@c9up/bay 0.1.13 → 0.2.0

package/README.md

@@ -29,37 +29,112 @@ providers: [
 
 ```ts
 // config/queue.ts
-import { defineConfig, stores } from '@c9up/bay'
+import { defineConfig, drivers } from '@c9up/bay'
 import env from '#start/env'
 
 export default defineConfig({
-  default: env.get('QUEUE_STORE'),
-  stores: {
-    memory: stores.memory(),
-    redis:  stores.redis({ connection: 'main' }),
+  default: env.get('QUEUE_DRIVER'),
+  adapters: {
+    memory: drivers.memory(),
+    redis:  drivers.redis({ connection: 'main' }),
   },
 })
 ```
 
+The keys are the framework's: `default` + `adapters`, filled from a `drivers`
+namespace, selected by `QUEUE_DRIVER`. Bay used to say `stores` / `QUEUE_STORE`;
+both names still resolve, so an existing `config/queue.ts` keeps working.
+
+## A job is a class
+
+```ts
+// app/jobs/send_email.ts  —  ream make:job SendEmail
+import { Job } from '@c9up/bay'
+import type { JobOptions } from '@c9up/bay'
+
+export default class SendEmail extends Job<{ to: string }> {
+  static options: JobOptions = {
+    queue: 'emails',   // which queue it waits in
+    maxRetries: 5,     // how many times the handler may run
+    delay: '10s',      // hold it before any worker may take it
+    timeout: '1m',     // how long the handler gets
+  }
+
+  async execute() {
+    await mail.send(this.payload.to)
+  }
+
+  async failed(error: Error) {
+    // Once the last attempt has failed — the alert, not the retry.
+  }
+}
+```
+
 ```ts
-// start/queue.ts
 import queue from '@c9up/bay/services/main'
 
-queue.register('send-email', new SendEmailJob())
+await queue.dispatch(SendEmail, { to: 'user@example.com' })
+```
+
+The class carries its own name, its options and the type of the payload it
+reads, so a field the handler reads cannot be one the dispatcher never sent. The
+call site overrides any of them: `dispatch(SendEmail, payload, { queue: 'critical' })`.
+
+Registering by name still works, and is what a job whose name is computed at
+runtime needs:
+
+```ts
+queue.register('send-email', new SendEmailHandler())
 await queue.dispatch('send-email', { to: 'user@example.com' })
 ```
 
-| Store | Keeps jobs | Use it when |
+## Workers
+
+```bash
+ream queue:work                                  # the default queue, one at a time
+ream queue:work --queue=critical,default         # in that order of preference
+ream queue:work --concurrency=10                 # ten in flight
+```
+
+```ts
+// or in process
+await queue.work({ queues: ['emails'], concurrency: 4 })
+```
+
+Naming the queues is what keeps a slow one from starving a fast one: run a
+worker for `emails` and another for `default` rather than one worker taking
+whatever comes. `concurrency` is one by default, which is safe and a poor
+default for anything that waits on the network.
+
+A `timeout` fails the attempt; it does not kill the handler, because nothing in
+Node can interrupt a running promise. What it buys is that the **worker** stops
+waiting — otherwise one stuck job costs the whole worker, which never picks
+anything up again.
+
+The `worker` block carries the framework's names for what a worker does between
+jobs — `idleDelay` (how long it waits after finding nothing, 2 s),
+`stalledInterval` (how often it reclaims what a crashed worker left behind,
+30 s), `concurrency` and `queues`. An argument to `work()` beats the block, and
+the block beats the defaults.
+
+`locations` says where the job classes live (`['app/jobs']` by default). 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".
+
+| Adapter | Keeps jobs | Use it when |
 | --- | --- | --- |
-| `stores.memory()` | until the process exits | tests, and local work |
-| `stores.redis({ connection })` | in Redis | anything that must survive a restart |
+| `drivers.memory()` | until the process exits | tests, and local work |
+| `drivers.redis({ connection })` | in Redis | anything that must survive a restart |
 
-Factories are lazy: only the store actually selected is built, so naming a Redis
-queue in a config that runs in memory opens no connection. A `default` that
-names nothing throws, listing what exists — falling back to memory would look
-like it worked until a restart dropped every pending job.
+Factories are lazy: only the adapter actually selected is built, so naming a
+Redis queue in a config that runs in memory opens no connection. A `default`
+that names nothing throws, listing what exists — falling back to memory would
+look like it worked until a restart dropped every pending job.
 
-`stores.redis` takes a `@c9up/quasar` connection name, resolved at first use so
+`drivers.redis` takes a `@c9up/quasar` connection name, resolved at first use so
 bay never imports quasar, which stays an optional peer. Pass an ioredis-shaped
 client (or a function answering one) to use any other.
 
@@ -79,7 +154,7 @@ which two ways out there are:
 
 ```ts
 // Either upgrade the server, or state that losing a job is acceptable here:
-stores.redis({ connection: 'jobs', allowNonAtomicPop: true })
+drivers.redis({ connection: 'jobs', allowNonAtomicPop: true })
 ```
 
 The opt-in is honoured and still logs a warning on every process that starts
@@ -87,6 +162,37 @@ with it, naming production — agreeing once in a config file is not the same as
 being reminded, in the logs of an incident, that this is how the process was
 running. Outside production the fallback simply warns.
 
+## A worker that dies, and a handler that is merely slow
+
+A job taken off the queue is held under a **lease** — `visibilityTimeoutMs`,
+30 s by default. While the lease is alive the job belongs to the worker holding
+it; once it expires, `recoverStale()` puts the job back in pending, which is how
+a crashed worker's job gets run at all.
+
+Two things follow, and both are handled rather than left to the deployment:
+
+**A slow handler is not a dead worker.** For as long as a handler runs, the
+worker renews its own lease — half the timeout, so one slow round-trip is not
+enough to lose the job. Without that, any handler outliving 30 s was recovered
+and re-delivered *while it was still running*, and the same job ran twice.
+Renewal is refused once the lease is gone or has passed to another worker, so a
+late heartbeat cannot resurrect somebody else's claim.
+
+**A job that kills its worker is bounded.** A crash never reaches the failure
+path, so `attempts` never moves and `maxAttempts` never applies — a job that
+takes the process down with it was recovered forever. `maxStalledCount`
+(default `1`) caps how many times a job may be reclaimed before it is filed as
+failed instead.
+
+```ts
+drivers.redis({
+  connection: 'jobs',
+  visibilityTimeoutMs: 30_000, // how long a worker owns a job it took
+  maxStalledCount: 1,          // reclaims allowed before the job is failed
+  maxFailedJobs: 1_000,        // failed jobs kept (needs LTRIM on the client)
+})
+```
+
 ## Entry points
 
 - `@c9up/bay` — main API

package/dist/BayProvider.d.ts

@@ -1,15 +1,22 @@
-import type { QueueStoreFactory } from "./stores.js";
+import type { AdapterFactory } from "./adapters.js";
+import "./augmentations.js";
+import { type WorkerOptions } from "./QueueManager.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 {
+/**
+ * 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 {
@@ -18,23 +25,45 @@ export interface BayAppContext {
 }
 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.
      */
-    stores?: Record<string, QueueStoreFactory>;
+    adapters?: 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 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, AdapterFactory>;
+    /**
+     * 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[];
 }
 export default class BayProvider {
     #private;
@@ -51,5 +80,4 @@ export default class BayProvider {
      */
     shutdown(): Promise<void>;
 }
-export {};
 //# sourceMappingURL=BayProvider.d.ts.map

package/dist/BayProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BayProvider.d.ts","sourceRoot":"","sources":["../src/BayProvider.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;GAKG;AACH,UAAU,YAAY;IACrB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjD;AACD,UAAU,cAAc;IACvB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AACD,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,cAAc,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;CAClB;AAoED,MAAM,CAAC,OAAO,OAAO,WAAW;;IACnB,SAAS,CAAC,GAAG,EAAE,aAAa;gBAAlB,GAAG,EAAE,aAAa;IAExC,QAAQ,IAAI,IAAI;IAaV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAS/B"}
+{"version":3,"file":"BayProvider.d.ts","sourceRoot":"","sources":["../src/BayProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,oBAAoB,CAAC;AAS5B,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGrE;;;;;GAKG;AACH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACjD;AACD,MAAM,WAAW,cAAc;IAC9B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;CAC7C;AACD,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,cAAc,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAwED,MAAM,CAAC,OAAO,OAAO,WAAW;;IACnB,SAAS,CAAC,GAAG,EAAE,aAAa;gBAAlB,GAAG,EAAE,aAAa;IAExC,QAAQ,IAAI,IAAI;IAmBV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB3B;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAS/B"}

package/dist/BayProvider.js

@@ -1,4 +1,6 @@
+import "./augmentations.js";
 import { MemoryDriver } from "./drivers/MemoryDriver.js";
+import { DEFAULT_JOBS_DIR, directoryOf, discoverJobs, setJobsDir, } from "./jobs.js";
 import { QueueManager } from "./QueueManager.js";
 import { clearQueue, getQueue, setQueue } from "./services/main.js";
 /**
@@ -33,27 +35,31 @@ import { clearQueue, getQueue, setQueue } from "./services/main.js";
  * queue would only find out when a restart dropped every pending job.
  */
 function buildDriver(config) {
-    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);
-            throw new Error(`[bay] config.queue names the store '${name}', which is not in \`stores\`. ` +
+            const known = Object.keys(adapters);
+            throw new Error(`[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) {
-        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(", ")}.`);
+    if (adapters && name === undefined) {
+        throw new Error(`[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' }) }.");
+        throw new Error(`[bay] Unsupported driver '${driverName}' — name it under \`adapters\` instead: ` +
+            "adapters: { redis: drivers.redis({ connection: 'main' }) }.");
     }
     return new MemoryDriver();
 }
@@ -65,9 +71,16 @@ export default class BayProvider {
     register() {
         this.app.container.singleton(QueueManager, () => {
             const config = this.app.config.get("queue");
-            return new QueueManager(buildDriver(config));
+            return new QueueManager(buildDriver(config), config?.worker);
         });
-        this.app.container.singleton("queue", () => this.app.container.resolve(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 = () => this.app.container.resolve(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. */
     #queue;
@@ -76,6 +89,15 @@ export default class BayProvider {
         // `import queue from '@c9up/bay/services/main'` from anywhere.
         this.#queue = await this.app.container.resolve(QueueManager);
         setQueue(this.#queue);
+        const config = this.app.config.get("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));
+        for (const job of await discoverJobs(locations)) {
+            this.#queue.registerJob(job);
+        }
     }
     /**
      * Stop the worker the app started, and let the job in flight finish.

package/dist/BayProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"BayProvider.js","sourceRoot":"","sources":["../src/BayProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BayProvider.js","sourceRoot":"","sources":["../src/BayProvider.ts"],"names":[],"mappings":"AACA,OAAO,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EACN,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,UAAU,GACV,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,YAAY,EAAsB,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAoEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,MAAqC;IACzD,2EAA2E;IAC3E,sEAAsE;IACtE,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,MAAM,EAAE,MAAM,CAAC;IACpD,MAAM,GAAG,GAAG,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC;IACrD,MAAM,IAAI,GAAG,MAAM,EAAE,OAAO,CAAC;IAE7B,IAAI,QAAQ,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACpC,MAAM,IAAI,KAAK,CACd,yCAAyC,IAAI,wBAAwB,GAAG,MAAM;gBAC7E,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;oBAChB,CAAC,CAAC,aAAa,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;oBAClC,CAAC,CAAC,KAAK,GAAG,qEAAqE,CAAC,CAClF,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,EAAE,CAAC;IACnB,CAAC;IAED,IAAI,QAAQ,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CACd,iCAAiC,GAAG,iDAAiD;YACpF,0BAA0B,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC9D,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,EAAE,MAAM,IAAI,QAAQ,CAAC;IAC9C,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACd,6BAA6B,UAAU,0CAA0C;YAChF,6DAA6D,CAC9D,CAAC;IACH,CAAC;IACD,OAAO,IAAI,YAAY,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,OAAO,OAAO,WAAW;IACT;IAAtB,YAAsB,GAAkB;QAAlB,QAAG,GAAH,GAAG,CAAe;IAAG,CAAC;IAE5C,QAAQ;QACP,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,YAAY,EAAE,GAAG,EAAE;YAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAoB,OAAO,CAAC,CAAC;YAC/D,OAAO,IAAI,YAAY,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;QACH,sEAAsE;QACtE,qEAAqE;QACrE,yDAAyD;QACzD,uEAAuE;QACvE,oBAAoB;QACpB,MAAM,KAAK,GAAG,GAA0B,EAAE,CACzC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CAAC;QACxD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAED,gFAAgF;IAChF,MAAM,CAA2B;IAEjC,KAAK,CAAC,IAAI;QACT,+DAA+D;QAC/D,+DAA+D;QAC/D,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAe,YAAY,CAAC,CAAC;QAC3E,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEtB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAoB,OAAO,CAAC,CAAC;QAC/D,MAAM,SAAS,GAAG,MAAM,EAAE,SAAS,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC1D,oEAAoE;QACpE,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS;YAAE,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QACxD,KAAK,MAAM,GAAG,IAAI,MAAM,YAAY,CAAC,SAAS,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;IACF,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ;QACb,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QACzB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACzB,uEAAuE;QACvE,uEAAuE;QACvE,oEAAoE;QACpE,IAAI,QAAQ,EAAE,KAAK,IAAI,CAAC,MAAM;YAAE,UAAU,EAAE,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;IACzB,CAAC;CACD"}

package/dist/Job.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 declare 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 declare 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. */
+    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 declare function isJobClass(value: unknown): value is JobClass;
+/**
+ * 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 declare function toMilliseconds(value: Duration, label: string): number;
+//# sourceMappingURL=Job.d.ts.map

package/dist/Job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Job.d.ts","sourceRoot":"","sources":["../src/Job.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,oEAAoE;AACpE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC;CACnB;AAED,sDAAsD;AACtD,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC;;;;;;GAMG;AACH,8BAAsB,GAAG,CAAC,OAAO,GAAG,OAAO;IAC1C,2EAA2E;IAC3E,MAAM,CAAC,OAAO,EAAE,UAAU,CAAM;IAEhC,2DAA2D;IAC3D,SAAiB,OAAO,EAAE,OAAO,CAAC;IAElC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAExC;;;;OAIG;IACH,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;CAC3C;AAED,8CAA8C;AAC9C,MAAM,WAAW,QAAQ,CAAC,OAAO,GAAG,OAAO;IAC1C,QAAQ,GAAG,CAAC,OAAO,CAAC,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC9B;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAM5D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAuBrE"}

package/dist/Job.js

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+/** 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 class Job {
+    /** Overridden by a subclass to change queue, retries, delay or timeout. */
+    static options = {};
+}
+/** Is this a job class rather than a name or a handler instance? */
+export function isJobClass(value) {
+    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, label) {
+    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 = {
+        ms: 1,
+        s: 1_000,
+        m: 60_000,
+        h: 3_600_000,
+        d: 86_400_000,
+    };
+    return amount * (scale[unit ?? "ms"] ?? 1);
+}
+//# sourceMappingURL=Job.js.map

package/dist/Job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Job.js","sourceRoot":"","sources":["../src/Job.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAkCH,sDAAsD;AACtD,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,OAAgB,GAAG;IACxB,2EAA2E;IAC3E,MAAM,CAAC,OAAO,GAAe,EAAE,CAAC;;AAuBjC,oEAAoE;AACpE,MAAM,UAAU,UAAU,CAAC,KAAc;IACxC,OAAO,CACN,OAAO,KAAK,KAAK,UAAU;QAC3B,KAAK,CAAC,SAAS,YAAY,GAAG;QAC9B,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,QAAQ,CAC9C,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAe,EAAE,KAAa;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,gDAAgD,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,kCAAkC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACd,GAAG,KAAK,iFAAiF,KAAK,GAAG,CACjG,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACtB,MAAM,KAAK,GAA2B;QACrC,EAAE,EAAE,CAAC;QACL,CAAC,EAAE,KAAK;QACR,CAAC,EAAE,MAAM;QACT,CAAC,EAAE,SAAS;QACZ,CAAC,EAAE,UAAU;KACb,CAAC;IACF,OAAO,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5C,CAAC"}