yaml-flow 3.1.1 → 5.0.0

package/dist/card-compute/index.d.cts

@@ -20,12 +20,23 @@
  * Returns the same `ValidationResult` shape as `CardCompute.validate()`.
  */
 declare function validateLiveCardSchema(node: unknown): ValidationResult;
+/**
+ * Validate JSONata expressions in compute[] by compiling with the same parser used at runtime.
+ */
+declare function validateLiveCardRuntimeExpressions(node: unknown): ValidationResult;
+declare function validateLiveCard(node: unknown): ValidationResult;
+/**
+ * Full validation for live card definitions:
+ * 1) JSON Schema structure/contract checks
+ * 2) Runtime JSONata parser compatibility checks for compute expressions
+ */
+declare function validateLiveCardDefinition(node: unknown): ValidationResult;
 
 /**
- * card-compute — Pure JSON expression evaluator for node-based cards.
+ * card-compute — JSONata-powered compute engine for LiveCards nodes.
  *
  * Isomorphic: works in browser, Node.js, and bundlers.
- * No DOM dependency. No eval(). Pure declarative JSON expressions.
+ * No DOM dependency. Compute expressions are JSONata strings.
  *
  * @example
  * ```typescript
@@ -33,76 +44,93 @@ declare function validateLiveCardSchema(node: unknown): ValidationResult;
  *
  * const node = {
  *   id: 'sales',
- *   state: { data: [{ revenue: 100 }, { revenue: 200 }] },
- *   compute: {
- *     total: { fn: 'sum', input: 'state.data', field: 'revenue' },
- *     avg:   { fn: 'avg', input: 'state.data', field: 'revenue' },
- *   },
+ *   card_data: { data: [{ revenue: 100 }, { revenue: 200 }] },
+ *   compute: [
+ *     { bindTo: 'total', expr: '$sum(card_data.data.revenue)' },
+ *     { bindTo: 'avg',   expr: '$average(card_data.data.revenue)' },
+ *   ],
  * };
- * CardCompute.run(node);
- * // node.state.total === 300
- * // node.state.avg   === 150
+ * await CardCompute.run(node);
+ * // node.computed_values.total === 300
+ * // node.computed_values.avg   === 150
  * ```
+ *
+ * Expressions are evaluated against { card_data, requires, fetched_sources, computed_values }.
+ * computed_values is ephemeral — never persisted to disk.
  */
-/** A compute expression — pure JSON, arbitrarily nestable. */
-interface ComputeExpr {
-    fn: string;
-    input?: string | number | boolean | ComputeExpr | (string | number | boolean | ComputeExpr)[];
-    field?: string;
-    where?: ComputeExpr;
-    apply?: ComputeExpr;
-    cond?: ComputeExpr;
-    then?: unknown;
-    else?: unknown;
-    format?: string;
-    decimals?: number;
-    separator?: string;
-    direction?: 'asc' | 'desc';
-    start?: number;
-    end?: number;
-    depth?: number;
-    path?: string;
-    value?: unknown;
+/** A source definition: cli writes to outputFile; bindTo names the fetched_sources.* key in compute context. */
+interface ComputeSource {
+    bindTo: string;
+    outputFile?: string;
+    cli?: string;
+    script?: string;
+    optionalForCompletionGating?: boolean;
     [key: string]: unknown;
 }
+/** Options for CardCompute.run() */
+interface RunOptions {
+    /** Pre-loaded source results map (keyed by bindTo). Use in browser or when caller loads files. */
+    sourcesData?: Record<string, unknown>;
+}
+/** A single compute step: bindTo names the computed_values key; expr is a JSONata expression. */
+interface ComputeStep {
+    bindTo: string;
+    expr: string;
+}
 /** Minimal node shape expected by CardCompute. */
 interface ComputeNode {
     id?: string;
-    state?: Record<string, unknown>;
-    compute?: Record<string, ComputeExpr>;
+    card_data?: Record<string, unknown>;
+    requires?: Record<string, unknown>;
+    sources?: ComputeSource[];
+    compute?: ComputeStep[];
+    computed_values?: Record<string, unknown>;
+    /** Ephemeral: populated by run() from sourcesData option. Never persisted. */
+    _sourcesData?: Record<string, unknown>;
     [key: string]: unknown;
 }
-/** Internal evaluator signature passed to compute functions. */
-type EvalFn = (expr: unknown, node: ComputeNode) => unknown;
-/** A compute function implementation. */
-type ComputeFn = (input: unknown, evalFn: EvalFn, opts: ComputeExpr) => unknown;
-declare function evalExpr(expr: unknown, node: ComputeNode): unknown;
-declare function run(node: ComputeNode): ComputeNode;
+/**
+ * Run all compute steps on a node.
+ * Each step's expr is evaluated against { card_data, requires, fetched_sources, computed_values }.
+ * Results are written to node.computed_values[bindTo].
+ * computed_values and _sourcesData are reset on each call — ephemeral, never persisted.
+ *
+ * @param options.sourcesData  Pre-loaded map of { [bindTo]: data } for fetched_sources namespace.
+ *   In Node/CLI: loaded from outputFiles by the caller (card-handler).
+ *   In browser:  passed in by the caller (e.g. from fetch results).
+ */
+declare function run(node: ComputeNode, options?: RunOptions): Promise<ComputeNode>;
+/**
+ * Evaluate a single JSONata expression against a node's context.
+ * Context is { card_data, requires, fetched_sources, computed_values }.
+ */
+declare function evalExpr(expr: string, node: ComputeNode): Promise<unknown>;
 declare function resolve(node: ComputeNode, path: string): unknown;
-declare function registerFunction(name: string, fn: ComputeFn): void;
 /** Result of validateNode — ok: true means valid, ok: false has errors[]. */
 interface ValidationResult {
     ok: boolean;
     errors: string[];
 }
+declare function validateNode(node: unknown): ValidationResult;
 /**
- * Validate a node against the LiveCards schema.
- * Lightweight structural check — no external dependencies.
+ * Enrich sources with execution context for template interpolation and prompt rendering.
+ * Pure function: no side effects, returns new enriched sources array.
  *
- * @example
- * ```typescript
- * const result = CardCompute.validate(node);
- * if (!result.ok) console.error(result.errors);
- * ```
+ * @param sources - Array of source definitions
+ * @param context - Execution context containing requires, sourcesData, computed_values
+ * @returns New array of sources with _requires, _sourcesData, _computed_values attached
  */
-declare function validateNode(node: unknown): ValidationResult;
+declare function enrichSources(sources: any[] | undefined, context: {
+    requires?: Record<string, any>;
+    sourcesData?: Record<string, any>;
+    computed_values?: Record<string, any>;
+}): any[];
 declare const CardCompute: {
     run: typeof run;
     eval: typeof evalExpr;
     resolve: typeof resolve;
     validate: typeof validateNode;
-    registerFunction: typeof registerFunction;
-    readonly functions: Record<string, ComputeFn>;
+    enrichSources: typeof enrichSources;
 };
 
-export { CardCompute, type ComputeExpr, type ComputeFn, type ComputeNode, type EvalFn, type ValidationResult, CardCompute as default, validateLiveCardSchema };
+export { CardCompute, type ComputeNode, type ComputeSource, type ComputeStep, type RunOptions, type ValidationResult, CardCompute as default, validateLiveCard, validateLiveCardDefinition, validateLiveCardRuntimeExpressions, validateLiveCardSchema };

package/dist/card-compute/index.d.ts

@@ -20,12 +20,23 @@
  * Returns the same `ValidationResult` shape as `CardCompute.validate()`.
  */
 declare function validateLiveCardSchema(node: unknown): ValidationResult;
+/**
+ * Validate JSONata expressions in compute[] by compiling with the same parser used at runtime.
+ */
+declare function validateLiveCardRuntimeExpressions(node: unknown): ValidationResult;
+declare function validateLiveCard(node: unknown): ValidationResult;
+/**
+ * Full validation for live card definitions:
+ * 1) JSON Schema structure/contract checks
+ * 2) Runtime JSONata parser compatibility checks for compute expressions
+ */
+declare function validateLiveCardDefinition(node: unknown): ValidationResult;
 
 /**
- * card-compute — Pure JSON expression evaluator for node-based cards.
+ * card-compute — JSONata-powered compute engine for LiveCards nodes.
  *
  * Isomorphic: works in browser, Node.js, and bundlers.
- * No DOM dependency. No eval(). Pure declarative JSON expressions.
+ * No DOM dependency. Compute expressions are JSONata strings.
  *
  * @example
  * ```typescript
@@ -33,76 +44,93 @@ declare function validateLiveCardSchema(node: unknown): ValidationResult;
  *
  * const node = {
  *   id: 'sales',
- *   state: { data: [{ revenue: 100 }, { revenue: 200 }] },
- *   compute: {
- *     total: { fn: 'sum', input: 'state.data', field: 'revenue' },
- *     avg:   { fn: 'avg', input: 'state.data', field: 'revenue' },
- *   },
+ *   card_data: { data: [{ revenue: 100 }, { revenue: 200 }] },
+ *   compute: [
+ *     { bindTo: 'total', expr: '$sum(card_data.data.revenue)' },
+ *     { bindTo: 'avg',   expr: '$average(card_data.data.revenue)' },
+ *   ],
  * };
- * CardCompute.run(node);
- * // node.state.total === 300
- * // node.state.avg   === 150
+ * await CardCompute.run(node);
+ * // node.computed_values.total === 300
+ * // node.computed_values.avg   === 150
  * ```
+ *
+ * Expressions are evaluated against { card_data, requires, fetched_sources, computed_values }.
+ * computed_values is ephemeral — never persisted to disk.
  */
-/** A compute expression — pure JSON, arbitrarily nestable. */
-interface ComputeExpr {
-    fn: string;
-    input?: string | number | boolean | ComputeExpr | (string | number | boolean | ComputeExpr)[];
-    field?: string;
-    where?: ComputeExpr;
-    apply?: ComputeExpr;
-    cond?: ComputeExpr;
-    then?: unknown;
-    else?: unknown;
-    format?: string;
-    decimals?: number;
-    separator?: string;
-    direction?: 'asc' | 'desc';
-    start?: number;
-    end?: number;
-    depth?: number;
-    path?: string;
-    value?: unknown;
+/** A source definition: cli writes to outputFile; bindTo names the fetched_sources.* key in compute context. */
+interface ComputeSource {
+    bindTo: string;
+    outputFile?: string;
+    cli?: string;
+    script?: string;
+    optionalForCompletionGating?: boolean;
     [key: string]: unknown;
 }
+/** Options for CardCompute.run() */
+interface RunOptions {
+    /** Pre-loaded source results map (keyed by bindTo). Use in browser or when caller loads files. */
+    sourcesData?: Record<string, unknown>;
+}
+/** A single compute step: bindTo names the computed_values key; expr is a JSONata expression. */
+interface ComputeStep {
+    bindTo: string;
+    expr: string;
+}
 /** Minimal node shape expected by CardCompute. */
 interface ComputeNode {
     id?: string;
-    state?: Record<string, unknown>;
-    compute?: Record<string, ComputeExpr>;
+    card_data?: Record<string, unknown>;
+    requires?: Record<string, unknown>;
+    sources?: ComputeSource[];
+    compute?: ComputeStep[];
+    computed_values?: Record<string, unknown>;
+    /** Ephemeral: populated by run() from sourcesData option. Never persisted. */
+    _sourcesData?: Record<string, unknown>;
     [key: string]: unknown;
 }
-/** Internal evaluator signature passed to compute functions. */
-type EvalFn = (expr: unknown, node: ComputeNode) => unknown;
-/** A compute function implementation. */
-type ComputeFn = (input: unknown, evalFn: EvalFn, opts: ComputeExpr) => unknown;
-declare function evalExpr(expr: unknown, node: ComputeNode): unknown;
-declare function run(node: ComputeNode): ComputeNode;
+/**
+ * Run all compute steps on a node.
+ * Each step's expr is evaluated against { card_data, requires, fetched_sources, computed_values }.
+ * Results are written to node.computed_values[bindTo].
+ * computed_values and _sourcesData are reset on each call — ephemeral, never persisted.
+ *
+ * @param options.sourcesData  Pre-loaded map of { [bindTo]: data } for fetched_sources namespace.
+ *   In Node/CLI: loaded from outputFiles by the caller (card-handler).
+ *   In browser:  passed in by the caller (e.g. from fetch results).
+ */
+declare function run(node: ComputeNode, options?: RunOptions): Promise<ComputeNode>;
+/**
+ * Evaluate a single JSONata expression against a node's context.
+ * Context is { card_data, requires, fetched_sources, computed_values }.
+ */
+declare function evalExpr(expr: string, node: ComputeNode): Promise<unknown>;
 declare function resolve(node: ComputeNode, path: string): unknown;
-declare function registerFunction(name: string, fn: ComputeFn): void;
 /** Result of validateNode — ok: true means valid, ok: false has errors[]. */
 interface ValidationResult {
     ok: boolean;
     errors: string[];
 }
+declare function validateNode(node: unknown): ValidationResult;
 /**
- * Validate a node against the LiveCards schema.
- * Lightweight structural check — no external dependencies.
+ * Enrich sources with execution context for template interpolation and prompt rendering.
+ * Pure function: no side effects, returns new enriched sources array.
  *
- * @example
- * ```typescript
- * const result = CardCompute.validate(node);
- * if (!result.ok) console.error(result.errors);
- * ```
+ * @param sources - Array of source definitions
+ * @param context - Execution context containing requires, sourcesData, computed_values
+ * @returns New array of sources with _requires, _sourcesData, _computed_values attached
  */
-declare function validateNode(node: unknown): ValidationResult;
+declare function enrichSources(sources: any[] | undefined, context: {
+    requires?: Record<string, any>;
+    sourcesData?: Record<string, any>;
+    computed_values?: Record<string, any>;
+}): any[];
 declare const CardCompute: {
     run: typeof run;
     eval: typeof evalExpr;
     resolve: typeof resolve;
     validate: typeof validateNode;
-    registerFunction: typeof registerFunction;
-    readonly functions: Record<string, ComputeFn>;
+    enrichSources: typeof enrichSources;
 };
 
-export { CardCompute, type ComputeExpr, type ComputeFn, type ComputeNode, type EvalFn, type ValidationResult, CardCompute as default, validateLiveCardSchema };
+export { CardCompute, type ComputeNode, type ComputeSource, type ComputeStep, type RunOptions, type ValidationResult, CardCompute as default, validateLiveCard, validateLiveCardDefinition, validateLiveCardRuntimeExpressions, validateLiveCardSchema };