qjs

package module
v0.0.1 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2025 License: MIT Imports: 23 Imported by: 4

README

QJS - JavaScript in Go with QuickJS and Wazero

Go.Dev reference go report card test status MIT license

QJS is a CGO-Free, modern, secure JavaScript runtime for Go applications, built on the powerful QuickJS engine and Wazero WebAssembly runtime. It allows you to run JavaScript code safely and efficiently, with full support for ES6+ features, async/await, and Go-JS interoperability.

Features

  • JavaScript ES6+ Support: Full ECMAScript 2020 compatibility via QuickJS
  • WebAssembly Execution: Secure, sandboxed runtime using Wazero
  • Go-JS Interoperability: Seamless data conversion between Go and JavaScript
  • ProxyValue Support: Zero-copy sharing of Go values with JavaScript via lightweight proxies
  • Function Binding: Expose Go functions to JavaScript and vice versa
  • Module System: Support for ES6 modules and CommonJS
  • Async/Await: Full support for asynchronous JavaScript execution
  • Runtime Pooling: Reuse JavaScript runtimes for better performance
  • Memory Safety: Memory-safe execution environment with configurable limits
  • No CGO Dependencies: Pure Go implementation with WebAssembly

Example Usage

Basic Execution
rt, err := qjs.New()
if err != nil {
    panic(err)
}

defer rt.Close()
ctx := rt.Context()

result, err := ctx.Eval("test.js", qjs.Code(`
    const person = {
        name: "Alice",
        age: 30,
        city: "New York"
    };

    const info = Object.keys(person).map(key =>
        key + ": " + person[key]
    ).join(", ");

    ({ person: person, info: info });
`))
if err != nil {
    log.Fatal("Eval error:", err)
}
defer result.Free()
// Output: name: Alice, age: 30, city: New York
log.Println(result.GetPropertyStr("info").String())
// Output: Alice
log.Println(result.GetPropertyStr("person").GetPropertyStr("name").String())
// Output: 30
log.Println(result.GetPropertyStr("person").GetPropertyStr("age").Int32())
Go function binding
ctx.SetFunc("goFunction", func(this *qjs.This) (*qjs.Value, error) {
    return this.Context().NewString("Hello from Go!"), nil
})

result, err := ctx.Eval("test.js", qjs.Code(`
    const message = goFunction();
    message;
`))
if err != nil {
    panic(err)
}
defer result.Free()

// Output: Hello from Go!
log.Println(result.String())
Async operations

Awaiting a promise

ctx.SetAsyncFunc("asyncFunction", func(this *qjs.This) {
    go func() {
        time.Sleep(100 * time.Millisecond)
        result := this.Context().NewString("Async result from Go!")
        this.Promise().Resolve(result)
    }()
})

result, err := ctx.Eval("test.js", qjs.Code(`
    async function main() {
        const result = await asyncFunction();
        return result;
    }
    main()
`))

if err != nil {
    log.Fatal("Eval error:", err)
}
defer result.Free()

// Wait for the promise to resolve
result.Await()
// Output: Async result from Go!
log.Println(result.String())

Top level await

result, err := ctx.Eval("test.js", qjs.Code(`
    async function main() {
        const result = await asyncFunction();
        return result;
    }
    await main()
`), qjs.FlagAsync())

if err != nil {
    log.Fatal("Eval error:", err)
}

defer result.Free()
log.Println(result.String())
Call JS function from Go
// Call JS function from Go
result, err := ctx.Eval("test.js", qjs.Code(`
    function add(a, b) {
        return a + b;
    }

    function errorFunc() {
        throw new Error("test error");
    }

    ({
        addFunc: add,
        errorFunc: errorFunc
    });
`))

if err != nil {
    panic(err)
}
defer result.Free()

jsAddFunc := result.GetPropertyStr("addFunc")
defer jsAddFunc.Free()

goAddFunc, err := qjs.JsFuncToGo[func(int, int) (int, error)](jsAddFunc)
if err != nil {
    panic(err)
}

total, err := goAddFunc(1, 2)
if err != nil {
    panic(err)
}

// Output: 3
log.Println(total)

jsErrorFunc := result.GetPropertyStr("errorFunc")
defer jsErrorFunc.Free()

goErrorFunc, err := qjs.JsFuncToGo[func() (any, error)](jsErrorFunc)
if err != nil {
    panic(err)
}

_, err = goErrorFunc()
if err != nil {
    // Output:
    // JS function execution failed: Error: test error
    // 	at errorFunc (test.js:7:14)
    log.Println(err.Error())
}
ES Modules
// Load a utility module
if _, err = ctx.Load("math-utils.js", qjs.Code(`
    export function add(a, b) {
        return a + b;
    }

    export function multiply(a, b) {
        return a * b;
    }

    export function power(base, exponent) {
        return Math.pow(base, exponent);
    }

    export const PI = 3.14159;
    export const E = 2.71828;
    export default {
        add,
        multiply,
        power,
        PI,
        E
    };
`)); err != nil {
    panic(err)
}

// Use the module
result, err := ctx.Eval("use-math.js", qjs.Code(`
    import mathUtils, { add, multiply, power, PI } from 'math-utils.js';

    const calculations = {
        addition: add(10, 20),
        multiplication: multiply(6, 7),
        power: power(2, 8),
        circleArea: PI * power(5, 2),
        defaultAdd: mathUtils.add(10, 20)
    };

    export default calculations;
`), qjs.TypeModule())

if err != nil {
    log.Fatal("Module eval error:", err)
}

// Output:
// Addition: 30
// Multiplication: 42
// Power: 256
// Circle Area: 78.54
// Default Add: 30
fmt.Printf("Addition: %d\n", result.GetPropertyStr("addition").Int32())
fmt.Printf("Multiplication: %.0f\n", result.GetPropertyStr("multiplication").Float64())
fmt.Printf("Power: %.0f\n", result.GetPropertyStr("power").Float64())
fmt.Printf("Circle Area: %.2f\n", result.GetPropertyStr("circleArea").Float64())
fmt.Printf("Default Add: %.d\n", result.GetPropertyStr("defaultAdd").Int32())
result.Free()
Bytecode Compilation
script := `
    function fibonacci(n) {
        if (n <= 1) return n;
        return fibonacci(n - 1) + fibonacci(n - 2);
    }

    function factorial(n) {
        return n <= 1 ? 1 : n * factorial(n - 1);
    }

    const result = {
        fib10: fibonacci(10),
        fact5: factorial(5),
        timestamp: Date.now()
    };

    result;
`

// Compile the script to bytecode
bytecode, err := ctx.Compile("math-functions.js", qjs.Code(script))
if err != nil {
    log.Fatal("Compilation error:", err)
}

fmt.Printf("Bytecode size: %d bytes\n", len(bytecode))

// Execute the compiled bytecode
result, err := ctx.Eval("compiled-math.js", qjs.Bytecode(bytecode))
if err != nil {
    log.Fatal("Bytecode execution error:", err)
}

fmt.Printf("Fibonacci(10): %d\n", result.GetPropertyStr("fib10").Int32())
fmt.Printf("Factorial(5): %d\n", result.GetPropertyStr("fact5").Int32())
result.Free()
ProxyValue Support

ProxyValue is a feature that allows you to pass Go values directly to JavaScript without full serialization, enabling efficient sharing of complex objects, functions, and resources.

ProxyValue creates a lightweight JavaScript wrapper around Go values, storing only a reference ID rather than copying the entire value. This is particularly useful for pass-through scenarios where JavaScript receives a Go value and passes it back to Go without needing to access its contents.

Key benefits:

  • Zero-copy data sharing - no serialization/deserialization overhead
  • Pass-through efficiency - JavaScript can hold and return Go values without conversion
  • Type preservation - original Go types are maintained across boundaries
  • Resource efficiency - perfect for objects like context.Context, database connections, or large structs

Most common use case: JavaScript callbacks that receive Go values (like context.Context) and pass them back to Go functions without ever accessing the value contents in JavaScript.

Basic ProxyValue Usage
package main

import (
	"context"
	"fmt"

	"github.com/fastschema/qjs"
)

func main() {
	rt, err := qjs.New()
	if err != nil {
		panic(err)
	}
	defer rt.Close()
	ctx := rt.Context()

	// Create a Go function that accepts context and a number
	goFuncWithContext := func(ctx context.Context, num int) int {
		// Access context values in Go
		fmt.Printf("Context received: %v\n", ctx)
		return num * 2
	}

	// Convert Go function to JavaScript function
	jsFuncWithContext, err := qjs.ToJSValue(ctx, goFuncWithContext)
	if err != nil {
		panic(err)
	}
	defer jsFuncWithContext.Free()
	ctx.Global().SetPropertyStr("funcWithContext", jsFuncWithContext)

	// Create a helper function that returns a ProxyValue
	ctx.SetFunc("$context", func(this *qjs.This) (*qjs.Value, error) {
		// Create context as ProxyValue - JavaScript will never access its contents
		val := ctx.NewProxyValue(context.Background())
		return val, nil
	})

	// JavaScript gets context as ProxyValue and passes it to Go function
	result, err := ctx.Eval("test.js", qjs.Code(`
		funcWithContext($context(), 10);
	`))
	if err != nil {
		panic(err)
	}
	defer result.Free()

	// Output: 20
	fmt.Println(result.Int32())
}
GO-JS Conversion
package main

import (
	"fmt"

	"github.com/fastschema/qjs"
)

type Post struct {
	ID     int    `json:"id"`
	Name   string `json:"name"`
	Author User   `json:"author"`
}

type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
	Age  int    `json:"age"`
}

// Method on User struct
func (u User) GetDisplayName() string {
	return fmt.Sprintf("%s (%d)", u.Name, u.Age)
}

func (u User) IsAdult() bool {
	return u.Age >= 18
}

func main() {
	rt, err := qjs.New()
	if err != nil {
		panic(err)
	}
	defer rt.Close()
	ctx := rt.Context()

	ctx.Global().SetPropertyStr("goInt", ctx.NewInt32(55))
	ctx.Global().SetPropertyStr("goString", ctx.NewString("Hello, World!"))
	jsUser, err := qjs.ToJSValue(ctx, User{ID: 1, Name: "Alice", Age: 25})
	if err != nil {
		panic(err)
	}
	ctx.Global().SetPropertyStr("goUser", jsUser)

	result, err := ctx.Eval("test.js", qjs.Code(`
		const post = {
			id: goInt,
			name: goString,
			author: goUser
		};
		post;
	`))
	if err != nil {
		panic(err)
	}
	defer result.Free()

	goPost, err := qjs.JsValueToGo[Post](result)
	if err != nil {
		panic(err)
	}

	// Output:
	// Post ID: 55
	// Post Name: Hello, World!
	// Author ID: 1
	// Author Name: Alice
	// Author Age: 25
	fmt.Printf("Post ID: %d\n", goPost.ID)
	fmt.Printf("Post Name: %s\n", goPost.Name)
	fmt.Printf("Author ID: %d\n", goPost.Author.ID)
	fmt.Printf("Author Name: %s\n", goPost.Author.Name)
	fmt.Printf("Author Age: %d\n", goPost.Author.Age)
}
Pool
package main

import (
	"log"
	"sync"

	"github.com/fastschema/qjs"
)

func main() {
	setupFunc := func(rt *qjs.Runtime) error {
		ctx := rt.Context()
		ctx.Eval("setup.js", qjs.Code(`
			function getMessage(workerId, taskId) {
				return "Hello from pooled runtime: " + workerId + "-" + taskId;
			}
		`))
		return nil
	}
	// Create a pool with 3 runtimes
	pool := qjs.NewPool(3, &qjs.Option{}, setupFunc)
	numWorkers := 5
	numTasks := 3
	var wg sync.WaitGroup

	for i := 0; i < numWorkers; i++ {
		wg.Add(1)
		go func(workerID int) {
			defer wg.Done()
			for j := 0; j < numTasks; j++ {
				rt, err := pool.Get()
				if err != nil {
					panic(err)
				}
				defer pool.Put(rt)
				ctx := rt.Context()
				workerIdValue := ctx.NewInt32(int32(workerID))
				taskIdValue := ctx.NewInt32(int32(j))
				ctx.Global().SetPropertyStr("workerID", workerIdValue)
				ctx.Global().SetPropertyStr("taskID", taskIdValue)

				// Use the runtime
				result, err := ctx.Eval("pool-test.js", qjs.Code(`
					({
						message: getMessage(workerID, taskID),
						timestamp: Date.now(),
					});
				`))
				if err != nil {
					panic(err)
				}
				defer result.Free()
				log.Println(result.GetPropertyStr("message").String())
			}
		}(i)
	}
	wg.Wait()
}

Installation

go get github.com/fastschema/qjs

import "github.com/fastschema/qjs"

Compatible with Go 1.22.0+

Architecture

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Your Go   │ ---> │   Wazero    │ ---> │   QuickJS   │
│ Application │      │ WebAssembly │      │ JavaScript  │
│             │      │  Runtime    │      │   Engine    │
└─────────────┘      └─────────────┘      └─────────────┘
       ^                    ^                     ^
       │                    │                     │
   Structured           Sandboxed              ES2020+
   Go Types               Memory              Modern JS

API Reference

Core Types
Type Description
Runtime Main JavaScript runtime instance
Context JavaScript execution context
Value JavaScript value wrapper
Pool Runtime pool for performance
ProxyRegistry Thread-safe registry for ProxyValue objects
Key Methods
// Runtime Management
rt, err := qjs.New(options...)           // Create runtime
rt.Close()                               // Cleanup runtime
ctx.Eval(filename, code, flags...)        // Execute JavaScript
rt.Load(filename, code)                  // Load module
rt.Compile(filename, code)               // Compile to bytecode
...

// Context Operations  
ctx := ctx                      // Get context
ctx.Global()                             // Access global object
ctx.SetFunc(name, fn)                    // Bind Go function
ctx.SetAsyncFunc(name, fn)               // Bind async function
ctx.NewString(s)                         // Create JS string
ctx.NewObject()                          // Create JS object
ctx.NewProxyValue(v)                     // Create ProxyValue from Go value
...

// Value Operations
value.String()                           // Convert to Go string
value.Int32()                            // Convert to Go int32
value.Bool()                             // Convert to Go bool
value.GetPropertyStr(name)               // Get object property
value.SetPropertyStr(name, val)          // Set object property
value.IsQJSProxyValue()                  // Check if value is a ProxyValue
value.Free()                             // Release memory
...

// ProxyValue Operations
qjs.JsValueToGo[T](value)               // Extract Go value from ProxyValue
qjs.ToJSValue(ctx, goValue)             // Convert Go value to JS (auto-detects ProxyValue need)
...
Configuration Options
type Option struct {
    CWD                string  // Working directory
    MaxStackSize       int     // Stack size limit
    MemoryLimit        int     // Memory usage limit  
    MaxExecutionTime   int     // Execution timeout
    GCThreshold        int     // GC trigger threshold
}

Performance & Security

Optimization Tips:

  1. Use runtime pools for concurrent applications
  2. Compile frequently-used scripts to bytecode
  3. Use ProxyValue for large objects or shared state to avoid serialization overhead
  4. Minimize small object conversions between Go and JS - prefer ProxyValue for complex types
  5. Set appropriate memory limits

Security

  • Complete filesystem isolation (unless explicitly configured)
  • No network access from JavaScript (unless explicitly allowed)
  • Memory safe - no buffer overflows
  • No CGO attack surface
  • Deterministic resource cleanup
  • ProxyValue safety - Go values are protected by type checking and automatic cleanup
Memory Management

Critical Rules:

  • Always call result.Free() on JavaScript values
  • Always call rt.Close() when done with runtime
  • Don't free functions registered to global object
  • Don't free object properties directly – free the entire object
// Correct pattern
result, err := ctx.Eval("script.js", code)
if err != nil {
    return err
}
defer result.Free() // Always free values

// Wrong - will cause memory leaks
result, _ := ctx.Eval("script.js", code)
// Missing result.Free()

Choose QJS when you need:

  • Modern JavaScript features with security
  • Zero external dependencies
  • Plugin systems or user-generated code
  • Compliance with strict security requirements

Choose alternatives when:

  • v8go: Maximum performance and you can manage CGO dependencies
  • goja: Simple scripts and don't need modern JS features
  • otto: Legacy JavaScript and minimal dependencies

Building from Source

Prerequisites
  • Go 1.23.0+
  • WASI SDK (for WebAssembly compilation)
  • CMake 3.16+
  • Make
Quick Build
# Clone with submodules
git clone --recursive https://github.com/fastschema/qjs.git
cd qjs

# Install WASI SDK (Linux/macOS)
curl -L https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-20/wasi-sdk-20.0-linux.tar.gz | tar xz
sudo mv wasi-sdk-20.0 /opt/wasi-sdk

# Build WebAssembly module
make build

# Run tests
go test ./...
Development Workflow
# Build and test
make build && go test ./...

# Run benchmarks
go test -bench=. ./...

# Coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Contributing

We'd love your help making QJS better! Here's how:

  1. Found a bug? Open an issue
  2. Want a feature? Start a discussion
  3. Ready to code? Fork, branch, test, and submit a PR

Development Setup:

git clone --recursive https://github.com/fastschema/qjs.git
cd qjs
make build
go test ./...

Code Standards:

  • Follow standard Go conventions (gofmt, golangci-lint)
  • Add tests for new features
  • Update documentation for API changes
  • Keep commit messages clear and descriptive

Support & Community

Getting Help:

  1. Check existing issues and documentation
  2. Create a minimal reproduction case
  3. Include Go version, OS, and QJS version
  4. Be specific about expected vs actual behavior

License

MIT License - see LICENSE file.

Acknowledgments

Built on the shoulders of giants:

  • QuickJS by Fabrice Bellard - The elegant JavaScript engine
  • Wazero - Pure Go WebAssembly runtime
  • QuickJS-NG - Maintained QuickJS fork

Ready to run JavaScript safely in your Go apps?

go get github.com/fastschema/qjs

Questions? Ideas? Contributions? We're here to help → Start a discussion

Documentation

Index

Constants

View Source 
const (
	// MinMapForeachArgs is the minimum number of arguments for Map forEach callback (value, key).
	MinMapForeachArgs = 2
	// NanosToMillis is the conversion factor from nanoseconds to milliseconds.
	NanosToMillis = 1e6
	// Uint64ByteSize is the size of a uint64 value in bytes.
	Uint64ByteSize = 8
	// Uint64SignBitPosition is the bit position of the sign bit in a 64-bit unsigned integer.
	Uint64SignBitPosition = 63
	// PackedPtrSize is the size in bytes of a packed pointer structure.
	PackedPtrSize = 8
	// NullPtr represents a null pointer value.
	NullPtr = uint32(0)
	// StringTerminator is the null terminator byte for C-style strings.
	StringTerminator = byte(0)
)
View Source 
const (
	// JsEvalTypeGlobal evaluates code in global scope (default).
	JsEvalTypeGlobal = (0 << 0)
	// JsEvalTypeModule evaluates code as ES6 module.
	JsEvalTypeModule = (1 << 0)
	// JsEvalTypeDirect performs direct call (internal use).
	JsEvalTypeDirect = (2 << 0)
	// JsEvalTypeInDirect performs indirect call (internal use).
	JsEvalTypeInDirect = (3 << 0)
	// JsEvalTypeMask masks the eval type bits.
	JsEvalTypeMask = (3 << 0)
	// JsEvalFlagStrict forces strict mode execution.
	JsEvalFlagStrict = (1 << 3)
	// JsEvalFlagUnUsed is reserved for future use.
	JsEvalFlagUnUsed = (1 << 4)
	// JsEvalFlagCompileOnly returns a JS bytecode/module for JS_EvalFunction().
	JsEvalFlagCompileOnly = (1 << 5)
	// JsEvalFlagBackTraceBarrier prevents the stack frames before this eval in the Error() backtraces.
	JsEvalFlagBackTraceBarrier = (1 << 6)
	// JsEvalFlagAsync enables top-level await (global scope only).
	JsEvalFlagAsync = (1 << 7)
)

Variables

View Source 
var (
	ErrRType                   = reflect.TypeOf((*error)(nil)).Elem()
	ErrZeroRValue              = reflect.Zero(ErrRType)
	ErrCallFuncOnNonObject     = errors.New("cannot call function on non-object")
	ErrNotAnObject             = errors.New("value is not an object")
	ErrObjectNotAConstructor   = errors.New("object not a constructor")
	ErrInvalidFileName         = errors.New("file name is required")
	ErrMissingProperties       = errors.New("value has no properties")
	ErrInvalidPointer          = errors.New("null pointer dereference")
	ErrIndexOutOfRange         = errors.New("index out of range")
	ErrNoNullTerminator        = errors.New("no NUL terminator")
	ErrInvalidContext          = errors.New("invalid context")
	ErrNotANumber              = errors.New("js value is not a number")
	ErrAsyncFuncRequirePromise = errors.New("jsFunctionProxy: async function requires a promise")
	ErrEmptyStringToNumber     = errors.New("empty string cannot be converted to number")
	ErrJsFuncDeallocated       = errors.New("js function context has been deallocated")
	ErrNotByteArray            = errors.New("invalid TypedArray: buffer is not a byte array")
	ErrNotArrayBuffer          = errors.New("input is not an ArrayBuffer")
	ErrMissingBufferProperty   = errors.New("invalid TypedArray: missing buffer property")
	ErrRuntimeClosed           = errors.New("runtime is closed")
	ErrNilModule               = errors.New("WASM module is nil")
	ErrNilHandle               = errors.New("handle is nil")
	ErrChanClosed              = errors.New("channel is closed")
	ErrChanSend                = errors.New("channel send would block: buffer full or no receiver ready")
	ErrChanReceive             = errors.New("channel receive would block: buffer empty or no sender ready")
	ErrChanCloseReceiveOnly    = errors.New("cannot close receive-only channel")
)

Functions

func AnyToError 

func AnyToError(err any) error

func ConvertToSigned 

func ConvertToSigned[T Signed](h *Handle) T

ConvertToSigned performs safe conversion to signed integer types with bounds checking.

func ConvertToUnsigned 

func ConvertToUnsigned[T Unsigned](h *Handle) T

ConvertToUnsigned performs safe conversion to unsigned integer types with bounds checking.

func CreateChannelCloseFunc 

func CreateChannelCloseFunc(rval reflect.Value) func() error

CreateChannelCloseFunc creates a function for closing a channel.

func CreateChannelReceiveFunc 

func CreateChannelReceiveFunc(chanRValue reflect.Value) func() (any, error)

CreateChannelReceiveFunc creates a function for receiving values from a channel.

func CreateChannelSendFunc 

func CreateChannelSendFunc(chanRValue reflect.Value) any

CreateChannelSendFunc creates 'func(T) error' for sending T to a channel.

func CreateGoBindFuncType 

func CreateGoBindFuncType[T any](sample T) (fnType reflect.Type, err error)

func CreateGoFuncSignature 

func CreateGoFuncSignature(fnType reflect.Type) string

CreateGoFuncSignature creates a readable string for function types.

func CreateNonNilSample 

func CreateNonNilSample(argType reflect.Type) any

CreateNonNilSample creates appropriate non-nil samples for types that have nil zero values.

func CreateVariadicSlice 

func CreateVariadicSlice(jsArgs []*Value, sliceType reflect.Type, fixedArgsCount int) (reflect.Value, error)

CreateVariadicSlice creates a reflect.Value slice for variadic arguments. Converts remaining JS arguments to the slice element type and returns as a slice value.

func FloatToInt 

func FloatToInt(floatVal float64, targetKind reflect.Kind) (any, error)

func GetGoTypeName 

func GetGoTypeName(input any) string

GetGoTypeName creates a descriptive string for complex types.

func Is32BitPlatform 

func Is32BitPlatform() bool

Is32BitPlatform check if the platform is 32-bit by comparing the size of uintptr.

func IsConvertibleToJs 

func IsConvertibleToJs(rType reflect.Type, visited map[reflect.Type]bool, detail string) (err error)

IsConvertibleToJs checks if a Go type can be converted to a JavaScript type.

func IsImplementError 

func IsImplementError(rtype reflect.Type) bool

func IsImplementsJSONUnmarshaler 

func IsImplementsJSONUnmarshaler(t reflect.Type) bool

IsImplementsJSONUnmarshaler checks if a type implements json.Unmarshaler.

func IsNumericType 

func IsNumericType(t reflect.Type) bool

IsNumericType checks if a reflect.Type represents a numeric type.

func IsTypedArray 

func IsTypedArray(input *Value) bool

IsTypedArray returns true if the input is TypedArray or DataView.

func IsValid32BitFloat 

func IsValid32BitFloat(floatVal float64, targetKind reflect.Kind) error

func JsArgToGo 

func JsArgToGo(jsArg *Value, argType reflect.Type) (reflect.Value, error)

JsArgToGo converts a single JS argument to a Go value with enhanced type handling.

func JsArrayBufferToGo 

func JsArrayBufferToGo(input *Value) ([]byte, error)

JsArrayBufferToGo converts an ArrayBuffer to a []byte.

func JsArrayToGo 

func JsArrayToGo[T any](input *Value, samples ...T) (T, error)

JsArrayToGo handles conversion of JavaScript Array objects to Go types.

func JsBigIntToGo 

func JsBigIntToGo[T any](input *Value, samples ...T) (v T, err error)

JsBigIntToGo converts a JS BigInt into the Go *big.Int/big.Int.

func JsFuncArgsToGo 

func JsFuncArgsToGo(jsArgs []*Value, fnType reflect.Type) ([]reflect.Value, error)

JsFuncArgsToGo converts JS arguments to Go arguments in both variadic and non-variadic functions, filling missing arguments with zero values.

func JsFuncToGo 

func JsFuncToGo[T any](input *Value, samples ...T) (v T, err error)

func JsNumberToGo 

func JsNumberToGo[T any](input *Value, samples ...T) (v T, err error)

JsNumberToGo converts JavaScript numbers to Go numeric types.

func JsObjectOrMapToGoMap 

func JsObjectOrMapToGoMap[T any](input *Value, samples ...T) (v T, err error)

func JsObjectOrMapToGoStruct 

func JsObjectOrMapToGoStruct[T any](
	input *Value,
	samples ...T,
) (v T, err error)

func JsObjectToGo 

func JsObjectToGo[T any](input *Value, samples ...T) (v T, err error)

JsObjectToGo handles conversion of JavaScript objects to Go types.

func JsSetToGo 

func JsSetToGo[T any](input *Value, samples ...T) (v T, err error)

JsSetToGo converts JavaScript Set to Go types.

func JsTimeToGo 

func JsTimeToGo(input *Value) (time.Time, error)

JsTimeToGo converts a JS Date object into a time.Time value.

func JsTypedArrayToGo 

func JsTypedArrayToGo(input *Value) ([]byte, error)

JsTypedArrayToGo return the underlying byte slice from a TypedArray/DataView.

func JsValueToGo 

func JsValueToGo[T any](input *Value, samples ...T) (v T, err error)

func Min 

func Min(a, b int) int

func NumericBoundsCheck 

func NumericBoundsCheck(floatVal float64, targetKind reflect.Kind) error

func ParseTimezone 

func ParseTimezone(tz string) *time.Location

ParseTimezone attempts to parse a timezone string as either an IANA location name or a UTC offset format (+/-HH:MM). Returns UTC location if parsing fails.

func StringToNumeric 

func StringToNumeric(s string, targetType reflect.Type) (result any, err error)

func VerifyGoFunc 

func VerifyGoFunc(fnType reflect.Type, sample any) error

VerifyGoFunc validates that a function signature is compatible with JS conversion.

Types

type Array 

type Array struct {
	*Value
}

Array provides a wrapper around JavaScript arrays with Go-like methods.

func NewArray 

func NewArray(value *Value) *Array

NewArray wraps a JavaScript array value in a Go Array type.

func (*Array) Delete 

func (a *Array) Delete(index int64) bool

Delete removes the element at the given index.

func (*Array) ForEach 

func (a *Array) ForEach(forFn func(key, value *Value))

func (*Array) Get 

func (a *Array) Get(index int64) *Value

Get returns the element at the given index.

func (*Array) HasIndex 

func (a *Array) HasIndex(i int64) bool

HasIndex returns true if the given index exists in the array.

func (*Array) Push 

func (a *Array) Push(elements ...*Value) int64

Push appends elements to the array and returns the new length.

func (*Array) Set 

func (a *Array) Set(index int64, value *Value)

Set updates the element at the given index.

type AsyncFunction 

type AsyncFunction func(ctx *This)

type Atom 

type Atom struct {
	*Value
	// contains filtered or unexported fields
}

Atom represents a JavaScript atom: Object property names and some strings are stored as Atoms (unique strings) to save memory and allow fast comparison.

func (Atom) Free 

func (a Atom) Free()

func (Atom) String 

func (a Atom) String() string

func (Atom) ToValue 

func (a Atom) ToValue() *Value

type CircularTracker 

type CircularTracker[T uintptr | uint64] struct {
	// contains filtered or unexported fields
}

CircularTracker manages the lifecycle of circular reference tracking for a single object.

type Context 

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

Context represents a QuickJS execution context with associated runtime.

func (*Context) Call 

func (c *Context) Call(name string, args ...uint64) *Value

func (*Context) CallUnPack 

func (c *Context) CallUnPack(name string, args ...uint64) (uint32, uint32)

CallUnPack delegates function calls and unpacks the result.

func (*Context) Compile 

func (c *Context) Compile(file string, flags ...EvalOptionFunc) ([]byte, error)

Compile compiles a script into bytecode.

func (*Context) Eval 

func (c *Context) Eval(file string, flags ...EvalOptionFunc) (*Value, error)

Eval evaluates a script within the current context.

func (*Context) Exception 

func (c *Context) Exception() error

Exception returns and clears the current pending exception.

func (*Context) FreeHandle 

func (c *Context) FreeHandle(ptr uint64)

FreeHandle releases memory associated with the given handle pointer.

func (*Context) FreeJsValue 

func (c *Context) FreeJsValue(val uint64)

FreeJsValue releases memory associated with the JavaScript value.

func (*Context) Function 

func (c *Context) Function(fn Function, isAsyncs ...bool) *Value

Function creates a JavaScript function that wraps the given Go function.

func (*Context) Global 

func (c *Context) Global() *Value

Global returns the global object, caching it for subsequent calls.

func (*Context) HasException 

func (c *Context) HasException() bool

HasException returns true if there is a pending exception.

func (*Context) Invoke 

func (c *Context) Invoke(fn *Value, this *Value, args ...*Value) (*Value, error)

Invoke invokes a function with given this value and arguments.

func (*Context) Load 

func (c *Context) Load(file string, flags ...EvalOptionFunc) (*Value, error)

Load loads a JavaScript module without evaluating it.

func (*Context) Malloc 

func (c *Context) Malloc(size uint64) uint64

Malloc allocates memory in the WASM runtime.

func (*Context) MemRead 

func (c *Context) MemRead(addr uint32, size uint64) []byte

MemRead reads bytes from WASM memory at the given address.

func (*Context) MemWrite 

func (c *Context) MemWrite(addr uint32, b []byte)

MemWrite writes bytes to WASM memory at the given address.

func (*Context) NewArray 

func (c *Context) NewArray() *Array

NewArray creates a new empty JavaScript array.

func (*Context) NewArrayBuffer 

func (c *Context) NewArrayBuffer(binaryData []byte) *Value

NewArrayBuffer creates a new JavaScript ArrayBuffer with the given binary data.

func (*Context) NewAtom 

func (c *Context) NewAtom(v string) Atom

NewAtom creates a new Atom from the given string.

func (*Context) NewAtomIndex 

func (c *Context) NewAtomIndex(index int64) Atom

NewAtomIndex creates a new Atom with the given index.

func (*Context) NewBigInt64 

func (c *Context) NewBigInt64(v int64) *Value

NewBigInt64 creates a new JavaScript BigInt from int64.

func (*Context) NewBigUint64 

func (c *Context) NewBigUint64(v uint64) *Value

NewBigUint64 creates a new JavaScript BigInt from uint64.

func (*Context) NewBool 

func (c *Context) NewBool(b bool) *Value

NewBool creates a new JavaScript boolean value.

func (*Context) NewBytes 

func (c *Context) NewBytes(v []byte) *Value

NewBytes creates a Value from a byte slice.

func (*Context) NewDate 

func (c *Context) NewDate(t *time.Time) *Value

NewDate creates a new JavaScript Date object from the given time.

func (*Context) NewError 

func (c *Context) NewError(e error) *Value

NewError creates a new JavaScript Error object from Go error.

func (*Context) NewFloat64 

func (c *Context) NewFloat64(v float64) *Value

NewFloat64 creates a new JavaScript number from float64.

func (*Context) NewInt32 

func (c *Context) NewInt32(v int32) *Value

NewInt32 creates a new JavaScript number from int32.

func (*Context) NewInt64 

func (c *Context) NewInt64(v int64) *Value

NewInt64 creates a new JavaScript number from int64.

func (*Context) NewMap 

func (c *Context) NewMap() *Map

NewMap creates a new JavaScript Map object.

func (*Context) NewNull 

func (c *Context) NewNull() *Value

NewNull creates a new null JavaScript value.

func (*Context) NewObject 

func (c *Context) NewObject() *Value

NewObject creates a new empty JavaScript object.

func (*Context) NewProxyValue 

func (c *Context) NewProxyValue(v any) *Value

NewProxyValue creates a new Value that represents a proxy to a Go value.

func (*Context) NewSet 

func (c *Context) NewSet() *Set

NewSet creates a new JavaScript Set object.

func (*Context) NewString 

func (c *Context) NewString(v string) *Value

NewString creates a new JavaScript string value.

func (*Context) NewStringHandle 

func (c *Context) NewStringHandle(v string) *Value

NewStringHandle creates a Value from a string using runtime handle.

func (*Context) NewUint32 

func (c *Context) NewUint32(v uint32) *Value

NewUint32 creates a new JavaScript number from uint32.

func (*Context) NewUndefined 

func (c *Context) NewUndefined() *Value

NewUndefined creates a new undefined JavaScript value.

func (*Context) NewUninitialized 

func (c *Context) NewUninitialized() *Value

NewUninitialized creates a new uninitialized JavaScript value.

func (*Context) NewValue 

func (c *Context) NewValue(handle *Handle) *Value

NewValue creates a new Value wrapper around the given handle.

func (*Context) ParseJSON 

func (c *Context) ParseJSON(v string) *Value

ParseJSON parses given JSON string and returns an object value.

func (*Context) Raw 

func (c *Context) Raw() uint64

Raw returns the raw handle value for low-level operations.

func (*Context) SetAsyncFunc 

func (c *Context) SetAsyncFunc(name string, fn AsyncFunction)

SetAsyncFunc sets an async function with given name in the global object.

func (*Context) SetFunc 

func (c *Context) SetFunc(name string, fn Function)

SetFunc sets a function with given name in the global object.

func (*Context) String 

func (c *Context) String() string

String returns the string representation of the Context.

func (*Context) Throw 

func (c *Context) Throw(v *Value) *Value

Throw throws a value as an exception.

func (*Context) ThrowError 

func (c *Context) ThrowError(err error) *Value

ThrowError throws an exception with the given error.

func (*Context) ThrowInternalError 

func (c *Context) ThrowInternalError(format string, args ...any) *Value

ThrowInternalError throws internal error with given cause.

func (*Context) ThrowRangeError 

func (c *Context) ThrowRangeError(format string, args ...any) *Value

ThrowRangeError throws range error with given cause.

func (*Context) ThrowReferenceError 

func (c *Context) ThrowReferenceError(format string, args ...any) *Value

ThrowReferenceError throws reference error with given cause.

func (*Context) ThrowSyntaxError 

func (c *Context) ThrowSyntaxError(format string, args ...any) *Value

ThrowSyntaxError throws syntax error with given cause.

func (*Context) ThrowTypeError 

func (c *Context) ThrowTypeError(format string, args ...any) *Value

ThrowTypeError throws type error with given cause.

type EvalOption 

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

EvalOption configures JavaScript evaluation behavior in QuickJS context.

func (*EvalOption) Free 

func (o *EvalOption) Free()

Free releases QuickJS value handles to prevent memory leaks. Must be called after Handle() to clean up WASM memory.

func (*EvalOption) Handle 

func (o *EvalOption) Handle() (handle uint64)

Handle creates QuickJS evaluation option handle for WASM function calls.

type EvalOptionFunc 

type EvalOptionFunc func(*EvalOption)

EvalOptionFunc configures evaluation behavior using functional option pattern.

func Bytecode 

func Bytecode(buf []byte) EvalOptionFunc

Bytecode sets precompiled JavaScript bytecode to execute.

func Code 

func Code(code string) EvalOptionFunc

Code sets the JavaScript source code to evaluate.

func FlagAsync 

func FlagAsync() EvalOptionFunc

FlagAsync enables top-level await in global scripts. Returns a promise from JS_Eval(). Only valid with TypeGlobal.

func FlagBacktraceBarrier 

func FlagBacktraceBarrier() EvalOptionFunc

FlagBacktraceBarrier excludes stack frames before this eval from error backtraces.

func FlagCompileOnly 

func FlagCompileOnly() EvalOptionFunc

FlagCompileOnly compiles code without execution. Returns bytecode object for later execution with JS_EvalFunction().

func FlagStrict 

func FlagStrict() EvalOptionFunc

FlagStrict forces strict mode execution.

func FlagUnused 

func FlagUnused() EvalOptionFunc

FlagUnused is reserved for future QuickJS features.

func TypeDirect 

func TypeDirect() EvalOptionFunc

TypeDirect sets direct call mode (internal QuickJS use).

func TypeGlobal 

func TypeGlobal() EvalOptionFunc

TypeGlobal sets evaluation to run in global scope (default behavior).

func TypeIndirect 

func TypeIndirect() EvalOptionFunc

TypeIndirect sets indirect call mode (internal QuickJS use).

func TypeMask 

func TypeMask() EvalOptionFunc

TypeMask applies eval type mask (internal QuickJS use).

func TypeModule 

func TypeModule() EvalOptionFunc

TypeModule sets evaluation to run as ES6 module.

type FieldMapper 

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

FieldMapper handles struct field mapping with caching for performance.

func NewFieldMapper 

func NewFieldMapper() *FieldMapper

NewFieldMapper creates a new field mapper with initialized cache.

func (*FieldMapper) GetFieldMap 

func (fm *FieldMapper) GetFieldMap(structType reflect.Type) map[string]FieldPath

GetFieldMap returns or builds a field map for a struct type.

type FieldPath 

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

FieldPath stores the path to a field through embedded structs.

type Float 

type Float interface {
	~float32 | ~float64
}

type Function 

type Function func(ctx *This) (*Value, error)

type Handle 

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

Handle represents a reference to a QuickJS value. It manages raw pointer values from WebAssembly memory and provides safe type conversion methods with proper resource management.

func NewHandle 

func NewHandle(runtime *Runtime, ptr uint64) *Handle

NewHandle creates a new Handle wrapping the given pointer value. The handle maintains a reference to the runtime for proper memory management.

func (*Handle) Bool 

func (h *Handle) Bool() bool

Bool converts the handle value to bool using zero/non-zero semantics.

func (*Handle) Bytes 

func (h *Handle) Bytes() []byte

Bytes converts the handle value to []byte by reading from QuickJS memory. Returns empty slice for zero handles or if the handle is freed. The returned bytes are a copy and safe to modify.

func (*Handle) Float32 

func (h *Handle) Float32() float32

Float32 converts the handle value to float32 by interpreting the lower 32 bits as IEEE 754 single-precision floating point representation. Returns 0.0 if the handle is nil or freed.

func (*Handle) Float64 

func (h *Handle) Float64() float64

Float64 converts the handle value to float64 by interpreting the raw bits as IEEE 754 double-precision floating point representation. Returns 0.0 if the handle is nil or freed.

func (*Handle) Free 

func (h *Handle) Free()

Free releases the memory associated with this handle. Only used with C values such as: QJS_ToCString, QJS_JSONStringify. Do not use this method for JsValue.

func (*Handle) Int 

func (h *Handle) Int() int

func (*Handle) Int8 

func (h *Handle) Int8() int8

func (*Handle) Int16 

func (h *Handle) Int16() int16

func (*Handle) Int32 

func (h *Handle) Int32() int32

func (*Handle) Int64 

func (h *Handle) Int64() int64

func (*Handle) IsFreed 

func (h *Handle) IsFreed() bool

IsFreed returns true if the handle has been freed.

func (*Handle) Raw 

func (h *Handle) Raw() uint64

Raw returns the underlying raw pointer or 0 if the handle is nil or freed.

func (*Handle) String 

func (h *Handle) String() string

String converts the handle value to string by unpacking a pointer to string data in QuickJS memory. Returns empty string if handle is nil or freed. If there's a JavaScript exception in the context, it will panic with the exception.

func (*Handle) Uint 

func (h *Handle) Uint() uint

func (*Handle) Uint8 

func (h *Handle) Uint8() uint8

func (*Handle) Uint16 

func (h *Handle) Uint16() uint16

func (*Handle) Uint32 

func (h *Handle) Uint32() uint32

func (*Handle) Uint64 

func (h *Handle) Uint64() uint64

func (*Handle) Uintptr 

func (h *Handle) Uintptr() uintptr

type Integer 

type Integer interface {
	Signed | Unsigned
}

type JSAtom 

type JSAtom uint32

type JSPropertyEnum 

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

type JsArrayToGoConverter 

type JsArrayToGoConverter[T any] struct {
	// contains filtered or unexported fields
}

JsArrayToGoConverter handles array conversions with better error handling and performance.

func NewJsArrayToGoConverter 

func NewJsArrayToGoConverter[T any](input *Value, samples ...T) *JsArrayToGoConverter[T]

func (*JsArrayToGoConverter[T]) Convert 

func (ac *JsArrayToGoConverter[T]) Convert() (T, error)

type JsFunctionProxy 

type JsFunctionProxy = func(
	ctx context.Context,
	module api.Module,
	jsCtx uint32,
	thisVal uint64,
	argc uint32,
	argv uint32,
) (rs uint64)

JsFunctionProxy is the Go host function that will be imported by the WASM module. It corresponds to the following C declaration: 

__attribute__((import_module("env"), import_name("jsFunctionProxy")))
extern JSValue jsFunctionProxy(JSContext *ctx, JSValueConst this, int argc, JSValueConst *argv);

Parameters:

  • ctx: JSContext pointer
  • this: JSValueConst this (the "this" value)
  • argc: int argc (number of arguments)
  • argv: pointer to argv (an array of JSValueConst/JSValue, each 8 bytes - uint64)

type JsNumericToGoConverter 

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

JsNumericToGoConverter handles conversion from float64 to various numeric types.

func NewJsNumericToGoConverter 

func NewJsNumericToGoConverter(targetType reflect.Type) *JsNumericToGoConverter

func (*JsNumericToGoConverter) Convert 

func (nc *JsNumericToGoConverter) Convert(floatVal float64) (any, error)

type Map 

type Map struct {
	*Value
}

Map provides a wrapper around JavaScript Map objects with Go-like methods.

func NewMap 

func NewMap(value *Value) *Map

NewMap wraps a JavaScript Map value in a Go Map type.

func (*Map) CreateObject 

func (m *Map) CreateObject() *Value

CreateObject converts the Map to a JavaScript object.

func (*Map) Delete 

func (m *Map) Delete(key *Value)

Delete removes the key-value pair.

func (*Map) ForEach 

func (m *Map) ForEach(forFn func(key, value *Value))

ForEach calls forFn for each key-value pair.

func (*Map) Get 

func (m *Map) Get(key *Value) *Value

Get retrieves the value for the given key.

func (*Map) Has 

func (m *Map) Has(key *Value) bool

Has returns true if the key exists.

func (*Map) IsMap 

func (m *Map) IsMap() bool

IsMap returns true if this is a valid Map. Mainly used to satisfy ObjectOrMap.

func (*Map) IsObject 

func (m *Map) IsObject() bool

IsObject returns true if this is a valid Map, mainly used to satisfy ObjectOrMap.

func (*Map) JSONStringify 

func (m *Map) JSONStringify() (string, error)

JSONStringify returns the JSON representation of the Map as an object.

func (*Map) Set 

func (m *Map) Set(key, value *Value)

Set sets the value for the given key.

func (*Map) ToMap 

func (m *Map) ToMap() *Map

ToMap returns this Map instance, mainly used to satisfy ObjectOrMap.

type Mem 

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

Mem provides a safe interface for WebAssembly memory operations. It wraps the underlying wazero api.Memory with bounds checking and error handling.

func (*Mem) MustRead 

func (m *Mem) MustRead(addr uint32, size uint64) []byte

MustRead is like Read but panics on error.

func (*Mem) MustWrite 

func (m *Mem) MustWrite(addr uint32, b []byte)

MustWrite is like Write but panics on error.

func (*Mem) Read 

func (m *Mem) Read(addr uint32, size uint64) ([]byte, error)

Read extracts bytes from WebAssembly memory at the specified address. Performs comprehensive validation and bounds checking.

func (*Mem) ReadFloat64 

func (m *Mem) ReadFloat64(ptr uint32) (float64, error)

ReadFloat64 reads a 64-bit floating point number from WebAssembly memory at the specified address.

func (*Mem) ReadString 

func (m *Mem) ReadString(addr, maxlen uint32) (string, error)

ReadString reads a null-terminated string from WebAssembly memory starting at the given address. It reads up to maxlen bytes and returns the string without the null terminator.

func (*Mem) ReadUint8 

func (m *Mem) ReadUint8(ptr uint32) (uint8, error)

ReadUint8 reads a single byte from WebAssembly memory at the specified address.

func (*Mem) ReadUint32 

func (m *Mem) ReadUint32(ptr uint32) (uint32, error)

ReadUint32 reads a 32-bit unsigned integer from WebAssembly memory at the specified address.

func (*Mem) ReadUint64 

func (m *Mem) ReadUint64(ptr uint32) (uint64, error)

ReadUint64 reads a 64-bit unsigned integer from WebAssembly memory at the specified address.

func (*Mem) Size 

func (m *Mem) Size() uint32

Size returns the current size of the WebAssembly memory in bytes.

func (*Mem) StringFromPackedPtr 

func (m *Mem) StringFromPackedPtr(ptr uint64) string

StringFromPackedPtr reads a string from a packed pointer containing address and size. Maintains original signature for backward compatibility - panics on error.

func (*Mem) UnpackPtr 

func (m *Mem) UnpackPtr(packedPtr uint64) (uint32, uint32)

UnpackPtr extracts address and size from a packed 64-bit value in memory. It reads 8 bytes from the memory address specified by packedPtr, reconstructs the original uint64 value, and then extracts the 32-bit address from the high bits and the 32-bit size from the low bits.

Maintains original signature for backward compatibility - panics on error.

func (*Mem) Write 

func (m *Mem) Write(addr uint32, b []byte) error

Write copies the contents of byte slice b to WebAssembly memory starting at the given address. Uses Read to validate address and bounds before writing.

func (*Mem) WriteFloat64 

func (m *Mem) WriteFloat64(ptr uint32, v float64) error

WriteFloat64 writes a 64-bit floating point number to WebAssembly memory at the specified address.

func (*Mem) WriteString 

func (m *Mem) WriteString(ptr uint32, s string) error

WriteString writes a null-terminated string to WebAssembly memory. It copies the string content to the specified memory address and appends a null terminator.

func (*Mem) WriteUint8 

func (m *Mem) WriteUint8(ptr uint32, v uint8) error

WriteUint8 writes a single byte to WebAssembly memory at the specified address.

func (*Mem) WriteUint32 

func (m *Mem) WriteUint32(ptr uint32, v uint32) error

WriteUint32 writes a 32-bit unsigned integer to WebAssembly memory at the specified address.

func (*Mem) WriteUint64 

func (m *Mem) WriteUint64(ptr uint32, v uint64) error

WriteUint64 writes a 64-bit unsigned integer to WebAssembly memory at the specified address.

type NumberType 

type NumberType interface {
	int |
		int8 |
		int16 |
		int32 |
		int64 |
		uint |
		uint8 |
		uint16 |
		uint32 |
		uint64 |
		uintptr |
		float32 |
		float64
}

type ObjectOrMap 

type ObjectOrMap interface {
	IsObject() bool
	IsMap() bool
	ToMap() *Map
	JSONStringify() (string, error)
	IsNull() bool
	ForEach(callback func(*Value, *Value))
}

ObjectOrMap interface for unified object/map handling.

type Option 

type Option struct {
	CWD               string
	StartFunctionName string
	Context           context.Context
	// Enabling this option significantly increases evaluation time
	// because every operation must check the done context, which introduces additional overhead.
	CloseOnContextDone bool
	DisableBuildCache  bool
	MemoryLimit        int
	MaxStackSize       int
	MaxExecutionTime   int
	GCThreshold        int
	QuickJSWasmBytes   []byte
	ProxyFunction      any
	Stdout             io.Writer
	Stderr             io.Writer
}

type OwnProperty 

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

func (OwnProperty) String 

func (p OwnProperty) String() string

type Pool 

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

Pool manages a collection of reusable QuickJS runtimes.

func NewPool 

func NewPool(size int, option *Option, setupFuncs ...func(*Runtime) error) *Pool

NewPool creates a new runtime pool with the specified size and configuration.

func (*Pool) Get 

func (p *Pool) Get() (*Runtime, error)

Get returns a runtime from the pool or creates a new one if the pool is empty. The caller must call Put() to return the runtime when finished.

func (*Pool) Put 

func (p *Pool) Put(rt *Runtime)

Put returns the runtime back to the pool for reuse. If the pool is full, the runtime is closed to prevent resource leaks.

type ProxyRegistry 

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

ProxyRegistry stores Go functions that can be called from JavaScript. It provides thread-safe registration and retrieval of functions with automatic ID generation.

func NewProxyRegistry 

func NewProxyRegistry() *ProxyRegistry

NewProxyRegistry creates a new thread-safe proxy registry.

func (*ProxyRegistry) Clear 

func (r *ProxyRegistry) Clear()

Clear removes all registered functions from the registry. This method is thread-safe.

func (*ProxyRegistry) Get 

func (r *ProxyRegistry) Get(id uint64) (any, bool)

Get retrieves a function by its ID. Returns the function and true if found, nil and false otherwise. This method is thread-safe and can be called concurrently.

func (*ProxyRegistry) Len 

func (r *ProxyRegistry) Len() int

Len returns the number of registered functions. This method is thread-safe.

func (*ProxyRegistry) Register 

func (r *ProxyRegistry) Register(fn any) uint64

Register adds a function to the registry and returns its unique ID. This method is thread-safe and can be called concurrently.

func (*ProxyRegistry) Unregister 

func (r *ProxyRegistry) Unregister(id uint64) bool

Unregister removes a function from the registry by its ID. Returns true if the function was found and removed, false otherwise. This method is thread-safe and can be called concurrently.

type Runtime 

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

Runtime wraps a QuickJS WebAssembly runtime with memory management.

func New 

func New(options ...*Option) (runtime *Runtime, err error)

New creates a QuickJS runtime with optional configuration.

func (*Runtime) Call 

func (r *Runtime) Call(name string, args ...uint64) *Handle

Call invokes a WebAssembly function by name with the given arguments.

func (*Runtime) CallUnPack 

func (r *Runtime) CallUnPack(name string, args ...uint64) (uint32, uint32)

CallUnPack calls a WebAssembly function and unpacks the returned pointer.

func (*Runtime) Close 

func (r *Runtime) Close()

Close cleanly shuts down the runtime and frees all associated resources.

func (*Runtime) Compile 

func (r *Runtime) Compile(file string, flags ...EvalOptionFunc) ([]byte, error)

Compile compiles JavaScript code to bytecode without executing it.

func (*Runtime) Context 

func (r *Runtime) Context() *Context

Context returns the JavaScript execution context for this runtime.

func (*Runtime) Eval 

func (r *Runtime) Eval(file string, flags ...EvalOptionFunc) (*Value, error)

Eval executes JavaScript code in the runtime's context.

func (*Runtime) FreeHandle 

func (r *Runtime) FreeHandle(ptr uint64)

FreeHandle releases memory allocated in WebAssembly linear memory.

func (*Runtime) FreeJsValue 

func (r *Runtime) FreeJsValue(val uint64)

FreeJsValue frees a JavaScript value in the QuickJS runtime.

func (*Runtime) FreeQJSRuntime 

func (r *Runtime) FreeQJSRuntime()

FreeQJSRuntime frees the QJS runtime.

func (*Runtime) Load 

func (r *Runtime) Load(file string, flags ...EvalOptionFunc) (*Value, error)

Load executes a JavaScript file in the runtime's context.

func (*Runtime) Malloc 

func (r *Runtime) Malloc(size uint64) uint64

Malloc allocates memory in the WebAssembly linear memory and return a pointer to it.

func (*Runtime) Mem 

func (r *Runtime) Mem() *Mem

Mem returns the WebAssembly memory interface for this runtime.

func (*Runtime) NewBytesHandle 

func (r *Runtime) NewBytesHandle(b []byte) *Handle

NewBytesHandle creates a handle for byte data in WebAssembly memory.

func (*Runtime) NewStringHandle 

func (r *Runtime) NewStringHandle(v string) *Handle

NewStringHandle creates a handle for string data with null termination.

func (*Runtime) String 

func (r *Runtime) String() string

String returns a string representation of the runtime.

type Set 

type Set struct {
	*Value
}

Set provides a wrapper around JavaScript Set objects with Go-like methods.

func NewSet 

func NewSet(value *Value) *Set

NewSet wraps a JavaScript Set value in a Go Set type.

func (*Set) Add 

func (s *Set) Add(value *Value)

Add adds a value to the Set.

func (*Set) Delete 

func (s *Set) Delete(value *Value)

Delete removes the value from the Set.

func (*Set) ForEach 

func (s *Set) ForEach(forFn func(value *Value))

ForEach calls forFn for each value.

func (*Set) Has 

func (s *Set) Has(value *Value) bool

Has returns true if the value exists.

func (*Set) JSONStringify 

func (s *Set) JSONStringify() (string, error)

JSONStringify returns the JSON representation of the Set as an array.

func (*Set) ToArray 

func (s *Set) ToArray() *Array

ToArray converts the Set to an Array.

type Signed 

type Signed interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64
}

Signed integer conversion methods with bounds checking.

type This 

type This struct {
	*Value
	// contains filtered or unexported fields
}

func (*This) Args 

func (t *This) Args() []*Value

func (*This) Context 

func (t *This) Context() *Context

func (*This) IsAsync 

func (t *This) IsAsync() bool

func (*This) Promise 

func (t *This) Promise() *Value

type Tracker 

type Tracker[T uintptr | uint64] struct {
	// contains filtered or unexported fields
}

Tracker tracks objects during Go-JS conversion to detect circular references.

func NewTracker 

func NewTracker[T uintptr | uint64]() *Tracker[T]

NewTracker creates a new conversion context for tracking circular references.

func (*Tracker[T]) ArrayToArrayValue 

func (tracker *Tracker[T]) ArrayToArrayValue(c *Context, rval reflect.Value) (*Value, error)

ArrayToArrayValue converts a Go array to a JavaScript array without unnecessary copying.

func (*Tracker[T]) MapToObjectValue 

func (tracker *Tracker[T]) MapToObjectValue(
	c *Context,
	rval reflect.Value,
) (*Value, error)

MapToObjectValue converts a Go map to a JavaScript object. Non-string keys are converted to string representation.

func (*Tracker[T]) SliceToArrayValue 

func (tracker *Tracker[T]) SliceToArrayValue(c *Context, rval reflect.Value) (*Value, error)

SliceToArrayValue converts a Go slice to a JavaScript array.

func (*Tracker[T]) StructToJSObjectValue 

func (tracker *Tracker[T]) StructToJSObjectValue(
	c *Context,
	rtype reflect.Type,
	rval reflect.Value,
) (*Value, error)

StructToJSObjectValue converts a Go struct to a JavaScript object. Includes both fields and methods as object properties.

func (*Tracker[T]) ToJSValue 

func (tracker *Tracker[T]) ToJSValue(c *Context, v any) (*Value, error)

ToJSValue converts any Go value to a QuickJS Value using the conversion context.

func (*Tracker[T]) Track 

func (tracker *Tracker[T]) Track(ptr T) bool

Track registers an object for circular reference detection. Returns true if the object is already being processed (circular reference detected).

func (*Tracker[T]) UnTrack 

func (tracker *Tracker[T]) UnTrack(ptr T)

UnTrack removes an object from circular reference tracking.

type Unsigned 

type Unsigned interface {
	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr
}

type Value 

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

func ChannelToJSObjectValue 

func ChannelToJSObjectValue(
	c *Context,
	rtype reflect.Type,
	rval reflect.Value,
) (*Value, error)

ChannelToJSObjectValue converts a Go channel to a JavaScript object with async methods.

func FuncToJS 

func FuncToJS(c *Context, v any) (_ *Value, err error)

FuncToJS converts a Go function to a JavaScript function.

func GoComplexToJS 

func GoComplexToJS[T complex64 | complex128](c *Context, z T) *Value

GoComplexToJS converts Go complex numbers to JS objects with real/imag properties.

func GoFuncResultToJs 

func GoFuncResultToJs(c *Context, results []reflect.Value) (*Value, error)

GoFuncResultToJs processes Go function call results and converts them to JS values. If last return value is a non-nil error, it's thrown in JS context. The remaining return values are converted to JS value or JS array if there are multiple.

func GoNumberToJS 

func GoNumberToJS[T NumberType](c *Context, i T) *Value

GoNumberToJS converts Go numeric types to appropriate JS number types.

func MapToObjectValue 

func MapToObjectValue(c *Context, rval reflect.Value) (*Value, error)

MapToObjectValue provides backward compatibility for the old API.

func SliceToArrayValue 

func SliceToArrayValue(c *Context, rval reflect.Value) (*Value, error)

SliceToArrayValue provides backward compatibility for the old API.

func StructToJSObjectValue 

func StructToJSObjectValue(
	c *Context,
	rtype reflect.Type,
	rval reflect.Value,
) (*Value, error)

StructToJSObjectValue provides backward compatibility for the old API.

func ToJSValue 

func ToJSValue(c *Context, v any) (*Value, error)

ToJSValue converts any Go value to a QuickJS value.

func (*Value) Await 

func (v *Value) Await() (*Value, error)

func (*Value) BigInt 

func (v *Value) BigInt() *big.Int

BigInt returns the big.Int value of the value.

func (*Value) Bool 

func (v *Value) Bool() bool

Bool returns the boolean value of the value.

func (*Value) ByteLen 

func (v *Value) ByteLen() int64

ByteLen returns the length of the ArrayBuffer.

func (*Value) Bytes 

func (v *Value) Bytes() []byte

func (*Value) Call 

func (v *Value) Call(name string, args ...uint64) *Value

func (*Value) CallConstructor 

func (v *Value) CallConstructor(args ...*Value) *Value

CallConstructor calls the constructor with the given arguments.

func (*Value) Clone 

func (v *Value) Clone() *Value

func (*Value) Context 

func (v *Value) Context() *Context

func (*Value) Ctx 

func (v *Value) Ctx() uint64

func (*Value) DateTime 

func (v *Value) DateTime(tzs ...string) *time.Time

DateTime returns the date value of the value.

func (*Value) DeleteProperty 

func (v *Value) DeleteProperty(name string) bool

DeleteProperty deletes the property with the given name.

func (*Value) Exception 

func (v *Value) Exception() error

func (*Value) Float64 

func (v *Value) Float64() float64

Float64 returns the float64 value of the value.

func (*Value) ForEach 

func (v *Value) ForEach(fn func(key *Value, value *Value))

ForEach iterates over the properties of the object and calls the given function for each property.

func (*Value) Free 

func (v *Value) Free()

func (*Value) GetOwnProperties 

func (v *Value) GetOwnProperties() []OwnProperty

func (*Value) GetOwnPropertyNames 

func (v *Value) GetOwnPropertyNames() (_ []string, err error)

GetOwnPropertyNames returns the names of the properties of the value.

func (*Value) GetProperty 

func (v *Value) GetProperty(name *Value) *Value

func (*Value) GetPropertyIndex 

func (v *Value) GetPropertyIndex(index int64) *Value

GetPropertyIndex returns the value of the property with the given index.

func (*Value) GetPropertyStr 

func (v *Value) GetPropertyStr(name string) *Value

GetPropertyStr returns the value of the property with the given name.

func (*Value) Handle 

func (v *Value) Handle() *Handle

func (*Value) HasProperty 

func (v *Value) HasProperty(name string) bool

HasProperty returns true if the value has the property with the given name.

func (*Value) HasPropertyIndex 

func (v *Value) HasPropertyIndex(index int64) bool

HasPropertyIndex returns true if the value has the property with the given index.

func (*Value) Int32 

func (v *Value) Int32() int32

Int32 returns the int32 value of the value. in c int is 32 bit, but in go it is depends on the architecture.

func (*Value) Int64 

func (v *Value) Int64() int64

func (*Value) Invoke 

func (v *Value) Invoke(fname string, args ...any) (_ *Value, err error)

Invoke call the object's method with the given name and arguments.

func (*Value) InvokeJS 

func (v *Value) InvokeJS(fname string, args ...*Value) (*Value, error)

InvokeJS call the object's method with the given name and JS arguments.

func (*Value) IsArray 

func (v *Value) IsArray() bool

func (*Value) IsBigInt 

func (v *Value) IsBigInt() bool

func (*Value) IsBool 

func (v *Value) IsBool() bool

func (*Value) IsByteArray 

func (v *Value) IsByteArray() bool

IsByteArray return true if the value is array buffer.

func (*Value) IsConstructor 

func (v *Value) IsConstructor() bool

func (*Value) IsDate 

func (v *Value) IsDate() bool

func (*Value) IsError 

func (v *Value) IsError() bool

func (*Value) IsFunction 

func (v *Value) IsFunction() bool

func (*Value) IsGlobalInstanceOf 

func (v *Value) IsGlobalInstanceOf(name string) bool

IsGlobalInstanceOf checks if the value is an instance of the given global constructor.

func (*Value) IsInfinity 

func (v *Value) IsInfinity() bool

func (*Value) IsMap 

func (v *Value) IsMap() bool

func (*Value) IsNaN 

func (v *Value) IsNaN() bool

func (*Value) IsNull 

func (v *Value) IsNull() bool

func (*Value) IsNumber 

func (v *Value) IsNumber() bool

func (*Value) IsObject 

func (v *Value) IsObject() bool

func (*Value) IsPromise 

func (v *Value) IsPromise() bool

func (*Value) IsQJSProxyValue 

func (v *Value) IsQJSProxyValue() bool

func (*Value) IsSet 

func (v *Value) IsSet() bool

func (*Value) IsString 

func (v *Value) IsString() bool

func (*Value) IsSymbol 

func (v *Value) IsSymbol() bool

func (*Value) IsUndefined 

func (v *Value) IsUndefined() bool

func (*Value) IsUninitialized 

func (v *Value) IsUninitialized() bool

func (*Value) JSONStringify 

func (v *Value) JSONStringify() (_ string, err error)

JSONStringify returns the JSON string representation of the value.

func (*Value) Len 

func (v *Value) Len() int64

Len returns the length of the array.

func (*Value) New 

func (v *Value) New(args ...*Value) *Value

New creates a new instance of the value as a constructor with the given arguments.

func (*Value) NewUndefined 

func (v *Value) NewUndefined() *Value

func (*Value) Object 

func (v *Value) Object() *Value

Object returns the object value of the value.

func (*Value) Raw 

func (v *Value) Raw() uint64

func (*Value) Reject 

func (v *Value) Reject(args ...*Value) error

Reject rejects a promise with the given arguments. This method is intended for use with Go function bindings (this.Promise() in async Go functions). It will NOT work with native JavaScript promises created via "new Promise()". For native JS promises, use direct function calls or Promise.withResolvers instead.

func (*Value) Resolve 

func (v *Value) Resolve(args ...*Value) error

Resolve resolves a promise with the given arguments. This method is intended for use with Go function bindings (this.Promise() in async Go functions). It will NOT work with native JavaScript promises created via "new Promise()". For native JS promises, use direct function calls or Promise.withResolvers instead.

func (*Value) SetProperty 

func (v *Value) SetProperty(name, val *Value)

func (*Value) SetPropertyIndex 

func (v *Value) SetPropertyIndex(index int64, val *Value)

SetPropertyIndex sets the value of the property with the given index.

func (*Value) SetPropertyStr 

func (v *Value) SetPropertyStr(name string, val *Value)

SetPropertyStr sets the value of the property with the given name.

func (*Value) String 

func (v *Value) String() string

func (*Value) ToArray 

func (v *Value) ToArray() (*Array, error)

ToArray returns the array value of the value. DO NOT FREE.

func (*Value) ToByteArray 

func (v *Value) ToByteArray() []byte

ToByteArray returns the byte array of the ArrayBuffer.

func (*Value) ToMap 

func (v *Value) ToMap() *Map

ToMap returns the map value of the value. DO NOT FREE.

func (*Value) ToSet 

func (v *Value) ToSet() *Set

ToSet returns the set value of the value. DO NOT FREE.

func (*Value) Type 

func (v *Value) Type() string

func (*Value) Uint32 

func (v *Value) Uint32() uint32

Uint32 returns the uint32 value of the value.

Source Files

View all Source files

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.