poiesis/plans/BUILTIN.md

JS Framework

Core Interfaces

JSValue

Base interface for any JavaScript value. Provides type-safe access to underlying values.

package jsframe

import "reflect"

type JSValue interface {
    GoType() reflect.Type
    GoValue() reflect.Value

    SliceValues() ([]JSValue, bool)
    MapValues() (map[string]JSValue, bool)
}

Methods:

• GoType() - Returns the Go reflect.Type of the underlying value
• GoValue() - Returns the underlying Go value
• SliceValues() - Returns (values, true) if the value is a slice/array, (nil, false) otherwise
• MapValues() - Returns (values, true) if the value is an object/map, (nil, false) otherwise

---

JSCallable

Interface for callable values (functions). Extends JSValue by adding call semantics and type information.

type JSCallable interface {
    JSValue

    ArgumentTypes() []TypeInfo
    ReturnType() TypeInfo

    Call(ctx Context, args ...JSValue) (JSValue, error)
}

Methods:

• Call(ctx, args) - Executes the function with provided arguments. Returns a JSValue and an error. The framework converts errors to JavaScript exceptions.
• ArgumentTypes() - Returns type information for each argument
• ReturnType() - Returns type information for the return value

Callable / Builtin Registrar

type BuiltinFunc[T any, R any] func(args T) (R, error)

type BuiltinArgs[T any] interface {
    T
    Defaults() T
}

func RegisterBuiltin[T any, R any](name string, fn BuiltinFunc[T, R]) JSCallable

Goja Types <-> Go Types Converstion

Implement bidirectional conversion between goja values and go values.