Description: Documentation for Documentation

## Documentation

# (EXP) tygoja

tygoja is a small helper library for generating TypeScript declarations from Go code.

The generated typings are intended to be used as import helpers to provide ambient TypeScript declarations (aka. `.d.ts`) for goja bindings.

> ⚠️ Don't use it directly in production! It is not tagged and may change without notice.

> It was created to semi-automate the documentation of the goja integration for PocketBase.

> Use it only as a reference or as a non-critical step in your dev pipeline.

tygoja is a heavily modified fork of tygo and extends its scope with:

- custom field and method names formatters
- types for interfaces (exported and unexported)
- types for exported interface methods
- types for exported struct methods
- types for exported package level functions (must enable `PackageConfig.WithPackageFunctions`)
- inheritance declarations for embeded structs (embedded pointers are treated as values)
- autoloading all unmapped argument and return types (when possible)
- applying the same goja's rules when resolving the return types of exported function and methods
- combining multiple packages typings in a single output
- generating all declarations in namespaces with the packages name (both unmapped and mapped)
- preserving comment block new lines
- converting Go comment code blocks to Markdown code blocks
- and others...

Note that by default the generated typings are not generated with `export` since the intended usage is to map them to your custom goja bindings. This mapping could be defined in the `Config.Heading` field usually with the `declare` keyword (eg. `declare let someGojaProp: app.Cache`).

## Example

    package main

    import (
        "log"
        "os"

        "github.com/pocketbase/tygoja"
    )

    func main() {
        gen := tygoja.New(tygoja.Config{
            Packages: map[string][]string{
                "github.com/pocketbase/tygoja/test/a": {"*"},
                "github.com/pocketbase/tygoja/test/b": {"*"},
                "github.com/pocketbase/tygoja/test/c": {"Example2", "Handler"},
            },
            Heading:              `declare var $app: c.Handler; // bind other fields `,
            WithPackageFunctions: true,
        })

        result, err := gen.Generate()
        if err != nil {
            log.Fatal(err)
        }

        if err := os.WriteFile("./types.d.ts", []byte(result), 0644); err != nil {
            log.Fatal(err)
        }
    }

You can also combine it with typedoc to create HTML/JSON docs from the generated declaration(s).

See the package `/test` directory for example output.

For a more detailed example you can also explore the PocketBase's jsvm plugin.

## Known issues and limitations

- Multiple versions of the same package may have unexpected declaration since all versions will be under the same namespace.
- For easier generation, it relies on TypeScript declarations merging, meaning that the generated types may not be very compact.
- Package level functions and constants, that are reserved JS identifier, are prefixed with underscore (eg. `_in()`).

Generated using TypeDoc