orqis

Structured async task orchestration for Node.js

The gap between p-limit and Bull — without Redis, without boilerplate.

Install

npm install orqis
# or
pnpm add orqis
# or
yarn add orqis

Requirements: Node.js ≥ 16. Works with ESM (import) and CommonJS (require) — zero configuration. Zero production dependencies.

Quick Start

import { TaskQueue } from 'orqis';

const queue = new TaskQueue({ concurrency: 5 });

const urls = [
  'https://api.example.com/users/1',
  'https://api.example.com/users/2',
  // ... hundreds more
];

const users = await queue.addAll(
  urls.map(url => async ({ signal }) => {
    const res = await fetch(url, { signal });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return res.json();
  })
);

console.log(`Fetched ${users.length} users`);

That's it. Concurrency capped at 5. Cancellation-ready. TypeScript-inferred.

Quick Decision Matrix

| Your Need | Use This | |-----------|----------| | Cap concurrency, nothing else | p-limit (~1 KB) | | Concurrency + priorities + timeouts | p-queue | | Concurrency + retries + cancellation + events + plugins | orqis (~5 KB) | | Redis-backed persistent queue across servers | BullMQ | | Cron / recurring jobs | Bree or node-cron | | API rate limiting | Bottleneck |

Orqis is for in-process async orchestration. If your tasks live in a single Node.js process and you need more than a concurrency cap but less than a full Redis-backed job queue, Orqis is the right tool.

The Problem Orqis Solves

You're building a CLI tool, a build script, or a background task runner. You have async work — lots of it — and you need more than raw Promise.all.

Promise.all starts everything at once. Feed it 10,000 URLs and you'll saturate the CPU, exhaust file handles, and get rate-limited by every API in sight. You need:

• Concurrency control — process 8 at a time, not 10,000
• Retries — transient failures happen; tasks should recover without boilerplate
• Timeouts — a hung network call shouldn't stall your entire pipeline
• Cancellation — Ctrl-C should clean up, not leak connections
• Observability — which tasks ran, which failed, how long they took

The existing solutions force a compromise: reach for p-limit and build everything else yourself, or adopt Bull/BullMQ and bring in Redis middleware infrastructure. Orqis fills the gap — production-grade orchestration with zero infrastructure.

Why Orqis

Resilience

• Built-in retry + backoff — exponential, fixed, with jitter. No p-retry wrapper needed.
• Per-task timeouts — hung requests get aborted, not awaited forever.
• stopOnError — halt the pipeline on first failure for build scripts and CI.

Control

• AbortSignal-native cancellation — ctx.signal on every task. Pass it to fetch, streams, database clients. Cancellation propagates cleanly through the call chain.
• TaskGroup scoped cancellation — cancel only the compile phase without touching lint. The missing primitive for structured concurrency.
• Priority queue — binary max-heap; critical tasks jump the line.

Observability

• Lifecycle events — start, success, error, retry, timeout, cancel, idle, empty, active. Every event has typed payloads.
• Plugin system — onBefore, onAfter, onError, onCancel hooks. Built-in logging, metrics, and retry observer. Write custom plugins for Sentry, OpenTelemetry, caching, etc.
• onIdle() / onEmpty() promises — await completion without polling.

Simplicity

• Zero dependencies — 5 KB minzipped. No node_modules baggage, no CVE surface.
• TypeScript-first — strict generics, typed events, no any leakage.
• Dual ESM + CJS — one package, both module systems, no config.
• No infrastructure — runs in-process. No Redis, no Docker, no worker processes.

When Should You Use Orqis

Use Orqis when your answer to one or more of these is "yes":

• You're writing a CLI, build script, test runner, or data pipeline in Node.js
• You need to run N async tasks but cap parallelism below some limit
• Some of those tasks call unreliable external services that need retry logic
• You need to handle Ctrl-C / graceful shutdown cleanly
• You want to log or monitor task progress without wiring up a full observability stack
• You have batches of related tasks that should be cancellable as a unit
• You need different tasks to run with different priorities (critical path vs. background)

Consider alternatives when:

• Tasks must survive process restarts → BullMQ (Redis-backed)
• Work distributes across machines → BullMQ or Agenda
• Recurring cron-style jobs needed → Bree or node-cron
• Only need concurrency control → p-limit
• Reactive stream processing → RxJS

Core Concepts

Tasks

A task is any async function. It receives { signal: AbortSignal } and returns a value. That's the entire interface.

const task = async ({ signal }: { signal: AbortSignal }) => {
  const data = await fetch('/api', { signal });
  return data.json();
};

const result = await queue.add(task);

Pending vs Active

Tasks exist in one of two states. Pending tasks are queued and waiting for a concurrency slot. Active tasks are running. queue.size is pending; queue.pending is active.

| Method | Effect | |--------|--------| | queue.clear() | Removes pending tasks (running continue) | | queue.cancel() | Removes pending + aborts running | | queue.pause() | Stops dequeuing (running continue) |

queue.onIdle() vs queue.onEmpty()

onIdle() resolves when pending = 0 AND running = 0 — everything is done. onEmpty() resolves when the pending queue drains, even if tasks are still running.

TaskGroup

A group is a named batch of tasks that can be awaited or cancelled as a unit, without affecting other work on the same queue.

import { TaskGroup } from 'orqis/group';

const queue  = new TaskQueue({ concurrency: 8 });
const build  = new TaskGroup(queue, { id: 'build' });
const test   = new TaskGroup(queue, { id: 'test' });

build.cancel();            // only build tasks abort
await test.onComplete();   // wait for only test tasks

Comparison

| | orqis | p-limit | p-queue | Bottleneck | Bull | |-|-----------|---------|---------|------------|------| | Size | ~5 KB | ~1 KB | ~25 KB publish | ~15 KB | ~229 KB | | Dependencies | 0 | 0 | 1 | 0 | 8+ | | ESM + CJS | ✅ | ✅ | ESM only | ✅ | ✅ | | TypeScript-first | ✅ | ✅ | ✅ | ❌ | ✅ | | Concurrency cap | ✅ | ✅ | ✅ | ✅ | ✅ | | Priority queue | ✅ | ❌ | ✅ | ✅ | ✅ | | AbortSignal cancellation | ✅ | ❌ | partial | ❌ | ❌ | | Structured concurrency (TaskGroup) | ✅ | ❌ | ❌ | ❌ | ❌ | | Built-in retry + backoff | ✅ | ❌ | ❌ | ❌ | ✅ | | Per-task timeouts | ✅ | ❌ | ✅ | ❌ | ✅ | | Lifecycle events | ✅ | ❌ | ✅ | ❌ | ✅ | | Plugin system | ✅ | ❌ | ❌ | ❌ | ❌ | | Infrastructure required | none | none | none | none | Redis | | Maintenance status | Active | Active | Active | Stale (2019) | Active |

The only things Orqis deliberately omits are persistence, clustering, and cron scheduling — all of which require external infrastructure that most in-process use cases don't need.

Graceful Shutdown

import { TaskQueue } from 'orqis';

const queue = new TaskQueue({ concurrency: 8 });

process.on('SIGINT', async () => {
  console.log('\nShutting down gracefully...');
  queue.pause();
  await queue.onIdle();
  process.exit(0);
});

process.on('SIGTERM', () => {
  queue.cancel();
  process.exit(1);
});

API at a Glance

new TaskQueue(options?)

// Methods
queue.add(task, opts?)      // → Promise<T>
queue.addAll(tasks, opts?)  // → Promise<T[]>
queue.onIdle()              // → Promise<void>
queue.onEmpty()             // → Promise<void>
queue.pause() / resume()
queue.clear() / cancel()
queue.on/off/once(event, fn)

// Properties
queue.size      // pending count
queue.pending   // active count
queue.isPaused
queue.signal    // AbortSignal

// Events
'on start'     → { id }
'on success'   → { id, result, durationMs }
'on error'     → { id, error, attempt }
'on retry'     → { id, attempt, delay }
'on timeout'   → { id }
'on cancel'    → { id }
'on idle' / 'on empty' / 'on active'

Full docs: API Reference

Plugin System

import { loggingPlugin, metricsPlugin, retryObserverPlugin } from 'orqis/plugins';

queue.use(loggingPlugin({ prefix: '[build]', verbose: true }));

const { plugin, snapshot } = metricsPlugin();
queue.use(plugin);
await queue.onIdle();
console.log(snapshot());

queue.use(retryObserverPlugin((id, attempt, delay) => {
  console.warn(`Task ${id} retrying (${attempt}) in ${delay}ms`);
}));

See the Plugin Guide for custom plugin examples (cache, Sentry, OpenTelemetry).

What's Next (Roadmap)

| Version | Focus | |---------|-------| | v1.0 | queue.use() on TaskQueue, rate limiting, 100% coverage | | v1.x | OpenTelemetry plugin, queue.stats(), progress events | | v2.0 | Browser/Worker support, Deno/Bun, optional persistence |

See the full roadmap.

Documentation

| Page | Description | |------|-------------| | Getting Started | Step-by-step from install to first queue | | Core Concepts | How Orqis works internally | | Recipes | Copy-paste patterns for common scenarios | | Plugin System | Logging, metrics, tracing, and custom middleware | | API Reference | Complete type signatures and option tables | | Migration Guide | Moving from p-limit, p-queue, async, fastq | | Testing Guide | How to test queue-based code reliably | | Comparison | Detailed survey of the ecosystem | | Roadmap | Planned features and release milestones | | Wiki | Troubleshooting, FAQs, common errors |

Contributing

git clone https://github.com/AkkilMG/orqis.git
cd orqis && npm install
npm test          # run test suite
npm run build     # compile dist/
npm run typecheck # type-check src/
npm run lint      # ESLint

Read CONTRIBUTING.md before opening a PR. Bug reports go in Issues. Questions go in Discussions.

License

MIT © Akkil M G