skills/docs/foundation/flow/queue/src/queue/memory-queue.md

memory-queue

Purpose

MemoryQueue<T> is the foundational FIFO queue for @suaveplan/queue. It stores jobs in memory in insertion order and dequeues the first eligible job (respecting delayMs). An optional maxSize cap enforces bounded operation, throwing QueueFullError when the limit is reached.

This queue is suitable for single-process scenarios — worker pools, test harnesses, and local development. For distributed systems, wrap it behind an adapter that delegates to a persistent store.

Features

• Pure in-memory FIFO ordering
• Optional maxSize cap with QueueFullError on overflow
• Delay support via Job.isEligible() — dequeues skip ineligible jobs
• enqueueCount / dequeueCount counters for observability
• clear() for draining between tests
• Implements QueueLike<T> for compatibility with QueueWorker

Usage: Basic Example

import { createMemoryQueue } from "@suaveplan/queue/queue/memory-queue";

const queue = createMemoryQueue<string>();
await queue.enqueue("task-1");
await queue.enqueue("task-2");

const job = await queue.dequeue();
console.log(job?.payload); // "task-1"
console.log(queue.size()); // 1

Usage: Advanced Example

import { createMemoryQueue } from "@suaveplan/queue/queue/memory-queue";
import { QueueFullError } from "@suaveplan/queue/errors/queue-error";

const bounded = createMemoryQueue<number>({ maxSize: 2 });
await bounded.enqueue(1);
await bounded.enqueue(2);
try {
  await bounded.enqueue(3); // throws QueueFullError
} catch (err) {
  console.log(err instanceof QueueFullError); // true
}

// Delayed job: enqueue with 100ms delay
await bounded.clear();
await bounded.enqueue(42, { delayMs: 100 });
const notYet = await bounded.dequeue();
console.log(notYet); // undefined (not yet eligible)

API Reference

createMemoryQueue<T>(options?): MemoryQueue<T>

Factory function. options.maxSize defaults to unbounded.

MemoryQueue<T>

Implements QueueLike<T>.

enqueue(payload, options?): Promise<string>

Returns the generated job ID. Throws QueueFullError when at capacity.

dequeue(): Promise<Job<T> | undefined>

Returns the first eligible job, or undefined if none.

size(): number

Current number of jobs (including delayed ones).

clear(): void

Removes all jobs.

enqueueCount: number / dequeueCount: number

Monotonically increasing counters.

Implementation Notes

The QueueFullError import is dynamic (await import(...)) to avoid a top-level circular import issue between the error module and the queue module. Job IDs are generated with Date.now() + a random suffix — suitable for in-memory uniqueness but not globally unique across processes; replace _generateId() in a subclass for UUID-based IDs.