Skip to content
Knitting

Welcome to Knitting

Knitting is a shared-memory IPC library for Node.js, Deno, and Bun that makes worker-thread parallelism feel like normal function calls.

You’ve probably tried workers before and thought: this is way more wiring than it should be. That’s exactly why Knitting exists. It gives you multi-core JavaScript without the ceremony, so you can focus on what your code actually does instead of how it talks between threads.

This page walks you through the reasoning, the design, and the trade-offs. If you’d rather just start building, head straight to the Quick Start.

Why Knitting Exists

Section titled “Why Knitting Exists”

JavaScript runs on a single thread. It handles I/O concurrency well, but when you need real CPU parallelism, you need Workers.

The thing is, most developers don’t use them. Not because parallelism isn’t useful, but because the ergonomics got in the way. When a server got hot, it was usually easier to scale out — spin up another process, another container, talk over HTTP — rather than deal with the worker boilerplate.

That works, but the cost adds up: more memory, more moving pieces, more latency, and a communication layer that has nothing to do with your actual logic.

Workers should be the answer. In practice, the workflow looks like this:

  • create a separate worker entry module,
  • build an event protocol on both sides,
  • implement routing and error handling,
  • wrap everything in promises,
  • track request IDs (and ordering, if FIFO matters),
  • then realize IPC overhead makes many small tasks not worth offloading.

None of that is hard. It’s just a lot of plumbing for something that should feel like calling a function.

The problem isn’t compute. The problem is the cost of reaching the compute.

With Knitting, that entire workflow collapses to about ten lines:

hello_world.ts
import { isMain, task } from "@vixeny/knitting";


export const world = task({
  f: (args: string) => args + " world",
}).createPool();


if (isMain) {
  world.call("hello")
    .then(console.log).finally(world.shutdown);
}

Three steps:

  • define tasks once,
  • spin up a pool,
  • call them like functions.

The result is a worker workflow that stays out of your way and can run 4x to 200x faster than message-based IPC in communication-focused microbenchmarks for small-to-medium, high-frequency tasks. That reflects IPC overhead reduction, not an automatic end-to-end app speedup.

Node.js shared-memory IPC benchmark

What Knitting Is

Section titled “What Knitting Is”

At its simplest: a shared-memory IPC transport for JavaScript runtimes that keeps things simple.

For the technically curious:

Knitting is a full-duplex shared-memory IPC transport built from two independent 32-slot shared mailboxes (request and response), using bitset slot ownership and futex-style wakeups with optional spin-pause.

The design rests on a few deliberate choices.

Core Design Principles

Section titled “Core Design Principles”

Tasks, not messages You export functions. The pool executes them. No message protocols, no custom serialization layers between you and the work.

Explicit configuration Routing strategy, batching limits, stall backoff, timeouts, and inline execution are choices you make, not hidden defaults.

Efficient idle behavior Workers spin briefly when needed, trigger a garbage collection if no work arrives (so the idle time is productive, not wasted), then park and wake only when there’s actual work. No CPU burn while waiting.

The Worker Runtime

Section titled “The Worker Runtime”

Each worker is a real OS thread spawned through the runtime’s native worker API (worker_threads on Node, Worker on Deno and Bun). When a pool starts, every worker goes through the same lifecycle:

  1. Boot — the worker process starts and imports your task modules from the URL list passed at spawn time. Each exported task becomes an entry in an internal function table, indexed by task ID.
  2. Signal ready — the worker writes a status flag into shared memory so the host knows this lane is available.
  3. Enter the main loop — a tight cycle that runs three phases per iteration:
    • Enqueue — read new request slots from the shared request mailbox.
    • Service — execute pending tasks (sync or async) in batches of up to 32.
    • Write-back — flush completed results into the response mailbox so the host can resolve promises.
  4. Sleep when idle — when there’s nothing to do, the worker spins briefly (configurable via spinMicroseconds). If no work arrives during the spin window, it triggers a garbage collection (global.gc()) — using idle time productively instead of just spinning. Then it parks using Atomics.wait (a futex-style block). It stays parked — zero CPU — until the host writes new work and wakes it with Atomics.notify.

Async tasks (functions returning a promise) are fully awaited inside the worker before the result is written back. There are no half-resolved values crossing the thread boundary.

This loop is the same on all three runtimes. The only runtime-specific part is how the worker thread is created — after that, everything runs through shared memory.

Why It’s Fast (and When That Matters)

Section titled “Why It’s Fast (and When That Matters)”

The performance gains aren’t magic — they come from removing the overhead that makes workers impractical for small tasks:

  • Low IPC overhead: shared-memory mailboxes skip serialization and message hops entirely.
  • Batch-friendly execution: work is encoded, dispatched, and resolved through a pipelined flow.
  • GC when idle, sleep when quiet: workers run garbage collection during idle spin windows (so idle time is productive), then park and wake only when there’s work.
  • Event-loop friendly: everything cooperates with the event loop. No blocking, no forced await, just predictable behavior.
  • Pressure-responsive: higher load improves throughput instead of stalling.

This matters most when the coordination cost would otherwise dominate the actual computation.

Knitting doesn’t make slow code fast. It makes parallel code cheap enough to be worth writing.

What Knitting Is Good For

Section titled “What Knitting Is Good For”

Knitting is built for workloads where CPU pressure comes in bursts and you need the main thread to stay responsive:

Design Boundaries

Section titled “Design Boundaries”

It solves one problem well and doesn’t try to be everything. Being upfront about that saves everyone time.

**Not a replacement for postMessage: ** postMessage is great for general-purpose messaging. Knitting occupies a different niche: structured task execution with minimal overhead. Use whichever fits your workload, or both.

No edge runtimes yet Node.js, Deno, and Bun are the current targets. Edge runtimes have different isolation models, limited shared memory, and different module lifecycles. Supporting them properly would require careful design, not a quick port.

Remote imports (with caution) Knitting can load task modules from remote sources, but doing so widens your trust boundary. Because of security and supply-chain concerns, remote import support may be restricted or removed in future releases.

Not a distributed system Knitting operates within a single process, across threads, using shared memory. If you need cross-machine distribution, Knitting is meant to complement that layer, not replace it.