@c9up/bay 0.1.13 → 0.2.1

package/dist/vendor/quasarConnection.d.ts

@@ -0,0 +1,35 @@
+export interface QuasarConnectionRequest {
+    /** The package asking. It prefixes every message this can raise. */
+    pkg: string;
+    /**
+     * How this package builds an error.
+     *
+     * Not optional, and not `new Error` by default: a package with its own
+     * error type carries codes (`E_<PKG>_<REASON>`) that a caller catches on,
+     * and a shared helper throwing a bare Error would silently drop them. The
+     * two reasons are distinguished so the codes can be too.
+     */
+    raise: (reason: "quasar-missing" | "incomplete-connection", message: string, cause?: unknown) => Error;
+    /** Connection name, or `undefined` for quasar's default. */
+    name?: string;
+    /** The commands the caller will actually issue. */
+    required: readonly string[];
+    /** What the caller does with them, for the message that names a gap. */
+    what: string;
+    /**
+     * A second way out, when this package has one.
+     *
+     * Several of them accept a client object directly, so "pass a client
+     * instead of a connection name" is actionable — and it was in each
+     * package's own message before this was shared. Dropping it to unify the
+     * wording would have made the error strictly less useful.
+     */
+    alternative?: string;
+}
+/**
+ * The named connection, checked for the commands the caller needs BEFORE it is
+ * handed over — a connection missing one would otherwise fail on the first
+ * command, far from the line that asked for it.
+ */
+export declare function quasarConnection<T>(request: QuasarConnectionRequest): Promise<T>;
+//# sourceMappingURL=quasarConnection.d.ts.map

package/dist/vendor/quasarConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quasarConnection.d.ts","sourceRoot":"","sources":["../../src/vendor/quasarConnection.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,uBAAuB;IACvC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,KAAK,EAAE,CACN,MAAM,EAAE,gBAAgB,GAAG,uBAAuB,EAClD,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,KACX,KAAK,CAAC;IACX,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACvC,OAAO,EAAE,uBAAuB,GAC9B,OAAO,CAAC,CAAC,CAAC,CAuCZ"}

package/dist/vendor/quasarConnection.js

@@ -0,0 +1,62 @@
+// Generated from scripts/vendor/quasarConnection.ts — do not edit.
+//
+// This package is published and built from its own repository, so the file
+// has to exist here rather than be imported. `pnpm vendor:sync` rewrites it,
+// and `pnpm vendor:check` fails if this copy has drifted from the original.
+/**
+ * Read a member without assuming how the object answers.
+ *
+ * Two shapes have to work, and they disagree about `in`. Quasar's accessor is
+ * a Proxy over an empty null-prototype object with only a `get` trap, so
+ * `"connection" in manager` is FALSE while reading it returns the function —
+ * gating on `in` rejected the real manager. And a module namespace under a
+ * test double RAISES for an export it does not have, rather than answering
+ * undefined, so a bare read fails on the mock. Reading through a catch is what
+ * satisfies both.
+ */
+function readMember(value, name) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    try {
+        return Reflect.get(value, name);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isConnectionSource(value) {
+    return typeof readMember(value, "connection") === "function";
+}
+/**
+ * The named connection, checked for the commands the caller needs BEFORE it is
+ * handed over — a connection missing one would otherwise fail on the first
+ * command, far from the line that asked for it.
+ */
+export async function quasarConnection(request) {
+    const { pkg, name, required, what, raise, alternative } = request;
+    const specifier = "@c9up/quasar/services/main";
+    let loaded;
+    try {
+        loaded = await import(/* @vite-ignore */ specifier);
+    }
+    catch (cause) {
+        throw raise("quasar-missing", `[${pkg}] ${what} asks for the quasar connection "${name ?? "default"}", but @c9up/quasar is not installed.\n` +
+            `  pnpm add @c9up/quasar${alternative ? `, ${alternative}` : ""}`, cause);
+    }
+    const manager = isConnectionSource(loaded)
+        ? loaded
+        : Reflect.get(Object(loaded), "default");
+    if (!isConnectionSource(manager)) {
+        throw raise("quasar-missing", `[${pkg}] @c9up/quasar/services/main did not expose a connection() manager`);
+    }
+    const connection = manager.connection(name);
+    const missing = required.filter((command) => typeof readMember(connection, command) !== "function");
+    if (missing.length > 0) {
+        throw raise("incomplete-connection", `[${pkg}] the quasar connection${name ? ` '${name}'` : ""} is missing ${missing.join(", ")}, which ${what} issues`);
+    }
+    // Load-bearing: every member of `required` has just been checked to be a
+    // function on this object. The caller names the type it needs because only
+    // the caller knows which commands it asked for.
+    return connection;
+}
+//# sourceMappingURL=quasarConnection.js.map

package/dist/vendor/quasarConnection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quasarConnection.js","sourceRoot":"","sources":["../../src/vendor/quasarConnection.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAqB5E;;;;;;;;;;GAUG;AACH,SAAS,UAAU,CAAC,KAAc,EAAE,IAAY;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAClE,IAAI,CAAC;QACJ,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,SAAS,CAAC;IAClB,CAAC;AACF,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAc;IACzC,OAAO,OAAO,UAAU,CAAC,KAAK,EAAE,YAAY,CAAC,KAAK,UAAU,CAAC;AAC9D,CAAC;AAmCD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,OAAgC;IAEhC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAClE,MAAM,SAAS,GAAG,4BAA4B,CAAC;IAC/C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACJ,MAAM,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,KAAK,CACV,gBAAgB,EAChB,IAAI,GAAG,KAAK,IAAI,oCAAoC,IAAI,IAAI,SAAS,yCAAyC;YAC7G,0BAA0B,WAAW,CAAC,CAAC,CAAC,KAAK,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAClE,KAAK,CACL,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,CAAC;QACzC,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,CAAC;IAC1C,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,MAAM,KAAK,CACV,gBAAgB,EAChB,IAAI,GAAG,oEAAoE,CAC3E,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAC9B,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,UAAU,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,UAAU,CAClE,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,CACV,uBAAuB,EACvB,IAAI,GAAG,0BAA0B,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,eAAe,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,SAAS,CAClH,CAAC;IACH,CAAC;IACD,yEAAyE;IACzE,2EAA2E;IAC3E,gDAAgD;IAChD,OAAO,UAAe,CAAC;AACxB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/bay",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "description": "Queue — pluggable job-queue contract with memory + Redis drivers for the Ream framework",
   "license": "MIT",
   "type": "module",
@@ -36,8 +36,10 @@
     "@biomejs/biome": "^2.4.10",
     "@c9up/quasar": "^0.1.0",
     "@types/node": "^22.19.15",
+    "@vitest/coverage-v8": "^4.1.2",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.2",
+    "@c9up/ream": "^0.2.0"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -66,7 +68,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
-    "lint": "biome check src/",
+    "lint": "biome check src/ tests/",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit"
   }

package/src/BayProvider.ts

@@ -1,8 +1,15 @@
+import type { AdapterFactory } from "./adapters.js";
+import "./augmentations.js";
 import { MemoryDriver } from "./drivers/MemoryDriver.js";
+import {
+	DEFAULT_JOBS_DIR,
+	directoryOf,
+	discoverJobs,
+	setJobsDir,
+} from "./jobs.js";
 import type { QueueDriver } from "./QueueManager.js";
-import { QueueManager } from "./QueueManager.js";
+import { QueueManager, type WorkerOptions } from "./QueueManager.js";
 import { clearQueue, getQueue, setQueue } from "./services/main.js";
-import type { QueueStoreFactory } from "./stores.js";
 
 /**
  * Slim, duck-typed host context — bay stays publishable without
@@ -10,37 +17,76 @@ import type { QueueStoreFactory } from "./stores.js";
  * `singleton(token, factory)` + `resolve(token)` and a config store
  * with `get(key)` satisfies the contract.
  */
-interface BayContainer {
+/**
+ * The slice of a host container bay uses. Exported because `BayAppContext` is:
+ * a host — or a test — cannot describe one without being able to name its
+ * members, and the two that could not were reached for with `as any` instead.
+ */
+export interface BayContainer {
 	singleton(token: unknown, factory: () => unknown): void;
 	resolve<T = unknown>(token: unknown): Promise<T>;
 }
-interface BayConfigStore {
+export interface BayConfigStore {
 	get<T = unknown>(key: string): T | undefined;
 }
 export interface BayAppContext {
 	container: BayContainer;
 	config: BayConfigStore;
+	/**
+	 * Resolve a path against the application root (AdonisJS `app.makePath`).
+	 *
+	 * `app/jobs` means "under the application root", not "under whatever
+	 * directory the process started in". Without this, discovery resolved
+	 * against `process.cwd()`, so a worker launched from anywhere else found
+	 * nothing — and found it silently.
+	 *
+	 * Optional, because bay is agnostic: a host with no notion of an
+	 * application root leaves discovery cwd-relative, as before.
+	 */
+	makePath?(...segments: string[]): string;
 }
 
 export interface BayProviderConfig {
 	/**
-	 * Which named store to use — a key of {@link stores}. Read from the
+	 * Which named adapter to use — a key of {@link adapters}. Read from the
 	 * environment in the generated config, so a deployment picks its queue
 	 * backend without editing a file.
 	 */
 	default?: string;
 	/**
-	 * The queue stores this application can use, by name. Each is a factory
-	 * from `stores.*`, built only when it is the one selected.
+	 * The queue adapters this application can use, by name. Each is a factory
+	 * from `drivers.*`, built only when it is the one selected.
+	 */
+	adapters?: Record<string, AdapterFactory>;
+	/**
+	 * The name this key had before it matched upstream's. Read when `adapters`
+	 * is absent, so a config written against the older spelling keeps selecting
+	 * the backend it named — silently falling back to an in-process queue is the
+	 * one outcome `buildDriver` exists to prevent.
 	 */
-	stores?: Record<string, QueueStoreFactory>;
+	stores?: Record<string, AdapterFactory>;
 	/**
-	 * The single-store form, kept for configs written against it: only
-	 * `"memory"` was ever accepted. Prefer `default` + `stores`, which is how a
-	 * pluggable backend is configured everywhere else and what lets the
+	 * The single-adapter form, kept for configs written against it: only
+	 * `"memory"` was ever accepted. Prefer `default` + `adapters`, which is how
+	 * a pluggable backend is configured everywhere else and what lets the
 	 * environment choose.
 	 */
 	driver?: "memory";
+	/**
+	 * Defaults for the worker `queue.work()` starts — upstream's `worker` block,
+	 * by the names it gives them. An argument to `work()` still wins.
+	 */
+	worker?: WorkerOptions;
+	/**
+	 * Where the application's job classes live. Default `['app/jobs']`.
+	 *
+	 * Every module under them is imported at boot and a default export that is
+	 * a job class is registered under its own name — which is what lets a
+	 * worker process resolve a record queued by an HTTP one. Without it the
+	 * registration list is a directory kept in step by hand, and the job
+	 * nobody added to it fails as "no handler registered".
+	 */
+	locations?: readonly string[];
 }
 
 /**
@@ -75,35 +121,39 @@ export interface BayProviderConfig {
  * queue would only find out when a restart dropped every pending job.
  */
 function buildDriver(config: BayProviderConfig | undefined): QueueDriver {
-	const stores = config?.stores;
+	// `adapters` first, `stores` when it is absent: the key was renamed to the
+	// one upstream reads, and a config that still says `stores` must keep
+	// selecting its backend rather than quietly landing on memory.
+	const adapters = config?.adapters ?? config?.stores;
+	const key = config?.adapters ? "adapters" : "stores";
 	const name = config?.default;
 
-	if (stores && name !== undefined) {
-		const selected = stores[name];
+	if (adapters && name !== undefined) {
+		const selected = adapters[name];
 		if (!selected) {
-			const known = Object.keys(stores);
+			const known = Object.keys(adapters);
 			throw new Error(
-				`[bay] config.queue names the store '${name}', which is not in \`stores\`. ` +
+				`[bay] config.queue names the adapter '${name}', which is not in \`${key}\`. ` +
 					(known.length > 0
 						? `Declared: ${known.join(", ")}.`
-						: "`stores` is empty — declare one with stores.memory() or stores.redis()."),
+						: `\`${key}\` is empty — declare one with drivers.memory() or drivers.redis().`),
 			);
 		}
 		return selected();
 	}
 
-	if (stores && name === undefined) {
+	if (adapters && name === undefined) {
 		throw new Error(
-			"[bay] config.queue declares `stores` but no `default` naming which one to use. " +
-				`Set default to one of: ${Object.keys(stores).join(", ")}.`,
+			`[bay] config.queue declares \`${key}\` but no \`default\` naming which one to use. ` +
+				`Set default to one of: ${Object.keys(adapters).join(", ")}.`,
 		);
 	}
 
 	const driverName = config?.driver ?? "memory";
 	if (driverName !== "memory") {
 		throw new Error(
-			`[bay] Unsupported driver '${driverName}' — name it under \`stores\` instead: ` +
-				"stores: { redis: stores.redis({ connection: 'main' }) }.",
+			`[bay] Unsupported driver '${driverName}' — name it under \`adapters\` instead: ` +
+				"adapters: { redis: drivers.redis({ connection: 'main' }) }.",
 		);
 	}
 	return new MemoryDriver();
@@ -115,11 +165,17 @@ export default class BayProvider {
 	register(): void {
 		this.app.container.singleton(QueueManager, () => {
 			const config = this.app.config.get<BayProviderConfig>("queue");
-			return new QueueManager(buildDriver(config));
+			return new QueueManager(buildDriver(config), config?.worker);
 		});
-		this.app.container.singleton("queue", () =>
-			this.app.container.resolve<QueueManager>(QueueManager),
-		);
+		// Namespaced by the package that owns it, the way upstream namespaces
+		// `lucid.db`, `auth.manager` and `drive.manager` by theirs. The bare
+		// token stays bound beside it: it is what every existing
+		// `container.make(...)` asks for, and a token is not worth breaking an
+		// application over.
+		const queue = (): Promise<QueueManager> =>
+			this.app.container.resolve<QueueManager>(QueueManager);
+		this.app.container.singleton("bay.queue", queue);
+		this.app.container.singleton("queue", queue);
 	}
 
 	/** The queue THIS provider booted — not whatever the module singleton holds. */
@@ -130,6 +186,16 @@ export default class BayProvider {
 		// `import queue from '@c9up/bay/services/main'` from anywhere.
 		this.#queue = await this.app.container.resolve<QueueManager>(QueueManager);
 		setQueue(this.#queue);
+
+		const config = this.app.config.get<BayProviderConfig>("queue");
+		const locations = config?.locations ?? [DEFAULT_JOBS_DIR];
+		// `make:job` writes where discovery reads, so the two cannot drift.
+		const first = locations[0];
+		if (first !== undefined) setJobsDir(directoryOf(first));
+		const resolveLocation = this.app.makePath?.bind(this.app);
+		for (const job of await discoverJobs(locations, resolveLocation)) {
+			this.#queue.registerJob(job);
+		}
 	}
 
 	/**

package/src/Job.ts

@@ -0,0 +1,137 @@
+/**
+ * A job as a class — what an application writes, and what `dispatch` takes.
+ *
+ * The queue accepted a registered name and a payload:
+ *
+ *     queue.register('send-email', new SendEmailHandler())
+ *     await queue.dispatch('send-email', { to: '…' })
+ *
+ * Two places to keep in step, and nothing tying the payload to the handler that
+ * reads it. A class carries its own name, its own options and its payload type:
+ *
+ *     export default class SendEmail extends Job<{ to: string }> {
+ *       static options: JobOptions = { queue: 'emails', maxRetries: 5 }
+ *
+ *       async execute() {
+ *         await mail.send(this.payload.to)
+ *       }
+ *
+ *       async failed(error: Error) {
+ *         // after the last retry, not after each one
+ *       }
+ *     }
+ *
+ *     await queue.dispatch(SendEmail, { to: 'user@example.com' })
+ *
+ * Registering by name still works, and is what a job whose name is computed at
+ * runtime still needs.
+ */
+
+/** Milliseconds, or a duration the way a config file writes one. */
+export type Duration = number | string;
+
+/**
+ * What a job class declares about how it should be run.
+ *
+ * Every field is optional, and the defaults are the manager's: the `default`
+ * queue, three attempts, no delay and no timeout.
+ */
+export interface JobOptions {
+	/** Named queue this job waits in. Default `"default"`. */
+	queue?: string;
+	/**
+	 * How many times the handler may run before the job is filed as failed.
+	 * Default `3`. Counts runs, not retries: `1` means one attempt and no
+	 * second chance.
+	 */
+	maxRetries?: number;
+	/** Hold the job for this long before any worker may take it. */
+	delay?: Duration;
+	/**
+	 * How long the handler gets. Past it the attempt is a failure and the job
+	 * retries or fails like any other.
+	 *
+	 * The handler is not killed — nothing in Node can interrupt a running
+	 * promise — so a job that ignores its timeout goes on burning CPU. What the
+	 * timeout buys is that the WORKER stops waiting for it, which is what a
+	 * stuck job otherwise costs: a worker that never picks anything up again.
+	 */
+	timeout?: Duration;
+}
+
+/** The queue a job goes to when nothing names one. */
+export const DEFAULT_QUEUE = "default";
+
+/**
+ * A background job.
+ *
+ * `execute()` takes no argument: the payload is on the instance, typed by the
+ * class's own parameter, so a handler cannot read a field the dispatcher never
+ * sent.
+ */
+export abstract class Job<Payload = unknown> {
+	/** Overridden by a subclass to change queue, retries, delay or timeout. */
+	static options: JobOptions = {};
+
+	/** What `dispatch` was given, as the class declared it. */
+	declare readonly payload: Payload;
+
+	/** Do the work. Throwing is what makes the attempt fail. */
+	abstract execute(): Promise<void> | void;
+
+	/**
+	 * Called once the last attempt has failed — for the cleanup or the alert,
+	 * not for the retry. A throw here is reported and swallowed: the job is
+	 * already failed, and failing to say so must not fail it twice.
+	 */
+	failed?(error: Error): Promise<void> | void;
+}
+
+/** A job class, as `dispatch` receives it. */
+export interface JobClass<Payload = unknown> {
+	new (): Job<Payload>;
+	readonly name: string;
+	readonly options?: JobOptions;
+}
+
+/** Is this a job class rather than a name or a handler instance? */
+export function isJobClass(value: unknown): value is JobClass {
+	return (
+		typeof value === "function" &&
+		value.prototype instanceof Job &&
+		typeof Reflect.get(value, "name") === "string"
+	);
+}
+
+/**
+ * Milliseconds from a number or a duration string.
+ *
+ * `'10s'`, `'1m'`, `'2h'`, `'500ms'`, `'1d'` — the spellings a config file
+ * uses. A number is already milliseconds. Anything else throws, rather than
+ * silently becoming `NaN` and then a job that never runs: a typo in `delay`
+ * would otherwise park the job forever with nothing to read about it.
+ */
+export function toMilliseconds(value: Duration, label: string): number {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || value < 0) {
+			throw new Error(`${label} must be a non-negative number of milliseconds`);
+		}
+		return value;
+	}
+	const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/.exec(value.trim());
+	if (!match) {
+		throw new Error(
+			`${label} must be a number of milliseconds or a duration like '10s', '1m', '2h' — got '${value}'`,
+		);
+	}
+	const amount = Number(match[1]);
+	const unit = match[2];
+	const scale: Record<string, number> = {
+		ms: 1,
+		s: 1_000,
+		m: 60_000,
+		h: 3_600_000,
+		d: 86_400_000,
+	};
+	return amount * (scale[unit ?? "ms"] ?? 1);
+}