go-fAST

https://github.com/t14raptor/go-fast
Admin
go-fAST is a super-fast Golang library designed for parsing, transforming, and generating JavaScript...
Tokens:51,065
Snippets:326
Trust Score:8.1
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Writing a transformer with NoopVisitor

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-visitor.md

Complete example of writing a transformer using NoopVisitor. It defines a renameOne visitor that renames the first identifier matching 'old' and sets V to self for recursive descent. The main function parses a simple program and visits it, demonstrating the required setup.

```go
package main

import (
	"github.com/t14raptor/go-fast/ast"
	"github.com/t14raptor/go-fast/parser"
)

// renameOne renames the first identifier named "old" in the tree.
type renameOne struct {
	ast.NoopVisitor
	old, new string
	done     bool
}

func (r *renameOne) VisitIdentifier(n *ast.Identifier) {
	if r.done {
		return
	}
	if n.Name == r.old {
		n.Name = r.new
		r.done = true
	}
	// Do NOT call n.VisitChildrenWith: identifiers are leaves anyway.
}

func main() {
	program, _ := parser.Parse(`let old = old + 1;`)
	// 1. unpack the top-level statement? No — use a small driver visitor:
	r := &renameOne{old: "old", new: "renamed"}
	r.V = r                    // NoopVisitor forwards children to r.V — set it to self
	program.VisitWith(r)       // traversal starts at Program
	_ = program
}
```

--------------------------------

### Example: using Source rune and byte access

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Shows how to create a Source from a string, peek and consume a rune, then read the next byte. The example demonstrates that NextByte returns the first byte of the multi-byte UTF-8 sequence for 'é' (0xC3).

```go
src := scanner.NewSource(`héllo`)
r, _ := src.PeekRune() // 'h'
src.NextRune()
b, _ := src.NextByte() // 0xC3 (first byte of é)
_ = r
_ = b
```

--------------------------------

### Example: copy a function body before rewriting

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-clone.md

Example showing how to clone a function body before rewriting. It parses a function, clones it, mutates the clone, and generates both the original and the clone to show the difference.

```go
import (
	"github.com/t14raptor/go-fast/ast"
	"github.com/t14raptor/go-fast/generator"
	"github.com/t14raptor/go-fast/parser"
)

func main() {
	program, _ := parser.Parse(`function f() { return 1; }`)
	fn := program.Body[0].MustFuncDecl().Function

	// Clone the whole function so we can mutate the copy freely.
	clone := fn.Clone()

	// Mutate the clone (pointer, so it changes in place).
	clone.Body.List[0].MustReturn().Argument = nil // return;

	// Generate the original (unchanged) and the clone side-by-side.
	println(generator.GenerateMinified(fn))
	println(generator.GenerateMinified(clone))
	_ = ast.Program{}
}
```

--------------------------------

### Using Idx with parser.Parse

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Shows how to obtain the start and end indices of a statement using `Idx0()` and `Idx1()`, and how to convert an index to line/column with `ast.LineColumn`.

```go
program, _ := parser.Parse(`x + 1`)
stmt := program.Body[0]
start := stmt.Idx0() // ast.Idx = 1 + byte offset of 'x'
end := stmt.Idx1()
line, col, _ := ast.LineColumn(src, start)
```

--------------------------------

### ExpressionFromPattern usage example

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Example usage of ExpressionFromPattern, converting a function parameter's target pattern into an Expression.

```go
// Given a function parameter that is a simple identifier:
param := fn.ParameterList.List[0].Target // *ast.Pattern
expr := ast.ExpressionFromPattern(param)  // ast.Expression wrapping the Identifier
```

--------------------------------

### Example: parsing and accessing an identifier

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Parses a simple expression and extracts the property name and its source position from an Identifier node.

```go
program, _ := parser.Parse(`foo.bar`)
stmt := program.Body[0].MustExpression()
member := stmt.Expression.MustMember()
prop := member.Property.MustIdentifier()
println("property:", prop.Name, "at", prop.Idx)
```

--------------------------------

### Example: minified / pretty / custom rendering

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/generator.md

Shows how to parse a program and render it with Generate, GenerateMinified, and GenerateWithOptions. The pretty output uses tabs and newlines and keeps comments; minified output is one line and drops comments.

```go
import (
	"github.com/t14raptor/go-fast/generator"
	"github.com/t14raptor/go-fast/parser"
)

func main() {
	program, err := parser.Parse(`
		function add(a, b) {
			// sum
			return a + b;
		}
		console.log(add(1, 2));
	`)
	if err != nil {
		panic(err)
	}

	pretty := generator.Generate(program)                       // tabs + newlines, comment kept
	minified := generator.GenerateMinified(program)             // one line, comment dropped
	custom := generator.GenerateWithOptions(program, generator.Options{Minified: true})

	println(pretty)
	println(minified)
	println(custom)
}
```

--------------------------------

### Resolve then inspect free references

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/resolver.md

Parses a program, resolves it, and uses a custom visitor to print identifiers that remain unresolved. The example shows how to access ScopeContext after resolution.

```go
import (
	"github.com/t14raptor/go-fast/ast"
	"github.com/t14raptor/go-fast/parser"
	"github.com/t14raptor/go-fast/resolver"
)

func main() {
	src := `var x = 1; function f() { var y = x + z; return y; }`
	program, err := parser.Parse(src)
	if err != nil {
		panic(err)
	}

	resolver.Resolve(program) // in-place: sets ScopeContext fields

	// After resolution: `x` appears as a reference inside f — its context is
	// TopLevelContext (declared at program scope); `z` stays UnresolvedContext.
	// (Print by visiting identifiers:)
	count := 0
	visitor := &identVisitor{program: program}
	visitor.V = visitor
	program.VisitWith(visitor)
	println("unresolved identifiers:", count)
	_ = ast.UnresolvedContext
}

type identVisitor struct {
	ast.NoopVisitor
	program *ast.Program
}

func (v *identVisitor) VisitIdentifier(n *ast.Identifier) {
	if n.ScopeContext == ast.UnresolvedContext {
		println("free:", n.Name)
	}
}
```

--------------------------------

### Manual scanning example using scanner.Next()

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Shows how to create a scanner with NewScanner, iterate over tokens using Next() until token.Eof, and print each token's kind and string representation. Errors are accumulated in the provided error pointer and checked after the loop.

```go
import (
	"github.com/t14raptor/go-fast/parser/scanner"
	"github.com/t14raptor/go-fast/parser/scanner/token"
)

func main() {
	var errs error
	s := scanner.NewScanner(`let x = 42;`, &errs)

	s.Next() // consume first token
	for s.Token.Kind != token.Eof {
		println(s.Token.Kind.String(), s.Token.String(s))
		s.Next()
	}
	if errs != nil {
		panic(errs) // accumulated scanner.Error values
	}
}
```

--------------------------------

### Example: render a single expression

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/generator.md

Shows how to parse a simple call expression and render just the callee or the entire statement. Uses MustExpression, MustCall, and Callee to drill into the AST.

```go
program, _ := parser.Parse(`foo(bar)`)

// Drill into the call expression and render just the callee:
callee := program.Body[0].MustExpression().Expression.MustCall().Callee
println(generator.Generate(callee)) // "foo"

// Or render any node generically:
println(generator.GenerateMinified(program.Body[0])) // "foo(bar);"
```

--------------------------------

### Example: inspecting identifier scope contexts after resolution

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Shows how to use resolver.Resolve to assign scope contexts and then iterate over program statements to inspect each identifier's ScopeContext, distinguishing free references, top-level bindings, and other scopes.

```go
resolver.Resolve(program)
for i := range program.Body {
	stmt := &program.Body[i]
	if stmt.IsExpression() {
		expr := stmt.MustExpression().Expression
		if id, ok := expr.Identifier(); ok {
			switch id.ScopeContext {
			case ast.UnresolvedContext:
				println(id.Name, "is a free reference")
			case ast.TopLevelContext:
				println(id.Name, "binds at top level")
			default:
				println(id.Name, "binds to scope", id.ScopeContext)
			}
		}
	}
}
```

--------------------------------

### ParseBytes usage example

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/parser.md

Example of calling ParseBytes with a byte slice containing JavaScript code. It returns a program and an error; the error is checked and the program is assigned to a blank identifier.

```go
program, err := parser.ParseBytes([]byte(`[1, 2, 3].map(x => x * 2)`))
if err != nil {
	panic(err)
}
_ = program
```

--------------------------------

### Example: extracting error position with LineColumn

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Shows how to use the Positioned interface and LineColumn to print the line and column of an error. It uses errors.As to extract the position and then calls LineColumn with the source text.

```go
var pos ast.Positioned
if errors.As(err, &pos) {
	start, _ := pos.Pos()
	line, col, _ := ast.LineColumn(src, start)
	fmt.Printf("error at %d:%d\n", line, col)
}
```

--------------------------------

### Basic use of parser.Parse

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/parser.md

Example showing how to parse a simple JavaScript string and print the number of top-level statements. The source string must remain valid for the lifetime of the returned AST because the parser keeps no-copy references.

```go
import (
	"fmt"

	"github.com/t14raptor/go-fast/parser"
)

func main() {
	program, err := parser.Parse(`const answer = 42;`)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%d top-level statement(s)\n", len(program.Body))
}
```

--------------------------------

### Error handling with position recovery

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/parser.md

Example demonstrating how to recover byte positions from parse errors using errors.As against ast.Positioned or *parser.Error. Shows that the program is returned even when err != nil and may be partially populated.

```go
import (
	"errors"
	"fmt"
	"strings"

	"github.com/t14raptor/go-fast/ast"
	"github.com/t14raptor/go-fast/parser"
)

func main() {
	src := "let x = ;"
	program, err := parser.Parse(src)

	// program is returned even when err != nil and may be partially populated.
	_ = program

	var pos ast.Positioned // implemented by both *parser.Error and scanner.Error
	if errors.As(err, &pos) {
		start, end := pos.Pos()
		line, col, offset := ast.LineColumn(src, start)
		fmt.Printf("%d:%d (%d): %v\n", line, col, offset, err)
	}
	// The same errors.As pattern works against *parser.Error directly:
	var perr *parser.Error
	if errors.As(err, &perr) {
		fmt.Println("message:", perr.Message, "range:", perr.Start, perr.End)
	}
	_ = strings.TrimSpace // avoid unused import noise
}
```

--------------------------------

### MatchKeyword function implementation

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/token.md

Returns the keyword token for the given literal, or Identifier if not found. Uses the internal keywordTable mapping 41 words. Example usage shows matching 'while' to token.While and 'foo' to token.Identifier.

```go
func MatchKeyword(literal string) Token {
	if k, exists := keywordTable[literal]; exists {
		return k.token
	}
	return Identifier
}
```

```go
import "github.com/t14raptor/go-fast/parser/scanner/token"

token.MatchKeyword("while") // token.While
token.MatchKeyword("foo")   // token.Identifier
```

--------------------------------

### MetaPropertyKind enum and String method

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-nodes.md

Defines the MetaPropertyKind enum with values for new.target and import.meta, and a String method. The iota starts at 0; the String method returns the textual representation.

```go
type MetaPropertyKind uint8
const (
	MetaPropertyNewTarget  MetaPropertyKind = iota // new.target
	MetaPropertyImportMeta                         // import.meta
)
func (k MetaPropertyKind) String() string
```

--------------------------------

### Node interface definition

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Defines the Node interface that all AST nodes implement, providing methods to get the start and end indices of the node's source range.

```go
type Node interface {
	// Idx0 returns the index of the first character belonging to the node.
	Idx0() Idx
	// Idx1 returns the index of the first character immediately after the node.
	Idx1() Idx
}
```

--------------------------------

### Resolution required before generating again

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/resolver.md

Shows that Resolve must be called before generating code again, using a self-referencing arrow function as an example.

```go
program, _ := parser.Parse(`const a = () => a;`) // self-reference via arrow
resolver.Resolve(program)                        // a binds to the const scope
_ = program
```

--------------------------------

### Kind enums: VarKind, MethodKind, MetaPropertyKind

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/types.md

Defines the kind enums used as discriminators for AST nodes. `VarKind` maps to "var"/"let"/"const"; `MethodKind` starts at 1 to leave zero unused; `MetaPropertyKind` maps to "new.target"/"import.meta". `MethodKind` has no String method.

```go
type VarKind uint8          // ast/decl.go:28
const (
	VarKindVar VarKind = iota // "var"
	VarKindLet                // "let"
	VarKindConst              // "const"
)

type MethodKind uint8       // ast/class.go:8
const (
	MethodKindMethod MethodKind = iota + 1 // zero value intentionally unused
	MethodKindGet
	MethodKindSet
)

type MetaPropertyKind uint8 // ast/expr.go:244
const (
	MetaPropertyNewTarget  MetaPropertyKind = iota // new.target
	MetaPropertyImportMeta                         // import.meta
)
```

--------------------------------

### Precedence constants (lowest to member)

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-operators.md

Defines the Precedence enum from PrecedenceLowest to PrecedenceMember. Relative ordering is meaningful; absolute values mirror esbuild's OpPrec, derived bottom-up from the ECMA grammar starting at the comma operator. Methods include IsRightAssociative() (** ?: =), IsLeftAssociative(), IsBitwise(), IsShift(), and IsAdditive().

```go
const (
	PrecedenceLowest Precedence = iota
	PrecedenceComma
	PrecedenceSpread
	PrecedenceYield
	PrecedenceAssign
	PrecedenceConditional
	PrecedenceNullishCoalescing
	PrecedenceLogicalOr
	PrecedenceLogicalAnd
	PrecedenceBitwiseOr
	PrecedenceBitwiseXor
	PrecedenceBitwiseAnd
	PrecedenceEquals
	PrecedenceCompare
	PrecedenceShift
	PrecedenceAdd
	PrecedenceMultiply
	PrecedenceExponentiation
	PrecedencePrefix
	PrecedencePostfix
	PrecedenceNew
	PrecedenceCall
	PrecedenceMember
)
```

--------------------------------

### Generate code with generator.Generate, GenerateMinified, and GenerateWithOptions

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/configuration.md

Shows how to generate code from a parsed program using the three generator entry points. `generator.Generate` produces pretty output, `generator.GenerateMinified` produces minified output, and `generator.GenerateWithOptions` with `Options{Minified: true}` is identical to `GenerateMinified`. The parser takes only source text and returns a program node.

```go
import (
	"github.com/t14raptor/go-fast/generator"
	"github.com/t14raptor/go-fast/parser"
)

func main() {
	program, _ := parser.Parse(`const hi = "world"; console.log(hi);`)

	a := generator.Generate(program)
	// const hi = "world";
	// console.log(hi);

	b := generator.GenerateMinified(program)
	// const hi="world";console.log(hi);

	c := generator.GenerateWithOptions(program, generator.Options{Minified: true})
	// identical to GenerateMinified
	_, _, _ = a, b, c
}

```

--------------------------------

### MethodKind enum in ast/class.go

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-nodes.md

Defines the MethodKind type with constants for method, get, and set. The zero value is intentionally unused.

```go
type MethodKind uint8
const (
	MethodKindMethod MethodKind = iota + 1 // zero value intentionally unused
	MethodKindGet
	MethodKindSet
)

```

--------------------------------

### Parsing and iterating over a Program

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Shows how to parse a script and iterate over its body to find function declarations, printing the function name.

```go
program, _ := parser.Parse(`
	function greet(name) { return "hi " + name; }
	greet("world");
`)
for i := range program.Body {
	stmt := &program.Body[i]
	if stmt.IsFuncDecl() {
		decl := stmt.MustFuncDecl()
		println("function:", decl.Function.Name.Name)
	}
}
```

--------------------------------

### Selected Clone() signatures

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-clone.md

Selected Clone() signatures verbatim from source, with file and line references.

```go
func (n *Expression) Clone() *Expression   // ast/clone.go:420
func (n *Statement) Clone() *Statement     // ast/clone.go:708
func (n *Program) Clone() *Program         // ast/clone.go:242
func (n *Statements) Clone() *Statements
func (n *Identifier) Clone() *Identifier   // ast/clone.go:152
func (n *VariableDeclaration) Clone() *VariableDeclaration // ast/clone.go:357
```

--------------------------------

### Define scanner.Error struct and methods

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Defines the Error struct with Message, Start, and End fields, along with the Error() and Pos() methods. The Pos() method implements the ast.Positioned interface.

```go
type Error struct {
	Message string
	Start   ast.Idx
	End     ast.Idx
}

func (d Error) Error() string // value receiver
func (d Error) Pos() (start, end ast.Idx) // implements ast.Positioned
```

--------------------------------

### Positioned interface definition

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Defines the Positioned interface that combines the error interface with a Pos() method returning the start and end indices of the source range. It is implemented by *parser.Error and scanner.Error.

```go
// Positioned is implemented by structured errors that carry a source
// range. Concrete error types in scanner and parser implement it so
// callers can pull positions without knowing which layer produced the
// error:
//
//	var p ast.Positioned
//	if errors.As(err, &p) {
//	    start, _ := p.Pos()
//	    line, col, _ := ast.LineColumn(src, start)
//	    // ...
//	}
type Positioned interface {
	error
	Pos() (start, end Idx)
}
```

--------------------------------

### Define ast.Visitor interface and NoopVisitor

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/types.md

Defines the central node-visitor contract. The interface lists all 96 Visit* methods (one per node type); NoopVisitor forwards every method to its embedded visitor so subclasses can override a subset.

```go
type Visitor interface { /* 96 Visit* methods, one per node type */ }
type NoopVisitor struct { V Visitor } // ast/visit.go:88 — every method forwards to children
```

--------------------------------

### Generator Options and GenVisitor implementation

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/types.md

Shows the generator configuration surface: Options with a single Minified boolean flag and GenVisitor that embeds ast.NoopVisitor and adds unexported buffer/options/precedence/context fields.

```go
type Options struct { // generator/generator.go:12
	Minified bool
}

type GenVisitor struct { // generator/generator.go:37 — ast.NoopVisitor + unexported buf/opts/prec/ctx
	ast.NoopVisitor
	// ...unexported fields...
}
```

--------------------------------

### AssignmentOperator enum constants

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-operators.md

Defines the AssignmentOperator enum constants with their source spellings. The zero value is AssignmentAssign (plain '='). Use String() to get the exact operator spelling, and the Is*/To* methods to classify operators.

```go
const (
	AssignmentAssign             AssignmentOperator = iota // =
	AssignmentAddition                                     // +=
	AssignmentSubtraction                                  // -=
	AssignmentMultiplication                               // *=
	AssignmentDivision                                     // /=
	AssignmentRemainder                                    // %=
	AssignmentExponential                                  // **=
	AssignmentShiftLeft                                    // <<=
	AssignmentShiftRight                                   // >>=
	AssignmentUnsignedShiftRight                           // >>>=
	AssignmentBitwiseOR                                    // |=
	AssignmentBitwiseXOR                                   // ^=
	AssignmentBitwiseAnd                                   // &=
	AssignmentLogicalOr                                    // ||=
	AssignmentLogicalAnd                                   // &&=
	AssignmentLogicalNullish                               // ??=
)
```

--------------------------------

### Usage pattern: count literals in AST

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-unions.md

Shows how to traverse AST nodes using Kind() and MustXxx accessors. Calling MustXxx on the wrong variant panics with "unexpected kind: <Kind().String()>"; guard with IsXxx()/Kind() or use the two-value Xxx() accessor.

```go
import "github.com/t14raptor/go-fast/ast"

func countLiterals(stmt ast.Statement) int {
	switch stmt.Kind() { // StmtKind
	case ast.StmtExpression:
		return countExpr(stmt.MustExpression().Expression)
	default:
		return 0
	}
}

func countExpr(expr *ast.Expression) int {
	switch expr.Kind() { // ExprKind
	case ast.ExprBinary:
		b := expr.MustBinary()
		return countExpr(b.Left) + countExpr(b.Right)
	case ast.ExprNumberLit, ast.ExprStringLit, ast.ExprBoolLit, ast.ExprNullLit:
		return 1
	default:
		// Any other kind: still recurse into children generically.
		count := 0
		expr.VisitChildrenWith(visitorCountingInto(&count))
		return count
	}
}
```

--------------------------------

### Type and value types in ast/ext (Type, Value, BoolValue, RemoveHelper)

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/types.md

Shows the value and type system in ast/ext: marker Type interface with seven concrete types, generic Value[T] with Known/Unknown helpers, TypeValue and BoolValue specializations, and RemoveHelper that inherits NoopVisitor and marks the current node.

```go
type Type interface { _type() } // ast/ext/value.go — marker interface

type UndefinedType struct{}
type NullType      struct{}
type BoolType      struct{}
type StringType    struct{}
type SymbolType    struct{}
type NumberType    struct{}
type ObjectType    struct{}

type Value[T any] struct { val T; unknown bool }       // Known[T](), Unknown[T](), Val(), Known(), Unknown()
type TypeValue struct { Value[Type] }                  // CastToNumberOnAdd() bool
type BoolValue struct { Value[bool] }                  // And, Or, Not — three-valued logic
type RemoveHelper struct { ast.NoopVisitor; remove bool } // Remove() marks current node
```

--------------------------------

### go:generate directives in ast/node.go

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

The go:generate directives that regenerate ast/clone.go, ast/visit.go, and ast/union.go from hand-written node declarations. These must be run from the repository root.

```go
//go:generate go run ast/gen_clone.go
//go:generate go run ast/gen_visit.go
//go:generate go run ast/gen_union.go
```

--------------------------------

### Define core ast package types: Idx, Node, VisitableNode, Positioned, ScopeContext

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/types.md

Defines the foundational types in the `ast` package: the `Idx` type as a compact source position, the `Node` and `VisitableNode` interfaces for traversing AST nodes, the `Positioned` interface for error types that report positions, and the `ScopeContext` enum with its constants. These types are used throughout the AST node implementations and by the generator and resolver APIs.

```go
type Idx uint32                       // ast/node.go:8 — compact source position (1 + byte offset)

type Node interface {                 // ast/node.go:10
	Idx0() Idx
	Idx1() Idx
}

type VisitableNode interface {        // ast/node.go:17
	VisitWith(v Visitor)
	VisitChildrenWith(v Visitor)
}

type Positioned interface {           // ast/position.go:14
	error
	Pos() (start, end Idx)
}

type ScopeContext int32               // ast/scope.go:10
const (
	UnresolvedContext ScopeContext = 0
	TopLevelContext   ScopeContext = 1
)
```

--------------------------------

### type Positioned interface

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Positioned is an interface implemented by structured errors that carry a source range. It embeds the error interface and adds a Pos method to retrieve the start and end byte offsets of the error's source range.

```APIDOC
## type Positioned interface

### Description
Positioned is implemented by structured errors that carry a source range. Concrete error types in scanner and parser implement it so callers can pull positions without knowing which layer produced the error.

### Interface Definition
```go
type Positioned interface {
	error
	Pos() (start, end Idx)
}
```

### Methods
- **Pos()** (start, end Idx) - Returns the start and end byte offsets of the error's source range.

### Implemented By
- `*parser.Error`
- `scanner.Error` (value receiver)

### Usage Example
```go
var p ast.Positioned
if errors.As(err, &p) {
    start, _ := p.Pos()
    line, col, _ := ast.LineColumn(src, start)
    // ...
}
```
```

--------------------------------

### Define Source struct and NewSource constructor

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Defines the Source struct with unexported fields and the NewSource constructor that creates a Source from a string. The source string must remain alive because the struct stores a pointer into it.

```go
type Source struct {
	base unsafe.Pointer
	pos  ast.Idx
	len  ast.Idx
}

func NewSource(src string) Source
```

--------------------------------

### Complete token constant block (token/token_const.go)

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/token.md

The full const block defining all token kinds, with iota starting at 0. The ordering is significant: the range Identifier through EscapedReservedWord is identifier territory, and tokens after EscapedReservedWord (Of, Let, Static, Async, Await, Yield) are unreserved-word tokens.

```go
const (
	Undetermined Token = iota

	Illegal
	Eof
	Comment

	String
	Number

	Plus      // +
	Minus     // -
	Multiply  // *
	Exponent  // **
	Slash     // /
	Remainder // %

	And                // &
	Or                 // |
	ExclusiveOr        // ^
	ShiftLeft          // <<
	ShiftRight         // >>
	UnsignedShiftRight // >>>

	AddAssign       // +=
	SubtractAssign  // -=
	MultiplyAssign  // *=
	ExponentAssign  // **=
	QuotientAssign  // /=
	RemainderAssign // %=

	AndAssign                // &=
	OrAssign                 // |=
	ExclusiveOrAssign        // ^=
	ShiftLeftAssign          // <<=
	ShiftRightAssign         // >>=
	UnsignedShiftRightAssign // >>>=

	LogicalAnd       // &&
	LogicalOr        // ||
	Coalesce         // ??
	LogicalAndAssign // &&=
	LogicalOrAssign  // ||=
	CoalesceAssign   // ??=
	Increment        // ++
	Decrement        // --

	Equal       // ==
	StrictEqual // ===
	Less        // <
	Greater     // >
	Assign      // =
	Not         // !

	BitwiseNot // ~

	NotEqual       // !=
	StrictNotEqual // !==
	LessOrEqual    // <=
	GreaterOrEqual // >=

	LeftParenthesis // (
	LeftBracket     // [
	LeftBrace       // {
	Comma           // ,
	Period          // .

	RightParenthesis // )
	RightBracket     // ]
	RightBrace       // }
	Semicolon        // ;
	Colon            // :
	QuestionMark     // ?
	QuestionDot      // ?.
	Arrow            // =>
	Ellipsis         // ...
	Backtick         // `

	PrivateIdentifier

	TemplateHead
	TemplateMiddle
	TemplateTail
	NoSubstitutionTemplate

	Identifier
	Keyword
	Boolean
	Null

	If
	In
	Do

	Var
	For
	New
	Try

	This
	Else
	Case
	Void
	With

	Const
	While
	Break
	Catch
	Throw
	Class
	Super

	Return
	Typeof
	Delete
	Switch

	Default
	Finally
	Extends

	Function
	Continue
	Debugger

	InstanceOf

	EscapedReservedWord

	Of
	Let
	Static
	Async
	Await
	Yield
)

```

--------------------------------

### ForInit and ForInto definitions

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-unions.md

Defines the ForInit and ForInto union types with their kind enums and unsafe pointers. ForInit variants include Expr and VarDecl, with constructors NewExprForInit and NewVarDeclForInit. ForInto variants include Pattern and VarDecl, with constructors NewPatternForInto and NewVarDeclForInto.

```go
type ForInit struct {
	kind ForInitKind
	ptr  unsafe.Pointer
}
type ForInitKind uint8 // ForInitNone, ForInitExpr, ForInitVarDecl

type ForInto struct {
	kind ForIntoKind
	ptr  unsafe.Pointer
}
type ForIntoKind uint8 // ForIntoNone, ForIntoPattern, ForIntoVarDecl
```

--------------------------------

### Scanner struct definition and NewScanner constructor

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Defines the Scanner struct with fields Token, EscapedStr, src, and errors, along with the NewScanner constructor that takes source text and an error pointer. The scanner holds a zero-copy reference to the source string, so the source must outlive scanning.

```go
type Scanner struct {
	Token Token

	src Source

	EscapedStr string // escape-processed string for current token

	errors *error
}

func NewScanner(src string, errors *error) Scanner
```

--------------------------------

### Statement union type definition

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-unions.md

Defines the Statement union type with a StmtKind enum and an unsafe pointer. Variants include Block, Break, ClassDecl, Continue, Debugger, DoWhile, Empty, Expression, For, ForIn, ForOf, FuncDecl, If, Labelled, Return, Switch, Throw, Try, VarDecl, While, With, and Bad. Accessor example: stmt.MustExpression() *ExpressionStatement; stmt.IsVarDecl() bool, stmt.VarDecl() (*VariableDeclaration, bool).

```go
type Statement struct {
	kind StmtKind
	ptr  unsafe.Pointer
}
type StmtKind uint8
```

--------------------------------

### NextRune() (rune, bool)

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Consumes and returns the next UTF-8 rune. Returns false if at EOF.

```APIDOC
## NextRune() (rune, bool)

### Description
Consumes and returns the next UTF-8 rune. Returns false if at EOF.

### Returns
- `rune` - The next rune.
- `bool` - True if a rune was read, false if EOF.
```

--------------------------------

### VisitableNode methods on nodes

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-visitor.md

Shows the two methods that every node struct, union wrapper, and slice type implements. VisitWith dispatches to the visitor's VisitXxx method, while VisitChildrenWith visits children, with union wrappers dispatching to their payload.

```go
func (n *T) VisitWith(v Visitor)         // v.VisitXxx(n) — dispatch to the visitor
func (n *T) VisitChildrenWith(v Visitor) // visit children (union wrappers dispatch to their payload)
```

--------------------------------

### GenerateWithOptions function signature

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/generator.md

Function signature for GenerateWithOptions, which renders a node as JavaScript source using the supplied options. Only the Minified option exists. Returns a string built with unsafe.String over an internal buffer; do not retain the buffer.

```go
// GenerateWithOptions renders node as JavaScript source using the supplied options.
func GenerateWithOptions(node ast.VisitableNode, opts Options) string
```

--------------------------------

### Access scanner.Error via errors.As

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Shows how to retrieve a scanner.Error from an accumulated error using errors.As, then print its fields.

```go
var serr scanner.Error
if errors.As(errs, &serr) {
	println(serr.Start, serr.End, serr.Message)
}
```

--------------------------------

### FromPositionToCurrent(pos ast.Idx) string

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Returns a slice of the source from the given position to the current offset.

```APIDOC
## FromPositionToCurrent(pos ast.Idx) string

### Description
Returns a slice of the source from the given position to the current offset.

### Parameters
- `pos` (ast.Idx) - Required - The starting position.

### Returns
- `string` - The substring from pos to current offset.
```

--------------------------------

### PeekRune() (rune, bool)

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Inspects the next UTF-8 rune without consuming it. Returns false if at EOF.

```APIDOC
## PeekRune() (rune, bool)

### Description
Inspects the next UTF-8 rune without consuming it. Returns false if at EOF.

### Returns
- `rune` - The next rune.
- `bool` - True if a rune is available, false if EOF.
```

--------------------------------

### Describe an ast.BinaryOperator

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-operators.md

Use this snippet to inspect an ast.BinaryOperator: it returns its string representation and appends " (arithmetic)" if the operator is arithmetic. Note that Precedence() has no String() method, so compare it with exported constants like ast.PrecedenceAdd.

```go
import "github.com/t14raptor/go-fast/ast"

func describe(op ast.BinaryOperator) string {
	s := op.String()
	if op.IsArithmetic() {
		// Precedence has no String(); compare with exported constants.
		_ = op.Precedence() == ast.PrecedenceAdd
		return s + " (arithmetic)"
	}
	return s
}
```

--------------------------------

### Visitor interface definition (ast/visit.go:83)

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-visitor.md

The generated Visitor interface with exactly 96 Visit* methods, one per node type. Implement this interface to traverse the AST; concrete Visit* methods receive concrete node types, so implementing VisitCallExpression matches every call expression anywhere in the tree.

```go
type Visitor interface {
	VisitArrayLiteral(n *ArrayLiteral)
	VisitArrayPattern(n *ArrayPattern)
	VisitArrowFunctionLiteral(n *ArrowFunctionLiteral)
	VisitAssignExpression(n *AssignExpression)
	VisitAssignmentPattern(n *AssignmentPattern)
	VisitAwaitExpression(n *AwaitExpression)
	VisitBadStatement(n *BadStatement)
	VisitBigIntLiteral(n *BigIntLiteral)
	VisitBinaryExpression(n *BinaryExpression)
	VisitBlockStatement(n *BlockStatement)
	VisitBooleanLiteral(n *BooleanLiteral)
	VisitBreakStatement(n *BreakStatement)
	VisitCallExpression(n *CallExpression)
	VisitCatchClause(n *CatchClause)
	VisitClassDeclaration(n *ClassDeclaration)
	VisitClassElement(n *ClassElement)
	VisitClassElements(n *ClassElements)
	VisitClassLiteral(n *ClassLiteral)
	VisitClassStaticBlock(n *ClassStaticBlock)
	VisitComputedProperty(n *ComputedProperty)
	VisitConciseBody(n *ConciseBody)
	VisitConditionalExpression(n *ConditionalExpression)
	VisitContinueStatement(n *ContinueStatement)
	VisitDebuggerStatement(n *DebuggerStatement)
	VisitDoWhileStatement(n *DoWhileStatement)
	VisitEmptyStatement(n *EmptyStatement)
	VisitExpression(n *Expression)
	VisitExpressionStatement(n *ExpressionStatement)
	VisitExpressions(n *Expressions)
	VisitFieldDefinition(n *FieldDefinition)
	VisitForInStatement(n *ForInStatement)
	VisitForInit(n *ForInit)
	VisitForInto(n *ForInto)
	VisitForOfStatement(n *ForOfStatement)
	VisitForStatement(n *ForStatement)
	VisitFunctionDeclaration(n *FunctionDeclaration)
	VisitFunctionLiteral(n *FunctionLiteral)
	VisitIdentifier(n *Identifier)
	VisitIfStatement(n *IfStatement)
	VisitInvalidExpression(n *InvalidExpression)
	VisitLabelledStatement(n *LabelledStatement)
	VisitLogicalExpression(n *LogicalExpression)
	VisitMemberExpression(n *MemberExpression)
	VisitMemberProperty(n *MemberProperty)
	VisitMetaProperty(n *MetaProperty)
	VisitMethodDefinition(n *MethodDefinition)
	VisitNewExpression(n *NewExpression)
	VisitNullLiteral(n *NullLiteral)
	VisitNumberLiteral(n *NumberLiteral)
	VisitObjectLiteral(n *ObjectLiteral)
	VisitObjectPattern(n *ObjectPattern)
	VisitOptional(n *Optional)
	VisitOptionalChain(n *OptionalChain)
	VisitParameterList(n *ParameterList)
	VisitPattern(n *Pattern)
	VisitPatternKeyValue(n *PatternKeyValue)
	VisitPatternProperties(n *PatternProperties)
	VisitPatternProperty(n *PatternProperty)
	VisitPatternShorthand(n *PatternShorthand)
	VisitPatterns(n *Patterns)
	VisitPrivateDotExpression(n *PrivateDotExpression)
	VisitPrivateIdentifier(n *PrivateIdentifier)
	VisitProgram(n *Program)
	VisitProperties(n *Properties)
	VisitProperty(n *Property)
	VisitPropertyGetter(n *PropertyGetter)
	VisitPropertyKeyValue(n *PropertyKeyValue)
	VisitPropertyMethod(n *PropertyMethod)
	VisitPropertyName(n *PropertyName)
	VisitPropertySetter(n *PropertySetter)
	VisitPropertyShort(n *PropertyShort)
	VisitRegExpLiteral(n *RegExpLiteral)
	VisitReturnStatement(n *ReturnStatement)
	VisitSequenceExpression(n *SequenceExpression)
	VisitSpreadElement(n *SpreadElement)
	VisitStatement(n *Statement)
	VisitStatements(n *Statements)
	VisitStringLiteral(n *StringLiteral)
	VisitSuperExpression(n *SuperExpression)
	VisitSwitchCase(n *SwitchCase)
	VisitSwitchCases(n *SwitchCases)
	VisitSwitchStatement(n *SwitchStatement)
	VisitTemplateElement(n *TemplateElement)
	VisitTemplateElements(n *TemplateElements)
	VisitTemplateLiteral(n *TemplateLiteral)
	VisitThisExpression(n *ThisExpression)
	VisitThrowStatement(n *ThrowStatement)
	VisitTryStatement(n *TryStatement)
	VisitUnaryExpression(n *UnaryExpression)
	VisitUpdateExpression(n *UpdateExpression)
	VisitVariableDeclaration(n *VariableDeclaration)
	VisitVariableDeclarator(n *VariableDeclarator)
	VisitVariableDeclarators(n *VariableDeclarators)
	VisitWhileStatement(n *WhileStatement)
	VisitWithStatement(n *WithStatement)
	VisitYieldExpression(n *YieldExpression)
}
```

--------------------------------

### Subclassing GenVisitor with VisitNumberLiteral override

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/generator.md

Shows the supported extension pattern: embed generator.GenVisitor and override Visit* methods, delegating child traversal via VisitChildrenWith. All state is unexported, so direct buffer writes are not possible from a subclass.

```go
type myGen struct {
	generator.GenVisitor
}

// Override emission for a node kind; delegate children via VisitChildrenWith.
func (g *myGen) VisitNumberLiteral(n *ast.NumberLiteral) {
	n.VisitChildrenWith(g.V)
}
```

--------------------------------

### Clone method for concrete node structs

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-clone.md

Every concrete AST node struct T has a Clone() method that returns a fresh pointer to a deep copy of the node.

```go
func (n *T) Clone() *T
```

--------------------------------

### Handle partial program from parser.Parse

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/errors.md

Use this to handle partial parse results. Even when err is non-nil, the returned *ast.Program may still have a populated Body containing recovery nodes like BadStatement or InvalidExpression alongside successfully parsed statements.

```go
program, err := parser.Parse(`let x = ; y = 1;`)
// err != nil (parser.Errors accumulated), yet program.Body is still
// returned and may contain recovery nodes (BadStatement /
// InvalidExpression) alongside the statements that parsed successfully.
_ = program
```

--------------------------------

### Slice(from, to ast.Idx) string

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Returns a slice of the source between the given offsets.

```APIDOC
## Slice(from, to ast.Idx) string

### Description
Returns a slice of the source between the given offsets.

### Parameters
- `from` (ast.Idx) - Required - The start offset.
- `to` (ast.Idx) - Required - The end offset.

### Returns
- `string` - The substring from `from` to `to`.
```

--------------------------------

### Clone method for union wrappers

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-clone.md

Union wrappers (Expression, Statement, Pattern, Property, PropertyName, PatternProperty, ClassElement, MemberProperty, ConciseBody, ForInit, ForInto) have a Clone() method that clones the payload and re-wraps it.

```go
func (n *T) Clone() *T // clones the payload and re-wraps it
```

--------------------------------

### NextByte() (byte, bool)

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Consumes and returns the next byte. Returns false if at EOF.

```APIDOC
## NextByte() (byte, bool)

### Description
Consumes and returns the next byte. Returns false if at EOF.

### Returns
- `byte` - The next byte.
- `bool` - True if a byte was read, false if EOF.
```

--------------------------------

### NextRune / NextByte

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Consumes and returns the next rune or byte from the source. The boolean return indicates whether a value was available (false at EOF).

```APIDOC
## NextRune / NextByte

### Description
Consumes and returns the next rune or byte from the source. The boolean return indicates whether a value was available (false at EOF).

### Method Signatures
func (s *Scanner) NextRune() (rune, bool)
func (s *Scanner) NextByte() (byte, bool)

### Parameters
None

### Returns
- **rune/byte** - The consumed rune or byte
- **bool** - True if a value was available, false at EOF

### Example
```go
r, ok := s.NextRune()
if ok {
    // process rune
}
```
```

--------------------------------

### NoopVisitor struct definition

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-visitor.md

Defines the NoopVisitor type with a V field and a VisitArrayLiteral method that forwards to VisitChildrenWith. The comment indicates all other Visit* methods follow the same pattern, providing a safe default for full tree traversal when embedded.

```go
type NoopVisitor struct {
	V Visitor
}

func (nv *NoopVisitor) VisitArrayLiteral(n *ArrayLiteral) { n.VisitChildrenWith(nv.V) }
// ... every other Visit* method forwards to n.VisitChildrenWith(nv.V)
```

--------------------------------

### PeekRune / PeekByte

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Returns the next rune or byte without consuming it. The boolean return indicates whether a value is available (false at EOF).

```APIDOC
## PeekRune / PeekByte

### Description
Returns the next rune or byte without consuming it. The boolean return indicates whether a value is available (false at EOF).

### Method Signatures
func (s *Scanner) PeekRune() (rune, bool)
func (s *Scanner) PeekByte() (byte, bool)

### Parameters
None

### Returns
- **rune/byte** - The peeked rune or byte
- **bool** - True if a value is available, false at EOF

### Example
```go
r, ok := s.PeekRune()
if ok {
    // process rune without consuming
}
```
```

--------------------------------

### Id and Identifier struct definitions

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/ast-core.md

Defines the Id and Identifier structs with fields for name, scope context, and source position. Also declares methods ToId, String, Idx0, and Idx1.

```go
type (
	Id struct {
		Name         string
		ScopeContext ScopeContext
	}

	Identifier struct {
		Name         string
		ScopeContext ScopeContext

		Idx Idx
	}
)

func (n *Identifier) ToId() Id
func (i *Id) String() string // returns i.Name
func (i *Identifier) Idx0() Idx
func (i *Identifier) Idx1() Idx
```

--------------------------------

### GenVisitor struct definition

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/generator.md

Defines the GenVisitor struct with unexported fields for buffer, options, indentation, precedence/context state, and a binary stack. It embeds ast.NoopVisitor and implements the full ast.Visitor interface.

```go
type GenVisitor struct {
	ast.NoopVisitor

	buf  []byte
	opts Options

	indent int

	// Precedence/context state threaded through expression generation.
	// Set by genExpr before calling VisitWith; read by each expression visitor.
	prec ast.Precedence
	ctx  context

	binaryStack []binaryExprEntry
}
```

--------------------------------

### AdvanceIfByteEquals(b byte) (matched bool)

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

If the next byte equals the given byte, consumes it and returns true; otherwise returns false.

```APIDOC
## AdvanceIfByteEquals(b byte) (matched bool)

### Description
If the next byte equals the given byte, consumes it and returns true; otherwise returns false.

### Parameters
- `b` (byte) - Required - The byte to compare.

### Returns
- `bool` - True if the next byte matched and was consumed, false otherwise.
```

--------------------------------

### Generate function signature

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/generator.md

Declares the Generate function that renders an ast.VisitableNode as JavaScript source using default pretty options. Returns a string with tabs for indentation and newlines between statements.

```go
// Generate renders node as JavaScript source using the default (pretty) options.
func Generate(node ast.VisitableNode) string
```

--------------------------------

### Offset() ast.Idx

Source: https://github.com/t14raptor/go-fast/blob/master/_autodocs/api-reference/scanner.md

Returns the current position in the source.

```APIDOC
## Offset() ast.Idx

### Description
Returns the current position in the source.

### Returns
- `ast.Idx` - The current offset.
```
Tokens:
Raw