Typebars

Type-safe Handlebars template engine with static analysis powered by JSON Schema.

Typebars wraps Handlebars with a static analysis layer that validates your templates against a JSON Schema before execution. Given an input schema describing your data, Typebars detects unknown properties, type mismatches, and missing arguments at analysis time — and infers the exact JSON Schema of the template's output.

import { Typebars } from "typebars";

const engine = new Typebars();

const inputSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    age:  { type: "number" },
  },
  required: ["name", "age"],
};

// Static analysis — no data needed
const { valid, diagnostics, outputSchema } = engine.analyze(
  "Hello {{name}}, you are {{age}}!",
  inputSchema,
);

valid;        // true — every referenced variable exists
outputSchema; // { type: "string" } — mixed template always produces a string

// Execution — types are preserved
engine.execute("{{age}}", { name: "Alice", age: 30 }); // → 30 (number, not string)

Installation

npm install typebars
# or
yarn add typebars
# or
pnpm add typebars
# or
bun add typebars

Peer dependency: TypeScript ≥ 5

Documentation

| Document | Description | |----------|-------------| | Getting Started | Installation, quick start, and how the engine works | | Static Analysis | Input validation, output schema inference, and diagnostics | | Schema Features | $ref resolution, combinators, additionalProperties, array .length | | Execution & Compiled Templates | Type preservation, execution modes, and compile-once / execute-many | | Templates | Object templates, array templates, and block helpers (#if, #each, #with) | | Built-in & Custom Helpers | Math, logical, comparison, map, default helpers, and custom helper registration | | Template Identifiers | The {{key:N}} syntax for multi-source data pipelines | | Advanced Features | coerceSchema, excludeTemplateExpression, and the $root token | | Error Handling | Error hierarchy, diagnostics structure, and syntax validation | | API Reference | Full API: constructor, methods, types, and options |

Key Features

• Static analysis — validate templates against JSON Schema before execution (docs)
• Output schema inference — know the exact type of the result without running anything (docs)
• Type preservation — {{age}} returns 30 (number), not "30" (docs)
• Object & array templates — pass structured inputs, get structured outputs (docs)
• Block helpers — #if, #unless, #each, #with with full static analysis (docs)
• Built-in helpers — math, logical, comparison, map, and default — all statically analyzed (docs)
• Custom helpers — register your own with type metadata for full analysis integration (docs)
• Template identifiers — {{key:N}} syntax for multi-source workflows (docs)
• Output type coercion — control how static literals are typed with coerceSchema (docs)
• Expression filtering — exclude dynamic expressions from output with excludeTemplateExpression (docs)
• $root token — reference the entire root context for primitive schemas (docs)
• Compiled templates — parse once, execute many times (docs)
• JSON Schema v7 — $ref, allOf/anyOf/oneOf, additionalProperties (docs)

License

MIT