@qkitt/queue 0.1.0

package/dist/persist/index.d.ts

@@ -0,0 +1,3 @@
+export { createMemoryRowStore, createMemorySnapshotStore, type MemoryRowStore, type MemorySnapshotStore, } from './memory';
+export { createLocalStorageRowStore, createLocalStorageSnapshotStore, createSessionStorageRowStore, createSessionStorageSnapshotStore, createWebRowStore, createWebSnapshotStore, StorageCodecError, type JsonCodec, type WebRowStoreOptions, type WebSnapshotStoreOptions, type WebStorageLike, } from './web-storage';
+//# sourceMappingURL=index.d.ts.map

package/dist/persist/json-codec.util.d.ts

@@ -0,0 +1,13 @@
+export type JsonCodec<T> = {
+    serialize: (value: T) => string;
+    deserialize: (raw: string) => T;
+};
+/** Thrown when storage JSON/codec deserialize fails (corrupt or hostile data). */
+export declare class StorageCodecError extends Error {
+    readonly name = "StorageCodecError";
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export declare const defaultJsonCodec: <T>() => JsonCodec<T>;
+export declare const decodeWithCodec: <T>(label: string, raw: string, deserialize: (raw: string) => T) => T;
+//# sourceMappingURL=json-codec.util.d.ts.map

package/dist/persist/memory.d.ts

@@ -0,0 +1,14 @@
+import type { RowRecord, RowStore, SnapshotStore } from '../queue/persist/persist.types';
+export type MemorySnapshotStore<T> = SnapshotStore<T> & {
+    /** Live in-memory snapshot (mutated by `save`). */
+    readonly data: T[];
+};
+export type MemoryRowStore<T> = RowStore<T> & {
+    /** Live rows head → tail (mutated by insert/remove/clear). */
+    readonly rows: RowRecord<T>[];
+};
+/** In-process snapshot store. Useful for tests and non-durable queues. */
+export declare const createMemorySnapshotStore: <T>(initial?: readonly T[]) => MemorySnapshotStore<T>;
+/** In-process row store with stable ids. */
+export declare const createMemoryRowStore: <T>(initial?: readonly RowRecord<T>[]) => MemoryRowStore<T>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/persist/web-storage-access.util.d.ts

@@ -0,0 +1,10 @@
+/** Minimal Web Storage surface (`localStorage` / `sessionStorage` / mocks). */
+export type WebStorageLike = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+};
+/** Lazy proxy so storage is resolved on each call (SSR / late availability). */
+export declare const lazyGlobalStorage: (name: 'localStorage' | 'sessionStorage') => WebStorageLike;
+export declare const resolveStorage: (storage?: WebStorageLike) => WebStorageLike;
+//# sourceMappingURL=web-storage-access.util.d.ts.map

package/dist/persist/web-storage.d.ts

@@ -0,0 +1,59 @@
+import type { RowStore, SnapshotStore } from '../queue/persist/persist.types';
+import { type JsonCodec } from './json-codec.util';
+import { type WebStorageLike } from './web-storage-access.util';
+export { StorageCodecError, type JsonCodec } from './json-codec.util';
+export type { WebStorageLike } from './web-storage-access.util';
+export type WebSnapshotStoreOptions<T> = {
+    /** Storage key for the full JSON array snapshot. */
+    key: string;
+    /** Defaults to `globalThis.localStorage`. */
+    storage?: WebStorageLike;
+    codec?: JsonCodec<T[]>;
+};
+/**
+ * Snapshot store backed by Web Storage (localStorage / sessionStorage).
+ * Entire queue is one JSON value under `key`.
+ *
+ * Corrupt data throws {@link StorageCodecError}. Supply a validating `codec`
+ * when storage may contain untrusted or versioned payloads.
+ *
+ * **Limits (not multi-tab safe):**
+ * - Reads/writes are not transactional; a failed `setItem` can leave a partial
+ *   or stale snapshot (e.g. quota exceeded).
+ * - Concurrent tabs race on the same key — last write wins; no locking.
+ * - Prefer a single tab owner, or a server-side store for shared durability.
+ */
+export declare const createWebSnapshotStore: <T>(options: WebSnapshotStoreOptions<T>) => SnapshotStore<T>;
+export type WebRowStoreOptions<T> = {
+    /**
+     * Key prefix. Uses:
+     * - `${key}:order` → id list head → tail
+     * - `${key}:row:${id}` → serialized item
+     */
+    key: string;
+    storage?: WebStorageLike;
+    itemCodec?: JsonCodec<T>;
+};
+/**
+ * Row-level store on Web Storage.
+ * Each job is its own key; order is a separate id list (true row ops).
+ *
+ * Corrupt order/row payloads throw {@link StorageCodecError}.
+ * Prefer a validating `itemCodec` for untrusted storage.
+ *
+ * **Limits (not multi-tab safe):**
+ * - `insert` / `remove` / `clear` are multi-key and not atomic — a crash or
+ *   quota error mid-op can leave order list and row keys inconsistent.
+ * - Concurrent tabs race on the same prefix; last writer wins without merge.
+ * - Use one owning tab, or a real DB/backend when durability must be shared.
+ */
+export declare const createWebRowStore: <T>(options: WebRowStoreOptions<T>) => RowStore<T>;
+/** Convenience: snapshot store on `localStorage` (resolved lazily on use). */
+export declare const createLocalStorageSnapshotStore: <T>(key: string, options?: Omit<WebSnapshotStoreOptions<T>, 'key' | 'storage'>) => SnapshotStore<T>;
+/** Convenience: row store on `localStorage` (resolved lazily on use). */
+export declare const createLocalStorageRowStore: <T>(key: string, options?: Omit<WebRowStoreOptions<T>, 'key' | 'storage'>) => RowStore<T>;
+/** Convenience: snapshot store on `sessionStorage` (resolved lazily on use). */
+export declare const createSessionStorageSnapshotStore: <T>(key: string, options?: Omit<WebSnapshotStoreOptions<T>, 'key' | 'storage'>) => SnapshotStore<T>;
+/** Convenience: row store on `sessionStorage` (resolved lazily on use). */
+export declare const createSessionStorageRowStore: <T>(key: string, options?: Omit<WebRowStoreOptions<T>, 'key' | 'storage'>) => RowStore<T>;
+//# sourceMappingURL=web-storage.d.ts.map

package/dist/queue/core/forward.util.d.ts

@@ -0,0 +1,21 @@
+import type { EventMap } from '../../events';
+import type { Queue } from './queue';
+/**
+ * Build a queue decorator surface: start from `queue` (keeps stacked extras
+ * such as `hydrate` / `flush`), then overlay `extra` (overrides win).
+ *
+ * Prefer this over re-listing every {@link Queue} method so new base methods
+ * and inner-wrapper APIs flow through automatically (OCP).
+ *
+ * Non-enumerable layer brands from `queue` are reapplied on the result
+ * (object spread does not copy non-enumerable symbols).
+ */
+export declare const forwardQueue: <TQueue extends object, TExtra extends object>(queue: TQueue, extra: TExtra) => Omit<TQueue, keyof TExtra> & TExtra;
+/** Keys that are part of the core {@link Queue} contract (not decorator extras). */
+export type QueueCoreKeys = keyof Queue<unknown, EventMap>;
+/**
+ * Preserve non-core methods from an inner queue when typing an outer decorator.
+ * e.g. `withWorker(withRowPersist(...))` keeps `flush` / `hydrate` / `rowIds`.
+ */
+export type PreserveQueueExtras<TQueue extends object> = Omit<TQueue, QueueCoreKeys>;
+//# sourceMappingURL=forward.util.d.ts.map

package/dist/queue/core/layers.util.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Decorator layer brands for composition guards.
+ * Uses `Symbol.for` so checks remain valid across duplicate package copies.
+ */
+export declare const WORKER_LAYER: unique symbol;
+export declare const PERSIST_LAYER: unique symbol;
+export type QueueLayerBrand = typeof WORKER_LAYER | typeof PERSIST_LAYER;
+/** Non-enumerable brand on a queue decorator object (idempotent). */
+export declare const markQueueLayer: <T extends object>(queue: T, layer: QueueLayerBrand) => T;
+export declare const hasQueueLayer: (queue: object, layer: QueueLayerBrand) => boolean;
+/** Copy known layer brands from an inner queue onto an outer decorator object. */
+export declare const copyQueueLayers: <T extends object>(from: object, to: T) => T;
+//# sourceMappingURL=layers.util.d.ts.map

package/dist/queue/core/queue.d.ts

@@ -0,0 +1,66 @@
+import { type EventEmitter, type EventMap, type MergeEventMaps } from '../../events';
+export type QueueEvents<T> = {
+    /** Fired after an item is added to the tail. */
+    'queue:enqueued': {
+        item: T;
+        size: number;
+    };
+    /** Fired after an item is removed from the head. */
+    'queue:dequeued': {
+        item: T;
+        size: number;
+    };
+    /** Fired when the last item is dequeued (queue becomes empty). */
+    'queue:emptied': undefined;
+    /** Fired after clear() removes all items. */
+    'queue:cleared': {
+        removed: number;
+    };
+};
+export type Queue<T, TEvents extends EventMap = QueueEvents<T>> = {
+    /** Add an item to the tail (FIFO). Throws {@link QueueFullError} when at `maxSize`. */
+    enqueue: (item: T) => void;
+    /** Remove and return the head item, or `undefined` if empty. */
+    dequeue: () => T | undefined;
+    /** Return the head item without removing it. */
+    peek: () => T | undefined;
+    /** Current number of items. */
+    size: () => number;
+    /** Whether the queue has no items. */
+    isEmpty: () => boolean;
+    /** Remove all items and emit `queue:cleared`. */
+    clear: () => void;
+    /**
+     * Replace all items without emitting queue events.
+     * Used by persist hydrate/rollback so workers are not mid-stream during rebuild.
+     * Throws {@link QueueFullError} when `items.length` exceeds `maxSize`.
+     */
+    replaceAll: (items: readonly T[]) => void;
+    /** Snapshot of items from head to tail (does not mutate). */
+    toArray: () => T[];
+    on: EventEmitter<TEvents>['on'];
+    once: EventEmitter<TEvents>['once'];
+    off: EventEmitter<TEvents>['off'];
+    /** Emit an event (built-in or added via expand). */
+    emit: EventEmitter<TEvents>['emit'];
+    /**
+     * Widen the queue event map with additional event types.
+     * Same queue instance; existing listeners are preserved.
+     */
+    expand: <TExtra extends EventMap>() => Queue<T, MergeEventMaps<TEvents, TExtra>>;
+};
+export type BuildQueueOptions = {
+    /**
+     * Maximum items allowed in the queue.
+     * `enqueue` / `replaceAll` throw {@link QueueFullError} when exceeded.
+     */
+    maxSize?: number;
+};
+/** Thrown when enqueue/replaceAll would exceed {@link BuildQueueOptions.maxSize}. */
+export declare class QueueFullError extends Error {
+    readonly name = "QueueFullError";
+    readonly maxSize: number;
+    constructor(maxSize: number);
+}
+export declare const buildQueue: <T>(options?: BuildQueueOptions) => Queue<T>;
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue/index.d.ts

@@ -0,0 +1,7 @@
+export { buildQueue, QueueFullError, type BuildQueueOptions, type Queue, type QueueEvents, } from './core/queue';
+export { withWorker, type QueueWithWorker, type WithWorkerOptions, type WorkerControls, type WorkerEvents, } from './worker/with-worker';
+export { createId } from './persist/create-id.util';
+export type { RowRecord, RowStore, SnapshotStore } from './persist/persist.types';
+export { withRowPersist, type QueueWithRowPersist, type RowPersistEvents, type RowPersistOptions, } from './persist/with-row-persist';
+export { withSnapshotPersist, type QueueWithSnapshotPersist, type SnapshotPersistEvents, type SnapshotPersistOptions, } from './persist/with-snapshot-persist';
+//# sourceMappingURL=index.d.ts.map

package/dist/queue/persist/create-id.util.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Compact URL-safe ids (nanoid-style alphabet + random bytes).
+ * Used as the default row id factory for {@link withRowPersist}.
+ */
+/**
+ * Generate a compact URL-safe id.
+ * Default length 21 ≈ 126 bits of entropy under `crypto.getRandomValues`.
+ */
+export declare const createId: (size?: number) => string;
+//# sourceMappingURL=create-id.util.d.ts.map

package/dist/queue/persist/hydrate-gate.util.d.ts

@@ -0,0 +1,9 @@
+/** Suppress side effects while restoring from the store. */
+export type HydrateGate = {
+    isSuppressing: () => boolean;
+    run: <R>(fn: () => Promise<R>) => Promise<R>;
+};
+export declare const createHydrateGate: () => HydrateGate;
+/** Reject user mutations while hydrate() is replacing memory from the store. */
+export declare const assertNotHydrating: (gate: HydrateGate) => void;
+//# sourceMappingURL=hydrate-gate.util.d.ts.map

package/dist/queue/persist/persist.support.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared checks and post-hydrate hooks for queue persistence decorators.
+ */
+/**
+ * Fail fast when persist is stacked incorrectly.
+ * Correct order: `withWorker(withRowPersist(queue, store), worker)`.
+ * Do not wrap a worker queue or an already-persisted queue.
+ */
+export declare const assertBareQueueForPersist: (queue: object, wrapperName: string) => void;
+/**
+ * After a silent hydrate rebuild, kick stacked workers that pump on
+ * `queue:enqueued` without re-inserting items into the store.
+ */
+export declare const notifyQueueRestored: <T>(queue: {
+    size: () => number;
+    peek: () => T | undefined;
+    emit: (eventName: string, data: unknown) => void;
+}) => void;
+//# sourceMappingURL=persist.support.d.ts.map

package/dist/queue/persist/persist.types.d.ts

@@ -0,0 +1,23 @@
+/** One durable row, stable id + payload, ordered head → tail when loaded. */
+export type RowRecord<T> = {
+    id: string;
+    item: T;
+};
+/**
+ * Row-level backend (SQL table, KV with per-job keys, etc.).
+ * `loadAll` must return rows in FIFO order (head first).
+ */
+export type RowStore<T> = {
+    loadAll: () => readonly RowRecord<T>[] | Promise<readonly RowRecord<T>[]>;
+    insert: (record: RowRecord<T>) => void | Promise<void>;
+    remove: (id: string) => void | Promise<void>;
+    clear: () => void | Promise<void>;
+};
+/** Whole-queue dump/restore backend (file, redis key, etc.). */
+export type SnapshotStore<T> = {
+    /** Load items head → tail. */
+    load: () => readonly T[] | Promise<readonly T[]>;
+    /** Replace the stored snapshot with the full queue. */
+    save: (items: readonly T[]) => void | Promise<void>;
+};
+//# sourceMappingURL=persist.types.d.ts.map

package/dist/queue/persist/row-ids.util.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parallel id list for row-persist (head at `idHead`, same FIFO order as the queue).
+ * Mirrors the queue's head-index buffer so dequeue stays O(1) amortized.
+ */
+export type RowIdList = {
+    push: (id: string) => void;
+    shift: () => string | undefined;
+    reset: (next: readonly string[]) => void;
+    /** Live ids head → tail (aligned with `queue.toArray()`). */
+    live: () => string[];
+    liveCount: () => number;
+};
+export declare const createRowIdList: () => RowIdList;
+//# sourceMappingURL=row-ids.util.d.ts.map

package/dist/queue/persist/with-row-persist.d.ts

@@ -0,0 +1,72 @@
+import { type EventMap, type MergeEventMaps } from '../../events';
+import type { Queue, QueueEvents } from '../core/queue';
+import type { RowStore } from './persist.types';
+export { createId } from './create-id.util';
+export type { RowRecord, RowStore } from './persist.types';
+export type RowPersistEvents<T> = {
+    'persist:loaded': {
+        size: number;
+    };
+    'persist:inserted': {
+        id: string;
+        item: T;
+    };
+    'persist:removed': {
+        id: string;
+        item: T;
+    };
+    'persist:cleared': {
+        removed: number;
+    };
+    'persist:error': {
+        operation: 'load' | 'insert' | 'remove' | 'clear';
+        error: unknown;
+        id?: string;
+    };
+};
+export type RowPersistOptions = {
+    /**
+     * Custom id factory for new rows (enqueue).
+     * Defaults to {@link createId} (nanoid-style URL-safe alphabet).
+     * Must return unique ids under concurrent enqueue.
+     *
+     * @example
+     * withRowPersist(queue, store, { createId: () => crypto.randomUUID() })
+     */
+    createId?: () => string;
+};
+type RowQueueEvents<T, TEvents extends EventMap> = MergeEventMaps<TEvents, RowPersistEvents<T>>;
+export type QueueWithRowPersist<T, TEvents extends EventMap = RowQueueEvents<T, QueueEvents<T>>> = Queue<T, TEvents> & {
+    /** Replace in-memory queue from store rows (head → tail). */
+    hydrate: () => Promise<void>;
+    /** Ids currently in the queue, head → tail (aligned with `toArray()`). */
+    rowIds: () => string[];
+    /**
+     * Wait for pending store mutations to settle.
+     * Store writes are async (enqueue/dequeue stay sync); use this when you
+     * need durability before continuing (e.g. before process exit).
+     */
+    flush: () => Promise<void>;
+};
+/**
+ * Persist each queue mutation as a row operation.
+ * Good for DB-style backends where enqueue/dequeue map to insert/delete.
+ *
+ * **Composition (required):** wrap the bare queue, then the worker:
+ * `withWorker(withRowPersist(buildQueue(), store), worker)`.
+ * Reverse order silently skips store removes — this helper throws if it
+ * detects a worker already on the queue.
+ *
+ * Durability:
+ * - Memory updates are optimistic and synchronous (API stays sync).
+ * - Store ops are serialized on a write chain.
+ * - Failed **insert** rolls back that row from memory if it is still present.
+ * - Failed **remove** / **clear** emit `persist:error` (memory already changed;
+ *   call `hydrate` to resync if needed).
+ * - `hydrate` uses a silent rebuild (no mid-hydrate worker drain of the store),
+ *   then emits one `queue:enqueued` so stacked workers pump after the gate opens.
+ * - Concurrent mutations during `hydrate` throw.
+ * - Call {@link QueueWithRowPersist.flush} to await pending writes.
+ */
+export declare const withRowPersist: <T, TEvents extends QueueEvents<T> = QueueEvents<T>>(queue: Queue<T, TEvents>, store: RowStore<T>, options?: RowPersistOptions) => QueueWithRowPersist<T, RowQueueEvents<T, TEvents>>;
+//# sourceMappingURL=with-row-persist.d.ts.map

package/dist/queue/persist/with-snapshot-persist.d.ts

@@ -0,0 +1,45 @@
+import { type EventMap, type MergeEventMaps } from '../../events';
+import type { Queue, QueueEvents } from '../core/queue';
+import type { SnapshotStore } from './persist.types';
+export type { SnapshotStore } from './persist.types';
+export type SnapshotPersistEvents = {
+    'persist:loaded': {
+        size: number;
+    };
+    'persist:saved': {
+        size: number;
+    };
+    'persist:error': {
+        operation: 'load' | 'save';
+        error: unknown;
+    };
+};
+export type SnapshotPersistOptions = {
+    /**
+     * Automatically `save` after enqueue / dequeue / clear.
+     * Defaults to `true`.
+     */
+    autoSave?: boolean;
+};
+type SnapshotQueueEvents<T, TEvents extends EventMap> = MergeEventMaps<TEvents, SnapshotPersistEvents>;
+export type QueueWithSnapshotPersist<T, TEvents extends EventMap = SnapshotQueueEvents<T, QueueEvents<T>>> = Queue<T, TEvents> & {
+    /** Replace in-memory queue contents from the store. */
+    hydrate: () => Promise<void>;
+    /** Write the current queue (head → tail) to the store. */
+    persist: () => Promise<void>;
+    /** Wait for pending auto-saves (and in-flight `persist`) to settle. */
+    flush: () => Promise<void>;
+};
+/**
+ * Persist the whole queue as one snapshot.
+ * Good for simple backends where you rewrite the full list each time.
+ *
+ * **Composition (required):** wrap the bare queue, then the worker:
+ * `withWorker(withSnapshotPersist(buildQueue(), store), worker)`.
+ *
+ * Uses silent hydrate rebuild + a post-gate `queue:enqueued` kick so stacked
+ * workers process restored items only after auto-save is allowed again.
+ * Concurrent mutations during `hydrate` throw.
+ */
+export declare const withSnapshotPersist: <T, TEvents extends QueueEvents<T> = QueueEvents<T>>(queue: Queue<T, TEvents>, store: SnapshotStore<T>, options?: SnapshotPersistOptions) => QueueWithSnapshotPersist<T, SnapshotQueueEvents<T, TEvents>>;
+//# sourceMappingURL=with-snapshot-persist.d.ts.map

package/dist/queue/persist/write-chain.util.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Serialize async store mutations so concurrent enqueue/dequeue/clear
+ * cannot race the backend.
+ */
+export type WriteChain = {
+    /** Enqueue an operation; returned promise settles when this op finishes. */
+    push: (op: () => Promise<void>) => Promise<void>;
+    /** Wait until all currently queued ops have settled. */
+    flush: () => Promise<void>;
+};
+export declare const createWriteChain: () => WriteChain;
+//# sourceMappingURL=write-chain.util.d.ts.map

package/dist/queue/worker/with-worker.d.ts

@@ -0,0 +1,56 @@
+import { type EventMap, type MergeEventMaps } from '../../events';
+import type { WorkerFn } from '../../worker/types';
+import { type PreserveQueueExtras } from '../core/forward.util';
+import type { Queue, QueueEvents } from '../core/queue';
+export type { WorkerFn };
+export type WorkerEvents<T, R = unknown> = {
+    /** Fired just before the worker runs an item. */
+    'worker:started': {
+        item: T;
+    };
+    /** Fired when the worker resolves successfully. */
+    'worker:completed': {
+        item: T;
+        result: R;
+    };
+    /** Fired when the worker throws or rejects. */
+    'worker:failed': {
+        item: T;
+        error: unknown;
+    };
+    /** Fired when nothing is in-flight and the queue is empty. */
+    'worker:idle': undefined;
+};
+export type WithWorkerOptions = {
+    /** Max items processed at the same time. Defaults to 1. Must be a finite number ≥ 1. */
+    concurrency?: number;
+    /** Start pumping immediately. Defaults to true. */
+    autoStart?: boolean;
+};
+type WorkerQueueEvents<T, R, TEvents extends EventMap> = MergeEventMaps<TEvents, WorkerEvents<T, R>>;
+export type WorkerControls = {
+    /** Begin processing queued items. */
+    start: () => void;
+    /** Stop taking new items. In-flight work still finishes. */
+    stop: () => void;
+    /** Whether the worker is allowed to take new items. */
+    isRunning: () => boolean;
+    /** Whether any items are currently being processed. */
+    isProcessing: () => boolean;
+    /** Number of items currently being processed. */
+    activeCount: () => number;
+};
+export type QueueWithWorker<T, R = unknown, TEvents extends EventMap = WorkerQueueEvents<T, R, QueueEvents<T>>> = Queue<T, TEvents> & WorkerControls;
+/**
+ * Wrap a queue with a worker that dequeues and processes items FIFO-style.
+ * Listens for `queue:enqueued` and pumps work up to `concurrency`.
+ *
+ * **Composition (required when using persist):** worker must be the **outer**
+ * decorator so `dequeue` hits the persist override:
+ * `withWorker(withRowPersist(buildQueue(), store), worker)` — not the reverse.
+ *
+ * Inner decorator extras (e.g. `flush` from row/snapshot persist) are preserved
+ * at runtime and in the return type via {@link PreserveQueueExtras}.
+ */
+export declare const withWorker: <T, R = unknown, TEvents extends QueueEvents<T> = QueueEvents<T>, TQueue extends Queue<T, TEvents> = Queue<T, TEvents>>(queue: TQueue & Queue<T, TEvents>, worker: WorkerFn<T, R>, options?: WithWorkerOptions) => QueueWithWorker<T, R, WorkerQueueEvents<T, R, TEvents>> & PreserveQueueExtras<TQueue>;
+//# sourceMappingURL=with-worker.d.ts.map

package/dist/router/index.d.ts

@@ -0,0 +1,3 @@
+export { buildRouter, type Binding, type BuildRouterOptions, type RouteMessage, type RouteTarget, type Router, type RouterEvents, type UnmatchedRecord, } from './router';
+export { isValidPattern, isValidTopic, matchTopic, MULTI_WILDCARD, SINGLE_WILDCARD, TOPIC_SEPARATOR, } from './match.util';
+//# sourceMappingURL=index.d.ts.map

package/dist/router/match.util.d.ts

@@ -0,0 +1,24 @@
+/** Dot-separated topic segments, e.g. `orders.created.eu`. */
+export declare const TOPIC_SEPARATOR = ".";
+/** Matches exactly one non-empty segment. */
+export declare const SINGLE_WILDCARD = "*";
+/** Matches zero or more segments; only valid as the final pattern token. */
+export declare const MULTI_WILDCARD = "#";
+/**
+ * Validate a concrete publish topic (no wildcards, no empty segments).
+ */
+export declare const isValidTopic: (topic: string) => boolean;
+/**
+ * Validate a bind pattern (`*`, `#` allowed; `#` only as last segment).
+ */
+export declare const isValidPattern: (pattern: string) => boolean;
+/**
+ * MQTT / AMQP-style topic match.
+ *
+ * - `orders.created` matches only that topic
+ * - `orders.*` matches `orders.created`, not `orders.a.b`
+ * - `orders.#` matches `orders`, `orders.created`, `orders.a.b`
+ * - `#` matches everything
+ */
+export declare const matchTopic: (pattern: string, topic: string) => boolean;
+//# sourceMappingURL=match.util.d.ts.map

package/dist/router/router.d.ts

@@ -0,0 +1,107 @@
+import { type EventEmitter, type EventMap, type MergeEventMaps } from '../events';
+/**
+ * Envelope enqueued into bound queues.
+ * `topic` is the concrete published topic (wildcards resolved).
+ */
+export type RouteMessage<T = unknown> = {
+    topic: string;
+    data: T;
+};
+/** Minimal queue surface the router needs. */
+export type RouteTarget<T = unknown> = {
+    enqueue: (item: RouteMessage<T>) => void;
+};
+/** Snapshot of the most recent unrouted publish. */
+export type UnmatchedRecord = {
+    topic: string;
+    data: unknown;
+};
+export type BuildRouterOptions = {
+    /**
+     * When a publish matches **no** bindings, enqueue a {@link RouteMessage}
+     * here (same shape as a normal route). Optional — stats + events still
+     * track unmatched publishes without a sink.
+     */
+    unmatchedTarget?: RouteTarget;
+};
+export type RouterEvents = {
+    'router:bound': {
+        pattern: string;
+    };
+    'router:unbound': {
+        pattern: string;
+        removed: number;
+    };
+    'router:published': {
+        topic: string;
+        data: unknown;
+        matched: number;
+    };
+    /**
+     * Fired when no binding matched.
+     * `delivered` is true only if {@link BuildRouterOptions.unmatchedTarget}
+     * (or a target set via {@link Router.setUnmatchedTarget}) accepted the message.
+     */
+    'router:unmatched': {
+        topic: string;
+        data: unknown;
+        delivered: boolean;
+    };
+    'router:error': {
+        operation: 'publish' | 'bind' | 'unmatched';
+        error: unknown;
+        topic?: string;
+        pattern?: string;
+    };
+};
+export type Binding<T = unknown> = {
+    pattern: string;
+    target: RouteTarget<T>;
+};
+export type Router<TEvents extends EventMap = RouterEvents> = {
+    /**
+     * Bind a queue (or any `enqueue` target) to a topic pattern.
+     * Returns an unbind function for this binding only.
+     *
+     * Patterns use `.` segments:
+     * - `orders.created` exact
+     * - `orders.*` one segment
+     * - `orders.#` zero or more trailing segments
+     */
+    bind: <T = unknown>(pattern: string, target: RouteTarget<T>) => () => void;
+    /** Remove one binding, or all bindings for a pattern if target omitted. */
+    unbind: <T = unknown>(pattern: string, target?: RouteTarget<T>) => void;
+    /**
+     * Publish an event on a concrete topic. Enqueues a {@link RouteMessage}
+     * into every matching target. Returns the number of matched bindings
+     * (0 when unrouted; the unmatched sink does not count as a match).
+     */
+    publish: <T = unknown>(topic: string, data: T) => number;
+    /** Snapshot of current pattern → target bindings. */
+    bindings: () => Binding[];
+    /** Clear all bindings (does not clear unmatched stats or the sink target). */
+    clear: () => void;
+    /**
+     * Optional sink for unrouted publishes (`matched === 0`).
+     * Pass `undefined` to clear.
+     */
+    setUnmatchedTarget: (target: RouteTarget | undefined) => void;
+    /** Current unmatched sink, if any. */
+    getUnmatchedTarget: () => RouteTarget | undefined;
+    /** How many publishes have been unrouted since the last {@link clearUnmatched}. */
+    unmatchedCount: () => number;
+    /** Most recent unrouted publish, if any. */
+    lastUnmatched: () => UnmatchedRecord | undefined;
+    /** Reset unmatched count and last record (does not drain the sink queue). */
+    clearUnmatched: () => void;
+    on: EventEmitter<TEvents>['on'];
+    once: EventEmitter<TEvents>['once'];
+    off: EventEmitter<TEvents>['off'];
+    emit: EventEmitter<TEvents>['emit'];
+    expand: <TExtra extends EventMap>() => Router<MergeEventMaps<TEvents, TExtra>>;
+};
+/**
+ * Topic router / controller: publish events, route into queues by pattern.
+ */
+export declare const buildRouter: (options?: BuildRouterOptions) => Router;
+//# sourceMappingURL=router.d.ts.map

package/dist/worker/index.d.ts

@@ -0,0 +1,4 @@
+export type { StepFn, WorkerFn } from './types';
+export { RetryExhaustedError, withRetry, type RetryOptions, } from './retry';
+export { pipeline } from './pipeline';
+//# sourceMappingURL=index.d.ts.map