typebars 1.0.16 → 1.0.18

package/dist/cjs/executor.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/executor.ts"],"sourcesContent":["import Handlebars from \"handlebars\";\nimport type { JSONSchema7 } from \"json-schema\";\nimport { dispatchExecute } from \"./dispatch.ts\";\nimport { TemplateRuntimeError } from \"./errors.ts\";\nimport { CollectionHelpers } from \"./helpers/collection-helpers.ts\";\nimport {\n\tcanUseFastPath,\n\tcoerceLiteral,\n\textractExpressionIdentifier,\n\textractPathSegments,\n\tgetEffectiveBody,\n\tgetEffectivelySingleBlock,\n\tgetEffectivelySingleExpression,\n\tisRootPathTraversal,\n\tisRootSegments,\n\tisSingleExpression,\n\tisThisExpression,\n\tparse,\n\tROOT_TOKEN,\n} from \"./parser.ts\";\nimport type { HelperDefinition, TemplateInput } from \"./types.ts\";\nimport { LRUCache } from \"./utils.ts\";\n\n// ─── Template Executor ───────────────────────────────────────────────────────\n// Executes a Handlebars template with real data.\n//\n// Four execution modes (from fastest to most general):\n//\n// 1. **Single expression** (`{{value}}` or `  {{value}}  `) → returns the raw\n//    value without converting to string. This preserves the original type\n//    (number, boolean, object, array, null).\n//\n// 2. **Fast-path** (text + simple expressions, no blocks or helpers) →\n//    direct concatenation without going through Handlebars.compile(). Up to\n//    10-100x faster for simple templates like `Hello {{name}}`.\n//\n// 3. **Single block** (`{{#if x}}10{{else}}20{{/if}}` possibly surrounded\n//    by whitespace) → rendered via Handlebars then intelligently coerced\n//    (detecting number, boolean, null literals).\n//\n// 4. **Mixed template** (text + multiple blocks, helpers, …) →\n//    delegates to Handlebars which always produces a string.\n//\n// ─── Caching ─────────────────────────────────────────────────────────────────\n// Handlebars-compiled templates are cached in an LRU cache to avoid costly\n// recompilation on repeated calls.\n//\n// Two cache levels:\n// - **Global cache** (module-level) for standalone `execute()` calls\n// - **Instance cache** for `Typebars` (passed via `ExecutorContext`)\n//\n// ─── Template Identifiers ────────────────────────────────────────────────────\n// The `{{key:N}}` syntax allows resolving a variable from a specific data\n// source, identified by an integer N. The optional `identifierData` parameter\n// provides a mapping `{ [id]: { key: value, ... } }`.\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\n/** Optional context for execution (used by Typebars/CompiledTemplate) */\nexport interface ExecutorContext {\n\t/** Data by identifier `{ [id]: { key: value } }` */\n\tidentifierData?: Record<number, Record<string, unknown>>;\n\t/** Pre-compiled Handlebars template (for CompiledTemplate) */\n\tcompiledTemplate?: HandlebarsTemplateDelegate;\n\t/** Isolated Handlebars environment (for custom helpers) */\n\thbs?: typeof Handlebars;\n\t/** Compilation cache shared by the engine */\n\tcompilationCache?: LRUCache<string, HandlebarsTemplateDelegate>;\n\t/**\n\t * Explicit coercion schema for the output value.\n\t * When set with a primitive type, the execution result will be coerced\n\t * to match the declared type instead of using auto-detection.\n\t */\n\tcoerceSchema?: JSONSchema7;\n\t/** Registered helpers (for direct execution of special helpers like `collect`) */\n\thelpers?: Map<string, HelperDefinition>;\n}\n\n// ─── Global Compilation Cache ────────────────────────────────────────────────\n// Used by the standalone `execute()` function and `renderWithHandlebars()`.\n// `Typebars` instances use their own cache.\nconst globalCompilationCache = new LRUCache<string, HandlebarsTemplateDelegate>(\n\t128,\n);\n\n// ─── Public API (backward-compatible) ────────────────────────────────────────\n\n/**\n * Executes a template with the provided data and returns the result.\n *\n * The return type depends on the template structure:\n * - Single expression `{{expr}}` → raw value (any)\n * - Single block → coerced value (number, boolean, null, or string)\n * - Mixed template → `string`\n *\n * @param template       - The template string\n * @param data           - The main context data\n * @param identifierData - (optional) Data by identifier `{ [id]: { key: value } }`\n */\nexport function execute(\n\ttemplate: TemplateInput,\n\tdata: unknown,\n\tidentifierData?: Record<number, Record<string, unknown>>,\n): unknown {\n\treturn dispatchExecute(\n\t\ttemplate,\n\t\tundefined,\n\t\t// String handler — parse and execute the AST\n\t\t(tpl) => {\n\t\t\tconst ast = parse(tpl);\n\t\t\treturn executeFromAst(ast, tpl, data, { identifierData });\n\t\t},\n\t\t// Recursive handler — re-enter execute() for child elements\n\t\t(child) => execute(child, data, identifierData),\n\t);\n}\n\n// ─── Internal API (for Typebars / CompiledTemplate) ──────────────────────\n\n/**\n * Executes a template from an already-parsed AST.\n *\n * This function is the core of execution. It is used by:\n * - `execute()` (backward-compatible wrapper)\n * - `CompiledTemplate.execute()` (with pre-parsed AST and cache)\n * - `Typebars.execute()` (with cache and helpers)\n *\n * @param ast       - The already-parsed Handlebars AST\n * @param template  - The template source (for Handlebars compilation if needed)\n * @param data      - The main context data\n * @param ctx       - Optional execution context\n */\nexport function executeFromAst(\n\tast: hbs.AST.Program,\n\ttemplate: string,\n\tdata: unknown,\n\tctx?: ExecutorContext,\n): unknown {\n\tconst identifierData = ctx?.identifierData;\n\n\t// ── Case 1: strict single expression `{{expr}}` ──────────────────────\n\t// Exclude helper calls (params > 0 or hash) because they must go\n\t// through Handlebars for correct execution.\n\tif (isSingleExpression(ast)) {\n\t\tconst stmt = ast.body[0] as hbs.AST.MustacheStatement;\n\t\tif (stmt.params.length === 0 && !stmt.hash) {\n\t\t\treturn resolveExpression(stmt.path, data, identifierData, ctx?.helpers);\n\t\t}\n\t}\n\n\t// ── Case 1b: single expression with surrounding whitespace `  {{expr}}  `\n\tconst singleExpr = getEffectivelySingleExpression(ast);\n\tif (singleExpr && singleExpr.params.length === 0 && !singleExpr.hash) {\n\t\treturn resolveExpression(\n\t\t\tsingleExpr.path,\n\t\t\tdata,\n\t\t\tidentifierData,\n\t\t\tctx?.helpers,\n\t\t);\n\t}\n\n\t// ── Case 1c: single expression with helper (params > 0) ──────────────\n\t// E.g. `{{ divide accountIds.length 10 }}` or `{{ math a \"+\" b }}`\n\t// The helper returns a typed value but Handlebars converts it to a\n\t// string. We render via Handlebars then coerce the result to recover\n\t// the original type (number, boolean, null).\n\tif (singleExpr && (singleExpr.params.length > 0 || singleExpr.hash)) {\n\t\t// ── Special case: helpers that return non-primitive values ────────\n\t\t// Some helpers (e.g. `collect`) return arrays or objects. Handlebars\n\t\t// would stringify these, so we resolve their arguments directly and\n\t\t// call the helper's fn to preserve the raw return value.\n\t\tconst directResult = tryDirectHelperExecution(singleExpr, data, ctx);\n\t\tif (directResult !== undefined) {\n\t\t\treturn directResult.value;\n\t\t}\n\n\t\tconst merged = mergeDataWithIdentifiers(data, identifierData);\n\t\tconst raw = renderWithHandlebars(template, merged, ctx);\n\t\treturn coerceValue(raw, ctx?.coerceSchema);\n\t}\n\n\t// ── Case 2: fast-path for simple templates (text + expressions) ──────\n\t// If the template only contains text and simple expressions (no blocks,\n\t// no helpers with parameters), we can do direct concatenation without\n\t// going through Handlebars.compile().\n\tif (canUseFastPath(ast) && ast.body.length > 1) {\n\t\treturn executeFastPath(ast, data, identifierData);\n\t}\n\n\t// ── Case 3: single block (possibly surrounded by whitespace) ─────────\n\t// Render via Handlebars then attempt to coerce the result to the\n\t// detected literal type (number, boolean, null).\n\tconst singleBlock = getEffectivelySingleBlock(ast);\n\tif (singleBlock) {\n\t\tconst merged = mergeDataWithIdentifiers(data, identifierData);\n\t\tconst raw = renderWithHandlebars(template, merged, ctx);\n\t\treturn coerceValue(raw, ctx?.coerceSchema);\n\t}\n\n\t// ── Case 4: mixed template ───────────────────────────────────────────\n\t// For purely static templates (only ContentStatements), coerce the\n\t// result to match the coerceSchema type or auto-detect the literal type.\n\t// For truly mixed templates (text + blocks + expressions), return string.\n\tconst merged = mergeDataWithIdentifiers(data, identifierData);\n\tconst raw = renderWithHandlebars(template, merged, ctx);\n\n\tconst effective = getEffectiveBody(ast);\n\tconst allContent = effective.every((s) => s.type === \"ContentStatement\");\n\tif (allContent) {\n\t\treturn coerceValue(raw, ctx?.coerceSchema);\n\t}\n\n\treturn raw;\n}\n\n// ─── Value Coercion ──────────────────────────────────────────────────────────\n// Coerces a raw string from Handlebars rendering based on an optional\n// coerceSchema. When no schema is provided, falls back to auto-detection\n// via `coerceLiteral`.\n\n/**\n * Coerces a raw string value based on an optional coercion schema.\n *\n * - If `coerceSchema` declares a primitive type (`string`, `number`,\n *   `integer`, `boolean`, `null`), the value is cast to that type.\n * - Otherwise, falls back to `coerceLiteral` (auto-detection).\n *\n * @param raw          - The raw string from Handlebars rendering\n * @param coerceSchema - Optional schema declaring the desired output type\n * @returns The coerced value\n */\nfunction coerceValue(raw: string, coerceSchema?: JSONSchema7): unknown {\n\tif (coerceSchema) {\n\t\tconst targetType = coerceSchema.type;\n\t\tif (typeof targetType === \"string\") {\n\t\t\tif (targetType === \"string\") return raw;\n\t\t\tif (targetType === \"number\" || targetType === \"integer\")\n\t\t\t\treturn Number(raw.trim());\n\t\t\tif (targetType === \"boolean\") return raw.trim() === \"true\";\n\t\t\tif (targetType === \"null\") return null;\n\t\t}\n\t}\n\t// No coerceSchema or non-primitive type → auto-detect\n\treturn coerceLiteral(raw);\n}\n\n// ─── Fast-Path Execution ─────────────────────────────────────────────────────\n// For templates consisting only of text and simple expressions (no blocks,\n// no helpers), we bypass Handlebars and do direct concatenation.\n// This is significantly faster.\n\n/**\n * Executes a template via the fast-path (direct concatenation).\n *\n * Precondition: `canUseFastPath(ast)` must return `true`.\n *\n * @param ast            - The template AST (only ContentStatement and simple MustacheStatement)\n * @param data           - The context data\n * @param identifierData - Data by identifier (optional)\n * @returns The resulting string\n */\nfunction executeFastPath(\n\tast: hbs.AST.Program,\n\tdata: unknown,\n\tidentifierData?: Record<number, Record<string, unknown>>,\n): string {\n\tlet result = \"\";\n\n\tfor (const stmt of ast.body) {\n\t\tif (stmt.type === \"ContentStatement\") {\n\t\t\tresult += (stmt as hbs.AST.ContentStatement).value;\n\t\t} else if (stmt.type === \"MustacheStatement\") {\n\t\t\tconst value = resolveExpression(\n\t\t\t\t(stmt as hbs.AST.MustacheStatement).path,\n\t\t\t\tdata,\n\t\t\t\tidentifierData,\n\t\t\t);\n\t\t\t// Handlebars converts values to strings for rendering.\n\t\t\t// We replicate this behavior: null/undefined → \"\", otherwise String(value).\n\t\t\tif (value != null) {\n\t\t\t\tresult += String(value);\n\t\t\t}\n\t\t}\n\t}\n\n\treturn result;\n}\n\n// ─── Direct Expression Resolution ────────────────────────────────────────────\n// Used for single-expression templates and the fast-path, to return the raw\n// value without going through the Handlebars engine.\n\n/**\n * Resolves an AST expression by following the path through the data.\n *\n * If the expression contains an identifier (e.g. `meetingId:1`), resolution\n * is performed in `identifierData[1]` instead of `data`.\n *\n * @param expr           - The AST expression to resolve\n * @param data           - The main data context\n * @param identifierData - Data by identifier (optional)\n * @returns The raw value pointed to by the expression\n */\nfunction resolveExpression(\n\texpr: hbs.AST.Expression,\n\tdata: unknown,\n\tidentifierData?: Record<number, Record<string, unknown>>,\n\thelpers?: Map<string, HelperDefinition>,\n): unknown {\n\t// this / . → return the entire context\n\tif (isThisExpression(expr)) {\n\t\treturn data;\n\t}\n\n\t// Literals\n\tif (expr.type === \"StringLiteral\")\n\t\treturn (expr as hbs.AST.StringLiteral).value;\n\tif (expr.type === \"NumberLiteral\")\n\t\treturn (expr as hbs.AST.NumberLiteral).value;\n\tif (expr.type === \"BooleanLiteral\")\n\t\treturn (expr as hbs.AST.BooleanLiteral).value;\n\tif (expr.type === \"NullLiteral\") return null;\n\tif (expr.type === \"UndefinedLiteral\") return undefined;\n\n\t// ── SubExpression (nested helper call) ────────────────────────────────\n\t// E.g. `(collect users 'cartItems')` used as an argument to another helper.\n\t// Resolve all arguments recursively and call the helper's fn directly.\n\tif (expr.type === \"SubExpression\") {\n\t\tconst subExpr = expr as hbs.AST.SubExpression;\n\t\tif (subExpr.path.type === \"PathExpression\") {\n\t\t\tconst helperName = (subExpr.path as hbs.AST.PathExpression).original;\n\t\t\tconst helper = helpers?.get(helperName);\n\t\t\tif (helper) {\n\t\t\t\tconst isCollect = helperName === CollectionHelpers.COLLECT_HELPER_NAME;\n\t\t\t\tconst resolvedArgs: unknown[] = [];\n\t\t\t\tfor (let i = 0; i < subExpr.params.length; i++) {\n\t\t\t\t\tconst param = subExpr.params[i] as hbs.AST.Expression;\n\t\t\t\t\t// For `collect`, the second argument is a property name literal\n\t\t\t\t\tif (isCollect && i === 1 && param.type === \"StringLiteral\") {\n\t\t\t\t\t\tresolvedArgs.push((param as hbs.AST.StringLiteral).value);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tresolvedArgs.push(\n\t\t\t\t\t\t\tresolveExpression(param, data, identifierData, helpers),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn helper.fn(...resolvedArgs);\n\t\t\t}\n\t\t}\n\t\t// Unknown sub-expression helper — return undefined\n\t\treturn undefined;\n\t}\n\n\t// PathExpression — navigate through segments in the data object\n\tconst segments = extractPathSegments(expr);\n\tif (segments.length === 0) {\n\t\tthrow new TemplateRuntimeError(\n\t\t\t`Cannot resolve expression of type \"${expr.type}\"`,\n\t\t);\n\t}\n\n\t// Extract the potential identifier from the last segment BEFORE\n\t// checking for $root, so that both {{$root}} and {{$root:N}} are\n\t// handled uniformly.\n\tconst { cleanSegments, identifier } = extractExpressionIdentifier(segments);\n\n\t// $root path traversal ($root.name) — not supported, return undefined\n\t// (the analyzer already rejects it with a diagnostic).\n\tif (isRootPathTraversal(cleanSegments)) {\n\t\treturn undefined;\n\t}\n\n\t// $root → return the entire data context (or identifier data)\n\tif (isRootSegments(cleanSegments)) {\n\t\tif (identifier !== null && identifierData) {\n\t\t\tconst source = identifierData[identifier];\n\t\t\treturn source ?? undefined;\n\t\t}\n\t\tif (identifier !== null) {\n\t\t\t// Template uses an identifier but no identifierData was provided\n\t\t\treturn undefined;\n\t\t}\n\t\treturn data;\n\t}\n\n\tif (identifier !== null && identifierData) {\n\t\tconst source = identifierData[identifier];\n\t\tif (source) {\n\t\t\treturn resolveDataPath(source, cleanSegments);\n\t\t}\n\t\t// Source does not exist → undefined (like a missing key)\n\t\treturn undefined;\n\t}\n\n\tif (identifier !== null && !identifierData) {\n\t\t// Template uses an identifier but no identifierData was provided\n\t\treturn undefined;\n\t}\n\n\treturn resolveDataPath(data, cleanSegments);\n}\n\n/**\n * Navigates through a data object by following a path of segments.\n *\n * @param data     - The data object\n * @param segments - The path segments (e.g. `[\"user\", \"address\", \"city\"]`)\n * @returns The value at the end of the path, or `undefined` if an\n *          intermediate segment is null/undefined\n */\nexport function resolveDataPath(data: unknown, segments: string[]): unknown {\n\tlet current: unknown = data;\n\n\tfor (const segment of segments) {\n\t\tif (current === null || current === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tif (typeof current !== \"object\") {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tcurrent = (current as Record<string, unknown>)[segment];\n\t}\n\n\treturn current;\n}\n\n// ─── Data Merging ────────────────────────────────────────────────────────────\n// For Handlebars rendering (mixed templates / blocks), we cannot intercept\n// resolution on a per-expression basis. Instead, we merge identifier data\n// into the main object using the format `\"key:N\"`.\n//\n// Handlebars parses `{{meetingId:1}}` as a PathExpression with a single\n// segment `\"meetingId:1\"`, so it looks up the key `\"meetingId:1\"` in the\n// data object — which matches our flattened format exactly.\n\n/**\n * Merges the main data with identifier data.\n *\n * @param data           - Main data\n * @param identifierData - Data by identifier\n * @returns A merged object where identifier data appears as `\"key:N\"` keys\n *\n * @example\n * ```\n * mergeDataWithIdentifiers(\n *   { name: \"Alice\" },\n *   { 1: { meetingId: \"val1\" }, 2: { meetingId: \"val2\" } }\n * )\n * // → { name: \"Alice\", \"meetingId:1\": \"val1\", \"meetingId:2\": \"val2\" }\n * ```\n */\nfunction mergeDataWithIdentifiers(\n\tdata: unknown,\n\tidentifierData?: Record<number, Record<string, unknown>>,\n): Record<string, unknown> {\n\t// Always include $root so that Handlebars can resolve {{$root}} in\n\t// mixed templates and block helpers (where we delegate to Handlebars\n\t// instead of resolving expressions ourselves).\n\t// When data is a primitive (e.g. number passed with {{$root}}), we\n\t// wrap it into an object so Handlebars can still function.\n\tconst base: Record<string, unknown> =\n\t\tdata !== null && typeof data === \"object\" && !Array.isArray(data)\n\t\t\t? (data as Record<string, unknown>)\n\t\t\t: {};\n\tconst merged: Record<string, unknown> = { ...base, [ROOT_TOKEN]: data };\n\n\tif (!identifierData) return merged;\n\n\tfor (const [id, idData] of Object.entries(identifierData)) {\n\t\t// Add `$root:N` so Handlebars can resolve {{$root:N}} in mixed/block\n\t\t// templates (where we delegate to Handlebars instead of resolving\n\t\t// expressions ourselves). The value is the entire identifier data object.\n\t\tmerged[`${ROOT_TOKEN}:${id}`] = idData;\n\n\t\tfor (const [key, value] of Object.entries(idData)) {\n\t\t\tmerged[`${key}:${id}`] = value;\n\t\t}\n\t}\n\n\treturn merged;\n}\n\n// ─── Handlebars Rendering ────────────────────────────────────────────────────\n// For complex templates (blocks, helpers), we delegate to Handlebars.\n// Compilation is cached to avoid costly recompilations.\n\n/**\n * Compiles and executes a template via Handlebars.\n *\n * Uses a compilation cache (LRU) to avoid recompiling the same template\n * on repeated calls. The cache is either:\n * - The global cache (for the standalone `execute()` function)\n * - The instance cache provided via `ExecutorContext` (for `Typebars`)\n *\n * @param template - The template string\n * @param data     - The context data\n * @param ctx      - Optional execution context (cache, Handlebars env)\n * @returns Always a string\n */\nfunction renderWithHandlebars(\n\ttemplate: string,\n\tdata: Record<string, unknown>,\n\tctx?: ExecutorContext,\n): string {\n\ttry {\n\t\t// 1. Use the pre-compiled template if available (CompiledTemplate)\n\t\tif (ctx?.compiledTemplate) {\n\t\t\treturn ctx.compiledTemplate(data);\n\t\t}\n\n\t\t// 2. Look up in the cache (instance or global)\n\t\tconst cache = ctx?.compilationCache ?? globalCompilationCache;\n\t\tconst hbs = ctx?.hbs ?? Handlebars;\n\n\t\tlet compiled = cache.get(template);\n\t\tif (!compiled) {\n\t\t\tcompiled = hbs.compile(template, {\n\t\t\t\t// Disable HTML-escaping by default — this engine is not\n\t\t\t\t// HTML-specific, we want raw values.\n\t\t\t\tnoEscape: true,\n\t\t\t\t// Strict mode: throws if a path does not exist in the data.\n\t\t\t\tstrict: false,\n\t\t\t});\n\t\t\tcache.set(template, compiled);\n\t\t}\n\n\t\treturn compiled(data);\n\t} catch (error: unknown) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\tthrow new TemplateRuntimeError(message);\n\t}\n}\n\n/**\n * Clears the global Handlebars compilation cache.\n * Useful for tests or to free memory.\n */\nexport function clearCompilationCache(): void {\n\tglobalCompilationCache.clear();\n}\n\n// ─── Direct Helper Execution ─────────────────────────────────────────────────\n// Some helpers (e.g. `collect`) return non-primitive values (arrays, objects)\n// that Handlebars would stringify. For these helpers, we resolve their\n// arguments directly and call the helper's `fn` to preserve the raw value.\n\n/** Set of helper names that must be executed directly (bypass Handlebars) */\nconst DIRECT_EXECUTION_HELPERS = new Set<string>([\n\tCollectionHelpers.COLLECT_HELPER_NAME,\n]);\n\n/**\n * Attempts to execute a helper directly (without Handlebars rendering).\n *\n * Returns `{ value }` if the helper was executed directly, or `undefined`\n * if the helper should go through the normal Handlebars rendering path.\n *\n * @param stmt - The MustacheStatement containing the helper call\n * @param data - The context data\n * @param ctx  - Optional execution context (with helpers and identifierData)\n */\nfunction tryDirectHelperExecution(\n\tstmt: hbs.AST.MustacheStatement,\n\tdata: unknown,\n\tctx?: ExecutorContext,\n): { value: unknown } | undefined {\n\t// Get the helper name from the path\n\tif (stmt.path.type !== \"PathExpression\") return undefined;\n\tconst helperName = (stmt.path as hbs.AST.PathExpression).original;\n\n\t// Only intercept known direct-execution helpers\n\tif (!DIRECT_EXECUTION_HELPERS.has(helperName)) return undefined;\n\n\t// Look up the helper definition\n\tconst helper = ctx?.helpers?.get(helperName);\n\tif (!helper) return undefined;\n\n\t// Resolve each argument from the data context.\n\t// For the `collect` helper, the resolution strategy is:\n\t//   - Arg 0 (collection): resolve as a data path (e.g. `users` → array)\n\t//   - Arg 1 (property):   must be a StringLiteral (e.g. `\"name\"`)\n\t//     The analyzer enforces this — bare identifiers like `name` are\n\t//     rejected at analysis time because Handlebars would resolve them\n\t//     as a data path instead of a literal property name.\n\tconst isCollect = helperName === CollectionHelpers.COLLECT_HELPER_NAME;\n\n\tconst resolvedArgs: unknown[] = [];\n\tfor (let i = 0; i < stmt.params.length; i++) {\n\t\tconst param = stmt.params[i] as hbs.AST.Expression;\n\n\t\t// For `collect`, the second argument (index 1) is a property name —\n\t\t// it must be a StringLiteral (enforced by the analyzer).\n\t\tif (isCollect && i === 1) {\n\t\t\tif (param.type === \"StringLiteral\") {\n\t\t\t\tresolvedArgs.push((param as hbs.AST.StringLiteral).value);\n\t\t\t} else {\n\t\t\t\t// Fallback: resolve normally (will likely be undefined at runtime)\n\t\t\t\tresolvedArgs.push(\n\t\t\t\t\tresolveExpression(param, data, ctx?.identifierData, ctx?.helpers),\n\t\t\t\t);\n\t\t\t}\n\t\t} else {\n\t\t\tresolvedArgs.push(\n\t\t\t\tresolveExpression(param, data, ctx?.identifierData, ctx?.helpers),\n\t\t\t);\n\t\t}\n\t}\n\n\t// Call the helper's fn directly with the resolved arguments\n\tconst value = helper.fn(...resolvedArgs);\n\treturn { value };\n}\n"],"names":["clearCompilationCache","execute","executeFromAst","resolveDataPath","globalCompilationCache","LRUCache","template","data","identifierData","dispatchExecute","undefined","tpl","ast","parse","child","ctx","isSingleExpression","stmt","body","params","length","hash","resolveExpression","path","helpers","singleExpr","getEffectivelySingleExpression","directResult","tryDirectHelperExecution","value","merged","mergeDataWithIdentifiers","raw","renderWithHandlebars","coerceValue","coerceSchema","canUseFastPath","executeFastPath","singleBlock","getEffectivelySingleBlock","effective","getEffectiveBody","allContent","every","s","type","targetType","Number","trim","coerceLiteral","result","String","expr","isThisExpression","subExpr","helperName","original","helper","get","isCollect","CollectionHelpers","COLLECT_HELPER_NAME","resolvedArgs","i","param","push","fn","segments","extractPathSegments","TemplateRuntimeError","cleanSegments","identifier","extractExpressionIdentifier","isRootPathTraversal","isRootSegments","source","current","segment","base","Array","isArray","ROOT_TOKEN","id","idData","Object","entries","key","compiledTemplate","cache","compilationCache","hbs","Handlebars","compiled","compile","noEscape","strict","set","error","message","Error","clear","DIRECT_EXECUTION_HELPERS","Set","has"],"mappings":"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"}
+{"version":3,"sources":["../../src/executor.ts"],"sourcesContent":["import Handlebars from \"handlebars\";\nimport type { JSONSchema7 } from \"json-schema\";\nimport { dispatchExecute } from \"./dispatch.ts\";\nimport { TemplateRuntimeError } from \"./errors.ts\";\nimport { MapHelpers } from \"./helpers/map-helpers.ts\";\nimport {\n\tcanUseFastPath,\n\tcoerceLiteral,\n\textractExpressionIdentifier,\n\textractPathSegments,\n\tgetEffectiveBody,\n\tgetEffectivelySingleBlock,\n\tgetEffectivelySingleExpression,\n\tisRootPathTraversal,\n\tisRootSegments,\n\tisSingleExpression,\n\tisThisExpression,\n\tparse,\n\tROOT_TOKEN,\n} from \"./parser.ts\";\nimport type { HelperDefinition, TemplateInput } from \"./types.ts\";\nimport { LRUCache } from \"./utils.ts\";\n\n// ─── Template Executor ───────────────────────────────────────────────────────\n// Executes a Handlebars template with real data.\n//\n// Four execution modes (from fastest to most general):\n//\n// 1. **Single expression** (`{{value}}` or `  {{value}}  `) → returns the raw\n//    value without converting to string. This preserves the original type\n//    (number, boolean, object, array, null).\n//\n// 2. **Fast-path** (text + simple expressions, no blocks or helpers) →\n//    direct concatenation without going through Handlebars.compile(). Up to\n//    10-100x faster for simple templates like `Hello {{name}}`.\n//\n// 3. **Single block** (`{{#if x}}10{{else}}20{{/if}}` possibly surrounded\n//    by whitespace) → rendered via Handlebars then intelligently coerced\n//    (detecting number, boolean, null literals).\n//\n// 4. **Mixed template** (text + multiple blocks, helpers, …) →\n//    delegates to Handlebars which always produces a string.\n//\n// ─── Caching ─────────────────────────────────────────────────────────────────\n// Handlebars-compiled templates are cached in an LRU cache to avoid costly\n// recompilation on repeated calls.\n//\n// Two cache levels:\n// - **Global cache** (module-level) for standalone `execute()` calls\n// - **Instance cache** for `Typebars` (passed via `ExecutorContext`)\n//\n// ─── Template Identifiers ────────────────────────────────────────────────────\n// The `{{key:N}}` syntax allows resolving a variable from a specific data\n// source, identified by an integer N. The optional `identifierData` parameter\n// provides a mapping `{ [id]: { key: value, ... } }`.\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\n/** Optional context for execution (used by Typebars/CompiledTemplate) */\nexport interface ExecutorContext {\n\t/** Data by identifier `{ [id]: { key: value } }` */\n\tidentifierData?: Record<number, Record<string, unknown>>;\n\t/** Pre-compiled Handlebars template (for CompiledTemplate) */\n\tcompiledTemplate?: HandlebarsTemplateDelegate;\n\t/** Isolated Handlebars environment (for custom helpers) */\n\thbs?: typeof Handlebars;\n\t/** Compilation cache shared by the engine */\n\tcompilationCache?: LRUCache<string, HandlebarsTemplateDelegate>;\n\t/**\n\t * Explicit coercion schema for the output value.\n\t * When set with a primitive type, the execution result will be coerced\n\t * to match the declared type instead of using auto-detection.\n\t */\n\tcoerceSchema?: JSONSchema7;\n\t/** Registered helpers (for direct execution of special helpers like `map`) */\n\thelpers?: Map<string, HelperDefinition>;\n}\n\n// ─── Global Compilation Cache ────────────────────────────────────────────────\n// Used by the standalone `execute()` function and `renderWithHandlebars()`.\n// `Typebars` instances use their own cache.\nconst globalCompilationCache = new LRUCache<string, HandlebarsTemplateDelegate>(\n\t128,\n);\n\n// ─── Public API (backward-compatible) ────────────────────────────────────────\n\n/**\n * Executes a template with the provided data and returns the result.\n *\n * The return type depends on the template structure:\n * - Single expression `{{expr}}` → raw value (any)\n * - Single block → coerced value (number, boolean, null, or string)\n * - Mixed template → `string`\n *\n * @param template       - The template string\n * @param data           - The main context data\n * @param identifierData - (optional) Data by identifier `{ [id]: { key: value } }`\n */\nexport function execute(\n\ttemplate: TemplateInput,\n\tdata: unknown,\n\tidentifierData?: Record<number, Record<string, unknown>>,\n): unknown {\n\treturn dispatchExecute(\n\t\ttemplate,\n\t\tundefined,\n\t\t// String handler — parse and execute the AST\n\t\t(tpl) => {\n\t\t\tconst ast = parse(tpl);\n\t\t\treturn executeFromAst(ast, tpl, data, { identifierData });\n\t\t},\n\t\t// Recursive handler — re-enter execute() for child elements\n\t\t(child) => execute(child, data, identifierData),\n\t);\n}\n\n// ─── Internal API (for Typebars / CompiledTemplate) ──────────────────────\n\n/**\n * Executes a template from an already-parsed AST.\n *\n * This function is the core of execution. It is used by:\n * - `execute()` (backward-compatible wrapper)\n * - `CompiledTemplate.execute()` (with pre-parsed AST and cache)\n * - `Typebars.execute()` (with cache and helpers)\n *\n * @param ast       - The already-parsed Handlebars AST\n * @param template  - The template source (for Handlebars compilation if needed)\n * @param data      - The main context data\n * @param ctx       - Optional execution context\n */\nexport function executeFromAst(\n\tast: hbs.AST.Program,\n\ttemplate: string,\n\tdata: unknown,\n\tctx?: ExecutorContext,\n): unknown {\n\tconst identifierData = ctx?.identifierData;\n\n\t// ── Case 1: strict single expression `{{expr}}` ──────────────────────\n\t// Exclude helper calls (params > 0 or hash) because they must go\n\t// through Handlebars for correct execution.\n\tif (isSingleExpression(ast)) {\n\t\tconst stmt = ast.body[0] as hbs.AST.MustacheStatement;\n\t\tif (stmt.params.length === 0 && !stmt.hash) {\n\t\t\treturn resolveExpression(stmt.path, data, identifierData, ctx?.helpers);\n\t\t}\n\t}\n\n\t// ── Case 1b: single expression with surrounding whitespace `  {{expr}}  `\n\tconst singleExpr = getEffectivelySingleExpression(ast);\n\tif (singleExpr && singleExpr.params.length === 0 && !singleExpr.hash) {\n\t\treturn resolveExpression(\n\t\t\tsingleExpr.path,\n\t\t\tdata,\n\t\t\tidentifierData,\n\t\t\tctx?.helpers,\n\t\t);\n\t}\n\n\t// ── Case 1c: single expression with helper (params > 0) ──────────────\n\t// E.g. `{{ divide accountIds.length 10 }}` or `{{ math a \"+\" b }}`\n\t// The helper returns a typed value but Handlebars converts it to a\n\t// string. We render via Handlebars then coerce the result to recover\n\t// the original type (number, boolean, null).\n\tif (singleExpr && (singleExpr.params.length > 0 || singleExpr.hash)) {\n\t\t// ── Special case: helpers that return non-primitive values ────────\n\t\t// Some helpers (e.g. `map`) return arrays or objects. Handlebars\n\t\t// would stringify these, so we resolve their arguments directly and\n\t\t// call the helper's fn to preserve the raw return value.\n\t\tconst directResult = tryDirectHelperExecution(singleExpr, data, ctx);\n\t\tif (directResult !== undefined) {\n\t\t\treturn directResult.value;\n\t\t}\n\n\t\tconst merged = mergeDataWithIdentifiers(data, identifierData);\n\t\tconst raw = renderWithHandlebars(template, merged, ctx);\n\t\treturn coerceValue(raw, ctx?.coerceSchema);\n\t}\n\n\t// ── Case 2: fast-path for simple templates (text + expressions) ──────\n\t// If the template only contains text and simple expressions (no blocks,\n\t// no helpers with parameters), we can do direct concatenation without\n\t// going through Handlebars.compile().\n\tif (canUseFastPath(ast) && ast.body.length > 1) {\n\t\treturn executeFastPath(ast, data, identifierData);\n\t}\n\n\t// ── Case 3: single block (possibly surrounded by whitespace) ─────────\n\t// Render via Handlebars then attempt to coerce the result to the\n\t// detected literal type (number, boolean, null).\n\tconst singleBlock = getEffectivelySingleBlock(ast);\n\tif (singleBlock) {\n\t\tconst merged = mergeDataWithIdentifiers(data, identifierData);\n\t\tconst raw = renderWithHandlebars(template, merged, ctx);\n\t\treturn coerceValue(raw, ctx?.coerceSchema);\n\t}\n\n\t// ── Case 4: mixed template ───────────────────────────────────────────\n\t// For purely static templates (only ContentStatements), coerce the\n\t// result to match the coerceSchema type or auto-detect the literal type.\n\t// For truly mixed templates (text + blocks + expressions), return string.\n\tconst merged = mergeDataWithIdentifiers(data, identifierData);\n\tconst raw = renderWithHandlebars(template, merged, ctx);\n\n\tconst effective = getEffectiveBody(ast);\n\tconst allContent = effective.every((s) => s.type === \"ContentStatement\");\n\tif (allContent) {\n\t\treturn coerceValue(raw, ctx?.coerceSchema);\n\t}\n\n\treturn raw;\n}\n\n// ─── Value Coercion ──────────────────────────────────────────────────────────\n// Coerces a raw string from Handlebars rendering based on an optional\n// coerceSchema. When no schema is provided, falls back to auto-detection\n// via `coerceLiteral`.\n\n/**\n * Coerces a raw string value based on an optional coercion schema.\n *\n * - If `coerceSchema` declares a primitive type (`string`, `number`,\n *   `integer`, `boolean`, `null`), the value is cast to that type.\n * - Otherwise, falls back to `coerceLiteral` (auto-detection).\n *\n * @param raw          - The raw string from Handlebars rendering\n * @param coerceSchema - Optional schema declaring the desired output type\n * @returns The coerced value\n */\nfunction coerceValue(raw: string, coerceSchema?: JSONSchema7): unknown {\n\tif (coerceSchema) {\n\t\tconst targetType = coerceSchema.type;\n\t\tif (typeof targetType === \"string\") {\n\t\t\tif (targetType === \"string\") return raw;\n\t\t\tif (targetType === \"number\" || targetType === \"integer\")\n\t\t\t\treturn Number(raw.trim());\n\t\t\tif (targetType === \"boolean\") return raw.trim() === \"true\";\n\t\t\tif (targetType === \"null\") return null;\n\t\t}\n\t}\n\t// No coerceSchema or non-primitive type → auto-detect\n\treturn coerceLiteral(raw);\n}\n\n// ─── Fast-Path Execution ─────────────────────────────────────────────────────\n// For templates consisting only of text and simple expressions (no blocks,\n// no helpers), we bypass Handlebars and do direct concatenation.\n// This is significantly faster.\n\n/**\n * Executes a template via the fast-path (direct concatenation).\n *\n * Precondition: `canUseFastPath(ast)` must return `true`.\n *\n * @param ast            - The template AST (only ContentStatement and simple MustacheStatement)\n * @param data           - The context data\n * @param identifierData - Data by identifier (optional)\n * @returns The resulting string\n */\nfunction executeFastPath(\n\tast: hbs.AST.Program,\n\tdata: unknown,\n\tidentifierData?: Record<number, Record<string, unknown>>,\n): string {\n\tlet result = \"\";\n\n\tfor (const stmt of ast.body) {\n\t\tif (stmt.type === \"ContentStatement\") {\n\t\t\tresult += (stmt as hbs.AST.ContentStatement).value;\n\t\t} else if (stmt.type === \"MustacheStatement\") {\n\t\t\tconst value = resolveExpression(\n\t\t\t\t(stmt as hbs.AST.MustacheStatement).path,\n\t\t\t\tdata,\n\t\t\t\tidentifierData,\n\t\t\t);\n\t\t\t// Handlebars converts values to strings for rendering.\n\t\t\t// We replicate this behavior: null/undefined → \"\", otherwise String(value).\n\t\t\tif (value != null) {\n\t\t\t\tresult += String(value);\n\t\t\t}\n\t\t}\n\t}\n\n\treturn result;\n}\n\n// ─── Direct Expression Resolution ────────────────────────────────────────────\n// Used for single-expression templates and the fast-path, to return the raw\n// value without going through the Handlebars engine.\n\n/**\n * Resolves an AST expression by following the path through the data.\n *\n * If the expression contains an identifier (e.g. `meetingId:1`), resolution\n * is performed in `identifierData[1]` instead of `data`.\n *\n * @param expr           - The AST expression to resolve\n * @param data           - The main data context\n * @param identifierData - Data by identifier (optional)\n * @returns The raw value pointed to by the expression\n */\nfunction resolveExpression(\n\texpr: hbs.AST.Expression,\n\tdata: unknown,\n\tidentifierData?: Record<number, Record<string, unknown>>,\n\thelpers?: Map<string, HelperDefinition>,\n): unknown {\n\t// this / . → return the entire context\n\tif (isThisExpression(expr)) {\n\t\treturn data;\n\t}\n\n\t// Literals\n\tif (expr.type === \"StringLiteral\")\n\t\treturn (expr as hbs.AST.StringLiteral).value;\n\tif (expr.type === \"NumberLiteral\")\n\t\treturn (expr as hbs.AST.NumberLiteral).value;\n\tif (expr.type === \"BooleanLiteral\")\n\t\treturn (expr as hbs.AST.BooleanLiteral).value;\n\tif (expr.type === \"NullLiteral\") return null;\n\tif (expr.type === \"UndefinedLiteral\") return undefined;\n\n\t// ── SubExpression (nested helper call) ────────────────────────────────\n\t// E.g. `(map users 'cartItems')` used as an argument to another helper.\n\t// Resolve all arguments recursively and call the helper's fn directly.\n\tif (expr.type === \"SubExpression\") {\n\t\tconst subExpr = expr as hbs.AST.SubExpression;\n\t\tif (subExpr.path.type === \"PathExpression\") {\n\t\t\tconst helperName = (subExpr.path as hbs.AST.PathExpression).original;\n\t\t\tconst helper = helpers?.get(helperName);\n\t\t\tif (helper) {\n\t\t\t\tconst isMap = helperName === MapHelpers.MAP_HELPER_NAME;\n\t\t\t\tconst resolvedArgs: unknown[] = [];\n\t\t\t\tfor (let i = 0; i < subExpr.params.length; i++) {\n\t\t\t\t\tconst param = subExpr.params[i] as hbs.AST.Expression;\n\t\t\t\t\t// For `map`, the second argument is a property name literal\n\t\t\t\t\tif (isMap && i === 1 && param.type === \"StringLiteral\") {\n\t\t\t\t\t\tresolvedArgs.push((param as hbs.AST.StringLiteral).value);\n\t\t\t\t\t} else {\n\t\t\t\t\t\tresolvedArgs.push(\n\t\t\t\t\t\t\tresolveExpression(param, data, identifierData, helpers),\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\treturn helper.fn(...resolvedArgs);\n\t\t\t}\n\t\t}\n\t\t// Unknown sub-expression helper — return undefined\n\t\treturn undefined;\n\t}\n\n\t// PathExpression — navigate through segments in the data object\n\tconst segments = extractPathSegments(expr);\n\tif (segments.length === 0) {\n\t\tthrow new TemplateRuntimeError(\n\t\t\t`Cannot resolve expression of type \"${expr.type}\"`,\n\t\t);\n\t}\n\n\t// Extract the potential identifier from the last segment BEFORE\n\t// checking for $root, so that both {{$root}} and {{$root:N}} are\n\t// handled uniformly.\n\tconst { cleanSegments, identifier } = extractExpressionIdentifier(segments);\n\n\t// $root path traversal ($root.name) — not supported, return undefined\n\t// (the analyzer already rejects it with a diagnostic).\n\tif (isRootPathTraversal(cleanSegments)) {\n\t\treturn undefined;\n\t}\n\n\t// $root → return the entire data context (or identifier data)\n\tif (isRootSegments(cleanSegments)) {\n\t\tif (identifier !== null && identifierData) {\n\t\t\tconst source = identifierData[identifier];\n\t\t\treturn source ?? undefined;\n\t\t}\n\t\tif (identifier !== null) {\n\t\t\t// Template uses an identifier but no identifierData was provided\n\t\t\treturn undefined;\n\t\t}\n\t\treturn data;\n\t}\n\n\tif (identifier !== null && identifierData) {\n\t\tconst source = identifierData[identifier];\n\t\tif (source) {\n\t\t\treturn resolveDataPath(source, cleanSegments);\n\t\t}\n\t\t// Source does not exist → undefined (like a missing key)\n\t\treturn undefined;\n\t}\n\n\tif (identifier !== null && !identifierData) {\n\t\t// Template uses an identifier but no identifierData was provided\n\t\treturn undefined;\n\t}\n\n\treturn resolveDataPath(data, cleanSegments);\n}\n\n/**\n * Navigates through a data object by following a path of segments.\n *\n * @param data     - The data object\n * @param segments - The path segments (e.g. `[\"user\", \"address\", \"city\"]`)\n * @returns The value at the end of the path, or `undefined` if an\n *          intermediate segment is null/undefined\n */\nexport function resolveDataPath(data: unknown, segments: string[]): unknown {\n\tlet current: unknown = data;\n\n\tfor (const segment of segments) {\n\t\tif (current === null || current === undefined) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tif (typeof current !== \"object\") {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tcurrent = (current as Record<string, unknown>)[segment];\n\t}\n\n\treturn current;\n}\n\n// ─── Data Merging ────────────────────────────────────────────────────────────\n// For Handlebars rendering (mixed templates / blocks), we cannot intercept\n// resolution on a per-expression basis. Instead, we merge identifier data\n// into the main object using the format `\"key:N\"`.\n//\n// Handlebars parses `{{meetingId:1}}` as a PathExpression with a single\n// segment `\"meetingId:1\"`, so it looks up the key `\"meetingId:1\"` in the\n// data object — which matches our flattened format exactly.\n\n/**\n * Merges the main data with identifier data.\n *\n * @param data           - Main data\n * @param identifierData - Data by identifier\n * @returns A merged object where identifier data appears as `\"key:N\"` keys\n *\n * @example\n * ```\n * mergeDataWithIdentifiers(\n *   { name: \"Alice\" },\n *   { 1: { meetingId: \"val1\" }, 2: { meetingId: \"val2\" } }\n * )\n * // → { name: \"Alice\", \"meetingId:1\": \"val1\", \"meetingId:2\": \"val2\" }\n * ```\n */\nfunction mergeDataWithIdentifiers(\n\tdata: unknown,\n\tidentifierData?: Record<number, Record<string, unknown>>,\n): Record<string, unknown> {\n\t// Always include $root so that Handlebars can resolve {{$root}} in\n\t// mixed templates and block helpers (where we delegate to Handlebars\n\t// instead of resolving expressions ourselves).\n\t// When data is a primitive (e.g. number passed with {{$root}}), we\n\t// wrap it into an object so Handlebars can still function.\n\tconst base: Record<string, unknown> =\n\t\tdata !== null && typeof data === \"object\" && !Array.isArray(data)\n\t\t\t? (data as Record<string, unknown>)\n\t\t\t: {};\n\tconst merged: Record<string, unknown> = { ...base, [ROOT_TOKEN]: data };\n\n\tif (!identifierData) return merged;\n\n\tfor (const [id, idData] of Object.entries(identifierData)) {\n\t\t// Add `$root:N` so Handlebars can resolve {{$root:N}} in mixed/block\n\t\t// templates (where we delegate to Handlebars instead of resolving\n\t\t// expressions ourselves). The value is the entire identifier data object.\n\t\tmerged[`${ROOT_TOKEN}:${id}`] = idData;\n\n\t\tfor (const [key, value] of Object.entries(idData)) {\n\t\t\tmerged[`${key}:${id}`] = value;\n\t\t}\n\t}\n\n\treturn merged;\n}\n\n// ─── Handlebars Rendering ────────────────────────────────────────────────────\n// For complex templates (blocks, helpers), we delegate to Handlebars.\n// Compilation is cached to avoid costly recompilations.\n\n/**\n * Compiles and executes a template via Handlebars.\n *\n * Uses a compilation cache (LRU) to avoid recompiling the same template\n * on repeated calls. The cache is either:\n * - The global cache (for the standalone `execute()` function)\n * - The instance cache provided via `ExecutorContext` (for `Typebars`)\n *\n * @param template - The template string\n * @param data     - The context data\n * @param ctx      - Optional execution context (cache, Handlebars env)\n * @returns Always a string\n */\nfunction renderWithHandlebars(\n\ttemplate: string,\n\tdata: Record<string, unknown>,\n\tctx?: ExecutorContext,\n): string {\n\ttry {\n\t\t// 1. Use the pre-compiled template if available (CompiledTemplate)\n\t\tif (ctx?.compiledTemplate) {\n\t\t\treturn ctx.compiledTemplate(data);\n\t\t}\n\n\t\t// 2. Look up in the cache (instance or global)\n\t\tconst cache = ctx?.compilationCache ?? globalCompilationCache;\n\t\tconst hbs = ctx?.hbs ?? Handlebars;\n\n\t\tlet compiled = cache.get(template);\n\t\tif (!compiled) {\n\t\t\tcompiled = hbs.compile(template, {\n\t\t\t\t// Disable HTML-escaping by default — this engine is not\n\t\t\t\t// HTML-specific, we want raw values.\n\t\t\t\tnoEscape: true,\n\t\t\t\t// Strict mode: throws if a path does not exist in the data.\n\t\t\t\tstrict: false,\n\t\t\t});\n\t\t\tcache.set(template, compiled);\n\t\t}\n\n\t\treturn compiled(data);\n\t} catch (error: unknown) {\n\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\tthrow new TemplateRuntimeError(message);\n\t}\n}\n\n/**\n * Clears the global Handlebars compilation cache.\n * Useful for tests or to free memory.\n */\nexport function clearCompilationCache(): void {\n\tglobalCompilationCache.clear();\n}\n\n// ─── Direct Helper Execution ─────────────────────────────────────────────────\n// Some helpers (e.g. `map`) return non-primitive values (arrays, objects)\n// that Handlebars would stringify. For these helpers, we resolve their\n// arguments directly and call the helper's `fn` to preserve the raw value.\n\n/** Set of helper names that must be executed directly (bypass Handlebars) */\nconst DIRECT_EXECUTION_HELPERS = new Set<string>([MapHelpers.MAP_HELPER_NAME]);\n\n/**\n * Attempts to execute a helper directly (without Handlebars rendering).\n *\n * Returns `{ value }` if the helper was executed directly, or `undefined`\n * if the helper should go through the normal Handlebars rendering path.\n *\n * @param stmt - The MustacheStatement containing the helper call\n * @param data - The context data\n * @param ctx  - Optional execution context (with helpers and identifierData)\n */\nfunction tryDirectHelperExecution(\n\tstmt: hbs.AST.MustacheStatement,\n\tdata: unknown,\n\tctx?: ExecutorContext,\n): { value: unknown } | undefined {\n\t// Get the helper name from the path\n\tif (stmt.path.type !== \"PathExpression\") return undefined;\n\tconst helperName = (stmt.path as hbs.AST.PathExpression).original;\n\n\t// Only intercept known direct-execution helpers\n\tif (!DIRECT_EXECUTION_HELPERS.has(helperName)) return undefined;\n\n\t// Look up the helper definition\n\tconst helper = ctx?.helpers?.get(helperName);\n\tif (!helper) return undefined;\n\n\t// Resolve each argument from the data context.\n\t// For the `map` helper, the resolution strategy is:\n\t//   - Arg 0 (array): resolve as a data path (e.g. `users` → array)\n\t//   - Arg 1 (property):   must be a StringLiteral (e.g. `\"name\"`)\n\t//     The analyzer enforces this — bare identifiers like `name` are\n\t//     rejected at analysis time because Handlebars would resolve them\n\t//     as a data path instead of a literal property name.\n\tconst isMap = helperName === MapHelpers.MAP_HELPER_NAME;\n\n\tconst resolvedArgs: unknown[] = [];\n\tfor (let i = 0; i < stmt.params.length; i++) {\n\t\tconst param = stmt.params[i] as hbs.AST.Expression;\n\n\t\t// For `map`, the second argument (index 1) is a property name —\n\t\t// it must be a StringLiteral (enforced by the analyzer).\n\t\tif (isMap && i === 1) {\n\t\t\tif (param.type === \"StringLiteral\") {\n\t\t\t\tresolvedArgs.push((param as hbs.AST.StringLiteral).value);\n\t\t\t} else {\n\t\t\t\t// Fallback: resolve normally (will likely be undefined at runtime)\n\t\t\t\tresolvedArgs.push(\n\t\t\t\t\tresolveExpression(param, data, ctx?.identifierData, ctx?.helpers),\n\t\t\t\t);\n\t\t\t}\n\t\t} else {\n\t\t\tresolvedArgs.push(\n\t\t\t\tresolveExpression(param, data, ctx?.identifierData, ctx?.helpers),\n\t\t\t);\n\t\t}\n\t}\n\n\t// Call the helper's fn directly with the resolved arguments\n\tconst value = helper.fn(...resolvedArgs);\n\treturn { value };\n}\n"],"names":["clearCompilationCache","execute","executeFromAst","resolveDataPath","globalCompilationCache","LRUCache","template","data","identifierData","dispatchExecute","undefined","tpl","ast","parse","child","ctx","isSingleExpression","stmt","body","params","length","hash","resolveExpression","path","helpers","singleExpr","getEffectivelySingleExpression","directResult","tryDirectHelperExecution","value","merged","mergeDataWithIdentifiers","raw","renderWithHandlebars","coerceValue","coerceSchema","canUseFastPath","executeFastPath","singleBlock","getEffectivelySingleBlock","effective","getEffectiveBody","allContent","every","s","type","targetType","Number","trim","coerceLiteral","result","String","expr","isThisExpression","subExpr","helperName","original","helper","get","isMap","MapHelpers","MAP_HELPER_NAME","resolvedArgs","i","param","push","fn","segments","extractPathSegments","TemplateRuntimeError","cleanSegments","identifier","extractExpressionIdentifier","isRootPathTraversal","isRootSegments","source","current","segment","base","Array","isArray","ROOT_TOKEN","id","idData","Object","entries","key","compiledTemplate","cache","compilationCache","hbs","Handlebars","compiled","compile","noEscape","strict","set","error","message","Error","clear","DIRECT_EXECUTION_HELPERS","Set","has"],"mappings":"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"}

package/dist/cjs/helpers/index.d.ts

@@ -1,5 +1,5 @@
-export { CollectionHelpers } from "./collection-helpers.js";
 export { HelperFactory, type HelperRegistry } from "./helper-factory.js";
 export { LogicalHelpers } from "./logical-helpers.js";
+export { MapHelpers } from "./map-helpers.js";
 export { MathHelpers } from "./math-helpers.js";
 export { toNumber } from "./utils.js";

package/dist/cjs/helpers/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:true});function _export(target,all){for(var name in all)Object.defineProperty(target,name,{enumerable:true,get:Object.getOwnPropertyDescriptor(all,name).get})}_export(exports,{get CollectionHelpers(){return _collectionhelpers.CollectionHelpers},get HelperFactory(){return _helperfactory.HelperFactory},get LogicalHelpers(){return _logicalhelpers.LogicalHelpers},get MathHelpers(){return _mathhelpers.MathHelpers},get toNumber(){return _utils.toNumber}});const _collectionhelpers=require("./collection-helpers.js");const _helperfactory=require("./helper-factory.js");const _logicalhelpers=require("./logical-helpers.js");const _mathhelpers=require("./math-helpers.js");const _utils=require("./utils.js");
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});function _export(target,all){for(var name in all)Object.defineProperty(target,name,{enumerable:true,get:Object.getOwnPropertyDescriptor(all,name).get})}_export(exports,{get HelperFactory(){return _helperfactory.HelperFactory},get LogicalHelpers(){return _logicalhelpers.LogicalHelpers},get MapHelpers(){return _maphelpers.MapHelpers},get MathHelpers(){return _mathhelpers.MathHelpers},get toNumber(){return _utils.toNumber}});const _helperfactory=require("./helper-factory.js");const _logicalhelpers=require("./logical-helpers.js");const _maphelpers=require("./map-helpers.js");const _mathhelpers=require("./math-helpers.js");const _utils=require("./utils.js");
 //# sourceMappingURL=index.js.map

package/dist/cjs/helpers/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/helpers/index.ts"],"sourcesContent":["export { CollectionHelpers } from \"./collection-helpers\";\nexport { HelperFactory, type HelperRegistry } from \"./helper-factory\";\nexport { LogicalHelpers } from \"./logical-helpers\";\nexport { MathHelpers } from \"./math-helpers\";\nexport { toNumber } from \"./utils\";\n"],"names":["CollectionHelpers","HelperFactory","LogicalHelpers","MathHelpers","toNumber"],"mappings":"mPAASA,2BAAAA,oCAAiB,MACjBC,uBAAAA,4BAAa,MACbC,wBAAAA,8BAAc,MACdC,qBAAAA,wBAAW,MACXC,kBAAAA,eAAQ,qCAJiB,qDACiB,kDACpB,gDACH,uCACH"}
+{"version":3,"sources":["../../../src/helpers/index.ts"],"sourcesContent":["export { HelperFactory, type HelperRegistry } from \"./helper-factory\";\nexport { LogicalHelpers } from \"./logical-helpers\";\nexport { MapHelpers } from \"./map-helpers\";\nexport { MathHelpers } from \"./math-helpers\";\nexport { toNumber } from \"./utils\";\n"],"names":["HelperFactory","LogicalHelpers","MapHelpers","MathHelpers","toNumber"],"mappings":"mPAASA,uBAAAA,4BAAa,MACbC,wBAAAA,8BAAc,MACdC,oBAAAA,sBAAU,MACVC,qBAAAA,wBAAW,MACXC,kBAAAA,eAAQ,iCAJkC,kDACpB,+CACJ,4CACC,uCACH"}

package/dist/cjs/helpers/{collection-helpers.d.ts → map-helpers.d.ts}

@@ -1,9 +1,9 @@
 import type { HelperDefinition } from "../types.js";
 import { HelperFactory } from "./helper-factory.js";
-export declare class CollectionHelpers extends HelperFactory {
+export declare class MapHelpers extends HelperFactory {
     /** The name used for special-case detection in the analyzer/executor */
-    static readonly COLLECT_HELPER_NAME = "collect";
+    static readonly MAP_HELPER_NAME = "map";
     protected buildDefinitions(defs: Map<string, HelperDefinition>): void;
-    /** Registers the `collect` helper */
-    private registerCollect;
+    /** Registers the `map` helper */
+    private registerMap;
 }

package/dist/cjs/helpers/map-helpers.js

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});Object.defineProperty(exports,"MapHelpers",{enumerable:true,get:function(){return MapHelpers}});const _helperfactoryts=require("./helper-factory.js");function _define_property(obj,key,value){if(key in obj){Object.defineProperty(obj,key,{value:value,enumerable:true,configurable:true,writable:true})}else{obj[key]=value}return obj}function mapProperty(array,property){if(!Array.isArray(array)){return[]}const prop=String(property);const flattened=array.flat(1);return flattened.map(item=>{if(item!==null&&item!==undefined&&typeof item==="object"){return item[prop]}return undefined})}class MapHelpers extends _helperfactoryts.HelperFactory{buildDefinitions(defs){this.registerMap(defs)}registerMap(defs){defs.set(MapHelpers.MAP_HELPER_NAME,{fn:(array,property)=>mapProperty(array,property),params:[{name:"array",type:{type:"array"},description:"The array of objects to extract values from"},{name:"property",type:{type:"string"},description:"The property name to extract from each element"}],returnType:{type:"array"},description:'Extracts a property from each element of an array: {{ map users "name" }} → ["Alice", "Bob", "Charlie"]'})}}_define_property(MapHelpers,"MAP_HELPER_NAME","map");
+//# sourceMappingURL=map-helpers.js.map

package/dist/cjs/helpers/map-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/helpers/map-helpers.ts"],"sourcesContent":["import type { HelperDefinition } from \"../types.ts\";\nimport { HelperFactory } from \"./helper-factory.ts\";\n\n// ─── MapHelpers ──────────────────────────────────────────────────────────────\n// Aggregates all map-related helpers for the template engine.\n//\n// Provides helpers for working with arrays of objects:\n//\n// - **`map`** — Extracts a specific property from each element of an\n//   array, returning a new array of those values.\n//   Usage: `{{ map users \"name\" }}` → `[\"Alice\", \"Bob\", \"Charlie\"]`\n//\n// ─── Registration ────────────────────────────────────────────────────────────\n// MapHelpers are automatically pre-registered by the `Typebars`\n// constructor. They can also be registered manually on any object\n// implementing `HelperRegistry`:\n//\n//   const factory = new MapHelpers();\n//   factory.register(engine);   // registers all helpers\n//   factory.unregister(engine); // removes all helpers\n//\n// ─── Static Analysis ─────────────────────────────────────────────────────────\n// The `map` helper has special static analysis handling in the analyzer:\n// - The first argument must resolve to an array of objects\n// - The second argument must be a quoted string literal (e.g. `\"name\"`, not `name`)\n// - The property must exist in the item schema of the array\n// - The inferred return type is `{ type: \"array\", items: <property schema> }`\n\n// ─── Internal utilities ─────────────────────────────────────────────────────\n\n/**\n * Extracts a property from each element of an array.\n *\n * @param array    - The array of objects\n * @param property - The property name to extract from each element\n * @returns A new array containing the extracted property values\n */\nfunction mapProperty(array: unknown, property: unknown): unknown[] {\n\tif (!Array.isArray(array)) {\n\t\treturn [];\n\t}\n\tconst prop = String(property);\n\t// Use flatMap semantics: if the array contains nested arrays\n\t// (e.g. from a previous map), flatten one level before extracting.\n\t// This enables chaining like `{{ map (map users 'cartItems') 'productId' }}`\n\t// where the inner map returns an array of arrays.\n\tconst flattened = array.flat(1);\n\treturn flattened.map((item: unknown) => {\n\t\tif (item !== null && item !== undefined && typeof item === \"object\") {\n\t\t\treturn (item as Record<string, unknown>)[prop];\n\t\t}\n\t\treturn undefined;\n\t});\n}\n\n// ─── Main class ─────────────────────────────────────────────────────────────\n\nexport class MapHelpers extends HelperFactory {\n\t/** The name used for special-case detection in the analyzer/executor */\n\tstatic readonly MAP_HELPER_NAME = \"map\";\n\n\t// ─── buildDefinitions (required by HelperFactory) ──────────────────\n\n\tprotected buildDefinitions(defs: Map<string, HelperDefinition>): void {\n\t\tthis.registerMap(defs);\n\t}\n\n\t// ── map ──────────────────────────────────────────────────────────────\n\n\t/** Registers the `map` helper */\n\tprivate registerMap(defs: Map<string, HelperDefinition>): void {\n\t\tdefs.set(MapHelpers.MAP_HELPER_NAME, {\n\t\t\tfn: (array: unknown, property: unknown) => mapProperty(array, property),\n\t\t\tparams: [\n\t\t\t\t{\n\t\t\t\t\tname: \"array\",\n\t\t\t\t\ttype: { type: \"array\" },\n\t\t\t\t\tdescription: \"The array of objects to extract values from\",\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\tname: \"property\",\n\t\t\t\t\ttype: { type: \"string\" },\n\t\t\t\t\tdescription: \"The property name to extract from each element\",\n\t\t\t\t},\n\t\t\t],\n\t\t\treturnType: { type: \"array\" },\n\t\t\tdescription:\n\t\t\t\t'Extracts a property from each element of an array: {{ map users \"name\" }} → [\"Alice\", \"Bob\", \"Charlie\"]',\n\t\t});\n\t}\n}\n"],"names":["MapHelpers","mapProperty","array","property","Array","isArray","prop","String","flattened","flat","map","item","undefined","HelperFactory","buildDefinitions","defs","registerMap","set","MAP_HELPER_NAME","fn","params","name","type","description","returnType"],"mappings":"oGAyDaA,oDAAAA,6CAxDiB,2MAoC9B,SAASC,YAAYC,KAAc,CAAEC,QAAiB,EACrD,GAAI,CAACC,MAAMC,OAAO,CAACH,OAAQ,CAC1B,MAAO,EAAE,AACV,CACA,MAAMI,KAAOC,OAAOJ,UAKpB,MAAMK,UAAYN,MAAMO,IAAI,CAAC,GAC7B,OAAOD,UAAUE,GAAG,CAAC,AAACC,OACrB,GAAIA,OAAS,MAAQA,OAASC,WAAa,OAAOD,OAAS,SAAU,CACpE,OAAO,AAACA,IAAgC,CAACL,KAAK,AAC/C,CACA,OAAOM,SACR,EACD,CAIO,MAAMZ,mBAAmBa,8BAAa,CAM5C,AAAUC,iBAAiBC,IAAmC,CAAQ,CACrE,IAAI,CAACC,WAAW,CAACD,KAClB,CAKA,AAAQC,YAAYD,IAAmC,CAAQ,CAC9DA,KAAKE,GAAG,CAACjB,WAAWkB,eAAe,CAAE,CACpCC,GAAI,CAACjB,MAAgBC,WAAsBF,YAAYC,MAAOC,UAC9DiB,OAAQ,CACP,CACCC,KAAM,QACNC,KAAM,CAAEA,KAAM,OAAQ,EACtBC,YAAa,6CACd,EACA,CACCF,KAAM,WACNC,KAAM,CAAEA,KAAM,QAAS,EACvBC,YAAa,gDACd,EACA,CACDC,WAAY,CAAEF,KAAM,OAAQ,EAC5BC,YACC,yGACF,EACD,CACD,CA/BC,iBAFYvB,WAEIkB,kBAAkB"}

package/dist/cjs/typebars.d.ts

@@ -89,9 +89,7 @@ export declare class Typebars {
      * @returns An object `{ analysis, value }` where `value` is `undefined`
      *          if analysis failed.
      */
-    analyzeAndExecute(template: TemplateInput, inputSchema: JSONSchema7 | undefined, data: TemplateData, options?: AnalyzeAndExecuteOptions & {
-        coerceSchema?: JSONSchema7;
-    }): {
+    analyzeAndExecute(template: TemplateInput, inputSchema: JSONSchema7 | undefined, data: TemplateData, options?: AnalyzeAndExecuteOptions): {
         analysis: AnalysisResult;
         value: unknown;
     };

package/dist/cjs/typebars.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:true});Object.defineProperty(exports,"Typebars",{enumerable:true,get:function(){return Typebars}});const _handlebars=/*#__PURE__*/_interop_require_default(require("handlebars"));const _analyzerts=require("./analyzer.js");const _compiledtemplatets=require("./compiled-template.js");const _dispatchts=require("./dispatch.js");const _errorsts=require("./errors.js");const _executorts=require("./executor.js");const _indexts=require("./helpers/index.js");const _parserts=require("./parser.js");const _typests=require("./types.js");const _utils=require("./utils.js");function _define_property(obj,key,value){if(key in obj){Object.defineProperty(obj,key,{value:value,enumerable:true,configurable:true,writable:true})}else{obj[key]=value}return obj}function _interop_require_default(obj){return obj&&obj.__esModule?obj:{default:obj}}const DIRECT_EXECUTION_HELPER_NAMES=new Set([_indexts.CollectionHelpers.COLLECT_HELPER_NAME]);function stringifyForTemplate(value){if(value===null||value===undefined)return"";if(Array.isArray(value)){return value.map(item=>{if(item===null||item===undefined)return"";if(typeof item==="object")return JSON.stringify(item);return String(item)}).join(", ")}return String(value)}class Typebars{compile(template){if((0,_typests.isArrayInput)(template)){const children=[];for(const element of template){children.push(this.compile(element))}return _compiledtemplatets.CompiledTemplate.fromArray(children,{helpers:this.helpers,hbs:this.hbs,compilationCache:this.compilationCache})}if((0,_typests.isObjectInput)(template)){const children={};for(const[key,value]of Object.entries(template)){children[key]=this.compile(value)}return _compiledtemplatets.CompiledTemplate.fromObject(children,{helpers:this.helpers,hbs:this.hbs,compilationCache:this.compilationCache})}if((0,_typests.isLiteralInput)(template)){return _compiledtemplatets.CompiledTemplate.fromLiteral(template,{helpers:this.helpers,hbs:this.hbs,compilationCache:this.compilationCache})}const ast=this.getCachedAst(template);const options={helpers:this.helpers,hbs:this.hbs,compilationCache:this.compilationCache};return _compiledtemplatets.CompiledTemplate.fromTemplate(ast,template,options)}analyze(template,inputSchema={},options){return(0,_dispatchts.dispatchAnalyze)(template,options,(tpl,coerceSchema)=>{const ast=this.getCachedAst(tpl);return(0,_analyzerts.analyzeFromAst)(ast,tpl,inputSchema,{identifierSchemas:options?.identifierSchemas,helpers:this.helpers,coerceSchema})},(child,childOptions)=>this.analyze(child,inputSchema,childOptions))}validate(template,inputSchema={},options){const analysis=this.analyze(template,inputSchema,options);return{valid:analysis.valid,diagnostics:analysis.diagnostics}}isValidSyntax(template){if((0,_typests.isArrayInput)(template)){return template.every(v=>this.isValidSyntax(v))}if((0,_typests.isObjectInput)(template)){return Object.values(template).every(v=>this.isValidSyntax(v))}if((0,_typests.isLiteralInput)(template))return true;try{this.getCachedAst(template);return true}catch{return false}}execute(template,data,options){return(0,_dispatchts.dispatchExecute)(template,options,(tpl,coerceSchema)=>{const ast=this.getCachedAst(tpl);if(options?.schema){const analysis=(0,_analyzerts.analyzeFromAst)(ast,tpl,options.schema,{identifierSchemas:options?.identifierSchemas,helpers:this.helpers});if(!analysis.valid){throw new _errorsts.TemplateAnalysisError(analysis.diagnostics)}}return(0,_executorts.executeFromAst)(ast,tpl,data,{identifierData:options?.identifierData,hbs:this.hbs,compilationCache:this.compilationCache,coerceSchema,helpers:this.helpers})},(child,childOptions)=>this.execute(child,data,{...options,...childOptions}))}analyzeAndExecute(template,inputSchema={},data,options){return(0,_dispatchts.dispatchAnalyzeAndExecute)(template,options,(tpl,coerceSchema)=>{const ast=this.getCachedAst(tpl);const analysis=(0,_analyzerts.analyzeFromAst)(ast,tpl,inputSchema,{identifierSchemas:options?.identifierSchemas,helpers:this.helpers,coerceSchema});if(!analysis.valid){return{analysis,value:undefined}}const value=(0,_executorts.executeFromAst)(ast,tpl,data,{identifierData:options?.identifierData,hbs:this.hbs,compilationCache:this.compilationCache,coerceSchema,helpers:this.helpers});return{analysis,value}},(child,childOptions)=>this.analyzeAndExecute(child,inputSchema,data,childOptions))}registerHelper(name,definition){this.helpers.set(name,definition);if(DIRECT_EXECUTION_HELPER_NAMES.has(name)){this.hbs.registerHelper(name,(...args)=>{const hbsArgs=args.slice(0,-1);const raw=definition.fn(...hbsArgs);return stringifyForTemplate(raw)})}else{this.hbs.registerHelper(name,definition.fn)}this.compilationCache.clear();return this}unregisterHelper(name){this.helpers.delete(name);this.hbs.unregisterHelper(name);this.compilationCache.clear();return this}hasHelper(name){return this.helpers.has(name)}clearCaches(){this.astCache.clear();this.compilationCache.clear()}getCachedAst(template){let ast=this.astCache.get(template);if(!ast){ast=(0,_parserts.parse)(template);this.astCache.set(template,ast)}return ast}constructor(options={}){_define_property(this,"hbs",void 0);_define_property(this,"astCache",void 0);_define_property(this,"compilationCache",void 0);_define_property(this,"helpers",new Map);this.hbs=_handlebars.default.create();this.astCache=new _utils.LRUCache(options.astCacheSize??256);this.compilationCache=new _utils.LRUCache(options.compilationCacheSize??256);new _indexts.MathHelpers().register(this);new _indexts.LogicalHelpers().register(this);new _indexts.CollectionHelpers().register(this);if(options.helpers){for(const helper of options.helpers){const{name,...definition}=helper;this.registerHelper(name,definition)}}}}
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});Object.defineProperty(exports,"Typebars",{enumerable:true,get:function(){return Typebars}});const _handlebars=/*#__PURE__*/_interop_require_default(require("handlebars"));const _analyzerts=require("./analyzer.js");const _compiledtemplatets=require("./compiled-template.js");const _dispatchts=require("./dispatch.js");const _errorsts=require("./errors.js");const _executorts=require("./executor.js");const _indexts=require("./helpers/index.js");const _parserts=require("./parser.js");const _typests=require("./types.js");const _utils=require("./utils.js");function _define_property(obj,key,value){if(key in obj){Object.defineProperty(obj,key,{value:value,enumerable:true,configurable:true,writable:true})}else{obj[key]=value}return obj}function _interop_require_default(obj){return obj&&obj.__esModule?obj:{default:obj}}const DIRECT_EXECUTION_HELPER_NAMES=new Set([_indexts.MapHelpers.MAP_HELPER_NAME]);function stringifyForTemplate(value){if(value===null||value===undefined)return"";if(Array.isArray(value)){return value.map(item=>{if(item===null||item===undefined)return"";if(typeof item==="object")return JSON.stringify(item);return String(item)}).join(", ")}return String(value)}class Typebars{compile(template){if((0,_typests.isArrayInput)(template)){const children=[];for(const element of template){children.push(this.compile(element))}return _compiledtemplatets.CompiledTemplate.fromArray(children,{helpers:this.helpers,hbs:this.hbs,compilationCache:this.compilationCache})}if((0,_typests.isObjectInput)(template)){const children={};for(const[key,value]of Object.entries(template)){children[key]=this.compile(value)}return _compiledtemplatets.CompiledTemplate.fromObject(children,{helpers:this.helpers,hbs:this.hbs,compilationCache:this.compilationCache})}if((0,_typests.isLiteralInput)(template)){return _compiledtemplatets.CompiledTemplate.fromLiteral(template,{helpers:this.helpers,hbs:this.hbs,compilationCache:this.compilationCache})}const ast=this.getCachedAst(template);const options={helpers:this.helpers,hbs:this.hbs,compilationCache:this.compilationCache};return _compiledtemplatets.CompiledTemplate.fromTemplate(ast,template,options)}analyze(template,inputSchema={},options){return(0,_dispatchts.dispatchAnalyze)(template,options,(tpl,coerceSchema)=>{const ast=this.getCachedAst(tpl);return(0,_analyzerts.analyzeFromAst)(ast,tpl,inputSchema,{identifierSchemas:options?.identifierSchemas,helpers:this.helpers,coerceSchema})},(child,childOptions)=>this.analyze(child,inputSchema,childOptions))}validate(template,inputSchema={},options){const analysis=this.analyze(template,inputSchema,options);return{valid:analysis.valid,diagnostics:analysis.diagnostics}}isValidSyntax(template){if((0,_typests.isArrayInput)(template)){return template.every(v=>this.isValidSyntax(v))}if((0,_typests.isObjectInput)(template)){return Object.values(template).every(v=>this.isValidSyntax(v))}if((0,_typests.isLiteralInput)(template))return true;try{this.getCachedAst(template);return true}catch{return false}}execute(template,data,options){return(0,_dispatchts.dispatchExecute)(template,options,(tpl,coerceSchema)=>{const ast=this.getCachedAst(tpl);if(options?.schema){const analysis=(0,_analyzerts.analyzeFromAst)(ast,tpl,options.schema,{identifierSchemas:options?.identifierSchemas,helpers:this.helpers});if(!analysis.valid){throw new _errorsts.TemplateAnalysisError(analysis.diagnostics)}}return(0,_executorts.executeFromAst)(ast,tpl,data,{identifierData:options?.identifierData,hbs:this.hbs,compilationCache:this.compilationCache,coerceSchema,helpers:this.helpers})},(child,childOptions)=>this.execute(child,data,{...options,...childOptions}))}analyzeAndExecute(template,inputSchema={},data,options){return(0,_dispatchts.dispatchAnalyzeAndExecute)(template,options,(tpl,coerceSchema)=>{const ast=this.getCachedAst(tpl);const analysis=(0,_analyzerts.analyzeFromAst)(ast,tpl,inputSchema,{identifierSchemas:options?.identifierSchemas,helpers:this.helpers,coerceSchema});if(!analysis.valid){return{analysis,value:undefined}}const value=(0,_executorts.executeFromAst)(ast,tpl,data,{identifierData:options?.identifierData,hbs:this.hbs,compilationCache:this.compilationCache,coerceSchema,helpers:this.helpers});return{analysis,value}},(child,childOptions)=>this.analyzeAndExecute(child,inputSchema,data,childOptions))}registerHelper(name,definition){this.helpers.set(name,definition);if(DIRECT_EXECUTION_HELPER_NAMES.has(name)){this.hbs.registerHelper(name,(...args)=>{const hbsArgs=args.slice(0,-1);const raw=definition.fn(...hbsArgs);return stringifyForTemplate(raw)})}else{this.hbs.registerHelper(name,definition.fn)}this.compilationCache.clear();return this}unregisterHelper(name){this.helpers.delete(name);this.hbs.unregisterHelper(name);this.compilationCache.clear();return this}hasHelper(name){return this.helpers.has(name)}clearCaches(){this.astCache.clear();this.compilationCache.clear()}getCachedAst(template){let ast=this.astCache.get(template);if(!ast){ast=(0,_parserts.parse)(template);this.astCache.set(template,ast)}return ast}constructor(options={}){_define_property(this,"hbs",void 0);_define_property(this,"astCache",void 0);_define_property(this,"compilationCache",void 0);_define_property(this,"helpers",new Map);this.hbs=_handlebars.default.create();this.astCache=new _utils.LRUCache(options.astCacheSize??256);this.compilationCache=new _utils.LRUCache(options.compilationCacheSize??256);new _indexts.MathHelpers().register(this);new _indexts.LogicalHelpers().register(this);new _indexts.MapHelpers().register(this);if(options.helpers){for(const helper of options.helpers){const{name,...definition}=helper;this.registerHelper(name,definition)}}}}
 //# sourceMappingURL=typebars.js.map

package/dist/cjs/typebars.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/typebars.ts"],"sourcesContent":["import Handlebars from \"handlebars\";\nimport type { JSONSchema7 } from \"json-schema\";\nimport type { AnalyzeOptions } from \"./analyzer.ts\";\nimport { analyzeFromAst } from \"./analyzer.ts\";\nimport {\n\tCompiledTemplate,\n\ttype CompiledTemplateOptions,\n} from \"./compiled-template.ts\";\nimport {\n\tdispatchAnalyze,\n\tdispatchAnalyzeAndExecute,\n\tdispatchExecute,\n} from \"./dispatch.ts\";\nimport { TemplateAnalysisError } from \"./errors.ts\";\nimport { executeFromAst } from \"./executor.ts\";\nimport {\n\tCollectionHelpers,\n\tLogicalHelpers,\n\tMathHelpers,\n} from \"./helpers/index.ts\";\nimport { parse } from \"./parser.ts\";\nimport type {\n\tAnalysisResult,\n\tAnalyzeAndExecuteOptions,\n\tExecuteOptions,\n\tHelperDefinition,\n\tTemplateData,\n\tTemplateEngineOptions,\n\tTemplateInput,\n\tValidationResult,\n} from \"./types.ts\";\nimport { isArrayInput, isLiteralInput, isObjectInput } from \"./types.ts\";\nimport { LRUCache } from \"./utils\";\n\n// ─── Typebars ────────────────────────────────────────────────────────────────\n// Public entry point of the template engine. Orchestrates three phases:\n//\n// 1. **Parsing**   — transforms the template string into an AST (via Handlebars)\n// 2. **Analysis**  — static validation + return type inference\n// 3. **Execution** — renders the template with real data\n//\n// ─── Architecture v2 ─────────────────────────────────────────────────────────\n// - **LRU cache** for parsed ASTs and compiled Handlebars templates\n// - **Isolated Handlebars environment** per instance (custom helpers)\n// - **`compile()` pattern**: parse-once / execute-many\n// - **`validate()` method**: API shortcut without `outputSchema`\n// - **`registerHelper()`**: custom helpers with static typing\n// - **`ExecuteOptions`**: options object for `execute()`\n//\n// ─── Template Identifiers ────────────────────────────────────────────────────\n// The `{{key:N}}` syntax allows referencing variables from specific data\n// sources, identified by an integer N.\n//\n// - `identifierSchemas`: mapping `{ [id]: JSONSchema7 }` for static analysis\n// - `identifierData`:    mapping `{ [id]: Record<string, unknown> }` for execution\n//\n// Usage:\n//   engine.execute(\"{{meetingId:1}}\", data, { identifierData: { 1: node1Data } });\n//   engine.analyze(\"{{meetingId:1}}\", schema, { identifierSchemas: { 1: node1Schema } });\n\n// ─── Direct Execution Helper Names ───────────────────────────────────────────\n// Helpers whose return values are non-primitive (arrays, objects) and must be\n// wrapped when registered with Handlebars so that mixed/block templates get a\n// human-readable string (e.g. `\", \"` joined) instead of JS default toString().\n// In single-expression mode the executor bypasses Handlebars entirely, so the\n// raw value is preserved.\nconst DIRECT_EXECUTION_HELPER_NAMES = new Set<string>([\n\tCollectionHelpers.COLLECT_HELPER_NAME,\n]);\n\n/**\n * Converts a value to a string suitable for embedding in a Handlebars template.\n *\n * - Arrays of primitives are joined with `\", \"`\n * - Arrays of objects are JSON-stringified per element, then joined\n * - Primitives use `String(value)`\n * - null/undefined become `\"\"`\n */\nfunction stringifyForTemplate(value: unknown): string {\n\tif (value === null || value === undefined) return \"\";\n\tif (Array.isArray(value)) {\n\t\treturn value\n\t\t\t.map((item) => {\n\t\t\t\tif (item === null || item === undefined) return \"\";\n\t\t\t\tif (typeof item === \"object\") return JSON.stringify(item);\n\t\t\t\treturn String(item);\n\t\t\t})\n\t\t\t.join(\", \");\n\t}\n\treturn String(value);\n}\n\n// ─── Main Class ──────────────────────────────────────────────────────────────\n\nexport class Typebars {\n\t/** Isolated Handlebars environment — each engine has its own helpers */\n\tprivate readonly hbs: typeof Handlebars;\n\n\t/** LRU cache of parsed ASTs (avoids re-parsing) */\n\tprivate readonly astCache: LRUCache<string, hbs.AST.Program>;\n\n\t/** LRU cache of compiled Handlebars templates (avoids recompilation) */\n\tprivate readonly compilationCache: LRUCache<\n\t\tstring,\n\t\tHandlebarsTemplateDelegate\n\t>;\n\n\t/** Custom helpers registered on this instance */\n\tprivate readonly helpers = new Map<string, HelperDefinition>();\n\n\tconstructor(options: TemplateEngineOptions = {}) {\n\t\tthis.hbs = Handlebars.create();\n\t\tthis.astCache = new LRUCache(options.astCacheSize ?? 256);\n\t\tthis.compilationCache = new LRUCache(options.compilationCacheSize ?? 256);\n\n\t\t// ── Built-in helpers ─────────────────────────────────────────────\n\t\tnew MathHelpers().register(this);\n\t\tnew LogicalHelpers().register(this);\n\t\tnew CollectionHelpers().register(this);\n\n\t\t// ── Custom helpers via options ───────────────────────────────────\n\t\tif (options.helpers) {\n\t\t\tfor (const helper of options.helpers) {\n\t\t\t\tconst { name, ...definition } = helper;\n\t\t\t\tthis.registerHelper(name, definition);\n\t\t\t}\n\t\t}\n\t}\n\n\t// ─── Compilation ───────────────────────────────────────────────────────\n\n\t/**\n\t * Compiles a template and returns a `CompiledTemplate` ready to be\n\t * executed or analyzed without re-parsing.\n\t *\n\t * Accepts a `TemplateInput`: string, number, boolean, null, or object.\n\t * For objects, each property is compiled recursively.\n\t *\n\t * @param template - The template to compile\n\t * @returns A reusable `CompiledTemplate`\n\t */\n\tcompile(template: TemplateInput): CompiledTemplate {\n\t\tif (isArrayInput(template)) {\n\t\t\tconst children: CompiledTemplate[] = [];\n\t\t\tfor (const element of template) {\n\t\t\t\tchildren.push(this.compile(element));\n\t\t\t}\n\t\t\treturn CompiledTemplate.fromArray(children, {\n\t\t\t\thelpers: this.helpers,\n\t\t\t\thbs: this.hbs,\n\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t});\n\t\t}\n\t\tif (isObjectInput(template)) {\n\t\t\tconst children: Record<string, CompiledTemplate> = {};\n\t\t\tfor (const [key, value] of Object.entries(template)) {\n\t\t\t\tchildren[key] = this.compile(value);\n\t\t\t}\n\t\t\treturn CompiledTemplate.fromObject(children, {\n\t\t\t\thelpers: this.helpers,\n\t\t\t\thbs: this.hbs,\n\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t});\n\t\t}\n\t\tif (isLiteralInput(template)) {\n\t\t\treturn CompiledTemplate.fromLiteral(template, {\n\t\t\t\thelpers: this.helpers,\n\t\t\t\thbs: this.hbs,\n\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t});\n\t\t}\n\t\tconst ast = this.getCachedAst(template);\n\t\tconst options: CompiledTemplateOptions = {\n\t\t\thelpers: this.helpers,\n\t\t\thbs: this.hbs,\n\t\t\tcompilationCache: this.compilationCache,\n\t\t};\n\t\treturn CompiledTemplate.fromTemplate(ast, template, options);\n\t}\n\n\t// ─── Static Analysis ─────────────────────────────────────────────────────\n\n\t/**\n\t * Statically analyzes a template against a JSON Schema v7 describing\n\t * the available context.\n\t *\n\t * Accepts a `TemplateInput`: string, number, boolean, null, or object.\n\t * For objects, each property is analyzed recursively and the\n\t * `outputSchema` reflects the object structure with resolved types.\n\t *\n\t * @param template    - The template to analyze\n\t * @param inputSchema - JSON Schema v7 describing the available variables\n\t * @param options     - (optional) Analysis options (identifierSchemas, coerceSchema)\n\t */\n\tanalyze(\n\t\ttemplate: TemplateInput,\n\t\tinputSchema: JSONSchema7 = {},\n\t\toptions?: AnalyzeOptions,\n\t): AnalysisResult {\n\t\treturn dispatchAnalyze(\n\t\t\ttemplate,\n\t\t\toptions,\n\t\t\t// String handler — parse with cache and analyze the AST\n\t\t\t(tpl, coerceSchema) => {\n\t\t\t\tconst ast = this.getCachedAst(tpl);\n\t\t\t\treturn analyzeFromAst(ast, tpl, inputSchema, {\n\t\t\t\t\tidentifierSchemas: options?.identifierSchemas,\n\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t\tcoerceSchema,\n\t\t\t\t});\n\t\t\t},\n\t\t\t// Recursive handler — re-enter analyze() for child elements\n\t\t\t(child, childOptions) => this.analyze(child, inputSchema, childOptions),\n\t\t);\n\t}\n\n\t// ─── Validation ──────────────────────────────────────────────────────────\n\n\t/**\n\t * Validates a template against a schema without returning the output type.\n\t *\n\t * This is an API shortcut for `analyze()` that only returns `valid` and\n\t * `diagnostics`, without `outputSchema`. The full analysis (including type\n\t * inference) is executed internally — this method provides no performance\n\t * gain, only a simplified API.\n\t *\n\t * @param template           - The template to validate\n\t * @param inputSchema        - JSON Schema v7 describing the available variables\n\t * @param identifierSchemas  - (optional) Schemas by identifier\n\t */\n\tvalidate(\n\t\ttemplate: TemplateInput,\n\t\tinputSchema: JSONSchema7 = {},\n\t\toptions?: AnalyzeOptions,\n\t): ValidationResult {\n\t\tconst analysis = this.analyze(template, inputSchema, options);\n\t\treturn {\n\t\t\tvalid: analysis.valid,\n\t\t\tdiagnostics: analysis.diagnostics,\n\t\t};\n\t}\n\n\t// ─── Syntax Validation ───────────────────────────────────────────────────\n\n\t/**\n\t * Checks only that the template syntax is valid (parsing).\n\t * Does not require a schema — useful for quick feedback in an editor.\n\t *\n\t * For objects, recursively checks each property.\n\t *\n\t * @param template - The template to validate\n\t * @returns `true` if the template is syntactically correct\n\t */\n\tisValidSyntax(template: TemplateInput): boolean {\n\t\tif (isArrayInput(template)) {\n\t\t\treturn template.every((v) => this.isValidSyntax(v));\n\t\t}\n\t\tif (isObjectInput(template)) {\n\t\t\treturn Object.values(template).every((v) => this.isValidSyntax(v));\n\t\t}\n\t\tif (isLiteralInput(template)) return true;\n\t\ttry {\n\t\t\tthis.getCachedAst(template);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// ─── Execution ───────────────────────────────────────────────────────────\n\n\t/**\n\t * Executes a template with the provided data.\n\t *\n\t * Accepts a `TemplateInput`: string, number, boolean, null, or object.\n\t * For objects, each property is executed recursively and an object with\n\t * resolved values is returned.\n\t *\n\t * If a `schema` is provided in options, static analysis is performed\n\t * before execution. A `TemplateAnalysisError` is thrown on errors.\n\t *\n\t * @param template - The template to execute\n\t * @param data     - The context data for rendering\n\t * @param options  - Execution options (schema, identifierData, identifierSchemas)\n\t * @returns The execution result\n\t */\n\texecute(\n\t\ttemplate: TemplateInput,\n\t\tdata?: TemplateData,\n\t\toptions?: ExecuteOptions,\n\t): unknown {\n\t\treturn dispatchExecute(\n\t\t\ttemplate,\n\t\t\toptions,\n\t\t\t// String handler — parse, optionally validate, then execute\n\t\t\t(tpl, coerceSchema) => {\n\t\t\t\tconst ast = this.getCachedAst(tpl);\n\n\t\t\t\t// Pre-execution static validation if a schema is provided\n\t\t\t\tif (options?.schema) {\n\t\t\t\t\tconst analysis = analyzeFromAst(ast, tpl, options.schema, {\n\t\t\t\t\t\tidentifierSchemas: options?.identifierSchemas,\n\t\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t\t});\n\t\t\t\t\tif (!analysis.valid) {\n\t\t\t\t\t\tthrow new TemplateAnalysisError(analysis.diagnostics);\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\treturn executeFromAst(ast, tpl, data, {\n\t\t\t\t\tidentifierData: options?.identifierData,\n\t\t\t\t\thbs: this.hbs,\n\t\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t\t\tcoerceSchema,\n\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t});\n\t\t\t},\n\t\t\t// Recursive handler — re-enter execute() for child elements\n\t\t\t(child, childOptions) =>\n\t\t\t\tthis.execute(child, data, { ...options, ...childOptions }),\n\t\t);\n\t}\n\n\t// ─── Combined Shortcuts ──────────────────────────────────────────────────\n\n\t/**\n\t * Analyzes a template and, if valid, executes it with the provided data.\n\t * Returns both the analysis result and the executed value.\n\t *\n\t * For objects, each property is analyzed and executed recursively.\n\t * The entire object is considered invalid if at least one property is.\n\t *\n\t * @param template    - The template\n\t * @param inputSchema - JSON Schema v7 describing the available variables\n\t * @param data        - The context data for rendering\n\t * @param options     - (optional) Options for template identifiers\n\t * @returns An object `{ analysis, value }` where `value` is `undefined`\n\t *          if analysis failed.\n\t */\n\tanalyzeAndExecute(\n\t\ttemplate: TemplateInput,\n\t\tinputSchema: JSONSchema7 = {},\n\t\tdata: TemplateData,\n\t\toptions?: AnalyzeAndExecuteOptions & { coerceSchema?: JSONSchema7 },\n\t): { analysis: AnalysisResult; value: unknown } {\n\t\treturn dispatchAnalyzeAndExecute(\n\t\t\ttemplate,\n\t\t\toptions,\n\t\t\t// String handler — analyze then execute if valid\n\t\t\t(tpl, coerceSchema) => {\n\t\t\t\tconst ast = this.getCachedAst(tpl);\n\t\t\t\tconst analysis = analyzeFromAst(ast, tpl, inputSchema, {\n\t\t\t\t\tidentifierSchemas: options?.identifierSchemas,\n\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t\tcoerceSchema,\n\t\t\t\t});\n\n\t\t\t\tif (!analysis.valid) {\n\t\t\t\t\treturn { analysis, value: undefined };\n\t\t\t\t}\n\n\t\t\t\tconst value = executeFromAst(ast, tpl, data, {\n\t\t\t\t\tidentifierData: options?.identifierData,\n\t\t\t\t\thbs: this.hbs,\n\t\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t\t\tcoerceSchema,\n\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t});\n\t\t\t\treturn { analysis, value };\n\t\t\t},\n\t\t\t// Recursive handler — re-enter analyzeAndExecute() for child elements\n\t\t\t(child, childOptions) =>\n\t\t\t\tthis.analyzeAndExecute(child, inputSchema, data, childOptions),\n\t\t);\n\t}\n\n\t// ─── Custom Helper Management ──────────────────────────────────────────\n\n\t/**\n\t * Registers a custom helper on this engine instance.\n\t *\n\t * The helper is available for both execution (via Handlebars) and\n\t * static analysis (via its declared `returnType`).\n\t *\n\t * @param name       - Helper name (e.g. `\"uppercase\"`)\n\t * @param definition - Helper definition (implementation + return type)\n\t * @returns `this` to allow chaining\n\t */\n\tregisterHelper(name: string, definition: HelperDefinition): this {\n\t\tthis.helpers.set(name, definition);\n\n\t\t// For helpers that return non-primitive values (arrays, objects),\n\t\t// register a Handlebars-friendly wrapper that converts the result\n\t\t// to a string. In single-expression mode the executor bypasses\n\t\t// Handlebars entirely (via tryDirectHelperExecution) and returns\n\t\t// the raw value, so this wrapper only affects mixed/block templates\n\t\t// where Handlebars renders the result into a larger string.\n\t\tif (DIRECT_EXECUTION_HELPER_NAMES.has(name)) {\n\t\t\tthis.hbs.registerHelper(name, (...args: unknown[]) => {\n\t\t\t\t// Handlebars appends an `options` object as the last argument.\n\t\t\t\t// Strip it before calling the real fn.\n\t\t\t\tconst hbsArgs = args.slice(0, -1);\n\t\t\t\tconst raw = definition.fn(...hbsArgs);\n\t\t\t\treturn stringifyForTemplate(raw);\n\t\t\t});\n\t\t} else {\n\t\t\tthis.hbs.registerHelper(name, definition.fn);\n\t\t}\n\n\t\t// Invalidate the compilation cache because helpers have changed\n\t\tthis.compilationCache.clear();\n\n\t\treturn this;\n\t}\n\n\t/**\n\t * Removes a custom helper from this engine instance.\n\t *\n\t * @param name - Name of the helper to remove\n\t * @returns `this` to allow chaining\n\t */\n\tunregisterHelper(name: string): this {\n\t\tthis.helpers.delete(name);\n\t\tthis.hbs.unregisterHelper(name);\n\n\t\t// Invalidate the compilation cache\n\t\tthis.compilationCache.clear();\n\n\t\treturn this;\n\t}\n\n\t/**\n\t * Checks whether a helper is registered on this instance.\n\t *\n\t * @param name - Helper name\n\t * @returns `true` if the helper is registered\n\t */\n\thasHelper(name: string): boolean {\n\t\treturn this.helpers.has(name);\n\t}\n\n\t// ─── Cache Management ──────────────────────────────────────────────────\n\n\t/**\n\t * Clears all internal caches (AST + compilation).\n\t *\n\t * Useful after a configuration change or to free memory.\n\t */\n\tclearCaches(): void {\n\t\tthis.astCache.clear();\n\t\tthis.compilationCache.clear();\n\t}\n\n\t// ─── Internals ─────────────────────────────────────────────────────────\n\n\t/**\n\t * Retrieves the AST of a template from the cache, or parses and caches it.\n\t */\n\tprivate getCachedAst(template: string): hbs.AST.Program {\n\t\tlet ast = this.astCache.get(template);\n\t\tif (!ast) {\n\t\t\tast = parse(template);\n\t\t\tthis.astCache.set(template, ast);\n\t\t}\n\t\treturn ast;\n\t}\n}\n"],"names":["Typebars","DIRECT_EXECUTION_HELPER_NAMES","Set","CollectionHelpers","COLLECT_HELPER_NAME","stringifyForTemplate","value","undefined","Array","isArray","map","item","JSON","stringify","String","join","compile","template","isArrayInput","children","element","push","CompiledTemplate","fromArray","helpers","hbs","compilationCache","isObjectInput","key","Object","entries","fromObject","isLiteralInput","fromLiteral","ast","getCachedAst","options","fromTemplate","analyze","inputSchema","dispatchAnalyze","tpl","coerceSchema","analyzeFromAst","identifierSchemas","child","childOptions","validate","analysis","valid","diagnostics","isValidSyntax","every","v","values","execute","data","dispatchExecute","schema","TemplateAnalysisError","executeFromAst","identifierData","analyzeAndExecute","dispatchAnalyzeAndExecute","registerHelper","name","definition","set","has","args","hbsArgs","slice","raw","fn","clear","unregisterHelper","delete","hasHelper","clearCaches","astCache","get","parse","Map","Handlebars","create","LRUCache","astCacheSize","compilationCacheSize","MathHelpers","register","LogicalHelpers","helper"],"mappings":"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"}
+{"version":3,"sources":["../../src/typebars.ts"],"sourcesContent":["import Handlebars from \"handlebars\";\nimport type { JSONSchema7 } from \"json-schema\";\nimport type { AnalyzeOptions } from \"./analyzer.ts\";\nimport { analyzeFromAst } from \"./analyzer.ts\";\nimport {\n\tCompiledTemplate,\n\ttype CompiledTemplateOptions,\n} from \"./compiled-template.ts\";\nimport {\n\tdispatchAnalyze,\n\tdispatchAnalyzeAndExecute,\n\tdispatchExecute,\n} from \"./dispatch.ts\";\nimport { TemplateAnalysisError } from \"./errors.ts\";\nimport { executeFromAst } from \"./executor.ts\";\nimport { LogicalHelpers, MapHelpers, MathHelpers } from \"./helpers/index.ts\";\nimport { parse } from \"./parser.ts\";\nimport type {\n\tAnalysisResult,\n\tAnalyzeAndExecuteOptions,\n\tExecuteOptions,\n\tHelperDefinition,\n\tTemplateData,\n\tTemplateEngineOptions,\n\tTemplateInput,\n\tValidationResult,\n} from \"./types.ts\";\nimport { isArrayInput, isLiteralInput, isObjectInput } from \"./types.ts\";\nimport { LRUCache } from \"./utils\";\n\n// ─── Typebars ────────────────────────────────────────────────────────────────\n// Public entry point of the template engine. Orchestrates three phases:\n//\n// 1. **Parsing**   — transforms the template string into an AST (via Handlebars)\n// 2. **Analysis**  — static validation + return type inference\n// 3. **Execution** — renders the template with real data\n//\n// ─── Architecture v2 ─────────────────────────────────────────────────────────\n// - **LRU cache** for parsed ASTs and compiled Handlebars templates\n// - **Isolated Handlebars environment** per instance (custom helpers)\n// - **`compile()` pattern**: parse-once / execute-many\n// - **`validate()` method**: API shortcut without `outputSchema`\n// - **`registerHelper()`**: custom helpers with static typing\n// - **`ExecuteOptions`**: options object for `execute()`\n//\n// ─── Template Identifiers ────────────────────────────────────────────────────\n// The `{{key:N}}` syntax allows referencing variables from specific data\n// sources, identified by an integer N.\n//\n// - `identifierSchemas`: mapping `{ [id]: JSONSchema7 }` for static analysis\n// - `identifierData`:    mapping `{ [id]: Record<string, unknown> }` for execution\n//\n// Usage:\n//   engine.execute(\"{{meetingId:1}}\", data, { identifierData: { 1: node1Data } });\n//   engine.analyze(\"{{meetingId:1}}\", schema, { identifierSchemas: { 1: node1Schema } });\n\n// ─── Direct Execution Helper Names ───────────────────────────────────────────\n// Helpers whose return values are non-primitive (arrays, objects) and must be\n// wrapped when registered with Handlebars so that mixed/block templates get a\n// human-readable string (e.g. `\", \"` joined) instead of JS default toString().\n// In single-expression mode the executor bypasses Handlebars entirely, so the\n// raw value is preserved.\nconst DIRECT_EXECUTION_HELPER_NAMES = new Set<string>([\n\tMapHelpers.MAP_HELPER_NAME,\n]);\n\n/**\n * Converts a value to a string suitable for embedding in a Handlebars template.\n *\n * - Arrays of primitives are joined with `\", \"`\n * - Arrays of objects are JSON-stringified per element, then joined\n * - Primitives use `String(value)`\n * - null/undefined become `\"\"`\n */\nfunction stringifyForTemplate(value: unknown): string {\n\tif (value === null || value === undefined) return \"\";\n\tif (Array.isArray(value)) {\n\t\treturn value\n\t\t\t.map((item) => {\n\t\t\t\tif (item === null || item === undefined) return \"\";\n\t\t\t\tif (typeof item === \"object\") return JSON.stringify(item);\n\t\t\t\treturn String(item);\n\t\t\t})\n\t\t\t.join(\", \");\n\t}\n\treturn String(value);\n}\n\n// ─── Main Class ──────────────────────────────────────────────────────────────\n\nexport class Typebars {\n\t/** Isolated Handlebars environment — each engine has its own helpers */\n\tprivate readonly hbs: typeof Handlebars;\n\n\t/** LRU cache of parsed ASTs (avoids re-parsing) */\n\tprivate readonly astCache: LRUCache<string, hbs.AST.Program>;\n\n\t/** LRU cache of compiled Handlebars templates (avoids recompilation) */\n\tprivate readonly compilationCache: LRUCache<\n\t\tstring,\n\t\tHandlebarsTemplateDelegate\n\t>;\n\n\t/** Custom helpers registered on this instance */\n\tprivate readonly helpers = new Map<string, HelperDefinition>();\n\n\tconstructor(options: TemplateEngineOptions = {}) {\n\t\tthis.hbs = Handlebars.create();\n\t\tthis.astCache = new LRUCache(options.astCacheSize ?? 256);\n\t\tthis.compilationCache = new LRUCache(options.compilationCacheSize ?? 256);\n\n\t\t// ── Built-in helpers ─────────────────────────────────────────────\n\t\tnew MathHelpers().register(this);\n\t\tnew LogicalHelpers().register(this);\n\t\tnew MapHelpers().register(this);\n\n\t\t// ── Custom helpers via options ───────────────────────────────────\n\t\tif (options.helpers) {\n\t\t\tfor (const helper of options.helpers) {\n\t\t\t\tconst { name, ...definition } = helper;\n\t\t\t\tthis.registerHelper(name, definition);\n\t\t\t}\n\t\t}\n\t}\n\n\t// ─── Compilation ───────────────────────────────────────────────────────\n\n\t/**\n\t * Compiles a template and returns a `CompiledTemplate` ready to be\n\t * executed or analyzed without re-parsing.\n\t *\n\t * Accepts a `TemplateInput`: string, number, boolean, null, or object.\n\t * For objects, each property is compiled recursively.\n\t *\n\t * @param template - The template to compile\n\t * @returns A reusable `CompiledTemplate`\n\t */\n\tcompile(template: TemplateInput): CompiledTemplate {\n\t\tif (isArrayInput(template)) {\n\t\t\tconst children: CompiledTemplate[] = [];\n\t\t\tfor (const element of template) {\n\t\t\t\tchildren.push(this.compile(element));\n\t\t\t}\n\t\t\treturn CompiledTemplate.fromArray(children, {\n\t\t\t\thelpers: this.helpers,\n\t\t\t\thbs: this.hbs,\n\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t});\n\t\t}\n\t\tif (isObjectInput(template)) {\n\t\t\tconst children: Record<string, CompiledTemplate> = {};\n\t\t\tfor (const [key, value] of Object.entries(template)) {\n\t\t\t\tchildren[key] = this.compile(value);\n\t\t\t}\n\t\t\treturn CompiledTemplate.fromObject(children, {\n\t\t\t\thelpers: this.helpers,\n\t\t\t\thbs: this.hbs,\n\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t});\n\t\t}\n\t\tif (isLiteralInput(template)) {\n\t\t\treturn CompiledTemplate.fromLiteral(template, {\n\t\t\t\thelpers: this.helpers,\n\t\t\t\thbs: this.hbs,\n\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t});\n\t\t}\n\t\tconst ast = this.getCachedAst(template);\n\t\tconst options: CompiledTemplateOptions = {\n\t\t\thelpers: this.helpers,\n\t\t\thbs: this.hbs,\n\t\t\tcompilationCache: this.compilationCache,\n\t\t};\n\t\treturn CompiledTemplate.fromTemplate(ast, template, options);\n\t}\n\n\t// ─── Static Analysis ─────────────────────────────────────────────────────\n\n\t/**\n\t * Statically analyzes a template against a JSON Schema v7 describing\n\t * the available context.\n\t *\n\t * Accepts a `TemplateInput`: string, number, boolean, null, or object.\n\t * For objects, each property is analyzed recursively and the\n\t * `outputSchema` reflects the object structure with resolved types.\n\t *\n\t * @param template    - The template to analyze\n\t * @param inputSchema - JSON Schema v7 describing the available variables\n\t * @param options     - (optional) Analysis options (identifierSchemas, coerceSchema)\n\t */\n\tanalyze(\n\t\ttemplate: TemplateInput,\n\t\tinputSchema: JSONSchema7 = {},\n\t\toptions?: AnalyzeOptions,\n\t): AnalysisResult {\n\t\treturn dispatchAnalyze(\n\t\t\ttemplate,\n\t\t\toptions,\n\t\t\t// String handler — parse with cache and analyze the AST\n\t\t\t(tpl, coerceSchema) => {\n\t\t\t\tconst ast = this.getCachedAst(tpl);\n\t\t\t\treturn analyzeFromAst(ast, tpl, inputSchema, {\n\t\t\t\t\tidentifierSchemas: options?.identifierSchemas,\n\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t\tcoerceSchema,\n\t\t\t\t});\n\t\t\t},\n\t\t\t// Recursive handler — re-enter analyze() for child elements\n\t\t\t(child, childOptions) => this.analyze(child, inputSchema, childOptions),\n\t\t);\n\t}\n\n\t// ─── Validation ──────────────────────────────────────────────────────────\n\n\t/**\n\t * Validates a template against a schema without returning the output type.\n\t *\n\t * This is an API shortcut for `analyze()` that only returns `valid` and\n\t * `diagnostics`, without `outputSchema`. The full analysis (including type\n\t * inference) is executed internally — this method provides no performance\n\t * gain, only a simplified API.\n\t *\n\t * @param template           - The template to validate\n\t * @param inputSchema        - JSON Schema v7 describing the available variables\n\t * @param identifierSchemas  - (optional) Schemas by identifier\n\t */\n\tvalidate(\n\t\ttemplate: TemplateInput,\n\t\tinputSchema: JSONSchema7 = {},\n\t\toptions?: AnalyzeOptions,\n\t): ValidationResult {\n\t\tconst analysis = this.analyze(template, inputSchema, options);\n\t\treturn {\n\t\t\tvalid: analysis.valid,\n\t\t\tdiagnostics: analysis.diagnostics,\n\t\t};\n\t}\n\n\t// ─── Syntax Validation ───────────────────────────────────────────────────\n\n\t/**\n\t * Checks only that the template syntax is valid (parsing).\n\t * Does not require a schema — useful for quick feedback in an editor.\n\t *\n\t * For objects, recursively checks each property.\n\t *\n\t * @param template - The template to validate\n\t * @returns `true` if the template is syntactically correct\n\t */\n\tisValidSyntax(template: TemplateInput): boolean {\n\t\tif (isArrayInput(template)) {\n\t\t\treturn template.every((v) => this.isValidSyntax(v));\n\t\t}\n\t\tif (isObjectInput(template)) {\n\t\t\treturn Object.values(template).every((v) => this.isValidSyntax(v));\n\t\t}\n\t\tif (isLiteralInput(template)) return true;\n\t\ttry {\n\t\t\tthis.getCachedAst(template);\n\t\t\treturn true;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t// ─── Execution ───────────────────────────────────────────────────────────\n\n\t/**\n\t * Executes a template with the provided data.\n\t *\n\t * Accepts a `TemplateInput`: string, number, boolean, null, or object.\n\t * For objects, each property is executed recursively and an object with\n\t * resolved values is returned.\n\t *\n\t * If a `schema` is provided in options, static analysis is performed\n\t * before execution. A `TemplateAnalysisError` is thrown on errors.\n\t *\n\t * @param template - The template to execute\n\t * @param data     - The context data for rendering\n\t * @param options  - Execution options (schema, identifierData, identifierSchemas)\n\t * @returns The execution result\n\t */\n\texecute(\n\t\ttemplate: TemplateInput,\n\t\tdata?: TemplateData,\n\t\toptions?: ExecuteOptions,\n\t): unknown {\n\t\treturn dispatchExecute(\n\t\t\ttemplate,\n\t\t\toptions,\n\t\t\t// String handler — parse, optionally validate, then execute\n\t\t\t(tpl, coerceSchema) => {\n\t\t\t\tconst ast = this.getCachedAst(tpl);\n\n\t\t\t\t// Pre-execution static validation if a schema is provided\n\t\t\t\tif (options?.schema) {\n\t\t\t\t\tconst analysis = analyzeFromAst(ast, tpl, options.schema, {\n\t\t\t\t\t\tidentifierSchemas: options?.identifierSchemas,\n\t\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t\t});\n\t\t\t\t\tif (!analysis.valid) {\n\t\t\t\t\t\tthrow new TemplateAnalysisError(analysis.diagnostics);\n\t\t\t\t\t}\n\t\t\t\t}\n\n\t\t\t\treturn executeFromAst(ast, tpl, data, {\n\t\t\t\t\tidentifierData: options?.identifierData,\n\t\t\t\t\thbs: this.hbs,\n\t\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t\t\tcoerceSchema,\n\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t});\n\t\t\t},\n\t\t\t// Recursive handler — re-enter execute() for child elements\n\t\t\t(child, childOptions) =>\n\t\t\t\tthis.execute(child, data, { ...options, ...childOptions }),\n\t\t);\n\t}\n\n\t// ─── Combined Shortcuts ──────────────────────────────────────────────────\n\n\t/**\n\t * Analyzes a template and, if valid, executes it with the provided data.\n\t * Returns both the analysis result and the executed value.\n\t *\n\t * For objects, each property is analyzed and executed recursively.\n\t * The entire object is considered invalid if at least one property is.\n\t *\n\t * @param template    - The template\n\t * @param inputSchema - JSON Schema v7 describing the available variables\n\t * @param data        - The context data for rendering\n\t * @param options     - (optional) Options for template identifiers\n\t * @returns An object `{ analysis, value }` where `value` is `undefined`\n\t *          if analysis failed.\n\t */\n\tanalyzeAndExecute(\n\t\ttemplate: TemplateInput,\n\t\tinputSchema: JSONSchema7 = {},\n\t\tdata: TemplateData,\n\t\toptions?: AnalyzeAndExecuteOptions,\n\t): { analysis: AnalysisResult; value: unknown } {\n\t\treturn dispatchAnalyzeAndExecute(\n\t\t\ttemplate,\n\t\t\toptions,\n\t\t\t// String handler — analyze then execute if valid\n\t\t\t(tpl, coerceSchema) => {\n\t\t\t\tconst ast = this.getCachedAst(tpl);\n\t\t\t\tconst analysis = analyzeFromAst(ast, tpl, inputSchema, {\n\t\t\t\t\tidentifierSchemas: options?.identifierSchemas,\n\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t\tcoerceSchema,\n\t\t\t\t});\n\n\t\t\t\tif (!analysis.valid) {\n\t\t\t\t\treturn { analysis, value: undefined };\n\t\t\t\t}\n\n\t\t\t\tconst value = executeFromAst(ast, tpl, data, {\n\t\t\t\t\tidentifierData: options?.identifierData,\n\t\t\t\t\thbs: this.hbs,\n\t\t\t\t\tcompilationCache: this.compilationCache,\n\t\t\t\t\tcoerceSchema,\n\t\t\t\t\thelpers: this.helpers,\n\t\t\t\t});\n\t\t\t\treturn { analysis, value };\n\t\t\t},\n\t\t\t// Recursive handler — re-enter analyzeAndExecute() for child elements\n\t\t\t(child, childOptions) =>\n\t\t\t\tthis.analyzeAndExecute(child, inputSchema, data, childOptions),\n\t\t);\n\t}\n\n\t// ─── Custom Helper Management ──────────────────────────────────────────\n\n\t/**\n\t * Registers a custom helper on this engine instance.\n\t *\n\t * The helper is available for both execution (via Handlebars) and\n\t * static analysis (via its declared `returnType`).\n\t *\n\t * @param name       - Helper name (e.g. `\"uppercase\"`)\n\t * @param definition - Helper definition (implementation + return type)\n\t * @returns `this` to allow chaining\n\t */\n\tregisterHelper(name: string, definition: HelperDefinition): this {\n\t\tthis.helpers.set(name, definition);\n\n\t\t// For helpers that return non-primitive values (arrays, objects),\n\t\t// register a Handlebars-friendly wrapper that converts the result\n\t\t// to a string. In single-expression mode the executor bypasses\n\t\t// Handlebars entirely (via tryDirectHelperExecution) and returns\n\t\t// the raw value, so this wrapper only affects mixed/block templates\n\t\t// where Handlebars renders the result into a larger string.\n\t\tif (DIRECT_EXECUTION_HELPER_NAMES.has(name)) {\n\t\t\tthis.hbs.registerHelper(name, (...args: unknown[]) => {\n\t\t\t\t// Handlebars appends an `options` object as the last argument.\n\t\t\t\t// Strip it before calling the real fn.\n\t\t\t\tconst hbsArgs = args.slice(0, -1);\n\t\t\t\tconst raw = definition.fn(...hbsArgs);\n\t\t\t\treturn stringifyForTemplate(raw);\n\t\t\t});\n\t\t} else {\n\t\t\tthis.hbs.registerHelper(name, definition.fn);\n\t\t}\n\n\t\t// Invalidate the compilation cache because helpers have changed\n\t\tthis.compilationCache.clear();\n\n\t\treturn this;\n\t}\n\n\t/**\n\t * Removes a custom helper from this engine instance.\n\t *\n\t * @param name - Name of the helper to remove\n\t * @returns `this` to allow chaining\n\t */\n\tunregisterHelper(name: string): this {\n\t\tthis.helpers.delete(name);\n\t\tthis.hbs.unregisterHelper(name);\n\n\t\t// Invalidate the compilation cache\n\t\tthis.compilationCache.clear();\n\n\t\treturn this;\n\t}\n\n\t/**\n\t * Checks whether a helper is registered on this instance.\n\t *\n\t * @param name - Helper name\n\t * @returns `true` if the helper is registered\n\t */\n\thasHelper(name: string): boolean {\n\t\treturn this.helpers.has(name);\n\t}\n\n\t// ─── Cache Management ──────────────────────────────────────────────────\n\n\t/**\n\t * Clears all internal caches (AST + compilation).\n\t *\n\t * Useful after a configuration change or to free memory.\n\t */\n\tclearCaches(): void {\n\t\tthis.astCache.clear();\n\t\tthis.compilationCache.clear();\n\t}\n\n\t// ─── Internals ─────────────────────────────────────────────────────────\n\n\t/**\n\t * Retrieves the AST of a template from the cache, or parses and caches it.\n\t */\n\tprivate getCachedAst(template: string): hbs.AST.Program {\n\t\tlet ast = this.astCache.get(template);\n\t\tif (!ast) {\n\t\t\tast = parse(template);\n\t\t\tthis.astCache.set(template, ast);\n\t\t}\n\t\treturn ast;\n\t}\n}\n"],"names":["Typebars","DIRECT_EXECUTION_HELPER_NAMES","Set","MapHelpers","MAP_HELPER_NAME","stringifyForTemplate","value","undefined","Array","isArray","map","item","JSON","stringify","String","join","compile","template","isArrayInput","children","element","push","CompiledTemplate","fromArray","helpers","hbs","compilationCache","isObjectInput","key","Object","entries","fromObject","isLiteralInput","fromLiteral","ast","getCachedAst","options","fromTemplate","analyze","inputSchema","dispatchAnalyze","tpl","coerceSchema","analyzeFromAst","identifierSchemas","child","childOptions","validate","analysis","valid","diagnostics","isValidSyntax","every","v","values","execute","data","dispatchExecute","schema","TemplateAnalysisError","executeFromAst","identifierData","analyzeAndExecute","dispatchAnalyzeAndExecute","registerHelper","name","definition","set","has","args","hbsArgs","slice","raw","fn","clear","unregisterHelper","delete","hasHelper","clearCaches","astCache","get","parse","Map","Handlebars","create","LRUCache","astCacheSize","compilationCacheSize","MathHelpers","register","LogicalHelpers","helper"],"mappings":"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"}

package/dist/cjs/types.d.ts

@@ -194,13 +194,7 @@ export interface TemplateEngineOptions {
      */
     helpers?: HelperConfig[];
 }
-export interface ExecuteOptions {
-    /** JSON Schema for pre-execution static validation */
-    schema?: JSONSchema7;
-    /** Data by identifier `{ [id]: { key: value } }` */
-    identifierData?: Record<number, Record<string, unknown>>;
-    /** Schemas by identifier (for static validation with identifiers) */
-    identifierSchemas?: Record<number, JSONSchema7>;
+export interface CommonTypebarsOptions {
     /**
      * Explicit coercion schema for the output value.
      * When provided with a primitive type, the execution result will be
@@ -226,17 +220,19 @@ export interface ExecuteOptions {
      */
     excludeTemplateExpression?: boolean;
 }
-export interface AnalyzeAndExecuteOptions {
+export interface ExecuteOptions extends CommonTypebarsOptions {
+    /** JSON Schema for pre-execution static validation */
+    schema?: JSONSchema7;
+    /** Data by identifier `{ [id]: { key: value } }` */
+    identifierData?: Record<number, Record<string, unknown>>;
+    /** Schemas by identifier (for static validation with identifiers) */
+    identifierSchemas?: Record<number, JSONSchema7>;
+}
+export interface AnalyzeAndExecuteOptions extends CommonTypebarsOptions {
     /** Schemas by identifier `{ [id]: JSONSchema7 }` for static analysis */
     identifierSchemas?: Record<number, JSONSchema7>;
     /** Data by identifier `{ [id]: { key: value } }` for execution */
     identifierData?: Record<number, Record<string, unknown>>;
-    /**
-     * Explicit coercion schema for the output value.
-     * When provided with a primitive type, the execution result will be
-     * coerced to match the declared type instead of using auto-detection.
-     */
-    coerceSchema?: JSONSchema7;
 }
 /** Describes a parameter expected by a helper */
 export interface HelperParam {

package/dist/cjs/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types.ts"],"sourcesContent":["import type { JSONSchema7 } from \"json-schema\";\nimport type { FromSchema, JSONSchema } from \"json-schema-to-ts\";\n\n// ─── Template Input ──────────────────────────────────────────────────────────\n// The engine accepts primitive values in addition to template strings.\n// When a non-string value is passed, it is treated as a literal passthrough:\n// analysis returns the inferred type, and execution returns the value as-is.\n\n/**\n * Object where each property is a `TemplateInput` (recursive).\n *\n * Allows passing an entire structure as a template:\n * ```\n * engine.analyze({\n *   userName: \"{{name}}\",\n *   userAge: \"{{age}}\",\n *   nested: { x: \"{{foo}}\" },\n * }, inputSchema);\n * ```\n */\nexport interface TemplateInputObject {\n\t[key: string]: TemplateInput;\n}\n\n/**\n * Array where each element is a `TemplateInput` (recursive).\n *\n * Allows passing an array as a template:\n * ```\n * engine.analyze([\"{{name}}\", \"{{age}}\"], inputSchema);\n * engine.execute([\"{{name}}\", 42], data);\n * ```\n */\nexport type TemplateInputArray = TemplateInput[];\n\n/**\n * Input type accepted by the template engine.\n *\n * - `string`              → standard Handlebars template (parsed and executed)\n * - `number`              → numeric literal (passthrough)\n * - `boolean`             → boolean literal (passthrough)\n * - `null`                → null literal (passthrough)\n * - `TemplateInputArray`  → array where each element is a `TemplateInput`\n * - `TemplateInputObject` → object where each property is a `TemplateInput`\n */\nexport type TemplateInput =\n\t| string\n\t| number\n\t| boolean\n\t| null\n\t| TemplateInputArray\n\t| TemplateInputObject;\n\n// ─── Template Data ───────────────────────────────────────────────────────────\n// The data parameter accepted by `execute()` and `analyzeAndExecute()`.\n// In most cases this is a `Record<string, unknown>` (object context), but\n// primitives are also allowed — for example when using `{{$root}}` to\n// reference the entire data value directly.\n\n/**\n * Data type accepted by the template engine's execution methods.\n *\n * - `Record<string, unknown>` → standard object context (most common)\n * - `string`                  → primitive value (e.g. for `{{$root}}`)\n * - `number`                  → primitive value\n * - `boolean`                 → primitive value\n * - `null`                    → null value\n * - `unknown[]`               → array value\n */\nexport type TemplateData =\n\t| Record<string, unknown>\n\t| string\n\t| number\n\t| boolean\n\t| null\n\t| unknown[];\n\n/**\n * Checks whether a value is a non-string primitive literal (number, boolean, null).\n * These values are treated as passthrough by the engine.\n *\n * Note: objects (`TemplateInputObject`) and arrays (`TemplateInputArray`) are NOT literals.\n */\nexport function isLiteralInput(\n\tinput: TemplateInput,\n): input is number | boolean | null {\n\treturn (\n\t\tinput === null || (typeof input !== \"string\" && typeof input !== \"object\")\n\t);\n}\n\n/**\n * Checks whether a value is a template array (`TemplateInputArray`).\n * Template arrays are processed recursively by the engine:\n * each element is analyzed/executed individually and the result is an array.\n */\nexport function isArrayInput(\n\tinput: TemplateInput,\n): input is TemplateInputArray {\n\treturn Array.isArray(input);\n}\n\n/**\n * Checks whether a value is a template object (`TemplateInputObject`).\n * Template objects are processed recursively by the engine:\n * each property is analyzed/executed individually.\n *\n * Note: arrays are excluded — use `isArrayInput()` first.\n */\nexport function isObjectInput(\n\tinput: TemplateInput,\n): input is TemplateInputObject {\n\treturn input !== null && typeof input === \"object\" && !Array.isArray(input);\n}\n\n/**\n * Infers the JSON Schema of a non-string primitive value.\n *\n * @param value - The primitive value (number, boolean, null)\n * @returns The corresponding JSON Schema\n *\n * @example\n * ```\n * inferPrimitiveSchema(42)    // → { type: \"number\" }\n * inferPrimitiveSchema(true)  // → { type: \"boolean\" }\n * inferPrimitiveSchema(null)  // → { type: \"null\" }\n * ```\n */\nexport function inferPrimitiveSchema(\n\tvalue: number | boolean | null,\n): JSONSchema7 {\n\tif (value === null) return { type: \"null\" };\n\tif (typeof value === \"boolean\") return { type: \"boolean\" };\n\tif (typeof value === \"number\") {\n\t\treturn Number.isInteger(value) ? { type: \"integer\" } : { type: \"number\" };\n\t}\n\t// Exhaustiveness check — all branches are covered above.\n\t// If the type of `value` changes, TypeScript will raise an error here.\n\tvalue satisfies never;\n\treturn { type: \"null\" };\n}\n\n// ─── Diagnostic Codes ────────────────────────────────────────────────────────\n// Machine-readable codes for each error/warning type, enabling the frontend\n// to react programmatically without parsing the human-readable message.\n\nexport type DiagnosticCode =\n\t/** The referenced property does not exist in the context schema */\n\t| \"UNKNOWN_PROPERTY\"\n\t/** Type mismatch (e.g. #each on a non-array) */\n\t| \"TYPE_MISMATCH\"\n\t/** A block helper is used without a required argument */\n\t| \"MISSING_ARGUMENT\"\n\t/** Unknown block helper (neither built-in nor registered) */\n\t| \"UNKNOWN_HELPER\"\n\t/** The expression cannot be statically analyzed */\n\t| \"UNANALYZABLE\"\n\t/** The {{key:N}} syntax is used but no identifierSchemas were provided */\n\t| \"MISSING_IDENTIFIER_SCHEMAS\"\n\t/** The identifier N does not exist in the provided identifierSchemas */\n\t| \"UNKNOWN_IDENTIFIER\"\n\t/** The property does not exist in the identifier's schema */\n\t| \"IDENTIFIER_PROPERTY_NOT_FOUND\"\n\t/** Syntax error in the template */\n\t| \"PARSE_ERROR\"\n\t/** The $root token is used with path traversal (e.g. $root.name) */\n\t| \"ROOT_PATH_TRAVERSAL\";\n\n// ─── Diagnostic Details ──────────────────────────────────────────────────────\n// Supplementary information to understand the exact cause of the error.\n// Designed to be easily JSON-serializable and consumable by a frontend.\n\nexport interface DiagnosticDetails {\n\t/** Path of the expression that caused the error (e.g. `\"user.name.foo\"`) */\n\tpath?: string;\n\t/** Name of the helper involved (for helper-related errors) */\n\thelperName?: string;\n\t/** What was expected (e.g. `\"array\"`, `\"property to exist\"`) */\n\texpected?: string;\n\t/** What was found (e.g. `\"string\"`, `\"undefined\"`) */\n\tactual?: string;\n\t/** Available properties in the current schema (for suggestions) */\n\tavailableProperties?: string[];\n\t/** Template identifier number (for `{{key:N}}` errors) */\n\tidentifier?: number;\n}\n\n// ─── Static Analysis Result ──────────────────────────────────────────────────\n\n/** Diagnostic produced by the static analyzer */\nexport interface TemplateDiagnostic {\n\t/** \"error\" blocks execution, \"warning\" is informational */\n\tseverity: \"error\" | \"warning\";\n\n\t/** Machine-readable code identifying the error type */\n\tcode: DiagnosticCode;\n\n\t/** Human-readable message describing the problem */\n\tmessage: string;\n\n\t/** Position in the template source (if available from the AST) */\n\tloc?: {\n\t\tstart: { line: number; column: number };\n\t\tend: { line: number; column: number };\n\t};\n\n\t/** Fragment of the template source around the error */\n\tsource?: string;\n\n\t/** Structured information for debugging and frontend display */\n\tdetails?: DiagnosticDetails;\n}\n\n/** Complete result of the static analysis */\nexport interface AnalysisResult {\n\t/** true if no errors (warnings are tolerated) */\n\tvalid: boolean;\n\t/** List of diagnostics (errors + warnings) */\n\tdiagnostics: TemplateDiagnostic[];\n\t/** JSON Schema describing the template's return type */\n\toutputSchema: JSONSchema7;\n}\n\n/** Lightweight validation result (without output type inference) */\nexport interface ValidationResult {\n\t/** true if no errors (warnings are tolerated) */\n\tvalid: boolean;\n\t/** List of diagnostics (errors + warnings) */\n\tdiagnostics: TemplateDiagnostic[];\n}\n\n// ─── Public Engine Options ───────────────────────────────────────────────────\n\nexport interface TemplateEngineOptions {\n\t/**\n\t * Capacity of the parsed AST cache. Each parsed template is cached\n\t * to avoid costly re-parsing on repeated calls.\n\t * @default 256\n\t */\n\tastCacheSize?: number;\n\n\t/**\n\t * Capacity of the compiled Handlebars template cache.\n\t * @default 256\n\t */\n\tcompilationCacheSize?: number;\n\n\t/**\n\t * Custom helpers to register during engine construction.\n\t *\n\t * Each entry describes a helper with its name, implementation,\n\t * expected parameters, and return type.\n\t *\n\t * @example\n\t * ```\n\t * const engine = new Typebars({\n\t *   helpers: [\n\t *     {\n\t *       name: \"uppercase\",\n\t *       description: \"Converts a string to uppercase\",\n\t *       fn: (value: string) => String(value).toUpperCase(),\n\t *       params: [\n\t *         { name: \"value\", type: { type: \"string\" }, description: \"The string to convert\" },\n\t *       ],\n\t *       returnType: { type: \"string\" },\n\t *     },\n\t *   ],\n\t * });\n\t * ```\n\t */\n\thelpers?: HelperConfig[];\n}\n\n// ─── Execution Options ───────────────────────────────────────────────────────\n// Optional options object for `execute()`, replacing multiple positional\n// parameters for better ergonomics.\n\nexport interface ExecuteOptions {\n\t/** JSON Schema for pre-execution static validation */\n\tschema?: JSONSchema7;\n\t/** Data by identifier `{ [id]: { key: value } }` */\n\tidentifierData?: Record<number, Record<string, unknown>>;\n\t/** Schemas by identifier (for static validation with identifiers) */\n\tidentifierSchemas?: Record<number, JSONSchema7>;\n\t/**\n\t * Explicit coercion schema for the output value.\n\t * When provided with a primitive type, the execution result will be\n\t * coerced to match the declared type instead of using auto-detection.\n\t */\n\tcoerceSchema?: JSONSchema7;\n\t/**\n\t * When `true`, properties whose values contain Handlebars expressions\n\t * (i.e. any `{{…}}` syntax) are excluded from the execution result.\n\t *\n\t * - **Object**: properties with template expressions are omitted from\n\t *   the resulting object.\n\t * - **Array**: elements with template expressions are omitted from\n\t *   the resulting array.\n\t * - **Root string** with expressions: returns `null` (there is no\n\t *   parent to exclude from).\n\t * - **Literals** (number, boolean, null): unaffected.\n\t *\n\t * This mirrors the analysis-side `excludeTemplateExpression` option\n\t * but applied at runtime.\n\t *\n\t * @default false\n\t */\n\texcludeTemplateExpression?: boolean;\n}\n\n// ─── Combined Analyze-and-Execute Options ────────────────────────────────────\n// Optional options object for `analyzeAndExecute()`, grouping parameters\n// related to template identifiers.\n\nexport interface AnalyzeAndExecuteOptions {\n\t/** Schemas by identifier `{ [id]: JSONSchema7 }` for static analysis */\n\tidentifierSchemas?: Record<number, JSONSchema7>;\n\t/** Data by identifier `{ [id]: { key: value } }` for execution */\n\tidentifierData?: Record<number, Record<string, unknown>>;\n\t/**\n\t * Explicit coercion schema for the output value.\n\t * When provided with a primitive type, the execution result will be\n\t * coerced to match the declared type instead of using auto-detection.\n\t */\n\tcoerceSchema?: JSONSchema7;\n}\n\n// ─── Custom Helpers ──────────────────────────────────────────────────────────\n// Allows registering custom helpers with their type signature for static\n// analysis support.\n\n/** Describes a parameter expected by a helper */\nexport interface HelperParam {\n\t/** Parameter name (for documentation / introspection) */\n\tname: string;\n\n\t/**\n\t * JSON Schema describing the expected type for this parameter.\n\t * Used for documentation and static validation.\n\t */\n\ttype?: JSONSchema7;\n\n\t/** Human-readable description of the parameter */\n\tdescription?: string;\n\n\t/**\n\t * Whether the parameter is optional.\n\t * @default false\n\t */\n\toptional?: boolean;\n}\n\n/**\n * Definition of a helper registerable via `registerHelper()`.\n *\n * Contains the runtime implementation and typing metadata\n * for static analysis.\n */\nexport interface HelperDefinition {\n\t/**\n\t * Runtime implementation of the helper — will be registered with Handlebars.\n\t *\n\t * For an inline helper `{{uppercase name}}`:\n\t *   `(value: string) => string`\n\t *\n\t * For a block helper `{{#repeat count}}...{{/repeat}}`:\n\t *   `function(this: any, count: number, options: Handlebars.HelperOptions) { ... }`\n\t */\n\t// biome-ignore lint/suspicious/noExplicitAny: Handlebars helper signatures are inherently dynamic\n\tfn: (...args: any[]) => unknown;\n\n\t/**\n\t * Parameters expected by the helper (for documentation and analysis).\n\t *\n\t * @example\n\t * ```\n\t * params: [\n\t *   { name: \"value\", type: { type: \"number\" }, description: \"The value to round\" },\n\t *   { name: \"precision\", type: { type: \"number\" }, description: \"Decimal places\", optional: true },\n\t * ]\n\t * ```\n\t */\n\tparams?: HelperParam[];\n\n\t/**\n\t * JSON Schema describing the helper's return type for static analysis.\n\t * @default { type: \"string\" }\n\t */\n\treturnType?: JSONSchema7;\n\n\t/** Human-readable description of the helper */\n\tdescription?: string;\n}\n\n/**\n * Full helper configuration for registration via the `Typebars({ helpers: [...] })`\n * constructor options.\n *\n * Extends `HelperDefinition` with a required `name`.\n *\n * @example\n * ```\n * const config: HelperConfig = {\n *   name: \"round\",\n *   description: \"Rounds a number to a given precision\",\n *   fn: (value: number, precision?: number) => { ... },\n *   params: [\n *     { name: \"value\", type: { type: \"number\" } },\n *     { name: \"precision\", type: { type: \"number\" }, optional: true },\n *   ],\n *   returnType: { type: \"number\" },\n * };\n * ```\n */\nexport interface HelperConfig extends HelperDefinition {\n\t/** Name of the helper as used in templates (e.g. `\"uppercase\"`) */\n\tname: string;\n}\n\n// ─── Automatic Type Inference via json-schema-to-ts ──────────────────────────\n// Allows `defineHelper()` to infer TypeScript types for `fn` arguments\n// from the JSON Schemas declared in `params`.\n\n/**\n * Param definition used for type inference.\n * Accepts `JSONSchema` from `json-schema-to-ts` to allow `FromSchema`\n * to resolve literal types.\n */\ntype TypedHelperParam = {\n\treadonly name: string;\n\treadonly type?: JSONSchema;\n\treadonly description?: string;\n\treadonly optional?: boolean;\n};\n\n/**\n * Infers the TypeScript type of a single parameter from its JSON Schema.\n * - If `optional: true`, the resolved type is unioned with `undefined`.\n * - If `type` is not provided, the type is `unknown`.\n */\ntype InferParamType<P> = P extends {\n\treadonly type: infer S extends JSONSchema;\n\treadonly optional: true;\n}\n\t? FromSchema<S> | undefined\n\t: P extends { readonly type: infer S extends JSONSchema }\n\t\t? FromSchema<S>\n\t\t: unknown;\n\n/**\n * Maps a tuple of `TypedHelperParam` to a tuple of inferred TypeScript types,\n * usable as the `fn` signature.\n *\n * @example\n * ```\n * type Args = InferArgs<readonly [\n *   { name: \"a\"; type: { type: \"string\" } },\n *   { name: \"b\"; type: { type: \"number\" }; optional: true },\n * ]>;\n * // => [string, number | undefined]\n * ```\n */\ntype InferArgs<P extends readonly TypedHelperParam[]> = {\n\t[K in keyof P]: InferParamType<P[K]>;\n};\n\n/**\n * Helper configuration with generic parameter inference.\n * Used exclusively by `defineHelper()`.\n */\ninterface TypedHelperConfig<P extends readonly TypedHelperParam[]> {\n\tname: string;\n\tdescription?: string;\n\tparams: P;\n\tfn: (...args: InferArgs<P>) => unknown;\n\treturnType?: JSONSchema;\n}\n\n/**\n * Creates a `HelperConfig` with automatic type inference for `fn` arguments\n * based on the JSON Schemas declared in `params`.\n *\n * The generic parameter `const P` preserves schema literal types\n * (equivalent of `as const`), enabling `FromSchema` to resolve the\n * corresponding TypeScript types.\n *\n * @example\n * ```\n * const helper = defineHelper({\n *   name: \"concat\",\n *   description: \"Concatenates two strings\",\n *   params: [\n *     { name: \"a\", type: { type: \"string\" }, description: \"First string\" },\n *     { name: \"b\", type: { type: \"string\" }, description: \"Second string\" },\n *     { name: \"sep\", type: { type: \"string\" }, description: \"Separator\", optional: true },\n *   ],\n *   fn: (a, b, sep) => {\n *     // a: string, b: string, sep: string | undefined\n *     const separator = sep ?? \"\";\n *     return `${a}${separator}${b}`;\n *   },\n *   returnType: { type: \"string\" },\n * });\n * ```\n */\nexport function defineHelper<const P extends readonly TypedHelperParam[]>(\n\tconfig: TypedHelperConfig<P>,\n): HelperConfig {\n\treturn config as unknown as HelperConfig;\n}\n"],"names":["defineHelper","inferPrimitiveSchema","isArrayInput","isLiteralInput","isObjectInput","input","Array","isArray","value","type","Number","isInteger","config"],"mappings":"mPAyfgBA,sBAAAA,kBAzXAC,8BAAAA,0BAhCAC,sBAAAA,kBAbAC,wBAAAA,oBA0BAC,uBAAAA,iBA1BT,SAASD,eACfE,KAAoB,EAEpB,OACCA,QAAU,MAAS,OAAOA,QAAU,UAAY,OAAOA,QAAU,QAEnE,CAOO,SAASH,aACfG,KAAoB,EAEpB,OAAOC,MAAMC,OAAO,CAACF,MACtB,CASO,SAASD,cACfC,KAAoB,EAEpB,OAAOA,QAAU,MAAQ,OAAOA,QAAU,UAAY,CAACC,MAAMC,OAAO,CAACF,MACtE,CAeO,SAASJ,qBACfO,KAA8B,EAE9B,GAAIA,QAAU,KAAM,MAAO,CAAEC,KAAM,MAAO,EAC1C,GAAI,OAAOD,QAAU,UAAW,MAAO,CAAEC,KAAM,SAAU,EACzD,GAAI,OAAOD,QAAU,SAAU,CAC9B,OAAOE,OAAOC,SAAS,CAACH,OAAS,CAAEC,KAAM,SAAU,EAAI,CAAEA,KAAM,QAAS,CACzE,CAGAD,MACA,MAAO,CAAEC,KAAM,MAAO,CACvB,CA6WO,SAAST,aACfY,MAA4B,EAE5B,OAAOA,MACR"}
+{"version":3,"sources":["../../src/types.ts"],"sourcesContent":["import type { JSONSchema7 } from \"json-schema\";\nimport type { FromSchema, JSONSchema } from \"json-schema-to-ts\";\n\n// ─── Template Input ──────────────────────────────────────────────────────────\n// The engine accepts primitive values in addition to template strings.\n// When a non-string value is passed, it is treated as a literal passthrough:\n// analysis returns the inferred type, and execution returns the value as-is.\n\n/**\n * Object where each property is a `TemplateInput` (recursive).\n *\n * Allows passing an entire structure as a template:\n * ```\n * engine.analyze({\n *   userName: \"{{name}}\",\n *   userAge: \"{{age}}\",\n *   nested: { x: \"{{foo}}\" },\n * }, inputSchema);\n * ```\n */\nexport interface TemplateInputObject {\n\t[key: string]: TemplateInput;\n}\n\n/**\n * Array where each element is a `TemplateInput` (recursive).\n *\n * Allows passing an array as a template:\n * ```\n * engine.analyze([\"{{name}}\", \"{{age}}\"], inputSchema);\n * engine.execute([\"{{name}}\", 42], data);\n * ```\n */\nexport type TemplateInputArray = TemplateInput[];\n\n/**\n * Input type accepted by the template engine.\n *\n * - `string`              → standard Handlebars template (parsed and executed)\n * - `number`              → numeric literal (passthrough)\n * - `boolean`             → boolean literal (passthrough)\n * - `null`                → null literal (passthrough)\n * - `TemplateInputArray`  → array where each element is a `TemplateInput`\n * - `TemplateInputObject` → object where each property is a `TemplateInput`\n */\nexport type TemplateInput =\n\t| string\n\t| number\n\t| boolean\n\t| null\n\t| TemplateInputArray\n\t| TemplateInputObject;\n\n// ─── Template Data ───────────────────────────────────────────────────────────\n// The data parameter accepted by `execute()` and `analyzeAndExecute()`.\n// In most cases this is a `Record<string, unknown>` (object context), but\n// primitives are also allowed — for example when using `{{$root}}` to\n// reference the entire data value directly.\n\n/**\n * Data type accepted by the template engine's execution methods.\n *\n * - `Record<string, unknown>` → standard object context (most common)\n * - `string`                  → primitive value (e.g. for `{{$root}}`)\n * - `number`                  → primitive value\n * - `boolean`                 → primitive value\n * - `null`                    → null value\n * - `unknown[]`               → array value\n */\nexport type TemplateData =\n\t| Record<string, unknown>\n\t| string\n\t| number\n\t| boolean\n\t| null\n\t| unknown[];\n\n/**\n * Checks whether a value is a non-string primitive literal (number, boolean, null).\n * These values are treated as passthrough by the engine.\n *\n * Note: objects (`TemplateInputObject`) and arrays (`TemplateInputArray`) are NOT literals.\n */\nexport function isLiteralInput(\n\tinput: TemplateInput,\n): input is number | boolean | null {\n\treturn (\n\t\tinput === null || (typeof input !== \"string\" && typeof input !== \"object\")\n\t);\n}\n\n/**\n * Checks whether a value is a template array (`TemplateInputArray`).\n * Template arrays are processed recursively by the engine:\n * each element is analyzed/executed individually and the result is an array.\n */\nexport function isArrayInput(\n\tinput: TemplateInput,\n): input is TemplateInputArray {\n\treturn Array.isArray(input);\n}\n\n/**\n * Checks whether a value is a template object (`TemplateInputObject`).\n * Template objects are processed recursively by the engine:\n * each property is analyzed/executed individually.\n *\n * Note: arrays are excluded — use `isArrayInput()` first.\n */\nexport function isObjectInput(\n\tinput: TemplateInput,\n): input is TemplateInputObject {\n\treturn input !== null && typeof input === \"object\" && !Array.isArray(input);\n}\n\n/**\n * Infers the JSON Schema of a non-string primitive value.\n *\n * @param value - The primitive value (number, boolean, null)\n * @returns The corresponding JSON Schema\n *\n * @example\n * ```\n * inferPrimitiveSchema(42)    // → { type: \"number\" }\n * inferPrimitiveSchema(true)  // → { type: \"boolean\" }\n * inferPrimitiveSchema(null)  // → { type: \"null\" }\n * ```\n */\nexport function inferPrimitiveSchema(\n\tvalue: number | boolean | null,\n): JSONSchema7 {\n\tif (value === null) return { type: \"null\" };\n\tif (typeof value === \"boolean\") return { type: \"boolean\" };\n\tif (typeof value === \"number\") {\n\t\treturn Number.isInteger(value) ? { type: \"integer\" } : { type: \"number\" };\n\t}\n\t// Exhaustiveness check — all branches are covered above.\n\t// If the type of `value` changes, TypeScript will raise an error here.\n\tvalue satisfies never;\n\treturn { type: \"null\" };\n}\n\n// ─── Diagnostic Codes ────────────────────────────────────────────────────────\n// Machine-readable codes for each error/warning type, enabling the frontend\n// to react programmatically without parsing the human-readable message.\n\nexport type DiagnosticCode =\n\t/** The referenced property does not exist in the context schema */\n\t| \"UNKNOWN_PROPERTY\"\n\t/** Type mismatch (e.g. #each on a non-array) */\n\t| \"TYPE_MISMATCH\"\n\t/** A block helper is used without a required argument */\n\t| \"MISSING_ARGUMENT\"\n\t/** Unknown block helper (neither built-in nor registered) */\n\t| \"UNKNOWN_HELPER\"\n\t/** The expression cannot be statically analyzed */\n\t| \"UNANALYZABLE\"\n\t/** The {{key:N}} syntax is used but no identifierSchemas were provided */\n\t| \"MISSING_IDENTIFIER_SCHEMAS\"\n\t/** The identifier N does not exist in the provided identifierSchemas */\n\t| \"UNKNOWN_IDENTIFIER\"\n\t/** The property does not exist in the identifier's schema */\n\t| \"IDENTIFIER_PROPERTY_NOT_FOUND\"\n\t/** Syntax error in the template */\n\t| \"PARSE_ERROR\"\n\t/** The $root token is used with path traversal (e.g. $root.name) */\n\t| \"ROOT_PATH_TRAVERSAL\";\n\n// ─── Diagnostic Details ──────────────────────────────────────────────────────\n// Supplementary information to understand the exact cause of the error.\n// Designed to be easily JSON-serializable and consumable by a frontend.\n\nexport interface DiagnosticDetails {\n\t/** Path of the expression that caused the error (e.g. `\"user.name.foo\"`) */\n\tpath?: string;\n\t/** Name of the helper involved (for helper-related errors) */\n\thelperName?: string;\n\t/** What was expected (e.g. `\"array\"`, `\"property to exist\"`) */\n\texpected?: string;\n\t/** What was found (e.g. `\"string\"`, `\"undefined\"`) */\n\tactual?: string;\n\t/** Available properties in the current schema (for suggestions) */\n\tavailableProperties?: string[];\n\t/** Template identifier number (for `{{key:N}}` errors) */\n\tidentifier?: number;\n}\n\n// ─── Static Analysis Result ──────────────────────────────────────────────────\n\n/** Diagnostic produced by the static analyzer */\nexport interface TemplateDiagnostic {\n\t/** \"error\" blocks execution, \"warning\" is informational */\n\tseverity: \"error\" | \"warning\";\n\n\t/** Machine-readable code identifying the error type */\n\tcode: DiagnosticCode;\n\n\t/** Human-readable message describing the problem */\n\tmessage: string;\n\n\t/** Position in the template source (if available from the AST) */\n\tloc?: {\n\t\tstart: { line: number; column: number };\n\t\tend: { line: number; column: number };\n\t};\n\n\t/** Fragment of the template source around the error */\n\tsource?: string;\n\n\t/** Structured information for debugging and frontend display */\n\tdetails?: DiagnosticDetails;\n}\n\n/** Complete result of the static analysis */\nexport interface AnalysisResult {\n\t/** true if no errors (warnings are tolerated) */\n\tvalid: boolean;\n\t/** List of diagnostics (errors + warnings) */\n\tdiagnostics: TemplateDiagnostic[];\n\t/** JSON Schema describing the template's return type */\n\toutputSchema: JSONSchema7;\n}\n\n/** Lightweight validation result (without output type inference) */\nexport interface ValidationResult {\n\t/** true if no errors (warnings are tolerated) */\n\tvalid: boolean;\n\t/** List of diagnostics (errors + warnings) */\n\tdiagnostics: TemplateDiagnostic[];\n}\n\n// ─── Public Engine Options ───────────────────────────────────────────────────\n\nexport interface TemplateEngineOptions {\n\t/**\n\t * Capacity of the parsed AST cache. Each parsed template is cached\n\t * to avoid costly re-parsing on repeated calls.\n\t * @default 256\n\t */\n\tastCacheSize?: number;\n\n\t/**\n\t * Capacity of the compiled Handlebars template cache.\n\t * @default 256\n\t */\n\tcompilationCacheSize?: number;\n\n\t/**\n\t * Custom helpers to register during engine construction.\n\t *\n\t * Each entry describes a helper with its name, implementation,\n\t * expected parameters, and return type.\n\t *\n\t * @example\n\t * ```\n\t * const engine = new Typebars({\n\t *   helpers: [\n\t *     {\n\t *       name: \"uppercase\",\n\t *       description: \"Converts a string to uppercase\",\n\t *       fn: (value: string) => String(value).toUpperCase(),\n\t *       params: [\n\t *         { name: \"value\", type: { type: \"string\" }, description: \"The string to convert\" },\n\t *       ],\n\t *       returnType: { type: \"string\" },\n\t *     },\n\t *   ],\n\t * });\n\t * ```\n\t */\n\thelpers?: HelperConfig[];\n}\n\nexport interface CommonTypebarsOptions {\n\t/**\n\t * Explicit coercion schema for the output value.\n\t * When provided with a primitive type, the execution result will be\n\t * coerced to match the declared type instead of using auto-detection.\n\t */\n\tcoerceSchema?: JSONSchema7;\n\t/**\n\t * When `true`, properties whose values contain Handlebars expressions\n\t * (i.e. any `{{…}}` syntax) are excluded from the execution result.\n\t *\n\t * - **Object**: properties with template expressions are omitted from\n\t *   the resulting object.\n\t * - **Array**: elements with template expressions are omitted from\n\t *   the resulting array.\n\t * - **Root string** with expressions: returns `null` (there is no\n\t *   parent to exclude from).\n\t * - **Literals** (number, boolean, null): unaffected.\n\t *\n\t * This mirrors the analysis-side `excludeTemplateExpression` option\n\t * but applied at runtime.\n\t *\n\t * @default false\n\t */\n\texcludeTemplateExpression?: boolean;\n}\n\n// ─── Execution Options ───────────────────────────────────────────────────────\n// Optional options object for `execute()`, replacing multiple positional\n// parameters for better ergonomics.\n\nexport interface ExecuteOptions extends CommonTypebarsOptions {\n\t/** JSON Schema for pre-execution static validation */\n\tschema?: JSONSchema7;\n\t/** Data by identifier `{ [id]: { key: value } }` */\n\tidentifierData?: Record<number, Record<string, unknown>>;\n\t/** Schemas by identifier (for static validation with identifiers) */\n\tidentifierSchemas?: Record<number, JSONSchema7>;\n}\n\n// ─── Combined Analyze-and-Execute Options ────────────────────────────────────\n// Optional options object for `analyzeAndExecute()`, grouping parameters\n// related to template identifiers.\n\nexport interface AnalyzeAndExecuteOptions extends CommonTypebarsOptions {\n\t/** Schemas by identifier `{ [id]: JSONSchema7 }` for static analysis */\n\tidentifierSchemas?: Record<number, JSONSchema7>;\n\t/** Data by identifier `{ [id]: { key: value } }` for execution */\n\tidentifierData?: Record<number, Record<string, unknown>>;\n}\n\n// ─── Custom Helpers ──────────────────────────────────────────────────────────\n// Allows registering custom helpers with their type signature for static\n// analysis support.\n\n/** Describes a parameter expected by a helper */\nexport interface HelperParam {\n\t/** Parameter name (for documentation / introspection) */\n\tname: string;\n\n\t/**\n\t * JSON Schema describing the expected type for this parameter.\n\t * Used for documentation and static validation.\n\t */\n\ttype?: JSONSchema7;\n\n\t/** Human-readable description of the parameter */\n\tdescription?: string;\n\n\t/**\n\t * Whether the parameter is optional.\n\t * @default false\n\t */\n\toptional?: boolean;\n}\n\n/**\n * Definition of a helper registerable via `registerHelper()`.\n *\n * Contains the runtime implementation and typing metadata\n * for static analysis.\n */\nexport interface HelperDefinition {\n\t/**\n\t * Runtime implementation of the helper — will be registered with Handlebars.\n\t *\n\t * For an inline helper `{{uppercase name}}`:\n\t *   `(value: string) => string`\n\t *\n\t * For a block helper `{{#repeat count}}...{{/repeat}}`:\n\t *   `function(this: any, count: number, options: Handlebars.HelperOptions) { ... }`\n\t */\n\t// biome-ignore lint/suspicious/noExplicitAny: Handlebars helper signatures are inherently dynamic\n\tfn: (...args: any[]) => unknown;\n\n\t/**\n\t * Parameters expected by the helper (for documentation and analysis).\n\t *\n\t * @example\n\t * ```\n\t * params: [\n\t *   { name: \"value\", type: { type: \"number\" }, description: \"The value to round\" },\n\t *   { name: \"precision\", type: { type: \"number\" }, description: \"Decimal places\", optional: true },\n\t * ]\n\t * ```\n\t */\n\tparams?: HelperParam[];\n\n\t/**\n\t * JSON Schema describing the helper's return type for static analysis.\n\t * @default { type: \"string\" }\n\t */\n\treturnType?: JSONSchema7;\n\n\t/** Human-readable description of the helper */\n\tdescription?: string;\n}\n\n/**\n * Full helper configuration for registration via the `Typebars({ helpers: [...] })`\n * constructor options.\n *\n * Extends `HelperDefinition` with a required `name`.\n *\n * @example\n * ```\n * const config: HelperConfig = {\n *   name: \"round\",\n *   description: \"Rounds a number to a given precision\",\n *   fn: (value: number, precision?: number) => { ... },\n *   params: [\n *     { name: \"value\", type: { type: \"number\" } },\n *     { name: \"precision\", type: { type: \"number\" }, optional: true },\n *   ],\n *   returnType: { type: \"number\" },\n * };\n * ```\n */\nexport interface HelperConfig extends HelperDefinition {\n\t/** Name of the helper as used in templates (e.g. `\"uppercase\"`) */\n\tname: string;\n}\n\n// ─── Automatic Type Inference via json-schema-to-ts ──────────────────────────\n// Allows `defineHelper()` to infer TypeScript types for `fn` arguments\n// from the JSON Schemas declared in `params`.\n\n/**\n * Param definition used for type inference.\n * Accepts `JSONSchema` from `json-schema-to-ts` to allow `FromSchema`\n * to resolve literal types.\n */\ntype TypedHelperParam = {\n\treadonly name: string;\n\treadonly type?: JSONSchema;\n\treadonly description?: string;\n\treadonly optional?: boolean;\n};\n\n/**\n * Infers the TypeScript type of a single parameter from its JSON Schema.\n * - If `optional: true`, the resolved type is unioned with `undefined`.\n * - If `type` is not provided, the type is `unknown`.\n */\ntype InferParamType<P> = P extends {\n\treadonly type: infer S extends JSONSchema;\n\treadonly optional: true;\n}\n\t? FromSchema<S> | undefined\n\t: P extends { readonly type: infer S extends JSONSchema }\n\t\t? FromSchema<S>\n\t\t: unknown;\n\n/**\n * Maps a tuple of `TypedHelperParam` to a tuple of inferred TypeScript types,\n * usable as the `fn` signature.\n *\n * @example\n * ```\n * type Args = InferArgs<readonly [\n *   { name: \"a\"; type: { type: \"string\" } },\n *   { name: \"b\"; type: { type: \"number\" }; optional: true },\n * ]>;\n * // => [string, number | undefined]\n * ```\n */\ntype InferArgs<P extends readonly TypedHelperParam[]> = {\n\t[K in keyof P]: InferParamType<P[K]>;\n};\n\n/**\n * Helper configuration with generic parameter inference.\n * Used exclusively by `defineHelper()`.\n */\ninterface TypedHelperConfig<P extends readonly TypedHelperParam[]> {\n\tname: string;\n\tdescription?: string;\n\tparams: P;\n\tfn: (...args: InferArgs<P>) => unknown;\n\treturnType?: JSONSchema;\n}\n\n/**\n * Creates a `HelperConfig` with automatic type inference for `fn` arguments\n * based on the JSON Schemas declared in `params`.\n *\n * The generic parameter `const P` preserves schema literal types\n * (equivalent of `as const`), enabling `FromSchema` to resolve the\n * corresponding TypeScript types.\n *\n * @example\n * ```\n * const helper = defineHelper({\n *   name: \"concat\",\n *   description: \"Concatenates two strings\",\n *   params: [\n *     { name: \"a\", type: { type: \"string\" }, description: \"First string\" },\n *     { name: \"b\", type: { type: \"string\" }, description: \"Second string\" },\n *     { name: \"sep\", type: { type: \"string\" }, description: \"Separator\", optional: true },\n *   ],\n *   fn: (a, b, sep) => {\n *     // a: string, b: string, sep: string | undefined\n *     const separator = sep ?? \"\";\n *     return `${a}${separator}${b}`;\n *   },\n *   returnType: { type: \"string\" },\n * });\n * ```\n */\nexport function defineHelper<const P extends readonly TypedHelperParam[]>(\n\tconfig: TypedHelperConfig<P>,\n): HelperConfig {\n\treturn config as unknown as HelperConfig;\n}\n"],"names":["defineHelper","inferPrimitiveSchema","isArrayInput","isLiteralInput","isObjectInput","input","Array","isArray","value","type","Number","isInteger","config"],"mappings":"mPAsfgBA,sBAAAA,kBAtXAC,8BAAAA,0BAhCAC,sBAAAA,kBAbAC,wBAAAA,oBA0BAC,uBAAAA,iBA1BT,SAASD,eACfE,KAAoB,EAEpB,OACCA,QAAU,MAAS,OAAOA,QAAU,UAAY,OAAOA,QAAU,QAEnE,CAOO,SAASH,aACfG,KAAoB,EAEpB,OAAOC,MAAMC,OAAO,CAACF,MACtB,CASO,SAASD,cACfC,KAAoB,EAEpB,OAAOA,QAAU,MAAQ,OAAOA,QAAU,UAAY,CAACC,MAAMC,OAAO,CAACF,MACtE,CAeO,SAASJ,qBACfO,KAA8B,EAE9B,GAAIA,QAAU,KAAM,MAAO,CAAEC,KAAM,MAAO,EAC1C,GAAI,OAAOD,QAAU,UAAW,MAAO,CAAEC,KAAM,SAAU,EACzD,GAAI,OAAOD,QAAU,SAAU,CAC9B,OAAOE,OAAOC,SAAS,CAACH,OAAS,CAAEC,KAAM,SAAU,EAAI,CAAEA,KAAM,QAAS,CACzE,CAGAD,MACA,MAAO,CAAEC,KAAM,MAAO,CACvB,CA0WO,SAAST,aACfY,MAA4B,EAE5B,OAAOA,MACR"}