diff --git a/plans/BUILTIN.md b/plans/BUILTIN.md new file mode 100644 index 0000000..3fca068 --- /dev/null +++ b/plans/BUILTIN.md @@ -0,0 +1,68 @@ +# JS Framework + +## Core Interfaces + +### JSValue + +Base interface for any JavaScript value. Provides type-safe access to underlying values. + +```go +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. + +```go +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 + +```go +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.