TypeflowTyped JSON transformations

A declarative mapping language for JSON — validated paths, inferred output types, and compile-time errors instead of production incidents.

Try the Playground

Getting started

GitHub

🧭

Paths are validated

Every path in a mapping is checked against the input type. A typo like user.emial is a compile error with a "Did you mean 'email'?" suggestion.

Paths & optionality

🧠

Output types are inferred

The compiler derives a precise output type from the mapping — optionality included — and emits .d.typeflow.ts declarations so imports are fully typed.

Typed imports

🛡️

Optionality is enforced

Accessing an optional path without ?. is an error. Adding a ?? default removes the optionality from the inferred output type.

See the diagnostic

📦

Mappings are artifacts

Compiled mappings are JSON-serializable and run on a small, deterministic, dependency-free interpreter — Node, Bun, browsers, CI.

Use it from code

🧩

Bring your own functions

A JSONata-level standard library, plus fn definitions, use declarations, and defineFunction — all checked at compile time like builtins.

Custom functions

🔁

Coming from JSONata or jq?

typeflow convert rewrites paths, predicates, lambdas and the stdlib to typed Typeflow — in parallel across files — and tells you exactly what it couldn't convert.

The convert command

Try it — this page runs the real compiler

Everything below is live: edit the mapping or the input and watch the output, the inferred type, and the diagnostics update on every keystroke. No server — the compiler and the runtime are running in your browser.

Mapping✔Playground ↗

input user: {
  id: number,
  firstName: string,
  lastName: string,
  role: "admin" | "member" | "guest",
  contact?: { email?: string },
  labels: { name: string, active: boolean }[],
  scores: number[],
}

fn grade(score: number) = score >= 15 ? "A" : score >= 10 ? "B" : "C"

map {
  id: user.id,
  fullName: user.firstName + " " + user.lastName,
  isAdmin: user.role == "admin",
  email: user.contact?.email ?? "unknown",
  activeTags: user.labels[active].name,
  results: user.scores -> { value: $, grade: grade($) },
}

Input JSON

{
  "id": 42,
  "firstName": "Ada",
  "lastName": "Lovelace",
  "role": "admin",
  "contact": {},
  "labels": [
    { "name": "founder", "active": true },
    { "name": "legacy", "active": false }
  ],
  "scores": [16, 9, 12]
}

Output

{
  "id": 42,
  "fullName": "Ada Lovelace",
  "isAdmin": true,
  "email": "unknown",
  "activeTags": [
    "founder"
  ],
  "results": [
    {
      "value": 16,
      "grade": "A"
    },
    {
      "value": 9,
      "grade": "C"
    },
    {
      "value": 12,
      "grade": "B"
    }
  ]
}

inferred type

{
  id: number;
  fullName: string;
  isAdmin: boolean;
  email: string;
  activeTags: string[];
  results: { value: number; grade: "A" | "B" | "C" }[];
}

Typos are compile errors, not production incidents

This mapping has two classic bugs: a misspelled property and an unguarded optional access. In a plain function they'd ship as silent undefineds — here they never leave your editor. Fix them live: emial → email, and add ?. + ?? on the second line.

Mapping✖ 2Playground ↗

input user: {
  email: string,
  contact?: { phone: string },
}

map {
  mail: user.emial,
  phone: user.contact.phone,
}

Input JSON

{ "email": "ada@lovelace.dev", "contact": { "phone": "+44" } }

Output

// Fix the mapping errors to see the output.

inferred type{ mail: any; phone: string }

7:14errorTF2002Property 'emial' does not exist on type '{ email: string; contact?: { phone: string } }'. Did you mean 'email'?
8:23errorTF2003Object is possibly 'undefined'.
hint: Use the optional access operator: '?.phone', or provide a default with '??'.

Every diagnostic has a stable code, a hint, and a live reproduction in the diagnostics reference.

The whole language is documented from source

Operator pages, the function reference, and the diagnostics reference are generated from the same definitions the compiler executes — signatures, docs and examples can't drift from the implementation. The build fails if an example stops compiling.

builtin functions

typed, documented, live

operators & constructs

each with a playground

diagnostics

documented with live repros

runtime dependencies

Node, Bun, browsers, CI

Why not JSONata, jq, or a plain function?

	Typeflow	JSONata	jq	Zod	Plain TS function
Declarative transformation	✅	✅	✅	❌ (validation)	❌
Input paths statically validated	✅	❌	❌	n/a	✅
Output type inferred	✅	❌	❌	⚠️ declared	✅
Serializable / sandboxable artifact	✅	✅	✅	❌	❌
Deterministic by design	✅	⚠️	✅	n/a	❌

Zod is a natural input to Typeflow, not a competitor: Zod answers "is this X?"; Typeflow answers "how does X become Y, and is that conversion sound?"

Get started in a minute

console

$ bun add -d typeflowjs
$ bunx typeflow init                 # scaffold an example mapping
$ bunx typeflow check                # tsc-style diagnostics
$ bunx typeflow run user.typeflow --input data.json

Read the guide Open the playground Browse all functions