@vercube/queue 1.3.0

package/dist/Strategies/MemoryStrategy.mjs

@@ -0,0 +1,305 @@
+import { g as readNumericHeader, p as generateJobId, r as ATTEMPT_HEADER, t as QueueStrategy } from "../QueueStrategy-DwLPpfFM.mjs";
+//#region src/Strategies/MemoryStrategy.ts
+/**
+* In-process queue implementation.
+*
+* Jobs never leave the running process, which makes this the strategy to use in
+* tests, in examples and for background work that may be lost on restart. It is
+* also the reference implementation: delays, priorities and progress all behave
+* exactly as the module documents them.
+*
+* @example
+* ```ts
+* await queueManager.mount({ strategy: MemoryStrategy });
+* ```
+*/
+var MemoryStrategy = class extends QueueStrategy {
+	/** Transport this strategy talks to. */
+	transport = "memory";
+	/** Queues created so far, indexed by name */
+	fQueues = /* @__PURE__ */ new Map();
+	/** Monotonic counter keeping jobs of equal priority in publish order */
+	fSequence = 0;
+	/** Callbacks waiting for a condition on the queues to hold */
+	fWaiters = [];
+	/**
+	* Everything the module offers is supported, jobs simply live in memory.
+	*
+	* @returns {QueueTypes.Capabilities} What this strategy supports
+	*/
+	get capabilities() {
+		return {
+			retries: false,
+			delay: true,
+			priority: true,
+			progress: true,
+			stats: true,
+			peek: true
+		};
+	}
+	/**
+	* Nothing to connect to.
+	*
+	* @returns {void}
+	*/
+	initialize() {}
+	/**
+	* Adds a job to an in-memory queue, honouring its delay and priority.
+	*
+	* @param {QueueTypes.PublishRequest} request - Job to publish
+	* @returns {Promise<QueueTypes.JobRef>} Reference to the published job
+	*/
+	async publish(request) {
+		const queue = this.queueFor(request.queue);
+		const job = {
+			id: request.options.jobId ?? generateJobId(),
+			job: request.job,
+			payload: request.payload,
+			headers: request.headers,
+			attempt: readNumericHeader(request.headers[ATTEMPT_HEADER], 1),
+			priority: request.options.priority ?? 0,
+			sequence: this.fSequence++
+		};
+		const delay = request.options.delay ?? 0;
+		if (delay > 0) {
+			const timer = setTimeout(() => {
+				queue.delayed.delete(timer);
+				queue.waiting.push(job);
+				this.pump(request.queue);
+			}, delay);
+			timer.unref?.();
+			queue.delayed.set(timer, {
+				job,
+				at: Date.now() + delay
+			});
+		} else {
+			queue.waiting.push(job);
+			this.pump(request.queue);
+		}
+		return {
+			id: job.id,
+			queue: request.queue,
+			job: request.job,
+			strategy: this.transport
+		};
+	}
+	/**
+	* Starts processing a queue. Only one consumer per queue is kept, a second
+	* call replaces the first.
+	*
+	* @param {QueueTypes.ConsumeRequest} request - Queue to consume, its concurrency and the dispatch callback
+	* @returns {Promise<QueueTypes.ConsumerHandle>} Handle used to stop the consumer again
+	*/
+	async consume(request) {
+		const queue = this.queueFor(request.queue);
+		queue.consumer = {
+			concurrency: Math.max(1, request.concurrency),
+			dispatch: request.dispatch
+		};
+		this.pump(request.queue);
+		return {
+			queue: request.queue,
+			stop: async () => {
+				queue.consumer = void 0;
+				await this.waitFor(() => queue.active === 0);
+			}
+		};
+	}
+	/**
+	* Reads the counters of a queue.
+	*
+	* @param {string} name - Queue to read
+	* @returns {Promise<QueueTypes.QueueStats>} Counters of that queue
+	*/
+	async stats(name) {
+		const queue = this.fQueues.get(name);
+		return {
+			waiting: queue?.waiting.length ?? 0,
+			active: queue?.active ?? 0,
+			completed: queue?.completed ?? 0,
+			failed: queue?.failed ?? 0,
+			delayed: queue?.delayed.size ?? 0
+		};
+	}
+	/**
+	* Shows what a queue is holding: the jobs waiting to run and the ones still
+	* waiting for their delay.
+	*
+	* @param {QueueTypes.PeekRequest} request - Queue to look at, how many messages and which states
+	* @returns {Promise<QueueTypes.PeekedMessage[]>} The messages found, in the order they would run
+	*/
+	async peek(request) {
+		const queue = this.fQueues.get(request.queue);
+		if (!queue) return [];
+		const messages = [];
+		if (request.states.includes("waiting")) for (const job of [...queue.waiting].sort((a, b) => a.priority - b.priority || a.sequence - b.sequence)) messages.push(this.describe(job, "waiting"));
+		if (request.states.includes("delayed")) for (const { job, at } of queue.delayed.values()) messages.push({
+			...this.describe(job, "delayed"),
+			availableAt: at
+		});
+		return messages.slice(0, request.limit);
+	}
+	/**
+	* Drops every queue, pending job and delay timer.
+	*
+	* @returns {Promise<void>} Resolves once everything is dropped
+	*/
+	async close() {
+		for (const queue of this.fQueues.values()) {
+			for (const timer of queue.delayed.keys()) clearTimeout(timer);
+			queue.delayed.clear();
+			queue.waiting.length = 0;
+			queue.consumer = void 0;
+		}
+		this.fQueues.clear();
+		this.notify();
+	}
+	/**
+	* Waits until no job is waiting, delayed or running.
+	* Handy in tests, where publishing and processing happen in the same process.
+	*
+	* @returns {Promise<void>} Resolves once every queue ran dry
+	*/
+	async idle() {
+		return this.waitFor(() => this.isIdle());
+	}
+	/**
+	* Hands as many waiting jobs to the consumer as its concurrency allows.
+	*
+	* @param {string} name - Queue to pump
+	* @returns {void}
+	*/
+	pump(name) {
+		const queue = this.fQueues.get(name);
+		if (!queue?.consumer) return;
+		while (queue.consumer && queue.active < queue.consumer.concurrency && queue.waiting.length > 0) {
+			const job = this.takeNext(queue);
+			if (!job) break;
+			queue.active++;
+			this.run(name, queue, job);
+		}
+		this.notify();
+	}
+	/**
+	* Runs a single job and keeps the queue moving afterwards.
+	*
+	* A rejected dispatch means the job failed for good: the manager has already
+	* applied the retry policy, so nothing is put back on the queue.
+	*
+	* @param {string} name - Queue the job belongs to
+	* @param {MemoryQueue} queue - State of that queue
+	* @param {MemoryJob} job - Job to run
+	* @returns {Promise<void>} Resolves once the job settled
+	*/
+	async run(name, queue, job) {
+		try {
+			await queue.consumer?.dispatch({
+				id: job.id,
+				job: job.job,
+				payload: job.payload,
+				headers: job.headers,
+				attempt: job.attempt,
+				raw: job,
+				updateProgress: (progress) => {
+					job.progress = progress;
+				}
+			});
+			queue.completed++;
+		} catch {
+			queue.failed++;
+		} finally {
+			queue.active--;
+			this.pump(name);
+			this.notify();
+		}
+	}
+	/**
+	* Describes a job the way the module reads a peeked message.
+	*
+	* @param {MemoryJob} job - Job sitting on the queue
+	* @param {QueueTypes.PeekState} state - Where it is sitting
+	* @returns {QueueTypes.PeekedMessage} The message, ready to be inspected
+	*/
+	describe(job, state) {
+		return {
+			id: job.id,
+			job: job.job,
+			state,
+			attempt: job.attempt,
+			payload: job.payload,
+			headers: job.headers
+		};
+	}
+	/**
+	* Picks the job to run next: lowest priority value first, publish order otherwise.
+	*
+	* @param {MemoryQueue} queue - Queue to take from
+	* @returns {MemoryJob | undefined} The next job, or undefined when the queue is empty
+	*/
+	takeNext(queue) {
+		if (queue.waiting.length === 0) return;
+		let index = 0;
+		for (let i = 1; i < queue.waiting.length; i++) {
+			const candidate = queue.waiting[i];
+			const best = queue.waiting[index];
+			if (candidate.priority < best.priority || candidate.priority === best.priority && candidate.sequence < best.sequence) index = i;
+		}
+		return queue.waiting.splice(index, 1)[0];
+	}
+	/**
+	* Returns the state of a queue, creating it on first use.
+	*
+	* @param {string} name - Queue name
+	* @returns {MemoryQueue} State of that queue
+	*/
+	queueFor(name) {
+		let queue = this.fQueues.get(name);
+		if (!queue) {
+			queue = {
+				waiting: [],
+				delayed: /* @__PURE__ */ new Map(),
+				active: 0,
+				completed: 0,
+				failed: 0
+			};
+			this.fQueues.set(name, queue);
+		}
+		return queue;
+	}
+	/**
+	* @returns {boolean} True when no job is waiting, delayed or running
+	*/
+	isIdle() {
+		for (const queue of this.fQueues.values()) if (queue.active > 0 || queue.waiting.length > 0 || queue.delayed.size > 0) return false;
+		return true;
+	}
+	/**
+	* Waits until a condition on the queues holds.
+	*
+	* @param {() => boolean} ready - Condition to wait for, checked after every job settles
+	* @returns {Promise<void>} Resolves once the condition holds
+	*/
+	waitFor(ready) {
+		if (ready()) return Promise.resolve();
+		return new Promise((resolve) => {
+			this.fWaiters.push({
+				ready,
+				resolve
+			});
+		});
+	}
+	/**
+	* Wakes everyone whose condition now holds.
+	*
+	* @returns {void}
+	*/
+	notify() {
+		if (this.fWaiters.length === 0) return;
+		const pending = [];
+		for (const waiter of this.fWaiters) if (waiter.ready()) waiter.resolve();
+		else pending.push(waiter);
+		this.fWaiters = pending;
+	}
+};
+//#endregion
+export { MemoryStrategy };

package/dist/Strategies/RabbitMQStrategy.d.mts

@@ -0,0 +1,205 @@
+import { n as QueueTypes, t as QueueStrategy } from "../QueueStrategy-saWSBeU6.mjs";
+import { Options, RecoveryOptions, SocketOptions } from "amqplib";
+//#region src/Strategies/RabbitMQStrategy.d.ts
+/** Options the RabbitMQ strategy connects with. */
+export interface RabbitMQStrategyOptions {
+  /** Broker to connect to, as an `amqp://` URL or as connection fields. */
+  url: string | Options.Connect;
+  /** Socket options handed to amqplib. */
+  socketOptions?: SocketOptions;
+  /**
+   * Automatic reconnection, on by default. Pass options to tune the backoff,
+   * or false to fail fast instead.
+   * @default true
+   */
+  recovery?: RecoveryOptions | boolean;
+  /**
+   * Options every queue is asserted with.
+   * @default { durable: true }
+   */
+  queueOptions?: Options.AssertQueue;
+  /**
+   * Options every message is published with.
+   * @default { persistent: true }
+   */
+  publishOptions?: Options.Publish;
+  /**
+   * Number of unacknowledged messages a consumer may hold. Defaults to the
+   * concurrency the consumer was started with.
+   */
+  prefetch?: number;
+}
+/**
+ * RabbitMQ backed queue implementation.
+ *
+ * Jobs are plain AMQP messages: the job name travels in the message `type`
+ * property, the module's bookkeeping in the headers, and the payload as JSON.
+ * RabbitMQ has no notion of attempts or delays, so the manager owns them - which
+ * also means a job that has run out of attempts is nacked without requeue, and
+ * ends up wherever the queue's dead letter exchange points.
+ *
+ * @example
+ * ```ts
+ * await queueManager.mount({
+ *   strategy: RabbitMQStrategy,
+ *   initOptions: { url: 'amqp://localhost' },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // a queue that dead-letters what it cannot process
+ * await queueManager.mount({
+ *   strategy: RabbitMQStrategy,
+ *   initOptions: {
+ *     url: 'amqp://localhost',
+ *     queueOptions: { durable: true, deadLetterExchange: 'failed' },
+ *   },
+ * });
+ * ```
+ */
+export declare class RabbitMQStrategy extends QueueStrategy<RabbitMQStrategyOptions> {
+  /** Transport this strategy talks to. */
+  readonly transport: string;
+  /** Logger instance */
+  private gLogger;
+  /** Options the strategy was initialized with */
+  private fOptions;
+  /** The connection, recovering on its own unless recovery was turned off */
+  private fConnection;
+  /** Channel every publish goes through */
+  private fPublishChannel;
+  /** Running consumers, indexed by queue name */
+  private fConsumers;
+  /**
+   * Queues the application asked to consume, indexed by queue name.
+   *
+   * Kept apart from {@link RabbitMQStrategy.fConsumers}, which holds the live
+   * channels: those belong to one connection and are thrown away when it is
+   * replaced, while what should be consumed does not change with a reconnect.
+   */
+  private fRequests;
+  /**
+   * Bumped on every connection. A consumer that finishes starting after its
+   * connection was replaced belongs to a dead one and is discarded.
+   */
+  private fGeneration;
+  /** Queues already asserted on the current connection */
+  private fAsserted;
+  /**
+   * RabbitMQ carries priorities and message counts, while attempts and delays
+   * are left to the manager.
+   *
+   * @returns {QueueTypes.Capabilities} What this strategy supports
+   */
+  get capabilities(): QueueTypes.Capabilities;
+  /**
+   * Opens the connection to the broker.
+   *
+   * @param {RabbitMQStrategyOptions} options - Broker to connect to and the defaults to use
+   * @returns {Promise<void>} Resolves once the connection is open
+   * @throws {QueueError} When no broker is given, or the connection cannot be opened
+   */
+  initialize(options: RabbitMQStrategyOptions): Promise<void>;
+  /**
+   * Sends a job to a queue.
+   *
+   * @param {QueueTypes.PublishRequest} request - Job to publish
+   * @returns {Promise<QueueTypes.JobRef>} Reference to the published job
+   * @throws {QueueError} When the job cannot be sent
+   */
+  publish(request: QueueTypes.PublishRequest): Promise<QueueTypes.JobRef>;
+  /**
+   * Starts consuming a queue on its own channel, so its prefetch is its own.
+   *
+   * A job whose dispatch rejects is nacked without requeue: the manager has
+   * already decided it is not worth another attempt.
+   *
+   * @param {QueueTypes.ConsumeRequest} request - Queue to consume, its concurrency and the dispatch callback
+   * @returns {Promise<QueueTypes.ConsumerHandle>} Handle used to stop the consumer again
+   * @throws {QueueError} When the consumer cannot be started
+   */
+  consume(request: QueueTypes.ConsumeRequest): Promise<QueueTypes.ConsumerHandle>;
+  /**
+   * Opens a channel for a queue and starts delivering its messages.
+   *
+   * @param {QueueTypes.ConsumeRequest} request - Queue to consume, its concurrency and the dispatch callback
+   * @param {number} generation - Connection this consumer is being started for
+   * @returns {Promise<boolean>} Whether the consumer was installed, false when it was no longer wanted
+   * @throws {Error} When the channel or the consumer cannot be created
+   */
+  private startConsumer;
+  /**
+   * Starts a consumer again on a recovered connection.
+   *
+   * Failing here is reported rather than thrown: nothing is waiting on a
+   * recovery, and a queue that cannot be consumed again has to be visible.
+   *
+   * @param {QueueTypes.ConsumeRequest} request - What the consumer was started with
+   * @param {number} generation - Connection being recovered onto
+   * @returns {Promise<void>} Resolves once the consumer is running again, or once the failure was reported
+   */
+  private resume;
+  /**
+   * Reads how many messages are waiting on a queue.
+   *
+   * @param {string} queue - Queue to read
+   * @returns {Promise<QueueTypes.QueueStats>} Counters of that queue
+   * @throws {QueueError} When the queue cannot be inspected
+   */
+  stats(queue: string): Promise<QueueTypes.QueueStats>;
+  /**
+   * Stops every consumer and closes the connection.
+   *
+   * @returns {Promise<void>} Resolves once the connection is closed
+   */
+  close(): Promise<void>;
+  /**
+   * Runs a single delivery and acknowledges it according to the outcome.
+   *
+   * @param {QueueTypes.ConsumeRequest} request - The consumer the message belongs to
+   * @param {ConsumeMessage} message - The delivery
+   * @returns {Promise<void>} Resolves once the message has been settled
+   */
+  private handle;
+  /**
+   * Cancels a consumer, waits for its in-flight messages and closes its channel.
+   *
+   * @param {string} queue - Queue whose consumer is stopped
+   * @returns {Promise<void>} Resolves once the channel is closed
+   */
+  private stopConsumer;
+  /**
+   * Returns the channel every publish goes through, opening it on first use and
+   * after a reconnection.
+   *
+   * @returns {Promise<Channel>} The publish channel
+   * @throws {QueueError} When the strategy is not connected
+   */
+  private publishChannel;
+  /**
+   * Declares a queue once per connection.
+   *
+   * @param {Channel} channel - Channel to declare it on
+   * @param {string} queue - Queue to declare
+   * @returns {Promise<void>} Resolves once the queue exists
+   */
+  private assertQueue;
+  /**
+   * Returns the options the strategy was initialized with.
+   *
+   * @param {string} operation - Operation asking for them, reported in the error
+   * @returns {RabbitMQStrategyOptions} The options
+   * @throws {QueueError} When the strategy has not been initialized
+   */
+  private requireOptions;
+  /**
+   * Returns the open connection.
+   *
+   * @param {string} operation - Operation asking for it, reported in the error
+   * @returns {ChannelModel | RecoveringChannelModel} The connection
+   * @throws {QueueError} When the strategy is not connected
+   */
+  private requireConnection;
+}
+//#endregion