@arkstack/queue 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toneflix Technologies Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @arkstack/queue
+
+[![@arkstack/queue](https://img.shields.io/npm/dt/@arkstack/queue?style=flat-square&label=@arkstack/queue&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F@arkstack/queue)](https://www.npmjs.com/package/@arkstack/queue)
+
+Queue module for Arkstack, providing a driver based queue transport and worker for background processing.
+
+`@arkstack/queue` is the **transport** layer: connections, drivers, and the worker. Author your jobs with [`@arkstack/jobs`](../jobs), which provides the `Job` base class and a `dispatch()` helper on top of this package.
+
+## Connections
+
+| Driver     | Backing store                       | Notes                                   |
+| ---------- | ----------------------------------- | --------------------------------------- |
+| `sync`     | runs inline                         | default; no worker, great for dev/tests |
+| `database` | a table via `@arkstack/database`    | a polling worker drains it              |
+| `redis`    | Redis lists/sorted sets (`ioredis`) | distributed, supports delays            |
+
+## Configuration
+
+```ts
+// src/config/queue.ts
+import type { QueueConfig } from '@arkstack/queue';
+
+export default (): QueueConfig => ({
+  default: env('QUEUE_CONNECTION', 'sync'),
+  connections: {
+    sync: { driver: 'sync' },
+    database: { driver: 'database', table: 'jobs', queue: 'default' },
+    redis: {
+      driver: 'redis',
+      host: env('REDIS_HOST', '127.0.0.1'),
+      port: env('REDIS_PORT', 6379),
+    },
+  },
+});
+```
+
+## Usage
+
+```ts
+import { Queue } from '@arkstack/queue';
+
+await Queue.push(new SendWelcomeEmail(user)); // onto the default connection
+await Queue.later(60, new ChargeInvoice(invoiceId)); // after 60 seconds
+await Queue.connection('redis').push(job, 'emails'); // a specific connection/queue
+await Queue.size('emails');
+await Queue.clear('emails');
+```
+
+## Workers
+
+```bash
+ark queue:work                      # daemon on the default connection
+ark queue:work redis --queue=emails
+ark queue:work --once               # process a single job and exit
+ark queue:clear redis --queue=emails
+```
+
+Programmatically:
+
+```ts
+import { Queue } from '@arkstack/queue';
+
+const worker = Queue.worker('database');
+await worker.daemon({ queue: 'default', sleep: 3 });
+```
+
+A job is **deleted** on success, **released** for another attempt on failure, and **marked failed** (invoking its `failed` hook) once it exhausts `tries`.
+
+## Job (de)serialization
+
+Drivers other than `sync` store a serialized payload and need to reconstruct job
+instances in the worker. `@arkstack/jobs` registers these strategies for you; to
+do it manually:
+
+```ts
+import { Queue } from '@arkstack/queue';
+
+Queue.serializeUsing((job) => ({
+  /* JobPayload */
+}));
+Queue.resolveJobsUsing((payload) => rebuildJob(payload));
+```

package/dist/QueueManager-DFdwxyXk.js

@@ -0,0 +1,603 @@
+import { randomUUID } from "node:crypto";
+import { config } from "@arkstack/common";
+//#region src/serialization.ts
+/**
+* Pluggable (de)serialization for queued jobs.
+*
+* The transport drivers don't know how to reconstruct application job classes,
+* so the strategy is injected. `@arkstack/jobs` registers strategies backed by
+* its job registry; standalone usage can register its own, or rely on the
+* defaults (a shallow copy serializer and a resolver that must be overridden).
+*
+* Keeping this in its own module avoids a circular import between the queue
+* manager and the drivers that need to serialize.
+*/
+const defaultSerializer = (job) => {
+	const data = typeof job.serialize === "function" ? job.serialize() : { ...job };
+	return {
+		id: randomUUID(),
+		displayName: job.constructor?.name ?? "Closure",
+		attempts: 0,
+		maxTries: job.tries ?? null,
+		backoff: job.backoff ?? 0,
+		data
+	};
+};
+const defaultResolver = () => {
+	throw new Error("No job resolver registered. Install/boot @arkstack/jobs, or call Queue.resolveJobsUsing().");
+};
+let serializer = defaultSerializer;
+let resolver = defaultResolver;
+const setSerializer = (fn) => {
+	serializer = fn;
+};
+const setResolver = (fn) => {
+	resolver = fn;
+};
+const serializeJob = (job) => serializer(job);
+const resolveJob = (payload) => resolver(payload);
+/**
+* Reset the strategies to their defaults. Intended for tests.
+*/
+const resetSerialization = () => {
+	serializer = defaultSerializer;
+	resolver = defaultResolver;
+};
+//#endregion
+//#region src/Job.ts
+/**
+* A runtime handle to a job that has been popped (reserved) from a queue.
+*
+* The worker uses it to inspect attempt counts and to acknowledge completion
+* (`delete`) or schedule a retry (`release`). Drivers create instances and bind
+* the `delete`/`release` behaviour appropriate to their backing store.
+*/
+var Job = class {
+	payload;
+	queue;
+	handlers;
+	deleted = false;
+	released = false;
+	failed = false;
+	constructor(payload, queue, handlers) {
+		this.payload = payload;
+		this.queue = queue;
+		this.handlers = handlers;
+	}
+	/**
+	* The unique job id.
+	* 
+	* @returns 
+	*/
+	id() {
+		return this.payload.id;
+	}
+	/** 
+	* The job's display name (used to resolve the job class). 
+	*/
+	name() {
+		return this.payload.displayName;
+	}
+	/** 
+	* How many times this job has been attempted (including the current run). 
+	*/
+	attempts() {
+		return this.payload.attempts;
+	}
+	/** 
+	* The maximum number of attempts, or `null` for unlimited. 
+	*/
+	maxTries() {
+		return this.payload.maxTries;
+	}
+	/**
+	* Seconds to wait before a released job becomes available again. 
+	*/
+	backoff() {
+		return this.payload.backoff;
+	}
+	/**
+	* Acknowledge the job as done and remove it from the queue. 
+	*/
+	async delete() {
+		this.deleted = true;
+		await this.handlers.delete();
+	}
+	/**
+	* Release the job back onto the queue, optionally after a delay. 
+	*/
+	async release(delay = 0) {
+		this.released = true;
+		await this.handlers.release(delay);
+	}
+	/**
+	* Mark the job as having failed permanently. 
+	*/
+	markAsFailed() {
+		this.failed = true;
+	}
+	isDeleted() {
+		return this.deleted;
+	}
+	isReleased() {
+		return this.released;
+	}
+	hasFailed() {
+		return this.failed;
+	}
+};
+//#endregion
+//#region src/Contracts/QueueContract.ts
+/**
+* The contract every queue connection (transport) driver implements.
+*
+* A connection is responsible only for moving job payloads to and from its
+* backing store. Executing jobs is the {@link import('../Worker').Worker}'s job,
+* and reconstructing job instances is handled by the serialization strategy.
+*/
+var QueueContract = class {
+	connectionName = "default";
+	/** The name this connection was resolved under. */
+	getConnectionName() {
+		return this.connectionName;
+	}
+	setConnectionName(name) {
+		this.connectionName = name;
+		return this;
+	}
+};
+//#endregion
+//#region src/drivers/DatabaseQueue.ts
+const now$1 = () => Math.floor(Date.now() / 1e3);
+/**
+* A queue connection backed by a relational table via `@arkstack/database`.
+*
+* Expected columns: `id` (auto increment), `queue` (string), `payload` (text),
+* `attempts` (int), `reserved_at` (nullable int), `available_at` (int),
+* `created_at` (int). Reservation marks `reserved_at` and bumps `attempts`;
+* completion deletes the row; release clears `reserved_at` and reschedules
+* `available_at`. Use `ark queue:table` (or a migration) to create the table.
+*/
+var DatabaseQueue = class extends QueueContract {
+	options;
+	db;
+	constructor(options) {
+		super();
+		this.options = options;
+	}
+	get defaultQueue() {
+		return this.options.queue ?? "default";
+	}
+	async database() {
+		if (this.db) return this.db;
+		try {
+			const { DB } = await import("@arkstack/database");
+			this.db = DB;
+		} catch {
+			throw new Error("The database queue connection requires the \"@arkstack/database\" package.");
+		}
+		return this.db;
+	}
+	async push(job, queue) {
+		return this.pushRaw(serializeJob(job), queue ?? job.queue);
+	}
+	async pushRaw(payload, queue, availableAt = now$1()) {
+		await (await this.database()).table(this.options.table).insert({
+			queue: queue ?? this.defaultQueue,
+			payload: JSON.stringify(payload),
+			attempts: payload.attempts,
+			reserved_at: null,
+			available_at: availableAt,
+			created_at: now$1()
+		});
+		return payload.id;
+	}
+	async later(delay, job, queue) {
+		const availableAt = delay instanceof Date ? Math.floor(delay.getTime() / 1e3) : now$1() + delay;
+		return this.pushRaw(serializeJob(job), queue ?? job.queue, availableAt);
+	}
+	async pop(queue) {
+		const db = await this.database();
+		const name = queue ?? this.defaultQueue;
+		const row = await this.availableQuery(db, name).orderBy({ id: "asc" }).first();
+		if (!row) return null;
+		const attempts = row.attempts + 1;
+		await db.table(this.options.table).where({ id: row.id }).update({
+			reserved_at: now$1(),
+			attempts
+		});
+		return new Job({
+			...JSON.parse(row.payload),
+			attempts
+		}, name, {
+			delete: async () => {
+				await db.table(this.options.table).where({ id: row.id }).delete();
+			},
+			release: async (delay) => {
+				await db.table(this.options.table).where({ id: row.id }).update({
+					reserved_at: null,
+					available_at: now$1() + delay
+				});
+			}
+		});
+	}
+	async size(queue) {
+		return (await this.database()).table(this.options.table).where({ queue: queue ?? this.defaultQueue }).count();
+	}
+	async clear(queue) {
+		const db = await this.database();
+		const name = queue ?? this.defaultQueue;
+		const count = await this.size(name);
+		await db.table(this.options.table).where({ queue: name }).delete();
+		return count;
+	}
+	/**
+	* Due, unreserved jobs on the given queue, oldest first. Released jobs become
+	* unreserved with a future `available_at`, so they naturally wait their turn.
+	* 
+	* @param db 
+	* @param queue 
+	* @returns 
+	*/
+	availableQuery(db, queue) {
+		return db.table(this.options.table).where({ queue }).whereNull("reserved_at").where("available_at", "<=", now$1());
+	}
+};
+//#endregion
+//#region src/drivers/RedisQueue.ts
+const now = () => Math.floor(Date.now() / 1e3);
+/**
+* A Redis backed queue connection using an ioredis compatible client.
+*
+* Per queue it maintains three structures: a `waiting` list (FIFO), a `delayed`
+* sorted set (scored by availability time), and a `reserved` sorted set (scored
+* by retry-visibility time). On `pop` it first migrates due delayed and expired
+* reserved jobs back to the waiting list, then reserves the head of the list.
+*/
+var RedisQueue = class extends QueueContract {
+	options;
+	client;
+	constructor(options) {
+		super();
+		this.options = options;
+	}
+	get defaultQueue() {
+		return this.options.queue ?? "default";
+	}
+	get retryAfter() {
+		return this.options.retryAfter ?? 90;
+	}
+	key(queue, suffix = "") {
+		return `${this.options.prefix ?? "queues:"}${queue}${suffix}`;
+	}
+	async connection() {
+		if (this.client) return this.client;
+		let Redis;
+		try {
+			Redis = (await import("ioredis")).default;
+		} catch {
+			throw new Error("The redis queue connection requires the \"ioredis\" package.");
+		}
+		this.client = this.options.url ? new Redis(this.options.url) : new Redis({
+			host: this.options.host ?? "127.0.0.1",
+			port: this.options.port ?? 6379,
+			password: this.options.password,
+			db: this.options.db ?? 0
+		});
+		return this.client;
+	}
+	/** Disconnect the underlying client. Useful for tests and shutdown. */
+	async disconnect() {
+		await this.client?.quit();
+		this.client = void 0;
+	}
+	async push(job, queue) {
+		return this.pushRaw(serializeJob(job), queue ?? job.queue);
+	}
+	async pushRaw(payload, queue, availableAt) {
+		const client = await this.connection();
+		const name = queue ?? this.defaultQueue;
+		if (availableAt && availableAt > now()) await client.zadd(this.key(name, ":delayed"), availableAt, JSON.stringify(payload));
+		else await client.rpush(this.key(name), JSON.stringify(payload));
+		return payload.id;
+	}
+	async later(delay, job, queue) {
+		const availableAt = delay instanceof Date ? Math.floor(delay.getTime() / 1e3) : now() + delay;
+		return this.pushRaw(serializeJob(job), queue ?? job.queue, availableAt);
+	}
+	async pop(queue) {
+		const client = await this.connection();
+		const name = queue ?? this.defaultQueue;
+		await this.migrate(client, name);
+		const raw = await client.lpop(this.key(name));
+		if (raw === null) return null;
+		const payload = { ...JSON.parse(raw) };
+		payload.attempts += 1;
+		const reserved = JSON.stringify(payload);
+		await client.zadd(this.key(name, ":reserved"), now() + this.retryAfter, reserved);
+		return new Job(payload, name, {
+			delete: async () => {
+				await client.zrem(this.key(name, ":reserved"), reserved);
+			},
+			release: async (delay) => {
+				await client.zrem(this.key(name, ":reserved"), reserved);
+				if (delay > 0) await client.zadd(this.key(name, ":delayed"), now() + delay, JSON.stringify(payload));
+				else await client.rpush(this.key(name), JSON.stringify(payload));
+			}
+		});
+	}
+	async size(queue) {
+		const client = await this.connection();
+		const name = queue ?? this.defaultQueue;
+		const [waiting, delayed, reserved] = await Promise.all([
+			client.llen(this.key(name)),
+			client.zcard(this.key(name, ":delayed")),
+			client.zcard(this.key(name, ":reserved"))
+		]);
+		return waiting + delayed + reserved;
+	}
+	async clear(queue) {
+		const client = await this.connection();
+		const name = queue ?? this.defaultQueue;
+		const count = await this.size(name);
+		await client.del(this.key(name), this.key(name, ":delayed"), this.key(name, ":reserved"));
+		return count;
+	}
+	/**
+	* Move due delayed jobs and expired reservations back onto the waiting list.
+	*/
+	async migrate(client, queue) {
+		for (const suffix of [":delayed", ":reserved"]) {
+			const key = this.key(queue, suffix);
+			const due = await client.zrangebyscore(key, "-inf", now());
+			for (const member of due) {
+				await client.zrem(key, member);
+				await client.rpush(this.key(queue), member);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/drivers/SyncQueue.ts
+/**
+* The synchronous connection runs jobs inline, the moment they are pushed.
+*
+* It needs no worker and no infrastructure, which makes it the natural default
+* for development and tests. Delays are ignored — the job runs immediately.
+*/
+var SyncQueue = class extends QueueContract {
+	async push(job, _queue) {
+		await this.execute(job);
+		return "sync";
+	}
+	async pushRaw(payload, _queue) {
+		await this.execute(await resolveJob(payload));
+		return payload.id;
+	}
+	async later(_delay, job, _queue) {
+		return this.push(job);
+	}
+	async pop() {
+		return null;
+	}
+	async size() {
+		return 0;
+	}
+	async clear() {
+		return 0;
+	}
+	/**
+	* Run a job, invoking its `failed` hook and rethrowing on error so the
+	* caller (e.g. a dispatch) observes the failure synchronously.
+	* 
+	* @param job 
+	*/
+	async execute(job) {
+		try {
+			await job.handle();
+		} catch (error) {
+			await job.failed?.(error);
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/Worker.ts
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Pulls jobs from a connection and executes them.
+*
+* On success a job is deleted; on failure it is released for another attempt
+* until it exhausts `maxTries`, at which point it is marked failed (invoking the
+* job's `failed` hook) and removed.
+*/
+var Worker = class {
+	connection;
+	shouldStop = false;
+	constructor(connection) {
+		this.connection = connection;
+	}
+	/** Signal a running {@link daemon} loop to stop after the current job. */
+	stop() {
+		this.shouldStop = true;
+	}
+	/**
+	* Pop and process the next job. Returns `true` if a job was processed,
+	* `false` when the queue was empty.
+	*/
+	async runNextJob(queue) {
+		const job = await this.connection.pop(queue);
+		if (!job) return false;
+		await this.process(job);
+		return true;
+	}
+	/**
+	* Execute a single reserved job, handling success and failure.
+	*/
+	async process(job) {
+		try {
+			await (await resolveJob(job.payload)).handle();
+			await job.delete();
+		} catch (error) {
+			await this.handleFailure(job, error);
+		}
+	}
+	/**
+	* Continuously process jobs until stopped (or until the queue drains, when
+	* `stopWhenEmpty` is set).
+	*/
+	async daemon(options = {}) {
+		const sleep = (options.sleep ?? 3) * 1e3;
+		let processed = 0;
+		this.shouldStop = false;
+		while (!this.shouldStop) {
+			if (await this.runNextJob(options.queue)) {
+				processed++;
+				if (options.maxJobs && processed >= options.maxJobs) break;
+				continue;
+			}
+			if (options.stopWhenEmpty) break;
+			await wait(sleep);
+		}
+	}
+	async handleFailure(job, error) {
+		const max = job.maxTries();
+		if (max !== null && job.attempts() >= max) {
+			job.markAsFailed();
+			try {
+				await (await resolveJob(job.payload)).failed?.(error);
+			} catch {}
+			await job.delete();
+			return;
+		}
+		await job.release(job.backoff());
+	}
+};
+//#endregion
+//#region src/config.ts
+/**
+* Read a value from the `queue` configuration namespace with a fallback.
+*
+* Never throws when the config file is missing; returns the default instead.
+*
+* @param key           Dot path within the queue config.
+* @param defaultValue  Value returned when the key is not set.
+*/
+const configure = (key, defaultValue) => {
+	try {
+		return config(`queue.${key}`, defaultValue);
+	} catch {
+		return defaultValue;
+	}
+};
+//#endregion
+//#region src/QueueManager.ts
+/**
+* The queue manager and primary entry point of `@arkstack/queue`.
+*
+* Resolves named connections from configuration, memoizes them, and exposes
+* static convenience methods that proxy the default connection:
+*
+* ```ts
+* await Queue.push(new SendWelcomeEmail(user))
+* await Queue.connection('redis').later(60, new ChargeInvoice(id))
+* ```
+*
+* It also owns the job (de)serialization strategy, which `@arkstack/jobs`
+* configures so workers can reconstruct application job classes.
+*/
+var Queue = class {
+	static connections = {};
+	static customDrivers = {};
+	/**
+	* Resolve a queue connection by name (or the default when omitted).
+	* 
+	* @param name 
+	* @returns 
+	*/
+	static connection(name) {
+		const key = name ?? configure("default", "sync");
+		if (!this.connections[key]) this.connections[key] = this.resolve(key);
+		return this.connections[key];
+	}
+	/**
+	* Register a custom connection driver factory.
+	* 
+	* @param name 
+	* @returns 
+	*/
+	static extend(driver, factory) {
+		this.customDrivers[driver] = factory;
+		return this;
+	}
+	/**
+	* Register how jobs are reconstructed from a payload (used by workers).
+	* 
+	* @param name 
+	* @returns 
+	*/
+	static resolveJobsUsing(resolver) {
+		setResolver(resolver);
+		return this;
+	}
+	/**
+	* Register how job instances are serialized for storage.
+	* 
+	* @param serializer 
+	* @returns 
+	*/
+	static serializeUsing(serializer) {
+		setSerializer(serializer);
+		return this;
+	}
+	/**
+	* Clear memoized connections. Intended for tests or runtime reconfiguration.
+	* 
+	* @param serializer 
+	* @returns 
+	*/
+	static clearResolved() {
+		this.connections = {};
+	}
+	/**
+	* Create a worker bound to the given (or default) connection.
+	* 
+	* @param serializer 
+	* @returns 
+	*/
+	static worker(name) {
+		return new Worker(this.connection(name));
+	}
+	static resolve(name) {
+		const config = configure(`connections.${name}`, void 0);
+		if (!config) throw new Error(`Queue connection "${name}" is not configured.`);
+		return this.createConnection(config, name).setConnectionName(name);
+	}
+	static createConnection(config, name) {
+		switch (config.driver) {
+			case "sync": return new SyncQueue();
+			case "database": return new DatabaseQueue(config);
+			case "redis": return new RedisQueue(config);
+			default:
+				if (this.customDrivers[config.driver]) return this.customDrivers[config.driver](config, name);
+				throw new Error(`Unsupported queue driver: ${config.driver}`);
+		}
+	}
+	static push(job, queue) {
+		return this.connection(job.connection).push(job, queue);
+	}
+	static later(delay, job, queue) {
+		return this.connection(job.connection).later(delay, job, queue);
+	}
+	static pop(queue) {
+		return this.connection().pop(queue);
+	}
+	static size(queue) {
+		return this.connection().size(queue);
+	}
+	static clear(queue) {
+		return this.connection().clear(queue);
+	}
+};
+//#endregion
+export { RedisQueue as a, Job as c, serializeJob as d, setResolver as f, SyncQueue as i, resetSerialization as l, configure as n, DatabaseQueue as o, setSerializer as p, Worker as r, QueueContract as s, Queue as t, resolveJob as u };

package/dist/commands/QueueClearCommand.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "@h3ravel/musket";
+
+//#region src/commands/QueueClearCommand.d.ts
+/**
+ * Delete all of the jobs from a queue.
+ */
+declare class QueueClearCommand extends Command {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<void>;
+}
+//#endregion
+export { QueueClearCommand };

package/dist/commands/QueueClearCommand.js

@@ -0,0 +1,21 @@
+import { t as Queue } from "../QueueManager-DFdwxyXk.js";
+import { Command } from "@h3ravel/musket";
+//#region src/commands/QueueClearCommand.ts
+/**
+* Delete all of the jobs from a queue.
+*/
+var QueueClearCommand = class extends Command {
+	signature = `queue:clear
+        {connection? : The queue connection to clear. Defaults to the configured default.}
+        {--queue= : The queue to clear.}
+    `;
+	description = "Delete all of the jobs from the specified queue.";
+	async handle() {
+		const connection = this.argument("connection");
+		const queue = this.option("queue");
+		const count = await Queue.connection(connection).clear(queue);
+		this.info(`Cleared ${count} job(s) from the [${connection ?? "default"}] connection.`);
+	}
+};
+//#endregion
+export { QueueClearCommand };

package/dist/commands/QueueWorkCommand.d.ts

@@ -0,0 +1,13 @@
+import { Command } from "@h3ravel/musket";
+
+//#region src/commands/QueueWorkCommand.d.ts
+/**
+ * Process jobs from a queue connection.
+ */
+declare class QueueWorkCommand extends Command {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<void>;
+}
+//#endregion
+export { QueueWorkCommand };

package/dist/commands/QueueWorkCommand.js

@@ -0,0 +1,36 @@
+import { t as Queue } from "../QueueManager-DFdwxyXk.js";
+import { Command } from "@h3ravel/musket";
+//#region src/commands/QueueWorkCommand.ts
+/**
+* Process jobs from a queue connection.
+*/
+var QueueWorkCommand = class extends Command {
+	signature = `queue:work
+        {connection? : The queue connection to work. Defaults to the configured default.}
+        {--queue= : The queue to process.}
+        {--sleep=3 : Seconds to sleep when no job is available.}
+        {--max-jobs=0 : Stop after processing this many jobs (0 for unlimited).}
+        {--once : Process a single job and exit.}
+        {--stop-when-empty : Stop when the queue is empty.}
+    `;
+	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.`);
+		await worker.daemon({
+			queue,
+			sleep: Number(this.option("sleep") ?? 3),
+			maxJobs: Number(this.option("max-jobs") ?? 0),
+			stopWhenEmpty: Boolean(this.option("stop-when-empty"))
+		});
+	}
+};
+//#endregion
+export { QueueWorkCommand };

package/dist/index.d.ts

@@ -0,0 +1,452 @@
+import { DotPath, DotPathValue } from "@arkstack/common";
+
+//#region src/Job.d.ts
+/**
+ * A runtime handle to a job that has been popped (reserved) from a queue.
+ *
+ * The worker uses it to inspect attempt counts and to acknowledge completion
+ * (`delete`) or schedule a retry (`release`). Drivers create instances and bind
+ * the `delete`/`release` behaviour appropriate to their backing store.
+ */
+declare class Job {
+  readonly payload: JobPayload;
+  readonly queue: string;
+  private readonly handlers;
+  private deleted;
+  private released;
+  private failed;
+  constructor(payload: JobPayload, queue: string, handlers: JobHandlers);
+  /**
+   * The unique job id.
+   *
+   * @returns
+   */
+  id(): string;
+  /**
+   * The job's display name (used to resolve the job class).
+   */
+  name(): string;
+  /**
+   * How many times this job has been attempted (including the current run).
+   */
+  attempts(): number;
+  /**
+   * The maximum number of attempts, or `null` for unlimited.
+   */
+  maxTries(): number | null;
+  /**
+   * Seconds to wait before a released job becomes available again.
+   */
+  backoff(): number;
+  /**
+   * Acknowledge the job as done and remove it from the queue.
+   */
+  delete(): Promise<void>;
+  /**
+   * Release the job back onto the queue, optionally after a delay.
+   */
+  release(delay?: number): Promise<void>;
+  /**
+   * Mark the job as having failed permanently.
+   */
+  markAsFailed(): void;
+  isDeleted(): boolean;
+  isReleased(): boolean;
+  hasFailed(): boolean;
+}
+//#endregion
+//#region src/Contracts/QueueContract.d.ts
+/**
+ * The contract every queue connection (transport) driver implements.
+ *
+ * A connection is responsible only for moving job payloads to and from its
+ * backing store. Executing jobs is the {@link import('../Worker').Worker}'s job,
+ * and reconstructing job instances is handled by the serialization strategy.
+ */
+declare abstract class QueueContract {
+  protected connectionName: string;
+  /** The name this connection was resolved under. */
+  getConnectionName(): string;
+  setConnectionName(name: string): this;
+  /**
+   * Push a job onto the queue. Returns the job id.
+   */
+  abstract push(job: Queueable, queue?: string): Promise<string>;
+  /**
+   * Push an already-serialized payload onto the queue. Returns the job id.
+   */
+  abstract pushRaw(payload: JobPayload, queue?: string, availableAt?: number): Promise<string>;
+  /**
+   * Push a job to be processed after a delay (seconds or an absolute Date).
+   */
+  abstract later(delay: number | Date, job: Queueable, queue?: string): Promise<string>;
+  /**
+   * Reserve and return the next available job, or `null` when none is ready.
+   */
+  abstract pop(queue?: string): Promise<Job | null>;
+  /**
+   * The number of jobs waiting on the given queue.
+   */
+  abstract size(queue?: string): Promise<number>;
+  /**
+   * Remove every job from the given queue. Returns the number removed.
+   */
+  abstract clear(queue?: string): Promise<number>;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Anything that can be queued and executed by a worker.
+ *
+ * The only hard requirement is a `handle` method. Optional fields let a job
+ * customize its routing and retry behaviour; the `@arkstack/jobs` package builds
+ * a richer base class on top of this contract.
+ */
+interface Queueable {
+  /** Perform the work for this job. */
+  handle(): unknown | Promise<unknown>;
+  /** Serialize the job's state for storage. Defaults to a shallow copy. */
+  serialize?(): Record<string, unknown>;
+  /** Override the queue this job is pushed onto. */
+  queue?: string;
+  /** Override the connection this job is pushed onto. */
+  connection?: string;
+  /** Maximum number of attempts before the job is marked failed. */
+  tries?: number;
+  /** Seconds to wait before a released job becomes available again. */
+  backoff?: number;
+  /** Seconds to delay before the job first becomes available. */
+  delay?: number;
+  /** Called when the job exhausts its attempts. */
+  failed?(error: unknown): unknown | Promise<unknown>;
+}
+/**
+ * The serialized envelope stored on a backing queue and reconstructed by a
+ * worker. `data` carries the job's own serialized state; `displayName` is the
+ * key used to resolve the concrete job class.
+ */
+interface JobPayload {
+  id: string;
+  displayName: string;
+  attempts: number;
+  maxTries: number | null;
+  backoff: number;
+  data: Record<string, unknown>;
+}
+interface SyncConnectionConfig {
+  driver: 'sync';
+}
+interface DatabaseConnectionConfig {
+  driver: 'database';
+  /** The table jobs are stored in. */
+  table: string;
+  /** Default queue name. */
+  queue?: string;
+  /** Seconds after which a reserved-but-unfinished job may be retried. */
+  retryAfter?: number;
+}
+interface RedisConnectionConfig {
+  driver: 'redis';
+  url?: string;
+  host?: string;
+  port?: number;
+  password?: string;
+  db?: number;
+  /** Default queue name. */
+  queue?: string;
+  /** Seconds after which a reserved-but-unfinished job may be retried. */
+  retryAfter?: number;
+  /** Key prefix for queue structures. */
+  prefix?: string;
+}
+/**
+ * Apps may augment this registry to register custom connection driver configs.
+ */
+interface CustomQueueConnectionRegistry {}
+type QueueConnectionConfig = SyncConnectionConfig | DatabaseConnectionConfig | RedisConnectionConfig | ({
+  driver: string;
+} & Record<string, unknown>);
+interface QueueConfig {
+  /** The default connection used when none is requested. */
+  default: string;
+  /** The configured queue connections, keyed by name. */
+  connections: Record<string, QueueConnectionConfig> & CustomQueueConnectionRegistry;
+}
+/** Turns a job instance into a storable payload. */
+type JobSerializer = (job: Queueable) => JobPayload;
+/** Reconstructs a runnable job instance from a payload. */
+type JobResolver = (payload: JobPayload) => Queueable | Promise<Queueable>;
+/** Factory for a custom queue connection driver. */
+type QueueConnectionFactory = (config: QueueConnectionConfig, name: string) => QueueContract;
+/**
+ * Lifecycle callbacks a driver binds to a reserved job so the worker can
+ * acknowledge or retry it without knowing the driver's internals.
+ */
+interface JobHandlers {
+  delete(): Promise<void>;
+  release(delay: number): Promise<void>;
+}
+interface JobRow {
+  id: number | string;
+  queue: string;
+  payload: string;
+  attempts: number;
+  reserved_at: number | null;
+  available_at: number;
+  created_at: number;
+}
+/**
+ * Chainable query surface we rely on from `@arkstack/database`'s `DB`. Declared
+ * locally so the queue package needn't depend on it at build time (it is an
+ * optional peer dependency).
+ */
+interface Query {
+  where(where: Record<string, unknown>): Query;
+  where(column: string, operator: string, value: unknown): Query;
+  whereNull(column: string): Query;
+  orderBy(orderBy: Record<string, 'asc' | 'desc'>): Query;
+  first(): Promise<JobRow | null>;
+  update(values: Record<string, unknown>): Promise<unknown>;
+  delete(): Promise<unknown>;
+  count(): Promise<number>;
+}
+interface DatabaseFacade {
+  table(table: string): Query & {
+    insert(values: Record<string, unknown>): Promise<unknown>;
+  };
+}
+/**
+ * Structural type for the slice of ioredis we use. Declared locally so the
+ * package needn't depend on ioredis at build time (optional peer dependency).
+ */
+interface RedisClient {
+  rpush(key: string, ...values: string[]): Promise<number>;
+  lpop(key: string): Promise<string | null>;
+  llen(key: string): Promise<number>;
+  del(...keys: string[]): Promise<number>;
+  zadd(key: string, score: number, member: string): Promise<unknown>;
+  zrem(key: string, member: string): Promise<number>;
+  zcard(key: string): Promise<number>;
+  zrangebyscore(key: string, min: string | number, max: string | number): Promise<string[]>;
+  quit(): Promise<unknown>;
+}
+//#endregion
+//#region src/Worker.d.ts
+interface WorkerOptions {
+  /** The queue name to pull from. */
+  queue?: string;
+  /** Seconds to wait when the queue is empty before polling again. */
+  sleep?: number;
+  /** Stop after processing this many jobs (0 = unlimited). */
+  maxJobs?: number;
+  /** Stop the daemon as soon as the queue drains. */
+  stopWhenEmpty?: boolean;
+}
+/**
+ * Pulls jobs from a connection and executes them.
+ *
+ * On success a job is deleted; on failure it is released for another attempt
+ * until it exhausts `maxTries`, at which point it is marked failed (invoking the
+ * job's `failed` hook) and removed.
+ */
+declare class Worker {
+  private readonly connection;
+  private shouldStop;
+  constructor(connection: QueueContract);
+  /** Signal a running {@link daemon} loop to stop after the current job. */
+  stop(): void;
+  /**
+   * Pop and process the next job. Returns `true` if a job was processed,
+   * `false` when the queue was empty.
+   */
+  runNextJob(queue?: string): Promise<boolean>;
+  /**
+   * Execute a single reserved job, handling success and failure.
+   */
+  process(job: Job): Promise<void>;
+  /**
+   * Continuously process jobs until stopped (or until the queue drains, when
+   * `stopWhenEmpty` is set).
+   */
+  daemon(options?: WorkerOptions): Promise<void>;
+  private handleFailure;
+}
+//#endregion
+//#region src/QueueManager.d.ts
+/**
+ * The queue manager and primary entry point of `@arkstack/queue`.
+ *
+ * Resolves named connections from configuration, memoizes them, and exposes
+ * static convenience methods that proxy the default connection:
+ *
+ * ```ts
+ * await Queue.push(new SendWelcomeEmail(user))
+ * await Queue.connection('redis').later(60, new ChargeInvoice(id))
+ * ```
+ *
+ * It also owns the job (de)serialization strategy, which `@arkstack/jobs`
+ * configures so workers can reconstruct application job classes.
+ */
+declare class Queue {
+  private static connections;
+  private static customDrivers;
+  /**
+   * Resolve a queue connection by name (or the default when omitted).
+   *
+   * @param name
+   * @returns
+   */
+  static connection(name?: string): QueueContract;
+  /**
+   * Register a custom connection driver factory.
+   *
+   * @param name
+   * @returns
+   */
+  static extend(driver: string, factory: QueueConnectionFactory): typeof Queue;
+  /**
+   * Register how jobs are reconstructed from a payload (used by workers).
+   *
+   * @param name
+   * @returns
+   */
+  static resolveJobsUsing(resolver: JobResolver): typeof Queue;
+  /**
+   * Register how job instances are serialized for storage.
+   *
+   * @param serializer
+   * @returns
+   */
+  static serializeUsing(serializer: JobSerializer): typeof Queue;
+  /**
+   * Clear memoized connections. Intended for tests or runtime reconfiguration.
+   *
+   * @param serializer
+   * @returns
+   */
+  static clearResolved(): void;
+  /**
+   * Create a worker bound to the given (or default) connection.
+   *
+   * @param serializer
+   * @returns
+   */
+  static worker(name?: string): Worker;
+  private static resolve;
+  private static createConnection;
+  static push(job: Queueable, queue?: string): Promise<string>;
+  static later(delay: number | Date, job: Queueable, queue?: string): Promise<string>;
+  static pop(queue?: string): ReturnType<QueueContract['pop']>;
+  static size(queue?: string): Promise<number>;
+  static clear(queue?: string): Promise<number>;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Read a value from the `queue` configuration namespace with a fallback.
+ *
+ * Never throws when the config file is missing; returns the default instead.
+ *
+ * @param key           Dot path within the queue config.
+ * @param defaultValue  Value returned when the key is not set.
+ */
+declare const configure: <T extends DotPath<QueueConfig>>(key: T, defaultValue: unknown) => DotPathValue<QueueConfig, T>;
+//#endregion
+//#region src/serialization.d.ts
+declare const setSerializer: (fn: JobSerializer) => void;
+declare const setResolver: (fn: JobResolver) => void;
+declare const serializeJob: (job: Queueable) => JobPayload;
+declare const resolveJob: (payload: JobPayload) => Queueable | Promise<Queueable>;
+/**
+ * Reset the strategies to their defaults. Intended for tests.
+ */
+declare const resetSerialization: () => void;
+//#endregion
+//#region src/drivers/SyncQueue.d.ts
+/**
+ * The synchronous connection runs jobs inline, the moment they are pushed.
+ *
+ * It needs no worker and no infrastructure, which makes it the natural default
+ * for development and tests. Delays are ignored — the job runs immediately.
+ */
+declare class SyncQueue extends QueueContract {
+  push(job: Queueable, _queue?: string): Promise<string>;
+  pushRaw(payload: JobPayload, _queue?: string): Promise<string>;
+  later(_delay: number | Date, job: Queueable, _queue?: string): Promise<string>;
+  pop(): Promise<Job | null>;
+  size(): Promise<number>;
+  clear(): Promise<number>;
+  /**
+   * Run a job, invoking its `failed` hook and rethrowing on error so the
+   * caller (e.g. a dispatch) observes the failure synchronously.
+   *
+   * @param job
+   */
+  private execute;
+}
+//#endregion
+//#region src/drivers/DatabaseQueue.d.ts
+/**
+ * A queue connection backed by a relational table via `@arkstack/database`.
+ *
+ * Expected columns: `id` (auto increment), `queue` (string), `payload` (text),
+ * `attempts` (int), `reserved_at` (nullable int), `available_at` (int),
+ * `created_at` (int). Reservation marks `reserved_at` and bumps `attempts`;
+ * completion deletes the row; release clears `reserved_at` and reschedules
+ * `available_at`. Use `ark queue:table` (or a migration) to create the table.
+ */
+declare class DatabaseQueue extends QueueContract {
+  private readonly options;
+  private db?;
+  constructor(options: DatabaseConnectionConfig);
+  private get defaultQueue();
+  private database;
+  push(job: Queueable, queue?: string): Promise<string>;
+  pushRaw(payload: JobPayload, queue?: string, availableAt?: number): Promise<string>;
+  later(delay: number | Date, job: Queueable, queue?: string): Promise<string>;
+  pop(queue?: string): Promise<Job | null>;
+  size(queue?: string): Promise<number>;
+  clear(queue?: string): Promise<number>;
+  /**
+   * Due, unreserved jobs on the given queue, oldest first. Released jobs become
+   * unreserved with a future `available_at`, so they naturally wait their turn.
+   *
+   * @param db
+   * @param queue
+   * @returns
+   */
+  private availableQuery;
+}
+//#endregion
+//#region src/drivers/RedisQueue.d.ts
+/**
+ * A Redis backed queue connection using an ioredis compatible client.
+ *
+ * Per queue it maintains three structures: a `waiting` list (FIFO), a `delayed`
+ * sorted set (scored by availability time), and a `reserved` sorted set (scored
+ * by retry-visibility time). On `pop` it first migrates due delayed and expired
+ * reserved jobs back to the waiting list, then reserves the head of the list.
+ */
+declare class RedisQueue extends QueueContract {
+  private readonly options;
+  private client?;
+  constructor(options: RedisConnectionConfig);
+  private get defaultQueue();
+  private get retryAfter();
+  private key;
+  private connection;
+  /** Disconnect the underlying client. Useful for tests and shutdown. */
+  disconnect(): Promise<void>;
+  push(job: Queueable, queue?: string): Promise<string>;
+  pushRaw(payload: JobPayload, queue?: string, availableAt?: number): Promise<string>;
+  later(delay: number | Date, job: Queueable, queue?: string): Promise<string>;
+  pop(queue?: string): Promise<Job | null>;
+  size(queue?: string): Promise<number>;
+  clear(queue?: string): Promise<number>;
+  /**
+   * Move due delayed jobs and expired reservations back onto the waiting list.
+   */
+  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 };

package/dist/index.js

@@ -0,0 +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-DFdwxyXk.js";
+export { DatabaseQueue, Job, Queue, QueueContract, RedisQueue, SyncQueue, Worker, configure, resetSerialization, resolveJob, serializeJob, setResolver, setSerializer };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@arkstack/queue",
+  "version": "0.13.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arkstack-hq/arkstack.git",
+    "directory": "packages/queue"
+  },
+  "keywords": [
+    "queue",
+    "worker",
+    "jobs",
+    "background",
+    "sync",
+    "redis",
+    "database",
+    "arkstack"
+  ],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./commands/QueueClearCommand": "./dist/commands/QueueClearCommand.js",
+    "./commands/QueueWorkCommand": "./dist/commands/QueueWorkCommand.js",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@arkstack/common": "^0.13.0"
+  },
+  "peerDependencies": {
+    "@h3ravel/musket": "^2.2.0",
+    "ioredis": "^5.4.1",
+    "@arkstack/contract": "^0.13.0",
+    "@arkstack/database": "^0.13.0"
+  },
+  "peerDependenciesMeta": {
+    "@arkstack/database": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "version:patch": "pnpm version patch"
+  }
+}