release: WRNexusJS 0.8.0

packages/queue/README.md

@@ -43,33 +43,45 @@ function createQueue(options?: QueueOptions): Queue;
 | `backoffMs`   | `number`                             | `1000`     | Base retry backoff in ms; doubles per attempt.           |
 | `pollMs`      | `number`                             | `250`      | Poll interval used once `start()` is called (ms).        |
 | `onFailed`    | `(job: Job, error: unknown) => void` | —          | Called when a job exhausts its attempts.                 |
+| `concurrency` | `number`                             | unlimited  | Maximum jobs claimed by one `drain()` call.              |
+| `capacity`    | `number`                             | unlimited  | Maximum queued plus active jobs before adds reject.      |
 | `now`         | `() => number`                       | `Date.now` | Clock injection for deterministic tests.                 |
 
 ### `Queue`
 
 The object returned by `createQueue`.
 
-| Method    | Signature                                                      | Description                                                    |
-| --------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
-| `add`     | `add<T>(name, data: T, options?: AddOptions): Promise<Job<T>>` | Enqueue a job under a worker name. Returns the created job.    |
-| `process` | `process<T>(name, handler: JobHandler<T>): void`               | Register the worker that runs jobs of the given name.          |
-| `drain`   | `drain(now?: number): Promise<number>`                         | Run every job whose `runAt ≤ now`, once. Returns how many ran. |
-| `start`   | `start(): void`                                                | Begin polling every `pollMs`. No-op if already started.        |
-| `stop`    | `stop(): void`                                                 | Stop the poll timer.                                           |
-| `size`    | `size(): number`                                               | Number of jobs currently queued.                               |
+| Method     | Signature                                                      | Description                                                    |
+| ---------- | -------------------------------------------------------------- | -------------------------------------------------------------- |
+| `add`      | `add<T>(name, data: T, options?: AddOptions): Promise<Job<T>>` | Enqueue a job under a worker name. Returns the created job.    |
+| `process`  | `process<T>(name, handler: JobHandler<T>): void`               | Register the worker that runs jobs of the given name.          |
+| `drain`    | `drain(now?: number): Promise<number>`                         | Run every job whose `runAt ≤ now`, once. Returns how many ran. |
+| `start`    | `start(): void`                                                | Begin polling every `pollMs`. No-op if already started.        |
+| `stop`     | `stop(): void`                                                 | Stop the poll timer.                                           |
+| `shutdown` | `shutdown({ force? }): Promise<void>`                          | Stop accepting jobs and await active work; force aborts it.    |
+| `size`     | `size(): number`                                               | Number of jobs currently queued.                               |
+| `get/list` | `get(id)` / `list(name?)`                                      | Inspect defensive copies of pending jobs.                      |
+| `cancel`   | `cancel(id): boolean`                                          | Remove queued work or abort an active handler.                 |
+| `failed`   | `failed(): Job[]`                                              | Inspect exhausted jobs in the dead-letter collection.          |
+| `retry`    | `retry(id): Promise<boolean>`                                  | Reset and requeue a dead-lettered job.                         |
 
 #### `AddOptions`
 
-| Option        | Type     | Description                                                                |
-| ------------- | -------- | -------------------------------------------------------------------------- |
-| `delayMs`     | `number` | Delay before the job becomes runnable (ms).                                |
-| `maxAttempts` | `number` | Max attempts before dead-lettering. Defaults to the queue's `maxAttempts`. |
-| `repeat`      | `number` | Re-enqueue this job this many ms after each successful run (recurring).    |
+| Option           | Type     | Description                                                                |
+| ---------------- | -------- | -------------------------------------------------------------------------- |
+| `delayMs`        | `number` | Delay before the job becomes runnable (ms).                                |
+| `maxAttempts`    | `number` | Max attempts before dead-lettering. Defaults to the queue's `maxAttempts`. |
+| `repeat`         | `number` | Re-enqueue this job this many ms after each successful run (recurring).    |
+| `priority`       | `number` | Higher values are selected first among due jobs.                           |
+| `idempotencyKey` | `string` | Return the matching pending job instead of enqueueing a duplicate.         |
 
 #### `JobHandler<T>`
 
 ```ts
-type JobHandler<T = unknown> = (job: Job<T>) => void | Promise<void>;
+type JobHandler<T = unknown> = (
+  job: Job<T>,
+  context: { signal: AbortSignal },
+) => void | Promise<void>;
 ```
 
 #### `Job<T>`
@@ -106,6 +118,18 @@ await queue.add("email", { to: "a@b.com" }, { delayMs: 5000, maxAttempts: 3 });
 queue.start(); // begin polling; queue.stop() to halt
 ```
 
+Use `context.signal` in network/database calls so forced shutdown and active
+cancellation finish promptly. For process termination, prefer
+`await queue.shutdown()`; use `{ force: true }` only after your grace period.
+
+### Durable queue
+
+`createDurableQueue({ store })` retains jobs until their handler succeeds and
+supports atomic leases when a driver implements `QueueStore.claim`. It exposes
+the same cancellation/shutdown behavior plus `list`, `failed`, and `retry`.
+The included `memoryQueueStore()` is useful for tests; production Redis/SQL
+drivers should make `claim()` atomic to prevent two workers executing one job.
+
 ### Recurring jobs
 
 Pass `repeat` to re-enqueue a job a fixed interval after each successful run:
@@ -145,6 +169,29 @@ clock = 5000;
 const ran = await queue.drain(); // => 1
 ```
 
+### Durable workflows and approvals
+
+`createWorkflowEngine(store)` executes dependency-ordered steps and persists every transition,
+result, progress update, failure, cancellation, and approval record. Approval steps pause safely
+and can resume after a process restart because the snapshot lives in the supplied `WorkflowStore`.
+
+```ts
+const workflow = defineDurableWorkflow({
+  name: "publish-report",
+  steps: [
+    { name: "build", run: buildReport },
+    { name: "approve", dependsOn: ["build"], approval: true, run: (report) => report },
+    { name: "publish", dependsOn: ["approve"], run: publishReport },
+  ],
+});
+
+const run = await engine.start(workflow, input);
+await engine.approve(workflow, run.id, "approve", currentUser.id);
+```
+
+Use `memoryWorkflowStore()` for tests. Production stores implement the small `get`, `put`, and
+`list` contract using the same transactional database or durable service as the application.
+
 ## Retry & backoff behavior
 
 - On a thrown handler error, the job is retried while `attempts < maxAttempts`.