initial commit

Author: ganigeorgiev

.gitignore

@@ -0,0 +1,19 @@
+/.vscode/
+.idea
+
+.DS_Store
+
+# tests coverage
+coverage.out
+
+# test data artifacts
+test/node_modules/
+test/output.json
+
+# plaintask todo files
+*.todo
+
+# generated markdown previews
+README.html
+CHANGELOG.html
+LICENSE.html

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 Guido Zuidhof
+Copyright (c) 2023-present Gani Georgiev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,73 @@
+(EXP) tygoja
+[![GoDoc](https://godoc.org/github.com/pocketbase/tygoja?status.svg)](https://pkg.go.dev/github.com/pocketbase/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](https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html) (aka. `.d.ts`) for [goja](https://github.com/dop251/goja) bindings.
+
+> **⚠️ Don't use it directly in production! It is not versioned and may change without notice.**
+>
+> **It was created to semi-automate the documentation of the goja integration for PocketBase.**
+>
+> **Use it only as a learning reference or as a non-critical step in your dev pipeline.**
+
+**tygoja** is a heavily modified fork of [tygo](https://github.com/gzuidhof/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](https://pkg.go.dev/github.com/dop251/goja#hdr-Nil) 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...
+
+
+## Known issues and limitations
+
+- Multiple versions of the same package may have unexpected declaration as 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
+
+## Example
+
+```go
+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;`,
+        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](https://typedoc.org/) to create HTML/JSON docs from the generated declaration(s).
+
+See the package `/test` directory for example output.

config.go

@@ -0,0 +1,82 @@
+package tygoja
+
+const (
+	defaultIndent = "  "
+
+	// custom base types that every package has access to
+	BaseTypeDict = "_TygojaDict" // Record type alternative as a more generic map-like type
+	BaseTypeAny  = "_TygojaAny"  // any type alias to allow easier extends generation
+)
+
+// FieldNameFormatterFunc defines a function for formatting a field name.
+type FieldNameFormatterFunc func(string) string
+
+// MethodNameFormatterFunc defines a function for formatting a method name.
+type MethodNameFormatterFunc func(string) string
+
+type Config struct {
+	// Packages is a list of package paths just like you would import them in Go.
+	// Use "*" to generate all package types.
+	//
+	// Example:
+	//
+	// 	Packages: map[string][]string{
+	// 		"time": {"Time"},
+	// 		"github.com/pocketbase/pocketbase/core": {"*"},
+	// 	}
+	Packages map[string][]string
+
+	// Heading specifies a content that will be put at the top of the output declaration file.
+	//
+	// You would generally use this to import custom types or some custom TS declarations.
+	Heading string
+
+	// TypeMappings specifies custom type translations.
+	//
+	// Useful for for mapping 3rd party package types, eg "unsafe.Pointer" => "CustomType".
+	//
+	// Be default unrecognized types will be recursively generated by
+	// traversing their import package (when possible).
+	TypeMappings map[string]string
+
+	// WithConstants indicates whether to generate types for constants
+	// ("false" by default).
+	WithConstants bool
+
+	// WithPackageFunctions indicates whether to generate types
+	// for package level functions ("false" by default).
+	WithPackageFunctions bool
+
+	// FieldNameFormatter allows specifying a custom struct field name formatter.
+	FieldNameFormatter FieldNameFormatterFunc
+
+	// MethodNameFormatter allows specifying a custom method name formatter.
+	MethodNameFormatter MethodNameFormatterFunc
+
+	// StartModifier usually should be "export" or declare but as of now prevents
+	// the LSP autocompletion so we keep it empty.
+	//
+	// See also:
+	// https://github.com/microsoft/TypeScript/issues/54330
+	// https://github.com/microsoft/TypeScript/pull/49644
+	StartModifier string
+
+	// Indent allow customizing the default indentation (use \t if you want tabs).
+	Indent string
+}
+
+// Initializes the defaults (if not already) of the current config.
+func (c *Config) InitDefaults() {
+	if c.Indent == "" {
+		c.Indent = defaultIndent
+	}
+
+	if c.TypeMappings == nil {
+		c.TypeMappings = make(map[string]string)
+	}
+
+	// special case for the unsafe package because it doesn't return its types in pkg.Syntax
+	if _, ok := c.TypeMappings["unsafe.Pointer"]; !ok {
+		c.TypeMappings["unsafe.Pointer"] = "number"
+	}
+}

go.mod

@@ -0,0 +1,10 @@
+module github.com/pocketbase/tygoja
+
+go 1.18
+
+require golang.org/x/tools v0.10.0
+
+require (
+	golang.org/x/mod v0.11.0 // indirect
+	golang.org/x/sys v0.9.0 // indirect
+)

go.sum

@@ -0,0 +1,7 @@
+golang.org/x/mod v0.11.0 h1:bUO06HqtnRcc/7l71XBe4WcqTZ+3AH1J59zWDDwLKgU=
+golang.org/x/mod v0.11.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
+golang.org/x/sync v0.3.0 h1:ftCYgMx6zT/asHUrPw8BLLscYtGznsLAnjq5RH9P66E=
+golang.org/x/sys v0.9.0 h1:KS/R3tvhPqvJvwcKfnBHJwwthS11LRhmM5D59eEXa0s=
+golang.org/x/sys v0.9.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/tools v0.10.0 h1:tvDr/iQoUqNdohiYm0LmmKcBk+q86lb9EprIUFhHHGg=
+golang.org/x/tools v0.10.0/go.mod h1:UJwyiVBsOA2uwvK/e5OY3GTpDUJriEd+/YlqAwLPmyM=

iota.go

@@ -0,0 +1,38 @@
+package tygoja
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+func isProbablyIotaType(groupType string) bool {
+	groupType = strings.Trim(groupType, "()")
+	return groupType == "iota" || strings.HasPrefix(groupType, "iota +") || strings.HasSuffix(groupType, "+ iota")
+}
+
+func basicIotaOffsetValueParse(groupType string) (int, error) {
+	if !isProbablyIotaType(groupType) {
+		panic("can't parse non-iota type")
+	}
+
+	groupType = strings.Trim(groupType, "()")
+	if groupType == "iota" {
+		return 0, nil
+	}
+	parts := strings.Split(groupType, " + ")
+
+	var numPart string
+	if parts[0] == "iota" {
+		numPart = parts[1]
+	} else {
+		numPart = parts[0]
+	}
+
+	addValue, err := strconv.ParseInt(numPart, 10, 64)
+	if err != nil {
+		return 0, fmt.Errorf("Failed to guesstimate initial iota value for \"%s\": %w", groupType, err)
+	}
+
+	return int(addValue), nil
+}

package_generator.go

@@ -0,0 +1,99 @@
+package tygoja
+
+import (
+	"go/ast"
+	"go/token"
+	"strings"
+
+	"golang.org/x/tools/go/packages"
+)
+
+// PackageGenerator is responsible for generating the code for a single input package.
+type PackageGenerator struct {
+	conf  *Config
+	pkg   *packages.Package
+	types []string
+
+	generatedTypes map[string]struct{}
+	unknownTypes   map[string]struct{}
+	imports        map[string][]string // path -> []names/aliases
+}
+
+// Generate generates the typings for a single package.
+func (g *PackageGenerator) Generate() (string, error) {
+	s := new(strings.Builder)
+
+	namespace := packageNameFromPath(g.pkg.ID)
+
+	s.WriteString("\n")
+	for _, f := range g.pkg.Syntax {
+		if f.Doc == nil || len(f.Doc.List) == 0 {
+			continue
+		}
+		g.writeCommentGroup(s, f.Doc, 0)
+	}
+	g.writeStartModifier(s, 0)
+	s.WriteString("namespace ")
+	s.WriteString(namespace)
+	s.WriteString(" {\n")
+
+	// register the aliased imports within the package namespace
+	// (see https://www.typescriptlang.org/docs/handbook/namespaces.html#aliases)
+	loadedAliases := map[string]struct{}{}
+	for _, file := range g.pkg.Syntax {
+		for _, imp := range file.Imports {
+			path := strings.Trim(imp.Path.Value, `"' `)
+
+			pgkName := packageNameFromPath(path)
+			alias := pgkName
+
+			if imp.Name != nil && imp.Name.Name != "" && imp.Name.Name != "_" {
+				alias = imp.Name.Name
+
+				if _, ok := loadedAliases[alias]; ok {
+					continue // already registered
+				}
+
+				loadedAliases[alias] = struct{}{}
+
+				g.writeIndent(s, 1)
+				s.WriteString("// @ts-ignore\n")
+				g.writeIndent(s, 1)
+				s.WriteString("import ")
+				s.WriteString(alias)
+				s.WriteString(" = ")
+				s.WriteString(pgkName)
+				s.WriteString("\n")
+			}
+
+			// register the import to export its package later
+			if !exists(g.imports[path], alias) {
+				if g.imports[path] == nil {
+					g.imports[path] = []string{}
+				}
+				g.imports[path] = append(g.imports[path], alias)
+			}
+		}
+
+		ast.Inspect(file, func(n ast.Node) bool {
+			switch x := n.(type) {
+			case *ast.FuncDecl: // FuncDecl can be package level function or struct method
+				g.writeFuncDecl(s, x, 1)
+				return false
+			case *ast.GenDecl: // GenDecl can be an import, type, var, or const expression
+				if x.Tok == token.VAR || x.Tok == token.IMPORT {
+					return false // ignore variables and import statements for now
+				}
+
+				g.writeGroupDecl(s, x, 1)
+				return false
+			}
+
+			return true
+		})
+	}
+
+	s.WriteString("}\n")
+
+	return s.String(), nil
+}

random.go

@@ -0,0 +1,31 @@
+package tygoja
+
+import (
+	mathRand "math/rand"
+	"time"
+)
+
+const defaultRandomAlphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+func init() {
+	mathRand.Seed(time.Now().UnixNano())
+}
+
+// PseudorandomString generates a pseudorandom string from the default
+// alphabet with the specified length.
+func PseudorandomString(length int) string {
+	return PseudorandomStringWithAlphabet(length, defaultRandomAlphabet)
+}
+
+// PseudorandomStringWithAlphabet generates a pseudorandom string
+// with the specified length and characters set.
+func PseudorandomStringWithAlphabet(length int, alphabet string) string {
+	b := make([]byte, length)
+	max := len(alphabet)
+
+	for i := range b {
+		b[i] = alphabet[mathRand.Intn(max)]
+	}
+
+	return string(b)
+}