@vercube/queue 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present - Vercube
+
+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,60 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/vercube/vercube/refs/heads/main/.github/assets/cover.png" width="100%" alt="Vercube - Unleash your server development." />
+  <br>
+  <br>
+
+# @vercube/queue
+
+### Background jobs for Vercube apps
+
+[![Ask DeepWiki](<https://img.shields.io/badge/ask-deepwiki-%20blue?style=for-the-badge&logo=bookstack&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)](https://deepwiki.com/vercube/vercube)
+![NPM Version](<https://img.shields.io/npm/v/%40vercube%2Fqueue?style=for-the-badge&logo=npm&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232e2e2e&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40vercube%2Fqueue>)
+![GitHub License](<https://img.shields.io/github/license/vercube/vercube?style=for-the-badge&logo=gitbook&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)
+![Codecov](<https://img.shields.io/codecov/c/github/vercube/vercube?style=for-the-badge&logo=vitest&logoColor=rgba(255%2C%20255%2C%20255%2C%200.6)&labelColor=%23000&color=%232f2f2f>)
+
+**One job model over BullMQ, RabbitMQ, Kafka or plain memory - publish with `add()`, consume with a decorator, and let the module handle retries, timeouts and validation.**
+
+[Website](https://vercube.dev) • [Documentation](https://vercube.dev/docs/getting-started)
+
+</div>
+
+## ✨ Features
+
+- **One API, four transports** - BullMQ, RabbitMQ, Kafka and an in-memory strategy, mounted side by side
+- **Decorator driven consumers** - `@Consumer()` on the class, `@Job()` on the method, `@AnyJob()` for everything else
+- **Retries that work everywhere** - attempts, fixed or exponential backoff, and timeouts, even on transports without them
+- **Payload validation** - any Standard Schema validates a job before the handler runs
+- **Type-safe queues** - augment the registry and every `add()` is checked against it
+- **Devtools ready** - queues, handlers and processed jobs show up in `@vercube/devtools`
+
+## 📦 Installation
+
+```bash
+pnpm add @vercube/queue
+```
+
+Install the client of the transport you use, they are all optional:
+
+```bash
+pnpm add bullmq       # BullMQ, backed by Redis
+pnpm add amqplib      # RabbitMQ
+pnpm add kafkajs      # Kafka
+```
+
+## 📖 Usage
+
+```ts
+@Consumer({ queue: 'emails', concurrency: 5 })
+export class EmailConsumer {
+  @Job('welcome', { attempts: 3, backoff: { type: 'exponential', delay: 1000 } })
+  public async welcome(payload: { userId: string }): Promise<void> {
+    await this.mailer.send(payload.userId);
+  }
+}
+```
+
+Check out the full [documentation](https://vercube.dev/docs/modules/queue/overview)
+
+## 📜 License
+
+[MIT](https://github.com/vercube/vercube/blob/main/LICENSE)

package/dist/QueueStrategy-DwLPpfFM.mjs

@@ -0,0 +1,237 @@
+//#region src/Errors/QueueError.ts
+/**
+* Error thrown by the queue module.
+* Wraps transport errors with a stable shape so callers can tell what failed
+* and whether the job is worth retrying.
+*/
+var QueueError = class QueueError extends Error {
+	/** The original error that caused this one. */
+	cause;
+	/** The queue operation that failed, for example `publish` or `consume`. */
+	operation;
+	/** Whether processing the job again could succeed. */
+	retryable;
+	/** Additional non-sensitive context about the failure. */
+	metadata;
+	/**
+	* @param message - Human readable description of the failure.
+	* @param operation - Queue operation that failed.
+	* @param cause - Underlying error, when there is one.
+	* @param metadata - Additional non-sensitive context.
+	* @param retryable - Whether processing the job again could succeed, defaults to true.
+	*/
+	constructor(message, operation, cause, metadata, retryable = true) {
+		super(message);
+		this.name = "QueueError";
+		this.operation = operation;
+		this.cause = cause;
+		this.metadata = metadata;
+		this.retryable = retryable;
+		if (Error.captureStackTrace) Error.captureStackTrace(this, QueueError);
+	}
+};
+//#endregion
+//#region src/Utils/Job.ts
+/**
+* Job name a handler registers under to receive every job of its queue that no
+* other handler claims.
+*/
+const WILDCARD_JOB = "*";
+/** Header carrying the job name across transports that have no native notion of one. */
+const JOB_HEADER = "x-job";
+/** Header carrying the current attempt number. */
+const ATTEMPT_HEADER = "x-attempt";
+/** Header carrying the total number of attempts the publisher asked for. */
+const ATTEMPTS_HEADER = "x-attempts";
+/** Header carrying the partition or routing key a job was published with. */
+const KEY_HEADER = "x-key";
+/** Header carrying the priority a job was published with. */
+const PRIORITY_HEADER = "x-priority";
+/**
+* Most attempts a job may ever take.
+*
+* On transports that do not retry natively the budget is read off the wire, so a
+* producer could otherwise ask for an arbitrarily large one and turn a single
+* poison message into an unbounded republish loop.
+*/
+const MAX_ATTEMPTS = 50;
+/**
+* Longest a retry may be held back, one day.
+*
+* An exponential backoff over a large attempt count overflows to `Infinity`,
+* which `setTimeout` clamps to one millisecond: the backoff meant to slow
+* retries down would make them as fast as the runtime allows.
+*/
+const MAX_BACKOFF_MS = 864e5;
+/**
+* Reads a positive integer from a raw header value.
+*
+* @param raw - Header value as received from the transport, in any shape.
+* @param fallback - Value returned when the header is absent or unusable.
+* @param max - Largest value accepted, so a value off the wire cannot be unbounded.
+* @returns The parsed integer, or the fallback.
+*/
+function readNumericHeader(raw, fallback, max = Number.MAX_SAFE_INTEGER) {
+	if (raw === null || raw === void 0) return fallback;
+	const value = Number(typeof raw === "object" ? String(raw) : raw);
+	return Number.isFinite(value) && value > 0 ? Math.min(Math.floor(value), max) : fallback;
+}
+/**
+* Normalizes transport headers into plain strings, so handlers never have to deal
+* with buffers or numbers coming from the wire.
+*
+* @param headers - Raw headers as received from the transport.
+* @returns Headers with string values only.
+*/
+function normalizeHeaders(headers) {
+	if (!headers) return {};
+	const normalized = {};
+	for (const [key, value] of Object.entries(headers)) if (value !== null && value !== void 0) normalized[key] = String(value);
+	return normalized;
+}
+/**
+* Computes how long to wait before the next attempt of a job.
+*
+* @param backoff - Backoff policy, a number being a fixed delay in milliseconds.
+* @param attempt - Attempt that just failed, starting at 1.
+* @returns Delay in milliseconds, zero when no backoff is configured and never above {@link MAX_BACKOFF_MS}.
+*/
+function resolveBackoff(backoff, attempt) {
+	if (!backoff) return 0;
+	if (typeof backoff === "number") return Math.min(Math.max(0, backoff), MAX_BACKOFF_MS);
+	const delay = Math.max(0, backoff.delay);
+	const resolved = backoff.type === "exponential" ? delay * 2 ** Math.max(0, attempt - 1) : delay;
+	return Math.min(resolved, MAX_BACKOFF_MS);
+}
+/**
+* Serializes a payload for transports that only carry bytes.
+*
+* @param payload - Payload to serialize.
+* @returns The payload as a UTF-8 JSON buffer.
+* @throws {QueueError} When the payload cannot be serialized.
+*/
+function encodePayload(payload) {
+	try {
+		return Buffer.from(JSON.stringify(payload ?? null), "utf8");
+	} catch (error) {
+		throw new QueueError("Job payload is not serializable", "encode", error, void 0, false);
+	}
+}
+/**
+* Deserializes a payload received from a transport that only carries bytes.
+* Content that is not JSON is returned as text, so foreign producers do not
+* break the consumer.
+*
+* @param content - Raw bytes received from the transport.
+* @returns The parsed payload, or the raw text when it is not JSON.
+*/
+function decodePayload(content) {
+	if (content === null || content === void 0) return null;
+	const text = typeof content === "string" ? content : Buffer.from(content).toString("utf8");
+	if (text.length === 0) return null;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+/**
+* Generates an id for transports that do not assign one themselves.
+*
+* @returns A unique job id.
+*/
+function generateJobId() {
+	return globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+* Waits for the given number of milliseconds.
+*
+* @param ms - Milliseconds to wait, values below one resolve immediately.
+* @returns Resolves once the delay elapsed.
+*/
+function delay(ms) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms).unref?.();
+	});
+}
+/**
+* Drops the keys whose value is undefined.
+*
+* Options objects are built by spreading whatever the caller set, which leaves
+* own properties holding `undefined` behind. A library that merges options with
+* `Object.assign` cannot tell those apart from a deliberate value, so they have
+* to go before the object is handed over.
+*
+* @param source - Object to clean up.
+* @returns A copy without the undefined entries.
+*/
+function prune(source) {
+	const pruned = {};
+	for (const [key, value] of Object.entries(source)) if (value !== void 0) pruned[key] = value;
+	return pruned;
+}
+//#endregion
+//#region src/Services/QueueStrategy.ts
+/**
+* Base class every queue transport implements.
+*
+* A strategy owns the connection to a broker and translates between the broker's
+* own vocabulary and the module's job model. It stays deliberately thin: routing
+* jobs to handlers, retries, timeouts and metrics all live in the
+* {@link QueueManager}, so every transport behaves the same way.
+*
+* @typeParam InitOptions - Options the strategy needs to connect. Use `undefined`
+* for strategies that need none.
+*
+* @example
+* ```ts
+* export class LogStrategy extends QueueStrategy {
+*   public readonly transport = 'log';
+*
+*   public initialize(): void {}
+*
+*   public async publish(request: QueueTypes.PublishRequest): Promise<QueueTypes.JobRef> {
+*     console.log(request.queue, request.job, request.payload);
+*     return { id: '1', queue: request.queue, job: request.job, strategy: this.transport };
+*   }
+*
+*   public async consume(): Promise<QueueTypes.ConsumerHandle> {
+*     throw new Error('This strategy only publishes');
+*   }
+*
+*   public async close(): Promise<void> {}
+* }
+* ```
+*/
+var QueueStrategy = class {
+	/**
+	* What the transport can do on its own. Anything reported as unsupported is
+	* either emulated by the manager or ignored.
+	*/
+	get capabilities() {
+		return {
+			retries: false,
+			delay: false,
+			priority: false,
+			progress: false,
+			stats: false,
+			peek: false
+		};
+	}
+	/**
+	* Publishes many jobs of the same kind. The default implementation publishes
+	* them one by one, transports with a batch API should override it.
+	*
+	* @param requests - Jobs to publish, all targeting the same queue.
+	* @returns References to the published jobs, in the same order.
+	* @throws {QueueError} When the jobs cannot be published.
+	*/
+	async publishMany(requests) {
+		const refs = [];
+		for (const request of requests) refs.push(await this.publish(request));
+		return refs;
+	}
+};
+//#endregion
+export { resolveBackoff as _, KEY_HEADER as a, PRIORITY_HEADER as c, delay as d, encodePayload as f, readNumericHeader as g, prune as h, JOB_HEADER as i, WILDCARD_JOB as l, normalizeHeaders as m, ATTEMPTS_HEADER as n, MAX_ATTEMPTS as o, generateJobId as p, ATTEMPT_HEADER as r, MAX_BACKOFF_MS as s, QueueStrategy as t, decodePayload as u, QueueError as v };