typebars 1.0.0

package/dist/errors.d.ts

@@ -0,0 +1,93 @@
+import type { TemplateDiagnostic } from "./types.ts";
+export declare class TemplateError extends Error {
+    constructor(message: string);
+    /**
+     * Serializes the error into a JSON-compatible object, suitable for sending
+     * to a frontend or a structured logging system.
+     */
+    toJSON(): Record<string, unknown>;
+}
+export declare class TemplateParseError extends TemplateError {
+    /** Approximate position of the error in the source */
+    readonly loc?: {
+        line: number;
+        column: number;
+    } | undefined;
+    /** Fragment of the template source around the error */
+    readonly source?: string | undefined;
+    constructor(message: string, 
+    /** Approximate position of the error in the source */
+    loc?: {
+        line: number;
+        column: number;
+    } | undefined, 
+    /** Fragment of the template source around the error */
+    source?: string | undefined);
+    toJSON(): Record<string, unknown>;
+}
+export declare class TemplateAnalysisError extends TemplateError {
+    /** Full list of diagnostics (errors + warnings) */
+    readonly diagnostics: TemplateDiagnostic[];
+    /** Only diagnostics with "error" severity */
+    readonly errors: TemplateDiagnostic[];
+    /** Only diagnostics with "warning" severity */
+    readonly warnings: TemplateDiagnostic[];
+    /** Total number of errors */
+    readonly errorCount: number;
+    /** Total number of warnings */
+    readonly warningCount: number;
+    constructor(diagnostics: TemplateDiagnostic[]);
+    /**
+     * Serializes the analysis error into a JSON-compatible object.
+     *
+     * Designed for direct use in API responses:
+     * ```
+     * res.status(400).json(error.toJSON());
+     * ```
+     *
+     * Returned structure:
+     * ```
+     * {
+     *   name: "TemplateAnalysisError",
+     *   message: "Static analysis failed with 2 error(s): ...",
+     *   errorCount: 2,
+     *   warningCount: 0,
+     *   diagnostics: [
+     *     {
+     *       severity: "error",
+     *       code: "UNKNOWN_PROPERTY",
+     *       message: "Property \"foo\" does not exist...",
+     *       loc: { start: { line: 1, column: 0 }, end: { line: 1, column: 7 } },
+     *       source: "{{foo}}",
+     *       details: { path: "foo", availableProperties: ["name", "age"] }
+     *     }
+     *   ]
+     * }
+     * ```
+     */
+    toJSON(): Record<string, unknown>;
+}
+export declare class TemplateRuntimeError extends TemplateError {
+    constructor(message: string);
+}
+/**
+ * Creates a structured diagnostic message for a missing property.
+ * Used by the analyzer to produce enriched error messages with suggestions.
+ */
+export declare function createPropertyNotFoundMessage(path: string, availableProperties: string[]): string;
+/**
+ * Creates a message for a type mismatch on a block helper.
+ */
+export declare function createTypeMismatchMessage(helperName: string, expected: string, actual: string): string;
+/**
+ * Creates a message for a missing argument on a block helper.
+ */
+export declare function createMissingArgumentMessage(helperName: string): string;
+/**
+ * Creates a message for an unknown block helper.
+ */
+export declare function createUnknownHelperMessage(helperName: string): string;
+/**
+ * Creates a message for an expression that cannot be statically analyzed.
+ */
+export declare function createUnanalyzableMessage(nodeType: string): string;

package/dist/errors.js

@@ -0,0 +1,4 @@
+import{A as b,B as c,C as d,D as e,E as f,F as g,G as h,H as i,z as a}from"./chunk-ybh51hbe.js";export{h as createUnknownHelperMessage,i as createUnanalyzableMessage,f as createTypeMismatchMessage,e as createPropertyNotFoundMessage,g as createMissingArgumentMessage,d as TemplateRuntimeError,b as TemplateParseError,a as TemplateError,c as TemplateAnalysisError};
+
+//# debugId=043280437018AA4064756E2164756E21
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "043280437018AA4064756E2164756E21",
+  "names": []
+}

package/dist/executor.d.ts

@@ -0,0 +1,55 @@
+import Handlebars from "handlebars";
+import type { TemplateInput } from "./types.ts";
+import { LRUCache } from "./utils.ts";
+/** Optional context for execution (used by Typebars/CompiledTemplate) */
+export interface ExecutorContext {
+    /** Data by identifier `{ [id]: { key: value } }` */
+    identifierData?: Record<number, Record<string, unknown>>;
+    /** Pre-compiled Handlebars template (for CompiledTemplate) */
+    compiledTemplate?: HandlebarsTemplateDelegate;
+    /** Isolated Handlebars environment (for custom helpers) */
+    hbs?: typeof Handlebars;
+    /** Compilation cache shared by the engine */
+    compilationCache?: LRUCache<string, HandlebarsTemplateDelegate>;
+}
+/**
+ * Executes a template with the provided data and returns the result.
+ *
+ * The return type depends on the template structure:
+ * - Single expression `{{expr}}` → raw value (any)
+ * - Single block → coerced value (number, boolean, null, or string)
+ * - Mixed template → `string`
+ *
+ * @param template       - The template string
+ * @param data           - The main context data
+ * @param identifierData - (optional) Data by identifier `{ [id]: { key: value } }`
+ */
+export declare function execute(template: TemplateInput, data: Record<string, unknown>, identifierData?: Record<number, Record<string, unknown>>): unknown;
+/**
+ * Executes a template from an already-parsed AST.
+ *
+ * This function is the core of execution. It is used by:
+ * - `execute()` (backward-compatible wrapper)
+ * - `CompiledTemplate.execute()` (with pre-parsed AST and cache)
+ * - `Typebars.execute()` (with cache and helpers)
+ *
+ * @param ast       - The already-parsed Handlebars AST
+ * @param template  - The template source (for Handlebars compilation if needed)
+ * @param data      - The main context data
+ * @param ctx       - Optional execution context
+ */
+export declare function executeFromAst(ast: hbs.AST.Program, template: string, data: Record<string, unknown>, ctx?: ExecutorContext): unknown;
+/**
+ * Navigates through a data object by following a path of segments.
+ *
+ * @param data     - The data object
+ * @param segments - The path segments (e.g. `["user", "address", "city"]`)
+ * @returns The value at the end of the path, or `undefined` if an
+ *          intermediate segment is null/undefined
+ */
+export declare function resolveDataPath(data: unknown, segments: string[]): unknown;
+/**
+ * Clears the global Handlebars compilation cache.
+ * Useful for tests or to free memory.
+ */
+export declare function clearCompilationCache(): void;

package/dist/executor.js

@@ -0,0 +1,4 @@
+import{f as a,g as b,h as c,i as d}from"./chunk-qpzzr2rd.js";import"./chunk-6955jpr7.js";import"./chunk-1gm6cf0e.js";import"./chunk-ybh51hbe.js";import"./chunk-4zv02svp.js";export{c as resolveDataPath,b as executeFromAst,a as execute,d as clearCompilationCache};
+
+//# debugId=E439EBF232D2886264756E2164756E21
+//# sourceMappingURL=executor.js.map

package/dist/executor.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "E439EBF232D2886264756E2164756E21",
+  "names": []
+}

package/dist/helpers/helper-factory.d.ts

@@ -0,0 +1,56 @@
+import type { HelperDefinition } from "../types.ts";
+/** Minimal registration interface — avoids tight coupling with Typebars */
+export interface HelperRegistry {
+    registerHelper(name: string, definition: HelperDefinition): unknown;
+    unregisterHelper(name: string): unknown;
+}
+export declare abstract class HelperFactory {
+    private _definitions;
+    private _helperNames;
+    private _helperNamesSet;
+    /**
+     * Populates the `defs` map with all helper definitions.
+     *
+     * Subclasses implement this method to register their helpers:
+     * ```
+     * protected buildDefinitions(defs: Map<string, HelperDefinition>): void {
+     *   defs.set("myHelper", {
+     *     fn: (a: unknown) => String(a).toUpperCase(),
+     *     params: [{ name: "a", type: { type: "string" } }],
+     *     returnType: { type: "string" },
+     *     description: "Converts to uppercase",
+     *   });
+     * }
+     * ```
+     *
+     * @param defs - The map to populate with `[name, HelperDefinition]` entries
+     */
+    protected abstract buildDefinitions(defs: Map<string, HelperDefinition>): void;
+    /**
+     * Returns all definitions as a `Map<name, HelperDefinition>`.
+     * The map is lazily built and cached on first access.
+     */
+    getDefinitions(): Map<string, HelperDefinition>;
+    /**
+     * Returns the list of all helper names provided by this factory.
+     */
+    getHelperNames(): readonly string[];
+    /**
+     * Checks whether a helper name belongs to this factory.
+     *
+     * @param name - The helper name to check
+     */
+    isHelper(name: string): boolean;
+    /**
+     * Registers all helpers from this factory on the given registry.
+     *
+     * @param registry - The engine or target registry
+     */
+    register(registry: HelperRegistry): void;
+    /**
+     * Removes all helpers from this factory from the given registry.
+     *
+     * @param registry - The engine or target registry
+     */
+    unregister(registry: HelperRegistry): void;
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export { HelperFactory, type HelperRegistry } from "./helper-factory.ts";
+export { LogicalHelpers } from "./logical-helpers.ts";
+export { MathHelpers } from "./math-helpers.ts";
+export { toNumber } from "./utils.ts";

package/dist/helpers/logical-helpers.d.ts

@@ -0,0 +1,15 @@
+import type { HelperDefinition } from "../types.ts";
+import { HelperFactory } from "./helper-factory.ts";
+export declare class LogicalHelpers extends HelperFactory {
+    protected buildDefinitions(defs: Map<string, HelperDefinition>): void;
+    /** Registers eq, ne / neq */
+    private registerEquality;
+    /** Registers lt, lte / le, gt, gte / ge */
+    private registerComparison;
+    /** Registers not, and, or */
+    private registerLogicalOperators;
+    /** Registers contains, in */
+    private registerCollectionHelpers;
+    /** Registers the generic `compare` helper with operator as a parameter */
+    private registerGenericCompare;
+}

package/dist/helpers/math-helpers.d.ts

@@ -0,0 +1,13 @@
+import type { HelperDefinition } from "../types.ts";
+import { HelperFactory } from "./helper-factory.ts";
+export declare class MathHelpers extends HelperFactory {
+    protected buildDefinitions(defs: Map<string, HelperDefinition>): void;
+    /** Registers add, subtract/sub, multiply/mul, divide/div, modulo/mod, pow */
+    private registerBinaryOperators;
+    /** Registers abs, ceil, floor, round, sqrt */
+    private registerUnaryFunctions;
+    /** Registers min and max */
+    private registerMinMax;
+    /** Registers the generic `math` helper with operator as a parameter */
+    private registerGenericMath;
+}

package/dist/helpers/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Converts an unknown value to a number.
+ *
+ * Conversion rules:
+ * - `number`  → returned as-is
+ * - `string`  → parsed via `Number()`; returns `fallback` if result is `NaN`
+ * - `boolean` → `true` → `1`, `false` → `0`
+ * - anything else → `fallback`
+ *
+ * The `fallback` parameter lets each consumer choose the right semantics:
+ * - **Math helpers** pass `0` so that invalid inputs silently become zero
+ *   (e.g. `add("abc", 5)` → `5`).
+ * - **Logical helpers** pass `NaN` (the default) so that invalid comparisons
+ *   evaluate to `false` (e.g. `lt("abc", 5)` → `false`).
+ *
+ * @param value    - The value to convert
+ * @param fallback - Value returned when conversion fails (default: `NaN`)
+ */
+export declare function toNumber(value: unknown, fallback?: number): number;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Typebars } from "./typebars.ts";
+export { defineHelper } from "./types.ts";

package/dist/index.js

@@ -0,0 +1,4 @@
+import{a as r}from"./chunk-7j6q1e3z.js";import"./chunk-kznb0bev.js";import"./chunk-1qwj7pjc.js";import"./chunk-qpzzr2rd.js";import{m as e}from"./chunk-6955jpr7.js";import"./chunk-1gm6cf0e.js";import"./chunk-ybh51hbe.js";import"./chunk-8g0d6h85.js";import"./chunk-4zv02svp.js";export{e as defineHelper,r as Typebars};
+
+//# debugId=55D58DC910FCA0B664756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "55D58DC910FCA0B664756E2164756E21",
+  "names": []
+}

package/dist/parser.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Parses a template string and returns the Handlebars AST.
+ *
+ * This function does not cache results — caching is managed at the
+ * `Typebars` instance level via its own configurable LRU cache.
+ *
+ * @param template - The template string to parse (e.g. `"Hello {{name}}"`)
+ * @returns The root AST node (`hbs.AST.Program`)
+ * @throws {TemplateParseError} if the template syntax is invalid
+ */
+export declare function parse(template: string): hbs.AST.Program;
+/**
+ * Determines whether the AST represents a template consisting of a single
+ * expression `{{expression}}` with no text content around it.
+ *
+ * This matters for return type inference:
+ * - Template `{{value}}`       → returns the raw type of `value` (number, object…)
+ * - Template `Hello {{name}}`  → always returns `string` (concatenation)
+ *
+ * @param ast - The parsed AST of the template
+ * @returns `true` if the template is a single expression
+ */
+export declare function isSingleExpression(ast: hbs.AST.Program): boolean;
+/**
+ * Extracts the path segments from a Handlebars `PathExpression`.
+ *
+ * Handlebars decomposes `user.address.city` into `{ parts: ["user", "address", "city"] }`.
+ * This function safely extracts those segments.
+ *
+ * @param expr - The expression to extract the path from
+ * @returns The path segments, or an empty array if the expression is not
+ *          a `PathExpression`
+ */
+export declare function extractPathSegments(expr: hbs.AST.Expression): string[];
+/**
+ * Checks whether an AST expression is a `PathExpression` pointing to `this`
+ * (used inside `{{#each}}` blocks).
+ */
+export declare function isThisExpression(expr: hbs.AST.Expression): boolean;
+/**
+ * Returns the semantically significant statements of a Program by
+ * filtering out `ContentStatement` nodes that contain only whitespace.
+ */
+export declare function getEffectiveBody(program: hbs.AST.Program): hbs.AST.Statement[];
+/**
+ * Determines whether a Program effectively consists of a single
+ * `BlockStatement` (ignoring surrounding whitespace).
+ *
+ * Recognized examples:
+ * ```
+ * {{#if x}}...{{/if}}
+ *
+ *   {{#each items}}...{{/each}}
+ * ```
+ *
+ * @returns The single `BlockStatement`, or `null` if the program contains
+ *          other significant nodes.
+ */
+export declare function getEffectivelySingleBlock(program: hbs.AST.Program): hbs.AST.BlockStatement | null;
+/**
+ * Determines whether a Program effectively consists of a single
+ * `MustacheStatement` (ignoring surrounding whitespace).
+ *
+ * Example: `  {{age}}  ` → true
+ */
+export declare function getEffectivelySingleExpression(program: hbs.AST.Program): hbs.AST.MustacheStatement | null;
+/**
+ * Determines whether an AST can be executed via the fast-path (direct
+ * concatenation without going through `Handlebars.compile()`).
+ *
+ * The fast-path is possible when the template only contains:
+ * - `ContentStatement` nodes (static text)
+ * - Simple `MustacheStatement` nodes (no params, no hash)
+ *
+ * This excludes:
+ * - Block helpers (`{{#if}}`, `{{#each}}`, etc.)
+ * - Inline helpers (`{{uppercase name}}`)
+ * - Sub-expressions
+ *
+ * @param ast - The parsed AST of the template
+ * @returns `true` if the template can use the fast-path
+ */
+export declare function canUseFastPath(ast: hbs.AST.Program): boolean;
+/**
+ * Attempts to detect the type of a raw text literal.
+ *
+ * @param text - The trimmed text from a ContentStatement or group of ContentStatements
+ * @returns The detected JSON Schema type, or `null` if it's free-form text (string).
+ */
+export declare function detectLiteralType(text: string): "number" | "boolean" | "null" | null;
+/**
+ * Coerces a raw string from Handlebars rendering to its actual type
+ * if it represents a literal (number, boolean, null).
+ * Returns the raw (untrimmed) string otherwise.
+ */
+export declare function coerceLiteral(raw: string): unknown;
+/** Result of parsing a path segment with a potential identifier */
+export interface ParsedIdentifier {
+    /** The variable name, without the `:N` suffix */
+    key: string;
+    /** The numeric identifier, or `null` if absent */
+    identifier: number | null;
+}
+/**
+ * Parses an individual path segment to extract the key and optional identifier.
+ *
+ * @param segment - A raw path segment (e.g. `"meetingId:1"` or `"meetingId"`)
+ * @returns An object `{ key, identifier }`
+ *
+ * @example
+ * ```
+ * parseIdentifier("meetingId:1")  // → { key: "meetingId", identifier: 1 }
+ * parseIdentifier("meetingId")    // → { key: "meetingId", identifier: null }
+ * parseIdentifier("meetingId:0")  // → { key: "meetingId", identifier: 0 }
+ * ```
+ */
+export declare function parseIdentifier(segment: string): ParsedIdentifier;
+/** Result of extracting the identifier from a complete expression */
+export interface ExpressionIdentifier {
+    /** Cleaned path segments (without the `:N` suffix on the last one) */
+    cleanSegments: string[];
+    /** The numeric identifier extracted from the last segment, or `null` */
+    identifier: number | null;
+}
+/**
+ * Extracts the identifier from a complete expression (array of segments).
+ *
+ * The identifier is always on the **last** segment of the path, because
+ * Handlebars splits on `.` before the `:`.
+ *
+ * @param segments - The raw path segments (e.g. `["user", "name:1"]`)
+ * @returns An object `{ cleanSegments, identifier }`
+ *
+ * @example
+ * ```
+ * extractExpressionIdentifier(["meetingId:1"])
+ * // → { cleanSegments: ["meetingId"], identifier: 1 }
+ *
+ * extractExpressionIdentifier(["user", "name:1"])
+ * // → { cleanSegments: ["user", "name"], identifier: 1 }
+ *
+ * extractExpressionIdentifier(["meetingId"])
+ * // → { cleanSegments: ["meetingId"], identifier: null }
+ * ```
+ */
+export declare function extractExpressionIdentifier(segments: string[]): ExpressionIdentifier;

package/dist/parser.js

@@ -0,0 +1,4 @@
+import{n as a,o as b,p as c,q as d,r as e,s as f,t as g,u as h,v as i,w as j,x as k,y as l}from"./chunk-1gm6cf0e.js";import"./chunk-ybh51hbe.js";export{k as parseIdentifier,a as parse,d as isThisExpression,b as isSingleExpression,g as getEffectivelySingleExpression,f as getEffectivelySingleBlock,e as getEffectiveBody,c as extractPathSegments,l as extractExpressionIdentifier,i as detectLiteralType,j as coerceLiteral,h as canUseFastPath};
+
+//# debugId=238977E59328291964756E2164756E21
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "238977E59328291964756E2164756E21",
+  "names": []
+}

package/dist/schema-resolver.d.ts

@@ -0,0 +1,50 @@
+import type { JSONSchema7 } from "json-schema";
+/**
+ * Recursively resolves `$ref` in a schema using the root schema as the
+ * source of definitions.
+ */
+export declare function resolveRef(schema: JSONSchema7, root: JSONSchema7): JSONSchema7;
+/**
+ * Resolves a full path (e.g. ["user", "address", "city"]) within a JSON
+ * Schema and returns the corresponding sub-schema.
+ *
+ * @param schema - The root schema describing the template context
+ * @param path   - Array of segments (property names)
+ * @returns The sub-schema at the end of the path, or `undefined` if the path
+ *          cannot be resolved.
+ *
+ * @example
+ * ```
+ * const schema = {
+ *   type: "object",
+ *   properties: {
+ *     user: {
+ *       type: "object",
+ *       properties: {
+ *         name: { type: "string" }
+ *       }
+ *     }
+ *   }
+ * };
+ * resolveSchemaPath(schema, ["user", "name"]);
+ * // → { type: "string" }
+ * ```
+ */
+export declare function resolveSchemaPath(schema: JSONSchema7, path: string[]): JSONSchema7 | undefined;
+/**
+ * Resolves the item schema of an array.
+ * If the schema is not of type `array` or has no `items`, returns `undefined`.
+ *
+ * @param schema - The array schema
+ * @param root   - The root schema (for resolving $refs)
+ */
+export declare function resolveArrayItems(schema: JSONSchema7, root: JSONSchema7): JSONSchema7 | undefined;
+/**
+ * Simplifies an output schema to avoid unnecessarily complex constructs
+ * (e.g. `oneOf` with a single element, duplicates, etc.).
+ *
+ * Uses `deepEqual` for deduplication — more robust and performant than
+ * `JSON.stringify` (independent of key order, no intermediate string
+ * allocations).
+ */
+export declare function simplifySchema(schema: JSONSchema7): JSONSchema7;

package/dist/schema-resolver.js

@@ -0,0 +1,4 @@
+import{I as a,J as b,K as c,L as d}from"./chunk-8g0d6h85.js";import"./chunk-4zv02svp.js";export{d as simplifySchema,b as resolveSchemaPath,a as resolveRef,c as resolveArrayItems};
+
+//# debugId=0ED578ADCD4302EE64756E2164756E21
+//# sourceMappingURL=schema-resolver.js.map

package/dist/schema-resolver.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "0ED578ADCD4302EE64756E2164756E21",
+  "names": []
+}