@arkstack/queue 0.18.3 → 0.18.4

package/dist/{QueueManager-C1GIAwK2.js → QueueManager-Dm9FLISk.js}

@@ -145,6 +145,13 @@ var QueueContract = class {
 		this.connectionName = name;
 		return this;
 	}
+	/**
+	* The queue this connection works when none is named. Drivers with a
+	* configurable queue override it.
+	*/
+	getDefaultQueue() {
+		return "default";
+	}
 };
 //#endregion
 //#region src/drivers/DatabaseQueue.ts
@@ -167,6 +174,10 @@ var DatabaseQueue = class extends QueueContract {
 		this.options = options;
 	}
 	get defaultQueue() {
+		return this.getDefaultQueue();
+	}
+	/** The configured queue this connection works when none is named. */
+	getDefaultQueue() {
 		return this.options.queue ?? "default";
 	}
 	async database() {
@@ -263,6 +274,10 @@ var RedisQueue = class extends QueueContract {
 		this.options = options;
 	}
 	get defaultQueue() {
+		return this.getDefaultQueue();
+	}
+	/** The configured queue this connection works when none is named. */
+	getDefaultQueue() {
 		return this.options.queue ?? "default";
 	}
 	get retryAfter() {
@@ -415,6 +430,7 @@ const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var Worker = class {
 	connection;
 	shouldStop = false;
+	handlers = {};
 	constructor(connection) {
 		this.connection = connection;
 	}
@@ -423,6 +439,16 @@ var Worker = class {
 		this.shouldStop = true;
 	}
 	/**
+	* Observe what the worker does with each job. Handlers merge, so they can be
+	* registered in more than one call.
+	*
+	* @param handlers  The callbacks to add.
+	*/
+	on(handlers) {
+		Object.assign(this.handlers, handlers);
+		return this;
+	}
+	/**
 	* Pop and process the next job. Returns `true` if a job was processed,
 	* `false` when the queue was empty.
 	*/
@@ -437,8 +463,10 @@ var Worker = class {
 	*/
 	async process(job) {
 		try {
+			await this.handlers.onProcessing?.(job);
 			await (await resolveJob(job.payload)).handle();
 			await job.delete();
+			await this.handlers.onProcessed?.(job);
 		} catch (error) {
 			await this.handleFailure(job, error);
 		}
@@ -469,9 +497,11 @@ var Worker = class {
 				await (await resolveJob(job.payload)).failed?.(error);
 			} catch {}
 			await job.delete();
+			await this.handlers.onFailed?.(job, error, false);
 			return;
 		}
 		await job.release(job.backoff());
+		await this.handlers.onFailed?.(job, error, true);
 	}
 };
 //#endregion

package/dist/commands/QueueClearCommand.js

@@ -1,4 +1,4 @@
-import { t as Queue } from "../QueueManager-C1GIAwK2.js";
+import { t as Queue } from "../QueueManager-Dm9FLISk.js";
 import { Command } from "@h3ravel/musket";
 import { bootArkorm } from "@arkstack/database";
 //#region src/commands/QueueClearCommand.ts

package/dist/commands/QueueWorkCommand.d.ts

@@ -7,6 +7,20 @@ declare class QueueWorkCommand extends Command {
   protected signature: string;
   protected description: string;
   handle(): Promise<void>;
+  /**
+   * Read a multi-word flag. Musket hands over the parsed options camelCased,
+   * so `--stop-when-empty` arrives as `stopWhenEmpty`; the kebab-case name is
+   * accepted too so the flag can't go quietly missing again.
+   *
+   * @param camel  The camelCase key.
+   * @param kebab  The flag as written in the signature.
+   */
+  private flag;
+  /**
+   * Register the application's job classes with `@arkstack/jobs` when it is
+   * installed. Without it a payload cannot be turned back into a job.
+   */
+  private registerJobs;
 }
 //#endregion
 export { QueueWorkCommand };

package/dist/commands/QueueWorkCommand.js

@@ -1,7 +1,9 @@
-import { t as Queue } from "../QueueManager-C1GIAwK2.js";
+import { r as Worker, t as Queue } from "../QueueManager-Dm9FLISk.js";
 import { Command } from "@h3ravel/musket";
 import { bootArkorm } from "@arkstack/database";
 //#region src/commands/QueueWorkCommand.ts
+/** The message of a thrown value, whatever it is. */
+const reason = (error) => error instanceof Error ? error.message : String(error);
 /**
 * Process jobs from a queue connection.
 */
@@ -16,25 +18,54 @@ var QueueWorkCommand = class extends Command {
     `;
 	description = "Start processing jobs on the queue as a daemon.";
 	async handle() {
-		const connection = this.argument("connection");
-		const worker = Queue.worker(connection);
-		const queue = this.option("queue");
-		if (this.option("once")) {
-			const handled = await worker.runNextJob(queue);
-			this.info(handled ? "Processed one job." : "No jobs available.");
-			return;
-		}
-		this.info(`Processing jobs from [${connection ?? "default"}] connection.`);
+		const connection = Queue.connection(this.argument("connection"));
+		const worker = new Worker(connection).on({
+			onProcessed: (job) => {
+				this.success(`Processed: ${job.name()}`);
+			},
+			onFailed: (job, error, released) => {
+				this.error(released ? `Failed (attempt ${job.attempts()}, retrying): ${job.name()} — ${reason(error)}` : `Failed permanently: ${job.name()} — ${reason(error)}`);
+			}
+		});
+		const queue = this.option("queue") ?? connection.getDefaultQueue();
 		try {
 			bootArkorm();
 		} catch {}
+		await this.registerJobs();
+		if (this.option("once")) {
+			if (!await worker.runNextJob(queue)) this.info("No jobs available.");
+			return;
+		}
+		this.info(`Processing jobs from the [${connection.getConnectionName()}] connection on the [${queue}] queue.`);
 		await worker.daemon({
 			queue,
 			sleep: Number(this.option("sleep") ?? 3),
-			maxJobs: Number(this.option("max-jobs") ?? 0),
-			stopWhenEmpty: Boolean(this.option("stop-when-empty"))
+			maxJobs: Number(this.flag("maxJobs", "max-jobs") ?? 0),
+			stopWhenEmpty: Boolean(this.flag("stopWhenEmpty", "stop-when-empty"))
 		});
 	}
+	/**
+	* Read a multi-word flag. Musket hands over the parsed options camelCased,
+	* so `--stop-when-empty` arrives as `stopWhenEmpty`; the kebab-case name is
+	* accepted too so the flag can't go quietly missing again.
+	*
+	* @param camel  The camelCase key.
+	* @param kebab  The flag as written in the signature.
+	*/
+	flag(camel, kebab) {
+		return this.option(camel) ?? this.option(kebab);
+	}
+	/**
+	* Register the application's job classes with `@arkstack/jobs` when it is
+	* installed. Without it a payload cannot be turned back into a job.
+	*/
+	async registerJobs() {
+		try {
+			const { loadJobs } = await import("@arkstack/jobs");
+			const names = await loadJobs();
+			if (names.length) this.line(`Loaded ${names.length} job class(es).`);
+		} catch {}
+	}
 };
 //#endregion
 export { QueueWorkCommand };

package/dist/index.d.ts

@@ -67,6 +67,11 @@ declare abstract class QueueContract {
   /** The name this connection was resolved under. */
   getConnectionName(): string;
   setConnectionName(name: string): this;
+  /**
+   * The queue this connection works when none is named. Drivers with a
+   * configurable queue override it.
+   */
+  getDefaultQueue(): string;
   /**
    * Push a job onto the queue. Returns the job id.
    */
@@ -241,6 +246,22 @@ interface WorkerOptions {
   /** Stop the daemon as soon as the queue drains. */
   stopWhenEmpty?: boolean;
 }
+/**
+ * Observers for what a worker does with each job. A worker executes jobs the
+ * caller can't see — a dedicated worker process reports what happened through
+ * these, so a job that keeps failing isn't indistinguishable from an idle queue.
+ */
+interface WorkerHandlers {
+  /** A job has been reserved and is about to run. */
+  onProcessing?: (job: Job) => void | Promise<void>;
+  /** A job completed and has been removed from the queue. */
+  onProcessed?: (job: Job) => void | Promise<void>;
+  /**
+   * A job threw. `released` is `true` when it goes back on the queue for
+   * another attempt, `false` when it has exhausted its tries and failed.
+   */
+  onFailed?: (job: Job, error: unknown, released: boolean) => void | Promise<void>;
+}
 /**
  * Pulls jobs from a connection and executes them.
  *
@@ -251,9 +272,17 @@ interface WorkerOptions {
 declare class Worker {
   private readonly connection;
   private shouldStop;
+  private readonly handlers;
   constructor(connection: QueueContract);
   /** Signal a running {@link daemon} loop to stop after the current job. */
   stop(): void;
+  /**
+   * Observe what the worker does with each job. Handlers merge, so they can be
+   * registered in more than one call.
+   *
+   * @param handlers  The callbacks to add.
+   */
+  on(handlers: WorkerHandlers): this;
   /**
    * Pop and process the next job. Returns `true` if a job was processed,
    * `false` when the queue was empty.
@@ -400,6 +429,8 @@ declare class DatabaseQueue extends QueueContract {
   private db?;
   constructor(options: DatabaseConnectionConfig);
   private get defaultQueue();
+  /** The configured queue this connection works when none is named. */
+  getDefaultQueue(): string;
   private database;
   push(job: Queueable, queue?: string): Promise<string>;
   pushRaw(payload: JobPayload, queue?: string, availableAt?: number): Promise<string>;
@@ -432,6 +463,8 @@ declare class RedisQueue extends QueueContract {
   private client?;
   constructor(options: RedisConnectionConfig);
   private get defaultQueue();
+  /** The configured queue this connection works when none is named. */
+  getDefaultQueue(): string;
   private get retryAfter();
   private key;
   private connection;
@@ -449,4 +482,4 @@ declare class RedisQueue extends QueueContract {
   private migrate;
 }
 //#endregion
-export { CustomQueueConnectionRegistry, DatabaseConnectionConfig, DatabaseFacade, DatabaseQueue, Job, JobHandlers, JobPayload, JobResolver, JobRow, JobSerializer, Query, Queue, QueueConfig, QueueConnectionConfig, QueueConnectionFactory, QueueContract, Queueable, RedisClient, RedisConnectionConfig, RedisQueue, SyncConnectionConfig, SyncQueue, Worker, WorkerOptions, configure, resetSerialization, resolveJob, serializeJob, setResolver, setSerializer };
+export { CustomQueueConnectionRegistry, DatabaseConnectionConfig, DatabaseFacade, DatabaseQueue, Job, JobHandlers, JobPayload, JobResolver, JobRow, JobSerializer, Query, Queue, QueueConfig, QueueConnectionConfig, QueueConnectionFactory, QueueContract, Queueable, RedisClient, RedisConnectionConfig, RedisQueue, SyncConnectionConfig, SyncQueue, Worker, WorkerHandlers, WorkerOptions, configure, resetSerialization, resolveJob, serializeJob, setResolver, setSerializer };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as RedisQueue, c as Job, d as serializeJob, f as setResolver, i as SyncQueue, l as resetSerialization, n as configure, o as DatabaseQueue, p as setSerializer, r as Worker, s as QueueContract, t as Queue, u as resolveJob } from "./QueueManager-C1GIAwK2.js";
+import { a as RedisQueue, c as Job, d as serializeJob, f as setResolver, i as SyncQueue, l as resetSerialization, n as configure, o as DatabaseQueue, p as setSerializer, r as Worker, s as QueueContract, t as Queue, u as resolveJob } from "./QueueManager-Dm9FLISk.js";
 export { DatabaseQueue, Job, Queue, QueueContract, RedisQueue, SyncQueue, Worker, configure, resetSerialization, resolveJob, serializeJob, setResolver, setSerializer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/queue",
-  "version": "0.18.3",
+  "version": "0.18.4",
   "type": "module",
   "description": "Queue module for Arkstack, providing a driver based queue transport and worker for background processing.",
   "homepage": "https://arkstack.toneflix.net/guide/queue",
@@ -34,13 +34,13 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@arkstack/common": "^0.18.3"
+    "@arkstack/common": "^0.18.4"
   },
   "peerDependencies": {
     "@h3ravel/musket": "^2.2.13",
     "ioredis": "^5.4.1",
-    "@arkstack/contract": "^0.18.3",
-    "@arkstack/database": "^0.18.3"
+    "@arkstack/contract": "^0.18.4",
+    "@arkstack/database": "^0.18.4"
   },
   "peerDependenciesMeta": {
     "@arkstack/database": {