Overview

typemaid runs workflows whose shape you can see. The flow lives in a .mmd file that any Mermaid viewer can draw; each box in the diagram is a TypeScript function checked with Zod.

flows/hello.mmd   ──►   tools.ts (typed steps)   ──►   run()  ──►  completed | paused | failed

Docs: getting started · durability · retries · stores · models · FAQ

Status: v0, not published to npm yet. The name and the .mmd extension can still change (see Renaming).

Install

npm install typemaid zod

Works the same with bun add, pnpm add or yarn add. Zod 4.2 or newer is required. Nothing else is installed with it.

The workflow viewer is a separate, optional package, so projects that only run workflows stay small:

npm install -D @typemaid/view
Runtime What works Checked by
Node 22+ Everything bun run runtimes on Node 22 and 24
Bun 1.2+ Everything the test suite
Browsers, edge workers (Cloudflare, Vercel Edge) The core: compile, check, run, pause and resume. Pass the diagram as text, not a file path. No SQLite store, CLI or viewer. a sandbox with no Node APIs
Deno Expected to work like Node; not tested yet not checked

The package is ES modules only. require('typemaid') works on Node 22.12+ and Bun.

Import What it is
typemaid run, resume, compile, check, tool, agent, human, the memory store
typemaid/ai defineAI: set the model once, for agent steps and for model calls inside tools
typemaid/sqlite a store that keeps runs in a SQLite file
typemaid/node file helpers used by the CLI and the viewer: find diagram files and load the tools file next to them
@typemaid/view the workflow viewer (separate package)
@typemaid/postgres a store that keeps runs in Postgres (separate package)
@typemaid/libsql a store that keeps runs in libSQL or Turso (separate package)
flows/hello.mmd     the diagram: what runs, in what order
flows/tools.ts       the steps: typed with Zod
index.ts             one call to run()

hello.mmd is plain Mermaid. It previews in any Mermaid viewer.

flowchart TD
  greet --> shout --> done([Done])

tools.ts: each node name in the diagram is an export here.

import { z } from 'zod';
import { tool } from 'typemaid';

export const greet = tool({
  input: z.object({ name: z.string() }),
  output: z.object({ greeting: z.string() }),
  run: ({ name }) => ({ greeting: `Hello, ${name}` }),
});

export const shout = tool({
  input: z.object({ greeting: z.string() }),
  output: z.object({ loud: z.string() }),
  run: ({ greeting }) => ({ loud: `${greeting.toUpperCase()}!` }),
});

index.ts

import { run } from 'typemaid';
import * as tools from './flows/tools.ts';

const result = await run('./flows/hello.mmd', tools, { name: 'Ada' });
// { status: 'completed', runId: '…', output: { name: 'Ada', greeting: 'Hello, Ada', loud: 'HELLO, ADA!' } }

Run it with Bun, which reads TypeScript directly:

bun index.ts

Or from the command line:

bunx typemaid run flows/hello.mmd --input '{"name":"Ada"}'

Bun is the tool used to develop and test this package. The built package also runs on Node 22.18 or newer.

How data moves

Every step’s output is merged into one shared set of fields. A step receives the fields its input schema names, picked out by name. Fields that no step produces must be passed to run(); you get an error before anything runs if one is missing.

What you can draw

In the diagram Meaning
a --> b run a, then b
name[Any text] a step; name is the export it runs, the text is only a label
first[$double] a step that runs the export double (to use one tool at two nodes)
ok{"score >= 8"} or ok{passes} a decision; needs two arrows labelled yes and no
ok -->|no, max 5| draft an arrow back makes a loop; every loop needs a max
two unlabelled arrows out of one node run both branches at the same time; they join where they meet
arrows labelled approved / rejected out of a step the step’s decision output picks one
([Done]) a start or end marker; runs nothing
no :::start anywhere the flow starts at the one node with no arrow into it; if every node is in a loop, at the node written first
:::start on several nodes named entry points: run(flow, tools, input, { start: 'webhook' })
subgraph each["for email in emails"] + class each foreach run the block once per list item, a few at a time
:::agent, :::human optional; checked against what the export really is

Conditions can compare fields with numbers (10, -2.5), text and true/false/null using == != > >= < <=, combine with and or not, use brackets, read nested fields (user.age) and .length. Text goes in single quotes: {"status == 'ok'"}. Or name an exported function (ctx) => boolean.

Anything else Mermaid allows (other arrow styles, &, click actions, directives, other shapes) is rejected with a message, never silently ignored. Styling lines (classDef, style, linkStyle, direction, frontmatter) are allowed and have no effect.

Kinds of step

import { human, tool } from 'typemaid';

// Your code. `ctx.key` is the same if the step is retried or re-run after a crash.
export const charge = tool({
  input: z.object({ amount: z.number() }),
  output: z.object({ receipt: z.string() }),
  retries: 2,
  timeoutMs: 10_000,
  run: ({ amount }, ctx) => payments.charge(amount, { idempotencyKey: ctx.key, signal: ctx.signal }),
});

// Pauses the run until someone answers.
export const approve = human({ resume: z.object({ note: z.string().optional() }) });

Model calls

Model calls go through the Vercel AI SDK, so any provider it supports works. Install it and one provider:

npm install ai @ai-sdk/openai

Choose the model once, in your tools file:

import { openai } from '@ai-sdk/openai';
import { defineAI } from 'typemaid/ai';

export const ai = defineAI({ model: openai('gpt-5-mini') });

The provider is imported from the AI SDK’s own package (@ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google, …). This package does not re-export them, so you install only the ones you use and control their versions.

An agent step asks the model for structured output. {text} is filled in from the shared fields.

export const summarize = ai.agent({
  instructions: 'You write short, factual summaries.',
  prompt: 'Summarize as bullet points:\n\n{text}',
  output: z.object({ bullets: z.array(z.string()) }),
});

Inside any tool, call the model with ai.ask (a checked object) or ai.text (plain text). Pass the tool’s ctx, so the call is cancelled if the step times out or the run is cancelled.

export const triage = tool({
  input: z.object({ review: z.string() }),
  output: z.object({ sentiment: z.enum(['positive', 'negative']), reply: z.string() }),
  run: async ({ review }, ctx) => {
    const { sentiment } = await ai.ask(ctx, {
      prompt: `Is this review positive or negative? "${review}"`,
      output: z.object({ sentiment: z.enum(['positive', 'negative']) }),
    });
    const reply = await ai.text(ctx, { prompt: `Reply in one sentence to this ${sentiment} review: "${review}"` });
    return { sentiment, reply };
  },
});

An agent can use AI SDK tools while it works out its answer. A limit on turns is required.

import { tool as aiTool } from 'ai';

const stock = aiTool({
  description: 'Look up how many units are in stock.',
  inputSchema: z.object({ product: z.string() }),
  execute: async ({ product }) => inventory.count(product),
});

export const check = ai.agent({
  prompt: 'How many units of {product} are in stock?',
  tools: { stock },
  maxSteps: 4,
  output: z.object({ units: z.number() }),
});

What to know:

Results, pausing and resuming

run() returns one of three shapes:

{ status: 'completed', runId, output }
{ status: 'paused',    runId, waitingAt: [{ node, fields, options }] }
{ status: 'failed',    runId, error: { code, message, node } }
import { resume } from 'typemaid';
import { sqliteStore } from 'typemaid/sqlite';

const store = sqliteStore('./runs.db');
const paused = await run('./flows/triage.mmd', tools, { ticketId: 'T-1' }, { store });
// later, even in another process:
await resume(paused.runId, tools, { decision: 'approved', note: 'ok' }, { store });

resume() also retries a failed run from the step that failed, and continues a run whose process died.

Without a store, runs are kept in memory and lost when the process exits. From the command line, pass --store runs.db to run if the flow can pause.

If the diagram text comes from someone you do not trust, call compile(text) yourself and pass the result to run(). A plain string passed to run() is read as a file when it ends in .mmd or .mermaid (or starts with file:), and as diagram text otherwise.

Checking

bunx typemaid check flows

Reports problems with file, line and a suggested fix, and exits 1 on errors (--json for tools). It works in stages: all syntax problems first; once the syntax is clean, all structure problems (loops, starts, parallel blocks); then all tool and data problems.

flows/hello.mmd:2:13  error E1201  The box `shuot` needs a tool named `shuot`, and there is none in the tools you passed. Did you mean `shout`?
   2 |   greet --> shuot
     |             ^

The same checks run automatically inside run().

Seeing your workflows

npm install -D @typemaid/view
bunx typemaid view flows

Opens a page that draws your workflows. Give it one file and it opens on that diagram; give it a folder and it lists every workflow in it. The page updates when you save a file.

The list of all workflows

One workflow, with a step selected

From code:

import { view } from '@typemaid/view';

const viewer = await view('./flows', { open: true });
console.log(viewer.url);
// later
await viewer.close();

What to know:

How the viewer is put together

The viewer lives in its own package, packages/view, published as @typemaid/view. It depends on the core; the core never depends on it. Both carry the same version and are released together. Without it, typemaid view prints how to install it.

The page is not tied to how the SDK works inside. It reads one small, versioned JSON format over HTTP, and that is all it knows.

Piece (in packages/view) Job
src/contract.ts The JSON format. No imports. Has a schemaVersion.
src/project.ts The one place that turns SDK results into that format.
src/source.ts, source-fs.ts Where data comes from. Today: files on disk.
src/handler.ts A standard (Request) => Response function serving /api/v1/... and the page.
src/index.ts view(): starts a local server around the handler.
ui/ The page itself, built ahead of time into dist/ui.

A hosted version can reuse the same page by serving the same /api/v1 format from somewhere else. Tests enforce the boundaries: the viewer reaches the core only through typemaid and typemaid/node, the page may import only types from the contract, and the handler may import only the contract.

The page is built with only Mermaid’s flowchart support. The other diagram types, the maths renderer and the larger layout engines are left out, which keeps it under 1 MB. The build fails if the page grows past 1.5 MB.

Guarantees and limits (v0)

Development

Bun is used for installing packages, running code and testing.

bun install
bun run test
bun run test:live
bun run smoke

Renaming

The product name, CLI name and accepted file extensions live in src/brand.ts (plus package.json). Stored runs and error codes do not contain the name. A test fails if the name appears anywhere else in src/. The viewer package also names the core in its imports and its package.json.

Design notes and the reasoning behind these choices are in SDK-DESIGN-GUIDE.md.

Licence

LICENSE.md (FSL-1.1-MIT).

The viewer page bundles third-party libraries (Mermaid, Preact and their dependencies), which remain under their own licences. Their licence texts are written to packages/view/THIRD-PARTY-NOTICES.md by the build and ship with that package.