wip

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.