From 69dbd2c61ea7c988721a93821b56c9325f308822 Mon Sep 17 00:00:00 2001 From: atinseau Date: Tue, 17 Mar 2026 11:32:00 +0100 Subject: [PATCH] feat(executor/analyzer): support aggregated array identifier data Co-Authored-By: Claude Opus 4.6 (1M context) --- src/analyzer.ts | 50 +- src/compiled-template.ts | 3 +- src/dispatch.ts | 4 +- src/executor.ts | 47 +- src/index.ts | 2 + src/types.ts | 57 +- tests/aggregated-identifiers.spec.ts | 1129 ++++++++++++++++++++++++++ 7 files changed, 1275 insertions(+), 17 deletions(-) create mode 100644 tests/aggregated-identifiers.spec.ts diff --git a/src/analyzer.ts b/src/analyzer.ts index 28e321d..403d243 100644 --- a/src/analyzer.ts +++ b/src/analyzer.ts @@ -1102,6 +1102,10 @@ function resolveExpressionWithDiagnostics( * a plain `{{$root}}`. Instead of navigating into properties, it returns * the identifier's root schema directly. * + * When the identifier schema is an array (aggregated multi-version data), + * the full array schema is returned as-is — the caller receives the + * complete `{ type: "array", items: ... }` schema. + * * Emits an error diagnostic if: * - No `identifierSchemas` were provided * - Identifier N has no associated schema @@ -1138,7 +1142,9 @@ function resolveRootWithIdentifier( return undefined; } - // Return the entire schema for identifier N + // Return the entire schema for identifier N. + // For aggregated identifiers (array schemas), this returns the full + // array schema — e.g. { type: "array", items: { type: "object", ... } } return idSchema; } @@ -1146,6 +1152,12 @@ function resolveRootWithIdentifier( * Resolves an expression with identifier `{{key:N}}` by looking up the * schema associated with identifier N. * + * When the identifier schema is an array (aggregated multi-version data), + * the property is resolved within the array's `items` schema, and the + * result is wrapped in `{ type: "array", items: }`. This + * models the runtime behavior where `{{accountId:4}}` on an array of + * objects extracts the property from each element, producing an array. + * * Emits an error diagnostic if: * - No `identifierSchemas` were provided * - Identifier N has no associated schema @@ -1186,7 +1198,41 @@ function resolveWithIdentifier( return undefined; } - // Resolve the path within the identifier's schema + // ── Aggregated identifier (array schema) ───────────────────────────── + // When the identifier schema is an array of objects (e.g. from a + // multi-versioned workflow node), resolve the property within the + // items schema and wrap the result in an array type. + // + // Example: identifierSchemas[4] = { type: "array", items: { type: "object", + // properties: { accountId: { type: "string" } } } } + // Expression: {{accountId:4}} + // Result: { type: "array", items: { type: "string" } } + const itemSchema = resolveArrayItems(idSchema, ctx.root); + if (itemSchema !== undefined) { + // The identifier schema is an array — resolve within items + const resolved = resolveSchemaPath(itemSchema, cleanSegments); + if (resolved === undefined) { + const availableProperties = getSchemaPropertyNames(itemSchema); + addDiagnostic( + ctx, + "IDENTIFIER_PROPERTY_NOT_FOUND", + "error", + `Property "${fullPath}" does not exist in the items schema for identifier ${identifier}`, + node, + { + path: fullPath, + identifier, + availableProperties, + }, + ); + return undefined; + } + // Wrap the resolved property schema in an array + return { type: "array", items: resolved }; + } + + // ── Standard identifier (single object schema) ─────────────────────── + // Resolve the path within the identifier's schema directly. const resolved = resolveSchemaPath(idSchema, cleanSegments); if (resolved === undefined) { const availableProperties = getSchemaPropertyNames(idSchema); diff --git a/src/compiled-template.ts b/src/compiled-template.ts index c4a6a5d..be56b87 100644 --- a/src/compiled-template.ts +++ b/src/compiled-template.ts @@ -9,6 +9,7 @@ import type { AnalysisResult, ExecuteOptions, HelperDefinition, + IdentifierData, TemplateData, ValidationResult, } from "./types.ts"; @@ -392,7 +393,7 @@ export class CompiledTemplate { data: TemplateData, options?: { identifierSchemas?: Record; - identifierData?: Record>; + identifierData?: IdentifierData; coerceSchema?: JSONSchema7; }, ): { analysis: AnalysisResult; value: unknown } { diff --git a/src/dispatch.ts b/src/dispatch.ts index 57510c9..95d9ef2 100644 --- a/src/dispatch.ts +++ b/src/dispatch.ts @@ -1,7 +1,7 @@ import type { JSONSchema7 } from "json-schema"; import { hasHandlebarsExpression } from "./parser.ts"; import { resolveSchemaPath } from "./schema-resolver.ts"; -import type { AnalysisResult, TemplateInput } from "./types.ts"; +import type { AnalysisResult, IdentifierData, TemplateInput } from "./types.ts"; import { inferPrimitiveSchema, isArrayInput, @@ -219,7 +219,7 @@ export function dispatchExecute( /** Options for combined analyze-and-execute dispatching */ export interface DispatchAnalyzeAndExecuteOptions { identifierSchemas?: Record; - identifierData?: Record>; + identifierData?: IdentifierData; coerceSchema?: JSONSchema7; /** When true, exclude entries containing Handlebars expressions */ excludeTemplateExpression?: boolean; diff --git a/src/executor.ts b/src/executor.ts index eb6ce2e..0d79ecf 100644 --- a/src/executor.ts +++ b/src/executor.ts @@ -18,7 +18,11 @@ import { parse, ROOT_TOKEN, } from "./parser.ts"; -import type { HelperDefinition, TemplateInput } from "./types.ts"; +import type { + HelperDefinition, + IdentifierData, + TemplateInput, +} from "./types.ts"; import { LRUCache } from "./utils.ts"; // ─── Template Executor ─────────────────────────────────────────────────────── @@ -58,8 +62,14 @@ import { LRUCache } from "./utils.ts"; /** Optional context for execution (used by Typebars/CompiledTemplate) */ export interface ExecutorContext { - /** Data by identifier `{ [id]: { key: value } }` */ - identifierData?: Record>; + /** + * Data by identifier `{ [id]: { key: value } }`. + * + * Each identifier can map to a single object (standard) or an array + * of objects (aggregated multi-version data). When the value is an + * array, `{{key:N}}` extracts the property from each element. + */ + identifierData?: IdentifierData; /** Pre-compiled Handlebars template (for CompiledTemplate) */ compiledTemplate?: HandlebarsTemplateDelegate; /** Isolated Handlebars environment (for custom helpers) */ @@ -100,7 +110,7 @@ const globalCompilationCache = new LRUCache( export function execute( template: TemplateInput, data: unknown, - identifierData?: Record>, + identifierData?: IdentifierData, ): unknown { return dispatchExecute( template, @@ -274,7 +284,7 @@ function coerceValue(raw: string, coerceSchema?: JSONSchema7): unknown { function executeFastPath( ast: hbs.AST.Program, data: unknown, - identifierData?: Record>, + identifierData?: IdentifierData, ): string { let result = ""; @@ -316,7 +326,7 @@ function executeFastPath( function resolveExpression( expr: hbs.AST.Expression, data: unknown, - identifierData?: Record>, + identifierData?: IdentifierData, helpers?: Map, ): unknown { // this / . → return the entire context @@ -398,6 +408,16 @@ function resolveExpression( if (identifier !== null && identifierData) { const source = identifierData[identifier]; if (source) { + // ── Aggregated identifier (array of objects) ────────────────── + // When the identifier maps to an array of objects (multi-version + // data), extract the property from each element to produce a + // result array. E.g. {{accountId:4}} on [{accountId:"A"},{accountId:"B"}] + // → ["A", "B"] + if (Array.isArray(source)) { + return source + .map((item) => resolveDataPath(item, cleanSegments)) + .filter((v) => v !== undefined); + } return resolveDataPath(source, cleanSegments); } // Source does not exist → undefined (like a missing key) @@ -465,7 +485,7 @@ export function resolveDataPath(data: unknown, segments: string[]): unknown { */ function mergeDataWithIdentifiers( data: unknown, - identifierData?: Record>, + identifierData?: IdentifierData, ): Record { // Always include $root so that Handlebars can resolve {{$root}} in // mixed templates and block helpers (where we delegate to Handlebars @@ -483,9 +503,20 @@ function mergeDataWithIdentifiers( for (const [id, idData] of Object.entries(identifierData)) { // Add `$root:N` so Handlebars can resolve {{$root:N}} in mixed/block // templates (where we delegate to Handlebars instead of resolving - // expressions ourselves). The value is the entire identifier data object. + // expressions ourselves). The value is the entire identifier data + // object (or array for aggregated identifiers). merged[`${ROOT_TOKEN}:${id}`] = idData; + // ── Aggregated identifier (array of objects) ───────────────── + // When the identifier data is an array (multi-version), we cannot + // flatten individual properties into `"key:N"` keys because there + // are multiple values per key. The array is only accessible via + // `$root:N` (already set above). Handlebars helpers like `map` + // can then consume it: `{{ map ($root:4) "accountId" }}`. + if (Array.isArray(idData)) { + continue; + } + for (const [key, value] of Object.entries(idData)) { merged[`${key}:${id}`] = value; } diff --git a/src/index.ts b/src/index.ts index 41e9c7e..fa3e9af 100644 --- a/src/index.ts +++ b/src/index.ts @@ -3,6 +3,8 @@ export * from "./errors"; export { Typebars } from "./typebars"; export { defineHelper, + type IdentifierData, + type IdentifierDataEntry, isArrayInput, type TemplateData, type TemplateInput, diff --git a/src/types.ts b/src/types.ts index 8109434..3f2940d 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,6 +1,43 @@ import type { JSONSchema7 } from "json-schema"; import type { FromSchema, JSONSchema } from "json-schema-to-ts"; +// ─── Identifier Data ───────────────────────────────────────────────────────── +// Maps template identifier integers to their associated data objects. +// +// Each identifier can hold either: +// - A **single object** — the standard case (one data source per identifier) +// - An **array of objects** — the aggregated case (multiple versions of a +// node merged into a collection, e.g. from a multi-versioned workflow node) +// +// When the value is an array, expressions like `{{key:N}}` automatically +// extract the property from each element, producing a result array. +// The full array is accessible via `{{$root:N}}` and can be used with +// the `map` helper: `{{ map ($root:N) "property" }}`. + +/** + * Data associated with a single template identifier. + * + * Can be a single record (scalar case) or an array of records + * (aggregated multi-version case). + */ +export type IdentifierDataEntry = + | Record + | Record[]; + +/** + * Mapping from template identifier integers to their data. + * + * @example + * ```ts + * // Scalar identifiers (standard) + * { 1: { meetingId: "abc" }, 2: { name: "Alice" } } + * + * // Aggregated identifier (multi-version node) + * { 4: [{ accountId: "A" }, { accountId: "B" }, { accountId: "C" }] } + * ``` + */ +export type IdentifierData = Record; + // ─── Template Input ────────────────────────────────────────────────────────── // The engine accepts primitive values in addition to template strings. // When a non-string value is passed, it is treated as a literal passthrough: @@ -309,8 +346,14 @@ export interface CommonTypebarsOptions { export interface ExecuteOptions extends CommonTypebarsOptions { /** JSON Schema for pre-execution static validation */ schema?: JSONSchema7; - /** Data by identifier `{ [id]: { key: value } }` */ - identifierData?: Record>; + /** + * Data by identifier `{ [id]: { key: value } }`. + * + * Each identifier can map to a single object (standard) or an array + * of objects (aggregated multi-version data). When the value is an + * array, `{{key:N}}` extracts the property from each element. + */ + identifierData?: IdentifierData; /** Schemas by identifier (for static validation with identifiers) */ identifierSchemas?: Record; } @@ -322,8 +365,14 @@ export interface ExecuteOptions extends CommonTypebarsOptions { export interface AnalyzeAndExecuteOptions extends CommonTypebarsOptions { /** Schemas by identifier `{ [id]: JSONSchema7 }` for static analysis */ identifierSchemas?: Record; - /** Data by identifier `{ [id]: { key: value } }` for execution */ - identifierData?: Record>; + /** + * Data by identifier `{ [id]: { key: value } }` for execution. + * + * Each identifier can map to a single object (standard) or an array + * of objects (aggregated multi-version data). When the value is an + * array, `{{key:N}}` extracts the property from each element. + */ + identifierData?: IdentifierData; } // ─── Custom Helpers ────────────────────────────────────────────────────────── diff --git a/tests/aggregated-identifiers.spec.ts b/tests/aggregated-identifiers.spec.ts new file mode 100644 index 0000000..16e5ae9 --- /dev/null +++ b/tests/aggregated-identifiers.spec.ts @@ -0,0 +1,1129 @@ +import { beforeEach, describe, expect, test } from "bun:test"; +import type { JSONSchema7 } from "json-schema"; +import { analyze } from "../src/analyzer.ts"; +import { clearCompilationCache, execute } from "../src/executor.ts"; +import { Typebars } from "../src/typebars.ts"; + +// ═════════════════════════════════════════════════════════════════════════════ +// Aggregated Identifier Data — Full Feature Tests +// ═════════════════════════════════════════════════════════════════════════════ +// +// These tests verify the support for aggregated (array) identifier data, +// where `identifierData[N]` maps to an array of objects instead of a single +// object. This is the key building block for consuming multi-versioned +// workflow node outputs at a merge point. +// +// When identifierData[N] is an array: +// - `{{key:N}}` → extracts `key` from each element → produces an array +// - `{{$root:N}}` → returns the entire array of objects +// +// When identifierSchemas[N] is an array schema: +// - `{{key:N}}` → inferred as { type: "array", items: } +// - `{{$root:N}}` → returns the full array schema as-is +// +// NOTE: `($root:N)` CANNOT be used as a Handlebars sub-expression argument +// (e.g. `{{ map ($root:4) "key" }}`), because Handlebars parses sub-expressions +// as helper calls, not data paths. The `{{key:N}}` direct extraction syntax +// is the primary way to consume aggregated data. + +// ─── Fixtures ──────────────────────────────────────────────────────────────── + +const aggregatedData: Record[] = [ + { accountId: "A", amount: 100, active: true }, + { accountId: "B", amount: 200, active: false }, + { accountId: "C", amount: 300, active: true }, +]; + +const aggregatedSchema: JSONSchema7 = { + type: "array", + items: { + type: "object", + properties: { + accountId: { type: "string" }, + amount: { type: "number" }, + active: { type: "boolean" }, + }, + }, +}; + +const scalarData = { seqOutput: "hello", count: 42 }; +const scalarSchema: JSONSchema7 = { + type: "object", + properties: { + seqOutput: { type: "string" }, + count: { type: "number" }, + }, +}; + +// ═════════════════════════════════════════════════════════════════════════════ +// SECTION 1 : Execution — standalone execute() +// ═════════════════════════════════════════════════════════════════════════════ + +describe("Aggregated identifiers — execute()", () => { + beforeEach(() => { + clearCompilationCache(); + }); + + // ─── Basic property extraction ─────────────────────────────────────── + + describe("basic property extraction from aggregated data", () => { + test("{{accountId:4}} extracts string property from each element → string[]", () => { + const result = execute("{{accountId:4}}", {}, { 4: aggregatedData }); + expect(result).toEqual(["A", "B", "C"]); + }); + + test("{{amount:4}} extracts number property from each element → number[]", () => { + const result = execute("{{amount:4}}", {}, { 4: aggregatedData }); + expect(result).toEqual([100, 200, 300]); + }); + + test("{{active:4}} extracts boolean property from each element → boolean[]", () => { + const result = execute("{{active:4}}", {}, { 4: aggregatedData }); + expect(result).toEqual([true, false, true]); + }); + + test("extracts property that doesn't exist in some items → filters out undefined", () => { + const data = [ + { accountId: "A", extra: "x" }, + { accountId: "B" }, + { accountId: "C", extra: "z" }, + ]; + const result = execute("{{extra:4}}", {}, { 4: data }); + expect(result).toEqual(["x", "z"]); + }); + + test("extracts property that doesn't exist in any item → empty array", () => { + const result = execute("{{nonexistent:4}}", {}, { 4: aggregatedData }); + expect(result).toEqual([]); + }); + }); + + // ─── $root access ──────────────────────────────────────────────────── + + describe("$root with aggregated identifier", () => { + test("{{$root:4}} returns the entire array of objects", () => { + const result = execute("{{$root:4}}", {}, { 4: aggregatedData }); + expect(result).toEqual(aggregatedData); + }); + + test("{{$root:4}} returns empty array when identifier data is []", () => { + const result = execute("{{$root:4}}", {}, { 4: [] }); + expect(result).toEqual([]); + }); + }); + + // ─── Mixed scalar and aggregated identifiers ───────────────────────── + + describe("mixing scalar and aggregated identifiers", () => { + test("scalar identifier still works alongside aggregated", () => { + const result = execute( + "{{seqOutput:2}}", + {}, + { + 2: scalarData, + 4: aggregatedData, + }, + ); + expect(result).toBe("hello"); + }); + + test("aggregated identifier works alongside scalar", () => { + const result = execute( + "{{accountId:4}}", + {}, + { + 2: scalarData, + 4: aggregatedData, + }, + ); + expect(result).toEqual(["A", "B", "C"]); + }); + + test("mixed template: scalar + aggregated in same template → string concatenation", () => { + const result = execute( + "output: {{seqOutput:2}} ids: {{accountId:4}}", + {}, + { + 2: scalarData, + 4: aggregatedData, + }, + ); + expect(typeof result).toBe("string"); + // Arrays are stringified via String() → "A,B,C" + expect(result).toBe("output: hello ids: A,B,C"); + }); + }); + + // ─── Edge cases ────────────────────────────────────────────────────── + + describe("edge cases", () => { + test("single-element array → returns array with one element", () => { + const result = execute( + "{{accountId:4}}", + {}, + { 4: [{ accountId: "only" }] }, + ); + expect(result).toEqual(["only"]); + }); + + test("empty array → returns empty array", () => { + const result = execute("{{accountId:4}}", {}, { 4: [] }); + expect(result).toEqual([]); + }); + + test("identifier 0 with aggregated data", () => { + const result = execute( + "{{accountId:0}}", + {}, + { 0: [{ accountId: "zero" }] }, + ); + expect(result).toEqual(["zero"]); + }); + + test("negative identifier with aggregated data", () => { + const result = execute( + "{{accountId:-1}}", + {}, + { [-1]: [{ accountId: "neg" }] }, + ); + expect(result).toEqual(["neg"]); + }); + + test("aggregated data with nested object property", () => { + const data = [{ info: { city: "Paris" } }, { info: { city: "London" } }]; + const result = execute("{{info.city:4}}", {}, { 4: data }); + expect(result).toEqual(["Paris", "London"]); + }); + + test("non-existent identifier returns undefined (not affected by aggregated data elsewhere)", () => { + const result = execute("{{accountId:99}}", {}, { 4: aggregatedData }); + expect(result).toBeUndefined(); + }); + + test("aggregated with null values in items", () => { + const data = [ + { accountId: "A", value: null }, + { accountId: "B", value: null }, + ]; + const result = execute("{{value:4}}", {}, { 4: data }); + expect(result).toEqual([null, null]); + }); + + test("aggregated with mixed types in items", () => { + const data = [{ value: "string" }, { value: 42 }, { value: true }]; + const result = execute("{{value:4}}", {}, { 4: data }); + expect(result).toEqual(["string", 42, true]); + }); + }); + + // ─── Interaction with main data ────────────────────────────────────── + + describe("interaction with main data context", () => { + test("non-identifier expression resolves from data, not from aggregated identifierData", () => { + const result = execute( + "{{name}}", + { name: "Alice" }, + { 4: aggregatedData }, + ); + expect(result).toBe("Alice"); + }); + + test("non-identifier and aggregated identifier coexist", () => { + const result = execute( + "{{name}} {{accountId:4}}", + { name: "Alice" }, + { 4: aggregatedData }, + ); + expect(result).toBe("Alice A,B,C"); + }); + }); + + // ─── Fast-path execution ───────────────────────────────────────────── + + describe("fast-path execution (text + simple expressions)", () => { + test("aggregated values are stringified in fast-path concatenation", () => { + const result = execute("IDs: {{accountId:4}}", {}, { 4: aggregatedData }); + expect(typeof result).toBe("string"); + expect(result).toBe("IDs: A,B,C"); + }); + + test("multiple aggregated expressions in fast-path", () => { + const result = execute( + "{{accountId:4}} / {{amount:4}}", + {}, + { 4: aggregatedData }, + ); + expect(result).toBe("A,B,C / 100,200,300"); + }); + }); +}); + +// ═════════════════════════════════════════════════════════════════════════════ +// SECTION 2 : Static Analysis — standalone analyze() +// ═════════════════════════════════════════════════════════════════════════════ + +describe("Aggregated identifiers — analyze()", () => { + beforeEach(() => { + clearCompilationCache(); + }); + + // ─── Output schema inference ───────────────────────────────────────── + + describe("output schema inference with array identifierSchemas", () => { + test("{{accountId:4}} on array schema → { type: 'array', items: { type: 'string' } }", () => { + const result = analyze( + "{{accountId:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + }); + }); + + test("{{amount:4}} on array schema → { type: 'array', items: { type: 'number' } }", () => { + const result = analyze( + "{{amount:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "number" }, + }); + }); + + test("{{active:4}} on array schema → { type: 'array', items: { type: 'boolean' } }", () => { + const result = analyze( + "{{active:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "boolean" }, + }); + }); + + test("{{$root:4}} on array schema → returns full array schema", () => { + const result = analyze( + "{{$root:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual(aggregatedSchema); + }); + }); + + // ─── Error diagnostics ─────────────────────────────────────────────── + + describe("error diagnostics for aggregated identifiers", () => { + test("invalid: property does not exist in items schema → IDENTIFIER_PROPERTY_NOT_FOUND", () => { + const result = analyze( + "{{nonexistent:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(false); + const errors = result.diagnostics.filter((d) => d.severity === "error"); + expect(errors.length).toBeGreaterThan(0); + expect(errors[0]?.code).toBe("IDENTIFIER_PROPERTY_NOT_FOUND"); + }); + + test("invalid: identifier not found → UNKNOWN_IDENTIFIER", () => { + const result = analyze( + "{{accountId:99}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(false); + const errors = result.diagnostics.filter((d) => d.severity === "error"); + expect(errors[0]?.code).toBe("UNKNOWN_IDENTIFIER"); + }); + + test("invalid: no identifierSchemas provided → MISSING_IDENTIFIER_SCHEMAS", () => { + const result = analyze("{{accountId:4}}", {}); + expect(result.valid).toBe(false); + const errors = result.diagnostics.filter((d) => d.severity === "error"); + expect(errors[0]?.code).toBe("MISSING_IDENTIFIER_SCHEMAS"); + }); + + test("error message mentions 'items schema' for aggregated identifiers", () => { + const result = analyze( + "{{nonexistent:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + const errors = result.diagnostics.filter((d) => d.severity === "error"); + expect(errors[0]?.message).toContain("items schema"); + }); + + test("available properties are reported from items schema", () => { + const result = analyze( + "{{nonexistent:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + const errors = result.diagnostics.filter((d) => d.severity === "error"); + expect(errors[0]?.details?.availableProperties).toContain("accountId"); + expect(errors[0]?.details?.availableProperties).toContain("amount"); + expect(errors[0]?.details?.availableProperties).toContain("active"); + }); + }); + + // ─── Coexistence with scalar identifiers ───────────────────────────── + + describe("mixing scalar and aggregated identifier schemas", () => { + test("scalar identifier infers scalar type, aggregated infers array type", () => { + const idSchemas: Record = { + 2: scalarSchema, + 4: aggregatedSchema, + }; + + const resultScalar = analyze( + "{{seqOutput:2}}", + {}, + { + identifierSchemas: idSchemas, + }, + ); + expect(resultScalar.valid).toBe(true); + expect(resultScalar.outputSchema).toEqual({ type: "string" }); + + const resultAggregated = analyze( + "{{accountId:4}}", + {}, + { + identifierSchemas: idSchemas, + }, + ); + expect(resultAggregated.valid).toBe(true); + expect(resultAggregated.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + }); + }); + + test("mixed template with scalar and aggregated → always string", () => { + const idSchemas: Record = { + 2: scalarSchema, + 4: aggregatedSchema, + }; + + const result = analyze( + "output: {{seqOutput:2}} ids: {{accountId:4}}", + {}, + { identifierSchemas: idSchemas }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: "string" }); + }); + }); + + // ─── Nested property resolution ────────────────────────────────────── + + describe("nested property resolution in aggregated items", () => { + test("resolves nested properties through items schema", () => { + const nestedSchema: JSONSchema7 = { + type: "array", + items: { + type: "object", + properties: { + info: { + type: "object", + properties: { + city: { type: "string" }, + }, + }, + }, + }, + }; + + const result = analyze( + "{{info.city:4}}", + {}, + { + identifierSchemas: { 4: nestedSchema }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + }); + }); + }); + + // ─── Array schema with $ref ────────────────────────────────────────── + + describe("array schema with $ref in items", () => { + test("resolves $ref in items schema for aggregated identifier", () => { + const schemaWithRef: JSONSchema7 = { + type: "array", + items: { $ref: "#/definitions/Account" }, + definitions: { + Account: { + type: "object", + properties: { + accountId: { type: "string" }, + }, + }, + }, + }; + + // For $ref resolution, the root schema used by the analyzer + // is the inputSchema (ctx.root). Since identifierSchemas are + // independent, we place the definitions where the resolver can + // find them. The analyzer's ctx.root is the inputSchema — but + // resolveSchemaPath in resolveWithIdentifier uses idSchema itself, + // so the $ref must be resolvable within the idSchema. + // resolveSchemaPath calls resolveRef which needs root — which is + // the inputSchema. So we pass the definitions in the inputSchema. + const inputSchema: JSONSchema7 = { + type: "object", + definitions: { + Account: { + type: "object", + properties: { + accountId: { type: "string" }, + }, + }, + }, + }; + + const result = analyze("{{accountId:4}}", inputSchema, { + identifierSchemas: { 4: schemaWithRef }, + }); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + }); + }); + }); + + // ─── Array without items ───────────────────────────────────────────── + + describe("array schema without items", () => { + test("array schema without items → resolves within {} (empty schema)", () => { + const schemaNoItems: JSONSchema7 = { type: "array" }; + + // When there are no items, resolveArrayItems returns {}. + // Resolving any property within {} succeeds with undefined, + // which causes IDENTIFIER_PROPERTY_NOT_FOUND. + const result = analyze( + "{{accountId:4}}", + {}, + { + identifierSchemas: { 4: schemaNoItems }, + }, + ); + expect(result.valid).toBe(false); + }); + }); +}); + +// ═════════════════════════════════════════════════════════════════════════════ +// SECTION 3 : Typebars engine integration +// ═════════════════════════════════════════════════════════════════════════════ + +describe("Aggregated identifiers — Typebars engine", () => { + let tp: Typebars; + + beforeEach(() => { + tp = new Typebars(); + }); + + // ─── analyze() ─────────────────────────────────────────────────────── + + describe("analyze()", () => { + test("infers array type for aggregated identifier", () => { + const result = tp.analyze( + "{{accountId:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + }); + }); + + test("infers full array schema for $root:N", () => { + const result = tp.analyze( + "{{$root:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual(aggregatedSchema); + }); + }); + + // ─── execute() ─────────────────────────────────────────────────────── + + describe("execute()", () => { + test("extracts property from aggregated identifierData", () => { + const result = tp.execute( + "{{accountId:4}}", + {}, + { + identifierData: { 4: aggregatedData }, + }, + ); + expect(result).toEqual(["A", "B", "C"]); + }); + + test("returns full array for $root:N", () => { + const result = tp.execute( + "{{$root:4}}", + {}, + { + identifierData: { 4: aggregatedData }, + }, + ); + expect(result).toEqual(aggregatedData); + }); + + test("scalar identifier still works", () => { + const result = tp.execute( + "{{seqOutput:2}}", + {}, + { + identifierData: { 2: scalarData, 4: aggregatedData }, + }, + ); + expect(result).toBe("hello"); + }); + }); + + // ─── analyzeAndExecute() ───────────────────────────────────────────── + + describe("analyzeAndExecute()", () => { + test("analyzes and executes aggregated identifier correctly", () => { + const { analysis, value } = tp.analyzeAndExecute( + "{{accountId:4}}", + {}, + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + identifierData: { 4: aggregatedData }, + }, + ); + expect(analysis.valid).toBe(true); + expect(analysis.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + }); + expect(value).toEqual(["A", "B", "C"]); + }); + + test("analyzeAndExecute with $root:N", () => { + const { analysis, value } = tp.analyzeAndExecute( + "{{$root:4}}", + {}, + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + identifierData: { 4: aggregatedData }, + }, + ); + expect(analysis.valid).toBe(true); + expect(value).toEqual(aggregatedData); + }); + + test("analyzeAndExecute fails when property not in items schema", () => { + const { analysis, value } = tp.analyzeAndExecute( + "{{nonexistent:4}}", + {}, + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + identifierData: { 4: aggregatedData }, + }, + ); + expect(analysis.valid).toBe(false); + expect(value).toBeUndefined(); + }); + }); + + // ─── compile() ─────────────────────────────────────────────────────── + + describe("compile()", () => { + test("compiled template executes with aggregated identifierData", () => { + const compiled = tp.compile("{{accountId:4}}"); + const result = compiled.execute( + {}, + { + identifierData: { 4: aggregatedData }, + }, + ); + expect(result).toEqual(["A", "B", "C"]); + }); + + test("compiled template analyzes with aggregated identifierSchemas", () => { + const compiled = tp.compile("{{accountId:4}}"); + const result = compiled.analyze( + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + }); + }); + }); +}); + +// ═════════════════════════════════════════════════════════════════════════════ +// SECTION 4 : Integration with map helper +// ═════════════════════════════════════════════════════════════════════════════ +// +// NOTE: `($root:N)` CANNOT be used as a Handlebars sub-expression argument +// because Handlebars parses parenthesized expressions as helper calls, not +// data paths. `$root:4` is not a registered helper, so `(map ($root:4) "prop")` +// fails at runtime. +// +// The primary way to consume aggregated data is the direct `{{key:N}}` syntax, +// which extracts the property from each element automatically. The `map` helper +// can still be used on aggregated data when the array is made available through +// the regular data context. + +describe("Aggregated identifiers — map helper integration", () => { + let tp: Typebars; + + beforeEach(() => { + tp = new Typebars(); + }); + + // ─── map on aggregated data passed via regular data context ────────── + + describe("map on aggregated data in regular data context", () => { + test("map works when aggregated array is passed in data (not identifierData)", () => { + const result = tp.execute('{{ map accounts "accountId" }}', { + accounts: aggregatedData, + }); + expect(result).toEqual(["A", "B", "C"]); + }); + + test("map extracts number property from aggregated array in data", () => { + const result = tp.execute('{{ map accounts "amount" }}', { + accounts: aggregatedData, + }); + expect(result).toEqual([100, 200, 300]); + }); + + test("map on empty array in data → empty array", () => { + const result = tp.execute('{{ map accounts "accountId" }}', { + accounts: [], + }); + expect(result).toEqual([]); + }); + }); + + // ─── ($root:N) sub-expression limitation ───────────────────────────── + + describe("($root:N) sub-expression limitation", () => { + test("($root:N) as sub-expression to map returns empty (Handlebars treats it as helper call)", () => { + // This documents the known limitation: Handlebars parses ($root:4) + // as a helper call, not a data path lookup. Since $root:4 is not + // a registered helper, it returns undefined → map gets undefined → []. + const result = tp.execute( + '{{ map ($root:4) "accountId" }}', + {}, + { identifierData: { 4: aggregatedData } }, + ); + expect(result).toEqual([]); + }); + }); + + // ─── Direct extraction via {{key:N}} is the primary mechanism ──────── + + describe("direct extraction via {{key:N}} (preferred over map)", () => { + test("{{accountId:4}} extracts property directly — no map needed", () => { + const result = tp.execute( + "{{accountId:4}}", + {}, + { + identifierData: { 4: aggregatedData }, + }, + ); + expect(result).toEqual(["A", "B", "C"]); + }); + + test("analysis infers array type for {{key:N}} on aggregated schema", () => { + const result = tp.analyze( + "{{accountId:4}}", + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + }); + }); + + test("analyzeAndExecute round-trip with direct extraction", () => { + const { analysis, value } = tp.analyzeAndExecute( + "{{accountId:4}}", + {}, + {}, + { + identifierSchemas: { 4: aggregatedSchema }, + identifierData: { 4: aggregatedData }, + }, + ); + expect(analysis.valid).toBe(true); + expect(analysis.outputSchema).toEqual({ + type: "array", + items: { type: "string" }, + }); + expect(value).toEqual(["A", "B", "C"]); + }); + }); +}); + +// ═════════════════════════════════════════════════════════════════════════════ +// SECTION 5 : Object and Array template inputs with aggregated identifiers +// ═════════════════════════════════════════════════════════════════════════════ + +describe("Aggregated identifiers — object/array template inputs", () => { + let tp: Typebars; + + beforeEach(() => { + tp = new Typebars(); + }); + + describe("object template with aggregated identifiers", () => { + test("resolves aggregated identifier within object template", () => { + const result = tp.execute( + { + accountIds: "{{accountId:4}}", + label: "{{seqOutput:2}}", + count: 42, + }, + {}, + { + identifierData: { + 2: scalarData, + 4: aggregatedData, + }, + }, + ); + expect(result).toEqual({ + accountIds: ["A", "B", "C"], + label: "hello", + count: 42, + }); + }); + + test("analyzes object template with mixed scalar and aggregated", () => { + const result = tp.analyze( + { + accountIds: "{{accountId:4}}", + label: "{{seqOutput:2}}", + }, + {}, + { + identifierSchemas: { + 2: scalarSchema, + 4: aggregatedSchema, + }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ + type: "object", + properties: { + accountIds: { + type: "array", + items: { type: "string" }, + }, + label: { type: "string" }, + }, + required: ["accountIds", "label"], + }); + }); + }); + + describe("array template with aggregated identifiers", () => { + test("resolves aggregated identifier within array template", () => { + const result = tp.execute( + ["{{accountId:4}}", "{{seqOutput:2}}", "static"], + {}, + { + identifierData: { + 2: scalarData, + 4: aggregatedData, + }, + }, + ); + expect(result).toEqual([["A", "B", "C"], "hello", "static"]); + }); + }); +}); + +// ═════════════════════════════════════════════════════════════════════════════ +// SECTION 6 : Backward compatibility — scalar identifiers unchanged +// ═════════════════════════════════════════════════════════════════════════════ + +describe("Aggregated identifiers — backward compatibility", () => { + beforeEach(() => { + clearCompilationCache(); + }); + + test("scalar identifierData still works exactly as before (string)", () => { + const result = execute("{{meetingId:1}}", {}, { 1: { meetingId: "abc" } }); + expect(result).toBe("abc"); + }); + + test("scalar identifierData still works exactly as before (number)", () => { + const result = execute("{{count:1}}", {}, { 1: { count: 42 } }); + expect(result).toBe(42); + }); + + test("scalar identifierData still works exactly as before (boolean)", () => { + const result = execute("{{active:1}}", {}, { 1: { active: true } }); + expect(result).toBe(true); + }); + + test("scalar identifierData still works exactly as before (null)", () => { + const result = execute("{{value:1}}", {}, { 1: { value: null } }); + expect(result).toBeNull(); + }); + + test("scalar identifierData with object value (not array of objects)", () => { + const result = execute( + "{{nested:1}}", + {}, + { 1: { nested: { a: 1, b: 2 } } }, + ); + expect(result).toEqual({ a: 1, b: 2 }); + }); + + test("scalar identifierData with array value (array stored as a property, not as the identifierData entry)", () => { + const result = execute("{{tags:1}}", {}, { 1: { tags: ["x", "y", "z"] } }); + expect(result).toEqual(["x", "y", "z"]); + }); + + test("scalar identifierSchemas still infer scalar types", () => { + const result = analyze( + "{{meetingId:1}}", + {}, + { + identifierSchemas: { + 1: { + type: "object", + properties: { meetingId: { type: "string" } }, + }, + }, + }, + ); + expect(result.valid).toBe(true); + expect(result.outputSchema).toEqual({ type: "string" }); + }); + + test("$root:N on scalar identifier still returns the object", () => { + const result = execute( + "{{$root:1}}", + {}, + { 1: { meetingId: "abc", count: 42 } }, + ); + expect(result).toEqual({ meetingId: "abc", count: 42 }); + }); +}); + +// ═════════════════════════════════════════════════════════════════════════════ +// SECTION 7 : mergeDataWithIdentifiers — Handlebars rendering path +// ═════════════════════════════════════════════════════════════════════════════ +// +// NOTE: In Handlebars rendering mode (mixed templates, blocks), aggregated +// identifier data is stored under `$root:N` in the merged context. However, +// since `($root:N)` is parsed by Handlebars as a helper call (not a data +// path), aggregated data cannot be used directly as a sub-expression argument +// to helpers like `map` or `#each` in mixed/block templates. +// +// The primary consumption mechanism is `{{key:N}}` in single-expression mode. + +describe("Aggregated identifiers — Handlebars rendering (mixed/block templates)", () => { + let tp: Typebars; + + beforeEach(() => { + tp = new Typebars(); + }); + + describe("aggregated values in fast-path (text + simple expressions)", () => { + test("aggregated identifier is stringified in fast-path concatenation", () => { + const result = tp.execute( + "IDs: {{accountId:4}}", + {}, + { identifierData: { 4: aggregatedData } }, + ); + // In fast-path, the array is stringified via String() + expect(typeof result).toBe("string"); + expect(result).toBe("IDs: A,B,C"); + }); + }); + + describe("scalar identifiers still work in mixed/block templates", () => { + test("scalar identifier in block template works normally", () => { + const result = tp.execute( + "{{#if seqOutput:2}}yes{{else}}no{{/if}}", + {}, + { identifierData: { 2: scalarData } }, + ); + expect(result).toBe("yes"); + }); + }); +}); + +// ═════════════════════════════════════════════════════════════════════════════ +// SECTION 8 : Workflow merge scenario — end-to-end +// ═════════════════════════════════════════════════════════════════════════════ + +describe("Aggregated identifiers — workflow merge scenario", () => { + let tp: Typebars; + + beforeEach(() => { + tp = new Typebars(); + }); + + test("end-to-end: Node 5 consumes scalar branch + aggregated multi-branch", () => { + // Simulates the topology: + // 0 (split) → 1 → 2 → 5 (merge) + // └→ 3 (multi) → 4 → 5 + // + // Node 5's params template consumes: + // - seqOutput from Node 2 (scalar, identifier 2) + // - accountIds from Node 4 (aggregated, identifier 4) + + const identifierData = { + 2: { seqOutput: "sequential-result" }, + 4: [ + { accountId: "ACC-001", processedId: "P1" }, + { accountId: "ACC-002", processedId: "P2" }, + { accountId: "ACC-003", processedId: "P3" }, + ], + }; + + const identifierSchemas: Record = { + 2: { + type: "object", + properties: { seqOutput: { type: "string" } }, + }, + 4: { + type: "array", + items: { + type: "object", + properties: { + accountId: { type: "string" }, + processedId: { type: "string" }, + }, + }, + }, + }; + + // Template for Node 5's params + const template = { + sequentialResult: "{{seqOutput:2}}", + accountIds: "{{accountId:4}}", + processedIds: "{{processedId:4}}", + }; + + // Analyze + const analysis = tp.analyze( + template, + {}, + { + identifierSchemas, + }, + ); + expect(analysis.valid).toBe(true); + expect(analysis.outputSchema).toEqual({ + type: "object", + properties: { + sequentialResult: { type: "string" }, + accountIds: { type: "array", items: { type: "string" } }, + processedIds: { type: "array", items: { type: "string" } }, + }, + required: ["sequentialResult", "accountIds", "processedIds"], + }); + + // Execute + const result = tp.execute(template, {}, { identifierData }); + expect(result).toEqual({ + sequentialResult: "sequential-result", + accountIds: ["ACC-001", "ACC-002", "ACC-003"], + processedIds: ["P1", "P2", "P3"], + }); + }); + + test("end-to-end: direct extraction from aggregated multi-branch", () => { + const identifierData = { + 4: [ + { accountId: "A", amount: 100 }, + { accountId: "B", amount: 200 }, + ], + }; + + const identifierSchemas: Record = { + 4: { + type: "array", + items: { + type: "object", + properties: { + accountId: { type: "string" }, + amount: { type: "number" }, + }, + }, + }, + }; + + // Using direct {{key:N}} extraction from aggregated data + const { analysis, value } = tp.analyzeAndExecute( + "{{amount:4}}", + {}, + {}, + { identifierSchemas, identifierData }, + ); + + expect(analysis.valid).toBe(true); + expect(analysis.outputSchema).toEqual({ + type: "array", + items: { type: "number" }, + }); + expect(value).toEqual([100, 200]); + }); +});