iterativeflow

library3.1.0jsnpmunverified

Durable, iterative workflows on your own Postgres. Version 3.1.0 as of 2025, released with monthly cadence. Runs inside your Node app using graphile-worker and drizzle-orm, inspired by Trigger.dev and Temporal, but without a separate service. Supports steps with retries, sleeps for days, external signals, child flows, versioned flows, and at-least-once execution via transactional outbox. Key differentiator: no external service, full control over Postgres schema, Standard Schema validation, and TypeScript-first.

devops database

npm install iterativeflow

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ITERATIVEFLOW

iterativeflow

devopsjavascriptv3.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

flow

✓ import { flow } from 'iterativeflow'

✗ const flow = require('iterativeflow')

ESM-only since v3. Node >=20 required.

createEngine

✓ import { createEngine } from 'iterativeflow'

✗ import { Engine } from 'iterativeflow'

Factory function; no class export. ESM-only.

type FlowBuilder

✓ import type { FlowBuilder } from 'iterativeflow'

✗ import { FlowBuilder } from 'iterativeflow'

Type only; not a runtime value. Using as value causes runtime error.

Shows full setup: create engine, define a simple flow with zod input, register, start, and wait for result. Requires Postgres connection via DATABASE_URL.

import { flow, createEngine } from 'iterativeflow'; import { z } from 'zod'; import { drizzle } from 'drizzle-orm/node-postgres'; import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL ?? '' }); const db = drizzle(pool); const engine = createEngine({ db, pool }); const myFlow = flow('my-flow') .input(z.object({ name: z.string() })) .step('greet', async ({ input }) => `Hello, ${input.name}!`) .build(); const handle = engine.register(myFlow); const { runId } = await handle.start({ name: 'World' }); const result = await handle.result(runId); console.log(result); // 'Hello, World!' await pool.end();

Debug

Known issues

breakingESM-only since v3; require() throws. Node >=20 required.

fix

Use import syntax and upgrade Node to >=20.

affects: >=3.0.0

breakingFlow versioning is compile-time enforced; editing a flow's shape after runs exist will cause a hard error. No silent migration.

fix

Create a new flow version or plan for breaking changes explicitly.

affects: >=1.0.0

gotchaGenerated iterativeflow-schema.ts must be passed to createEngine if customized; otherwise engine uses default workflow.* schema and customizations break.

fix

Pass { tables: flowTables } to createEngine after customizing the generated schema.

affects: >=1.0.0

gotchaSignals may arrive before the flow arms (buffered) or after timeout (expired); handle all four return kinds (delivered, buffered, duplicate, expired).

fix

Check result.kind and respond appropriately as shown in README.

affects: >=1.0.0

deprecatedUsing built-in sleep steps with durations exceeding 999 days may cause integer overflow in Postgres interval.

fix

Upgrade to v3 where sleep is stored as bigint milliseconds.

affects: <3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'iterativeflow'

Missing npm install or ESM-only package used with require()

fix

Run `npm install iterativeflow drizzle-orm graphile-worker pg` and use import syntax.

Error: drizzle-orm version must be >=0.45.0 (found x.y.z)

Incompatible peer dependency version

fix

Run `npm install drizzle-orm@latest` to satisfy peer requirement.

Error: GraphileWorker is not installed. Please run `npm install graphile-worker`

Missing peer dependency graphile-worker

fix

Run `npm install graphile-worker@>=0.16.0`.

Error: relation "workflow.runs" does not exist

Missing generated schema migration in database

fix

Run `npx iterativeflow generate-schema`, then `npx drizzle-kit generate && npx drizzle-kit migrate`.

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

drizzle-ormrequiredRuntime peer dependency for database schema and query building

graphile-workerrequiredRuntime peer dependency for job queue and worker management

pgrequiredRuntime peer dependency for Postgres client

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/ahmedrowaihi/iterativeflow ↗

packageiterativeflow ↗

homepagehttps://github.com/ahmedrowaihi/iterativeflow#readme ↗