typebars 1.0.3 → 1.0.5

package/dist/esm/schema-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/schema-resolver.ts"],"sourcesContent":["import type { JSONSchema7 } from \"json-schema\";\nimport { UnsupportedSchemaError } from \"./errors.ts\";\nimport { deepEqual } from \"./utils.ts\";\n\n// ─── JSON Schema Resolver ────────────────────────────────────────────────────\n// Utility for navigating a JSON Schema Draft v7 by following a property path\n// (e.g. [\"user\", \"address\", \"city\"]).\n//\n// Handles:\n// - `$ref` resolution (internal references #/definitions/...)\n// - Navigation through `properties`\n// - Navigation through `items` (array elements)\n// - Combinators `allOf`, `anyOf`, `oneOf` (searches each branch)\n// - `additionalProperties` when the property is not explicitly declared\n//\n// Rejects:\n// - Conditional schemas (`if/then/else`) — non-resolvable without runtime data\n\n// ─── Conditional Schema Detection ────────────────────────────────────────────\n// JSON Schema Draft v7 introduced `if/then/else` conditional schemas.\n// These are fundamentally non-resolvable during static analysis because\n// they depend on runtime data values. Rather than silently ignoring them\n// (which would produce incorrect results — missing properties, wrong types),\n// we fail fast with a clear error pointing to the exact location in the schema.\n\n/**\n * Recursively validates that a JSON Schema does not contain `if/then/else`\n * conditional keywords. Throws an `UnsupportedSchemaError` if any are found.\n *\n * This check traverses the entire schema tree, including:\n * - `properties` values\n * - `additionalProperties` (when it's a schema)\n * - `items` (single schema or tuple)\n * - `allOf`, `anyOf`, `oneOf` branches\n * - `not`\n * - `definitions` / `$defs` values\n *\n * A `Set<object>` is used to track visited schemas and prevent infinite loops\n * from circular structures.\n *\n * @param schema - The JSON Schema to validate\n * @param path   - The current JSON pointer path (for error reporting)\n * @param visited - Set of already-visited schema objects (cycle protection)\n *\n * @throws {UnsupportedSchemaError} if `if`, `then`, or `else` is found\n *\n * @example\n * ```\n * // Throws UnsupportedSchemaError:\n * assertNoConditionalSchema({\n *   type: \"object\",\n *   if: { properties: { kind: { const: \"a\" } } },\n *   then: { properties: { a: { type: \"string\" } } },\n * });\n *\n * // OK — no conditional keywords:\n * assertNoConditionalSchema({\n *   type: \"object\",\n *   properties: { name: { type: \"string\" } },\n * });\n * ```\n */\nexport function assertNoConditionalSchema(\n\tschema: JSONSchema7,\n\tpath = \"\",\n\tvisited: Set<object> = new Set(),\n): void {\n\t// Cycle protection — avoid infinite loops on circular schema structures\n\tif (visited.has(schema)) return;\n\tvisited.add(schema);\n\n\t// ── Detect if/then/else at the current level ─────────────────────────\n\tif (schema.if !== undefined) {\n\t\tthrow new UnsupportedSchemaError(\"if/then/else\", path || \"/\");\n\t}\n\t// `then` or `else` without `if` is unusual but still unsupported\n\tif (schema.then !== undefined) {\n\t\tthrow new UnsupportedSchemaError(\"if/then/else\", path || \"/\");\n\t}\n\tif (schema.else !== undefined) {\n\t\tthrow new UnsupportedSchemaError(\"if/then/else\", path || \"/\");\n\t}\n\n\t// ── Recurse into properties ──────────────────────────────────────────\n\tif (schema.properties) {\n\t\tfor (const [key, prop] of Object.entries(schema.properties)) {\n\t\t\tif (prop && typeof prop !== \"boolean\") {\n\t\t\t\tassertNoConditionalSchema(prop, `${path}/properties/${key}`, visited);\n\t\t\t}\n\t\t}\n\t}\n\n\t// ── Recurse into additionalProperties ────────────────────────────────\n\tif (\n\t\tschema.additionalProperties &&\n\t\ttypeof schema.additionalProperties === \"object\"\n\t) {\n\t\tassertNoConditionalSchema(\n\t\t\tschema.additionalProperties,\n\t\t\t`${path}/additionalProperties`,\n\t\t\tvisited,\n\t\t);\n\t}\n\n\t// ── Recurse into items ───────────────────────────────────────────────\n\tif (schema.items) {\n\t\tif (Array.isArray(schema.items)) {\n\t\t\tfor (let i = 0; i < schema.items.length; i++) {\n\t\t\t\tconst item = schema.items[i];\n\t\t\t\tif (item && typeof item !== \"boolean\") {\n\t\t\t\t\tassertNoConditionalSchema(item, `${path}/items/${i}`, visited);\n\t\t\t\t}\n\t\t\t}\n\t\t} else if (typeof schema.items !== \"boolean\") {\n\t\t\tassertNoConditionalSchema(schema.items, `${path}/items`, visited);\n\t\t}\n\t}\n\n\t// ── Recurse into combinators ─────────────────────────────────────────\n\tfor (const keyword of [\"allOf\", \"anyOf\", \"oneOf\"] as const) {\n\t\tconst branches = schema[keyword];\n\t\tif (branches) {\n\t\t\tfor (let i = 0; i < branches.length; i++) {\n\t\t\t\tconst branch = branches[i];\n\t\t\t\tif (branch && typeof branch !== \"boolean\") {\n\t\t\t\t\tassertNoConditionalSchema(branch, `${path}/${keyword}/${i}`, visited);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t// ── Recurse into not ─────────────────────────────────────────────────\n\tif (schema.not && typeof schema.not !== \"boolean\") {\n\t\tassertNoConditionalSchema(schema.not, `${path}/not`, visited);\n\t}\n\n\t// ── Recurse into definitions / $defs ─────────────────────────────────\n\tfor (const defsKey of [\"definitions\", \"$defs\"] as const) {\n\t\tconst defs = schema[defsKey];\n\t\tif (defs) {\n\t\t\tfor (const [name, def] of Object.entries(defs)) {\n\t\t\t\tif (def && typeof def !== \"boolean\") {\n\t\t\t\t\tassertNoConditionalSchema(def, `${path}/${defsKey}/${name}`, visited);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n\n// ─── $ref Resolution ─────────────────────────────────────────────────────────\n// Only supports internal references in the format `#/definitions/Foo`\n// or `#/$defs/Foo` (JSON Schema Draft 2019+). Remote $refs (URLs) are\n// not supported — that is outside the scope of a template engine.\n\n/**\n * Recursively resolves `$ref` in a schema using the root schema as the\n * source of definitions.\n */\nexport function resolveRef(\n\tschema: JSONSchema7,\n\troot: JSONSchema7,\n): JSONSchema7 {\n\tif (!schema.$ref) return schema;\n\n\tconst ref = schema.$ref;\n\n\t// Expected format: #/definitions/Name or #/$defs/Name\n\tconst match = ref.match(/^#\\/(definitions|\\$defs)\\/(.+)$/);\n\tif (!match) {\n\t\tthrow new Error(\n\t\t\t`Unsupported $ref format: \"${ref}\". Only internal #/definitions/ references are supported.`,\n\t\t);\n\t}\n\n\tconst defsKey = match[1] as \"definitions\" | \"$defs\";\n\tconst name = match[2] ?? \"\";\n\n\tconst defs = defsKey === \"definitions\" ? root.definitions : root.$defs;\n\n\tif (!defs || !(name in defs)) {\n\t\tthrow new Error(\n\t\t\t`Cannot resolve $ref \"${ref}\": definition \"${name}\" not found.`,\n\t\t);\n\t}\n\n\t// Recursive resolution in case the definition itself contains a $ref\n\tconst def = defs[name];\n\tif (!def || typeof def === \"boolean\") {\n\t\tthrow new Error(\n\t\t\t`Cannot resolve $ref \"${ref}\": definition \"${name}\" not found.`,\n\t\t);\n\t}\n\treturn resolveRef(def, root);\n}\n\n// ─── Single-Segment Path Navigation ─────────────────────────────────────────\n\n/**\n * Resolves a single path segment (a property name) within a schema.\n * Returns the corresponding sub-schema, or `undefined` if the path is invalid.\n *\n * @param schema  - The current schema (already resolved, no $ref)\n * @param segment - The property name to resolve\n * @param root    - The root schema (for resolving any internal $refs)\n */\nfunction resolveSegment(\n\tschema: JSONSchema7,\n\tsegment: string,\n\troot: JSONSchema7,\n): JSONSchema7 | undefined {\n\tconst resolved = resolveRef(schema, root);\n\n\t// 1. Explicit properties\n\tif (resolved.properties && segment in resolved.properties) {\n\t\tconst prop = resolved.properties[segment];\n\t\tif (prop && typeof prop !== \"boolean\") return resolveRef(prop, root);\n\t\tif (prop === true) return {};\n\t}\n\n\t// 2. additionalProperties (when the property is not declared)\n\tif (\n\t\tresolved.additionalProperties !== undefined &&\n\t\tresolved.additionalProperties !== false\n\t) {\n\t\tif (resolved.additionalProperties === true) {\n\t\t\t// additionalProperties: true → type is unknown\n\t\t\treturn {};\n\t\t}\n\t\treturn resolveRef(resolved.additionalProperties, root);\n\t}\n\n\t// 3. Intrinsic array properties (e.g. `.length`)\n\tconst schemaType = resolved.type;\n\tconst isArray =\n\t\tschemaType === \"array\" ||\n\t\t(Array.isArray(schemaType) && schemaType.includes(\"array\"));\n\n\tif (isArray && segment === \"length\") {\n\t\treturn { type: \"integer\" };\n\t}\n\n\t// 4. Combinators — search within each branch\n\tconst combinatorResult = resolveInCombinators(resolved, segment, root);\n\tif (combinatorResult) return combinatorResult;\n\n\treturn undefined;\n}\n\n/**\n * Searches for a segment within `allOf`, `anyOf`, `oneOf` branches.\n * Returns the first matching sub-schema, or `undefined`.\n * For `allOf`, found results are merged into a single `allOf`.\n */\nfunction resolveInCombinators(\n\tschema: JSONSchema7,\n\tsegment: string,\n\troot: JSONSchema7,\n): JSONSchema7 | undefined {\n\t// allOf: the property can be defined in any branch, and all constraints\n\t// apply simultaneously.\n\tif (schema.allOf) {\n\t\tconst matches = schema.allOf\n\t\t\t.filter((b): b is JSONSchema7 => typeof b !== \"boolean\")\n\t\t\t.map((branch) => resolveSegment(branch, segment, root))\n\t\t\t.filter((s): s is JSONSchema7 => s !== undefined);\n\n\t\tif (matches.length === 1) return matches[0] as JSONSchema7;\n\t\tif (matches.length > 1) return { allOf: matches };\n\t}\n\n\t// anyOf / oneOf: the property can come from any branch.\n\tfor (const key of [\"anyOf\", \"oneOf\"] as const) {\n\t\tif (!schema[key]) continue;\n\t\tconst matches = schema[key]\n\t\t\t.filter((b): b is JSONSchema7 => typeof b !== \"boolean\")\n\t\t\t.map((branch) => resolveSegment(branch, segment, root))\n\t\t\t.filter((s): s is JSONSchema7 => s !== undefined);\n\n\t\tif (matches.length === 1) return matches[0] as JSONSchema7;\n\t\tif (matches.length > 1) return { [key]: matches };\n\t}\n\n\treturn undefined;\n}\n\n// ─── Public API ──────────────────────────────────────────────────────────────\n\n/**\n * Resolves a full path (e.g. [\"user\", \"address\", \"city\"]) within a JSON\n * Schema and returns the corresponding sub-schema.\n *\n * @param schema - The root schema describing the template context\n * @param path   - Array of segments (property names)\n * @returns The sub-schema at the end of the path, or `undefined` if the path\n *          cannot be resolved.\n *\n * @example\n * ```\n * const schema = {\n *   type: \"object\",\n *   properties: {\n *     user: {\n *       type: \"object\",\n *       properties: {\n *         name: { type: \"string\" }\n *       }\n *     }\n *   }\n * };\n * resolveSchemaPath(schema, [\"user\", \"name\"]);\n * // → { type: \"string\" }\n * ```\n */\nexport function resolveSchemaPath(\n\tschema: JSONSchema7,\n\tpath: string[],\n): JSONSchema7 | undefined {\n\tif (path.length === 0) return resolveRef(schema, schema);\n\n\tlet current: JSONSchema7 = resolveRef(schema, schema);\n\tconst root = schema;\n\n\tfor (const segment of path) {\n\t\tconst next = resolveSegment(current, segment, root);\n\t\tif (next === undefined) return undefined;\n\t\tcurrent = next;\n\t}\n\n\treturn current;\n}\n\n/**\n * Resolves the item schema of an array.\n * If the schema is not of type `array` or has no `items`, returns `undefined`.\n *\n * @param schema - The array schema\n * @param root   - The root schema (for resolving $refs)\n */\nexport function resolveArrayItems(\n\tschema: JSONSchema7,\n\troot: JSONSchema7,\n): JSONSchema7 | undefined {\n\tconst resolved = resolveRef(schema, root);\n\n\t// Verify that it's actually an array\n\tconst schemaType = resolved.type;\n\tconst isArray =\n\t\tschemaType === \"array\" ||\n\t\t(Array.isArray(schemaType) && schemaType.includes(\"array\"));\n\n\tif (!isArray && resolved.items === undefined) {\n\t\treturn undefined;\n\t}\n\n\tif (resolved.items === undefined) {\n\t\t// array without items → element type is unknown\n\t\treturn {};\n\t}\n\n\t// items can be a boolean (true = anything, false = nothing)\n\tif (typeof resolved.items === \"boolean\") {\n\t\treturn {};\n\t}\n\n\t// items can be a single schema or a tuple (array of schemas).\n\t// For template loops, we handle the single-schema case.\n\tif (Array.isArray(resolved.items)) {\n\t\t// Tuple: create a oneOf of all possible types\n\t\tconst schemas = resolved.items\n\t\t\t.filter((item): item is JSONSchema7 => typeof item !== \"boolean\")\n\t\t\t.map((item) => resolveRef(item, root));\n\t\tif (schemas.length === 0) return {};\n\t\treturn { oneOf: schemas };\n\t}\n\n\treturn resolveRef(resolved.items, root);\n}\n\n/**\n * Simplifies an output schema to avoid unnecessarily complex constructs\n * (e.g. `oneOf` with a single element, duplicates, etc.).\n *\n * Uses `deepEqual` for deduplication — more robust and performant than\n * `JSON.stringify` (independent of key order, no intermediate string\n * allocations).\n */\nexport function simplifySchema(schema: JSONSchema7): JSONSchema7 {\n\t// oneOf / anyOf with a single element → unwrap\n\tfor (const key of [\"oneOf\", \"anyOf\"] as const) {\n\t\tconst arr = schema[key];\n\t\tif (arr && arr.length === 1) {\n\t\t\tconst first = arr[0];\n\t\t\tif (first !== undefined && typeof first !== \"boolean\")\n\t\t\t\treturn simplifySchema(first);\n\t\t}\n\t}\n\n\t// allOf with a single element → unwrap\n\tif (schema.allOf && schema.allOf.length === 1) {\n\t\tconst first = schema.allOf[0];\n\t\tif (first !== undefined && typeof first !== \"boolean\")\n\t\t\treturn simplifySchema(first);\n\t}\n\n\t// Deduplicate identical entries in oneOf/anyOf\n\tfor (const key of [\"oneOf\", \"anyOf\"] as const) {\n\t\tconst arr = schema[key];\n\t\tif (arr && arr.length > 1) {\n\t\t\tconst unique: JSONSchema7[] = [];\n\t\t\tfor (const entry of arr) {\n\t\t\t\tif (typeof entry === \"boolean\") continue;\n\t\t\t\t// Use deepEqual instead of JSON.stringify for structural\n\t\t\t\t// comparison — more robust (key order independent) and\n\t\t\t\t// more performant (no string allocations).\n\t\t\t\tconst isDuplicate = unique.some((existing) =>\n\t\t\t\t\tdeepEqual(existing, entry),\n\t\t\t\t);\n\t\t\t\tif (!isDuplicate) {\n\t\t\t\t\tunique.push(simplifySchema(entry));\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (unique.length === 1) return unique[0] as JSONSchema7;\n\t\t\treturn { ...schema, [key]: unique };\n\t\t}\n\t}\n\n\treturn schema;\n}\n"],"names":["UnsupportedSchemaError","deepEqual","assertNoConditionalSchema","schema","path","visited","Set","has","add","if","undefined","then","else","properties","key","prop","Object","entries","additionalProperties","items","Array","isArray","i","length","item","keyword","branches","branch","not","defsKey","defs","name","def","resolveRef","root","$ref","ref","match","Error","definitions","$defs","resolveSegment","segment","resolved","schemaType","type","includes","combinatorResult","resolveInCombinators","allOf","matches","filter","b","map","s","resolveSchemaPath","current","next","resolveArrayItems","schemas","oneOf","simplifySchema","arr","first","unique","entry","isDuplicate","some","existing","push"],"mappings":"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"}

package/dist/esm/typebars.d.ts

@@ -0,0 +1,130 @@
+import type { JSONSchema7 } from "json-schema";
+import { CompiledTemplate } from "./compiled-template.js";
+import type { AnalysisResult, AnalyzeAndExecuteOptions, ExecuteOptions, HelperDefinition, TemplateEngineOptions, TemplateInput, ValidationResult } from "./types.js";
+export declare class Typebars {
+    /** Isolated Handlebars environment — each engine has its own helpers */
+    private readonly hbs;
+    /** LRU cache of parsed ASTs (avoids re-parsing) */
+    private readonly astCache;
+    /** LRU cache of compiled Handlebars templates (avoids recompilation) */
+    private readonly compilationCache;
+    /** Custom helpers registered on this instance */
+    private readonly helpers;
+    constructor(options?: TemplateEngineOptions);
+    /**
+     * Compiles a template and returns a `CompiledTemplate` ready to be
+     * executed or analyzed without re-parsing.
+     *
+     * Accepts a `TemplateInput`: string, number, boolean, null, or object.
+     * For objects, each property is compiled recursively.
+     *
+     * @param template - The template to compile
+     * @returns A reusable `CompiledTemplate`
+     */
+    compile(template: TemplateInput): CompiledTemplate;
+    /**
+     * Statically analyzes a template against a JSON Schema v7 describing
+     * the available context.
+     *
+     * Accepts a `TemplateInput`: string, number, boolean, null, or object.
+     * For objects, each property is analyzed recursively and the
+     * `outputSchema` reflects the object structure with resolved types.
+     *
+     * @param template           - The template to analyze
+     * @param inputSchema        - JSON Schema v7 describing the available variables
+     * @param identifierSchemas  - (optional) Schemas by identifier `{ [id]: JSONSchema7 }`
+     */
+    analyze(template: TemplateInput, inputSchema: JSONSchema7, identifierSchemas?: Record<number, JSONSchema7>): AnalysisResult;
+    /**
+     * Validates a template against a schema without returning the output type.
+     *
+     * This is an API shortcut for `analyze()` that only returns `valid` and
+     * `diagnostics`, without `outputSchema`. The full analysis (including type
+     * inference) is executed internally — this method provides no performance
+     * gain, only a simplified API.
+     *
+     * @param template           - The template to validate
+     * @param inputSchema        - JSON Schema v7 describing the available variables
+     * @param identifierSchemas  - (optional) Schemas by identifier
+     */
+    validate(template: TemplateInput, inputSchema: JSONSchema7, identifierSchemas?: Record<number, JSONSchema7>): ValidationResult;
+    /**
+     * Checks only that the template syntax is valid (parsing).
+     * Does not require a schema — useful for quick feedback in an editor.
+     *
+     * For objects, recursively checks each property.
+     *
+     * @param template - The template to validate
+     * @returns `true` if the template is syntactically correct
+     */
+    isValidSyntax(template: TemplateInput): boolean;
+    /**
+     * Executes a template with the provided data.
+     *
+     * Accepts a `TemplateInput`: string, number, boolean, null, or object.
+     * For objects, each property is executed recursively and an object with
+     * resolved values is returned.
+     *
+     * If a `schema` is provided in options, static analysis is performed
+     * before execution. A `TemplateAnalysisError` is thrown on errors.
+     *
+     * @param template - The template to execute
+     * @param data     - The context data for rendering
+     * @param options  - Execution options (schema, identifierData, identifierSchemas)
+     * @returns The execution result
+     */
+    execute(template: TemplateInput, data: Record<string, unknown>, options?: ExecuteOptions): unknown;
+    /**
+     * Analyzes a template and, if valid, executes it with the provided data.
+     * Returns both the analysis result and the executed value.
+     *
+     * For objects, each property is analyzed and executed recursively.
+     * The entire object is considered invalid if at least one property is.
+     *
+     * @param template    - The template
+     * @param inputSchema - JSON Schema v7 describing the available variables
+     * @param data        - The context data for rendering
+     * @param options     - (optional) Options for template identifiers
+     * @returns An object `{ analysis, value }` where `value` is `undefined`
+     *          if analysis failed.
+     */
+    analyzeAndExecute(template: TemplateInput, inputSchema: JSONSchema7, data: Record<string, unknown>, options?: AnalyzeAndExecuteOptions): {
+        analysis: AnalysisResult;
+        value: unknown;
+    };
+    /**
+     * Registers a custom helper on this engine instance.
+     *
+     * The helper is available for both execution (via Handlebars) and
+     * static analysis (via its declared `returnType`).
+     *
+     * @param name       - Helper name (e.g. `"uppercase"`)
+     * @param definition - Helper definition (implementation + return type)
+     * @returns `this` to allow chaining
+     */
+    registerHelper(name: string, definition: HelperDefinition): this;
+    /**
+     * Removes a custom helper from this engine instance.
+     *
+     * @param name - Name of the helper to remove
+     * @returns `this` to allow chaining
+     */
+    unregisterHelper(name: string): this;
+    /**
+     * Checks whether a helper is registered on this instance.
+     *
+     * @param name - Helper name
+     * @returns `true` if the helper is registered
+     */
+    hasHelper(name: string): boolean;
+    /**
+     * Clears all internal caches (AST + compilation).
+     *
+     * Useful after a configuration change or to free memory.
+     */
+    clearCaches(): void;
+    /**
+     * Retrieves the AST of a template from the cache, or parses and caches it.
+     */
+    private getCachedAst;
+}

package/dist/esm/typebars.js

@@ -0,0 +1,2 @@
+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}import Handlebars from"handlebars";import{analyzeFromAst}from"./analyzer.js";import{CompiledTemplate}from"./compiled-template.js";import{TemplateAnalysisError}from"./errors.js";import{executeFromAst}from"./executor.js";import{LogicalHelpers,MathHelpers}from"./helpers/index.js";import{parse}from"./parser.js";import{inferPrimitiveSchema,isLiteralInput,isObjectInput}from"./types.js";import{aggregateObjectAnalysis,aggregateObjectAnalysisAndExecution,LRUCache}from"./utils.js";export class Typebars{compile(template){if(isObjectInput(template)){const children={};for(const[key,value]of Object.entries(template)){children[key]=this.compile(value)}return CompiledTemplate.fromObject(children,{helpers:this.helpers,hbs:this.hbs,compilationCache:this.compilationCache})}if(isLiteralInput(template)){return 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 CompiledTemplate.fromTemplate(ast,template,options)}analyze(template,inputSchema,identifierSchemas){if(isObjectInput(template)){return aggregateObjectAnalysis(Object.keys(template),key=>this.analyze(template[key],inputSchema,identifierSchemas))}if(isLiteralInput(template)){return{valid:true,diagnostics:[],outputSchema:inferPrimitiveSchema(template)}}const ast=this.getCachedAst(template);return analyzeFromAst(ast,template,inputSchema,{identifierSchemas,helpers:this.helpers})}validate(template,inputSchema,identifierSchemas){const analysis=this.analyze(template,inputSchema,identifierSchemas);return{valid:analysis.valid,diagnostics:analysis.diagnostics}}isValidSyntax(template){if(isObjectInput(template)){return Object.values(template).every(v=>this.isValidSyntax(v))}if(isLiteralInput(template))return true;try{this.getCachedAst(template);return true}catch{return false}}execute(template,data,options){if(isObjectInput(template)){const result={};for(const[key,value]of Object.entries(template)){result[key]=this.execute(value,data,options)}return result}if(isLiteralInput(template))return template;const ast=this.getCachedAst(template);if(options?.schema){const analysis=analyzeFromAst(ast,template,options.schema,{identifierSchemas:options.identifierSchemas,helpers:this.helpers});if(!analysis.valid){throw new TemplateAnalysisError(analysis.diagnostics)}}return executeFromAst(ast,template,data,{identifierData:options?.identifierData,hbs:this.hbs,compilationCache:this.compilationCache})}analyzeAndExecute(template,inputSchema,data,options){if(isObjectInput(template)){return aggregateObjectAnalysisAndExecution(Object.keys(template),key=>this.analyzeAndExecute(template[key],inputSchema,data,options))}if(isLiteralInput(template)){return{analysis:{valid:true,diagnostics:[],outputSchema:inferPrimitiveSchema(template)},value:template}}const ast=this.getCachedAst(template);const analysis=analyzeFromAst(ast,template,inputSchema,{identifierSchemas:options?.identifierSchemas,helpers:this.helpers});if(!analysis.valid){return{analysis,value:undefined}}const value=executeFromAst(ast,template,data,{identifierData:options?.identifierData,hbs:this.hbs,compilationCache:this.compilationCache});return{analysis,value}}registerHelper(name,definition){this.helpers.set(name,definition);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=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.create();this.astCache=new LRUCache(options.astCacheSize??256);this.compilationCache=new LRUCache(options.compilationCacheSize??256);new MathHelpers().register(this);new LogicalHelpers().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/esm/typebars.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/typebars.ts"],"sourcesContent":["import Handlebars from \"handlebars\";\nimport type { JSONSchema7 } from \"json-schema\";\nimport { analyzeFromAst } from \"./analyzer.ts\";\nimport {\n\tCompiledTemplate,\n\ttype CompiledTemplateOptions,\n} from \"./compiled-template.ts\";\nimport { TemplateAnalysisError } from \"./errors.ts\";\nimport { executeFromAst } from \"./executor.ts\";\nimport { LogicalHelpers, MathHelpers } from \"./helpers/index.ts\";\nimport { parse } from \"./parser.ts\";\nimport type {\n\tAnalysisResult,\n\tAnalyzeAndExecuteOptions,\n\tExecuteOptions,\n\tHelperDefinition,\n\tTemplateEngineOptions,\n\tTemplateInput,\n\tValidationResult,\n} from \"./types.ts\";\nimport {\n\tinferPrimitiveSchema,\n\tisLiteralInput,\n\tisObjectInput,\n} from \"./types.ts\";\nimport {\n\taggregateObjectAnalysis,\n\taggregateObjectAnalysisAndExecution,\n\tLRUCache,\n} 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, { 1: node1Schema });\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\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 (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 identifierSchemas  - (optional) Schemas by identifier `{ [id]: JSONSchema7 }`\n\t */\n\tanalyze(\n\t\ttemplate: TemplateInput,\n\t\tinputSchema: JSONSchema7,\n\t\tidentifierSchemas?: Record<number, JSONSchema7>,\n\t): AnalysisResult {\n\t\tif (isObjectInput(template)) {\n\t\t\treturn aggregateObjectAnalysis(Object.keys(template), (key) =>\n\t\t\t\tthis.analyze(\n\t\t\t\t\ttemplate[key] as TemplateInput,\n\t\t\t\t\tinputSchema,\n\t\t\t\t\tidentifierSchemas,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\t\tif (isLiteralInput(template)) {\n\t\t\treturn {\n\t\t\t\tvalid: true,\n\t\t\t\tdiagnostics: [],\n\t\t\t\toutputSchema: inferPrimitiveSchema(template),\n\t\t\t};\n\t\t}\n\t\tconst ast = this.getCachedAst(template);\n\t\treturn analyzeFromAst(ast, template, inputSchema, {\n\t\t\tidentifierSchemas,\n\t\t\thelpers: this.helpers,\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\tidentifierSchemas?: Record<number, JSONSchema7>,\n\t): ValidationResult {\n\t\tconst analysis = this.analyze(template, inputSchema, identifierSchemas);\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 (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: Record<string, unknown>,\n\t\toptions?: ExecuteOptions,\n\t): unknown {\n\t\t// ── Object template → recursive execution ────────────────────────────\n\t\tif (isObjectInput(template)) {\n\t\t\tconst result: Record<string, unknown> = {};\n\t\t\tfor (const [key, value] of Object.entries(template)) {\n\t\t\t\tresult[key] = this.execute(value, data, options);\n\t\t\t}\n\t\t\treturn result;\n\t\t}\n\n\t\t// ── Passthrough for literal values ────────────────────────────────────\n\t\tif (isLiteralInput(template)) return template;\n\n\t\t// ── Parse once ───────────────────────────────────────────────────────\n\t\tconst ast = this.getCachedAst(template);\n\n\t\t// ── Pre-execution static validation ──────────────────────────────────\n\t\tif (options?.schema) {\n\t\t\tconst analysis = analyzeFromAst(ast, template, options.schema, {\n\t\t\t\tidentifierSchemas: options.identifierSchemas,\n\t\t\t\thelpers: this.helpers,\n\t\t\t});\n\t\t\tif (!analysis.valid) {\n\t\t\t\tthrow new TemplateAnalysisError(analysis.diagnostics);\n\t\t\t}\n\t\t}\n\n\t\t// ── Execution ────────────────────────────────────────────────────────\n\t\treturn executeFromAst(ast, template, data, {\n\t\t\tidentifierData: options?.identifierData,\n\t\t\thbs: this.hbs,\n\t\t\tcompilationCache: this.compilationCache,\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: Record<string, unknown>,\n\t\toptions?: AnalyzeAndExecuteOptions,\n\t): { analysis: AnalysisResult; value: unknown } {\n\t\tif (isObjectInput(template)) {\n\t\t\treturn aggregateObjectAnalysisAndExecution(Object.keys(template), (key) =>\n\t\t\t\tthis.analyzeAndExecute(\n\t\t\t\t\ttemplate[key] as TemplateInput,\n\t\t\t\t\tinputSchema,\n\t\t\t\t\tdata,\n\t\t\t\t\toptions,\n\t\t\t\t),\n\t\t\t);\n\t\t}\n\n\t\tif (isLiteralInput(template)) {\n\t\t\treturn {\n\t\t\t\tanalysis: {\n\t\t\t\t\tvalid: true,\n\t\t\t\t\tdiagnostics: [],\n\t\t\t\t\toutputSchema: inferPrimitiveSchema(template),\n\t\t\t\t},\n\t\t\t\tvalue: template,\n\t\t\t};\n\t\t}\n\n\t\tconst ast = this.getCachedAst(template);\n\t\tconst analysis = analyzeFromAst(ast, template, inputSchema, {\n\t\t\tidentifierSchemas: options?.identifierSchemas,\n\t\t\thelpers: this.helpers,\n\t\t});\n\n\t\tif (!analysis.valid) {\n\t\t\treturn { analysis, value: undefined };\n\t\t}\n\n\t\tconst value = executeFromAst(ast, template, data, {\n\t\t\tidentifierData: options?.identifierData,\n\t\t\thbs: this.hbs,\n\t\t\tcompilationCache: this.compilationCache,\n\t\t});\n\t\treturn { analysis, value };\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\t\tthis.hbs.registerHelper(name, definition.fn);\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":["Handlebars","analyzeFromAst","CompiledTemplate","TemplateAnalysisError","executeFromAst","LogicalHelpers","MathHelpers","parse","inferPrimitiveSchema","isLiteralInput","isObjectInput","aggregateObjectAnalysis","aggregateObjectAnalysisAndExecution","LRUCache","Typebars","compile","template","children","key","value","Object","entries","fromObject","helpers","hbs","compilationCache","fromLiteral","ast","getCachedAst","options","fromTemplate","analyze","inputSchema","identifierSchemas","keys","valid","diagnostics","outputSchema","validate","analysis","isValidSyntax","values","every","v","execute","data","result","schema","identifierData","analyzeAndExecute","undefined","registerHelper","name","definition","set","fn","clear","unregisterHelper","delete","hasHelper","has","clearCaches","astCache","get","Map","create","astCacheSize","compilationCacheSize","register","helper"],"mappings":"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"}

package/dist/esm/types.d.ts

@@ -0,0 +1,334 @@
+import type { JSONSchema7 } from "json-schema";
+import type { FromSchema, JSONSchema } from "json-schema-to-ts";
+/**
+ * Object where each property is a `TemplateInput` (recursive).
+ *
+ * Allows passing an entire structure as a template:
+ * ```
+ * engine.analyze({
+ *   userName: "{{name}}",
+ *   userAge: "{{age}}",
+ *   nested: { x: "{{foo}}" },
+ * }, inputSchema);
+ * ```
+ */
+export interface TemplateInputObject {
+    [key: string]: TemplateInput;
+}
+/**
+ * Input type accepted by the template engine.
+ *
+ * - `string`              → standard Handlebars template (parsed and executed)
+ * - `number`              → numeric literal (passthrough)
+ * - `boolean`             → boolean literal (passthrough)
+ * - `null`                → null literal (passthrough)
+ * - `TemplateInputObject` → object where each property is a `TemplateInput`
+ */
+export type TemplateInput = string | number | boolean | null | TemplateInputObject;
+/**
+ * Checks whether a value is a non-string primitive literal (number, boolean, null).
+ * These values are treated as passthrough by the engine.
+ *
+ * Note: objects (`TemplateInputObject`) are NOT literals.
+ */
+export declare function isLiteralInput(input: TemplateInput): input is number | boolean | null;
+/**
+ * Checks whether a value is a template object (`TemplateInputObject`).
+ * Template objects are processed recursively by the engine:
+ * each property is analyzed/executed individually.
+ */
+export declare function isObjectInput(input: TemplateInput): input is TemplateInputObject;
+/**
+ * Infers the JSON Schema of a non-string primitive value.
+ *
+ * @param value - The primitive value (number, boolean, null)
+ * @returns The corresponding JSON Schema
+ *
+ * @example
+ * ```
+ * inferPrimitiveSchema(42)    // → { type: "number" }
+ * inferPrimitiveSchema(true)  // → { type: "boolean" }
+ * inferPrimitiveSchema(null)  // → { type: "null" }
+ * ```
+ */
+export declare function inferPrimitiveSchema(value: number | boolean | null): JSONSchema7;
+export type DiagnosticCode = 
+/** The referenced property does not exist in the context schema */
+"UNKNOWN_PROPERTY"
+/** Type mismatch (e.g. #each on a non-array) */
+ | "TYPE_MISMATCH"
+/** A block helper is used without a required argument */
+ | "MISSING_ARGUMENT"
+/** Unknown block helper (neither built-in nor registered) */
+ | "UNKNOWN_HELPER"
+/** The expression cannot be statically analyzed */
+ | "UNANALYZABLE"
+/** The {{key:N}} syntax is used but no identifierSchemas were provided */
+ | "MISSING_IDENTIFIER_SCHEMAS"
+/** The identifier N does not exist in the provided identifierSchemas */
+ | "UNKNOWN_IDENTIFIER"
+/** The property does not exist in the identifier's schema */
+ | "IDENTIFIER_PROPERTY_NOT_FOUND"
+/** Syntax error in the template */
+ | "PARSE_ERROR";
+export interface DiagnosticDetails {
+    /** Path of the expression that caused the error (e.g. `"user.name.foo"`) */
+    path?: string;
+    /** Name of the helper involved (for helper-related errors) */
+    helperName?: string;
+    /** What was expected (e.g. `"array"`, `"property to exist"`) */
+    expected?: string;
+    /** What was found (e.g. `"string"`, `"undefined"`) */
+    actual?: string;
+    /** Available properties in the current schema (for suggestions) */
+    availableProperties?: string[];
+    /** Template identifier number (for `{{key:N}}` errors) */
+    identifier?: number;
+}
+/** Diagnostic produced by the static analyzer */
+export interface TemplateDiagnostic {
+    /** "error" blocks execution, "warning" is informational */
+    severity: "error" | "warning";
+    /** Machine-readable code identifying the error type */
+    code: DiagnosticCode;
+    /** Human-readable message describing the problem */
+    message: string;
+    /** Position in the template source (if available from the AST) */
+    loc?: {
+        start: {
+            line: number;
+            column: number;
+        };
+        end: {
+            line: number;
+            column: number;
+        };
+    };
+    /** Fragment of the template source around the error */
+    source?: string;
+    /** Structured information for debugging and frontend display */
+    details?: DiagnosticDetails;
+}
+/** Complete result of the static analysis */
+export interface AnalysisResult {
+    /** true if no errors (warnings are tolerated) */
+    valid: boolean;
+    /** List of diagnostics (errors + warnings) */
+    diagnostics: TemplateDiagnostic[];
+    /** JSON Schema describing the template's return type */
+    outputSchema: JSONSchema7;
+}
+/** Lightweight validation result (without output type inference) */
+export interface ValidationResult {
+    /** true if no errors (warnings are tolerated) */
+    valid: boolean;
+    /** List of diagnostics (errors + warnings) */
+    diagnostics: TemplateDiagnostic[];
+}
+export interface TemplateEngineOptions {
+    /**
+     * Capacity of the parsed AST cache. Each parsed template is cached
+     * to avoid costly re-parsing on repeated calls.
+     * @default 256
+     */
+    astCacheSize?: number;
+    /**
+     * Capacity of the compiled Handlebars template cache.
+     * @default 256
+     */
+    compilationCacheSize?: number;
+    /**
+     * Custom helpers to register during engine construction.
+     *
+     * Each entry describes a helper with its name, implementation,
+     * expected parameters, and return type.
+     *
+     * @example
+     * ```
+     * const engine = new Typebars({
+     *   helpers: [
+     *     {
+     *       name: "uppercase",
+     *       description: "Converts a string to uppercase",
+     *       fn: (value: string) => String(value).toUpperCase(),
+     *       params: [
+     *         { name: "value", type: { type: "string" }, description: "The string to convert" },
+     *       ],
+     *       returnType: { type: "string" },
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    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 AnalyzeAndExecuteOptions {
+    /** 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>>;
+}
+/** Describes a parameter expected by a helper */
+export interface HelperParam {
+    /** Parameter name (for documentation / introspection) */
+    name: string;
+    /**
+     * JSON Schema describing the expected type for this parameter.
+     * Used for documentation and static validation.
+     */
+    type?: JSONSchema7;
+    /** Human-readable description of the parameter */
+    description?: string;
+    /**
+     * Whether the parameter is optional.
+     * @default false
+     */
+    optional?: boolean;
+}
+/**
+ * Definition of a helper registerable via `registerHelper()`.
+ *
+ * Contains the runtime implementation and typing metadata
+ * for static analysis.
+ */
+export interface HelperDefinition {
+    /**
+     * Runtime implementation of the helper — will be registered with Handlebars.
+     *
+     * For an inline helper `{{uppercase name}}`:
+     *   `(value: string) => string`
+     *
+     * For a block helper `{{#repeat count}}...{{/repeat}}`:
+     *   `function(this: any, count: number, options: Handlebars.HelperOptions) { ... }`
+     */
+    fn: (...args: any[]) => unknown;
+    /**
+     * Parameters expected by the helper (for documentation and analysis).
+     *
+     * @example
+     * ```
+     * params: [
+     *   { name: "value", type: { type: "number" }, description: "The value to round" },
+     *   { name: "precision", type: { type: "number" }, description: "Decimal places", optional: true },
+     * ]
+     * ```
+     */
+    params?: HelperParam[];
+    /**
+     * JSON Schema describing the helper's return type for static analysis.
+     * @default { type: "string" }
+     */
+    returnType?: JSONSchema7;
+    /** Human-readable description of the helper */
+    description?: string;
+}
+/**
+ * Full helper configuration for registration via the `Typebars({ helpers: [...] })`
+ * constructor options.
+ *
+ * Extends `HelperDefinition` with a required `name`.
+ *
+ * @example
+ * ```
+ * const config: HelperConfig = {
+ *   name: "round",
+ *   description: "Rounds a number to a given precision",
+ *   fn: (value: number, precision?: number) => { ... },
+ *   params: [
+ *     { name: "value", type: { type: "number" } },
+ *     { name: "precision", type: { type: "number" }, optional: true },
+ *   ],
+ *   returnType: { type: "number" },
+ * };
+ * ```
+ */
+export interface HelperConfig extends HelperDefinition {
+    /** Name of the helper as used in templates (e.g. `"uppercase"`) */
+    name: string;
+}
+/**
+ * Param definition used for type inference.
+ * Accepts `JSONSchema` from `json-schema-to-ts` to allow `FromSchema`
+ * to resolve literal types.
+ */
+type TypedHelperParam = {
+    readonly name: string;
+    readonly type?: JSONSchema;
+    readonly description?: string;
+    readonly optional?: boolean;
+};
+/**
+ * Infers the TypeScript type of a single parameter from its JSON Schema.
+ * - If `optional: true`, the resolved type is unioned with `undefined`.
+ * - If `type` is not provided, the type is `unknown`.
+ */
+type InferParamType<P> = P extends {
+    readonly type: infer S extends JSONSchema;
+    readonly optional: true;
+} ? FromSchema<S> | undefined : P extends {
+    readonly type: infer S extends JSONSchema;
+} ? FromSchema<S> : unknown;
+/**
+ * Maps a tuple of `TypedHelperParam` to a tuple of inferred TypeScript types,
+ * usable as the `fn` signature.
+ *
+ * @example
+ * ```
+ * type Args = InferArgs<readonly [
+ *   { name: "a"; type: { type: "string" } },
+ *   { name: "b"; type: { type: "number" }; optional: true },
+ * ]>;
+ * // => [string, number | undefined]
+ * ```
+ */
+type InferArgs<P extends readonly TypedHelperParam[]> = {
+    [K in keyof P]: InferParamType<P[K]>;
+};
+/**
+ * Helper configuration with generic parameter inference.
+ * Used exclusively by `defineHelper()`.
+ */
+interface TypedHelperConfig<P extends readonly TypedHelperParam[]> {
+    name: string;
+    description?: string;
+    params: P;
+    fn: (...args: InferArgs<P>) => unknown;
+    returnType?: JSONSchema;
+}
+/**
+ * Creates a `HelperConfig` with automatic type inference for `fn` arguments
+ * based on the JSON Schemas declared in `params`.
+ *
+ * The generic parameter `const P` preserves schema literal types
+ * (equivalent of `as const`), enabling `FromSchema` to resolve the
+ * corresponding TypeScript types.
+ *
+ * @example
+ * ```
+ * const helper = defineHelper({
+ *   name: "concat",
+ *   description: "Concatenates two strings",
+ *   params: [
+ *     { name: "a", type: { type: "string" }, description: "First string" },
+ *     { name: "b", type: { type: "string" }, description: "Second string" },
+ *     { name: "sep", type: { type: "string" }, description: "Separator", optional: true },
+ *   ],
+ *   fn: (a, b, sep) => {
+ *     // a: string, b: string, sep: string | undefined
+ *     const separator = sep ?? "";
+ *     return `${a}${separator}${b}`;
+ *   },
+ *   returnType: { type: "string" },
+ * });
+ * ```
+ */
+export declare function defineHelper<const P extends readonly TypedHelperParam[]>(config: TypedHelperConfig<P>): HelperConfig;
+export {};

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export function isLiteralInput(input){return input===null||typeof input!=="string"&&typeof input!=="object"}export function isObjectInput(input){return input!==null&&typeof input==="object"}export function inferPrimitiveSchema(value){if(value===null)return{type:"null"};if(typeof value==="boolean")return{type:"boolean"};if(typeof value==="number"){return Number.isInteger(value)?{type:"integer"}:{type:"number"}}value;return{type:"null"}}export function defineHelper(config){return config}
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +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 * 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 * - `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| TemplateInputObject;\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`) 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 object (`TemplateInputObject`).\n * Template objects are processed recursively by the engine:\n * each property is analyzed/executed individually.\n */\nexport function isObjectInput(\n\tinput: TemplateInput,\n): input is TemplateInputObject {\n\treturn input !== null && typeof input === \"object\";\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\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}\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}\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":["isLiteralInput","input","isObjectInput","inferPrimitiveSchema","value","type","Number","isInteger","defineHelper","config"],"mappings":"AA8CA,OAAO,SAASA,eACfC,KAAoB,EAEpB,OACCA,QAAU,MAAS,OAAOA,QAAU,UAAY,OAAOA,QAAU,QAEnE,CAOA,OAAO,SAASC,cACfD,KAAoB,EAEpB,OAAOA,QAAU,MAAQ,OAAOA,QAAU,QAC3C,CAeA,OAAO,SAASE,qBACfC,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,CA6UA,OAAO,SAASG,aACfC,MAA4B,EAE5B,OAAOA,MACR"}