JSON DSL compiler for optimized functions - StateDelta expression engine
npm install @statedelta-libs/expressions> Compilador de JSON DSL puro para funções otimizadas.


Um compilador que transforma expressões declarativas em JSON puro em funções JavaScript de alta performance. A entrada é sempre JSON serializável. A saída é sempre uma (data) => result.
O compilador não conhece nenhuma função — todas vêm via scope fornecido pelo consumer. O mesmo motor serve para matemática, queries de game engine, ETL, NoCode, ou qualquer domínio.
``bash`
pnpm add @statedelta-libs/expressions
`typescript
import { ExpressionCompiler } from '@statedelta-libs/expressions';
const compiler = new ExpressionCompiler({
scope: {
add: (a, b) => a + b,
multiply: (a, b) => a * b,
filter: (pred) => (arr) => arr.filter(pred),
sum: (arr) => arr.reduce((a, b) => a + b, 0),
},
});
// Compila uma vez
const compiled = compiler.compile({
$pipe: [
{ $: "items" },
{ $fn: "filter", args: [{ $arrow: { $: "item.active" }, args: ["item"] }] },
{ $fn: "sum" }
]
});
// Executa milhões de vezes
compiled.fn({ items: [{ active: true, price: 10 }, { active: false, price: 20 }] });
compiled.deps; // ["items"]
`
| Primitivo | O que faz | Exemplo DSL | JS equivalente |
|-----------|-----------|-------------|----------------|
| $ | Referência a path | { $: "user.name" } | data.user.name |$fn
| | Invocação/referência de função | { $fn: "add", args: [...] } | add(a, b) |$if
| | Condicional | { $if: cond, then: a, else: b } | cond ? a : b |$pipe
| | Composição left-to-right | { $pipe: [x, f, g] } | g(f(x)) |$arrow
| | Closure deferida | { $arrow: body, args: ["x"] } | (x) => body |
Tudo 100% JSON-serializável. Funções nunca aparecem no DSL — são referenciadas por nome e resolvidas contra o scope em runtime.
`typescript`
compiler.compile(expr); // closures — compilação rápida, ~9-20M ops/s
compiler.jit(expr); // JIT — compilação lenta, ~25-27M ops/s de execução
Closures compõe funções JavaScript aninhadas. Ideal para expressões executadas poucas vezes ou ambientes com CSP restritivo.
JIT gera código JavaScript via AST e new Function(). Ideal para hot paths executados muitas vezes. Break-even em ~8 execuções.
`typescript`
const compiler = new ExpressionCompiler({
scope: {
add: (a, b) => a + b,
filter: (pred) => (arr) => arr.filter(pred),
tryCatch: (arrow, params) => {
try { return arrow(); }
catch { return params?.fallback ?? null; }
},
},
});
Transforma sugar syntax em DSL puro antes da compilação. Para quando o resultado é expression DSL válido.
`typescript
const transforms = {
$double: (node) => ({ $fn: "multiply", args: [node.$double, 2] }),
};
const pure = compiler.normalize({ $double: { $: "value" } }, transforms);
compiler.compile(pure);
`
Intercepta nós durante a compilação e terceiriza para outro algoritmo. Para quando o nó precisa de um compilador completamente diferente.
`typescript
import type { BoundaryDef } from '@statedelta-libs/expressions';
// $raw — passthrough, nada é compilado
const rawBoundary: BoundaryDef = {
check: (node) => "$raw" in node,
handle: (node) => () => node.$raw,
};
// $rules — DSL estrangeiro com compilador próprio
const rulesBoundary: BoundaryDef = {
check: (node) => "$rules" in node,
handle: (node) => {
const compiled = ruleEngine.compile(node.$rules);
return (data) => compiled.evaluate(data);
},
};
const compiler = new ExpressionCompiler({
scope,
boundaries: [rawBoundary, rulesBoundary],
});
// $rules é interceptado pelo boundary, compilado pelo ruleEngine
compiler.compile({
$fn: "add",
args: [{ $: "base" }, { $rules: { when: "vip", then: 20 } }]
});
`
O handler é uma closure auto-suficiente — captura o que precisa (outros compiladores, databases, etc.) por fora. Zero overhead quando não há boundaries registrados.
| | normalize() | BoundaryDef |Expression
|---|---|---|
| Quando roda | Antes da compilação | Durante a compilação (no walk) |
| Retorno | (DSL puro) | CompiledFn (função pronta) |$raw
| Uso típico | Sugar syntax | DSL estrangeiro, , rule engines |
`typescript``
const compiler = new ExpressionCompiler({
scope,
accessor: (path, ctx) => ctx.get(path), // ex: TickContext, reactive store
});
| Doc | Conteúdo |
|-----|----------|
| docs/EXPRESSIONS-API.md | Referência completa da API pública |
| docs/ARCHITECTURE.md | Visão geral da infraestrutura |
| docs/COMPILE.md | Internals do pipeline closures |
| docs/JIT.md | Internals do pipeline JIT |
MIT © Anderson D. Rosa