@c9up/bay 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @c9up/bay — Background job queue for the Ream framework.
+ *
+ * Dispatch/process/retry/fail pattern with pluggable drivers (Memory, Redis).
+ *
+ * @implements MISS-11
+ */
+export { MemoryDriver } from "./drivers/MemoryDriver.js";
+export type { RedisClient } from "./drivers/RedisDriver.js";
+export { RedisDriver } from "./drivers/RedisDriver.js";
+export type { Job, JobHandler, QueueDriver } from "./QueueManager.js";
+export { QueueManager } from "./QueueManager.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EAAE,GAAG,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @c9up/bay — Background job queue for the Ream framework.
+ *
+ * Dispatch/process/retry/fail pattern with pluggable drivers (Memory, Redis).
+ *
+ * @implements MISS-11
+ */
+export { MemoryDriver } from "./drivers/MemoryDriver.js";
+export { RedisDriver } from "./drivers/RedisDriver.js";
+export { QueueManager } from "./QueueManager.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/services/main.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Default `QueueManager` singleton — mirror of Adonis's
+ * `import queue from '@adonisjs/queue/services/main'` shape.
+ *
+ * Populated by either:
+ *   - `BayProvider.boot()`, when the app uses `() => import('@c9up/bay/provider')`
+ *   - The app itself, via `setQueue(myQueue)`, when it wires a
+ *     custom-driver `QueueManager` outside the provider flow.
+ *
+ *   import queue from '@c9up/bay/services/main'
+ *
+ *   queue.register('send-email', new SendEmailJob())
+ *   await queue.dispatch('send-email', { to: 'user@example.com' })
+ */
+import type { QueueManager } from "../QueueManager.js";
+/** @internal Bind the singleton (called by BayProvider or by the app). */
+export declare function setQueue(value: QueueManager): void;
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export declare function getQueue(): QueueManager | undefined;
+declare const queue: QueueManager;
+export default queue;
+//# sourceMappingURL=main.d.ts.map

package/dist/services/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAElD;AAED,8DAA8D;AAC9D,wBAAgB,QAAQ,IAAI,YAAY,GAAG,SAAS,CAEnD;AAED,QAAA,MAAM,KAAK,EAAE,YAWX,CAAC;AAEH,eAAe,KAAK,CAAC"}

package/dist/services/main.js

@@ -0,0 +1,35 @@
+/**
+ * Default `QueueManager` singleton — mirror of Adonis's
+ * `import queue from '@adonisjs/queue/services/main'` shape.
+ *
+ * Populated by either:
+ *   - `BayProvider.boot()`, when the app uses `() => import('@c9up/bay/provider')`
+ *   - The app itself, via `setQueue(myQueue)`, when it wires a
+ *     custom-driver `QueueManager` outside the provider flow.
+ *
+ *   import queue from '@c9up/bay/services/main'
+ *
+ *   queue.register('send-email', new SendEmailJob())
+ *   await queue.dispatch('send-email', { to: 'user@example.com' })
+ */
+let instance;
+/** @internal Bind the singleton (called by BayProvider or by the app). */
+export function setQueue(value) {
+    instance = value;
+}
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getQueue() {
+    return instance;
+}
+const queue = new Proxy({}, {
+    get(_target, prop) {
+        if (!instance) {
+            throw new Error("[bay] QueueManager singleton accessed before BayProvider.boot() ran " +
+                "or `setQueue(myQueue)` was called. Wire one of them first.");
+        }
+        const value = Reflect.get(instance, prop, instance);
+        return typeof value === "function" ? value.bind(instance) : value;
+    },
+});
+export default queue;
+//# sourceMappingURL=main.js.map

package/dist/services/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/services/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,IAAI,QAAkC,CAAC;AAEvC,0EAA0E;AAC1E,MAAM,UAAU,QAAQ,CAAC,KAAmB;IAC3C,QAAQ,GAAG,KAAK,CAAC;AAClB,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,QAAQ;IACvB,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,MAAM,KAAK,GAAiB,IAAI,KAAK,CAAC,EAAkB,EAAE;IACzD,GAAG,CAAC,OAAO,EAAE,IAAI;QAChB,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACd,sEAAsE;gBACrE,4DAA4D,CAC7D,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,KAAK,CAAC"}

package/dist/testing/FakeQueue.d.ts

@@ -0,0 +1,44 @@
+/**
+ * In-memory `QueueDriver` for tests — captures every dispatched
+ * job and exposes Adonis/Laravel-style `assertPushed` /
+ * `assertNotPushed` helpers in the same shape as Rover's
+ * `FakeMail`.
+ *
+ * Not re-exported from the main barrel; reach via
+ * `@c9up/bay/testing` so production code never accidentally pulls
+ * the fake into a runtime build.
+ */
+import type { Job, QueueDriver } from "../QueueManager.js";
+export interface FakeQueuePredicate {
+    /** Custom payload predicate — receives the job's `payload` and
+     *  returns `true` to match. The job name is always taken from the
+     *  positional `name` argument of `assertPushed` / `assertNotPushed`
+     *  — there is no `name` field on the predicate (would create a
+     *  silent override footgun where `assertPushed('a', { name: 'b' })`
+     *  matches 'b' but the error message says 'a'). */
+    payloadMatches?: (payload: unknown) => boolean;
+}
+export type FakeQueuePredicateArg = FakeQueuePredicate | ((job: Job) => boolean);
+export declare class FakeQueue implements QueueDriver {
+    #private;
+    push(job: Job): Promise<void>;
+    /** Always returns `null` — fake queues never auto-dispatch.
+     *  Tests that need handler execution should use the memory
+     *  driver directly. */
+    pop(): Promise<Job | null>;
+    fail(job: Job, error: string): Promise<void>;
+    complete(job: Job): Promise<void>;
+    retry(job: Job): Promise<void>;
+    failed(): Promise<Job[]>;
+    size(): Promise<number>;
+    /**
+     * Defensive snapshot of every captured job. Each entry is a
+     * shallow clone so test-side mutations can't bleed back into the
+     * internal capture store — avoids cross-test contamination.
+     */
+    getPushed(): Job[];
+    reset(): void;
+    assertPushed(name: string, predicate?: FakeQueuePredicateArg): void;
+    assertNotPushed(name: string, predicate?: FakeQueuePredicateArg): void;
+}
+//# sourceMappingURL=FakeQueue.d.ts.map

package/dist/testing/FakeQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeQueue.d.ts","sourceRoot":"","sources":["../../src/testing/FakeQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE3D,MAAM,WAAW,kBAAkB;IAClC;;;;;uDAKmD;IACnD,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;CAC/C;AAED,MAAM,MAAM,qBAAqB,GAC9B,kBAAkB,GAClB,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;AAE3B,qBAAa,SAAU,YAAW,WAAW;;IAGtC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnC;;2BAEuB;IACjB,GAAG,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAI1B,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5C,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjC,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA0B9B,MAAM,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAMxB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7B;;;;OAIG;IACH,SAAS,IAAI,GAAG,EAAE;IAIlB,KAAK,IAAI,IAAI;IAIb,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,qBAAqB,GAAG,IAAI;IAQnE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,qBAAqB,GAAG,IAAI;CAQtE"}

package/dist/testing/FakeQueue.js

@@ -0,0 +1,131 @@
+/**
+ * In-memory `QueueDriver` for tests — captures every dispatched
+ * job and exposes Adonis/Laravel-style `assertPushed` /
+ * `assertNotPushed` helpers in the same shape as Rover's
+ * `FakeMail`.
+ *
+ * Not re-exported from the main barrel; reach via
+ * `@c9up/bay/testing` so production code never accidentally pulls
+ * the fake into a runtime build.
+ */
+export class FakeQueue {
+    #pushed = [];
+    async push(job) {
+        // Reject duplicate ids to surface the most common test-fixture
+        // mistake — two `makeJob({ id: 'x' })` reused across pushes
+        // silently corrupts later `fail`/`complete`/`retry` lookups.
+        if (this.#pushed.some((j) => j.id === job.id)) {
+            throw new Error(`FakeQueue: duplicate job id '${job.id}' — each push must use a unique id (the real drivers enforce this implicitly via crypto.randomUUID()).`);
+        }
+        this.#pushed.push(job);
+    }
+    /** Always returns `null` — fake queues never auto-dispatch.
+     *  Tests that need handler execution should use the memory
+     *  driver directly. */
+    async pop() {
+        return null;
+    }
+    async fail(job, error) {
+        const found = this.#requireJob(job, "fail");
+        found.status = "failed";
+        found.error = error;
+    }
+    async complete(job) {
+        const found = this.#requireJob(job, "complete");
+        found.status = "completed";
+        found.processedAt = Date.now();
+    }
+    async retry(job) {
+        const found = this.#requireJob(job, "retry");
+        found.attempts += 1;
+        found.status = "pending";
+        // Reset transient state from the prior failure so a retried
+        // job's invariants match a fresh push (a real driver would
+        // either drop these on requeue or rely on the worker to clear
+        // them — we mirror "drop").
+        found.error = undefined;
+        found.processedAt = undefined;
+    }
+    /** Look up the captured copy of a job by id. Throws when the id
+     *  isn't present — silent no-op on a missing job is the most
+     *  insidious test bug (caller's local Job ref shows the new
+     *  status while the FakeQueue's internal capture is unchanged). */
+    #requireJob(job, verb) {
+        const found = this.#pushed.find((j) => j.id === job.id);
+        if (!found) {
+            throw new Error(`FakeQueue.${verb}: job id '${job.id}' is not in the queue. Did you forget to push it, or is it from a different FakeQueue instance?`);
+        }
+        return found;
+    }
+    async failed() {
+        return this.#pushed
+            .filter((j) => j.status === "failed")
+            .map((j) => ({ ...j }));
+    }
+    async size() {
+        return this.#pushed.filter((j) => j.status === "pending").length;
+    }
+    /**
+     * Defensive snapshot of every captured job. Each entry is a
+     * shallow clone so test-side mutations can't bleed back into the
+     * internal capture store — avoids cross-test contamination.
+     */
+    getPushed() {
+        return this.#pushed.map((j) => ({ ...j }));
+    }
+    reset() {
+        this.#pushed = [];
+    }
+    assertPushed(name, predicate) {
+        const match = makeMatcher(name, predicate);
+        if (this.#pushed.some(match))
+            return;
+        throw new Error(`queue.assertPushed('${name}'${describePredicate(predicate)}) failed — no captured job matches.\n${describeCaptured(this.#pushed)}`);
+    }
+    assertNotPushed(name, predicate) {
+        const match = makeMatcher(name, predicate);
+        const found = this.#pushed.find(match);
+        if (!found)
+            return;
+        throw new Error(`queue.assertNotPushed('${name}'${describePredicate(predicate)}) failed — at least one captured job matches.\n${describeCaptured(this.#pushed)}`);
+    }
+}
+function makeMatcher(name, predicate) {
+    // Function-form predicate — caller does ALL the matching, the
+    // `name` arg is still a hard prerequisite.
+    if (typeof predicate === "function") {
+        return (j) => j.name === name && predicate(j);
+    }
+    if (predicate === undefined) {
+        return (j) => j.name === name;
+    }
+    // Object-form: positional `name` is the contract; the predicate
+    // narrows further via `payloadMatches`.
+    return (j) => {
+        if (j.name !== name)
+            return false;
+        if (predicate.payloadMatches && !predicate.payloadMatches(j.payload)) {
+            return false;
+        }
+        return true;
+    };
+}
+function describePredicate(predicate) {
+    if (predicate === undefined)
+        return "";
+    if (typeof predicate === "function")
+        return ", <function predicate>";
+    // Empty object collapses to a name-only match — say so explicitly
+    // so a mistaken `assertPushed('x', {})` is not mistaken for "I'm
+    // narrowing by some predicate I forgot to fill in".
+    if (Object.keys(predicate).length === 0)
+        return ", <empty predicate (name-only)>";
+    return `, ${JSON.stringify(predicate)}`;
+}
+function describeCaptured(captured) {
+    if (captured.length === 0)
+        return "Captured: (none)";
+    const lines = captured.map((j, i) => `  [${i}] name="${j.name}" status=${j.status} attempts=${j.attempts}/${j.maxAttempts}`);
+    return `Captured (${captured.length}):\n${lines.join("\n")}`;
+}
+//# sourceMappingURL=FakeQueue.js.map

package/dist/testing/FakeQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeQueue.js","sourceRoot":"","sources":["../../src/testing/FakeQueue.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@c9up/bay",
+  "version": "0.1.3",
+  "description": "Queue — pluggable job-queue contract with memory + Redis drivers for the Ream framework",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/BayProvider.d.ts",
+      "import": "./dist/BayProvider.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/FakeQueue.d.ts",
+      "import": "./dist/testing/FakeQueue.js"
+    }
+  },
+  "peerDependencies": {
+    "@c9up/ream": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "@c9up/ream": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/bay.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/BayProvider.ts

@@ -0,0 +1,85 @@
+import { MemoryDriver } from "./drivers/MemoryDriver.js";
+import { QueueManager } from "./QueueManager.js";
+import { setQueue } from "./services/main.js";
+
+/**
+ * Slim, duck-typed host context — bay stays publishable without
+ * importing `@c9up/ream`. Any framework that exposes a Container with
+ * `singleton(token, factory)` + `resolve(token)` and a config store
+ * with `get(key)` satisfies the contract.
+ */
+interface BayContainer {
+	singleton(token: unknown, factory: () => unknown): void;
+	resolve<T = unknown>(token: unknown): T;
+}
+interface BayConfigStore {
+	get<T = unknown>(key: string): T | undefined;
+}
+export interface BayAppContext {
+	container: BayContainer;
+	config: BayConfigStore;
+}
+
+export interface BayProviderConfig {
+	/**
+	 * Driver to bind by default. Recognized strings: `"memory"`,
+	 * `"redis"`. For any other case (custom driver, pre-built
+	 * instance), wire `QueueManager` directly in your app's startup
+	 * and skip the provider — the `services/main` singleton accepts
+	 * `setQueue(myQueue)` from outside.
+	 *
+	 * Default `"memory"`.
+	 */
+	driver?: "memory" | "redis";
+}
+
+/**
+ * BayProvider — registers a default in-memory `QueueManager` in the
+ * host container so apps that don't need custom driver wiring can
+ * `import queue from '@c9up/bay/services/main'` and dispatch
+ * straight away. Job handlers are still registered manually via
+ * `queue.register(name, handler)` — that's intrinsic to the queue
+ * design (handlers are app-defined, not config-driven).
+ *
+ * Apps with non-trivial wiring (Redis driver, custom queue config)
+ * can ignore this provider and bind their own `QueueManager` instance
+ * in the container; the `services/main` proxy resolves whatever is
+ * registered.
+ *
+ *   // reamrc.ts
+ *   providers: [() => import('@c9up/bay/provider')]
+ *
+ *   // start/queue.ts
+ *   import queue from '@c9up/bay/services/main'
+ *
+ *   queue.register('send-email', new SendEmailJob())
+ *   await queue.dispatch('send-email', { to: 'user@example.com' })
+ */
+export default class BayProvider {
+	constructor(protected app: BayAppContext) {}
+
+	register(): void {
+		this.app.container.singleton(QueueManager, () => {
+			const config = this.app.config.get<BayProviderConfig>("queue");
+			const driverName = config?.driver ?? "memory";
+			if (driverName !== "memory") {
+				throw new Error(
+					`[bay] Unsupported driver '${driverName}' for default provider — ` +
+						"wire QueueManager yourself in start/queue.ts for non-memory drivers.",
+				);
+			}
+			return new QueueManager(new MemoryDriver());
+		});
+		this.app.container.singleton("queue", () =>
+			this.app.container.resolve<QueueManager>(QueueManager),
+		);
+	}
+
+	async boot(): Promise<void> {
+		// Populate the `@c9up/bay/services/main` singleton so apps can
+		// `import queue from '@c9up/bay/services/main'` from anywhere.
+		setQueue(this.app.container.resolve<QueueManager>(QueueManager));
+	}
+
+	async shutdown(): Promise<void> {}
+}

package/src/QueueManager.ts

@@ -0,0 +1,165 @@
+/**
+ * QueueManager — dispatch and process background jobs.
+ *
+ * Usage:
+ *   queue.register('send-email', new SendEmailHandler())
+ *   await queue.dispatch('send-email', { to: 'user@example.com' })
+ *   queue.work()
+ */
+
+export interface Job {
+	id: string;
+	name: string;
+	payload: unknown;
+	attempts: number;
+	maxAttempts: number;
+	status: "pending" | "processing" | "completed" | "failed";
+	error?: string;
+	createdAt: number;
+	processedAt?: number;
+}
+
+export interface JobHandler {
+	handle(payload: unknown): Promise<void>;
+}
+
+export interface QueueDriver {
+	push(job: Job): Promise<void>;
+	pop(): Promise<Job | null>;
+	fail(job: Job, error: string): Promise<void>;
+	complete(job: Job): Promise<void>;
+	retry(job: Job): Promise<void>;
+	failed(): Promise<Job[]>;
+	size(): Promise<number>;
+}
+
+export class QueueManager {
+	private driver: QueueDriver;
+	private handlers: Map<string, JobHandler | (new () => JobHandler)> =
+		new Map();
+	private running = false;
+	private inflightPromise: Promise<boolean> | null = null;
+
+	constructor(driver: QueueDriver) {
+		this.driver = driver;
+	}
+
+	/** Register a job handler. */
+	register(name: string, handler: JobHandler | (new () => JobHandler)): void {
+		this.handlers.set(name, handler);
+	}
+
+	/** Dispatch a job to the queue. */
+	async dispatch(
+		name: string,
+		payload: unknown,
+		options?: { maxAttempts?: number },
+	): Promise<string> {
+		if (options?.maxAttempts !== undefined && options.maxAttempts < 1) {
+			throw new Error("maxAttempts must be >= 1");
+		}
+		const id = `job_${crypto.randomUUID()}`;
+		const job: Job = {
+			id,
+			name,
+			payload,
+			attempts: 0,
+			maxAttempts: options?.maxAttempts ?? 3,
+			status: "pending",
+			createdAt: Date.now(),
+		};
+		await this.driver.push(job);
+		return id;
+	}
+
+	/** Process the next job in the queue. */
+	async processOne(): Promise<boolean> {
+		const job = await this.driver.pop();
+		if (!job) return false;
+
+		const handlerOrClass = this.handlers.get(job.name);
+		if (!handlerOrClass) {
+			process.stderr.write(
+				`QueueManager: no handler registered for job '${job.name}'\n`,
+			);
+			await this.driver.fail(job, `No handler registered for job: ${job.name}`);
+			return true;
+		}
+
+		const handler =
+			typeof handlerOrClass === "function"
+				? new handlerOrClass()
+				: handlerOrClass;
+		job.attempts++;
+		job.status = "processing";
+		job.processedAt = Date.now();
+
+		try {
+			await handler.handle(job.payload);
+			job.status = "completed";
+			await this.driver.complete(job);
+		} catch (err) {
+			const errorMsg = err instanceof Error ? err.message : String(err);
+			if (job.attempts < job.maxAttempts) {
+				job.status = "pending";
+				await this.driver.retry(job);
+			} else {
+				job.status = "failed";
+				job.error = errorMsg;
+				await this.driver.fail(job, errorMsg);
+			}
+		}
+
+		return true;
+	}
+
+	/** Start processing jobs continuously. */
+	async work(pollIntervalMs = 1000): Promise<void> {
+		if (pollIntervalMs <= 0) {
+			throw new Error("pollIntervalMs must be positive");
+		}
+		if (this.running) {
+			throw new Error("QueueManager is already running");
+		}
+		this.running = true;
+		while (this.running) {
+			try {
+				this.inflightPromise = this.processOne();
+				const processed = await this.inflightPromise;
+				if (!processed) {
+					await new Promise((r) => setTimeout(r, pollIntervalMs));
+				}
+			} catch (err) {
+				process.stderr.write(
+					`QueueManager processOne error: ${err instanceof Error ? err.message : String(err)}\n`,
+				);
+				await new Promise((r) => setTimeout(r, pollIntervalMs));
+			} finally {
+				this.inflightPromise = null;
+			}
+		}
+	}
+
+	/** Await the currently in-flight processOne, if any. */
+	async drain(): Promise<void> {
+		if (this.inflightPromise) {
+			await this.inflightPromise.catch(() => {});
+		}
+	}
+
+	/** Stop the worker. */
+	async stop(): Promise<void> {
+		this.running = false;
+		await this.drain();
+	}
+
+	/** Get failed jobs. */
+	async failedJobs(): Promise<Job[]> {
+		return this.driver.failed();
+	}
+
+	/** Get queue size. */
+	async size(): Promise<number> {
+		return this.driver.size();
+	}
+}

package/src/drivers/MemoryDriver.ts

@@ -0,0 +1,49 @@
+/**
+ * Memory queue driver — in-process queue for development.
+ */
+
+import type { Job, QueueDriver } from "../QueueManager.js";
+
+export class MemoryDriver implements QueueDriver {
+	#pending: Job[] = [];
+	#failedJobs: Job[] = [];
+	#maxFailedJobs: number;
+
+	constructor(options?: { maxFailedJobs?: number }) {
+		this.#maxFailedJobs = options?.maxFailedJobs ?? 1000;
+	}
+
+	async push(job: Job): Promise<void> {
+		this.#pending.push(job);
+	}
+
+	async pop(): Promise<Job | null> {
+		return this.#pending.shift() ?? null;
+	}
+
+	async fail(job: Job, error: string): Promise<void> {
+		job.error = error;
+		job.status = "failed";
+		this.#failedJobs.push(job);
+		if (this.#failedJobs.length > this.#maxFailedJobs) {
+			this.#failedJobs.splice(0, this.#failedJobs.length - this.#maxFailedJobs);
+		}
+	}
+
+	async complete(_job: Job): Promise<void> {
+		// Nothing to do for memory driver
+	}
+
+	async retry(job: Job): Promise<void> {
+		job.status = "pending";
+		this.#pending.push(job);
+	}
+
+	async failed(): Promise<Job[]> {
+		return [...this.#failedJobs];
+	}
+
+	async size(): Promise<number> {
+		return this.#pending.length;
+	}
+}