@qkitt/queue 0.1.0

package/dist/config/config-freeze.util.d.ts

@@ -0,0 +1,7 @@
+import type { SystemConfig } from './types';
+/**
+ * Shallow-freeze so callers cannot reassign top-level fields, while keeping
+ * worker / store impl references intact (unlike JSON round-trip).
+ */
+export declare const freezeConfig: <TConfig extends SystemConfig>(config: TConfig) => Readonly<TConfig>;
+//# sourceMappingURL=config-freeze.util.d.ts.map

package/dist/config/from-config.d.ts

@@ -0,0 +1,33 @@
+import type { BuildFromConfigOptions, ConfiguredSystem, SystemConfig } from './types';
+/**
+ * Build named stores, queues, optional workers, and an optional topic router
+ * from a single {@link SystemConfig}.
+ *
+ * ```ts
+ * const config = defineConfig({
+ *   stores: {
+ *     jobsDb: { adapter: 'memory', strategy: 'row' },
+ *     redis: { strategy: 'row', impl: createRedisRowStore() },
+ *   },
+ *   queues: {
+ *     jobs: {
+ *       persist: { store: 'jobsDb' },
+ *       worker: { run: handleJob, concurrency: 2 },
+ *     },
+ *   },
+ *   router: { bindings: [{ pattern: 'jobs.#', queue: 'jobs' }] },
+ * })
+ *
+ * const system = await buildFromConfig(config)
+ * ```
+ *
+ * Order: resolve stores → queue → persist → worker → router bind → hydrate.
+ */
+export declare const buildFromConfig: <TConfig extends SystemConfig, T = unknown>(config: TConfig, options?: BuildFromConfigOptions) => Promise<ConfiguredSystem<TConfig, T>>;
+/**
+ * Parse **data-only** JSON, validate, and build the system.
+ * Workers / custom store `impl` cannot appear in JSON — use a JS module and
+ * {@link buildFromConfig} instead.
+ */
+export declare const buildFromJson: <T = unknown>(json: string, options?: BuildFromConfigOptions) => Promise<ConfiguredSystem<SystemConfig, T>>;
+//# sourceMappingURL=from-config.d.ts.map

package/dist/config/index.d.ts

@@ -0,0 +1,4 @@
+export { buildFromConfig, buildFromJson, } from './from-config';
+export { defineConfig, parseSystemConfig, validateJsConfig, validateSystemConfig, } from './validate';
+export type { BindingConfig, BuildFromConfigOptions, BuiltinStoreAdapter, ConfiguredQueue, ConfiguredSystem, PersistConfig, QueueConfig, ResolvedStore, RouterConfig, StoreDefinition, StoreKind, SystemConfig, WorkerConfig, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/config/parse.util.d.ts

@@ -0,0 +1,12 @@
+import type { BuiltinStoreAdapter } from './types';
+export declare const BUILTIN_ADAPTERS: Set<BuiltinStoreAdapter>;
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+export declare const expectString: (value: unknown, path: string) => string;
+export declare const expectBoolean: (value: unknown, path: string) => boolean;
+/** Finite number ≥ 1 (queue maxSize, worker concurrency, …). */
+export declare const expectPositiveFinite: (value: unknown, path: string) => number;
+export declare const parseAdapter: (value: unknown, path: string) => BuiltinStoreAdapter;
+export declare const isSnapshotStoreLike: (value: unknown) => boolean;
+export declare const isRowStoreLike: (value: unknown) => boolean;
+export declare const parseStrategy: (value: unknown, path: string) => 'snapshot' | 'row';
+//# sourceMappingURL=parse.util.d.ts.map

package/dist/config/store-resolve.util.d.ts

@@ -0,0 +1,11 @@
+import type { RowStore, SnapshotStore } from '../queue/persist/persist.types';
+import type { BuildFromConfigOptions, ResolvedStore, StoreDefinition } from './types';
+export declare const isSnapshotStore: <T>(value: SnapshotStore<T> | RowStore<T>) => value is SnapshotStore<T>;
+export declare const isRowStore: <T>(value: SnapshotStore<T> | RowStore<T>) => value is RowStore<T>;
+/**
+ * Materialize one store definition into a live SnapshotStore or RowStore.
+ * Custom `impl` is used as-is; built-ins are constructed from `adapter`.
+ */
+export declare const resolveStore: <T>(storeName: string, definition: StoreDefinition, options: BuildFromConfigOptions) => ResolvedStore<T>;
+export declare const resolveAllStores: <T>(stores: Record<string, StoreDefinition> | undefined, options: BuildFromConfigOptions) => Record<string, ResolvedStore<T>>;
+//# sourceMappingURL=store-resolve.util.d.ts.map

package/dist/config/types.d.ts

@@ -0,0 +1,205 @@
+import type { WebStorageLike } from '../persist/web-storage-access.util';
+import type { Queue } from '../queue/core/queue';
+import type { RowStore, SnapshotStore } from '../queue/persist/persist.types';
+import type { WithWorkerOptions, WorkerControls } from '../queue/worker/with-worker';
+import type { Router } from '../router';
+import type { WorkerFn } from '../worker/types';
+/**
+ * Built-in store **adapters** the library can construct for you.
+ * Custom backends do not appear here — implement {@link SnapshotStore} or
+ * {@link RowStore} and register the instance under `stores`.
+ */
+export type BuiltinStoreAdapter = 'memory' | 'localStorage' | 'sessionStorage';
+/**
+ * @deprecated Use {@link BuiltinStoreAdapter}. Kept as an alias.
+ */
+export type StoreKind = BuiltinStoreAdapter;
+/**
+ * Named entry in `config.stores`.
+ *
+ * - **Built-in**: `{ adapter, strategy, key? }` — library creates the store.
+ * - **Custom**: `{ strategy, impl }` — your {@link SnapshotStore} / {@link RowStore}.
+ */
+export type StoreDefinition = {
+    strategy: 'snapshot';
+    adapter: BuiltinStoreAdapter;
+    /**
+     * Required when `adapter` is `localStorage` or `sessionStorage`.
+     * Storage key for the full JSON array.
+     */
+    key?: string;
+} | {
+    strategy: 'row';
+    adapter: BuiltinStoreAdapter;
+    /**
+     * Required when `adapter` is `localStorage` or `sessionStorage`.
+     * Key prefix for order list + per-row keys.
+     */
+    key?: string;
+} | {
+    strategy: 'snapshot';
+    /** JS config only — custom snapshot backend. */
+    impl: SnapshotStore<any>;
+} | {
+    strategy: 'row';
+    /** JS config only — custom row backend. */
+    impl: RowStore<any>;
+};
+/**
+ * Queue-level persistence: pick a named store from `config.stores`.
+ * Strategy comes from the store definition, not from the queue.
+ */
+export type PersistConfig = {
+    /** Name of an entry in `config.stores`. */
+    store: string;
+    /**
+     * Snapshot stores only: auto-save after mutations.
+     * Defaults to `true`. Ignored for row stores.
+     */
+    autoSave?: boolean;
+};
+/**
+ * Worker attachment for a queue (JS config only — functions are not JSON).
+ *
+ * ```ts
+ * import { handleJob } from './workers/job'
+ *
+ * worker: handleJob
+ * // or
+ * worker: { run: handleJob, concurrency: 4, autoStart: false }
+ * ```
+ */
+export type WorkerConfig = WorkerFn<any, any> | ({
+    run: WorkerFn<any, any>;
+} & WithWorkerOptions);
+export type QueueConfig = {
+    /**
+     * Maximum items in the in-memory queue (backpressure).
+     * Same semantics as `buildQueue({ maxSize })` — enqueue throws
+     * {@link import('../queue/core/queue').QueueFullError} when exceeded.
+     */
+    maxSize?: number;
+    /** Optional persistence via a named store in `config.stores`. */
+    persist?: PersistConfig;
+    /**
+     * JS config only — process items with {@link withWorker}.
+     * Import the function from your app and pass it here.
+     */
+    worker?: WorkerConfig;
+};
+export type BindingConfig = {
+    /** Topic pattern (`orders.*`, `mail.#`, …). */
+    pattern: string;
+    /** Name of a queue defined under `queues`. */
+    queue: string;
+};
+export type RouterConfig = {
+    bindings?: BindingConfig[];
+    /**
+     * Named queue that receives {@link import('../router').RouteMessage}
+     * envelopes when a publish matches **no** bindings (unrouted).
+     * Must exist under `queues`. The queue is not auto-bound as a pattern —
+     * it is only the unmatched sink.
+     */
+    unmatchedQueue?: string;
+};
+/**
+ * Single system config: **stores** (adapters) + **queues** (+ optional router).
+ *
+ * Prefer a JS/TS module so workers and custom store `impl`s can be imported.
+ * A JSON subset (built-in adapters only, no workers) works via
+ * {@link parseSystemConfig} / {@link buildFromJson}.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@qkitt/queue'
+ * import { handleMail } from './workers/mail'
+ * import { createRedisRowStore } from './stores/redis'
+ *
+ * export default defineConfig({
+ *   stores: {
+ *     mailDb: { adapter: 'localStorage', strategy: 'row', key: 'mail' },
+ *     redis: { strategy: 'row', impl: createRedisRowStore() },
+ *   },
+ *   queues: {
+ *     mail: {
+ *       persist: { store: 'mailDb' },
+ *       worker: { run: handleMail, concurrency: 2 },
+ *     },
+ *   },
+ *   router: {
+ *     bindings: [{ pattern: 'mail.#', queue: 'mail' }],
+ *     unmatchedQueue: 'unrouted',
+ *   },
+ * })
+ * ```
+ */
+export type SystemConfig = {
+    /**
+     * Named store adapters. Queues reference them with `persist.store`.
+     * Omit (or `{}`) when no queue uses persistence.
+     */
+    stores?: Record<string, StoreDefinition>;
+    queues: Record<string, QueueConfig>;
+    /**
+     * When present, a router is created and bindings applied.
+     * Use `{}` or `{ bindings: [] }` for an empty router.
+     * Optional `unmatchedQueue` parks unrouted publishes.
+     */
+    router?: RouterConfig;
+    /**
+     * Hydrate all persisted queues after construction (and after workers
+     * are attached, so restored items can be processed when autoStart is on).
+     * Defaults to `true` when any queue has `persist`.
+     */
+    hydrate?: boolean;
+};
+/** Build-time options that cannot live in config data. */
+export type BuildFromConfigOptions = {
+    /**
+     * Inject Web Storage (tests, Node, custom backends).
+     * Used when a store's `adapter` is `localStorage` or `sessionStorage`.
+     */
+    storage?: WebStorageLike;
+};
+/** Resolved store instance after build (custom or built-in). */
+export type ResolvedStore<T = unknown> = SnapshotStore<T> | RowStore<T>;
+/**
+ * Queue surface returned by the config builder.
+ * Persist / worker helpers are present only when configured.
+ */
+export type ConfiguredQueue<T = unknown> = Queue<T> & Partial<WorkerControls> & {
+    hydrate?: () => Promise<void>;
+    persist?: () => Promise<void>;
+    flush?: () => Promise<void>;
+    rowIds?: () => string[];
+};
+export type ConfiguredSystem<TConfig extends SystemConfig = SystemConfig, T = unknown> = {
+    queues: {
+        [K in keyof TConfig['queues']]: ConfiguredQueue<T>;
+    };
+    /**
+     * Resolved store instances keyed by `config.stores` names.
+     * Empty object when no stores were defined.
+     */
+    stores: {
+        [K in keyof NonNullable<TConfig['stores']>]: ResolvedStore<T>;
+    } & Record<string, ResolvedStore<T>>;
+    /**
+     * Present when `router` was set in config.
+     * Always defined for that case; `undefined` when no router was requested.
+     */
+    router: TConfig extends {
+        router: RouterConfig;
+    } ? Router : Router | undefined;
+    /** Hydrate every queue that exposes `hydrate`. */
+    hydrateAll: () => Promise<void>;
+    /** Flush every queue that exposes `flush`. */
+    flushAll: () => Promise<void>;
+    /**
+     * The config used to build this system (shallow-frozen).
+     * Function references (workers, store impls) are preserved.
+     */
+    config: Readonly<TConfig>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/config/validate.d.ts

@@ -0,0 +1,36 @@
+import type { SystemConfig } from './types';
+/**
+ * Validate an unknown value as **data-only** config (JSON-safe).
+ * Rejects `worker` and custom store `impl` (JS-only fields).
+ */
+export declare const validateSystemConfig: (value: unknown) => SystemConfig;
+/**
+ * Validate a JS/TS module config, preserving workers and custom store impls.
+ * Prefer {@link defineConfig} at the export site for typed inference.
+ */
+export declare const validateJsConfig: <TConfig extends SystemConfig>(value: TConfig) => TConfig;
+/**
+ * Identity helper for typed JS config modules.
+ * Validates structure and preserves function / store instance references.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   stores: {
+ *     jobs: { adapter: 'memory', strategy: 'row' },
+ *   },
+ *   queues: {
+ *     jobs: {
+ *       persist: { store: 'jobs' },
+ *       worker: handleJob,
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export declare const defineConfig: <const TConfig extends SystemConfig>(config: TConfig) => TConfig;
+/**
+ * Parse a JSON string into a validated **data-only** {@link SystemConfig}.
+ */
+export declare const parseSystemConfig: (json: string) => SystemConfig;
+//# sourceMappingURL=validate.d.ts.map

package/dist/events/index.d.ts

@@ -0,0 +1,48 @@
+/** Base constraint for typed event maps. Avoids a string index signature so intersections stay precise. */
+export type EventMap = Record<never, never>;
+/**
+ * Merge event maps. Extra keys overwrite base keys (no `A[K] & B[K]` intersection).
+ * Needed so generic expand/withWorker emit payloads stay assignable.
+ */
+export type MergeEventMaps<TBase extends EventMap, TExtra extends EventMap> = Omit<TBase, keyof TExtra> & TExtra;
+export type EventCallback<T> = (data: T) => void;
+/**
+ * Typed emit bridge over a loosely typed `emit`.
+ * Avoids `TBase[K] & TExtra[K]` from generic map merges making concrete
+ * payloads unassignable under a free `TEvents`.
+ */
+export declare const createTypedEmit: <TEvents extends EventMap>(emit: (eventName: string, data: unknown) => void) => <K extends keyof TEvents>(eventName: K, data: TEvents[K]) => void;
+export type EventEmitter<TEvents extends EventMap = EventMap> = {
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on: <K extends keyof TEvents>(eventName: K, callback: EventCallback<TEvents[K]>) => () => void;
+    /** Subscribe for a single emission, then auto-unsubscribe. Returns an unsubscribe function. */
+    once: <K extends keyof TEvents>(eventName: K, callback: EventCallback<TEvents[K]>) => () => void;
+    /** Remove a specific listener, or all listeners for the event if no callback is given. */
+    off: <K extends keyof TEvents>(eventName: K, callback?: EventCallback<TEvents[K]>) => void;
+    /**
+     * Emit an event to all current listeners (snapshot taken before dispatch).
+     * Listener errors are isolated: one throw does not skip remaining listeners.
+     * Failures are swallowed at emit time — listeners should handle their own errors
+     * (critical paths like worker pump must not die because of a user handler).
+     */
+    emit: <K extends keyof TEvents>(eventName: K, data: TEvents[K]) => void;
+    /** Remove all listeners for all events. */
+    clear: () => void;
+    /** Number of listeners registered for an event. */
+    listenerCount: <K extends keyof TEvents>(eventName: K) => number;
+    /** Event names that currently have at least one listener. */
+    eventNames: () => (keyof TEvents)[];
+    /**
+     * Widen the event map with additional event types.
+     * Returns the same instance (listeners preserved), typed as the merged map.
+     * Extra keys overwrite base keys (see {@link MergeEventMaps}).
+     *
+     * @example
+     * const base = buildEventEmitter<{ job: { id: string } }>()
+     * const events = base.expand<{ drained: undefined; error: Error }>()
+     * events.on('drained', () => {})
+     */
+    expand: <TExtra extends EventMap>() => EventEmitter<MergeEventMaps<TEvents, TExtra>>;
+};
+export declare const buildEventEmitter: <TEvents extends EventMap = EventMap>() => EventEmitter<TEvents>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { buildFromConfig, buildFromJson, defineConfig, parseSystemConfig, validateJsConfig, validateSystemConfig, type BindingConfig, type BuildFromConfigOptions, type BuiltinStoreAdapter, type ConfiguredQueue, type ConfiguredSystem, type PersistConfig, type QueueConfig, type ResolvedStore, type RouterConfig, type StoreDefinition, type StoreKind, type SystemConfig, type WorkerConfig, } from './config';
+export { buildEventEmitter, createTypedEmit, type EventCallback, type EventEmitter, type EventMap, type MergeEventMaps, } from './events';
+export { createLocalStorageRowStore, createLocalStorageSnapshotStore, createMemoryRowStore, createMemorySnapshotStore, createSessionStorageRowStore, createSessionStorageSnapshotStore, createWebRowStore, createWebSnapshotStore, StorageCodecError, type JsonCodec, type MemoryRowStore, type MemorySnapshotStore, type WebRowStoreOptions, type WebSnapshotStoreOptions, type WebStorageLike, } from './persist';
+export { buildQueue, createId, QueueFullError, withRowPersist, withSnapshotPersist, withWorker, type BuildQueueOptions, type Queue, type QueueEvents, type QueueWithRowPersist, type QueueWithSnapshotPersist, type QueueWithWorker, type RowPersistEvents, type RowPersistOptions, type RowRecord, type RowStore, type SnapshotPersistEvents, type SnapshotPersistOptions, type SnapshotStore, type WithWorkerOptions, type WorkerControls, type WorkerEvents, } from './queue';
+export { buildRouter, isValidPattern, isValidTopic, matchTopic, MULTI_WILDCARD, SINGLE_WILDCARD, TOPIC_SEPARATOR, type Binding, type BuildRouterOptions, type RouteMessage, type RouteTarget, type Router, type RouterEvents, type UnmatchedRecord, } from './router';
+export { pipeline, RetryExhaustedError, withRetry, type RetryOptions, type StepFn, type WorkerFn, } from './worker';
+//# sourceMappingURL=index.d.ts.map