@c9up/bay 0.1.12 → 0.2.0

package/src/jobs.ts

@@ -0,0 +1,111 @@
+/**
+ * Finding the job classes an application wrote.
+ *
+ * A job class carries its own name, and a worker resolves a queued record by
+ * that name — so the worker process has to have imported the class. Written by
+ * hand that is a registration list to keep in step with a directory:
+ *
+ *     queue.registerJob(SendEmail)
+ *     queue.registerJob(SendInvoice)   // …and the one nobody added
+ *
+ * `locations` in `config/queue.ts` is the directory instead. Every module under
+ * it is imported once at boot, and a default export that is a job class is
+ * registered under its own name.
+ *
+ * Directories, not globs. `'./app/jobs/**\/*.{ts,js}'` — the spelling upstream's
+ * config uses — is accepted and read as the directory it starts with, so a
+ * config copied from there works; bay ships no glob engine and adding a
+ * dependency for one path shape is not worth it.
+ */
+
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { isJobClass, type JobClass } from "./Job.js";
+
+/** Where `make:job` writes, and where discovery looks when nothing is declared. */
+export const DEFAULT_JOBS_DIR = "app/jobs";
+
+let jobsDir = DEFAULT_JOBS_DIR;
+
+/** @internal Told by the provider what the config declared. */
+export function setJobsDir(dir: string): void {
+	jobsDir = dir;
+}
+
+/** Where job files live — the first `locations` entry, or the default. */
+export function getJobsDir(): string {
+	return jobsDir;
+}
+
+/**
+ * The directory a `locations` entry names.
+ *
+ * Everything from the first glob character on is dropped: `app/jobs/** /*.ts`
+ * and `app/jobs` name the same directory, and the walk below is recursive
+ * either way.
+ */
+export function directoryOf(location: string): string {
+	const withoutGlob = location.split(/[*?[{]/)[0] ?? location;
+	const trimmed = withoutGlob.replace(/\/+$/, "");
+	return trimmed.replace(/^\.\//, "") || ".";
+}
+
+/** Every module file under `dir`, recursively. */
+async function walk(dir: string, depth = 0): Promise<string[]> {
+	// A jobs directory is a flat convention with the occasional subdirectory;
+	// an unbounded walk would follow whatever happens to live under it.
+	if (depth > 8) return [];
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = await fsp.readdir(dir, { withFileTypes: true });
+	} catch {
+		// A declared directory that does not exist yet is not an error: a project
+		// can name where its jobs will go before writing the first one.
+		return [];
+	}
+	const found: string[] = [];
+	for (const entry of entries) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			found.push(...(await walk(full, depth + 1)));
+			continue;
+		}
+		// `.d.ts` is a declaration, not a module with a job in it.
+		if (/\.d\.[cm]?ts$/.test(entry.name)) continue;
+		if (/\.[cm]?[jt]s$/.test(entry.name)) found.push(full);
+	}
+	return found.sort();
+}
+
+/**
+ * Import every module under `locations` and return the job classes they
+ * default-export.
+ *
+ * A module that throws on import is reported and skipped: one unfinished job
+ * file must not stop the worker from running every other job.
+ */
+export async function discoverJobs(
+	locations: readonly string[],
+): Promise<JobClass[]> {
+	const found: JobClass[] = [];
+	for (const location of locations) {
+		for (const file of await walk(directoryOf(location))) {
+			let module: unknown;
+			try {
+				module = await import(pathToFileURL(path.resolve(file)).href);
+			} catch (err) {
+				process.stderr.write(
+					`[bay] could not load '${file}': ${
+						err instanceof Error ? err.message : String(err)
+					}\n`,
+				);
+				continue;
+			}
+			if (typeof module !== "object" || module === null) continue;
+			const exported = Reflect.get(module, "default");
+			if (isJobClass(exported)) found.push(exported);
+		}
+	}
+	return found;
+}

package/src/nodeEnv.ts

@@ -0,0 +1,30 @@
+/**
+ * Reading `NODE_ENV`, with the aliases people actually set.
+ *
+ * `NODE_ENV=prod` is ordinary in a Dockerfile or a platform dashboard. Read
+ * verbatim it answers "not production" — and here that decides whether a queue
+ * silently accepts a delivery guarantee weaker than the one it advertises.
+ *
+ * Duplicated rather than imported: bay depends on no other package in this
+ * workspace, and a safety decision that only holds when an optional peer is
+ * installed is not a decision.
+ */
+
+const DEV_ENVS = ["dev", "develop", "development"];
+const PROD_ENVS = ["prod", "production"];
+const TEST_ENVS = ["test", "testing"];
+
+/** The canonical name for whatever `NODE_ENV` holds. */
+export function normalizeNodeEnv(value: string | undefined): string {
+	if (!value || typeof value !== "string") return "unknown";
+	const env = value.toLowerCase();
+	if (DEV_ENVS.includes(env)) return "development";
+	if (PROD_ENVS.includes(env)) return "production";
+	if (TEST_ENVS.includes(env)) return "test";
+	return env;
+}
+
+/** Whether this process is running in production, under any spelling. */
+export function inProduction(): boolean {
+	return normalizeNodeEnv(process.env.NODE_ENV) === "production";
+}

package/src/quasar.ts

@@ -3,7 +3,7 @@
  *
  * Bay does not depend on quasar: it is an optional peer, and this module
  * never imports it statically. The specifier is built at runtime so the
- * TypeScript build stays free of it too — a hard type import would make echo
+ * TypeScript build stays free of it too — a hard type import would make bay
  * unbuildable for anyone who queues in memory.
  *
  * The shape is checked before use rather than asserted, the same way bay

package/src/services/main.ts

@@ -27,6 +27,14 @@ export function getQueue(): QueueManager | undefined {
 	return instance;
 }
 
+/**
+ * @internal Release the singleton, so a shut-down application does not leave a
+ * dead queue reachable through `services/main`.
+ */
+export function clearQueue(): void {
+	instance = undefined;
+}
+
 const queue: QueueManager = new Proxy({} as QueueManager, {
 	get(_target, prop) {
 		// A module loader inspects what it imports before anyone uses it: it reads

package/src/testing/FakeQueue.ts

@@ -9,7 +9,7 @@
  * the fake into a runtime build.
  */
 
-import type { Job, QueueDriver } from "../QueueManager.js";
+import type { JobRecord, QueueDriver } from "../QueueManager.js";
 
 export interface FakeQueuePredicate {
 	/** Custom payload predicate — receives the job's `payload` and
@@ -23,12 +23,12 @@ export interface FakeQueuePredicate {
 
 export type FakeQueuePredicateArg =
 	| FakeQueuePredicate
-	| ((job: Job) => boolean);
+	| ((job: JobRecord) => boolean);
 
 export class FakeQueue implements QueueDriver {
-	#pushed: Job[] = [];
+	#pushed: JobRecord[] = [];
 
-	async push(job: Job): Promise<void> {
+	async push(job: JobRecord): Promise<void> {
 		// 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.
@@ -43,25 +43,35 @@ export class FakeQueue implements QueueDriver {
 	/** Always returns `null` — fake queues never auto-dispatch.
 	 *  Tests that need handler execution should use the memory
 	 *  driver directly. */
-	async pop(): Promise<Job | null> {
+	/**
+	 * Always empty: this fake captures what was dispatched, it does not run it.
+	 *
+	 * The parameter is declared so the queue names a caller asks for are part of
+	 * the signature a test reads, even though nothing here serves them.
+	 */
+	async pop(_queues?: readonly string[]): Promise<JobRecord | null> {
 		return null;
 	}
 
-	async fail(job: Job, error: string): Promise<void> {
+	async fail(job: JobRecord, error: string): Promise<void> {
 		const found = this.#requireJob(job, "fail");
 		found.status = "failed";
 		found.error = error;
 	}
 
-	async complete(job: Job): Promise<void> {
+	async complete(job: JobRecord): Promise<void> {
 		const found = this.#requireJob(job, "complete");
 		found.status = "completed";
 		found.processedAt = Date.now();
 	}
 
-	async retry(job: Job): Promise<void> {
+	async retry(job: JobRecord): Promise<void> {
 		const found = this.#requireJob(job, "retry");
-		found.attempts += 1;
+		// `attempts` is the WORKER's counter, not the driver's: `processOne`
+		// increments it before it calls this, and neither real driver touches it
+		// again. Incrementing here counted the same attempt twice, so a fake
+		// exhausted `maxAttempts` in half the tries the real queue takes — a
+		// test double that disagrees with what it stands in for.
 		found.status = "pending";
 		// Reset transient state from the prior failure so a retried
 		// job's invariants match a fresh push (a real driver would
@@ -73,9 +83,9 @@ export class FakeQueue implements QueueDriver {
 
 	/** 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
+	 *  insidious test bug (caller's local job ref shows the new
 	 *  status while the FakeQueue's internal capture is unchanged). */
-	#requireJob(job: Job, verb: string): Job {
+	#requireJob(job: JobRecord, verb: string): JobRecord {
 		const found = this.#pushed.find((j) => j.id === job.id);
 		if (!found) {
 			throw new Error(
@@ -85,7 +95,7 @@ export class FakeQueue implements QueueDriver {
 		return found;
 	}
 
-	async failed(): Promise<Job[]> {
+	async failed(): Promise<JobRecord[]> {
 		return this.#pushed
 			.filter((j) => j.status === "failed")
 			.map((j) => ({ ...j }));
@@ -100,7 +110,7 @@ export class FakeQueue implements QueueDriver {
 	 * shallow clone so test-side mutations can't bleed back into the
 	 * internal capture store — avoids cross-test contamination.
 	 */
-	getPushed(): Job[] {
+	getPushed(): JobRecord[] {
 		return this.#pushed.map((j) => ({ ...j }));
 	}
 
@@ -129,7 +139,7 @@ export class FakeQueue implements QueueDriver {
 function makeMatcher(
 	name: string,
 	predicate: FakeQueuePredicateArg | undefined,
-): (j: Job) => boolean {
+): (j: JobRecord) => boolean {
 	// Function-form predicate — caller does ALL the matching, the
 	// `name` arg is still a hard prerequisite.
 	if (typeof predicate === "function") {
@@ -162,7 +172,7 @@ function describePredicate(
 	return `, ${JSON.stringify(predicate)}`;
 }
 
-function describeCaptured(captured: Job[]): string {
+function describeCaptured(captured: JobRecord[]): string {
 	if (captured.length === 0) return "Captured: (none)";
 	const lines = captured.map(
 		(j, i) =>