@statedelta-libs/expressions 2.2.0 → 3.0.0

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import { types } from 'omni-ast';
-
 /**
  * @statedelta-libs/expressions - Types
  *
@@ -45,15 +43,16 @@ interface PipeExpr {
     $pipe: Expression[];
 }
 /**
- * Callback expression - HOC de continuidade
- * Executa body dentro de um context function (tryCatch, transaction, etc.)
- * @example { $cb: "tryCatch", body: { $fn: "query" } }
- * @example { $cb: "transaction", params: { isolation: "serializable" }, body: { $fn: "query" } }
+ * Arrow expression — closure deferida
+ * Cria uma função sem executar. Pode receber args posicionais nomeados.
+ *
+ * @example { "$arrow": { "$fn": "query" } }                      // () => query()
+ * @example { "$arrow": { "$": "item.price" }, "args": ["item"] } // (item) => item.price
  */
-interface CbExpr {
-    $cb: string;
-    body: Expression;
-    params?: Expression;
+interface ArrowExpr {
+    $arrow: Expression;
+    args?: string[];
+    schema?: Record<string, unknown>;
 }
 /**
  * Literal values (primitives, arrays, plain objects)
@@ -86,7 +85,7 @@ type ConditionExpr = Condition | ConditionGroup;
 /**
  * Union of all expression types
  */
-type Expression = Literal | RefExpr | ConditionalExpr | FnExpr | PipeExpr | CbExpr | ConditionExpr;
+type Expression = Literal | RefExpr | ConditionalExpr | FnExpr | PipeExpr | ArrowExpr | ConditionExpr;
 /**
  * Compiled expression function
  */
@@ -133,50 +132,6 @@ interface ValidationResult {
  * @example { add, subtract, multiply, filter, map, sum }
  */
 type Scope = Record<string, (...args: any[]) => any>;
-/**
- * Path getter function for context callbacks
- */
-type PathGetterFn = (path: string) => unknown;
-/**
- * Context function - HOC que controla execução do body.
- * Recebe o body como callback e decide quando/se executá-lo.
- *
- * @param cb - Body compilado como callback (recebe data e get)
- * @param data - Dados do runtime
- * @param get - Resolver de paths (accessor)
- * @param params - Parâmetros extras para o context (opcional)
- *
- * @example
- * ```ts
- * const tryCatch: ContextFn = (cb, data, get, params) => {
- *   try {
- *     return cb(data, get);
- *   } catch (e) {
- *     return params?.fallback ?? null;
- *   }
- * };
- *
- * const transaction: ContextFn = (cb, data, get, params) => {
- *   const tx = db.beginTransaction(params);
- *   try {
- *     const result = cb({ ...data, tx }, get);
- *     tx.commit();
- *     return result;
- *   } catch (e) {
- *     tx.rollback();
- *     throw e;
- *   }
- * };
- * ```
- */
-type ContextFn<T = any, R = any> = (cb: (data: T, get: PathGetterFn) => R, data: T, get: PathGetterFn, params?: unknown) => R;
-/**
- * Context registry - HOC functions available to $cb expressions.
- * Separate from scope because context functions have different signature.
- *
- * @example { tryCatch, transaction, withRetry }
- */
-type Context = Record<string, ContextFn>;
 /**
  * Options for compilation
  */
@@ -192,263 +147,125 @@ interface CompileOptions<T = unknown> {
      * compile(expr, { accessor: (path, ctx) => ctx.get(path) })
      */
     accessor?: AccessorFn<T>;
-    /**
-     * Context functions available to $cb expressions.
-     * HOC functions that control body execution (tryCatch, transaction, etc.).
-     *
-     * @example
-     * compile(expr, {
-     *   context: {
-     *     tryCatch: (cb, data, get) => { try { return cb(data, get); } catch { return null; } }
-     *   }
-     * })
-     */
-    context?: Context;
+    /** Boundary definitions for compile-time interception */
+    boundaries?: BoundaryDef<T>[];
 }
 /**
- * Check if value is a reference expression
- */
-declare const isRef: (v: unknown) => v is RefExpr;
-/**
- * Check if value is a conditional expression
- */
-declare const isConditional: (v: unknown) => v is ConditionalExpr;
-/**
- * Check if value is a function call expression
- */
-declare const isFn: (v: unknown) => v is FnExpr;
-/**
- * Check if value is a pipe expression
- */
-declare const isPipe: (v: unknown) => v is PipeExpr;
-/**
- * Check if value is a callback expression
- */
-declare const isCb: (v: unknown) => v is CbExpr;
-/**
- * Check if value is a condition expression
- *
- * Verifies `op` is a valid condition operator to distinguish from
- * effect objects that also have `left` and `op` (e.g. op: "set").
- */
-declare const isCondition: (v: unknown) => v is Condition;
-/**
- * Check if value is a condition group
- */
-declare const isConditionGroup: (v: unknown) => v is ConditionGroup;
-/**
- * Check if value is any condition expression
- */
-declare const isConditionExpr: (v: unknown) => v is ConditionExpr;
-/**
- * Check if value is a literal (not an expression object)
- */
-declare const isLiteral: (v: unknown) => v is Literal;
-
-/**
- * @statedelta-libs/expressions - Compiler
+ * Boundary definition for compile-time interception.
+ * Allows foreign DSLs and compilers to plug into the expression walk.
+ * The handler is a self-sufficient closure — it captures whatever it needs
+ * from the consumer's scope (ExpressionCompiler, databases, other compilers).
  *
- * Compiles JSON DSL expressions to optimized functions.
- * Functions are provided via scope, not hardcoded.
+ * @example
+ * ```ts
+ * const rawBoundary: BoundaryDef = {
+ *   check: (node) => "$raw" in node,
+ *   handle: (node) => () => node.$raw,
+ * };
+ * ```
  */
+interface BoundaryDef<T = unknown> {
+    /** Check if node belongs to this boundary */
+    check: (node: Record<string, unknown>) => boolean;
+    /** Compile the node. Returns a ready-to-call function. */
+    handle: (node: Record<string, unknown>) => CompiledFn<T>;
+}
 
 /**
- * Compile expression to optimized function
+ * @statedelta-libs/expressions - Normalize
  *
- * @param expr - Expression to compile
- * @param options - Compile options (scope with functions, accessor)
- * @returns Compiled expression with fn, deps, and hash
+ * External normalization helper for custom expression types.
+ * Converts custom DSL nodes ($query, $mapper, etc.) to standard Expression
+ * BEFORE compilation. Keeps the core compiler pure.
  *
  * @example
  * ```ts
- * // Uso padrão - acesso direto por propriedade
- * import { add, filter, sum } from '@statedelta-libs/operators';
- *
- * const { fn } = compile(
- *   { $fn: "add", args: [{ $: "a" }, { $: "b" }] },
- *   { scope: { add, filter, sum } }
- * );
- *
- * fn({ a: 1, b: 2 }); // 3
- * ```
+ * const transforms = {
+ *   $query: (node) => ({ $fn: "__query", args: [node.$query, node.params ?? {}] })
+ * };
  *
- * @example
- * ```ts
- * // Com accessor customizado (ex: TickContext)
- * const { fn } = compile(
- *   { $: "hp:value" },
- *   { accessor: (path, ctx) => ctx.get(path) }
+ * const pure = normalize(
+ *   { $query: "isAttacked", params: { row: { $: "kingRow" } } },
+ *   transforms
  * );
+ * // → { $fn: "__query", args: ["isAttacked", { row: { $: "kingRow" } }] }
  *
- * fn(tickContext); // usa ctx.get('hp:value')
+ * compile(pure, { scope });
  * ```
  */
-declare function compile<T = unknown, R = unknown>(expr: Expression, options?: CompileOptions<T>): CompiledExpression<T, R>;
+
 /**
- * Compile and execute in one step
+ * Transform function for custom expression types.
+ * Receives the raw node and returns a standard Expression.
  *
  * @example
  * ```ts
- * // Uso padrão
- * evaluate(
- *   { $fn: "add", args: [{ $: "a" }, { $: "b" }] },
- *   { a: 1, b: 2 },
- *   { scope: { add } }
- * ); // 3
- *
- * // Com accessor customizado
- * evaluate(
- *   { $: "hp:value" },
- *   tickContext,
- *   { accessor: (path, ctx) => ctx.get(path) }
- * );
+ * const transforms: Transforms = {
+ *   $query: (node) => ({
+ *     $fn: "__query",
+ *     args: [node.$query, node.params ?? {}]
+ *   }),
+ * };
  * ```
  */
-declare function evaluate<T = unknown, R = unknown>(expr: Expression, data: T, options?: CompileOptions<T>): R;
-
-/**
- * @statedelta-libs/expressions - Path Compiler
- *
- * Compiles paths to optimized getters with wildcard support.
- * Performance: ~50M ops/sec for simple paths, ~10M ops/sec for wildcards
- */
-
-/**
- * Check if path has wildcards
- */
-declare function hasWildcard(path: string): boolean;
-/**
- * Compile path to optimized getter
- */
-declare function compilePath<T = unknown>(path: string): PathGetter<T>;
-/**
- * Get value at path directly (without caching)
- */
-declare function get<T = unknown>(data: T, path: string): unknown;
-/**
- * Normalize path for dependency tracking (remove wildcards)
- * @example "items[*].price" → "items"
- * @example "users[*].posts[*].title" → "users"
- */
-declare function normalizePath(path: string): string;
-/**
- * Clear path cache
- */
-declare function clearPathCache(): void;
-/**
- * Get cache size
- */
-declare function getPathCacheSize(): number;
-
-/**
- * @statedelta-libs/expressions - Dependency Extraction
- *
- * Extracts paths that an expression depends on.
- * Performance: ~200K ops/sec
- */
-
-/**
- * Extract all paths an expression depends on
- * @example { "$": "user.age" } → ["user.age"]
- * @example { "$if": "$isVip", "then": { "$": "price.vip" } } → ["$isVip", "price.vip"]
- */
-declare function extractDeps(expr: Expression): string[];
-/**
- * Check if expression has dependencies
- */
-declare function hasDeps(expr: Expression): boolean;
-/**
- * Check if expression is pure (no dependencies)
- */
-declare function isPure(expr: Expression): boolean;
-
-/**
- * @statedelta-libs/expressions - Cache
- *
- * LRU cache for compiled expressions.
- * Performance: cache hit ~10M ops/sec
- */
-
-/**
- * LRU Cache for compiled expressions
- */
-declare class ExpressionCache {
-    private cache;
-    private _maxSize;
-    constructor(maxSize?: number);
-    /**
-     * Get or compile expression
-     *
-     * Note: The cache key is based on the expression only, not the scope.
-     * If you use different scopes for the same expression, consider using
-     * separate cache instances or not caching at all.
-     */
-    get<T = unknown, R = unknown>(expr: Expression, options?: CompileOptions): CompiledExpression<T, R>;
-    /**
-     * Check if expression is cached
-     */
-    has(expr: Expression): boolean;
-    /**
-     * Delete specific expression from cache
-     */
-    delete(expr: Expression): boolean;
-    /**
-     * Clear the cache
-     */
-    clear(): void;
-    /**
-     * Current cache size
-     */
-    get size(): number;
-    /**
-     * Maximum cache size
-     */
-    get maxSize(): number;
-    /**
-     * Set maximum cache size
-     */
-    set maxSize(value: number);
-}
-declare const cache: ExpressionCache;
+type TransformFn = (node: Record<string, unknown>) => Expression;
 /**
- * Compile and cache expression (convenience function)
- *
- * Note: Uses global cache. For custom scope management,
- * use a dedicated ExpressionCache instance.
+ * Map of transform functions keyed by marker (e.g. "$query", "$mapper")
  */
-declare function cached<T = unknown, R = unknown>(expr: Expression, options?: CompileOptions): CompiledExpression<T, R>;
+type Transforms = Record<string, TransformFn>;
 
 /**
- * @statedelta-libs/expressions - Validation
+ * @statedelta-libs/expressions - ExpressionCompiler
  *
- * Validates expression structure before compilation.
+ * Unified public API for expression compilation.
+ * Centralizes scope, accessor, and cache in a single reusable instance.
  */
 
-/**
- * Validation options
- */
-interface ValidateOptions {
-    /** Scope to validate function names against (optional) */
+interface ExpressionCompilerOptions<T = unknown> {
+    /** Functions available to $fn expressions */
     scope?: Scope;
-    /** Context to validate $cb function names against (optional) */
-    context?: Context;
+    /** Custom accessor for resolving paths */
+    accessor?: AccessorFn<T>;
+    /** Max LRU cache size per mode (default: 1000) */
+    cacheSize?: number;
+    /** Boundary definitions for compile-time interception */
+    boundaries?: BoundaryDef<T>[];
+}
+interface JITOptions {
+    /** Use accessor to resolve paths instead of direct access */
+    useAccessor?: boolean;
+    /** Prefix for paths that bypass accessor (direct access) */
+    lexicalPrefix?: string;
+}
+declare class ExpressionCompiler<T = unknown> {
+    private readonly scope;
+    private readonly accessor?;
+    private readonly boundaries?;
+    private readonly cacheClosures;
+    private readonly cacheJIT;
+    constructor(options?: ExpressionCompilerOptions<T>);
+    /** Compile via closure composition (interpretation) */
+    compile<R = unknown>(expr: Expression): CompiledExpression<T, R>;
+    /** Compile via JS code generation (JIT) */
+    jit<R = unknown>(expr: Expression, opts?: JITOptions): CompiledExpression<T, R>;
+    /** Compile (closures) and execute in one step */
+    evaluate<R = unknown>(expr: Expression, data: T): R;
+    /** Compile (JIT) and execute in one step */
+    evaluateJIT<R = unknown>(expr: Expression, data: T, opts?: JITOptions): R;
+    /** Normalize custom expression to pure DSL */
+    normalize(expr: Expression, transforms: Transforms): Expression;
+    /** Extract dependencies without compiling */
+    extractDeps(expr: Expression): string[];
+    /** Cache size per mode */
+    get cacheSize(): {
+        closures: number;
+        jit: number;
+    };
+    /** Clear both caches */
+    clearCache(): void;
+    /** Read-only access to scope */
+    getScope(): Readonly<Scope>;
 }
-/**
- * Validate expression structure
- *
- * @param expr - Expression to validate
- * @param path - Current path in expression tree (for error messages)
- * @param options - Validation options
- */
-declare function validate(expr: Expression, path?: string, options?: ValidateOptions): ValidationResult;
-/**
- * Validate and throw if invalid
- */
-declare function assertValid(expr: Expression, options?: ValidateOptions): void;
-/**
- * Check if expression is valid
- */
-declare function isValid(expr: Expression, options?: ValidateOptions): boolean;
 
 /**
  * @statedelta-libs/expressions - Builders
@@ -555,25 +372,22 @@ declare function $cond(left: Expression, op: ConditionOp, right?: Expression): C
  */
 declare const cond: typeof $cond;
 /**
- * Create a callback expression (HOC de continuidade).
+ * Create an arrow expression (closure).
  *
- * @param name - Context function name (from context)
- * @param body - Expression to execute inside the context
- * @param params - Optional parameters for the context function
- * @returns CbExpr
+ * @param body - Expression to defer
+ * @param args - Named positional arguments (optional)
+ * @returns ArrowExpr
  *
  * @example
- * $cb("tryCatch", $fn("query"))
- * // { $cb: "tryCatch", body: { $fn: "query" } }
- *
- * $cb("transaction", $fn("saveUser"), { isolation: "serializable" })
- * // { $cb: "transaction", body: {...}, params: {...} }
+ * $arrow($fn("query"))                              // () => query()
+ * $arrow($("item.price"), ["item"])                  // (item) => item.price
+ * $arrow($fn("add", [$("a"), $("b")]), ["a", "b"])  // (a, b) => add(a, b)
  */
-declare function $cb(name: string, body: Expression, params?: Expression): CbExpr;
+declare function $arrow(body: Expression, args?: string[]): ArrowExpr;
 /**
- * Alias for $cb (callback builder)
+ * Alias for $arrow
  */
-declare const cb: typeof $cb;
+declare const arrow: typeof $arrow;
 /**
  * Create a function call expression that always calls the function.
  * Unlike $fn which returns function reference when args is empty/undefined,
@@ -594,428 +408,154 @@ declare function $call(name: string, args?: Expression[]): FnExpr;
 declare const call: typeof $call;
 
 declare const builders_$: typeof $;
+declare const builders_$arrow: typeof $arrow;
 declare const builders_$call: typeof $call;
-declare const builders_$cb: typeof $cb;
 declare const builders_$cond: typeof $cond;
 declare const builders_$fn: typeof $fn;
 declare const builders_$if: typeof $if;
 declare const builders_$pipe: typeof $pipe;
+declare const builders_arrow: typeof arrow;
 declare const builders_call: typeof call;
-declare const builders_cb: typeof cb;
 declare const builders_cond: typeof cond;
 declare const builders_fn: typeof fn;
 declare const builders_pipe: typeof pipe;
 declare const builders_ref: typeof ref;
 declare namespace builders {
-  export { builders_$ as $, builders_$call as $call, builders_$cb as $cb, builders_$cond as $cond, builders_$fn as $fn, builders_$if as $if, builders_$pipe as $pipe, builders_call as call, builders_cb as cb, builders_cond as cond, builders_fn as fn, builders_pipe as pipe, builders_ref as ref };
+  export { builders_$ as $, builders_$arrow as $arrow, builders_$call as $call, builders_$cond as $cond, builders_$fn as $fn, builders_$if as $if, builders_$pipe as $pipe, builders_arrow as arrow, builders_call as call, builders_cond as cond, builders_fn as fn, builders_pipe as pipe, builders_ref as ref };
 }
 
 /**
- * @statedelta-libs/expressions - DSL to AST Transformer
+ * @statedelta-libs/expressions - Type Guards
  *
- * Transforms JSON DSL expressions to ESTree AST nodes using omni-ast builders.
- * Supports two modes:
- * - With prefixes (default): generates `data?.user?.name`, `scope.add()`
- * - Without prefixes: generates `user?.name`, `add()` (for use with destructuring)
+ * Type guards and constants for expression type checking.
  */
 
-type ASTNode = types.Expression;
-/** Options for DSL to AST transformation */
-interface TransformOptions {
-    /**
-     * Name of data parameter (default: "data")
-     * When noPrefixes=true, this is ignored for property access
-     */
-    dataParam?: string;
-    /**
-     * Name of scope parameter (default: "scope")
-     * When noPrefixes=true, this is ignored for function calls
-     */
-    scopeParam?: string;
-    /**
-     * When true, generates code without data/scope prefixes.
-     * Assumes variables are available via destructuring.
-     * - `user?.name` instead of `data?.user?.name`
-     * - `add(a, b)` instead of `scope.add(data?.a, data?.b)`
-     */
-    noPrefixes?: boolean;
-    /**
-     * When true, generates accessor("path", data) instead of property access.
-     * Requires `accessor` function in scope.
-     * - `accessor("user.name", data)` instead of `user?.name`
-     */
-    useAccessor?: boolean;
-    /**
-     * Path prefix that should use direct property access instead of accessor.
-     * Only used when useAccessor is true.
-     * - `lexicalPrefix: "params"` → `params?.foo` instead of `accessor("params.foo", data)`
-     */
-    lexicalPrefix?: string;
-}
 /**
- * Transform DSL expression to AST node
- *
- * @param expr - DSL expression
- * @param options - Transform options
- * @returns ESTree AST node
- *
- * @example
- * ```ts
- * // With prefixes (default)
- * dslToAST({ $: "user.name" })
- * // → data?.user?.name
- *
- * // Without prefixes (for destructuring)
- * dslToAST({ $: "user.name" }, { noPrefixes: true })
- * // → user?.name
- * ```
+ * Check if value is a reference expression
  */
-declare function dslToAST(expr: Expression, options?: TransformOptions): ASTNode;
+declare const isRef: (v: unknown) => v is RefExpr;
 /**
- * Wrap AST expression in an arrow function
+ * Check if value is a conditional expression
  */
-declare function wrapInFunction(bodyAst: ASTNode, params?: string[]): ASTNode;
-
+declare const isConditional: (v: unknown) => v is ConditionalExpr;
 /**
- * @statedelta-libs/expressions - Extract Scope Functions
- *
- * Extracts function names used from scope in a DSL expression.
- * Used to generate optimized destructuring: const { add, filter } = scope;
+ * Check if value is a function call expression
  */
-
+declare const isFn: (v: unknown) => v is FnExpr;
 /**
- * Extract all function names used from scope in an expression
- *
- * @param expr - DSL expression to analyze
- * @returns Set of function names used
- *
- * @example
- * ```ts
- * extractScopeFns({ $fn: "add", args: [{ $: "a" }, { $: "b" }] })
- * // Set { "add" }
- *
- * extractScopeFns({
- *   $pipe: [
- *     { $: "items" },
- *     { $fn: "filter", args: [pred] },
- *     { $fn: "sum" }
- *   ]
- * })
- * // Set { "filter", "sum" }
- * ```
+ * Check if value is a pipe expression
  */
-declare function extractScopeFns(expr: Expression): Set<string>;
+declare const isPipe: (v: unknown) => v is PipeExpr;
 /**
- * Extract all context function names used in an expression
- *
- * @param expr - DSL expression to analyze
- * @returns Set of context function names used
- *
- * @example
- * ```ts
- * extractContextFns({ $cb: "tryCatch", body: { $fn: "query" } })
- * // Set { "tryCatch" }
- * ```
+ * Check if value is an arrow expression (closure)
  */
-declare function extractContextFns(expr: Expression): Set<string>;
+declare const isArrow: (v: unknown) => v is ArrowExpr;
 /**
- * Extract root-level data dependencies from paths
- *
- * @param deps - Array of dependency paths
- * @returns Set of root-level property names
+ * Check if value is a condition expression
  *
- * @example
- * ```ts
- * extractDataRoots(["user.name", "user.age", "items", "config.theme"])
- * // Set { "user", "items", "config" }
- * ```
+ * Verifies `op` is a valid condition operator to distinguish from
+ * effect objects that also have `left` and `op` (e.g. op: "set").
  */
-declare function extractDataRoots(deps: string[]): Set<string>;
-
+declare const isCondition: (v: unknown) => v is Condition;
 /**
- * @statedelta-libs/expressions - AST Compiler
- *
- * Compiles DSL expressions to optimized functions using AST generation.
- * Uses destructuring for better performance:
- * - Variables from data are destructured into local scope
- * - Functions from scope are destructured into local scope
- * - Generated code is smaller and faster
+ * Check if value is a condition group
  */
-
-/** Options for AST compilation */
-interface CompileASTOptions {
-    /** Scope with functions available to the expression */
-    scope?: Scope;
-    /** Context with HOC functions available to $cb expressions */
-    context?: Context;
-    /** Return generated code instead of function (for debugging) */
-    returnCode?: boolean;
-    /**
-     * When true, generates accessor("path", data) instead of property access.
-     * Requires `accessor` function in scope.
-     */
-    useAccessor?: boolean;
-    /**
-     * Path prefix that should use direct property access instead of accessor.
-     * Only used when useAccessor is true.
-     * - `lexicalPrefix: "params"` → `params?.foo` instead of `accessor("params.foo", data)`
-     */
-    lexicalPrefix?: string;
-}
-/** Result when returnCode is true */
-interface CompileASTCodeResult {
-    code: string;
-    deps: string[];
-    hash: string;
-    dataRoots: string[];
-    scopeFns: string[];
-    contextFns: string[];
-}
+declare const isConditionGroup: (v: unknown) => v is ConditionGroup;
 /**
- * Compile DSL expression to optimized function using AST generation
- *
- * This is the high-performance compiler that:
- * 1. Extracts dependencies and scope functions
- * 2. Generates AST without prefixes
- * 3. Wraps in destructuring for optimal variable access
- * 4. Creates function via `new Function()` or `eval()`
- *
- * @example
- * ```ts
- * import { compileAST } from '@statedelta-libs/expressions';
- * import { add, filter, sum } from '@statedelta-libs/operators';
- *
- * const { fn } = compileAST(
- *   { $fn: "add", args: [{ $: "a" }, { $: "b" }] },
- *   { scope: { add, filter, sum } }
- * );
- *
- * fn({ a: 1, b: 2 }); // 3
- * ```
+ * Check if value is any condition expression
  */
-declare function compileAST<T = unknown, R = unknown>(expr: Expression, options: CompileASTOptions & {
-    returnCode: true;
-}): CompileASTCodeResult;
-declare function compileAST<T = unknown, R = unknown>(expr: Expression, options?: CompileASTOptions): CompiledExpression<T, R>;
+declare const isConditionExpr: (v: unknown) => v is ConditionExpr;
 /**
- * Compile and execute in one step
- *
- * @example
- * ```ts
- * evaluateAST(
- *   { $fn: "add", args: [{ $: "a" }, { $: "b" }] },
- *   { a: 1, b: 2 },
- *   { scope: { add } }
- * ); // 3
- * ```
+ * Check if value is a literal (not an expression object)
  */
-declare function evaluateAST<T = unknown, R = unknown>(expr: Expression, data: T, options?: CompileASTOptions): R;
+declare const isLiteral: (v: unknown) => v is Literal;
 
 /**
- * @statedelta-libs/expressions - Normalize
- *
- * External normalization helper for custom expression types.
- * Converts custom DSL nodes ($query, $mapper, etc.) to standard Expression
- * BEFORE compilation. Keeps the core compiler pure.
- *
- * @example
- * ```ts
- * const transforms = {
- *   $query: (node) => ({ $fn: "__query", args: [node.$query, node.params ?? {}] })
- * };
- *
- * const pure = normalize(
- *   { $query: "isAttacked", params: { row: { $: "kingRow" } } },
- *   transforms
- * );
- * // → { $fn: "__query", args: ["isAttacked", { row: { $: "kingRow" } }] }
+ * @statedelta-libs/expressions - Validation
  *
- * compile(pure, { scope });
- * ```
+ * Validates expression structure before compilation.
  */
 
 /**
- * Transform function for custom expression types.
- * Receives the raw node and returns a standard Expression.
+ * Validation options
+ */
+interface ValidateOptions {
+    /** Scope to validate function names against (optional) */
+    scope?: Scope;
+    /** Boundary definitions — matched nodes skip validation */
+    boundaries?: BoundaryDef[];
+}
+/**
+ * Validate expression structure
  *
- * @example
- * ```ts
- * const transforms: Transforms = {
- *   $query: (node) => ({
- *     $fn: "__query",
- *     args: [node.$query, node.params ?? {}]
- *   }),
- * };
- * ```
+ * @param expr - Expression to validate
+ * @param path - Current path in expression tree (for error messages)
+ * @param options - Validation options
  */
-type TransformFn = (node: Record<string, unknown>) => Expression;
+declare function validate(expr: Expression, path?: string, options?: ValidateOptions): ValidationResult;
 /**
- * Map of transform functions keyed by marker (e.g. "$query", "$mapper")
+ * Validate and throw if invalid
  */
-type Transforms = Record<string, TransformFn>;
+declare function assertValid(expr: Expression, options?: ValidateOptions): void;
 /**
- * Normalize an expression by applying transforms recursively.
- * Converts custom DSL nodes to standard Expression types.
- *
- * @param expr - Expression (possibly with custom nodes)
- * @param transforms - Map of transform functions
- * @returns Pure Expression with all custom nodes converted
- *
- * @example
- * ```ts
- * const transforms = {
- *   $query: (node) => ({ $fn: "__query", args: [node.$query, node.params ?? {}] })
- * };
- *
- * normalize({ $query: "check", params: { x: 1 } }, transforms);
- * // → { $fn: "__query", args: ["check", { x: 1 }] }
- *
- * // Nested expressions in params are also normalized
- * normalize({ $query: "check", params: { row: { $: "myRow" } } }, transforms);
- * // → { $fn: "__query", args: ["check", { row: { $: "myRow" } }] }
- * ```
+ * Check if expression is valid
  */
-declare function normalize(expr: unknown, transforms: Transforms): Expression;
+declare function isValid(expr: Expression, options?: ValidateOptions): boolean;
 
 /**
- * @statedelta-libs/expressions - Boundaries
- *
- * Resolve custom boundaries ($simulate, $query, etc.) before compilation.
- * Boundaries are "foreign bodies" that stop the expression flow and delegate
- * to external handlers. The handler can compile internal slots independently.
- *
- * @example
- * ```ts
- * const { expr, scope } = resolveBoundaries(
- *   { $simulate: { effects: [...], query: {...} } },
- *   {
- *     scope: baseScope,
- *     resolvers: {
- *       $simulate: (node, { compile, genId }) => {
- *         const id = `__simulate_${genId()}`;
- *         const fn = buildSimulateFn(node, compile);
- *         return {
- *           expr: { $fn: id },
- *           scopeEntry: [id, fn]
- *         };
- *       }
- *     }
- *   }
- * );
+ * @statedelta-libs/expressions - Path Compiler
  *
- * compile(expr, { scope });
- * ```
+ * Compiles paths to optimized getters with wildcard support.
+ * Performance: ~50M ops/sec for simple paths, ~10M ops/sec for wildcards
  */
 
 /**
- * Result returned by a boundary resolver
+ * Check if path has wildcards
  */
-interface ResolverResult {
-    /** Expression to replace the boundary with */
-    expr: Expression;
-    /** Optional entry to add to scope [key, value] */
-    scopeEntry?: [string, unknown];
-}
+declare function hasWildcard(path: string): boolean;
 /**
- * Context provided to boundary resolvers
- */
-interface ResolverContext {
-    /** Compile function for compiling internal slots */
-    compile: typeof compile;
-    /** Generate unique ID for scope entries */
-    genId: () => string;
-    /** Current scope (read-only reference) */
-    scope: Readonly<Scope>;
-    /** Compile options passed to resolveBoundaries */
-    options: Readonly<CompileOptions>;
-}
+ * Compile path to optimized getter
+ */
+declare function compilePath<T = unknown>(path: string): PathGetter<T>;
 /**
- * Boundary resolver function.
- * Receives the raw node and context, returns replacement expression.
+ * Get value at path directly (without caching)
  */
-type BoundaryResolver = (node: Record<string, unknown>, ctx: ResolverContext) => ResolverResult;
+declare function get<T = unknown>(data: T, path: string): unknown;
 /**
- * Map of boundary resolvers keyed by marker (e.g. "$simulate", "$query")
+ * Normalize path for dependency tracking (remove wildcards)
+ * @example "items[*].price" → "items"
+ * @example "users[*].posts[*].title" → "users"
  */
-type BoundaryResolvers = Record<string, BoundaryResolver>;
+declare function normalizePath(path: string): string;
+
 /**
- * ID generator function
+ * @statedelta-libs/expressions - Dependency Extraction
+ *
+ * Extracts paths that an expression depends on.
+ * Performance: ~200K ops/sec
  */
-type IdGenerator = () => string;
+
 /**
- * Options for resolveBoundaries
+ * Extract all paths an expression depends on
+ * @example { "$": "user.age" } → ["user.age"]
+ * @example { "$if": "$isVip", "then": { "$": "price.vip" } } → ["$isVip", "price.vip"]
  */
-interface ResolveBoundariesOptions extends CompileOptions {
-    /** Map of boundary resolvers */
-    resolvers: BoundaryResolvers;
-    /** Custom ID generator. Default: simple counter ("0", "1", "2"...) */
-    genId?: IdGenerator;
-}
+declare function extractDeps(expr: Expression): string[];
 /**
- * Result of resolveBoundaries
+ * Check if expression has dependencies
  */
-interface ResolveBoundariesResult {
-    /** Pure expression with boundaries replaced */
-    expr: Expression;
-    /** Enriched scope with boundary handlers */
-    scope: Scope;
-}
+declare function hasDeps(expr: Expression): boolean;
 /**
- * Resolve boundaries in an expression tree.
- *
- * Boundaries are custom DSL nodes ($simulate, $query, etc.) that stop the
- * normal expression compilation flow. Each boundary is extracted, processed
- * by its resolver, and replaced with a standard expression.
- *
- * The resolver receives:
- * - `node`: The raw boundary object (e.g. { $simulate: {...}, effects: [...] })
- * - `ctx.compile`: Compile function for internal slots
- * - `ctx.genId`: Unique ID generator
- * - `ctx.scope`: Current scope (read-only)
- *
- * The resolver returns:
- * - `expr`: Replacement expression (typically { $fn: "__id" })
- * - `scopeEntry`: Optional [key, fn] to add to scope
- *
- * @param expr - Expression (possibly with boundaries)
- * @param options - Resolvers, scope, and compile options
- * @returns Pure expression and enriched scope
+ * Check if expression is pure (no dependencies)
  */
-declare function resolveBoundaries(expr: unknown, options: ResolveBoundariesOptions): ResolveBoundariesResult;
+declare function isPure(expr: Expression): boolean;
 
 /**
  * @statedelta-libs/expressions
  *
  * JSON DSL compiler for optimized functions.
  * Functions are provided via scope, not hardcoded.
- *
- * @example
- * ```ts
- * import { compile, evaluate } from '@statedelta-libs/expressions';
- * import { filter, map, sum } from '@statedelta-libs/operators';
- *
- * const scope = { filter, map, sum };
- *
- * // Using $pipe for composition with initial value
- * const { fn } = compile({
- *   $pipe: [
- *     { $: "items" },
- *     { $fn: "filter", args: [{ path: "active", op: "eq", value: true }] },
- *     { $fn: "map", args: [{ $: "price" }] },
- *     { $fn: "sum" }
- *   ]
- * }, { scope });
- *
- * fn({ items: [...] }); // sum of active item prices
- *
- * // Using $fn for simple function calls
- * evaluate(
- *   { $fn: "add", args: [{ $: "a" }, { $: "b" }] },
- *   { a: 1, b: 2 },
- *   { scope: { add: (a, b) => a + b } }
- * ); // 3
- * ```
  */
-declare const VERSION = "2.0.0";
+declare const VERSION = "3.0.0";
 
-export { type AccessorFn, type BoundaryResolver, type BoundaryResolvers, type CbExpr, type CompileASTCodeResult, type CompileASTOptions, type CompileOptions, type CompiledExpression, type CompiledFn, type Condition, type ConditionExpr, type ConditionGroup, type ConditionOp, type ConditionalExpr, type Context, type ContextFn, type Expression, ExpressionCache, type FnExpr, type IdGenerator, type Literal, type PathGetter, type PathGetterFn, type PipeExpr, type RefExpr, type ResolveBoundariesOptions, type ResolveBoundariesResult, type ResolverContext, type ResolverResult, type Scope, type TransformFn, type TransformOptions, type Transforms, VERSION, type ValidateOptions, type ValidationResult, assertValid, builders, cache, cached, clearPathCache, compile, compileAST, compilePath, dslToAST, evaluate, evaluateAST, extractContextFns, extractDataRoots, extractDeps, extractScopeFns, get, getPathCacheSize, hasDeps, hasWildcard, isCb, isCondition, isConditionExpr, isConditionGroup, isConditional, isFn, isLiteral, isPipe, isPure, isRef, isValid, normalize, normalizePath, resolveBoundaries, validate, wrapInFunction };
+export { type AccessorFn, type ArrowExpr, type BoundaryDef, type CompileOptions, type CompiledExpression, type CompiledFn, type Condition, type ConditionExpr, type ConditionGroup, type ConditionOp, type ConditionalExpr, type Expression, ExpressionCompiler, type ExpressionCompilerOptions, type FnExpr, type JITOptions, type Literal, type PipeExpr, type RefExpr, type Scope, type TransformFn, type Transforms, VERSION, type ValidateOptions, type ValidationResult, assertValid, builders, compilePath, extractDeps, get, hasDeps, hasWildcard, isArrow, isCondition, isConditionExpr, isConditionGroup, isConditional, isFn, isLiteral, isPipe, isPure, isRef, isValid, normalizePath, validate };