@statedelta-libs/expressions 2.3.0 → 3.1.0

package/dist/index.d.cts

@@ -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
  */
@@ -107,14 +106,13 @@ interface CompiledExpression<T = unknown, R = unknown> {
  */
 type PathGetter<T = unknown> = (data: T) => unknown;
 /**
- * Accessor customizado para resolver paths
- * Permite usar ctx.get(path) em vez de acesso direto por propriedade
+ * Accessor customizado para resolver paths.
+ * Closure auto-suficiente — já sabe de onde ler.
  *
  * @example
- * // Com TickContext
- * const accessor: AccessorFn<TickContext> = (path, ctx) => ctx.get(path);
+ * const accessor: AccessorFn = (path) => tickContext.get(path);
  */
-type AccessorFn<T = unknown> = (path: string, data: T) => unknown;
+type AccessorFn = (path: string) => unknown;
 /**
  * Validation result
  */
@@ -133,74 +131,6 @@ interface ValidationResult {
  * @example { add, subtract, multiply, filter, map, sum }
  */
 type Scope = Record<string, (...args: any[]) => any>;
-/**
- * Path getter function - accessor de paths.
- */
-type PathGetterFn = (path: string) => unknown;
-/**
- * Runtime context - contexto unificado passado para ContextFn.
- * Agrupa dados e utilitários da lib em um único objeto imutável.
- *
- * @example
- * ```ts
- * // No ContextFn
- * const tryCatch: ContextFn = (cb, ctx, params) => {
- *   console.log(ctx.data);        // dados do usuário
- *   console.log(ctx.get("path")); // accessor
- * };
- * ```
- */
-interface RuntimeCtx<T = unknown> {
-    /** Dados do runtime (passados pelo usuário) */
-    data: T;
-    /** Accessor de paths - resolve { $: "path" } */
-    get: PathGetterFn;
-}
-/**
- * Context function - HOC que controla execução do body.
- * Recebe o body como callback e decide quando/se executá-lo.
- *
- * @param cb - Body compilado (recebe ctx)
- * @param ctx - Contexto de runtime (data + get)
- * @param params - Parâmetros específicos deste $cb (opcional)
- *
- * @example
- * ```ts
- * const tryCatch: ContextFn = (cb, ctx, params) => {
- *   try {
- *     return cb(ctx);
- *   } catch (e) {
- *     return params?.fallback ?? null;
- *   }
- * };
- *
- * const transaction: ContextFn = (cb, ctx, params) => {
- *   const tx = db.beginTransaction(params);
- *   try {
- *     // Pode criar novo ctx com dados extras
- *     const result = cb({ ...ctx, data: { ...ctx.data, tx } });
- *     tx.commit();
- *     return result;
- *   } catch (e) {
- *     tx.rollback();
- *     throw e;
- *   }
- * };
- *
- * // Context pode injetar accessor customizado
- * const simulate: ContextFn = (cb, ctx, params) => {
- *   const simulatedGet = (path) => store.getSimulated(path);
- *   return cb({ ...ctx, get: simulatedGet });
- * };
- * ```
- */
-type ContextFn<T = any, R = any> = (cb: (ctx: RuntimeCtx<T>) => R, ctx: RuntimeCtx<T>, params?: unknown) => R;
-/**
- * Context registry - HOC functions available to $cb expressions.
- *
- * @example { tryCatch, transaction, simulate }
- */
-type Context = Record<string, ContextFn>;
 /**
  * Options for compilation
  */
@@ -212,267 +142,186 @@ interface CompileOptions<T = unknown> {
      * Quando fornecido, substitui o acesso direto por propriedade.
      *
      * @example
-     * // Com TickContext
-     * 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; } }
-     *   }
-     * })
+     * compile(expr, { accessor: (path) => ctx.get(path) })
      */
-    context?: Context;
+    accessor?: AccessorFn;
+    /** Boundary definitions for compile-time interception */
+    boundaries?: BoundaryDef<T>[];
+    /** Wrapped handlers (ctx already bound) for $fn "namespace:method" calls */
+    handlers?: WrappedHandlers;
 }
 /**
- * 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
+ * Handler function — receives HandlerContext via `this` (bound at compile time).
+ * Must be a regular function or method shorthand (NOT arrow function).
+ * HandlerContext is defined in compiler.ts.
  *
- * 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
+ * @example
+ * {
+ *   query: {
+ *     find(key: string) { return this.scope.add(key, 1); }
+ *   }
+ * }
  */
-declare const isConditionGroup: (v: unknown) => v is ConditionGroup;
+type HandlerFn = (...args: any[]) => any;
 /**
- * Check if value is any condition expression
+ * Handlers map — namespaces of handler methods.
+ * Provided by consumer in ExpressionCompiler constructor.
+ * Handlers access context via `this` (bound automatically via .bind()).
+ *
+ * @example
+ * {
+ *   query: {
+ *     find(filter: string) { return this.scope.transform(filter); },
+ *     findAll() { return this.handlers.other.list(); },
+ *   },
+ * }
  */
-declare const isConditionExpr: (v: unknown) => v is ConditionExpr;
+type HandlersMap = Record<string, Record<string, HandlerFn>>;
 /**
- * Check if value is a literal (not an expression object)
+ * Wrapped handlers (ctx already bound via .bind()).
+ * Used internally by both pipelines.
  */
-declare const isLiteral: (v: unknown) => v is Literal;
-
+type WrappedHandlers = Record<string, Record<string, (...args: any[]) => any>>;
 /**
- * @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;
+type TransformFn = (node: Record<string, unknown>) => Expression;
 /**
- * Check if expression is pure (no dependencies)
+ * Map of transform functions keyed by marker (e.g. "$query", "$mapper")
  */
-declare function isPure(expr: Expression): boolean;
+type Transforms = Record<string, TransformFn>;
 
 /**
- * @statedelta-libs/expressions - Cache
+ * @statedelta-libs/expressions - ExpressionCompiler
  *
- * LRU cache for compiled expressions.
- * Performance: cache hit ~10M ops/sec
+ * Unified public API for expression compilation.
+ * Centralizes scope, accessor, and cache in a single reusable instance.
  */
 
+interface ExpressionCompilerOptions<T = unknown> {
+    /** Functions available to $fn expressions */
+    scope?: Scope;
+    /** Custom accessor for resolving paths */
+    accessor?: AccessorFn;
+    /** Max LRU cache size per mode (default: 1000) */
+    cacheSize?: number;
+    /** Boundary definitions for compile-time interception */
+    boundaries?: BoundaryDef<T>[];
+    /** Handler namespaces — services with injected context */
+    handlers?: HandlersMap;
+}
+interface JITOptions {
+    /** Use accessor to resolve paths instead of direct access */
+    useAccessor?: boolean;
+    /** Prefix for paths that bypass accessor (direct access) */
+    lexicalPrefix?: string;
+}
 /**
- * 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;
+ * Context available via `this` inside every handler (bound via .bind()).
+ * Created once per ExpressionCompiler instance — zero per-call overhead.
+ */
+interface HandlerContext<T = unknown> {
+    /** Custom accessor for resolving paths */
+    accessor?: AccessorFn;
+    /** All wrapped handlers — handlers can call other handlers */
+    handlers: WrappedHandlers;
+    /** Compiler instance — can compile sub-expressions */
+    compiler: ExpressionCompiler<T>;
+    /** Pure scope functions */
+    scope: Scope;
+}
+declare class ExpressionCompiler<T = unknown> {
+    private readonly scope;
+    private readonly accessor?;
+    private readonly boundaries?;
+    private readonly wrappedHandlers?;
+    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>;
     /**
-     * Set maximum cache size
+     * Wrap raw handlers with ctx via .bind().
+     * Creates ctx once, binds each handler method once.
+     * Resolves circular reference: ctx.handlers = wrappedHandlers.
+     * Handlers access ctx via `this`.
      */
-    set maxSize(value: number);
+    private wrapHandlers;
+    /** 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>;
 }
-declare const cache: ExpressionCache;
-/**
- * Compile and cache expression (convenience function)
- *
- * Note: Uses global cache. For custom scope management,
- * use a dedicated ExpressionCache instance.
- */
-declare function cached<T = unknown, R = unknown>(expr: Expression, options?: CompileOptions): CompiledExpression<T, R>;
-
-/**
- * @statedelta-libs/expressions - Validation
- *
- * Validates expression structure before compilation.
- */
-
-/**
- * Validation options
- */
-interface ValidateOptions {
-    /** Scope to validate function names against (optional) */
-    scope?: Scope;
-    /** Context to validate $cb function names against (optional) */
-    context?: Context;
-}
-/**
- * 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
@@ -579,25 +428,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,
@@ -618,428 +464,156 @@ 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[];
+    /** Handlers map to validate handler names against (optional) */
+    handlers?: HandlersMap;
+}
+/**
+ * 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 RuntimeCtx, 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 HandlerContext, type HandlerFn, type HandlersMap, type JITOptions, type Literal, type PipeExpr, type RefExpr, type Scope, type TransformFn, type Transforms, VERSION, type ValidateOptions, type ValidationResult, type WrappedHandlers, assertValid, builders, compilePath, extractDeps, get, hasDeps, hasWildcard, isArrow, isCondition, isConditionExpr, isConditionGroup, isConditional, isFn, isLiteral, isPipe, isPure, isRef, isValid, normalizePath, validate };