# Knitting

> Knitting is a zero-dependency worker pool over a shared-memory IPC runtime for Node.js, Deno, and Bun. Export a function, create a pool, and call it like a normal async function — on real threads or isolated processes.

**Building with Knitting? Fetch [llms-full.txt](https://knittingdocs.netlify.app/llms-full.txt) first** — it inlines every documentation page into one file. The essentials below cover the common path; the full text covers everything else.

## Essentials (read this first)

- Install: `npm install knitting` (the npm package is `knitting`; it is also on JSR as `@vixeny/knitting`). Requires Node 22+, Deno 2+, or Bun 1+.
- A task is an exported function at module scope. Wrap it with `task({ f })` only when you want options like a timeout or an abort signal.
- Tasks take ONE argument. Use a tuple or object for multiple values: `([a, b]) => a + b`.
- Guard host-only code with `isMain` — workers re-import the module.
- Module loading: each worker re-imports the module that DEFINES your tasks, and its top-level `import`s run in every worker (they are hoisted — `isMain` does NOT gate them). Keep tasks in a lean module separate from your server/framework code. Tasks must be `export`ed or the loader can't find them and the call silently hangs. `importTask` targets must be plain functions, not `task()` wrappers.
- Create a pool with `createPool(options)({ taskA, taskB })`, then call `await pool.call.taskA(args)`.
- Cleanup: `using pool = createPool(...)` disposes the pool at scope exit. `await pool.shutdown()` still exists to close it earlier or to await teardown.
- Isolation: `importTask({ href, name })` keeps a task's code off the host (only the worker imports it). Set `worker.runtime: "process"` to run each worker as a separate process — including inside a bwrap sandbox or a container.
- Security: for untrusted or security-sensitive code, define the task with `importTask`. The host holds only a typed wrapper and never imports or evaluates the module, so that code runs only in the worker (under its permissions), never at host scope.
- Zero-copy IN: `ProcessSharedBuffer` (`knitting/process-shared-buffer`) shares bytes across processes; `SharedArrayBuffer` and `BufferReference` (`knitting/unsafe`) move bytes to thread workers without copying. Pick by boundary — process vs thread.
- Zero-copy OUT (good practice): for large binary results from a thread worker, RETURN a `BufferReference` so bytes move back instead of being copied through the transport. `knitting/utils` converts string/JSON/number ↔ `SharedArrayBuffer`.
- Optimized for HTTP: `call.*()` accepts `Promise<supported>` inputs, so forward `request.arrayBuffer()` (e.g. Hono `c.req.arrayBuffer()`) straight into a task without awaiting it on the request thread — UTF-8 decode / JSON parse then happens in the worker. Ideal for SSR, JWT, and upload routes.
- Workers are quiet and contained by default: in strict mode (the default) worker `console.*` does NOT reach the host — set `permission: { console: true }` to surface it. Task code cannot take the host down: `process.exit`, `process.kill`, `process.abort`, and `Deno.exit` are blocked.
- Debugging goes to STDERR: pass `debug: true` to `createPool` (or set the `KNITTING_DEBUG=*` env var) to stream diagnostics, each line tagged with the worker (`host`, `w0`, `w1`, …), the runtime, and a per-worker ms timer. Select namespaces instead of all — `host` (pool/task setup), `imports` (which modules each worker loaded), `lifecycle` (worker ready / process events), `signals` (per-dispatch traffic, very chatty), `globals` (`globalThis` pollution per load phase) — via `debug: { host: true, imports: true }` or `KNITTING_DEBUG=host,imports`. The option and the env var merge; either can enable a namespace. Zero-cost when off: the logger module isn't even imported.
- Payload size: dynamic payloads are hard-capped at ~8 MiB by default (over-cap calls reject with `KNT_ERROR_3`). Raise it with `payload: { maxPayloadBytes, payloadMaxByteLength }` — `maxPayloadBytes` must be `<= payloadMaxByteLength >> 3`; the buffer growth cap defaults to 64 MiB.
- Cancellation & timeouts: `task({ f, timeout: { time: 100 } })` bounds a call, `task({ f, abortSignal: true })` injects an `AbortSignal`, and `worker.hardTimeoutMs` is a hard wall-clock kill for runaway CPU.
- Errors are real: thrown errors and rejected promises return to the host as `Error` objects with `name`, `message`, `stack`, and the full `cause` chain.

```ts
import { createPool, isMain } from "knitting";

export const square = (n: number) => n * n;
export const greet = (name: string) => `hello ${name}`;

if (isMain) {
  // `using` shuts the pool down when this block ends.
  using pool = createPool({ threads: 2 })({ square, greet });

  const [n, msg] = await Promise.all([
    pool.call.square(8),
    pool.call.greet("knitting"),
  ]);
  console.log({ n, msg }); // { n: 64, msg: "hello knitting" }
}
```

## Getting Started

- [Installation](https://knittingdocs.netlify.app/start/installation/): Install Knitting from npm for Node.js, Deno, and Bun, and verify runtime requirements for shared-memory worker IPC.
- [Quick Start](https://knittingdocs.netlify.app/start/quick-start/): Build your first Knitting worker pool, define tasks, call them like async functions, run them in parallel, and shut down cleanly with `using`.
- [Welcome to Knitting](https://knittingdocs.netlify.app/start/welcome/): Learn what Knitting is, why shared-memory IPC matters, and when to use worker pools in Node.js, Deno, and Bun.

## Guides

- [Defining tasks](https://knittingdocs.netlify.app/guides/defining-tasks/): A task is a function your workers run. Use a plain function for the simple case, or task() when you want timeouts, aborts, or imported worker code.
- [Creating pools](https://knittingdocs.netlify.app/guides/creating-pools/): Spin up workers and call tasks.
- [Payloads](https://knittingdocs.netlify.app/guides/payloads/): Data types you can send through knitting.
- [Buffer utilities](https://knittingdocs.netlify.app/guides/utils/): knitting/utils — helpers for serializing strings, JSON, and numbers into SharedArrayBuffer and back.
- [Permissions](https://knittingdocs.netlify.app/guides/permissions/): Runtime permission policy for worker processes.
- [Process workers](https://knittingdocs.netlify.app/guides/process-workers/): Run each worker as a separate OS process for stronger isolation — through a sandbox like bubblewrap or a container like Docker.
- [Shared memory](https://knittingdocs.netlify.app/guides/shared-memory/): ProcessSharedBuffer — the lower-level shared-memory channel for passing bytes between workers and processes without copying.
- [Buffer reference](https://knittingdocs.netlify.app/guides/buffer-reference/): knitting/unsafe — zero-copy ArrayBuffer handles for thread workers.
- [Performance](https://knittingdocs.netlify.app/guides/performance/): Tips about performance and good practices.
- [Inliner](https://knittingdocs.netlify.app/guides/inliner/): Run pure compute on the host thread as an extra lane.

## Examples

- [Examples](https://knittingdocs.netlify.app/examples/intro_examples/): Practical, copyable patterns for using Knitting in real workloads.
- [Data transforms](https://knittingdocs.netlify.app/examples/data_transforms/intro_data_transforms/): Validation, rendering, and output examples -- pick the one closest to your workload.
- [Big prime](https://knittingdocs.netlify.app/examples/maths/big_prime/): Parallel prime search through large integers with Miller-Rabin
- [React SSR](https://knittingdocs.netlify.app/examples/data_transforms/rendering_output/react_ssr/): Render React components to HTML strings on workers -- the example closest to a real server workload.
- [Schema validate](https://knittingdocs.netlify.app/examples/data_transforms/validation/schema_validate/): Validate JSON payloads against a Zod schema on workers.
- [JWT revalidation](https://knittingdocs.netlify.app/examples/data_transforms/validation/jwt_revalidation/): Verify JWTs and optionally reissue them using Web Crypto -- no external JWT library needed.
- [Monte Carlo pi](https://knittingdocs.netlify.app/examples/maths/monte_pi/): Estimate pi by throwing darts at a circle -- embarrassingly parallel
- [React SSR compression](https://knittingdocs.netlify.app/examples/data_transforms/rendering_output/react_ssr_compress/): SSR + Brotli compression on workers -- testing where compression should live.
- [Markdown to HTML](https://knittingdocs.netlify.app/examples/data_transforms/rendering_output/markdown_to_html/): Convert markdown to HTML with Brotli compression -- a simple transform pipeline.
- [Physics loop](https://knittingdocs.netlify.app/examples/maths/physics_loop/): 2D random walk simulation -- branch-heavy physics loop parallelized across workers
- [Salt hashing](https://knittingdocs.netlify.app/examples/data_transforms/validation/salt_hashing/): PBKDF2 password hashing with constant-time verification -- the heaviest per-call workload in the validation set.
- [Hono server routes](https://knittingdocs.netlify.app/examples/data_transforms/rendering_output/hono_server/): Build a Hono server with ping, SSR, and JWT routes in Knitting or host-only mode.
- [Prompt token budgeting](https://knittingdocs.netlify.app/examples/data_transforms/validation/prompt_token_budgeting/): Trim LLM prompts to fit a token budget before sending them to any model.
- [TSP (GSA)](https://knittingdocs.netlify.app/examples/maths/tsp_gsa/): Parallel heuristic restarts for a gravity-inspired TSP solver

## Benchmarks

- [Benchmarks](https://knittingdocs.netlify.app/benchmarks/introduction/): Overall benchmark overview across Node, Deno, and Bun, plus a Tokio comparison for primitive and small-payload benchmark shapes.
- [Node.js](https://knittingdocs.netlify.app/benchmarks/node/): Node.js benchmark results for Knitting, including IPC latency, worker comparison, call-growth transfer throughput, heavy-load scaling, and payload type costs.
- [Deno](https://knittingdocs.netlify.app/benchmarks/deno/): Deno benchmark results for Knitting, including IPC latency, worker comparison, call-growth transfer throughput, heavy-load scaling, and payload type costs.
- [Bun](https://knittingdocs.netlify.app/benchmarks/bun/): Bun benchmark results for Knitting, including IPC latency, worker comparison, call-growth transfer throughput, heavy-load scaling, and payload type costs.
- [Tokio](https://knittingdocs.netlify.app/benchmarks/tokio/): Tokio benchmark comparison for Knitting, covering scalar latency, 1 MiB payload behavior, byte-size sweeps, an Arc<Vec<u8>> reference sweep, and the benchmark fairness model.

## Extras

- [Architecture](https://knittingdocs.netlify.app/extras/architecture/): How Knitting's shared-memory transport, mailbox protocol, and lane model work under the hood.

## Full text

- [llms-full.txt](https://knittingdocs.netlify.app/llms-full.txt): every documentation page inlined into one file.