@statedelta-libs/expressions 3.0.0 → 3.2.0

package/dist/index.d.cts

@@ -91,29 +91,85 @@ type Expression = Literal | RefExpr | ConditionalExpr | FnExpr | PipeExpr | Arro
  */
 type CompiledFn<T = unknown, R = unknown> = (data: T) => R;
 /**
- * Result of compiling an expression
+ * Callable function bound to a context, with metadata as properties.
+ * Call directly — no `.fn` needed.
+ *
+ * @example
+ * const fn = artifact.bind({ scope, accessor });
+ * fn(data);          // callable direct
+ * fn.deps;           // ["hp", "armor"]
+ * fn.hash;           // "a1b2c3"
+ * items.map(fn);     // works as first-class function
+ */
+interface BoundFn<T = unknown, R = unknown> {
+    /** Execute the expression with the given data */
+    (data: T): R;
+    /** Paths this expression depends on */
+    readonly deps: string[];
+    /** Unique hash for caching */
+    readonly hash: string;
+}
+/**
+ * Create a BoundFn from a compiled function + metadata.
+ * Attaches deps and hash as readonly props.
  */
-interface CompiledExpression<T = unknown, R = unknown> {
-    /** Compiled function */
-    fn: CompiledFn<T, R>;
+declare function createBoundFn<T = unknown, R = unknown>(fn: CompiledFn<T, R>, deps: string[], hash: string): BoundFn<T, R>;
+/**
+ * Context-free compile artifact — result of compilation without pre-prepared fn.
+ * Stored in shared compile caches. Use bind() to attach context and get fn.
+ */
+interface CompileArtifact<T = unknown, R = unknown> {
     /** Paths this expression depends on */
     deps: string[];
     /** Unique hash for caching */
     hash: string;
+    /**
+     * Bind to a context and get a callable BoundFn.
+     * @param ctx - Runtime context (scope, accessor, handlers). Uses defaults if omitted.
+     */
+    bind(ctx?: BindContext): BoundFn<T, R>;
 }
+/**
+ * Context for bind() — runtime dependencies injected after compilation.
+ */
+interface BindContext {
+    scope?: Scope;
+    accessor?: AccessorFn;
+    handlers?: WrappedHandlers;
+}
+/**
+ * Alias for CompileArtifact — the public name going forward.
+ */
+type Artifact<T = unknown, R = unknown> = CompileArtifact<T, R>;
+/**
+ * Describes what each flat parameter of the compiled factory expects.
+ * Order matches the factory's parameter order.
+ */
+type ParamSlot = {
+    kind: "scope";
+    name: string;
+} | {
+    kind: "accessor";
+} | {
+    kind: "handler";
+    ns: string;
+    m: string;
+} | {
+    kind: "boundary";
+    index: number;
+};
 /**
  * Path getter function
  */
 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
  */
@@ -143,13 +199,46 @@ interface CompileOptions<T = unknown> {
      * Quando fornecido, substitui o acesso direto por propriedade.
      *
      * @example
-     * // Com TickContext
-     * compile(expr, { accessor: (path, ctx) => ctx.get(path) })
+     * compile(expr, { accessor: (path) => ctx.get(path) })
      */
-    accessor?: AccessorFn<T>;
+    accessor?: AccessorFn;
     /** Boundary definitions for compile-time interception */
     boundaries?: BoundaryDef<T>[];
+    /** Wrapped handlers (ctx already bound) for $fn "namespace:method" calls */
+    handlers?: WrappedHandlers;
 }
+/**
+ * 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.
+ *
+ * @example
+ * {
+ *   query: {
+ *     find(key: string) { return this.scope.add(key, 1); }
+ *   }
+ * }
+ */
+type HandlerFn = (...args: any[]) => any;
+/**
+ * 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(); },
+ *   },
+ * }
+ */
+type HandlersMap = Record<string, Record<string, HandlerFn>>;
+/**
+ * Wrapped handlers (ctx already bound via .bind()).
+ * Used internally by both pipelines.
+ */
+type WrappedHandlers = Record<string, Record<string, (...args: any[]) => any>>;
 /**
  * Boundary definition for compile-time interception.
  * Allows foreign DSLs and compilers to plug into the expression walk.
@@ -214,22 +303,77 @@ type TransformFn = (node: Record<string, unknown>) => Expression;
  */
 type Transforms = Record<string, TransformFn>;
 
+/**
+ * @statedelta-libs/expressions - JIT Compiler
+ *
+ * IR-based pipeline: receives IR from analyze(), emits optimized JS via AST.
+ * Factory with flat parameters — zero destructuring, zero property chains.
+ * No DSL knowledge — no guards, no type detection.
+ */
+
+/** Result when returnCode is true */
+interface JITCodeResult {
+    code: string;
+    deps: string[];
+    hash: string;
+    dataRoots: string[];
+    scopeFns: string[];
+    paramNames: string[];
+}
+
+/**
+ * @statedelta-libs/expressions - Cache
+ *
+ * LRU cache for compiled expressions and compile artifacts.
+ * Performance: cache hit ~10M ops/sec
+ */
+
+/**
+ * Shared compile cache — stores context-free CompileArtifacts.
+ * Can be shared between ExpressionCompiler instances for multi-tenant scenarios.
+ * Dual mode: separate closures and JIT caches.
+ */
+declare class CompileCache {
+    private closures;
+    private jit;
+    constructor(maxSize?: number);
+    /**
+     * Get or compile artifact by key and mode.
+     */
+    getOrCompile<V>(key: string, mode: "closures" | "jit", factory: () => V): V;
+    /**
+     * Cache size per mode
+     */
+    get size(): {
+        closures: number;
+        jit: number;
+    };
+    /**
+     * Clear both caches
+     */
+    clear(): void;
+}
+
 /**
  * @statedelta-libs/expressions - ExpressionCompiler
  *
  * Unified public API for expression compilation.
- * Centralizes scope, accessor, and cache in a single reusable instance.
+ * Phase 4: two-level cache (instance + shared compile), DI-first pattern.
  */
 
 interface ExpressionCompilerOptions<T = unknown> {
     /** Functions available to $fn expressions */
     scope?: Scope;
     /** Custom accessor for resolving paths */
-    accessor?: AccessorFn<T>;
+    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;
+    /** Shared compile cache — enables cross-instance cache sharing */
+    compileCache?: CompileCache;
 }
 interface JITOptions {
     /** Use accessor to resolve paths instead of direct access */
@@ -237,34 +381,84 @@ interface JITOptions {
     /** Prefix for paths that bypass accessor (direct access) */
     lexicalPrefix?: string;
 }
+interface CompileConfig {
+    /** Use accessor to resolve paths instead of direct access */
+    useAccessor?: boolean;
+}
+interface EvalOptions {
+    /** Pipeline: "closures" (default) or "jit" */
+    mode?: "closures" | "jit";
+    /** Use accessor to resolve paths instead of direct access */
+    useAccessor?: boolean;
+}
+/**
+ * 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 compileCache?;
     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;
+    /** Compile via closure composition — DSL → IR → closures */
+    compile<R = unknown>(expr: Expression, opts?: CompileConfig): CompileArtifact<T, R>;
+    /** Compile via JS code generation (JIT) — DSL → IR → AST → JS */
+    jit<R = unknown>(expr: Expression, opts?: JITOptions): CompileArtifact<T, R>;
+    /** Return generated JS code without creating function — for inspection/testing */
+    jitCode(expr: Expression, opts?: JITOptions): JITCodeResult;
+    /** Compile, bind with default context, and execute in one step */
+    eval<R = unknown>(expr: Expression, data: T, opts?: EvalOptions): R;
+    /**
+     * 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`.
+     */
+    private wrapHandlers;
     /** Normalize custom expression to pure DSL */
     normalize(expr: Expression, transforms: Transforms): Expression;
     /** Extract dependencies without compiling */
     extractDeps(expr: Expression): string[];
-    /** Cache size per mode */
+    /** Instance cache size per mode */
     get cacheSize(): {
         closures: number;
         jit: number;
     };
-    /** Clear both caches */
+    /** Clear instance caches */
     clearCache(): void;
     /** Read-only access to scope */
     getScope(): Readonly<Scope>;
+    /**
+     * Get or create compile artifact.
+     * Two-level: compile cache (shared, optional) → fresh compile.
+     */
+    private getArtifact;
+    /**
+     * Full compile: analyze → backend → CompileArtifact.
+     */
+    private doCompile;
+    /**
+     * Default BindContext from constructor options.
+     */
+    private defaultCtx;
+    /**
+     * Build compile cache key including compile-time flags.
+     */
+    private compileCacheKey;
 }
 
 /**
@@ -465,6 +659,10 @@ 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 any Expression DSL node
+ */
+declare const isExpression: (v: unknown) => boolean;
 /**
  * Check if value is a literal (not an expression object)
  */
@@ -484,6 +682,8 @@ interface ValidateOptions {
     scope?: Scope;
     /** Boundary definitions — matched nodes skip validation */
     boundaries?: BoundaryDef[];
+    /** Handlers map to validate handler names against (optional) */
+    handlers?: HandlersMap;
 }
 /**
  * Validate expression structure
@@ -550,6 +750,93 @@ declare function hasDeps(expr: Expression): boolean;
  */
 declare function isPure(expr: Expression): boolean;
 
+/**
+ * Template Compiler — Types
+ *
+ * Declarative template system for compiling arbitrary JSON structures
+ * using ExpressionCompiler as the engine.
+ */
+
+type SchemaType = "string" | "number" | "boolean" | "string[]" | "number[]" | "enum" | "schema" | "object" | "any";
+interface SchemaFieldDef {
+    type: SchemaType;
+    required?: boolean;
+    default?: unknown;
+    values?: string[];
+}
+interface FieldHandlerOptions {
+    allow?: string[];
+    deny?: string[];
+    transforms?: Transforms;
+    mode?: "closures" | "jit";
+}
+type FieldHandler = (value: unknown, compiler: ExpressionCompiler, options: FieldHandlerOptions) => unknown;
+type CompileFieldDef = {
+    compile: "condition";
+} | {
+    compile: "expression";
+} | {
+    compile: string;
+    allow?: string[];
+    deny?: string[];
+} | {
+    compile: FieldHandler;
+    allow?: string[];
+    deny?: string[];
+    [key: string]: unknown;
+};
+type FieldDef = CompileFieldDef | SchemaFieldDef;
+type DefinitionTemplate = Record<string, FieldDef>;
+interface CompileDefinitionOptions {
+    transforms?: Transforms;
+    mode?: "closures" | "jit";
+    validate?: boolean;
+    handlers?: Record<string, FieldHandler>;
+}
+interface CompiledDefinition<T = unknown> {
+    [field: string]: unknown;
+    /** Bind to a context — re-binds all compiled fields */
+    bind(ctx: BindContext): CompiledDefinition<T>;
+}
+type DefinitionValidationErrorType = "unknown_field" | "missing_required" | "type_mismatch" | "invalid_enum";
+interface DefinitionValidationError {
+    field: string;
+    message: string;
+    type: DefinitionValidationErrorType;
+}
+interface DefinitionValidationResult {
+    valid: boolean;
+    errors: DefinitionValidationError[];
+}
+declare function isCompileField(def: FieldDef): def is CompileFieldDef;
+declare function isSchemaField(def: FieldDef): def is SchemaFieldDef;
+declare function isNativeCompile(def: CompileFieldDef): def is {
+    compile: "condition";
+} | {
+    compile: "expression";
+};
+declare function isHandlerCompile(def: CompileFieldDef): def is {
+    compile: FieldHandler;
+    [key: string]: unknown;
+};
+
+/**
+ * Template Compiler — Core Compilation
+ *
+ * compileDefinition(): validates, normalizes, compiles, and assembles
+ * a JSON structure using a template + ExpressionCompiler.
+ */
+
+declare function compileDefinition<T = unknown>(dsl: Record<string, unknown>, template: DefinitionTemplate, compiler: ExpressionCompiler, options?: CompileDefinitionOptions): CompiledDefinition<T>;
+
+/**
+ * Template Compiler — Validation
+ *
+ * Validates a DSL object against a DefinitionTemplate.
+ */
+
+declare function validateDefinition(dsl: Record<string, unknown>, template: DefinitionTemplate): DefinitionValidationResult;
+
 /**
  * @statedelta-libs/expressions
  *
@@ -558,4 +845,4 @@ declare function isPure(expr: Expression): boolean;
  */
 declare const VERSION = "3.0.0";
 
-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 };
+export { type AccessorFn, type ArrowExpr, type Artifact, type BindContext, type BoundFn, type BoundaryDef, type CompileArtifact, CompileCache, type CompileConfig, type CompileDefinitionOptions, type CompileFieldDef, type CompileOptions, type CompiledDefinition, type CompiledFn, type Condition, type ConditionExpr, type ConditionGroup, type ConditionOp, type ConditionalExpr, type DefinitionTemplate, type DefinitionValidationError, type DefinitionValidationErrorType, type DefinitionValidationResult, type EvalOptions, type Expression, ExpressionCompiler, type ExpressionCompilerOptions, type FieldDef, type FieldHandler, type FieldHandlerOptions, type FnExpr, type HandlerContext, type HandlerFn, type HandlersMap, type JITCodeResult, type JITOptions, type Literal, type ParamSlot, type PipeExpr, type RefExpr, type SchemaFieldDef, type SchemaType, type Scope, type TransformFn, type Transforms, VERSION, type ValidateOptions, type ValidationResult, type WrappedHandlers, assertValid, builders, compileDefinition, compilePath, createBoundFn, extractDeps, get, hasDeps, hasWildcard, isArrow, isCompileField, isCondition, isConditionExpr, isConditionGroup, isConditional, isExpression, isFn, isHandlerCompile, isLiteral, isNativeCompile, isPipe, isPure, isRef, isSchemaField, isValid, normalizePath, validate, validateDefinition };