js

package
v0.39.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidLib is returned by NewEngine when a registered library is nil
	// or reports an empty name.
	ErrInvalidLib = errors.New("js: invalid lib")
	// ErrDuplicateLib is returned by NewEngine when two libraries share one
	// name, or a registered library shadows a standard library.
	ErrDuplicateLib = errors.New("js: duplicate lib name")
	// ErrLibNotFound is returned by Engine.NewRuntime when EnableLibs names a
	// library the engine catalog does not hold.
	ErrLibNotFound = errors.New("js: lib not found")
)
View Source 
var (
	Compile     = goja.Compile
	MustCompile = goja.MustCompile
	IsNaN       = goja.IsNaN
	IsString    = goja.IsString
	IsBigInt    = goja.IsBigInt
	IsNumber    = goja.IsNumber
	IsInfinity  = goja.IsInfinity
	IsUndefined = goja.IsUndefined
	IsNull      = goja.IsNull
)

Function aliases from goja for script compilation and type checking.

Functions

This section is empty.

Types

type AstProgram 

type AstProgram = ast.Program

Type aliases from goja for convenient access.

func Parse 

func Parse(name, src string) (*AstProgram, error)

Parse parses JavaScript source code into an AST.

type Engine added in v0.39.0 

type Engine struct {
	// contains filtered or unexported fields
}

Engine holds an immutable, validated set of libraries and stamps out runtimes. It is safe for concurrent use; one engine typically serves the whole application, with NewRuntime called wherever a script executes.

The engine distinguishes two library tiers: the baseline (the standard libraries plus any always-on libraries registered via WithBaseLibs, installed into every runtime) and the catalog (registered via WithLibs, installed only into runtimes that activate them through EnableLibs).

func NewEngine added in v0.39.0 

func NewEngine(opts ...EngineOption) (*Engine, error)

NewEngine builds an engine from the given options, validating the library set eagerly: a nil library, an empty name, or a name collision (across the standard, always-on, and catalog libraries) fails construction.

func (*Engine) NewRuntime added in v0.39.0 

func (e *Engine) NewRuntime(opts ...RuntimeOption) (*Runtime, error)

NewRuntime creates a fresh Runtime carrying the engine baseline plus the catalog libraries activated through EnableLibs. The returned Runtime is not safe for concurrent use; create one per goroutine and discard it after use.

type EngineOption added in v0.39.0 

type EngineOption func(*engineConfig)

EngineOption customizes engine construction.

func WithBaseLibs added in v0.39.0 

func WithBaseLibs(libs ...Lib) EngineOption

WithBaseLibs registers always-on libraries: they install into every runtime alongside the standard libraries, without an EnableLibs opt-in. Reserve this for safe, ubiquitous utilities; gate capabilities with side effects behind the catalog (WithLibs) instead.

func WithLibs added in v0.39.0 

func WithLibs(libs ...Lib) EngineOption

WithLibs registers libraries into the engine catalog. Catalog libraries are opt-in: each runtime activates the ones it needs via EnableLibs.

func WithoutStdLibs added in v0.39.0 

func WithoutStdLibs() EngineOption

WithoutStdLibs builds a bare engine whose runtimes start without the built-in standard library bundle (BigNumber, dayjs, fxp, radashi, z, and the URL / URLSearchParams polyfills). Libraries added through WithBaseLibs are unaffected.

type Func added in v0.39.0 

type Func func(args ...any) (Value, error)

Func is a JavaScript function handle callable from host code. Calls must happen on the goroutine currently driving the runtime — from a host callback, or between runs — matching the runtime's single-goroutine rule. A script exception surfaces as the returned error.

type Lib added in v0.39.0 

type Lib interface {
	// Name returns the library's unique identifier within an Engine.
	Name() string
	// Install binds the library into the runtime.
	Install(rt *Runtime) error
}

Lib is a named library that can be installed into a Runtime.

A Lib is either a pure JavaScript library (see SourceLib and ProgramLib) or a host capability implemented in Go (e.g. jshttp, jssql). Its name is the unique key within an Engine and, by convention, matches the global binding the library installs.

Implementations must be safe to install into multiple runtimes: a Lib holds shared, goroutine-safe dependencies (an http.Client, an orm.DB), never per-runtime state. Host libraries must issue IO through the context of the runtime they were installed into (Runtime.Context), so cancellation reaches blocking Go calls.

func ProgramLib added in v0.39.0 

func ProgramLib(name string, program *Program) Lib

ProgramLib builds a Lib from a pre-compiled JavaScript program.

func SourceLib added in v0.39.0 

func SourceLib(name, source string) (Lib, error)

SourceLib builds a Lib from JavaScript source, compiling it eagerly so syntax errors surface at construction time rather than at install time.

type Object 

type Object = goja.Object

Type aliases from goja for convenient access.

type Program 

type Program = goja.Program

Type aliases from goja for convenient access.

type Runtime 

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime is a sandboxed JavaScript runtime bound to a single goroutine. It carries the engine baseline plus the catalog libraries activated at creation; scripts can touch nothing beyond what was installed.

A Runtime is not safe for concurrent use, and only one Run call may be in flight at a time.

func (*Runtime) AsFunction added in v0.39.0 

func (r *Runtime) AsFunction(value Value) (Func, bool)

AsFunction converts a value produced by this runtime into a callable Func; ok is false when the value is not a function.

func (*Runtime) Context added in v0.39.0 

func (r *Runtime) Context() context.Context

Context returns the context of the in-flight Run call, or context.Background when the runtime is idle. Host libraries must issue IO through it so cancellation reaches blocking Go calls.

func (*Runtime) RunProgram added in v0.39.0 

func (r *Runtime) RunProgram(ctx context.Context, program *Program) (Value, error)

RunProgram executes a pre-compiled program. Cancellation of ctx interrupts the running script and, through Context, any in-flight host library IO; the returned error is then the context's error.

func (*Runtime) RunString added in v0.39.0 

func (r *Runtime) RunString(ctx context.Context, source string) (Value, error)

RunString compiles and executes source with the same cancellation semantics as RunProgram.

func (*Runtime) Set added in v0.39.0 

func (r *Runtime) Set(name string, value any) error

Set binds a value as a global variable of the runtime.

func (*Runtime) VM added in v0.39.0 

func (r *Runtime) VM() *goja.Runtime

VM exposes the underlying goja runtime for advanced library authoring (custom object construction, exception throwing). Prefer the Runtime methods for everything else.

type RuntimeOption added in v0.39.0 

type RuntimeOption func(*runtimeConfig)

RuntimeOption customizes a single runtime produced by Engine.NewRuntime.

func EnableLibs added in v0.39.0 

func EnableLibs(names ...string) RuntimeOption

EnableLibs activates catalog libraries by name for the new runtime. Installation follows the argument order; enabling a name twice is a no-op. An unknown name fails NewRuntime with ErrLibNotFound.

func WithMaxCallStackSize added in v0.39.0 

func WithMaxCallStackSize(size int) RuntimeOption

WithMaxCallStackSize bounds the JavaScript call stack depth, guarding against runaway recursion.

func WithRunTimeout added in v0.39.0 

func WithRunTimeout(d time.Duration) RuntimeOption

WithRunTimeout caps the duration of every Run call on the runtime. It combines with the caller's context: whichever deadline is earlier wins.

type Value 

type Value = goja.Value

Type aliases from goja for convenient access.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.