@qkitt/queue 0.1.0

package/dist/index.js

@@ -0,0 +1,1552 @@
+// src/events/index.ts
+var createTypedEmit = (emit) => {
+  return (eventName, data) => {
+    emit(eventName, data);
+  };
+};
+var buildEventEmitter = () => {
+  const listenersByEvent = /* @__PURE__ */ new Map();
+  const on = (eventName, callback) => {
+    const listeners = listenersByEvent.get(eventName);
+    if (listeners) {
+      listeners.push(callback);
+    } else {
+      listenersByEvent.set(eventName, [
+        callback
+      ]);
+    }
+    return () => off(eventName, callback);
+  };
+  const once = (eventName, callback) => {
+    const wrapper = (data) => {
+      off(eventName, wrapper);
+      callback(data);
+    };
+    return on(eventName, wrapper);
+  };
+  const off = (eventName, callback) => {
+    const listeners = listenersByEvent.get(eventName);
+    if (!listeners) return;
+    if (!callback) {
+      listenersByEvent.delete(eventName);
+      return;
+    }
+    const next = listeners.filter((cb) => cb !== callback);
+    if (next.length === 0) {
+      listenersByEvent.delete(eventName);
+    } else {
+      listenersByEvent.set(eventName, next);
+    }
+  };
+  const emit = (eventName, data) => {
+    const listeners = listenersByEvent.get(eventName);
+    if (!listeners?.length) return;
+    for (const callback of [...listeners]) {
+      try {
+        callback(data);
+      } catch {
+      }
+    }
+  };
+  const clear = () => {
+    listenersByEvent.clear();
+  };
+  const listenerCount = (eventName) => {
+    return listenersByEvent.get(eventName)?.length ?? 0;
+  };
+  const eventNames = () => {
+    return [...listenersByEvent.keys()];
+  };
+  const api = {
+    on,
+    once,
+    off,
+    emit,
+    clear,
+    listenerCount,
+    eventNames,
+    expand: () => api
+  };
+  return api;
+};
+
+// 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/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/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/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;
+};
+
+// src/router/match.util.ts
+var TOPIC_SEPARATOR = ".";
+var SINGLE_WILDCARD = "*";
+var MULTI_WILDCARD = "#";
+var isEmptySegment = (segment) => segment.length === 0;
+var isValidTopic = (topic) => {
+  if (topic.length === 0) return false;
+  if (topic.includes(SINGLE_WILDCARD) || topic.includes(MULTI_WILDCARD)) {
+    return false;
+  }
+  const segments = topic.split(TOPIC_SEPARATOR);
+  return segments.length > 0 && !segments.some(isEmptySegment);
+};
+var isValidPattern = (pattern) => {
+  if (pattern.length === 0) return false;
+  const segments = pattern.split(TOPIC_SEPARATOR);
+  if (segments.some(isEmptySegment)) return false;
+  for (let i = 0; i < segments.length; i += 1) {
+    const segment = segments[i];
+    if (segment === MULTI_WILDCARD) {
+      return i === segments.length - 1;
+    }
+  }
+  return true;
+};
+var matchTopic = (pattern, topic) => {
+  if (!isValidPattern(pattern) || !isValidTopic(topic)) return false;
+  const patternParts = pattern.split(TOPIC_SEPARATOR);
+  const topicParts = topic.split(TOPIC_SEPARATOR);
+  let pi = 0;
+  let ti = 0;
+  while (pi < patternParts.length && ti < topicParts.length) {
+    const token = patternParts[pi];
+    if (token === MULTI_WILDCARD) {
+      return true;
+    }
+    if (token === SINGLE_WILDCARD || token === topicParts[ti]) {
+      pi += 1;
+      ti += 1;
+      continue;
+    }
+    return false;
+  }
+  if (pi === patternParts.length - 1 && patternParts[pi] === MULTI_WILDCARD) {
+    return true;
+  }
+  return pi === patternParts.length && ti === topicParts.length;
+};
+
+// src/router/router.ts
+var buildRouter = (options = {}) => {
+  const events = buildEventEmitter();
+  const emitRouter = createTypedEmit(
+    events.emit
+  );
+  const routes = [];
+  let unmatchedTarget = options.unmatchedTarget;
+  let unmatchedTotal = 0;
+  let lastUnmatchedRecord;
+  const bind = (pattern, target) => {
+    if (!isValidPattern(pattern)) {
+      const error = new Error(`Invalid route pattern: ${pattern}`);
+      emitRouter("router:error", { operation: "bind", error, pattern });
+      throw error;
+    }
+    const binding = {
+      pattern,
+      target
+    };
+    routes.push(binding);
+    emitRouter("router:bound", { pattern });
+    return () => {
+      unbind(pattern, target);
+    };
+  };
+  const unbind = (pattern, target) => {
+    let removed = 0;
+    for (let i = routes.length - 1; i >= 0; i -= 1) {
+      const route = routes[i];
+      if (route.pattern !== pattern) continue;
+      if (target !== void 0 && route.target !== target) continue;
+      routes.splice(i, 1);
+      removed += 1;
+    }
+    if (removed > 0) {
+      emitRouter("router:unbound", { pattern, removed });
+    }
+  };
+  const deliverUnmatched = (topic, data) => {
+    if (unmatchedTarget === void 0) {
+      return false;
+    }
+    try {
+      unmatchedTarget.enqueue({ topic, data });
+      return true;
+    } catch (error) {
+      emitRouter("router:error", {
+        operation: "unmatched",
+        error,
+        topic
+      });
+      return false;
+    }
+  };
+  const publish = (topic, data) => {
+    if (!isValidTopic(topic)) {
+      const error = new Error(`Invalid publish topic: ${topic}`);
+      emitRouter("router:error", { operation: "publish", error, topic });
+      throw error;
+    }
+    const message = { topic, data };
+    let matched = 0;
+    for (const route of [...routes]) {
+      if (!matchTopic(route.pattern, topic)) continue;
+      try {
+        route.target.enqueue(message);
+        matched += 1;
+      } catch (error) {
+        emitRouter("router:error", {
+          operation: "publish",
+          error,
+          topic,
+          pattern: route.pattern
+        });
+      }
+    }
+    if (matched === 0) {
+      unmatchedTotal += 1;
+      lastUnmatchedRecord = { topic, data };
+      const delivered = deliverUnmatched(topic, data);
+      emitRouter("router:unmatched", { topic, data, delivered });
+    } else {
+      emitRouter("router:published", { topic, data, matched });
+    }
+    return matched;
+  };
+  const bindings = () => routes.map((route) => ({
+    pattern: route.pattern,
+    target: route.target
+  }));
+  const clear = () => {
+    routes.length = 0;
+  };
+  const setUnmatchedTarget = (target) => {
+    unmatchedTarget = target;
+  };
+  const getUnmatchedTarget = () => unmatchedTarget;
+  const unmatchedCount = () => unmatchedTotal;
+  const lastUnmatched = () => lastUnmatchedRecord;
+  const clearUnmatched = () => {
+    unmatchedTotal = 0;
+    lastUnmatchedRecord = void 0;
+  };
+  const api = {
+    bind,
+    unbind,
+    publish,
+    bindings,
+    clear,
+    setUnmatchedTarget,
+    getUnmatchedTarget,
+    unmatchedCount,
+    lastUnmatched,
+    clearUnmatched,
+    on: events.on,
+    once: events.once,
+    off: events.off,
+    emit: events.emit,
+    expand: () => api
+  };
+  return api;
+};
+
+// src/config/config-freeze.util.ts
+var freezeConfig = (config) => {
+  const queues = {};
+  for (const [name, queue] of Object.entries(config.queues)) {
+    queues[name] = Object.freeze({ ...queue });
+  }
+  const stores = {};
+  if (config.stores) {
+    for (const [name, store] of Object.entries(config.stores)) {
+      stores[name] = Object.freeze({ ...store });
+    }
+  }
+  const frozen = {
+    ...config,
+    ...Object.keys(stores).length > 0 ? { stores: Object.freeze(stores) } : {},
+    queues: Object.freeze(queues),
+    ...config.router ? {
+      router: Object.freeze({
+        ...config.router,
+        ...config.router.bindings ? {
+          bindings: Object.freeze(
+            config.router.bindings.map(
+              (b) => Object.freeze({ ...b })
+            )
+          )
+        } : {},
+        ...config.router.unmatchedQueue !== void 0 ? { unmatchedQueue: config.router.unmatchedQueue } : {}
+      })
+    } : {}
+  };
+  return Object.freeze(frozen);
+};
+
+// src/persist/memory.ts
+var createMemorySnapshotStore = (initial = []) => {
+  const data = [...initial];
+  return {
+    get data() {
+      return data;
+    },
+    load: () => data.slice(),
+    save: (items) => {
+      data.length = 0;
+      data.push(...items);
+    }
+  };
+};
+var createMemoryRowStore = (initial = []) => {
+  const rows = initial.map((row) => ({
+    id: row.id,
+    item: row.item
+  }));
+  return {
+    get rows() {
+      return rows;
+    },
+    loadAll: () => rows.map((row) => ({ id: row.id, item: row.item })),
+    insert: (record) => {
+      const index = rows.findIndex((row) => row.id === record.id);
+      const next = { id: record.id, item: record.item };
+      if (index >= 0) {
+        rows[index] = next;
+      } else {
+        rows.push(next);
+      }
+    },
+    remove: (id) => {
+      const index = rows.findIndex((row) => row.id === id);
+      if (index >= 0) {
+        rows.splice(index, 1);
+      }
+    },
+    clear: () => {
+      rows.length = 0;
+    }
+  };
+};
+
+// src/persist/json-codec.util.ts
+var StorageCodecError = class extends Error {
+  name = "StorageCodecError";
+  cause;
+  constructor(message, cause) {
+    super(message, cause !== void 0 ? { cause } : void 0);
+    this.cause = cause;
+  }
+};
+var defaultJsonCodec = () => ({
+  serialize: (value) => JSON.stringify(value),
+  deserialize: (raw) => JSON.parse(raw)
+});
+var decodeWithCodec = (label, raw, deserialize) => {
+  try {
+    return deserialize(raw);
+  } catch (error) {
+    throw new StorageCodecError(
+      `Failed to deserialize ${label}: ${error instanceof Error ? error.message : String(error)}`,
+      error
+    );
+  }
+};
+
+// src/persist/web-storage-access.util.ts
+var getGlobalStorage = (name) => {
+  const storage = globalThis[name];
+  if (!storage) {
+    throw new Error(
+      `${name} is not available; pass an explicit \`storage\` option`
+    );
+  }
+  return storage;
+};
+var lazyGlobalStorage = (name) => ({
+  getItem: (key) => getGlobalStorage(name).getItem(key),
+  setItem: (key, value) => getGlobalStorage(name).setItem(key, value),
+  removeItem: (key) => getGlobalStorage(name).removeItem(key)
+});
+var resolveStorage = (storage) => {
+  if (storage) return storage;
+  return lazyGlobalStorage("localStorage");
+};
+
+// src/persist/web-storage.ts
+var createWebSnapshotStore = (options) => {
+  const storage = () => resolveStorage(options.storage);
+  const codec = options.codec ?? defaultJsonCodec();
+  return {
+    load: () => {
+      const raw = storage().getItem(options.key);
+      if (raw === null || raw === "") return [];
+      const items = decodeWithCodec(
+        `snapshot "${options.key}"`,
+        raw,
+        codec.deserialize
+      );
+      return Array.isArray(items) ? items : [];
+    },
+    save: (items) => {
+      storage().setItem(options.key, codec.serialize([...items]));
+    }
+  };
+};
+var orderCodec = {
+  serialize: (ids) => JSON.stringify(ids),
+  deserialize: (raw) => {
+    const ids = JSON.parse(raw);
+    if (!Array.isArray(ids)) return [];
+    return ids.filter((id) => typeof id === "string");
+  }
+};
+var createWebRowStore = (options) => {
+  const storage = () => resolveStorage(options.storage);
+  const itemCodec = options.itemCodec ?? defaultJsonCodec();
+  const orderKey = `${options.key}:order`;
+  const rowKey = (id) => `${options.key}:row:${id}`;
+  const readOrder = () => {
+    const raw = storage().getItem(orderKey);
+    if (raw === null || raw === "") return [];
+    return decodeWithCodec(
+      `row order "${orderKey}"`,
+      raw,
+      orderCodec.deserialize
+    );
+  };
+  const writeOrder = (ids) => {
+    if (ids.length === 0) {
+      storage().removeItem(orderKey);
+      return;
+    }
+    storage().setItem(orderKey, orderCodec.serialize(ids));
+  };
+  return {
+    loadAll: () => {
+      const ids = readOrder();
+      const rows = [];
+      for (const id of ids) {
+        const raw = storage().getItem(rowKey(id));
+        if (raw === null) continue;
+        rows.push({
+          id,
+          item: decodeWithCodec(
+            `row "${rowKey(id)}"`,
+            raw,
+            itemCodec.deserialize
+          )
+        });
+      }
+      return rows;
+    },
+    insert: (record) => {
+      const store = storage();
+      store.setItem(rowKey(record.id), itemCodec.serialize(record.item));
+      const ids = readOrder();
+      if (!ids.includes(record.id)) {
+        ids.push(record.id);
+        writeOrder(ids);
+      }
+    },
+    remove: (id) => {
+      const store = storage();
+      store.removeItem(rowKey(id));
+      writeOrder(readOrder().filter((entry) => entry !== id));
+    },
+    clear: () => {
+      const store = storage();
+      for (const id of readOrder()) {
+        store.removeItem(rowKey(id));
+      }
+      store.removeItem(orderKey);
+    }
+  };
+};
+var createLocalStorageSnapshotStore = (key, options = {}) => createWebSnapshotStore({
+  ...options,
+  key,
+  storage: lazyGlobalStorage("localStorage")
+});
+var createLocalStorageRowStore = (key, options = {}) => createWebRowStore({
+  ...options,
+  key,
+  storage: lazyGlobalStorage("localStorage")
+});
+var createSessionStorageSnapshotStore = (key, options = {}) => createWebSnapshotStore({
+  ...options,
+  key,
+  storage: lazyGlobalStorage("sessionStorage")
+});
+var createSessionStorageRowStore = (key, options = {}) => createWebRowStore({
+  ...options,
+  key,
+  storage: lazyGlobalStorage("sessionStorage")
+});
+
+// src/config/store-resolve.util.ts
+var isWebAdapter = (adapter) => adapter === "localStorage" || adapter === "sessionStorage";
+var isSnapshotStore = (value) => typeof value.load === "function" && typeof value.save === "function";
+var isRowStore = (value) => {
+  const store = value;
+  return typeof store.loadAll === "function" && typeof store.insert === "function" && typeof store.remove === "function" && typeof store.clear === "function";
+};
+var createBuiltinSnapshot = (storeName, adapter, key, options) => {
+  if (adapter === "memory") {
+    return createMemorySnapshotStore();
+  }
+  if (key === void 0 || key.length === 0) {
+    throw new Error(
+      `config.stores.${storeName}.key is required when adapter is "${adapter}"`
+    );
+  }
+  if (options.storage) {
+    return createWebSnapshotStore({
+      key,
+      storage: options.storage
+    });
+  }
+  if (adapter === "localStorage") {
+    return createLocalStorageSnapshotStore(key);
+  }
+  return createSessionStorageSnapshotStore(key);
+};
+var createBuiltinRow = (storeName, adapter, key, options) => {
+  if (adapter === "memory") {
+    return createMemoryRowStore();
+  }
+  if (key === void 0 || key.length === 0) {
+    throw new Error(
+      `config.stores.${storeName}.key is required when adapter is "${adapter}"`
+    );
+  }
+  if (options.storage) {
+    return createWebRowStore({
+      key,
+      storage: options.storage
+    });
+  }
+  if (adapter === "localStorage") {
+    return createLocalStorageRowStore(key);
+  }
+  return createSessionStorageRowStore(key);
+};
+var resolveStore = (storeName, definition, options) => {
+  if ("impl" in definition) {
+    const impl = definition.impl;
+    if (definition.strategy === "snapshot" && !isSnapshotStore(impl)) {
+      throw new Error(
+        `config.stores.${storeName}.impl must be a SnapshotStore (strategy is "snapshot")`
+      );
+    }
+    if (definition.strategy === "row" && !isRowStore(impl)) {
+      throw new Error(
+        `config.stores.${storeName}.impl must be a RowStore (strategy is "row")`
+      );
+    }
+    return impl;
+  }
+  const { adapter, strategy } = definition;
+  const key = definition.key;
+  if (isWebAdapter(adapter) && (key === void 0 || key.length === 0)) {
+    throw new Error(
+      `config.stores.${storeName}.key is required when adapter is "${adapter}"`
+    );
+  }
+  if (strategy === "snapshot") {
+    return createBuiltinSnapshot(storeName, adapter, key, options);
+  }
+  return createBuiltinRow(storeName, adapter, key, options);
+};
+var resolveAllStores = (stores, options) => {
+  const resolved = {};
+  if (!stores) return resolved;
+  for (const [name, definition] of Object.entries(stores)) {
+    resolved[name] = resolveStore(name, definition, options);
+  }
+  return resolved;
+};
+
+// src/config/parse.util.ts
+var BUILTIN_ADAPTERS = /* @__PURE__ */ new Set([
+  "memory",
+  "localStorage",
+  "sessionStorage"
+]);
+var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var expectString = (value, path) => {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${path} must be a non-empty string`);
+  }
+  return value;
+};
+var expectBoolean = (value, path) => {
+  if (typeof value !== "boolean") {
+    throw new Error(`${path} must be a boolean`);
+  }
+  return value;
+};
+var expectPositiveFinite = (value, path) => {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    throw new Error(`${path} must be a finite number >= 1`);
+  }
+  return value;
+};
+var parseAdapter = (value, path) => {
+  if (typeof value !== "string" || !BUILTIN_ADAPTERS.has(value)) {
+    throw new Error(
+      `${path} must be one of: memory, localStorage, sessionStorage`
+    );
+  }
+  return value;
+};
+var isSnapshotStoreLike = (value) => isPlainObject(value) && typeof value.load === "function" && typeof value.save === "function";
+var isRowStoreLike = (value) => isPlainObject(value) && typeof value.loadAll === "function" && typeof value.insert === "function" && typeof value.remove === "function" && typeof value.clear === "function";
+var parseStrategy = (value, path) => {
+  if (value !== "snapshot" && value !== "row") {
+    throw new Error(`${path} must be "snapshot" or "row"`);
+  }
+  return value;
+};
+
+// src/config/validate.ts
+var parseStoreDefinition = (value, path, { allowJs }) => {
+  if (!isPlainObject(value)) {
+    throw new Error(`${path} must be an object`);
+  }
+  const strategy = parseStrategy(value.strategy, `${path}.strategy`);
+  if (value.impl !== void 0) {
+    if (!allowJs) {
+      throw new Error(
+        `${path}.impl is only valid in JS config (not JSON); implement SnapshotStore/RowStore and pass the instance from a module`
+      );
+    }
+    if (value.adapter !== void 0) {
+      throw new Error(
+        `${path} cannot set both "adapter" and "impl"`
+      );
+    }
+    if (strategy === "snapshot") {
+      if (!isSnapshotStoreLike(value.impl)) {
+        throw new Error(
+          `${path}.impl must be a SnapshotStore (load + save)`
+        );
+      }
+      return {
+        strategy: "snapshot",
+        impl: value.impl
+      };
+    }
+    if (!isRowStoreLike(value.impl)) {
+      throw new Error(
+        `${path}.impl must be a RowStore (loadAll + insert + remove + clear)`
+      );
+    }
+    return {
+      strategy: "row",
+      impl: value.impl
+    };
+  }
+  if (value.adapter === void 0) {
+    throw new Error(
+      `${path} must define "adapter" (built-in) or "impl" (custom store)`
+    );
+  }
+  const adapter = parseAdapter(value.adapter, `${path}.adapter`);
+  const key = value.key === void 0 ? void 0 : expectString(value.key, `${path}.key`);
+  if ((adapter === "localStorage" || adapter === "sessionStorage") && (key === void 0 || key.length === 0)) {
+    throw new Error(
+      `${path}.key is required when adapter is "${adapter}"`
+    );
+  }
+  if (strategy === "snapshot") {
+    return {
+      strategy: "snapshot",
+      adapter,
+      ...key !== void 0 ? { key } : {}
+    };
+  }
+  return {
+    strategy: "row",
+    adapter,
+    ...key !== void 0 ? { key } : {}
+  };
+};
+var parsePersistConfig = (value, path, storeNames) => {
+  if (!isPlainObject(value)) {
+    throw new Error(`${path} must be an object`);
+  }
+  const store = expectString(value.store, `${path}.store`);
+  if (!storeNames.has(store)) {
+    throw new Error(
+      `${path}.store "${store}" is not defined in config.stores`
+    );
+  }
+  const autoSave = value.autoSave === void 0 ? void 0 : expectBoolean(value.autoSave, `${path}.autoSave`);
+  return {
+    store,
+    ...autoSave !== void 0 ? { autoSave } : {}
+  };
+};
+var parseWorkerConfig = (value, path) => {
+  if (typeof value === "function") {
+    return value;
+  }
+  if (!isPlainObject(value)) {
+    throw new Error(
+      `${path} must be a function or { run, concurrency?, autoStart? }`
+    );
+  }
+  if (typeof value.run !== "function") {
+    throw new Error(`${path}.run must be a function`);
+  }
+  const concurrency = value.concurrency === void 0 ? void 0 : expectPositiveFinite(value.concurrency, `${path}.concurrency`);
+  const autoStart = value.autoStart === void 0 ? void 0 : expectBoolean(value.autoStart, `${path}.autoStart`);
+  return {
+    run: value.run,
+    ...concurrency !== void 0 ? { concurrency } : {},
+    ...autoStart !== void 0 ? { autoStart } : {}
+  };
+};
+var parseQueueConfig = (value, path, storeNames, { allowJs }) => {
+  if (!isPlainObject(value)) {
+    throw new Error(`${path} must be an object`);
+  }
+  const queue = {};
+  if (value.maxSize !== void 0) {
+    queue.maxSize = expectPositiveFinite(value.maxSize, `${path}.maxSize`);
+  }
+  if (value.persist !== void 0) {
+    queue.persist = parsePersistConfig(
+      value.persist,
+      `${path}.persist`,
+      storeNames
+    );
+  }
+  if (value.worker !== void 0) {
+    if (!allowJs) {
+      throw new Error(
+        `${path}.worker is only valid in JS config (functions cannot be expressed in JSON)`
+      );
+    }
+    queue.worker = parseWorkerConfig(value.worker, `${path}.worker`);
+  }
+  return queue;
+};
+var parseBindingConfig = (value, path) => {
+  if (!isPlainObject(value)) {
+    throw new Error(`${path} must be an object`);
+  }
+  return {
+    pattern: expectString(value.pattern, `${path}.pattern`),
+    queue: expectString(value.queue, `${path}.queue`)
+  };
+};
+var parseRouterConfig = (value, path) => {
+  if (!isPlainObject(value)) {
+    throw new Error(`${path} must be an object`);
+  }
+  const router = {};
+  if (value.bindings !== void 0) {
+    if (!Array.isArray(value.bindings)) {
+      throw new Error(`${path}.bindings must be an array`);
+    }
+    router.bindings = value.bindings.map(
+      (binding, index) => parseBindingConfig(binding, `${path}.bindings[${index}]`)
+    );
+  }
+  if (value.unmatchedQueue !== void 0) {
+    router.unmatchedQueue = expectString(
+      value.unmatchedQueue,
+      `${path}.unmatchedQueue`
+    );
+  }
+  return router;
+};
+var parseSystemConfigValue = (value, options) => {
+  if (!isPlainObject(value)) {
+    throw new Error("config must be an object");
+  }
+  if (!isPlainObject(value.queues)) {
+    throw new Error("config.queues must be an object");
+  }
+  const queueNames = Object.keys(value.queues);
+  if (queueNames.length === 0) {
+    throw new Error("config.queues must define at least one queue");
+  }
+  const stores = {};
+  if (value.stores !== void 0) {
+    if (!isPlainObject(value.stores)) {
+      throw new Error("config.stores must be an object");
+    }
+    for (const name of Object.keys(value.stores)) {
+      if (name.length === 0) {
+        throw new Error("config.stores keys must be non-empty strings");
+      }
+      stores[name] = parseStoreDefinition(
+        value.stores[name],
+        `config.stores.${name}`,
+        { allowJs: options.allowJs }
+      );
+    }
+  }
+  const storeNames = new Set(Object.keys(stores));
+  const queues = {};
+  for (const name of queueNames) {
+    if (name.length === 0) {
+      throw new Error("config.queues keys must be non-empty strings");
+    }
+    queues[name] = parseQueueConfig(
+      value.queues[name],
+      `config.queues.${name}`,
+      storeNames,
+      { allowJs: options.allowJs }
+    );
+  }
+  const config = { queues };
+  if (Object.keys(stores).length > 0) {
+    config.stores = stores;
+  }
+  if (value.router !== void 0) {
+    config.router = parseRouterConfig(value.router, "config.router");
+  }
+  if (value.hydrate !== void 0) {
+    config.hydrate = expectBoolean(value.hydrate, "config.hydrate");
+  }
+  if (config.router?.bindings) {
+    for (const [index, binding] of config.router.bindings.entries()) {
+      if (!(binding.queue in queues)) {
+        throw new Error(
+          `config.router.bindings[${index}].queue "${binding.queue}" is not defined in config.queues`
+        );
+      }
+    }
+  }
+  if (config.router?.unmatchedQueue !== void 0) {
+    if (!(config.router.unmatchedQueue in queues)) {
+      throw new Error(
+        `config.router.unmatchedQueue "${config.router.unmatchedQueue}" is not defined in config.queues`
+      );
+    }
+  }
+  return config;
+};
+var validateSystemConfig = (value) => parseSystemConfigValue(value, { allowJs: false });
+var validateJsConfig = (value) => parseSystemConfigValue(value, { allowJs: true });
+var defineConfig = (config) => validateJsConfig(config);
+var parseSystemConfig = (json) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "invalid JSON";
+    throw new Error(`config JSON is invalid: ${message}`);
+  }
+  return validateSystemConfig(parsed);
+};
+
+// src/config/from-config.ts
+var resolveWorker = (worker) => {
+  if (typeof worker === "function") {
+    return { run: worker, options: {} };
+  }
+  const { run, concurrency, autoStart } = worker;
+  return {
+    run,
+    options: {
+      ...concurrency !== void 0 ? { concurrency } : {},
+      ...autoStart !== void 0 ? { autoStart } : {}
+    }
+  };
+};
+var buildQueueFromConfig = (queueName, queueConfig, storeDefs, resolvedStores) => {
+  let queue = buildQueue(
+    queueConfig.maxSize !== void 0 ? { maxSize: queueConfig.maxSize } : {}
+  );
+  if (queueConfig.persist) {
+    const storeName = queueConfig.persist.store;
+    const definition = storeDefs?.[storeName];
+    const store = resolvedStores[storeName];
+    if (!definition || !store) {
+      throw new Error(
+        `config.queues.${queueName}.persist.store "${storeName}" is not defined in config.stores`
+      );
+    }
+    if (definition.strategy === "snapshot") {
+      if (!isSnapshotStore(store)) {
+        throw new Error(
+          `config.stores.${storeName} is not a SnapshotStore`
+        );
+      }
+      queue = withSnapshotPersist(queue, store, {
+        autoSave: queueConfig.persist.autoSave
+      });
+    } else {
+      if (!isRowStore(store)) {
+        throw new Error(
+          `config.stores.${storeName} is not a RowStore`
+        );
+      }
+      queue = withRowPersist(queue, store);
+    }
+  }
+  if (queueConfig.worker) {
+    const { run, options: workerOptions } = resolveWorker(queueConfig.worker);
+    queue = withWorker(queue, run, workerOptions);
+  }
+  return queue;
+};
+var buildFromConfig = async (config, options = {}) => {
+  const validated = validateJsConfig(config);
+  const resolvedStores = resolveAllStores(validated.stores, options);
+  const queues = {};
+  for (const [name, queueConfig] of Object.entries(validated.queues)) {
+    queues[name] = buildQueueFromConfig(
+      name,
+      queueConfig,
+      validated.stores,
+      resolvedStores
+    );
+  }
+  let router;
+  if (validated.router) {
+    const queueMap = queues;
+    let unmatchedTarget;
+    if (validated.router.unmatchedQueue !== void 0) {
+      const sink = queueMap[validated.router.unmatchedQueue];
+      if (!sink) {
+        throw new Error(
+          `router unmatchedQueue "${validated.router.unmatchedQueue}" is not defined`
+        );
+      }
+      unmatchedTarget = sink;
+    }
+    const built = buildRouter(
+      unmatchedTarget !== void 0 ? { unmatchedTarget } : {}
+    );
+    for (const binding of validated.router.bindings ?? []) {
+      const target = queueMap[binding.queue];
+      if (!target) {
+        throw new Error(
+          `router binding queue "${binding.queue}" is not defined`
+        );
+      }
+      built.bind(binding.pattern, target);
+    }
+    router = built;
+  }
+  const hydrateAll = async () => {
+    const tasks = [];
+    for (const queue of Object.values(
+      queues
+    )) {
+      if (typeof queue.hydrate === "function") {
+        tasks.push(queue.hydrate());
+      }
+    }
+    await Promise.all(tasks);
+  };
+  const flushAll = async () => {
+    const tasks = [];
+    for (const queue of Object.values(
+      queues
+    )) {
+      if (typeof queue.flush === "function") {
+        tasks.push(queue.flush());
+      }
+    }
+    await Promise.all(tasks);
+  };
+  const shouldHydrate = validated.hydrate ?? Object.values(validated.queues).some((q) => q.persist !== void 0);
+  if (shouldHydrate) {
+    await hydrateAll();
+  }
+  return {
+    queues,
+    stores: resolvedStores,
+    router,
+    hydrateAll,
+    flushAll,
+    config: freezeConfig(validated)
+  };
+};
+var buildFromJson = async (json, options = {}) => {
+  const config = parseSystemConfig(json);
+  return buildFromConfig(config, options);
+};
+
+// src/worker/retry.ts
+var RetryExhaustedError = class extends Error {
+  name = "RetryExhaustedError";
+  attempts;
+  cause;
+  constructor(attempts, cause) {
+    super(`Retry exhausted after ${attempts} attempt(s)`, { cause });
+    this.attempts = attempts;
+    this.cause = cause;
+  }
+};
+var sleep = (ms) => new Promise((resolve) => {
+  const schedule = globalThis.setTimeout;
+  schedule(() => resolve(), ms);
+});
+var resolveDelay = (delay, failedAttempt, error) => {
+  if (delay === void 0) return 0;
+  if (typeof delay === "function") return Math.max(0, delay(failedAttempt, error));
+  return Math.max(0, delay);
+};
+var withRetry = (worker, options) => {
+  const opts = typeof options === "number" ? { retries: options } : options;
+  const maxRetries = Math.max(0, opts.retries);
+  const shouldRetry = opts.shouldRetry ?? (() => true);
+  return async (item) => {
+    let lastError;
+    for (let attempt = 1; attempt <= maxRetries + 1; attempt += 1) {
+      try {
+        return await worker(item);
+      } catch (error) {
+        lastError = error;
+        const failedAttempt = attempt;
+        const retriesLeft = maxRetries + 1 - attempt;
+        if (retriesLeft <= 0 || !shouldRetry(error, failedAttempt)) {
+          throw new RetryExhaustedError(failedAttempt, error);
+        }
+        const wait = resolveDelay(opts.delay, failedAttempt, error);
+        if (wait > 0) {
+          await sleep(wait);
+        }
+      }
+    }
+    throw lastError;
+  };
+};
+
+// src/worker/pipeline.ts
+function pipeline(...steps) {
+  if (steps.length === 0) {
+    throw new Error("pipeline requires at least one step");
+  }
+  return async (input) => {
+    let value = input;
+    for (const step of steps) {
+      value = await step(value);
+    }
+    return value;
+  };
+}
+
+export { MULTI_WILDCARD, QueueFullError, RetryExhaustedError, SINGLE_WILDCARD, StorageCodecError, TOPIC_SEPARATOR, buildEventEmitter, buildFromConfig, buildFromJson, buildQueue, buildRouter, createId, createLocalStorageRowStore, createLocalStorageSnapshotStore, createMemoryRowStore, createMemorySnapshotStore, createSessionStorageRowStore, createSessionStorageSnapshotStore, createTypedEmit, createWebRowStore, createWebSnapshotStore, defineConfig, isValidPattern, isValidTopic, matchTopic, parseSystemConfig, pipeline, validateJsConfig, validateSystemConfig, withRetry, withRowPersist, withSnapshotPersist, withWorker };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map