@ultimat3/notify 20.2.1 → 22.0.0

package/README.md

@@ -240,6 +240,20 @@ without bound and every replay would re-send the whole audience.
 | `X_NOTIFY_STORE_MISSING` | an inbox or digest channel with no store installed |
 | `X_NOTIFY_DELIVERY_FAILED` | a channel's `deliver` threw; the run retries on its policy |
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `NotifyChannelDuplicateError` | `X_NOTIFY_CHANNEL_DUPLICATE` | `src/errors.ts` |
+| `NotifyChannelsEmptyError` | `X_NOTIFY_CHANNELS_EMPTY` | `src/errors.ts` |
+| `NotifyDeliveryFailedError` | `X_NOTIFY_DELIVERY_FAILED` | `src/errors.ts` |
+| `NotifyDigestUnsupportedError` | `X_NOTIFY_DIGEST_UNSUPPORTED` | `src/errors.ts` |
+| `NotifyFanoutTooWideError` | `X_NOTIFY_FANOUT_TOO_WIDE` | `src/errors.ts` |
+| `NotifyStoreMissingError` | `X_NOTIFY_STORE_MISSING` | `src/errors.ts` |
+
 ## Boundary
 
 Tier 4. May import tiers 0-3 — enforced by `bun run boundaries`. Its real imports are `core`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/notify",
-  "version": "20.2.1",
+  "version": "22.0.0",
   "description": "Notifications: one declaration, many channels — fan-out, preference gate, digest window, delivery ledger, in-app inbox",
   "license": "MIT",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "20.2.1",
-    "@ultimat3/jobs": "20.2.1",
-    "@ultimat3/schema": "20.2.1",
-    "@ultimat3/time": "20.2.1"
+    "@ultimat3/core": "22.0.0",
+    "@ultimat3/jobs": "22.0.0",
+    "@ultimat3/schema": "22.0.0",
+    "@ultimat3/time": "22.0.0"
   }
 }

package/src/digest.ts

@@ -50,7 +50,13 @@ export interface DigestStore {
    * close it entirely by flipping a row's status here and deleting on `settle`. The memory store
    * below cannot.
    */
-  drain(slot: DigestSlot): Promise<readonly NotifyEvent<unknown>[]>;
+  /**
+   * `endsAt` names the window this flush owns (what `append` answered it). Every window of the
+   * slot closing at or before it is taken — its own, and an OLDER one a crashed flush left behind
+   * — while a newer window, opened after this one closed, stays for its own flush. Omitted, only
+   * the oldest window is taken.
+   */
+  drain(slot: DigestSlot, endsAt?: number): Promise<readonly NotifyEvent<unknown>[]>;
 }
 
 const slotKey = (slot: DigestSlot): string =>
@@ -66,35 +72,46 @@ export interface MemoryDigestStore extends DigestStore {
   clear(): void;
 }
 
+/**
+ * A QUEUE of windows per slot, oldest first. One bucket per slot replaced a closed window that its
+ * flush had not drained yet, so an append arriving between a window's end and its drain lost every
+ * event the earlier window held. A closed window is now sealed under its `endsAt`, and a later
+ * append opens the next one beside it.
+ */
 export function createMemoryDigestStore(): MemoryDigestStore {
-  const buckets = new Map<string, OpenBucket>();
+  const slots = new Map<string, OpenBucket[]>();
   return {
     get open(): number {
-      return buckets.size;
+      let count = 0;
+      for (const windows of slots.values()) count += windows.length;
+      return count;
     },
     append(input) {
       const id = slotKey(input.slot);
       const at = input.now.getTime();
-      const existing = buckets.get(id);
-      // A bucket whose window has already elapsed is not a bucket to append to: its owner is gone
-      // (a crashed flush) and the event would sit there until an unrelated third event arrived.
-      // Re-opening is the repair, and it costs one extra delivery rather than a lost one.
-      if (existing !== undefined && existing.endsAt > at) {
-        existing.events.push(input.event);
-        return Promise.resolve({ opened: false, endsAt: existing.endsAt });
+      const windows = slots.get(id) ?? [];
+      const newest = windows.at(-1);
+      // An elapsed window is SEALED — its flush drains it — and never appended to: the event
+      // opens the next window, which is one extra delivery rather than a lost one.
+      if (newest !== undefined && newest.endsAt > at) {
+        newest.events.push(input.event);
+        return Promise.resolve({ opened: false, endsAt: newest.endsAt });
       }
       const endsAt = at + input.windowMs;
-      buckets.set(id, { endsAt, events: [input.event] });
+      windows.push({ endsAt, events: [input.event] });
+      slots.set(id, windows);
       return Promise.resolve({ opened: true, endsAt });
     },
-    drain(slot) {
+    drain(slot, endsAt) {
       const id = slotKey(slot);
-      const bucket = buckets.get(id);
-      buckets.delete(id);
-      return Promise.resolve(bucket?.events ?? []);
+      const windows = slots.get(id) ?? [];
+      const cut = endsAt === undefined ? 1 : windows.filter((w) => w.endsAt <= endsAt).length;
+      const taken = windows.splice(0, Math.max(cut, 0));
+      if (windows.length === 0) slots.delete(id);
+      return Promise.resolve(taken.flatMap((window) => window.events));
     },
     clear() {
-      buckets.clear();
+      slots.clear();
     },
   };
 }

package/src/fanout-digest.ts

@@ -35,7 +35,9 @@ export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<v
   // One step for the whole append pass: appending is what a replayed attempt must NOT redo, or the
   // same event lands in the digest twice.
   const opened = await step.run(`digest:${channel.name}`, async () => {
-    const owned: string[] = [];
+    // Each owner's OWN window end: two recipients' windows need not close together, and the
+    // drain takes the window it names.
+    const owned: { readonly id: string; readonly endsAt: number }[] = [];
     let endsAt = 0;
     for (const recipient of allowed) {
       const bucket = await digest.append({
@@ -45,7 +47,7 @@ export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<v
         now: ctx.now(),
       });
       if (!bucket.opened) continue;
-      owned.push(recipient.id);
+      owned.push({ id: recipient.id, endsAt: bucket.endsAt });
       endsAt = Math.max(endsAt, bucket.endsAt);
     }
     return { owned, endsAt };
@@ -58,7 +60,7 @@ export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<v
   if (remaining > 0) await step.sleep(`digest-wait:${channel.name}`, remaining);
 
   const byId = new Map(allowed.map((recipient) => [recipient.id, recipient]));
-  for (const id of opened.owned) {
+  for (const { id, endsAt } of opened.owned) {
     const recipient = byId.get(id);
     if (recipient === undefined) continue;
     // Drain and send are TWO steps on purpose. The drain's result is checkpointed, so an ordinary
@@ -66,7 +68,7 @@ export async function flushDigest<Params>(input: DigestFlush<Params>): Promise<v
     // now empty. What it does not close is a process killed between the drain and its checkpoint;
     // `DigestStore.drain` says so in its own words, and a durable store can do better.
     const batch = await step.run(`digest-drain:${channel.name}:${id}`, () =>
-      digest.drain(slotFor(id)),
+      digest.drain(slotFor(id), endsAt),
     );
     if (batch.length === 0) continue;
     const events = rehydrate<Params>(batch);

package/src/index.ts

@@ -47,13 +47,9 @@ export { createMemoryInboxStore, DEFAULT_INBOX_PAGE } from './inbox';
 export type { InboxPurgeBefore, PgInboxStore, PgInboxStoreOptions } from './inbox-pg';
 export {
   createPgInboxStore,
-  SQL_NOTIFY_INBOX_ADD,
   SQL_NOTIFY_INBOX_MARK_READ,
-  SQL_NOTIFY_INBOX_MARK_SEEN,
   SQL_NOTIFY_INBOX_PAGE,
-  SQL_NOTIFY_INBOX_PURGE,
   SQL_NOTIFY_INBOX_TABLE,
-  SQL_NOTIFY_INBOX_UNREAD,
 } from './inbox-pg';
 export type {
   DeliveryClaim,
@@ -65,19 +61,14 @@ export type {
 } from './ledger';
 export {
   createMemoryDeliveryLedger,
-  DEFAULT_MAX_DELIVERY_RECORDS,
   DELIVERY_STATUSES,
   isDeliveryStatus,
 } from './ledger';
 export type { PgDeliveryLedger, PgDeliveryLedgerOptions } from './ledger-pg';
 export {
   createPgDeliveryLedger,
-  DEFAULT_DELIVERY_WINDOW_MS,
   SQL_NOTIFY_CLAIM,
-  SQL_NOTIFY_DELIVERIES_PURGE,
   SQL_NOTIFY_DELIVERIES_TABLE,
-  SQL_NOTIFY_FIND,
-  SQL_NOTIFY_SETTLE,
 } from './ledger-pg';
 export type { NotifyEvent, Recipient } from './notification';
 export { recipientSchema } from './notification';
@@ -101,7 +92,6 @@ export { purgeNotifyDeliveries, purgeNotifyInbox } from './retention';
 export type { InstalledNotifyStores, NotifyStores } from './stores';
 export {
   notifyStores,
-  requireDigest,
   requireInbox,
   resetNotifyStores,
   setNotifyStores,