Byron Kennedy

Posted on Jan 18

Quantam: A Lightweight Async Workflow Engine for Node.js

#javascript #node #async #workflow

Quantam: A Clean Async Workflow Engine for JavaScript/TypeScript

Writing asynchronous code in JavaScript/TypeScript can get messy fast. Between nested try/catch, broken retries, and unpredictable behavior, managing complex workflows often feels like juggling knives. That's why we built Quantam, a lightweight async workflow engine designed to make pipelines reliable, readable, and controllable.

The Problem

Without a structured framework, async code tends to spiral out of control:

Messy Promise chains — impossible to follow after a few levels
Nested try/catch everywhere — scattered error handling
Broken retries — manual logic that often fails silently
Race conditions — concurrent tasks stepping on each other
No cancellation — long-running jobs can't be stopped
Lost context — data disappears between steps
Non-deterministic behavior — same input, different output

The Solution

Quantam gives you one clean, fluent API to compose, run, and control async workflows:

const result = await quantam()
  .step(fetchUser)
  .step(enrichUserData)
  .parallel([saveToCache, logAnalytics])
  .retry(3)
  .timeout(5000)
  .run(userId);

With this simple syntax, you can handle retries, parallel execution, timeouts, and cancellations without breaking a sweat.

Key Features

✅ Fluent API — easy to read and write
✅ Sequential & parallel execution — mix steps however you like
✅ Automatic retries — exponential backoff included
✅ Timeouts & cancellation — control SLAs and long-running tasks
✅ Batch processing — run many inputs efficiently
✅ Error propagation — catch errors once at the end
✅ Deterministic & testable — same input produces same output, easy to mock

Quick Start

Install via npm:

npm install quantam-async

Define your async steps:

import { quantam } from 'quantam-async';

// Example async functions
async function fetchUser(id: string) {
  return { id, name: 'Alice' };
}

async function fetchOrders(user: any) {
  return { user, orders: [1, 2, 3] };
}

async function enrichData(data: any) {
  return { ...data, enriched: true };
}

// Compose and run the pipeline
const result = await quantam()
  .step(fetchUser)
  .step(fetchOrders)
  .step(enrichData)
  .run('user-123');

console.log(result);
// { user: { id: 'user-123', name: 'Alice' }, orders: [...], enriched: true }

Parallel Execution Example

await quantam()
  .step(fetchUser)
  .parallel([saveToCache, logAnalytics])
  .run(userId);

Handling Errors

try {
  await quantam()
    .step(riskyOperation)
    .run(input);
} catch (error) {
  console.error('Pipeline failed:', error.message);
}

Cancellation

const controller = new AbortController();
const promise = quantam()
  .step(longTask)
  .run(input, { signal: controller.signal });

// Abort the pipeline later
controller.abort();

Version

v0.1.0 — Core features only. API may change in future versions.

DEV Community