@statedelta-libs/expressions 1.2.1 → 2.0.1

package/README.md

@@ -1,12 +1,13 @@
 # @statedelta-libs/expressions
 
-> Compilador de JSON DSL para funções otimizadas.
+> Compilador de JSON DSL puro para funções otimizadas.
 
 [![npm version](https://img.shields.io/npm/v/@statedelta-libs/expressions.svg)](https://www.npmjs.com/package/@statedelta-libs/expressions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Características
 
+- **DSL Puro** - 100% JSON-serializável, sem callbacks inline
 - **Compilação** - Compila uma vez, executa milhões de vezes
 - **Alta performance** - ~25-30M ops/s após compilação
 - **Scope externo** - Funções vêm via scope, não hardcoded
@@ -15,7 +16,7 @@
 - **Path syntax** - Suporte a wildcards (`items[*].price`)
 - **Dependency extraction** - Para dirty tracking/reatividade
 - **Conditions nativo** - Condicionais integradas com expressions nos lados
-- **Custom Transforms** - Extensão do walker via transforms registrados (`$query`, `$mapper`, etc.)
+- **normalize()** - Helper externo para custom transforms (`$query`, `$mapper`, etc.)
 - **Type-safe** - TypeScript nativo com inferência
 
 ## Instalação
@@ -29,18 +30,23 @@ pnpm add @statedelta-libs/expressions
 ## Quick Start
 
 ```typescript
-import { compile, evaluate } from '@statedelta-libs/expressions';
-import { filter, map, sum } from '@statedelta-libs/operators';
+import { compile } from '@statedelta-libs/expressions';
 
 // Define o scope com funções disponíveis
-const scope = { filter, map, sum };
+const scope = {
+  filter: (pred) => (arr) => arr?.filter(pred),
+  map: (fn) => (arr) => arr?.map(fn),
+  sum: (arr) => arr?.reduce((a, b) => a + b, 0),
+  isActive: (item) => item.active,
+  getPrice: (item) => item.price,
+};
 
-// Compilar expressão com $pipe
+// Compilar expressão com $pipe (DSL puro)
 const expr = compile({
   $pipe: [
     { $: "items" },
-    { $fn: "filter", args: [(item) => item.active] },
-    { $fn: "map", args: [(item) => item.price] },
+    { $fn: "filter", args: [{ $fn: "isActive" }] },
+    { $fn: "map", args: [{ $fn: "getPrice" }] },
     { $fn: "sum" }
   ]
 }, { scope });
@@ -115,16 +121,6 @@ const { fn } = compileAST(
 fn();  // usa ctx.get("hp") + ctx.get("mp")
 ```
 
-Código gerado:
-```js
-(function(scope){
-  const{add,accessor}=scope;
-  return function(data){
-    return add(accessor("hp",data),accessor("mp",data))
-  }
-})
-```
-
 #### lexicalPrefix (compileAST)
 
 Para máxima performance em paths específicos, use `lexicalPrefix` para acesso direto via destructuring:
@@ -147,22 +143,6 @@ const { fn } = compileAST(
 fn({ params: { damage: 25 } });  // ctx.get("hp") + params.damage
 ```
 
-Código gerado:
-```js
-(function(scope){
-  const{add,accessor}=scope;
-  return function(data){
-    const{params}=data??{};  // destructuring direto (rápido!)
-    return add(accessor("hp",data),params?.damage)
-  }
-})
-```
-
-| Path | Com lexicalPrefix | Sem lexicalPrefix |
-|------|-------------------|-------------------|
-| `params.damage` | `params?.damage` (direto) | `accessor("params.damage", data)` |
-| `hp` | `accessor("hp", data)` | `accessor("hp", data)` |
-
 ### evaluate() / evaluateAST()
 
 Compila e executa em um passo.
@@ -192,32 +172,30 @@ const deps = extractDeps({
 // ["$isVip", "price.vip", "price.regular"]
 ```
 
-## JSON Aninhado (Walk Automático)
+### normalize()
 
-O compilador **percorre automaticamente** todo o JSON e resolve expressões onde quer que estejam:
+Normaliza expressões customizadas para DSL puro **antes** da compilação.
 
 ```typescript
-const { fn } = compile({
-  name: "John",
-  damage: { $: "params.damage" },
-  active: { $if: "hp.current", then: true, else: false },
-  nested: {
-    deep: {
-      value: { $fn: "add", args: [{ $: "a" }, { $: "b" }] }
-    }
-  }
-}, { scope });
+import { normalize, type Transforms } from '@statedelta-libs/expressions';
 
-fn({ params: { damage: 25 }, hp: { current: 100 }, a: 1, b: 2 });
-// {
-//   name: "John",
-//   damage: 25,
-//   active: true,
-//   nested: { deep: { value: 3 } }
-// }
-```
+const transforms: Transforms = {
+  $query: (node) => ({
+    $fn: "__query",
+    args: [node.$query as string, (node.params ?? {}) as Expression],
+  }),
+};
+
+// Converte expressão customizada para DSL puro
+const pure = normalize(
+  { $query: "isAttacked", params: { row: { $: "kingRow" } } },
+  transforms
+);
+// → { $fn: "__query", args: ["isAttacked", { row: { $: "kingRow" } }] }
 
-Não precisa de walker manual - o `compile()` e `compileAST()` já fazem isso internamente.
+// Agora pode compilar normalmente
+const { fn } = compile(pure, { scope });
+```
 
 ## Tipos de Expressão
 
@@ -260,10 +238,10 @@ Composição com valor inicial - o valor passa por cada função em sequência.
 ```typescript
 {
   $pipe: [
-    { $: "items" },                              // Valor inicial
-    { $fn: "filter", args: [predicateFn] },      // Retorna função curried
-    { $fn: "map", args: [mapperFn] },            // Retorna função curried
-    { $fn: "sum" }                               // Referência à função
+    { $: "items" },                                   // Valor inicial
+    { $fn: "filter", args: [{ $fn: "isActive" }] },   // Curried filter
+    { $fn: "map", args: [{ $fn: "getPrice" }] },      // Curried map
+    { $fn: "sum" }                                    // Referência à função
   ]
 }
 ```
@@ -284,6 +262,10 @@ Chama função do scope com argumentos compilados.
 // Com args vazio: chama função sem argumentos
 { $fn: "getTimestamp", args: [] }
 // → scope.getTimestamp()
+
+// Passando função como argumento (referência via $fn)
+{ $fn: "filter", args: [{ $fn: "isActive" }] }
+// → scope.filter(scope.isActive)
 ```
 
 ### Condition
@@ -315,8 +297,6 @@ Condicionais compiladas internamente. Ambos os lados aceitam qualquer expressão
 
 **Operadores:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`, `contains`, `notContains`, `exists`, `notExists`, `matches`, `notMatches`, `startsWith`, `endsWith`
 
-> **Nota:** Objetos com `op: "set"` ou outros operadores não-condition são tratados como literals.
-
 ## Scope
 
 O scope define quais funções estão disponíveis para `$fn`:
@@ -333,388 +313,115 @@ const scope = {
   filter: R.filter,
   map: R.map,
   sum: R.sum,
-  // Funções custom
+  // Funções custom (predicados, mappers, etc.)
   double: (n) => n * 2,
-  isActive: (item) => item.active
+  isActive: (item) => item.active,
+  getPrice: (item) => item.price,
 };
 
 const { fn } = compile(expression, { scope });
 ```
 
-## Accessor Customizado
-
-Para objetos que usam interface de acesso customizada (como `ctx.get(path)`), use o `accessor`:
-
-```typescript
-// Contexto com método get() customizado
-interface TickContext {
-  get(path: string): unknown;
-}
-
-const accessor = (path: string, ctx: TickContext) => ctx.get(path);
-
-// Compilação com accessor
-const { fn } = compile<TickContext>(
-  { $: "hp:value" },
-  { accessor }
-);
-
-fn(tickContext); // usa ctx.get('hp:value')
-
-// Com scope + accessor
-const { fn } = compile<TickContext>(
-  { $fn: "add", args: [{ $: "a" }, { $: "b" }] },
-  { scope, accessor }
-);
-```
-
-O accessor é propagado para:
-- Referências (`{ $: "path" }`)
-- Shorthand de `$if` (`{ $if: "path", ... }`)
-- Argumentos de `$fn`
-- Steps de `$pipe`
-- Conditions (compiladas internamente)
-
-**Performance:** Igual ao acesso direto (~25-30M ops/s).
+## Custom Transforms (normalize)
 
-## Path Syntax
-
-| Path | Resultado |
-|------|-----------|
-| `user` | `data.user` |
-| `user.name` | `data.user.name` |
-| `items[0]` | `data.items[0]` |
-| `items[*].price` | `data.items.map(i => i.price)` |
-
-## Cache
+Para tipos de expressão customizados (`$query`, `$mapper`, etc.), use `normalize()` para convertê-los em DSL puro **antes** da compilação:
 
 ```typescript
-import { cache, cached } from '@statedelta-libs/expressions';
-
-// Com scope
-const compiled = cache.get(expression, { scope });
-
-// Ou função helper
-const compiled = cached(expression, { scope });
-
-// Gerenciar
-cache.size;    // Tamanho atual
-cache.clear(); // Limpar
-```
+import { normalize, compile, type Transforms, type Expression } from '@statedelta-libs/expressions';
 
-## Performance
-
-### compile() - Closures
-
-| Operação | Velocidade |
-|----------|------------|
-| Compile (literal) | ~6.5M ops/s |
-| Compile (ref) | ~3M ops/s |
-| Compile (fn nested) | ~550K ops/s |
-| Compile (complex) | ~300K ops/s |
-| Execute (ref) | ~28-30M ops/s |
-| Execute (fn nested) | ~9M ops/s |
-| Execute (com accessor) | ~23-30M ops/s |
-
-### compileAST() - AST + new Function
-
-| Operação | Velocidade |
-|----------|------------|
-| Compile (literal) | ~1.2M ops/s |
-| Compile (ref) | ~800K ops/s |
-| Compile (fn nested) | ~230K ops/s |
-| Compile (complex) | ~130K ops/s |
-| Execute (ref) | ~27M ops/s |
-| Execute (fn nested) | ~25M ops/s ⚡ |
-
-### Comparação Execução
-
-| Cenário | Closures | AST | Ganho AST |
-|---------|----------|-----|-----------|
-| fn nested | 9M ops/s | 25M ops/s | **+169%** |
-| ref 4 níveis | 16M ops/s | 27M ops/s | **+69%** |
-| conditional nested | 20M ops/s | 25M ops/s | **+25%** |
-
-**Break-even:** ~8 execuções - após isso, `compileAST()` compensa o tempo extra de compilação.
-
-## Segurança
-
-Ambas as abordagens são **seguras contra injeção de código**:
-
-| Método | Proteção |
-|--------|----------|
-| `compile()` | Não gera código string - apenas compõe funções |
-| `compileAST()` | Usa destructuring que valida identificadores automaticamente |
-
-```typescript
-// Tentativa de injeção - FALHA em ambos
-{ $fn: "add; console.log('hacked'); //" }
-
-// compile(): tenta acessar scope["add; console.log..."] → undefined
-// compileAST(): destructuring inválido → SyntaxError
-```
-
-Funções só são acessíveis se existirem no `scope` fornecido pelo desenvolvedor.
-
-## Custom Transforms
-
-Mecanismo de extensão do walker para tipos de expressão customizados. Permite registrar transforms que interceptam objetos com chaves específicas e os convertem em expressões padrão antes da compilação.
-
-### API
-
-Transforms retornam `Expression` ou `TransformResult`. Use `TransformResult` quando os args contêm tipos domain-specific (não `FnArg`):
-
-```typescript
-import type { TransformFn, TransformResult } from '@statedelta-libs/expressions';
-
-const transforms: Record<string, TransformFn> = {
-  // TransformResult.args aceita unknown[] — sem casts necessários
+// Define transforms
+const transforms: Transforms = {
   $query: (node) => ({
     $fn: "__query",
-    args: [node.$query, node.params ?? {}]
+    args: [node.$query as string, (node.params ?? {}) as Expression],
   }),
-  $test: (node) => ({
-    $fn: "__test",
-    args: [node.$test]  // TestSpec, QueryParams, etc. — qualquer tipo
+  $mapper: (node) => ({
+    $fn: "__mapper",
+    args: [node.$mapper as string],
   }),
 };
-```
-
-### Uso com compile() e compileAST()
-
-```typescript
-import { compile, compileAST } from '@statedelta-libs/expressions';
 
+// Define scope com as funções de runtime
 const scope = {
   __query: (name, params) => queryEngine.run(name, params),
+  __mapper: (name) => mapperRegistry.get(name),
 };
 
-// Closures
-const { fn } = compile(
-  { $query: "isKingAttacked", params: { row: 0, col: 4 } },
-  { scope, transforms }
+// 1. Normalize (converte para DSL puro)
+const pure = normalize(
+  { $query: "isAttacked", params: { row: { $: "kingRow" } } },
+  transforms
 );
 
-// AST (mesmo contrato)
-const { fn } = compileAST(
-  { $query: "isKingAttacked", params: { row: 0, col: 4 } },
-  { scope, transforms }
-);
-```
+// 2. Compile (DSL puro)
+const { fn } = compile(pure, { scope });
 
-### Expressions dentro de params
-
-Os params do transform são compilados recursivamente — referências e expressões dentro deles são resolvidas normalmente:
-
-```typescript
-const { fn } = compile(
-  { $query: "check", params: { row: { $: "myRow" }, col: { $: "myCol" } } },
-  { scope, transforms }
-);
-
-fn({ myRow: 5, myCol: 3 });
-// → __query("check", { row: 5, col: 3 })
+// 3. Execute
+fn({ kingRow: 0 });
 ```
 
 ### Aninhamento
 
-Transforms funcionam em qualquer posição — dentro de `$if`, `$pipe`, `$fn`, conditions, plain objects:
+O `normalize` percorre toda a árvore, então transforms funcionam em qualquer posição:
 
 ```typescript
-// Dentro de condition
-{
-  $if: {
-    left: { $query: "isAttacked", params: { row: 0 } },
-    op: "eq",
-    right: true
+normalize(
+  {
+    $if: {
+      left: { $query: "isAttacked", params: { row: 0 } },
+      op: "eq",
+      right: true
+    },
+    then: "check",
+    else: "safe"
   },
-  then: "check",
-  else: "safe"
-}
-
-// Dentro de plain object (walk automático)
-{
-  damage: { $query: "getDamage", params: { base: 10 } },
-  name: "attack"
-}
-```
-
-### Extração de deps
-
-`extractDeps` também resolve transforms para capturar dependências internas:
-
-```typescript
-import { extractDeps } from '@statedelta-libs/expressions';
-
-const deps = extractDeps(
-  { $query: "check", params: { row: { $: "myRow" } } },
   transforms
 );
-// ["myRow"]
 ```
 
-### Proteção contra loops infinitos
+### Proteção contra loops
 
-Se um transform retornar um objeto com a mesma chave de entrada, um erro é lançado:
+Se um transform retornar objeto com a mesma chave, erro é lançado:
 
 ```typescript
 const badTransforms = {
   $loop: (node) => ({ $loop: node.$loop }),  // mesma chave!
 };
 
-compile({ $loop: "test" }, { transforms: badTransforms });
+normalize({ $loop: "test" }, badTransforms);
 // Error: Transform "$loop" returned object with same key — infinite loop
 ```
 
-### Performance
-
-Transforms são resolvidos **em tempo de compilação**. Zero overhead em runtime — a função compilada resultante é idêntica a uma expressão `$fn` normal.
-
-## Type Detection
-
-O compilador detecta automaticamente o tipo de expressão baseado na estrutura do objeto:
-
-| Tipo | Detecção | Exemplo |
-|------|----------|---------|
-| Reference | `{ $ }` presente | `{ $: "user.name" }` |
-| Conditional | `{ $if, then }` presentes | `{ $if: cond, then: x, else: y }` |
-| Function | `{ $fn }` presente | `{ $fn: "add", args: [...] }` |
-| Pipe | `{ $pipe }` presente | `{ $pipe: [...] }` |
-| Condition | `{ left, op }` com operador válido | `{ left: { $: "age" }, op: "gte", right: 18 }` |
-| Custom Transform | Chave registrada em `transforms` | `{ $query: "check", params: {...} }` |
-| Literal | Nenhum dos acima | `{ foo: "bar" }`, `42`, `"hello"` |
-
-### Distinção entre Conditions e Effect Objects
-
-Objetos com `left` e `op` só são tratados como conditions se `op` for um operador válido:
-
-```typescript
-// ✓ Condition (op: "eq" é operador válido)
-{ left: { $: "user.age" }, op: "eq", right: 18 }
-
-// ✓ Literal object (op: "set" NÃO é operador de condition)
-{ resource: "state", op: "set", path: "currentPlayer", value: "X" }
-```
-
-Isso permite que effect objects de handlers (que usam `{ resource, op: "set", path, value }`) sejam processados corretamente sem serem confundidos com conditions.
-
 ## Builders
 
-Funções declarativas para construir expressões. Disponíveis via namespace `builders`:
+Funções declarativas para construir expressões:
 
 ```typescript
-import { builders, compile } from '@statedelta-libs/expressions';
+import { builders } from '@statedelta-libs/expressions';
 
 const { $, $fn, $if, $pipe, $cond } = builders;
-```
-
-### `$` / `ref` - Path Reference
-
-```typescript
-$("player.hp")         // { $: "player.hp" }
-$("items[0].price")    // { $: "items[0].price" }
-$("items[*].price")    // { $: "items[*].price" } (wildcard)
-```
 
-### `$fn` / `fn` - Function Call
+// Path reference
+$("player.hp")                    // { $: "player.hp" }
 
-```typescript
-// Com argumentos - chama a função
-$fn("add", [$("a"), $("b")])     // { $fn: "add", args: [...] }
-$fn("multiply", [10, $("x")])    // literal + expression
-
-// Sem argumentos - retorna referência à função (útil em $pipe)
+// Function call
+$fn("add", [$("a"), $("b")])      // { $fn: "add", args: [...] }
 $fn("sum")                        // { $fn: "sum" }
 
-// Com callbacks (predicados, mappers)
-$fn("filter", [(item) => item.active])
-$fn("map", [(item) => item.price])
-```
-
-### `$if` - Conditional
-
-```typescript
-// Com else
-$if($("isVip"), 0.2, 0)
-// { $if: { $: "isVip" }, then: 0.2, else: 0 }
-
-// Sem else
-$if($("active"), "yes")
-// { $if: { $: "active" }, then: "yes" }
-
-// Nested
-$if($("level1"), $if($("level2"), "deep", "shallow"), "none")
-```
-
-### `$pipe` / `pipe` - Composition
+// Conditional
+$if($("isVip"), 0.2, 0)           // { $if: ..., then: 0.2, else: 0 }
 
-```typescript
+// Pipe
 $pipe(
-  $("items"),                              // valor inicial
-  $fn("filter", [(x) => x.active]),        // transforma
-  $fn("map", [(x) => x.price]),            // transforma
-  $fn("sum")                               // resultado
-)
-```
-
-### `$cond` / `cond` - Condition
-
-```typescript
-// Básico
-$cond($("age"), "gte", 18)
-// { left: { $: "age" }, op: "gte", right: 18 }
-
-// Exists (sem right)
-$cond($("email"), "exists")
-
-// Ref vs Ref
-$cond($("price"), "lte", $("budget"))
-
-// Com $fn nos lados
-$cond($fn("add", [$("a"), $("b")]), "gt", 100)
-
-// Com $pipe
-$cond($pipe($("name"), $fn("upper")), "eq", "ADMIN")
-```
-
-### Exemplo Completo
-
-```typescript
-import { builders, compile } from '@statedelta-libs/expressions';
-import { filter, map, sum } from '@statedelta-libs/operators';
-
-const { $, $fn, $if, $pipe, $cond } = builders;
-
-const scope = { filter, map, sum };
-
-// Soma preços de itens ativos com desconto VIP
-const expr = $pipe(
   $("items"),
-  $fn("filter", [(item) => item.active]),
-  $fn("map", [(item) => item.price]),
+  $fn("filter", [$fn("isActive")]),
   $fn("sum")
-);
-
-const { fn } = compile(expr, { scope });
+)
 
-fn({
-  items: [
-    { price: 10, active: true },
-    { price: 20, active: false },
-    { price: 30, active: true }
-  ]
-}); // 40
+// Condition
+$cond($("age"), "gte", 18)        // { left: ..., op: "gte", right: 18 }
 ```
 
-### Aliases
-
-| Builder | Alias |
-|---------|-------|
-| `$` | `ref` |
-| `$fn` | `fn` |
-| `$pipe` | `pipe` |
-| `$cond` | `cond` |
-
 ## TypeScript
 
 ```typescript
@@ -733,7 +440,7 @@ import type {
   CompileOptions,
   AccessorFn,
   TransformFn,
-  TransformResult,
+  Transforms,
 } from '@statedelta-libs/expressions';
 
 // Type guards
@@ -744,79 +451,59 @@ import {
   isPipe,
   isCondition,
   isLiteral,
-  isTransformResult,
 } from '@statedelta-libs/expressions';
 ```
 
-## Migração de v0.1.x
-
-### Breaking Changes
-
-1. **Builtins removidos**: Funções não são mais hardcoded. Passe via `scope`:
-   ```typescript
-   // Antes
-   compile({ $fn: "add", args: [1, 2] })
-
-   // Depois
-   compile({ $fn: "add", args: [1, 2] }, { scope: { add } })
-   ```
-
-2. **$fn sem args retorna função**: Para chamar sem argumentos, use `args: []`:
-   ```typescript
-   // Retorna a função
-   { $fn: "sum" }
+## Performance
 
-   // Chama a função
-   { $fn: "getTime", args: [] }
-   ```
+### Comparação Execução
 
-3. **Removidos**: `registerFunction`, `hasFunction`, `getFunctionNames`
+| Cenário | Closures | AST | Ganho AST |
+|---------|----------|-----|-----------|
+| fn nested | 9M ops/s | 25M ops/s | **+169%** |
+| ref 4 níveis | 16M ops/s | 27M ops/s | **+69%** |
+| conditional nested | 20M ops/s | 25M ops/s | **+25%** |
 
-4. **Novo**: `$pipe` como sintaxe DSL para composição
+**Break-even:** ~8 execuções - após isso, `compileAST()` compensa o tempo extra de compilação.
 
-### v1.0 → v1.1
+## Segurança
 
-1. **Conditions internas**: `@statedelta-libs/conditions` não é mais dependência. Conditions são compiladas internamente.
+Ambas as abordagens são **seguras contra injeção de código**:
 
-2. **Expressions nos lados**: `left`/`right` de conditions agora aceitam qualquer `Expression` (`$fn`, `$pipe`, `$if`, etc), não apenas `Ref | literal`.
+| Método | Proteção |
+|--------|----------|
+| `compile()` | Não gera código string - apenas compõe funções |
+| `compileAST()` | Usa destructuring que valida identificadores automaticamente |
 
-3. **Novo builder**: `$cond(left, op, right?)` para construir conditions com expressions:
-   ```typescript
-   $cond($fn("add", [$("a"), $("b")]), "gt", 100)
-   ```
+Funções só são acessíveis se existirem no `scope` fornecido pelo desenvolvedor.
 
-4. **Novos tipos**: `ConditionOp`, `Condition`, `ConditionGroup`, `ConditionExpr` exportados diretamente do expressions.
+## Migração
 
 ### v1.1 → v1.2
 
-1. **Custom Transforms**: Nova option `transforms` em `CompileOptions` e `CompileASTOptions`. Permite estender o walker com tipos de expressão customizados (`$query`, `$mapper`, etc.):
+1. **DSL Puro**: `FnExpr.args` agora é `Expression[]` (removido suporte a callbacks inline). Funções devem ser passadas via scope:
    ```typescript
-   const transforms = {
-     $query: (node) => ({ $fn: "__query", args: [node.$query, node.params ?? {}] }),
-   };
-   compile(expr, { scope, transforms });
-   compileAST(expr, { scope, transforms });
-   ```
+   // Antes (callbacks inline - não funciona mais)
+   { $fn: "filter", args: [(item) => item.active] }
 
-2. **extractDeps com transforms**: `extractDeps` agora aceita `transforms` como segundo argumento para capturar deps dentro de expressões customizadas:
-   ```typescript
-   extractDeps(expr, transforms);
+   // Depois (referência via scope)
+   { $fn: "filter", args: [{ $fn: "isActive" }] }
+   // Com scope: { isActive: (item) => item.active, filter: ... }
    ```
 
-3. **Novos tipos**: `TransformFn` e `TransformResult` exportados diretamente do expressions.
+2. **Removidos**: `CallbackFn`, `FnArg` types
 
-4. **TransformResult**: Transforms podem retornar `TransformResult` com `args: unknown[]` para tipos domain-specific:
+3. **normalize()**: Custom transforms agora são externos via `normalize()`, não mais dentro de `CompileOptions`:
    ```typescript
-   // TransformResult.args aceita unknown[] — sem casts necessários
-   const transforms: Record<string, TransformFn> = {
-     $test: (node) => ({
-       $fn: "__test",
-       args: [node.$test]  // TestSpec, QueryParams, etc.
-     }),
-   };
+   // Antes
+   compile(expr, { scope, transforms });
+
+   // Depois
+   const pure = normalize(expr, transforms);
+   compile(pure, { scope });
    ```
 
-5. **Zero breaking change**: O campo `transforms` é opcional. Sem ele, o comportamento é idêntico ao anterior.
+4. **Novos tipos**: `Transforms` (alias para `Record<string, TransformFn>`)
 
 ## Licença