Temple
A small, fast Rust DSL for shaping data — input in, strongly-typed Rust value out.
Install · Quick start · The language · Diagnostics · How it works · Reliability · Design
You give Temple a template and an input value; it gives you back a value
deserialized straight into your Rust types. A template fixes the shape of the
output, with {{ … }} holes where values are computed:
let items = input.items
{
"summary": "{{ input.customer }} ordered {{ items.len() }} item(s)",
"lines": {{ items.map(it -> { "name": it.name, "total": it.qty * it.price }) }},
"subtotal": {{ items.map(it -> it.qty * it.price).sum() }},
"discount"?: {{ this.subtotal >= 100 ? round(this.subtotal * 0.1, 2) : null }},
"receipt": "Total due: {{ this.subtotal }}"
}
// input
{ "customer": "Ada",
"items": [ { "name": "widget", "qty": 3, "price": 9.99 } ] }
// output — deserialized into your Receipt struct
{ "summary": "Ada ordered 1 item(s)",
"lines": [ { "name": "widget", "total": 29.97 } ],
"subtotal": 29.97, // exact Decimal, never f64
"receipt": "Total due: 29.97" }
// "discount" dropped — `?:` omits null fields
Compile once, render against millions of inputs — into your
#[derive(Deserialize)] struct, a serde_json::Value, or a dynamic Value.
[!NOTE] Pre-1.0, production-shaped. The language, API and author tooling are complete: a broad test suite, a compatibility gate against the last published version, benchmarks, a CLI and CI. Breaking changes happen only across pre-1.0 minor versions and are listed in
CHANGELOG.md.
Why Temple
| 🎯 Exact decimals | rust_decimal end to end — 129.99 * 0.0825 is exactly 10.724175. No f64 exists anywhere in the value model. |
| 🦀 Typed output | Renders straight into your #[derive(Deserialize)] structs via a custom serde Deserializer — or a dynamic Value with render_value. |
| 🛡️ Never panics | compile / render / from_bytes return Result on any template or input — checked arithmetic, parser depth & size caps, value-depth cap, iterative drop. |
| ⚡ Compile once, render many | Parse · validate · dependency-graph analysis happen at write time. The render path never re-parses; sub-µs simple renders. |
| 📦 Versioned blobs | to_bytes / from_bytes persist the compiled form as a signature-tagged CBOR blob and reload it without parsing — store it in any BYTEA/BLOB column. |
| 🧭 Author tooling | Template::format canonicalizes a template; compile / validate report every error at once as rustc-style underlined snippets with did-you-mean hints. |
| 🪶 Lean core | Five small dependencies; serde_json and the CLI are opt-in behind a feature. No unsafe code. |
Install
[]
= { = "https://github.com/sinha-sahil/temple-dsl", = "release" }
crates.io publishing is wired through CI and lands with the next release. The core library pulls in nothing extra; two opt-in features:
| Feature | Adds |
|---|---|
json |
exact From conversions to/from serde_json::Value — JSON flows straight into render, decimals travel as verbatim digit tokens (never f64) |
cli |
the temple binary (implies json) |
Quick start
Render into your own types — compile once, render many:
use ;
use Deserialize;
// Err(Vec<CompileError>) — every problem reported at once
let template = compile?;
let out: Out = template.render?; // Out { id: 7, name: "ADA" }
Dynamic output when there's no struct: template.render_value(input) -> Result<Value, RenderError>.
(render::<Value> is deliberately a compile error — use render_value, it skips the serde round-trip.)
JSON in, JSON out — with the json feature there's no manual conversion:
let input: Value = from_str?;
let out = from;
// decimals stay exact in both directions — verbatim digits, never f64
Persist the compiled form and skip parsing at render time:
let blob: = template.to_bytes; // → store in any BYTEA/BLOB column
let loaded = from_bytes?; // deserialize + re-validate, no parse
let out: Out = loaded.render?;
Every fallible call returns a structured error (CompileError, RenderError,
LoadError) — Temple never panics and never decides failure handling for you.
The language
A .temple document is an optional let preamble followed by one output
literal. Bare {{ expr }} holes yield a typed value; quoted "… {{ expr }} …"
holes interpolate into a string. Entries are separated by commas or
newlines; trailing commas are always fine; # starts a comment.
| Feature | Looks like |
|---|---|
| Paths & access | input.cart.subtotal · input.items[0] · obj["key"] · input.coupon?.code ?? "none" |
| Operators | + - * / % · == != < <= > >= · && || ! · cond ? a : b |
when guards |
when { score >= 90: "A", score >= 80: "B", else: "C" } |
let + this |
preamble let, plus this.total reads a sibling key — order-free, cycle-checked at compile time |
let … in … |
local bindings anywhere: let rate = … in subtotal * rate (incl. inside when) |
| Array methods | .map .filter .fold .sum .any .all .count .find .contains .index_of .sort .sort_by .reverse .unique .flatten .flat_map .take .drop .slice .join .min .max .avg .first .last .concat .len |
| String methods | .contains .starts_with .ends_with .replace .split .slice .index_of .len |
| Object methods | .keys .values .entries .has .get .merge |
| Lambdas | x -> x * 2 · (acc, x) -> acc + x — bounded iteration only, never Turing-complete |
| Constructors | array [a, b], object { "k": expr }, computed keys { [expr]: v }, omit-if-null "k"?: expr |
| Built-in functions | abs round floor ceil min max upper lower trim to_string to_number concat type_of is_* json_encode url_encode base64 |
Methods chain on any expression — [3, 1].sort(), f(x).replace(…),
(a.concat(b)).len() — not just paths. Put together, that covers real work like
building an HTTP request with computed headers and conditional fields:
{
"url": {{ concat("https://", input.host, "/v1/rules") }},
"headers": { "Authorization": {{ concat("Bearer ", input.token) }} },
"trace_id"?: {{ input.trace_id }}, # absent when null
"by_category": {{ input.items.fold({}, (acc, it) -> # group-by via computed keys
acc.merge({ [it.cat]: (acc.get(it.cat) ?? 0) + it.qty })) }}
}
See DESIGN.md for the complete spec and samples/
for worked templates — every shipped sample is compile-tested in CI.
Diagnostics
compile and validate report all problems in one pass — parser recovery
plus resolver collection — and each error renders as an underlined snippet with
line/column and a did-you-mean hint when a name is a near-miss:
error: unknown identifier `inputt` — did you mean `input`?
--> 2:15
|
2 | "total": {{ inputt.cart.subtotal }},
| ^^^^^^
error: unknown function `rouns` — did you mean `round`?
--> 3:15
|
3 | "tier": {{ rouns(this.total) }}
| ^^^^^
Programmatic access: every error carries a Span; CompileError::report(src)
renders one snippet, CompileError::report_all(src, &errs) renders the batch.
Template::format(src) re-emits any parseable template in the canonical
layout — deterministic and idempotent, ready for format-on-save.
CLI
The feature-gated temple binary renders a template against a JSON input, or
prints its canonical formatting:
Compile errors print as the underlined snippets above; exit codes are
script-friendly (0 ok, 1 error, 2 usage).
How it works
A template is compiled once, at save time — parsing, validation, and dependency-graph analysis all happen there. The render path loads the compiled artifact and evaluates it without re-parsing, so render latency is bounded by construction, not by template size at request time.
sequenceDiagram
participant App as Application
participant Temple
participant Store as Storage
Note over App,Store: Write time — once, when a template is saved
App->>Temple: compile(source)
Temple-->>App: Template
App->>Store: persist source + to_bytes() blob
Note over App,Store: Render time — on every request
App->>Store: load compiled blob
Store-->>App: blob
App->>Temple: from_bytes(blob)
Temple-->>App: Template (no parsing)
App->>Temple: render(input)
Temple-->>App: Ok(value) or Err(RenderError)
The blob is a signature-tagged, versioned CBOR encoding of the compiled module;
from_bytes re-runs validation on load, so a corrupt or version-stale blob is
rejected (recompile from the stored source) — never rendered.
Performance
Tree-walking evaluator, measured with cargo bench (Criterion, release):
| Benchmark | Time |
|---|---|
compile_small — 3-field template |
~0.7 µs |
compile_big — ~30 fields, 4 levels deep |
~7 µs |
render_small |
~0.34 µs |
render_big — 30 fields, decimals, struct round-trip |
~3.8 µs |
render_lambdas — filter, map and any over 200 items |
~0.95 ms |
| compile + render — cold path | ~1.1 µs |
Render cost scales with template size plus the input elements a render
visits — a large passive input subtree adds nothing. A let … in … binding
is an O(1) scope overlay, and lambdas flatten their scope once per collection
walk, never per element. Memory: a compiled template holds ~15× its source in
RAM (≈1.5 KB for a small one); a render allocates ~1 KB transient.
Reliability
The crate is built around a no-panic guarantee: compile, render, and
from_bytes return typed errors on any template and any input.
- Enforced structurally — checked arithmetic everywhere, parser depth cap,
1 MiB source cap, render-time value-depth cap, and an iterative
Dropso even dropping a pathologically deep value cannot overflow the stack. - Tested broadly — feature-named suites plus a kitchen-sink test that exercises every operator, method, builtin, and structural feature in one template, asserted value-exactly and pushed through the blob and formatter round-trips.
- Thrash-tested — fuzz-style sweeps over malformed sources, deep nesting, overflow inputs, and corrupted blobs (~245k cases at last full run).
- Round-trip invariants under test —
formatis idempotent and its output always re-parses;to_bytes→from_bytesrenders identically to the original. - Deterministic — no I/O, clocks, or randomness in the language by design: same template + input ⇒ same output, always.
How Temple compares
Temple needs four things at once. Existing crates each miss at least one:
| Crate | Sub-ms render | Exact decimals | Typed Rust output | Focused surface |
|---|---|---|---|---|
minijinja |
✓ | ✗ | ✗ | ✗ |
jaq |
✓ | ✗ | ✗ | ✗ |
jsonata-core |
~ | ✗ | ✗ | ✗ |
liquid_json |
~ | ✗ | ✗ | ~ |
| Temple | ✓ | ✓ | ✓ | ✓ |
✓ yes · ~ partial · ✗ no. Evaluated for Temple's specific needs — not a general verdict on these crates.
Status
The language, API and author tooling are complete. Temple also has an
embedding API (ExprUnit, TemplateUnit, Names, Env, Budget) for host
languages that put temple expressions inside their own syntax, and it builds
for wasm32-wasip1. Not built yet: a web editor component on top of that
build, with intellisense, inline diagnostics and format-on-save.
| Capability | Status |
|---|---|
| Object / array / scalar output, value literals | ✅ |
Bare-hole expressions, path access (input.a.b.c) |
✅ |
Comments (#), trailing commas, newline-separated entries |
✅ |
Decimal-correct arithmetic via rust_decimal |
✅ |
Typed output — render::<T> (serde) or render_value (dynamic Value); render::<Value> is a compile error |
✅ |
Compile once, render many (in-memory Template) |
✅ |
Result everywhere, no panics — checked arithmetic, parser depth/size caps, value-depth cap, iterative drop |
✅ |
Operators (+ - * / %, comparison, logical, unary -/!, parens) |
✅ |
Conditionals (when guards, ternary ?:, short-circuit &&/||) |
✅ |
Safe access ?. and nullish coalesce ?? |
✅ |
let preamble, this self-reference, compile-time DAG (cycle detection) |
✅ |
Core methods (map/filter/fold/sum/any/all/len/first/last/concat), lambdas, arr[i] indexing |
✅ |
Array stdlib: count/find/contains/index_of/sort/sort_by/reverse/unique/flatten/flat_map/take/drop/slice/join/min/max/avg |
✅ |
String methods: contains/starts_with/ends_with/replace/split/slice/index_of |
✅ |
Object methods + indexing: keys/values/entries/has/get/merge, obj["k"] |
✅ |
% operator; to_number, type_of/is_*, concat, json_encode, url_encode, base64 |
✅ |
Constructors: array […], object { "k": expr }, computed keys { [expr]: v }, omit-if-null "k"?: |
✅ |
let … in … local bindings; method/index chains on any expression |
✅ |
String interpolation in quoted holes — "Hi {{ input.name }}" (incl. \{ escape) |
✅ |
Built-in scalar functions (abs … to_string) |
✅ |
validate(src) author-time check; size/depth caps (early rejection) |
✅ |
to_bytes / from_bytes — versioned compiled blob, reload without reparsing |
✅ |
Template::format — canonical, idempotent pretty-printer |
✅ |
| Diagnostics — multi-error reporting with parser recovery, rustc-style underlined snippets, did-you-mean | ✅ |
| Embedding API — parse, check and evaluate one expression or value inside a host language, under a work budget | ✅ |
| Web editor component (intellisense, inline diagnostics, format-on-save) | 🟡 not yet |
Project layout
| Path | What's there |
|---|---|
src/ |
The library and the feature-gated temple CLI; ARCHITECTURE.md maps it |
DESIGN.md |
The language: format, expressions, values, guarantees, decisions |
ARCHITECTURE.md |
Where the code for each part lives, and the rules that hold it together |
FAQ.md |
How the engine works inside, question by question |
CONTRIBUTING.md |
Building, the checks CI runs, the compatibility gate |
CHANGELOG.md |
What changed in each version |
samples/ |
Canonical .temple templates, one per pattern (compile-tested) |
examples/ |
Runnable Rust demos against the public API |
tests/ |
The test suite; tests/compat/ holds the compatibility goldens |
benches/ |
Criterion benchmark suite |
e2e/ |
Out-of-crate end-to-end (Postgres) harness |
Developing
Rust 1.80 or newer. cargo fmt and cargo clippy -D warnings are enforced
by a pre-commit hook (installed automatically via cargo-husky) and by CI on
every push and pull request, which also builds the docs, checks the MSRV and
builds for wasm32-wasip1. See CONTRIBUTING.md.
Author
Sahil Sinha · sahilsinha.dar@gmail.com
License
Dual-licensed under MIT OR Apache-2.0 — use it under either at your option.