@qkitt/queue 0.1.0 → 0.1.1

package/README.md

@@ -23,7 +23,9 @@ npm install @qkitt/queue
 
 **Requirements:** Node.js **18+** (see `engines`). **ESM only** — `"type": "module"`, no CommonJS/`require` build.
 
-Zero runtime dependencies (TypeScript + Vitest + tsup are dev-only). Published entry is compiled ESM + declarations under `dist/` (`import` / `types`). Tree-shaking friendly (`sideEffects: false`).
+Zero runtime dependencies (TypeScript + Vitest + tsup are dev-only). Published entries are compiled ESM + declarations under `dist/` (`import` / `types`). Tree-shaking friendly (`sideEffects: false`).
+
+Root import (everything):
 
 ```ts
 import {
@@ -44,6 +46,17 @@ import {
 } from '@qkitt/queue'
 ```
 
+Area subpaths (same symbols as the root barrel for that area):
+
+```ts
+import { buildQueue, withWorker } from '@qkitt/queue/queue'
+import { pipeline, withRetry } from '@qkitt/queue/worker'
+import { buildRouter } from '@qkitt/queue/router'
+import { createMemoryRowStore } from '@qkitt/queue/persist'
+import { defineConfig, buildFromConfig } from '@qkitt/queue/config'
+import { buildEventEmitter } from '@qkitt/queue/events'
+```
+
 ## Quick start
 
 ```ts
@@ -648,24 +661,24 @@ queue.on('worker:idle', () => console.log('inbox empty'))
 | Events | Typed emitter; listener errors are isolated so pumps keep running |
 | Routing | MQTT/AMQP-style patterns; unmatched sink does not count as a match |
 | Config | Named stores + named queues; workers/`impl` are JS-only; JSON is data-only |
-| Packaging | Zero runtime deps; ESM-only npm package; `npm run build` emits ESM + `.d.ts` to `dist/` |
+| Packaging | Zero runtime deps; ESM-only; root + area subpaths; `npm run build` emits ESM + `.d.ts` to `dist/` |
 
 ## Source layout
 
-Consumers always import `@qkitt/queue` (root only). The tree under `src/` mirrors composition layers:
+Consumers import `@qkitt/queue` (root) or an area subpath (`@qkitt/queue/router`, …). The tree under `src/` mirrors composition layers:
 
-| Folder | Meaning |
-| --- | --- |
-| `queue/core` | FIFO queue (`buildQueue`) |
-| `queue/worker` | Attach a processor (`withWorker`) |
-| `queue/persist` | Durable queue decorators + store contracts |
-| `persist` | Storage backends (memory, Web Storage) |
-| `worker` | Processor helpers (`pipeline`, `withRetry`) — not queue decoration |
-| `router` | Topic routing |
-| `config` | Declarative system build |
-| `events` | Typed emitter |
+| Folder | npm subpath | Meaning |
+| --- | --- | --- |
+| `queue/core` | `@qkitt/queue/queue` | FIFO queue (`buildQueue`) |
+| `queue/worker` | `@qkitt/queue/queue` | Attach a processor (`withWorker`) |
+| `queue/persist` | `@qkitt/queue/queue` | Durable queue decorators + store contracts |
+| `persist` | `@qkitt/queue/persist` | Storage backends (memory, Web Storage) |
+| `worker` | `@qkitt/queue/worker` | Processor helpers (`pipeline`, `withRetry`) — not queue decoration |
+| `router` | `@qkitt/queue/router` | Topic routing |
+| `config` | `@qkitt/queue/config` | Declarative system build |
+| `events` | `@qkitt/queue/events` | Typed emitter |
 
-**Name disambiguation:** `src/worker` = functions that process items; `src/queue/worker` = the decorator that runs them on a queue. `src/persist` = store adapters; `src/queue/persist` = queue decorators that use those stores.
+**Name disambiguation:** `src/worker` / `@qkitt/queue/worker` = functions that process items; `src/queue/worker` / `@qkitt/queue/queue` = the decorator that runs them on a queue. `src/persist` / `@qkitt/queue/persist` = store adapters; `src/queue/persist` lives under `@qkitt/queue/queue`.
 
 ## Naming convention
 
@@ -690,19 +703,18 @@ Rules:
 
 ## API map
 
-Public surface (via `@qkitt/queue` / `src/index.ts`):
+Public surface via `@qkitt/queue` (`src/index.ts`) and matching area subpaths:
 
-| Area | Exports |
-| --- | --- |
-| Queue | `buildQueue`, `QueueFullError`, `Queue`, `QueueEvents`, `BuildQueueOptions` |
-| Worker | `withWorker`, `QueueWithWorker`, `WorkerEvents`, `WithWorkerOptions` |
-| Snapshot persist | `withSnapshotPersist`, `SnapshotStore`, `SnapshotPersistOptions` |
-| Row persist | `withRowPersist`, `RowStore`, `RowRecord`, `createId`, `RowPersistOptions` |
-| Worker helpers | `pipeline`, `withRetry`, `RetryExhaustedError`, `WorkerFn`, `StepFn` |
-| Router | `buildRouter`, `RouteMessage`, `matchTopic`, `isValidTopic`, `isValidPattern`, … |
-| Persist stores | memory + Web Storage factories, `StorageCodecError`, `WebStorageLike` |
-| Config | `defineConfig`, `buildFromConfig`, `buildFromJson`, `parseSystemConfig`, `validate*`, `SystemConfig`, … |
-| Events | `buildEventEmitter`, `createTypedEmit`, `EventEmitter`, `MergeEventMaps` |
+| Area | Subpath | Exports |
+| --- | --- | --- |
+| Queue + queue worker + queue persist | `@qkitt/queue/queue` | `buildQueue`, `QueueFullError`, `withWorker`, `withRowPersist`, `withSnapshotPersist`, `createId`, types… |
+| Worker helpers | `@qkitt/queue/worker` | `pipeline`, `withRetry`, `RetryExhaustedError`, `WorkerFn`, `StepFn` |
+| Router | `@qkitt/queue/router` | `buildRouter`, `RouteMessage`, `matchTopic`, `isValidTopic`, `isValidPattern`, … |
+| Persist stores | `@qkitt/queue/persist` | memory + Web Storage factories, `StorageCodecError`, `WebStorageLike` |
+| Config | `@qkitt/queue/config` | `defineConfig`, `buildFromConfig`, `buildFromJson`, `parseSystemConfig`, `validate*`, `SystemConfig`, … |
+| Events | `@qkitt/queue/events` | `buildEventEmitter`, `createTypedEmit`, `EventEmitter`, `MergeEventMaps` |
+
+Root `@qkitt/queue` re-exports all of the above.
 
 Internals (`forward.util`, `hydrate-gate.util`, `write-chain.util`, `row-ids.util`, codecs) are not part of the stable public contract.
 

package/dist/chunk-4BUYKZS2.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-4BUYKZS2.js.map
+//# sourceMappingURL=chunk-4BUYKZS2.js.map

package/dist/chunk-653YYS22.js

@@ -0,0 +1,525 @@
+import { buildEventEmitter, createTypedEmit } from './chunk-TX6HHN5M.js';
+
+// src/queue/core/queue.ts
+var QueueFullError = class extends Error {
+  name = "QueueFullError";
+  maxSize;
+  constructor(maxSize) {
+    super(`Queue is full (maxSize=${maxSize})`);
+    this.maxSize = maxSize;
+  }
+};
+var COMPACT_HEAD_THRESHOLD = 64;
+var buildQueue = (options = {}) => {
+  const maxSize = options.maxSize;
+  if (maxSize !== void 0 && (!Number.isFinite(maxSize) || maxSize < 1)) {
+    throw new Error("maxSize must be a finite number >= 1");
+  }
+  const items = [];
+  let head = 0;
+  const emitter = buildEventEmitter();
+  const liveSize = () => items.length - head;
+  const compactIfNeeded = () => {
+    if (head === 0) return;
+    if (head < COMPACT_HEAD_THRESHOLD && head * 2 < items.length) return;
+    items.splice(0, head);
+    head = 0;
+  };
+  const assertCapacity = (nextSize) => {
+    if (maxSize !== void 0 && nextSize > maxSize) {
+      throw new QueueFullError(maxSize);
+    }
+  };
+  const enqueue = (item) => {
+    assertCapacity(liveSize() + 1);
+    items.push(item);
+    emitter.emit("queue:enqueued", { item, size: liveSize() });
+  };
+  const dequeue = () => {
+    if (head >= items.length) return void 0;
+    const item = items[head];
+    head += 1;
+    compactIfNeeded();
+    const size2 = liveSize();
+    emitter.emit("queue:dequeued", { item, size: size2 });
+    if (size2 === 0) {
+      emitter.emit("queue:emptied", void 0);
+    }
+    return item;
+  };
+  const peek = () => {
+    if (head >= items.length) return void 0;
+    return items[head];
+  };
+  const size = () => liveSize();
+  const isEmpty = () => head >= items.length;
+  const clear = () => {
+    const removed = liveSize();
+    if (removed === 0) return;
+    items.length = 0;
+    head = 0;
+    emitter.emit("queue:cleared", { removed });
+  };
+  const replaceAll = (next) => {
+    assertCapacity(next.length);
+    items.length = 0;
+    head = 0;
+    for (const item of next) {
+      items.push(item);
+    }
+  };
+  const toArray = () => items.slice(head);
+  const api = {
+    enqueue,
+    dequeue,
+    peek,
+    size,
+    isEmpty,
+    clear,
+    replaceAll,
+    toArray,
+    on: emitter.on,
+    once: emitter.once,
+    off: emitter.off,
+    emit: emitter.emit,
+    expand: () => api
+  };
+  return api;
+};
+
+// src/queue/persist/create-id.util.ts
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+var DEFAULT_SIZE = 21;
+var fillRandom = (bytes) => {
+  const cryptoObj = globalThis.crypto;
+  if (typeof cryptoObj?.getRandomValues === "function") {
+    cryptoObj.getRandomValues(bytes);
+    return;
+  }
+  for (let i = 0; i < bytes.length; i += 1) {
+    bytes[i] = Math.floor(Math.random() * 256);
+  }
+};
+var createId = (size = DEFAULT_SIZE) => {
+  if (!Number.isInteger(size) || size <= 0) {
+    throw new RangeError(`createId size must be a positive integer, got ${size}`);
+  }
+  const bytes = new Uint8Array(size);
+  fillRandom(bytes);
+  let id = "";
+  for (let i = 0; i < size; i += 1) {
+    id += ALPHABET[bytes[i] & 63];
+  }
+  return id;
+};
+
+// src/queue/core/layers.util.ts
+var WORKER_LAYER = /* @__PURE__ */ Symbol.for("qkitt:worker-layer");
+var PERSIST_LAYER = /* @__PURE__ */ Symbol.for("qkitt:persist-layer");
+var markQueueLayer = (queue, layer) => {
+  if (hasQueueLayer(queue, layer)) return queue;
+  Object.defineProperty(queue, layer, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+  return queue;
+};
+var hasQueueLayer = (queue, layer) => queue[layer] === true;
+var copyQueueLayers = (from, to) => {
+  if (hasQueueLayer(from, WORKER_LAYER)) {
+    markQueueLayer(to, WORKER_LAYER);
+  }
+  if (hasQueueLayer(from, PERSIST_LAYER)) {
+    markQueueLayer(to, PERSIST_LAYER);
+  }
+  return to;
+};
+
+// src/queue/core/forward.util.ts
+var forwardQueue = (queue, extra) => {
+  const next = {
+    ...queue,
+    ...extra
+  };
+  return copyQueueLayers(queue, next);
+};
+
+// src/queue/persist/hydrate-gate.util.ts
+var createHydrateGate = () => {
+  let suppressing = false;
+  return {
+    isSuppressing: () => suppressing,
+    run: async (fn) => {
+      suppressing = true;
+      try {
+        return await fn();
+      } finally {
+        suppressing = false;
+      }
+    }
+  };
+};
+var assertNotHydrating = (gate) => {
+  if (gate.isSuppressing()) {
+    throw new Error(
+      "Cannot mutate queue while hydrate() is in progress; await hydrate() first"
+    );
+  }
+};
+
+// src/queue/persist/persist.support.ts
+var assertBareQueueForPersist = (queue, wrapperName) => {
+  if (hasQueueLayer(queue, WORKER_LAYER)) {
+    throw new Error(
+      `${wrapperName} must wrap the bare queue before withWorker: withWorker(${wrapperName}(queue, store), worker)`
+    );
+  }
+  if (hasQueueLayer(queue, PERSIST_LAYER)) {
+    throw new Error(
+      `${wrapperName} cannot wrap an already-persisted queue; use a single persist layer on the bare queue`
+    );
+  }
+};
+var notifyQueueRestored = (queue) => {
+  const size = queue.size();
+  if (size === 0) return;
+  const item = queue.peek();
+  if (item === void 0) return;
+  queue.emit("queue:enqueued", { item, size });
+};
+
+// src/queue/persist/row-ids.util.ts
+var COMPACT_HEAD_THRESHOLD2 = 64;
+var createRowIdList = () => {
+  const ids = [];
+  let idHead = 0;
+  const compactIfNeeded = () => {
+    if (idHead === 0) return;
+    if (idHead < COMPACT_HEAD_THRESHOLD2 && idHead * 2 < ids.length) return;
+    ids.splice(0, idHead);
+    idHead = 0;
+  };
+  return {
+    push: (id) => {
+      ids.push(id);
+    },
+    shift: () => {
+      if (idHead >= ids.length) return void 0;
+      const id = ids[idHead];
+      idHead += 1;
+      compactIfNeeded();
+      return id;
+    },
+    reset: (next) => {
+      ids.length = 0;
+      idHead = 0;
+      for (const id of next) {
+        ids.push(id);
+      }
+    },
+    live: () => ids.slice(idHead),
+    liveCount: () => ids.length - idHead
+  };
+};
+
+// src/queue/persist/write-chain.util.ts
+var createWriteChain = () => {
+  let chain = Promise.resolve();
+  const push = (op) => {
+    const run = chain.then(op, op);
+    chain = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  };
+  const flush = () => chain;
+  return { push, flush };
+};
+
+// src/queue/persist/with-row-persist.ts
+var withRowPersist = (queue, store, options = {}) => {
+  assertBareQueueForPersist(queue, "withRowPersist");
+  const nextId = options.createId ?? createId;
+  const inner = queue.expand();
+  const emitPersist = createTypedEmit(
+    inner.emit
+  );
+  const gate = createHydrateGate();
+  const writes = createWriteChain();
+  const rowIdsList = createRowIdList();
+  let localSuppress = false;
+  const isSuppressing = () => gate.isSuppressing() || localSuppress;
+  const trackError = (operation, error, id) => {
+    emitPersist("persist:error", { operation, error, id });
+  };
+  const rollbackLocalById = (id) => {
+    const liveIds = rowIdsList.live();
+    const liveIndex = liveIds.indexOf(id);
+    if (liveIndex < 0) return;
+    const remainingItems = inner.toArray();
+    remainingItems.splice(liveIndex, 1);
+    liveIds.splice(liveIndex, 1);
+    localSuppress = true;
+    try {
+      rowIdsList.reset(liveIds);
+      inner.replaceAll(remainingItems);
+    } finally {
+      localSuppress = false;
+    }
+  };
+  const scheduleStore = (op) => {
+    if (isSuppressing()) return;
+    void writes.push(op).catch(() => {
+    });
+  };
+  const enqueue = (item) => {
+    assertNotHydrating(gate);
+    const id = nextId();
+    rowIdsList.push(id);
+    if (!isSuppressing()) {
+      scheduleStore(async () => {
+        try {
+          await store.insert({ id, item });
+          emitPersist("persist:inserted", { id, item });
+        } catch (error) {
+          rollbackLocalById(id);
+          trackError("insert", error, id);
+        }
+      });
+    }
+    inner.enqueue(item);
+  };
+  const dequeue = () => {
+    assertNotHydrating(gate);
+    const item = inner.dequeue();
+    if (item === void 0) return void 0;
+    const id = rowIdsList.shift();
+    if (id === void 0) return item;
+    if (isSuppressing()) return item;
+    scheduleStore(async () => {
+      try {
+        await store.remove(id);
+        emitPersist("persist:removed", { id, item });
+      } catch (error) {
+        trackError("remove", error, id);
+      }
+    });
+    return item;
+  };
+  const clear = () => {
+    assertNotHydrating(gate);
+    const removed = rowIdsList.liveCount();
+    if (removed === 0 && inner.isEmpty()) return;
+    rowIdsList.reset([]);
+    inner.clear();
+    if (isSuppressing()) return;
+    scheduleStore(async () => {
+      try {
+        await store.clear();
+        emitPersist("persist:cleared", { removed });
+      } catch (error) {
+        trackError("clear", error);
+      }
+    });
+  };
+  const replaceAll = (_items) => {
+    throw new Error(
+      "replaceAll is not supported on row-persisted queues; use hydrate() to restore from the store, or enqueue/dequeue/clear"
+    );
+  };
+  const hydrate = async () => {
+    await gate.run(async () => {
+      try {
+        await writes.flush();
+        const rows = await store.loadAll();
+        rowIdsList.reset(rows.map((row) => row.id));
+        inner.replaceAll(rows.map((row) => row.item));
+        emitPersist("persist:loaded", { size: inner.size() });
+      } catch (error) {
+        trackError("load", error);
+        throw error;
+      }
+    });
+    notifyQueueRestored({
+      size: inner.size,
+      peek: inner.peek,
+      emit: inner.emit
+    });
+  };
+  const api = markQueueLayer(
+    forwardQueue(inner, {
+      enqueue,
+      dequeue,
+      clear,
+      replaceAll,
+      expand: () => api,
+      hydrate,
+      rowIds: () => rowIdsList.live(),
+      flush: writes.flush
+    }),
+    PERSIST_LAYER
+  );
+  return api;
+};
+
+// src/queue/persist/with-snapshot-persist.ts
+var withSnapshotPersist = (queue, store, options = {}) => {
+  assertBareQueueForPersist(queue, "withSnapshotPersist");
+  const autoSave = options.autoSave ?? true;
+  const inner = queue.expand();
+  const emitPersist = createTypedEmit(
+    inner.emit
+  );
+  const gate = createHydrateGate();
+  const writes = createWriteChain();
+  const persist = () => writes.push(async () => {
+    try {
+      const items = inner.toArray();
+      await store.save(items);
+      emitPersist("persist:saved", { size: items.length });
+    } catch (error) {
+      emitPersist("persist:error", { operation: "save", error });
+      throw error;
+    }
+  });
+  const scheduleSave = () => {
+    if (gate.isSuppressing() || !autoSave) return;
+    void persist().catch(() => {
+    });
+  };
+  const enqueue = (item) => {
+    assertNotHydrating(gate);
+    inner.enqueue(item);
+    scheduleSave();
+  };
+  const dequeue = () => {
+    assertNotHydrating(gate);
+    const item = inner.dequeue();
+    if (item !== void 0) {
+      scheduleSave();
+    }
+    return item;
+  };
+  const clear = () => {
+    assertNotHydrating(gate);
+    if (inner.isEmpty()) return;
+    inner.clear();
+    scheduleSave();
+  };
+  const replaceAll = (items) => {
+    assertNotHydrating(gate);
+    inner.replaceAll(items);
+    scheduleSave();
+  };
+  const hydrate = async () => {
+    await gate.run(async () => {
+      try {
+        await writes.flush();
+        const items = await store.load();
+        inner.replaceAll(items);
+        emitPersist("persist:loaded", { size: inner.size() });
+      } catch (error) {
+        emitPersist("persist:error", { operation: "load", error });
+        throw error;
+      }
+    });
+    notifyQueueRestored({
+      size: inner.size,
+      peek: inner.peek,
+      emit: inner.emit
+    });
+  };
+  const api = markQueueLayer(
+    forwardQueue(inner, {
+      enqueue,
+      dequeue,
+      clear,
+      replaceAll,
+      expand: () => api,
+      hydrate,
+      persist,
+      flush: writes.flush
+    }),
+    PERSIST_LAYER
+  );
+  return api;
+};
+
+// src/queue/worker/with-worker.ts
+var resolveConcurrency = (value) => {
+  const concurrency = value ?? 1;
+  if (!Number.isFinite(concurrency) || concurrency < 1) {
+    throw new Error("concurrency must be a finite number >= 1");
+  }
+  return Math.floor(concurrency);
+};
+var withWorker = (queue, worker, options = {}) => {
+  const concurrency = resolveConcurrency(options.concurrency);
+  const autoStart = options.autoStart ?? true;
+  const inner = queue.expand();
+  const emitWorker = createTypedEmit(
+    inner.emit
+  );
+  const onQueue = inner.on;
+  let running = false;
+  let active = 0;
+  const processItem = async (item) => {
+    emitWorker("worker:started", { item });
+    try {
+      const result = await worker(item);
+      emitWorker("worker:completed", { item, result });
+    } catch (error) {
+      emitWorker("worker:failed", { item, error });
+    } finally {
+      active -= 1;
+      if (active === 0 && inner.isEmpty()) {
+        emitWorker("worker:idle", void 0);
+      }
+      pump();
+    }
+  };
+  const pump = () => {
+    try {
+      while (running && active < concurrency) {
+        const item = inner.dequeue();
+        if (item === void 0) break;
+        active += 1;
+        void processItem(item);
+      }
+    } catch {
+    }
+  };
+  const start = () => {
+    if (running) return;
+    running = true;
+    pump();
+  };
+  const stop = () => {
+    running = false;
+  };
+  onQueue("queue:enqueued", () => {
+    pump();
+  });
+  if (autoStart) {
+    start();
+  }
+  const api = markQueueLayer(
+    forwardQueue(inner, {
+      expand: () => api,
+      start,
+      stop,
+      isRunning: () => running,
+      isProcessing: () => active > 0,
+      activeCount: () => active
+    }),
+    WORKER_LAYER
+  );
+  return api;
+};
+
+export { QueueFullError, buildQueue, createId, withRowPersist, withSnapshotPersist, withWorker };
+//# sourceMappingURL=chunk-653YYS22.js.map
+//# sourceMappingURL=chunk-653YYS22.js.map