typebars 1.0.0

package/dist/typebars.d.ts

@@ -0,0 +1,130 @@
+import type { JSONSchema7 } from "json-schema";
+import { CompiledTemplate } from "./compiled-template.ts";
+import type { AnalysisResult, AnalyzeAndExecuteOptions, ExecuteOptions, HelperDefinition, TemplateEngineOptions, TemplateInput, ValidationResult } from "./types.ts";
+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/typebars.js

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

package/dist/typebars.js.map

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

package/dist/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/types.js

@@ -0,0 +1,4 @@
+import{j as a,k as b,l as c,m as d}from"./chunk-6955jpr7.js";export{b as isObjectInput,a as isLiteralInput,c as inferPrimitiveSchema,d as defineHelper};
+
+//# debugId=9DCD2B51206A921264756E2164756E21
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/utils.d.ts

@@ -0,0 +1,113 @@
+import type { JSONSchema7 } from "json-schema";
+import type { AnalysisResult } from "./types.ts";
+/**
+ * Recursively compares two JSON-compatible values.
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @returns `true` if the two values are structurally identical
+ *
+ * @example
+ * ```
+ * deepEqual({ a: 1, b: 2 }, { b: 2, a: 1 }) // → true
+ * deepEqual([1, 2], [1, 2])                   // → true
+ * deepEqual({ a: 1 }, { a: 2 })               // → false
+ * ```
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Simple fixed-capacity LRU cache.
+ *
+ * @example
+ * ```
+ * const cache = new LRUCache<string, number>(2);
+ * cache.set("a", 1);
+ * cache.set("b", 2);
+ * cache.get("a");      // → 1 (marks "a" as recently used)
+ * cache.set("c", 3);   // evicts "b" (least recently used)
+ * cache.get("b");      // → undefined
+ * ```
+ */
+export declare class LRUCache<K, V> {
+    private readonly capacity;
+    private readonly cache;
+    constructor(capacity: number);
+    /**
+     * Retrieves a value from the cache. Returns `undefined` if absent.
+     * Marks the entry as recently used.
+     */
+    get(key: K): V | undefined;
+    /**
+     * Inserts or updates a value in the cache.
+     * If the cache is full, evicts the least recently used entry.
+     */
+    set(key: K, value: V): void;
+    /**
+     * Checks whether a key exists in the cache (without affecting LRU order).
+     */
+    has(key: K): boolean;
+    /**
+     * Removes an entry from the cache.
+     * @returns `true` if the entry existed and was removed
+     */
+    delete(key: K): boolean;
+    /** Clears the entire cache. */
+    clear(): void;
+    /** Number of entries currently in the cache. */
+    get size(): number;
+}
+/**
+ * Extracts a template fragment around a given position.
+ *
+ * @param template - The full template source
+ * @param loc      - The position (line/column, 1-based) of the error
+ * @returns The corresponding code fragment (trimmed)
+ */
+export declare function extractSourceSnippet(template: string, loc: {
+    start: {
+        line: number;
+        column: number;
+    };
+    end: {
+        line: number;
+        column: number;
+    };
+}): string;
+/**
+ * Lists the declared property names in a JSON Schema.
+ * Returns an empty array if the schema has no `properties`.
+ */
+export declare function getSchemaPropertyNames(schema: JSONSchema7): string[];
+/**
+ * Aggregates analysis results from a set of named entries into a single
+ * `AnalysisResult` with an object-typed `outputSchema`.
+ *
+ * @param keys         - The keys of the object to analyze
+ * @param analyzeEntry - Callback that analyzes an entry by its key
+ * @returns An aggregated `AnalysisResult`
+ *
+ * @example
+ * ```
+ * aggregateObjectAnalysis(
+ *   Object.keys(template),
+ *   (key) => analyze(template[key], inputSchema),
+ * );
+ * ```
+ */
+export declare function aggregateObjectAnalysis(keys: string[], analyzeEntry: (key: string) => AnalysisResult): AnalysisResult;
+/**
+ * Aggregates both analysis **and** execution results from a set of named
+ * entries. Returns the aggregated `AnalysisResult` and the object of
+ * executed values (or `undefined` if at least one entry is invalid).
+ *
+ * @param keys         - The keys of the object
+ * @param processEntry - Callback that analyzes and executes an entry by its key
+ * @returns Aggregated `{ analysis, value }`
+ */
+export declare function aggregateObjectAnalysisAndExecution(keys: string[], processEntry: (key: string) => {
+    analysis: AnalysisResult;
+    value: unknown;
+}): {
+    analysis: AnalysisResult;
+    value: unknown;
+};

package/dist/utils.js

@@ -0,0 +1,4 @@
+import{M as a,N as b,O as c,P as d,Q as e,R as f}from"./chunk-4zv02svp.js";export{d as getSchemaPropertyNames,c as extractSourceSnippet,a as deepEqual,f as aggregateObjectAnalysisAndExecution,e as aggregateObjectAnalysis,b as LRUCache};
+
+//# debugId=F71EB52AAB98830164756E2164756E21
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "typebars",
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Typebars is a type-safe handlebars based template engine for generating object or content with static type checking",
+  "author": {
+    "email": "arthurtinseau@live.fr",
+    "url": "https://github.com/atinseau/typebars",
+    "name": "atinseau"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "lefthook install",
+    "build:bun": "bun build src/*.ts --outdir ./dist --production --minify --root src --sourcemap --splitting --target node --format esm --packages external --chunk-naming='chunk-[hash].js'",
+    "build:tsc": "tsc --project tsconfig.build.json",
+    "build": "bun --parallel build:bun build:tsc",
+    "prepublishOnly": "bun run build",
+    "check-types": "tsc --noEmit",
+    "check": "biome check --write --unsafe",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.3",
+    "@types/bun": "latest",
+    "@types/json-schema": "7.0.15",
+    "lefthook": "2.1.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "handlebars": "4.7.8",
+    "json-schema-to-ts": "3.1.1"
+  }
+}