(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)
    }
}
Copy

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()).