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