temple-dsl 1.0.0

A small, fast Rust DSL for shaping data — input in, strongly-typed Rust value out.
Documentation

Temple

A small, fast Rust DSL for shaping data — input in, strongly-typed Rust value out.

CI MSRV 1.80 Version Coverage Decimals License

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

[dependencies]
temple-dsl = { git = "https://github.com/sinha-sahil/temple-dsl", branch = "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 temple_dsl::{Template, Value};
use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct Out { id: i64, name: String }

// Err(Vec<CompileError>) — every problem reported at once
let template = Template::compile(r#"{ "id": {{ input.id }}, "name": {{ upper(input.name) }} }"#)?;

let out: Out = template.render(Value::obj([
    ("id",   Value::Int(7)),
    ("name", Value::Str("ada".into())),
]))?;                                   // 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: serde_json::Value = serde_json::from_str(request_body)?;
let out = serde_json::Value::from(template.render_value(input)?);
// decimals stay exact in both directions — verbatim digits, never f64

Persist the compiled form and skip parsing at render time:

let blob: Vec<u8> = template.to_bytes();        // → store in any BYTEA/BLOB column
let loaded = Template::from_bytes(&blob)?;      // deserialize + re-validate, no parse
let out: Out = loaded.render(input)?;

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:

cargo install --path . --features cli

temple order.temple input.json    # render → JSON on stdout
temple fmt order.temple           # canonical formatting on stdout

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 Drop so 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 — format is idempotent and its output always re-parses; to_bytes→from_bytes renders 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

cargo test --all-features     # full suite
cargo bench                   # Criterion benchmarks
cargo llvm-cov --all-features # coverage report

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.