Conformance fixes and performance optimizations (#13)

* Fix signature validation for variadic, optional-skip, context, and u-type

Addresses four conformance gaps in function signature validation
against the JSONata spec:

- Variadic overflow: cap consumption to leave room for mandatory
  params that follow, preventing spurious T0410 "too few arguments"
  errors when a trailing fixed param is present after a variadic.
- Optional-skip: when an optional param's type doesn't match, skip
  the spec and retry the same arg against the next spec instead of
  raising T0410.
- '-' (context) modifier: inject the current focus value when the
  argument is absent. Adds Context field to ParamSpec and threads
  focus through processCallArgs / validateCallArgs.
- 'u' type specifier (union of primitives: bool, number, string,
  null). Recognised by both the parser and evaluator.

Adds test cases 035-040 covering each scenario end-to-end.

* Return T0410 from $split on non-string input

$split previously returned nil (undefined) for non-string arguments,
which matched the jsonata-js reference implementation but diverged
from the JSONata spec, which prescribes a T0410 type error.

Align with the spec by returning T0410 for non-string args, and
update case016/case017 to expect the error code instead of an
undefined result.

* Sort raw map keys for deterministic iteration

When a Go native map[string]any enters the evaluator (via DecodeRawMap
or MapKeys/MapRange in paths that walk raw maps), iteration order was
Go-randomised, which leaked into ordering-sensitive operations like
$keys, $lookup fallbacks, and aggregate results.

Sort keys alphabetically using slices.Sorted(maps.Keys(m)) before
iteration so identical inputs produce identical outputs across runs.

* Pre-parse function signatures at registration

Signature strings were re-parsed on every SignedBuiltin / Lambda call
via parser.ParseSig, which is pure overhead since the string never
changes after the function is defined.

Parse once and cache:

- Add ParsedSig []parser.ParamSpec to SignedBuiltin and Lambda.
- Introduce a newSignedBuiltin helper in functions/register.go that
  parses at construction time; use it for signature-carrying
  registrations.
- Populate Lambda.ParsedSig once in evalLambda when the signature is
  compiled from the AST.
- Replace the per-call parser.ParseSig() lookups in evalFunction and
  callFunction with direct reads of the cached ParsedSig slice.

Hot-path-only change; no behavioural difference.

* Optimize eval hot paths: float arith, DeepEqual, HOF buffers

Five targeted hot-path optimisations in the evaluator and function
dispatch layer:

- Arithmetic fast-path (eval_binary.go): when both operands are
  already float64, bypass the generic numeric-coercion path and go
  straight to evalArithFloat64. This is the common case for numeric
  expressions after AST evaluation.

- DeepEqual primitive fast-path (value.go): for same-type float64 /
  string / bool comparisons, skip normalizeNumber and compare
  directly. Drops a per-call allocation that showed up in profiles
  on equality-heavy expressions.

- Sequence collapse (value.go): use slices.Clip in CollapseSequence
  and CollapseToSlice instead of slices.Clone. Since the sequence is
  being discarded, we can transfer ownership of the backing array
  rather than allocating a copy.

- HOF argument buffers (hof_funcs.go, object_funcs.go): replace the
  per-iteration hofArgs slice with reusable hofArity / hofArgsBuf /
  fillHofArgs helpers applied to $map, $filter, $single, $reduce,
  $sift, and $each. Same arity detection, zero per-iteration
  allocation.

- Sort comparator args (array_funcs.go): pre-allocate the 2-element
  sortArgs slice once per $sort call instead of rebuilding it on
  each comparator invocation.

No behavioural changes; all existing tests pass.

* Add EvalMap, EvalBytesWithVars; expose via WASM; fix gjson docs

Extends the public Expression API and the WASM bridge with two
evaluation paths that were previously only reachable from the
StreamEvaluator or the byte-level API, and cleans up the docs to
match how gjson is actually used.

Expression API (gnata.go):

- EvalMap(ctx, data map[string]json.RawMessage): O(1) top-level key
  lookup via DecodeRawMap, with gjson fast paths for nested access
  inside each RawMessage. Useful when the caller already has the
  JSON decoded into a map and wants to avoid re-serialising.
- EvalBytesWithVars(ctx, data json.RawMessage, vars map[string]any):
  evaluate raw JSON bytes with external $-variable bindings, while
  keeping the gjson fast-path eligible.

WASM bridge (wasm/main.go, playground.html):

- Export two new JS functions, gnataEvalMap and gnataEvalWithVars,
  mirroring the new Expression methods. gnataEvalMap takes a JS
  object and feeds its top-level keys as json.RawMessage values;
  gnataEvalWithVars takes a vars JSON blob for $-bindings.
- Route gnataEval and gnataEvalHandle through EvalBytes so they
  also benefit from the gjson fast path.
- Add JS wrappers in playground.html so the new exports are usable
  from the browser playground.

Documentation (README.md, AGENTS.md):

- Fix the StreamEvaluator description: the hot path uses
  gjson.GetBytes per fast-path expression, not a single
  gjson.GetManyBytes call for the whole event.
- Update the public-API list in README to include EvalMap and
  EvalBytesWithVars, and expand the WASM section with a table of
  all six exported JS functions.

Author: NirBarak-RecoLabs

AGENTS.md

@@ -43,7 +43,7 @@ Lexer → Parser → AST Processing → Fast-Path Analysis → Expression
 
 ### StreamEvaluator (stream.go)
 
-Batch-evaluates multiple expressions against events. Schema-keyed `GroupPlan` caching deduplicates field extraction across expressions. Lock-free reads via `atomic.Pointer` snapshot; writes serialized by `sync.Mutex`. Single JSON scan per event via `gjson.GetManyBytes`.
+Batch-evaluates multiple expressions against events. Schema-keyed `GroupPlan` caching classifies expressions into fast-path vs full-eval at plan-build time. Lock-free reads via `atomic.Pointer` snapshot; writes serialized by `sync.Mutex`. Fast-path expressions use `gjson.GetBytes` for zero-copy field extraction.
 
 ### Evaluator Dispatch (internal/evaluator/)
 
@@ -97,4 +97,4 @@ se := gnata.NewStreamEvaluator(nil, gnata.WithCustomFunctions(customFuncs))
 
 ## WASM
 
-`wasm/main.go` exports `gnataEval`, `gnataCompile`, `gnataEvalHandle` for browser use. Build with `GOOS=js GOARCH=wasm go build -ldflags="-s -w" -trimpath -o gnata.wasm ./wasm/`.
+`wasm/main.go` exports six JS functions: `gnataEval`, `gnataCompile`, `gnataEvalHandle`, `gnataReleaseHandle`, `gnataEvalMap` (O(1) top-level key lookup via `EvalMap`), and `gnataEvalWithVars` (external `$`-variable bindings). `gnataEval` and `gnataEvalHandle` use `EvalBytes`; `gnataEvalMap` uses `EvalMap`; `gnataEvalWithVars` uses `EvalBytesWithVars`. All paths leverage gjson fast-path access where applicable. Build with `GOOS=js GOARCH=wasm go build -ldflags="-s -w" -trimpath -o gnata.wasm ./wasm/`.

README.md

@@ -148,15 +148,15 @@ Hot Path (millions/day, lock-free)
     ├── BoundedCache lookup (atomic pointer read)
     │   ├── HIT  ──> Immutable GroupPlan
     │   └── MISS ──> Build plan (merge GJSON paths, atomic CAS store)
-    ├── gjson.GetManyBytes: SINGLE scan for ALL expressions
+    ├── gjson.GetBytes per fast-path expression
     ├── Fast-path expressions: distribute extracted results (0 allocs)
     ├── Full-path expressions: selective unmarshal + AST eval
     └── results[]
 ```
 
 ### Key Properties
 
-- **One JSON scan per event** — all field paths needed by all expressions are merged into a single `gjson.GetManyBytes` call.
+- **Efficient JSON field extraction** — fast-path expressions use `gjson.GetBytes` for zero-copy path lookups directly on raw JSON bytes.
 - **Schema-keyed caching** — the `GroupPlan` (merged paths, expression groupings, selective unmarshal targets) is computed once per schema key and reused immutably.
 - **Lock-free reads** — `BoundedCache` publishes an `atomic.Pointer` snapshot on every write; reads scan the snapshot without acquiring a lock. Writes are serialised by a mutex.
 - **Selective unmarshal** — full-path expressions unmarshal only the subtrees they need (e.g., just the `items` array from a 10KB event), not the entire document.
@@ -421,7 +421,7 @@ All standard regex features (character classes, quantifiers, alternation, groupi
 
 ```
 gnata/
-├── gnata.go                     # Public API: Compile, Eval, EvalBytes, EvalWithVars, CustomFunc
+├── gnata.go                     # Public API: Compile, Eval, EvalBytes, EvalBytesWithVars, EvalMap, EvalWithVars, CustomFunc
 ├── stream.go                    # StreamEvaluator, GroupPlan, EvalMany, EvalMap, MetricsHook
 ├── bounded_cache.go             # Lock-free FIFO ring-buffer plan cache
 ├── deep_equal.go                # JSONata-compatible deep equality
@@ -485,7 +485,18 @@ python3 -m http.server 8899
 caddy file-server --root . --listen :8899
 ```
 
-The WASM build exposes `gnataEval`, `gnataCompile`, and `gnataEvalHandle` functions for use from JavaScript, with a compiled-expression cache for repeated evaluations. A ready-made `playground.html` is included — build the WASM binary, copy the Go WASM support file, and serve the directory:
+The WASM build exposes six functions for use from JavaScript (the raw exports are underscore-prefixed; `playground.html` wraps them into clean public names):
+
+| Function | Description |
+|---|---|
+| `gnataEval(expr, jsonData)` | One-shot compile + evaluate (expressions are cached). |
+| `gnataCompile(expr)` | Compile an expression and return a numeric handle. |
+| `gnataEvalHandle(handle, jsonData)` | Evaluate a compiled handle against JSON data. Uses `EvalBytes` internally for gjson fast-path access. |
+| `gnataReleaseHandle(handle)` | Free a compiled handle. |
+| `gnataEvalMap(handle, jsonObject)` | Evaluate a compiled handle using `EvalMap` — O(1) top-level key lookup with gjson fast paths for nested access. Ideal for pre-destructured data. |
+| `gnataEvalWithVars(handle, jsonData, varsJson)` | Evaluate with external `$`-variable bindings (e.g. `{"$threshold": 100}`). |
+
+A ready-made `playground.html` is included — build the WASM binary, copy the Go WASM support file, and serve the directory:
 
 ```bash
 cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" .

functions/array_funcs.go

@@ -129,8 +129,11 @@ func makeFnSort(evalFn EvalFn) evaluator.EnvAwareBuiltin {
 			// JSONata $sort comparator: fn(a, b) returns true when a should come
 			// before b. We call fn(b, a) and map true→-1 (a<b), false→0 (a>=b).
 			// SortItemsErr only tests < 0, so +1 is unnecessary.
+			sortArgs := make([]any, 2)
 			cmpFn = func(a, b any) (int, error) {
-				result, err := evalFn(fn, []any{b, a}, focus, env)
+				sortArgs[0] = b
+				sortArgs[1] = a
+				result, err := evalFn(fn, sortArgs, focus, env)
 				if err != nil {
 					return 0, err
 				}

functions/hof_funcs.go

@@ -9,25 +9,42 @@ import (
 	"github.com/recolabs/gnata/internal/parser"
 )
 
-// hofArgs trims the HOF callback argument list to the function's expected arity.
-// For lambdas, use the declared parameter count.
-// For built-in functions, default to 1 (value only) since they have their own
-// argument validation and may reject unexpected extra args.
-func hofArgs(fn, value, index any, arr []any) []any {
+// hofArity returns the callback argument count for the given HOF function.
+// For lambdas, uses the declared parameter count (capped at 3).
+// For built-in functions, defaults to 1 (value only).
+func hofArity(fn any) int {
 	if lambda, ok := fn.(*evaluator.Lambda); ok {
-		switch len(lambda.Params) {
-		case 0:
-			return []any{}
-		case 1:
-			return []any{value}
-		case 2:
-			return []any{value, index}
-		default:
-			return []any{value, index, arr}
+		n := len(lambda.Params)
+		if n > 3 {
+			return 3
 		}
+		return n
+	}
+	return 1
+}
+
+// hofArgsBuf allocates a reusable buffer for HOF callback arguments.
+func hofArgsBuf(arity int) []any {
+	if arity == 0 {
+		return nil
+	}
+	return make([]any, arity)
+}
+
+// fillHofArgs populates a pre-allocated argument buffer for a HOF callback.
+func fillHofArgs(buf []any, value, index any, arr []any) {
+	switch len(buf) {
+	case 0:
+	case 1:
+		buf[0] = value
+	case 2:
+		buf[0] = value
+		buf[1] = index
+	default:
+		buf[0] = value
+		buf[1] = index
+		buf[2] = arr
 	}
-	// For built-in functions pass (value) only to avoid arity rejections.
-	return []any{value}
 }
 
 // ── $map ──────────────────────────────────────────────────────────────────────
@@ -56,8 +73,9 @@ func makeFnMap(evalFn EvalFn) evaluator.EnvAwareBuiltin {
 
 		seq := evaluator.CreateSequence()
 		arrAny := slices.Clone(arr)
+		callArgs := hofArgsBuf(hofArity(fn))
 		for i, item := range arr {
-			callArgs := hofArgs(fn, item, float64(i), arrAny)
+			fillHofArgs(callArgs, item, float64(i), arrAny)
 			val, err := evalFn(fn, callArgs, focus, env)
 			if err != nil {
 				return nil, err
@@ -94,8 +112,9 @@ func makeFnFilter(evalFn EvalFn) evaluator.EnvAwareBuiltin {
 
 		seq := evaluator.CreateSequence()
 		arrAny := slices.Clone(arr)
+		callArgs := hofArgsBuf(hofArity(fn))
 		for i, item := range arr {
-			callArgs := hofArgs(fn, item, float64(i), arrAny)
+			fillHofArgs(callArgs, item, float64(i), arrAny)
 			val, err := evalFn(fn, callArgs, focus, env)
 			if err != nil {
 				return nil, err
@@ -151,8 +170,9 @@ func makeFnSingle(evalFn EvalFn) evaluator.EnvAwareBuiltin {
 		fn := args[1]
 		var matched []any
 		arrAny := slices.Clone(arr)
+		callArgs := hofArgsBuf(hofArity(fn))
 		for i, item := range arr {
-			callArgs := hofArgs(fn, item, float64(i), arrAny)
+			fillHofArgs(callArgs, item, float64(i), arrAny)
 			val, err := evalFn(fn, callArgs, focus, env)
 			if err != nil {
 				return nil, err
@@ -218,21 +238,23 @@ func makeFnReduce(evalFn EvalFn) evaluator.EnvAwareBuiltin {
 		}
 
 		arrAny := slices.Clone(arr)
+		var reduceArity int
+		if lambda, ok := fn.(*evaluator.Lambda); ok {
+			reduceArity = max(min(len(lambda.Params), 4), 1)
+		} else {
+			reduceArity = 2
+		}
+		callArgs := make([]any, reduceArity)
 		for i := startIdx; i < len(arr); i++ {
-			var callArgs []any
-			if lambda, ok := fn.(*evaluator.Lambda); ok {
-				switch len(lambda.Params) {
-				case 0, 1:
-					callArgs = []any{acc}
-				case 2:
-					callArgs = []any{acc, arr[i]}
-				case 3:
-					callArgs = []any{acc, arr[i], float64(i)}
-				default:
-					callArgs = []any{acc, arr[i], float64(i), arrAny}
-				}
-			} else {
-				callArgs = []any{acc, arr[i]}
+			callArgs[0] = acc
+			if reduceArity > 1 {
+				callArgs[1] = arr[i]
+			}
+			if reduceArity > 2 {
+				callArgs[2] = float64(i)
+			}
+			if reduceArity > 3 {
+				callArgs[3] = arrAny
 			}
 			val, err := evalFn(fn, callArgs, focus, env)
 			if err != nil {

functions/object_funcs.go

@@ -158,20 +158,19 @@ func fnMerge(args []any, _ any) (any, error) {
 	return result, nil
 }
 
-func siftArgs(fn, value any, key string, obj any) []any {
-	if lambda, ok := fn.(*evaluator.Lambda); ok {
-		switch len(lambda.Params) {
-		case 0:
-			return []any{}
-		case 1:
-			return []any{value}
-		case 2:
-			return []any{value, key}
-		default:
-			return []any{value, key, obj}
-		}
+func fillSiftArgs(buf []any, value any, key string, obj any) {
+	switch len(buf) {
+	case 0:
+	case 1:
+		buf[0] = value
+	case 2:
+		buf[0] = value
+		buf[1] = key
+	default:
+		buf[0] = value
+		buf[1] = key
+		buf[2] = obj
 	}
-	return []any{value}
 }
 
 // ── $sift ─────────────────────────────────────────────────────────────────────
@@ -199,9 +198,10 @@ func makeFnSift(evalFn EvalFn) evaluator.EnvAwareBuiltin {
 
 		result := evaluator.NewOrderedMap()
 		keys := evaluator.MapKeys(objVal)
+		callArgs := hofArgsBuf(hofArity(fn))
 		for _, ks := range keys {
 			val, _ := evaluator.MapGet(objVal, ks)
-			callArgs := siftArgs(fn, val, ks, objVal)
+			fillSiftArgs(callArgs, val, ks, objVal)
 			res, err := evalFn(fn, callArgs, focus, env)
 			if err != nil {
 				return nil, err
@@ -242,9 +242,11 @@ func makeFnEach(evalFn EvalFn) evaluator.EnvAwareBuiltin {
 
 		keys := evaluator.MapKeys(objVal)
 		seq := evaluator.CreateSequence()
+		callArgs := hofArgsBuf(max(hofArity(fn), 2))
 		for _, ks := range keys {
 			val, _ := evaluator.MapGet(objVal, ks)
-			res, err := evalFn(fn, []any{val, ks}, focus, env)
+			fillSiftArgs(callArgs, val, ks, objVal)
+			res, err := evalFn(fn, callArgs, focus, env)
 			if err != nil {
 				return nil, err
 			}

functions/register.go

@@ -1,7 +1,10 @@
 // Package functions implements the JSONata 2.x standard library.
 package functions
 
-import "github.com/recolabs/gnata/internal/evaluator"
+import (
+	"github.com/recolabs/gnata/internal/evaluator"
+	"github.com/recolabs/gnata/internal/parser"
+)
 
 // EvalFn is a callback used by higher-order functions to invoke a lambda or
 // builtin function value without creating an import cycle. The env parameter
@@ -77,14 +80,19 @@ var builtinFuncs = []struct {
 	{"toMillis", fnToMillis},
 }
 
+func newSignedBuiltin(fn func([]any, any) (any, error), sig string) *evaluator.SignedBuiltin {
+	parsed, _ := parser.ParseSig(sig)
+	return &evaluator.SignedBuiltin{Fn: fn, Sig: sig, ParsedSig: parsed}
+}
+
 // RegisterAll binds every JSONata built-in function into env.
 // evalFn must call evaluator.ApplyFunction (supplied by gnata.go).
 func RegisterAll(env *evaluator.Environment, evalFn EvalFn) {
 	for _, b := range builtinFuncs {
 		env.Bind(b.name, evaluator.BuiltinFunction(b.fn))
 	}
-	env.Bind("uppercase", &evaluator.SignedBuiltin{Fn: fnUppercase, Sig: "s-:s"})
-	env.Bind("lowercase", &evaluator.SignedBuiltin{Fn: fnLowercase, Sig: "s-:s"})
+	env.Bind("uppercase", newSignedBuiltin(fnUppercase, "s-:s"))
+	env.Bind("lowercase", newSignedBuiltin(fnLowercase, "s-:s"))
 	env.Bind("match", makeFnMatch(evalFn))
 	env.Bind("replace", makeFnReplace(evalFn))
 	env.Bind("eval", makeFnEval())

functions/string_funcs.go

@@ -424,7 +424,7 @@ func fnSplit(args []any, _ any) (any, error) {
 	}
 	s, ok := args[0].(string)
 	if !ok {
-		return nil, nil
+		return nil, &evaluator.JSONataError{Code: "T0410", Message: fmt.Sprintf("$split: argument 1 must be a string, got %T", args[0])}
 	}
 	if len(args) < 2 {
 		return nil, &evaluator.JSONataError{Code: "D3006", Message: "$split: requires at least 2 arguments"}

gnata.go

@@ -223,6 +223,62 @@ func (e *Expression) EvalBytes(ctx context.Context, data json.RawMessage) (resul
 	return e.Eval(ctx, v)
 }
 
+// EvalMap evaluates the expression against a map of field names to raw JSON values.
+// This enables O(1) top-level key lookup with gjson fast paths for nested access,
+// making it ideal for pre-destructured data (e.g. database columns, form fields).
+func (e *Expression) EvalMap(ctx context.Context, data map[string]json.RawMessage) (result any, err error) {
+	defer recoverEvalPanic(&err)
+	if e.fastPath && len(e.paths) == 1 {
+		if res := resolveGjsonPath(nil, data, e.paths[0]); res.Exists() {
+			return gjsonValueToAny(&res), nil
+		}
+	}
+	if e.cmpFast != nil {
+		if res, handled, evalErr := evalComparison(e.cmpFast, nil, data); handled || evalErr != nil {
+			return res, evalErr
+		}
+	}
+	if e.funcFast != nil {
+		if res, handled, evalErr := evalFunc(e.funcFast, nil, data); handled || evalErr != nil {
+			return res, evalErr
+		}
+	}
+	v, err := evaluator.DecodeRawMap(data)
+	if err != nil {
+		return nil, err
+	}
+	return e.Eval(ctx, v)
+}
+
+// EvalBytesWithVars evaluates the expression against raw JSON bytes with extra
+// variable bindings. Combines the gjson fast-path cascade from EvalBytes with
+// the variable support from EvalWithVars. Fast-path expressions never reference
+// $variables (excluded at compile time), so the fast-path result is independent
+// of the variable map; only the full-eval fallback uses vars.
+func (e *Expression) EvalBytesWithVars(ctx context.Context, data json.RawMessage, vars map[string]any) (result any, err error) {
+	defer recoverEvalPanic(&err)
+	if e.fastPath && len(e.paths) == 1 {
+		if res := gjson.GetBytes(data, e.paths[0]); res.Exists() {
+			return gjsonValueToAny(&res), nil
+		}
+	}
+	if e.cmpFast != nil {
+		if res, handled, evalErr := evalComparison(e.cmpFast, data, nil); handled || evalErr != nil {
+			return res, evalErr
+		}
+	}
+	if e.funcFast != nil {
+		if res, handled, evalErr := evalFunc(e.funcFast, data, nil); handled || evalErr != nil {
+			return res, evalErr
+		}
+	}
+	v, err := evaluator.DecodeJSON(data)
+	if err != nil {
+		return nil, err
+	}
+	return e.evalCore(ctx, v, builtinEnv, vars)
+}
+
 // resolveGjsonPath resolves a gjson path from either raw bytes or a pre-decoded map.
 // When data is available (EvalMany), it delegates to gjson.GetBytes on the full blob.
 // When mapData is available (EvalMap), it does an O(1) map lookup for the top-level

internal/evaluator/env.go

@@ -178,16 +178,18 @@ type EnvAwareBuiltin func(args []any, focus any, env *Environment) (any, error)
 // function via ApplyFunction bypass signature validation, allowing extra
 // arguments (key, index, array) to be passed silently.
 type SignedBuiltin struct {
-	Fn  BuiltinFunction
-	Sig string
+	Fn        BuiltinFunction
+	Sig       string
+	ParsedSig []parser.ParamSpec // pre-parsed signature; avoids re-parsing on every call
 }
 
 // Lambda represents a user-defined function (lambda expression).
 type Lambda struct {
-	Params        []string     // parameter names
-	Body          *parser.Node // function body AST node
-	Closure       *Environment // lexical scope at definition site
-	Thunk         bool         // for tail-call optimization
-	Sig           string       // type signature (Wave 5)
-	CapturedFocus any          // focus ($) captured at definition time for zero-param closures
+	Params        []string           // parameter names
+	Body          *parser.Node       // function body AST node
+	Closure       *Environment       // lexical scope at definition site
+	Thunk         bool               // for tail-call optimization
+	Sig           string             // type signature (Wave 5)
+	ParsedSig     []parser.ParamSpec // pre-parsed signature; avoids re-parsing per call
+	CapturedFocus any                // focus ($) captured at definition time for zero-param closures
 }