goscript 0.0.11 → 0.0.14

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2019-2024 Christian Stewart
+Copyright (c) 2024-2025 Aperture Robotics, LLC.
+Copyright (c) 2019-2025 Christian Stewart
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,10 +2,10 @@
 
 [![GoDoc Widget]][GoDoc] [![Go Report Card Widget]][Go Report Card]
 
-[GoDoc]: https://godoc.org/github.com/paralin/goscript
-[GoDoc Widget]: https://godoc.org/github.com/paralin/goscript?status.svg
-[Go Report Card Widget]: https://goreportcard.com/badge/github.com/paralin/goscript
-[Go Report Card]: https://goreportcard.com/report/github.com/paralin/goscript
+[GoDoc]: https://godoc.org/github.com/aperturerobotics/goscript
+[GoDoc Widget]: https://godoc.org/github.com/aperturerobotics/goscript?status.svg
+[Go Report Card Widget]: https://goreportcard.com/badge/github.com/aperturerobotics/goscript
+[Go Report Card]: https://goreportcard.com/report/github.com/aperturerobotics/goscript
 
 ## Introduction
 
@@ -15,6 +15,10 @@ It works on translating Go to TypeScript on the AST level.
 
 For detailed information on the compiler's design, refer to the [design document](./design/DESIGN.md).
 
+> Right now goscript looks pretty cool if you problem is "I want this self-sufficient algorithm be available in Go and JS runtimes". gopherjs's ambition, however, has always been "any valid Go program can run in a browser". There is a lot that goes on in gopherjs that is necessary for supporting the standard library, which goes beyond cross-language translation.
+>
+> — [nevkontakte](https://gophers.slack.com/archives/C039C0R2T/p1745870396945719), developer of [GopherJS](https://github.com/gopherjs/gopherjs)
+
 GoScript intends to compile a subset of the Go language to TypeScript in a
 non-spec-compliant way. It is intended only for bringing over high-level logic
 from Go to TypeScript, so not all programs will work correctly:
@@ -63,7 +67,7 @@ import (
 	"context"
 	"log"
 
-	"github.com/paralin/goscript/compiler"
+	"github.com/aperturerobotics/goscript/compiler"
 	"github.com/sirupsen/logrus"
 )
 
@@ -306,7 +310,7 @@ func main() {
 Generated with `goscript compile .`:
 
 ```typescript
-import * as goscript from "@go/builtin"
+import * as goscript from "@goscript/builtin"
 
 class MyStruct {
   // MyInt is a public integer field, initialized to zero.
@@ -460,10 +464,10 @@ export async function main(): Promise<void> {
 
 Code is compiled with `GOARCH=js` and uses a 32-bit environment similar to wasm.
 
-All Go import paths are prefixed with `@go/` and can be imported in TypeScript:
+All Go import paths are prefixed with `@goscript/` and can be imported in TypeScript:
 
 ```typescript
-import { MyAsyncFunction, MyStruct } from '@go/github.com/myorg/mypackage';
+import { MyAsyncFunction, MyStruct } from '@goscript/github.com/myorg/mypackage';
 
 // Example of importing and using a compiled Go async function
 async function runGoCode() {
@@ -480,4 +484,4 @@ async function runGoCode() {
 
 ## License
 
-MIT
+MIT

package/builtin/builtin.go

@@ -0,0 +1,11 @@
+package builtin
+
+import (
+	_ "embed"
+)
+
+// BuiltinTs contains the contents of the builtin.ts file which provides
+// runtime support for GoScript compiled code.
+//
+//go:embed builtin.ts
+var BuiltinTs string

package/builtin/builtin.ts

@@ -90,6 +90,15 @@ export const stringToRunes = (str: string): number[] => {
   return Array.from(str).map((c) => c.codePointAt(0) || 0)
 }
 
+/**
+ * Converts an array of Unicode code points (runes) to a string.
+ * @param runes The input array of numbers representing Unicode code points.
+ * @returns The resulting string.
+ */
+export const runesToString = (runes: number[]): string => {
+  return String.fromCharCode(...runes);
+};
+
 /**
  * Gets a value from a map, with a default value if the key doesn't exist.
  * @param map The map to get from.
@@ -262,7 +271,7 @@ export function typeAssert<T>(
       }
       break
 
-    case TypeKind.Basic:
+    case TypeKind.Basic: {
       // For basic types, check if the value matches the expected JavaScript type
       // This is a simple check for common basic types
       const basicType = typeof value
@@ -274,6 +283,7 @@ export function typeAssert<T>(
         return { value: value as T, ok: true }
       }
       break
+    }
 
     case TypeKind.Pointer:
       // For pointers, check if value is not null or undefined

package/cmd/goscript/cmd_compile.go

@@ -2,17 +2,22 @@ package main
 
 import (
 	"context"
+	"slices"
 
 	"github.com/aperturerobotics/cli"
-	"github.com/paralin/goscript/compiler"
+	"github.com/aperturerobotics/goscript/compiler"
 	"github.com/pkg/errors"
 	"github.com/sirupsen/logrus"
+
+	// _ ensure we include the builtin package
+	_ "github.com/aperturerobotics/goscript/builtin"
 )
 
 var (
-	cliCompiler       *compiler.Compiler
-	cliCompilerConfig compiler.Config
-	cliCompilerPkg    cli.StringSlice
+	cliCompiler           *compiler.Compiler
+	cliCompilerConfig     compiler.Config
+	cliCompilerPkg        cli.StringSlice
+	cliCompilerBuildFlags cli.StringSlice
 )
 
 // CompileCommands are commands related to compiling code.
@@ -33,6 +38,7 @@ var CompileCommands = []*cli.Command{{
 			Name:        "package",
 			Usage:       "the package(s) to compile",
 			Aliases:     []string{"p", "packages"},
+			EnvVars:     []string{"GOSCRIPT_PACKAGES"},
 			Destination: &cliCompilerPkg,
 		},
 		&cli.StringFlag{
@@ -40,12 +46,21 @@ var CompileCommands = []*cli.Command{{
 			Usage:       "the output typescript path to use",
 			Destination: &cliCompilerConfig.OutputPathRoot,
 			Value:       "./output",
+			EnvVars:     []string{"GOSCRIPT_OUTPUT"},
 		},
 		&cli.StringFlag{
 			Name:        "dir",
 			Usage:       "the working directory to use for the compiler (default: current directory)",
 			Destination: &cliCompilerConfig.Dir,
 			Value:       "",
+			EnvVars:     []string{"GOSCRIPT_DIR"},
+		},
+		&cli.StringSliceFlag{
+			Name:        "build-flags",
+			Aliases:     []string{"b", "buildflags", "build-flag", "buildflag"},
+			Usage:       "Go build flags (tags) to use during analysis",
+			Destination: &cliCompilerBuildFlags,
+			EnvVars:     []string{"GOSCRIPT_BUILD_FLAGS"},
 		},
 	},
 }}
@@ -57,5 +72,8 @@ func compilePackage(c *cli.Context) error {
 		return errors.New("package(s) must be specified")
 	}
 
+	// build flags
+	cliCompilerConfig.BuildFlags = slices.Clone(cliCompilerBuildFlags.Value())
+
 	return cliCompiler.CompilePackages(context.Background(), pkgs...)
 }

package/compiler/compile.go

@@ -4,9 +4,9 @@ import (
 	"fmt"
 	"go/ast"
 	"go/token"
-	"go/types"
+	gtypes "go/types"
 
-	gstypes "github.com/paralin/goscript/compiler/types"
+	gstypes "github.com/aperturerobotics/goscript/compiler/types"
 	"golang.org/x/tools/go/packages"
 )
 
@@ -19,14 +19,12 @@ type GoToTSCompiler struct {
 	asyncFuncs          map[string]bool // Track which functions are async
 	nextBlockNeedsDefer bool            // Track if the next block should have a "using" statement
 	inAsyncFunction     bool            // Track if we're inside an async function
-
-	tempVarCounter int // Counter for generating unique temporary variable names
 }
 
 // WriteGoType writes a Go type as a TypeScript type.
-func (c *GoToTSCompiler) WriteGoType(typ types.Type) {
+func (c *GoToTSCompiler) WriteGoType(typ gtypes.Type) {
 	switch t := typ.(type) {
-	case *types.Basic:
+	case *gtypes.Basic:
 		// Handle basic types (int, string, etc.)
 		name := t.Name()
 		if tsType, ok := gstypes.GoBuiltinToTypescript(name); ok {
@@ -34,31 +32,31 @@ func (c *GoToTSCompiler) WriteGoType(typ types.Type) {
 		} else {
 			c.tsw.WriteLiterally(name)
 		}
-	case *types.Named:
+	case *gtypes.Named:
 		// Handle named types (custom types)
 		c.tsw.WriteLiterally(t.Obj().Name())
-	case *types.Pointer:
+	case *gtypes.Pointer:
 		// Handle pointer types (*T becomes T | null)
 		c.WriteGoType(t.Elem())
 		c.tsw.WriteLiterally(" | null")
-	case *types.Slice, *types.Array:
+	case *gtypes.Slice, *gtypes.Array:
 		// Handle array/slice types ([]T or [N]T becomes T[])
-		var elemType types.Type
-		if slice, ok := t.(*types.Slice); ok {
+		var elemType gtypes.Type
+		if slice, ok := t.(*gtypes.Slice); ok {
 			elemType = slice.Elem()
-		} else if array, ok := t.(*types.Array); ok {
+		} else if array, ok := t.(*gtypes.Array); ok {
 			elemType = array.Elem()
 		}
 		c.WriteGoType(elemType)
 		c.tsw.WriteLiterally("[]")
-	case *types.Map:
+	case *gtypes.Map:
 		// Handle map types (map[K]V becomes Map<K, V>)
 		c.tsw.WriteLiterally("Map<")
 		c.WriteGoType(t.Key())
 		c.tsw.WriteLiterally(", ")
 		c.WriteGoType(t.Elem())
 		c.tsw.WriteLiterally(">")
-	case *types.Chan:
+	case *gtypes.Chan:
 		// Handle channel types (chan T becomes goscript.Channel<T>)
 		c.tsw.WriteLiterally("goscript.Channel<")
 		c.WriteGoType(t.Elem())
@@ -93,16 +91,9 @@ func NewGoToTSCompiler(tsw *TSCodeWriter, pkg *packages.Package, cmap ast.Commen
 		asyncFuncs:          make(map[string]bool),
 		nextBlockNeedsDefer: false,
 		inAsyncFunction:     false,
-		tempVarCounter:      0, // Initialize counter
 	}
 }
 
-// newTempVar generates a unique temporary variable name.
-func (c *GoToTSCompiler) newTempVar() string {
-	c.tempVarCounter++
-	return fmt.Sprintf("_tempVar%d", c.tempVarCounter)
-}
-
 // isAsyncFunc determines if a function is asynchronous
 // A function is async if it contains channel operations or calls other async functions
 func (c *GoToTSCompiler) isAsyncFunc(name string) bool {
@@ -145,7 +136,7 @@ func (c *GoToTSCompiler) containsAsyncOperations(node ast.Node) bool {
 // Handles array types recursively.
 func (c *GoToTSCompiler) WriteZeroValueForType(typ any) {
 	switch t := typ.(type) {
-	case *types.Array:
+	case *gtypes.Array:
 		c.tsw.WriteLiterally("[")
 		for i := 0; i < int(t.Len()); i++ {
 			if i > 0 {
@@ -170,11 +161,11 @@ func (c *GoToTSCompiler) WriteZeroValueForType(typ any) {
 			c.WriteZeroValueForType(t.Elt)
 		}
 		c.tsw.WriteLiterally("]")
-	case *types.Basic:
+	case *gtypes.Basic:
 		switch t.Kind() {
-		case types.Bool:
+		case gtypes.Bool:
 			c.tsw.WriteLiterally("false")
-		case types.String:
+		case gtypes.String:
 			c.tsw.WriteLiterally(`""`)
 		default:
 			c.tsw.WriteLiterally("0")

package/compiler/compile_expr.go

@@ -9,7 +9,7 @@ import (
 	"strconv"
 	"strings"
 
-	gstypes "github.com/paralin/goscript/compiler/types"
+	gstypes "github.com/aperturerobotics/goscript/compiler/types"
 )
 
 // WriteTypeExpr writes an expression that represents a type.
@@ -315,13 +315,14 @@ func (c *GoToTSCompiler) WriteInterfaceType(exp *ast.InterfaceType) {
 
 	// If there are embedded interfaces, write the extends clause
 	if len(embeddedInterfaces) > 0 {
-		c.tsw.WriteLiterally(" extends ")
+		c.tsw.WriteLiterally("extends ")
 		c.tsw.WriteLiterally(strings.Join(embeddedInterfaces, ", "))
+		c.tsw.WriteLiterally(" ")
 	}
 
 	// Write the interface body on the same line
-	c.tsw.WriteLiterally("{") // Removed leading space
-	c.tsw.WriteLine("")       // Newline after opening brace
+	c.tsw.WriteLiterally("{")
+	c.tsw.WriteLine("") // Newline after opening brace
 	c.tsw.Indent(1)
 
 	// Write named methods
@@ -377,6 +378,28 @@ func (c *GoToTSCompiler) WriteFuncType(exp *ast.FuncType, isAsync bool) {
 func (c *GoToTSCompiler) WriteCallExpr(exp *ast.CallExpr) error {
 	expFun := exp.Fun
 
+	// Handle array type conversions like []rune(string)
+	if arrayType, isArrayType := expFun.(*ast.ArrayType); isArrayType {
+		// Check if it's a []rune type
+		if ident, isIdent := arrayType.Elt.(*ast.Ident); isIdent && ident.Name == "rune" {
+			// Check if the argument is a string
+			if len(exp.Args) == 1 {
+				arg := exp.Args[0]
+				if tv, ok := c.pkg.TypesInfo.Types[arg]; ok && tv.Type != nil {
+					if basic, isBasic := tv.Type.Underlying().(*gtypes.Basic); isBasic && basic.Kind() == gtypes.String {
+						// Translate []rune(stringValue) to goscript.stringToRunes(stringValue)
+						c.tsw.WriteLiterally("goscript.stringToRunes(")
+						if err := c.WriteValueExpr(arg); err != nil {
+							return fmt.Errorf("failed to write argument for []rune(string) conversion: %w", err)
+						}
+						c.tsw.WriteLiterally(")")
+						return nil // Handled []rune(string)
+					}
+				}
+			}
+		}
+	}
+
 	if funIdent, funIsIdent := expFun.(*ast.Ident); funIsIdent {
 		switch funIdent.String() {
 		case "println":
@@ -507,10 +530,18 @@ func (c *GoToTSCompiler) WriteCallExpr(exp *ast.CallExpr) error {
 			// Fallthrough for unhandled make calls (e.g., channels)
 			return errors.New("unhandled make call")
 		case "string":
-			// Handle string() conversion, specifically for rune to string
+			// Handle string() conversion
 			if len(exp.Args) == 1 {
-				// Check if the argument is a rune (int32) or a call to rune()
 				arg := exp.Args[0]
+
+				// Case 1: Argument is a string literal string("...")
+				if basicLit, isBasicLit := arg.(*ast.BasicLit); isBasicLit && basicLit.Kind == token.STRING {
+					// Translate string("...") to "..." (no-op)
+					c.WriteBasicLitValue(basicLit)
+					return nil // Handled string literal conversion
+				}
+
+				// Case 2: Argument is a rune (int32) or a call to rune()
 				innerCall, isCallExpr := arg.(*ast.CallExpr)
 
 				if isCallExpr {
@@ -540,6 +571,19 @@ func (c *GoToTSCompiler) WriteCallExpr(exp *ast.CallExpr) error {
 						c.tsw.WriteLiterally(")")
 						return nil // Handled string(int32)
 					}
+
+					// Case 3: Argument is a slice of runes string([]rune{...})
+					if sliceType, isSlice := tv.Type.Underlying().(*gtypes.Slice); isSlice {
+						if basic, isBasic := sliceType.Elem().Underlying().(*gtypes.Basic); isBasic && basic.Kind() == gtypes.Int32 {
+							// Translate string([]rune) to goscript.runesToString(...)
+							c.tsw.WriteLiterally("goscript.runesToString(")
+							if err := c.WriteValueExpr(arg); err != nil {
+								return fmt.Errorf("failed to write argument for string([]rune) conversion: %w", err)
+							}
+							c.tsw.WriteLiterally(")")
+							return nil // Handled string([]rune)
+						}
+					}
 				}
 			}
 			// Return error for other unhandled string conversions
@@ -667,6 +711,17 @@ func (c *GoToTSCompiler) WriteBinaryExprValue(exp *ast.BinaryExpr) error {
 		return nil
 	}
 
+	// Check if the operator is a bitwise operator
+	isBitwise := false
+	switch exp.Op {
+	case token.AND, token.OR, token.XOR, token.SHL, token.SHR, token.AND_NOT:
+		isBitwise = true
+	}
+
+	if isBitwise {
+		c.tsw.WriteLiterally("(") // Add opening parenthesis for bitwise operations
+	}
+
 	if err := c.WriteValueExpr(exp.X); err != nil {
 		return fmt.Errorf("failed to write binary expression left operand: %w", err)
 	}
@@ -682,6 +737,11 @@ func (c *GoToTSCompiler) WriteBinaryExprValue(exp *ast.BinaryExpr) error {
 	if err := c.WriteValueExpr(exp.Y); err != nil {
 		return fmt.Errorf("failed to write binary expression right operand: %w", err)
 	}
+
+	if isBitwise {
+		c.tsw.WriteLiterally(")") // Add closing parenthesis for bitwise operations
+	}
+
 	return nil
 }
 
@@ -742,6 +802,16 @@ func (c *GoToTSCompiler) WriteCompositeLitValue(exp *ast.CompositeLit) error {
 
 		// Handle array literals
 		if arrType, isArrayType := exp.Type.(*ast.ArrayType); isArrayType {
+			// Special case: empty slice literal
+			if len(exp.Elts) == 0 {
+				// Generate: ([] as ElementType[])
+				c.tsw.WriteLiterally("([] as ")
+				// Write the element type using the existing function
+				c.WriteTypeExpr(arrType.Elt)
+				c.tsw.WriteLiterally("[])") // Close the type assertion
+				return nil                  // Handled empty slice literal
+			}
+
 			c.tsw.WriteLiterally("[")
 			// Use type info to get array length and element type
 			var arrayLen int
@@ -829,7 +899,7 @@ func (c *GoToTSCompiler) WriteCompositeLitValue(exp *ast.CompositeLit) error {
 			// Typed literal, likely a struct: new Type({...})
 			c.tsw.WriteLiterally("new ")
 			c.WriteTypeExpr(exp.Type)
-			c.tsw.WriteLiterally("({ ")
+			c.tsw.WriteLiterally("({")
 			for i, elm := range exp.Elts {
 				if i != 0 {
 					c.tsw.WriteLiterally(", ")
@@ -838,7 +908,7 @@ func (c *GoToTSCompiler) WriteCompositeLitValue(exp *ast.CompositeLit) error {
 					return fmt.Errorf("failed to write struct literal field: %w", err)
 				}
 			}
-			c.tsw.WriteLiterally(" })")
+			c.tsw.WriteLiterally("})")
 			return nil
 		}
 	}
@@ -935,7 +1005,7 @@ func (c *GoToTSCompiler) WriteFuncLitValue(exp *ast.FuncLit) error {
 	}
 
 	c.tsw.WriteLiterally(" => ")
-	
+
 	// Save previous async state and set current state based on isAsync
 	previousAsyncState := c.inAsyncFunction
 	c.inAsyncFunction = isAsync
@@ -945,7 +1015,7 @@ func (c *GoToTSCompiler) WriteFuncLitValue(exp *ast.FuncLit) error {
 		c.inAsyncFunction = previousAsyncState // Restore state before returning error
 		return fmt.Errorf("failed to write function literal body: %w", err)
 	}
-	
+
 	// Restore previous async state
 	c.inAsyncFunction = previousAsyncState
 	return nil

package/compiler/compile_field.go

@@ -3,6 +3,7 @@ package compiler
 import (
 	"fmt"
 	"go/ast"
+	gtypes "go/types"
 )
 
 // WriteFieldList writes a field list.
@@ -50,6 +51,7 @@ func (c *GoToTSCompiler) WriteField(field *ast.Field, isArguments bool) {
 			c.WriteDoc(field.Comment)
 		}
 	}
+
 	for _, name := range field.Names {
 		isExported := name.IsExported()
 
@@ -68,14 +70,33 @@ func (c *GoToTSCompiler) WriteField(field *ast.Field, isArguments bool) {
 			c.tsw.WriteLiterally(name.Name)
 		}
 
+		// Check if field type is an interface
+		isInterface := false
+		if c.pkg != nil && c.pkg.TypesInfo != nil {
+			if tv, ok := c.pkg.TypesInfo.Types[field.Type]; ok && tv.Type != nil {
+				_, isInterface = tv.Type.Underlying().(*gtypes.Interface)
+			}
+		}
+
 		// write type for struct fields (not arguments)
 		c.tsw.WriteLiterally(": ")
 		c.WriteTypeExpr(field.Type) // Use WriteTypeExpr for field type
 
+		// Append "| null" for interface fields
+		if !isArguments && isInterface {
+			c.tsw.WriteLiterally(" | null")
+		}
+
 		if !isArguments {
 			// write initializer with zero value for struct fields
 			c.tsw.WriteLiterally(" = ")
-			c.WriteZeroValueForType(field.Type)
+
+			// Special initialization for interface fields
+			if isInterface {
+				c.tsw.WriteLiterally("null")
+			} else {
+				c.WriteZeroValueForType(field.Type)
+			}
 
 			// write tag comment if any for struct fields
 			if field.Tag != nil {

package/compiler/compile_spec.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"go/ast"
 	"go/types"
+	gtypes "go/types"
 	"sort"
 	"strings"
 )
@@ -147,15 +148,19 @@ func (c *GoToTSCompiler) WriteTypeSpec(a *ast.TypeSpec) error {
 		if err := c.WriteValueExpr(a.Name); err != nil { // Class name is a value identifier
 			return err
 		}
+		c.tsw.WriteLiterally(" ")
+
 		if embeddedExpr != nil {
 			// For pointer embedding (*T) unwrap the star so we extend T, not (T|null)
 			if star, ok := embeddedExpr.(*ast.StarExpr); ok {
 				embeddedExpr = star.X
 			}
-			c.tsw.WriteLiterally(" extends ")
+			c.tsw.WriteLiterally("extends ")
 			c.WriteTypeExpr(embeddedExpr) // Embedded type name
+			c.tsw.WriteLiterally(" ")
 		}
-		c.tsw.WriteLine(" {")
+
+		c.tsw.WriteLine("{")
 		c.tsw.Indent(1)
 
 		// className is the name of the class type
@@ -282,15 +287,15 @@ func (c *GoToTSCompiler) WriteFuncDeclAsMethod(decl *ast.FuncDecl) error {
 
 	// Determine if method is async by checking for async operations in the body
 	isAsync := c.containsAsyncOperations(decl.Body)
-	
+
 	// Methods are typically public in the TS output
 	c.tsw.WriteLiterally("public ")
-	
+
 	// Add async modifier if needed
 	if isAsync {
 		c.tsw.WriteLiterally("async ")
 	}
-	
+
 	// Keep original Go casing for method names
 	if err := c.WriteValueExpr(decl.Name); err != nil { // Method name is a value identifier
 		return err
@@ -342,7 +347,7 @@ func (c *GoToTSCompiler) WriteFuncDeclAsMethod(decl *ast.FuncDecl) error {
 
 	// Check if function body has defer statements
 	c.nextBlockNeedsDefer = c.scanForDefer(decl.Body)
-	
+
 	// Save previous async state and set current state based on isAsync
 	previousAsyncState := c.inAsyncFunction
 	c.inAsyncFunction = isAsync
@@ -374,7 +379,7 @@ func (c *GoToTSCompiler) WriteFuncDeclAsMethod(decl *ast.FuncDecl) error {
 			}
 			c.tsw.Indent(-1)
 			c.tsw.WriteLine("}")
-			
+
 			// Restore previous async state
 			c.inAsyncFunction = previousAsyncState
 			return nil
@@ -385,7 +390,7 @@ func (c *GoToTSCompiler) WriteFuncDeclAsMethod(decl *ast.FuncDecl) error {
 		c.inAsyncFunction = previousAsyncState // Restore state before returning error
 		return fmt.Errorf("failed to write function body: %w", err)
 	}
-	
+
 	// Restore previous async state
 	c.inAsyncFunction = previousAsyncState
 	return nil
@@ -403,13 +408,30 @@ func (c *GoToTSCompiler) WriteValueSpec(a *ast.ValueSpec) error {
 	if len(a.Names) == 1 {
 		name := a.Names[0]
 		c.tsw.WriteLiterally(name.Name)
+
+		// Check if it's an interface type
+		isInterface := false
+		if c.pkg != nil && c.pkg.TypesInfo != nil && a.Type != nil {
+			if tv, ok := c.pkg.TypesInfo.Types[a.Type]; ok && tv.Type != nil {
+				_, isInterface = tv.Type.Underlying().(*gtypes.Interface)
+			}
+		}
+
 		if a.Type != nil {
 			c.tsw.WriteLiterally(": ")
 			c.WriteTypeExpr(a.Type) // Variable type annotation
 
+			// Append "| null" for interface types
+			if isInterface {
+				c.tsw.WriteLiterally(" | null")
+			}
+
 			// Check if it's an array type declaration without an initial value
 			if _, isArrayType := a.Type.(*ast.ArrayType); isArrayType && len(a.Values) == 0 {
 				c.tsw.WriteLiterally(" = []")
+			} else if isInterface && len(a.Values) == 0 {
+				// Interface with no initialization value, initialize to null
+				c.tsw.WriteLiterally(" = null")
 			}
 		}
 		if len(a.Values) > 0 {
@@ -473,6 +495,14 @@ func (c *GoToTSCompiler) WriteImportSpec(a *ast.ImportSpec) {
 
 // WriteInterfaceMethodSignature writes a TypeScript interface method signature from a Go ast.Field.
 func (c *GoToTSCompiler) WriteInterfaceMethodSignature(field *ast.Field) error {
+	// Include comments
+	if field.Doc != nil {
+		c.WriteDoc(field.Doc)
+	}
+	if field.Comment != nil {
+		c.WriteDoc(field.Comment)
+	}
+
 	if len(field.Names) == 0 {
 		// Should not happen for named methods in an interface, but handle defensively
 		return fmt.Errorf("interface method field has no name")