@statedelta-libs/expressions

> Compilador de JSON DSL puro para funções otimizadas.


O que é

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.

Instalação

``bash
pnpm add @statedelta-libs/expressions
`

Quick Start

`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"]
`

Os 5 Primitivos

| 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.

Dois Modos de Compilação

`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.

Extensibilidade

$3

`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; }
},
},
});
`

$3

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);
`

$3

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 |
|---|---|---|
| Quando roda | Antes da compilação | Durante a compilação (no walk) |
| Retorno | Expression (DSL puro) | CompiledFn (função pronta) |
| Uso típico | Sugar syntax | DSL estrangeiro, $raw, rule engines |

$3

`typescript
const compiler = new ExpressionCompiler({
scope,
accessor: (path, ctx) => ctx.get(path), // ex: TickContext, reactive store
});
``

Documentação

| 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 |

Licença

MIT © Anderson D. Rosa