CursedObject calculates values on a plain JS object with deterministic templates, expressions, local async bindings, and inline conditionals. It does not parse YAML โ bring your own parser (js-yaml, json5, hand-built objects, whatever).
import { load as parseYaml } from "js-yaml";
import { load } from "./cursedobject";
const obj = load(
parseYaml(`
name: Ada
greeting: Hello {{name}}
score: -> 1 + 2
names:
- Ada
- Grace
firstName: "{{get('names.0')}}"
loud: "{{shout(name)}}"
allNames: -> select("names.*")
line: |
<<lookup:result name Ada>>
{{#if result == "ok"}}
passed
{{else}}
failed
{{/if}}
`),
{
seed: 123,
fn: {
shout: (s) => String(s).toUpperCase(),
},
io: {
async lookup(params) {
const row = await db.find(params.pairs.name);
return row ? "ok" : "no";
},
},
},
);
await obj.calc("greeting"); // "Hello Ada"
await obj.calc("score"); // 3
await obj.calc("allNames"); // ["Ada", "Grace"]
await obj.evaluate("get('names.0')"); // "Ada"
await obj.calc("greeting", { name: "Grace" }); // "Hello Grace"
obj.has("names.0"); // true
obj.raw("greeting"); // "Hello {{name}}"
await obj.calcAll();
const { values, undo } = await obj.update(
{
"relations.{{other}}.emotions.arousal": "-> incr(this)",
emotions: { arousal: "-> incr(this) + 2.5" },
},
{ other: "sarah" },
);
obj.restore(undo);
obj.clear();{{expr}}evaluates expressions against object keys, params, local bindings, and built-in helpers. Pure โ no PRNG, no counters, no I/O.get("path.to.value")reads one calculated path and returnsnullwhen missing.select("path.*.value")reads calculated wildcard matches and always returns an array.*matches one object key or array index.-> exprmakes a string value calculate directly to the expression value. The expression source may embed{{...}}and<<...>>(so the impurity is still visible in the source).opts.fnregisters sync helpers callable from{{...}}expressions (e.g.shout(name)).{{#if expr}}...{{elseif expr}}...{{else}}...{{/if}}renders the first matching block.- A property whose value is a function is invoked as
(vars, handle) => SerialValue | Promise<SerialValue>, wherevarsare the caller-passed vars fromcalc(path, vars)(orcalcAll/peek/update) andhandleis the loaded handle. The return value is recursively calculated, so functions can return template strings, nested objects, or-> exprstrings.
Everything that mutates state โ PRNG advancement, counter bumps, I/O โ uses chevrons. Authors can grep << to find every site that breaks reproducibility.
<<name args>>callsopts.io.name(params, handle)(sync or async) and inserts the result. The legacy<<#name args>>form still works. When the field value is a single directive with no surrounding text (e.g.field: <<lookup id 7>>), the raw return value is preserved โ objects, arrays, numbers, etc. pass through unchanged. When embedded in a larger string, the result is stringified (objects/arrays viaJSON.stringify).<<name:binding args>>stores result in a local binding for the rest of the current string and inserts nothing. The binding holds the raw value, so subsequent{{binding}}or{{binding.field}}expressions can read object/array fields directly.- Built-in variation pickers (split parts on
|):<<rand A|B|C>>(PRNG),<<cycle A|B|C>>,<<seq A|B|C>>(stops at last),<<once A|B|C>>(visits each once then""). Cycle/seq/once use a counter keyed on the directive body. - Built-in rand value generators:
<<random>>(float 0โ1),<<randint min max>>,<<randfloat min max>>,<<randnormal min max>>,<<randintnormal min max>>,<<dice sides=6>>,<<coin prob=0.5>>,<<roll count sides=6>>. Builtin names take precedence overopts.ioentries.
calc(path), calcAll(), and evaluate(expr) are async. Each accepts an optional vars object that overlays the loaded params for that call. Use fork(opts) to create a new handle with merged options. evaluate(expr) runs the expression language directly against the calculated state (no directive processing โ directives only fire while rendering field values). Missing paths and variables evaluate to null; bad expressions, unknown directives, and circular dependencies throw.
update(patch, vars?, opts?) mutates the loaded state and returns { values, undo }. values is the resolved path/value map that was written. undo is a serializable snapshot for restore(undo), recording prior values, created paths, and a revision guard. PRNG state and cycle counters are NOT tracked in undo โ randomness is an explicit side effect (the <<>> is the signal) and not rolled back. Restore patches are LIFO: restore the newest successful update first, then earlier updates. Patch keys are dotted paths (key templates may interpolate {{vars}} and contain * wildcards). Add + to a path to merge/append/concat instead of replace: objects deep-merge, arrays append, and strings concatenate. Patch values are plain literals or template strings (-> expr, {{...}}, <<...>>); inside a template, this is the current calculated value at that path. All this snapshots are read before any writes. Missing paths are created by default; pass opts.create: false to throw instead. clear() resets state to the originally loaded values.
Use evaluate(expr, opts?) to run a single expression without a source object. Use render(template, opts?) for a single template string with full {{...}}, <<...>>, and conditionals. Both accept the same options as load (seed, cycle, params, fn, io).
import { evaluate, render } from "./cursedobject";
await evaluate("x + y", { params: { x: 5, y: 10 } }); // 15
await evaluate("shout(name)", {
params: { name: "ada" },
fn: { shout: (s) => String(s).toUpperCase() },
}); // "ADA"
await render("solution: {{foo + bar}}", { params: { foo: 1, bar: 2 } });
// "solution: 3"
await render("{{#if x > 0}}pos{{else}}neg{{/if}}", { params: { x: 5 } });
// "pos"
await render("<<lookup id 7>>", {
io: { async lookup(p) { return db.find(p.pairs.id); } },
});render returns the raw value when the template is a single directive (e.g. <<obj>> returning an object); otherwise the result is stringified.
Copyright 2026 Matthew Trost.
Licensed under the Apache License, Version 2.0. See LICENSE.