@fluojs/notifications 1.0.2 → 2.0.0

package/dist/service.js

@@ -5,7 +5,8 @@ function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e =
 function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
 function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
 import { Inject } from '@fluojs/core';
-import { NotificationChannelNotFoundError, NotificationQueueNotConfiguredError } from './errors.js';
+import { NotificationChannelNotFoundError, NotificationQueueNotConfiguredError, NotificationQueueResultIntegrityError } from './errors.js';
+import { createNotificationDispatchSnapshot, createNotificationLifecycleEventSnapshot } from './snapshots.js';
 import { createNotificationsPlatformStatusSnapshot } from './status.js';
 import { NOTIFICATION_CHANNELS, NOTIFICATIONS_OPTIONS } from './tokens.js';
 let _NotificationsService;
@@ -38,6 +39,7 @@ class NotificationsService {
    * @returns A normalized dispatch result describing direct vs queued delivery.
    * @throws {NotificationChannelNotFoundError} When no registered channel matches `notification.channel`.
    * @throws {NotificationQueueNotConfiguredError} When queue delivery is requested without a queue adapter.
+   * @throws {NotificationQueueResultIntegrityError} When a queue adapter returns an invalid delivery identifier.
    *
    * @example
    * ```ts
@@ -50,52 +52,60 @@ class NotificationsService {
    * ```
    */
   async dispatch(notification, options = {}) {
-    const requestedPublicationError = await this.publishLifecycleEventBestEffort('notification.dispatch.requested', notification, options);
+    const dispatchNotification = createNotificationDispatchSnapshot(notification);
+    return this.dispatchAdmitted(dispatchNotification, options);
+  }
+  async dispatchAdmitted(dispatchNotification, options) {
+    const requestedPublicationError = await this.publishLifecycleEventBestEffort('notification.dispatch.requested', dispatchNotification, options);
     if (this.shouldQueueSingleDispatch(options)) {
       try {
-        this.requireChannel(notification.channel);
+        this.requireChannel(dispatchNotification.channel);
       } catch (error) {
-        await this.publishFailureLifecycleEvent(notification, options, error, requestedPublicationError);
+        await this.publishFailureLifecycleEvent(dispatchNotification, options, error, requestedPublicationError);
         throw error;
       }
-      const job = this.createQueueJob(notification);
+      const job = this.createQueueJob(dispatchNotification);
       try {
-        const deliveryId = await this.requireQueueAdapter().enqueue(job);
+        const queue = this.requireQueueAdapter();
+        throwIfAborted(options.signal);
+        const deliveryId = validateQueueDeliveryId(await queue.enqueue(job, {
+          signal: options.signal
+        }));
         const result = {
-          channel: notification.channel,
-          deliveryId: this.normalizeDeliveryId(deliveryId, notification),
+          channel: dispatchNotification.channel,
+          deliveryId,
           queued: true,
           status: 'queued'
         };
-        await this.publishLifecycleEventBestEffort('notification.dispatch.queued', notification, options, result.deliveryId);
+        await this.publishLifecycleEventBestEffort('notification.dispatch.queued', dispatchNotification, options, result.deliveryId);
         return result;
       } catch (error) {
-        await this.publishFailureLifecycleEvent(notification, options, error, requestedPublicationError);
+        await this.publishFailureLifecycleEvent(dispatchNotification, options, error, requestedPublicationError);
         throw error;
       }
     }
     let channel;
     try {
-      channel = this.requireChannel(notification.channel);
+      channel = this.requireChannel(dispatchNotification.channel);
     } catch (error) {
-      await this.publishFailureLifecycleEvent(notification, options, error, requestedPublicationError);
+      await this.publishFailureLifecycleEvent(dispatchNotification, options, error, requestedPublicationError);
       throw error;
     }
     try {
-      const delivery = await channel.send(notification, {
+      const delivery = await channel.send(dispatchNotification, {
         signal: options.signal
       });
       const result = {
-        channel: notification.channel,
-        deliveryId: this.normalizeDeliveryId(delivery.externalId, notification),
+        channel: dispatchNotification.channel,
+        deliveryId: this.normalizeDeliveryId(delivery.externalId, dispatchNotification),
         metadata: delivery.metadata,
         queued: delivery.status === 'queued',
         status: delivery.status ?? 'delivered'
       };
-      await this.publishLifecycleEventBestEffort(result.queued ? 'notification.dispatch.queued' : 'notification.dispatch.delivered', notification, options, result.deliveryId);
+      await this.publishLifecycleEventBestEffort(result.queued ? 'notification.dispatch.queued' : 'notification.dispatch.delivered', dispatchNotification, options, result.deliveryId);
       return result;
     } catch (error) {
-      await this.publishFailureLifecycleEvent(notification, options, error, requestedPublicationError);
+      await this.publishFailureLifecycleEvent(dispatchNotification, options, error, requestedPublicationError);
       throw error;
     }
   }
@@ -108,6 +118,7 @@ class NotificationsService {
    * @param options Optional queue preference and tolerant error-handling controls.
    * @returns A batch summary containing successes and captured failures.
    * @throws {NotificationQueueNotConfiguredError} When queue-backed bulk delivery is requested without a queue adapter.
+   * @throws {NotificationQueueResultIntegrityError} When a queue adapter returns invalid delivery identifiers.
    */
   async dispatchMany(notifications, options = {}) {
     if (notifications.length === 0) {
@@ -119,42 +130,53 @@ class NotificationsService {
         succeeded: 0
       };
     }
+    const dispatchNotifications = notifications.map(notification => createNotificationDispatchSnapshot(notification));
     if (this.shouldQueue(notifications.length, options)) {
-      const requestedPublicationErrors = await this.publishRequestedLifecycleEvents(notifications, options);
+      const requestedPublicationErrors = await this.publishRequestedLifecycleEvents(dispatchNotifications, options);
       let queue;
       try {
         queue = this.requireQueueAdapter();
       } catch (error) {
-        await this.publishFailureLifecycleEvents(notifications, options, error, requestedPublicationErrors);
+        await this.publishFailureLifecycleEvents(dispatchNotifications, options, error, requestedPublicationErrors);
         throw error;
       }
       try {
-        for (const notification of notifications) {
+        for (const notification of dispatchNotifications) {
           this.requireChannel(notification.channel);
         }
       } catch (error) {
-        await this.publishFailureLifecycleEvents(notifications, options, error, requestedPublicationErrors);
+        await this.publishFailureLifecycleEvents(dispatchNotifications, options, error, requestedPublicationErrors);
         throw error;
       }
-      const jobs = notifications.map(notification => this.createQueueJob(notification));
+      const jobs = dispatchNotifications.map(notification => this.createQueueJob(notification));
       if (!queue.enqueueMany) {
-        return this.dispatchManyThroughSequentialQueueFallback(notifications, jobs, options, requestedPublicationErrors);
+        return this.dispatchManyThroughSequentialQueueFallback(dispatchNotifications, jobs, options, requestedPublicationErrors);
       }
-      let ids;
+      const admittedJobCount = jobs.length;
+      let results;
       try {
-        ids = validateQueueBatchDeliveryIds(await queue.enqueueMany(jobs), jobs.length);
+        throwIfAborted(options.signal);
+        const ids = validateQueueBatchDeliveryIds(await queue.enqueueMany(jobs, {
+          signal: options.signal
+        }), admittedJobCount);
+        results = dispatchNotifications.map((notification, index) => {
+          const deliveryId = ids[index];
+          if (deliveryId === undefined) {
+            throw createQueueResultIntegrityError('enqueueMany', `queue id at index ${index} must be present`);
+          }
+          return {
+            channel: notification.channel,
+            deliveryId,
+            queued: true,
+            status: 'queued'
+          };
+        });
       } catch (error) {
-        await this.publishFailureLifecycleEvents(notifications, options, error, requestedPublicationErrors);
+        await this.publishFailureLifecycleEvents(dispatchNotifications, options, error, requestedPublicationErrors);
         throw error;
       }
-      const results = notifications.map((notification, index) => ({
-        channel: notification.channel,
-        deliveryId: this.normalizeDeliveryId(ids[index], notification),
-        queued: true,
-        status: 'queued'
-      }));
-      for (let index = 0; index < notifications.length; index += 1) {
-        const notification = notifications[index];
+      for (let index = 0; index < dispatchNotifications.length; index += 1) {
+        const notification = dispatchNotifications[index];
         await this.publishLifecycleEventBestEffort('notification.dispatch.queued', notification, options, results[index]?.deliveryId);
       }
       return {
@@ -167,9 +189,9 @@ class NotificationsService {
     }
     const results = [];
     const failures = [];
-    for (const notification of notifications) {
+    for (const notification of dispatchNotifications) {
       try {
-        results.push(await this.dispatch(notification, options));
+        results.push(await this.dispatchAdmitted(notification, options));
       } catch (error) {
         const failure = {
           error: error instanceof Error ? error : new Error('Notification dispatch failed.'),
@@ -199,6 +221,7 @@ class NotificationsService {
     return createNotificationsPlatformStatusSnapshot({
       bulkQueueThreshold: this.options.queue?.bulkThreshold ?? 0,
       channelsRegistered: this.channelsByName.size,
+      eventPublicationEnabled: this.options.events?.publishLifecycleEvents ?? false,
       eventPublisherConfigured: this.options.events !== undefined,
       queueConfigured: this.options.queue !== undefined
     });
@@ -261,7 +284,7 @@ class NotificationsService {
     if (!this.options.events || !this.shouldPublishLifecycleEvents(options)) {
       return;
     }
-    const event = {
+    const event = createNotificationLifecycleEventSnapshot({
       channel: notification.channel,
       deliveryId,
       error: error instanceof Error ? {
@@ -271,7 +294,7 @@ class NotificationsService {
       name,
       notification,
       occurredAt: new Date().toISOString()
-    };
+    });
     await this.options.events.publisher.publish(event);
   }
   async publishLifecycleEventBestEffort(name, notification, options, deliveryId, error) {
@@ -323,7 +346,10 @@ class NotificationsService {
         continue;
       }
       try {
-        const deliveryId = this.normalizeDeliveryId(await queue.enqueue(job), notification);
+        throwIfAborted(options.signal);
+        const deliveryId = validateQueueDeliveryId(await queue.enqueue(job, {
+          signal: options.signal
+        }));
         const result = {
           channel: notification.channel,
           deliveryId,
@@ -362,73 +388,174 @@ class NotificationsService {
   }
 }
 export { _NotificationsService as NotificationsService };
+function throwIfAborted(signal) {
+  signal?.throwIfAborted();
+}
 function validateQueueBatchDeliveryIds(value, expectedCount) {
   if (!Array.isArray(value)) {
-    throw createQueueBatchResultIntegrityError(`expected ${expectedCount} queue ids but received a non-array result`);
+    throw createQueueResultIntegrityError('enqueueMany', `expected ${expectedCount} queue ids but received a non-array result`);
   }
-  if (value.length !== expectedCount) {
-    throw createQueueBatchResultIntegrityError(`expected ${expectedCount} queue ids but received ${value.length}`);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const lengthDescriptor = Object.getOwnPropertyDescriptor(value, 'length');
+  if (!isOwnDataPropertyDescriptor(lengthDescriptor)) {
+    throw createQueueResultIntegrityError('enqueueMany', `expected ${expectedCount} queue ids but received an invalid length descriptor`);
+  }
+  if (lengthDescriptor.value !== expectedCount) {
+    throw createQueueResultIntegrityError('enqueueMany', `expected ${expectedCount} queue ids but received ${String(lengthDescriptor.value)}`);
   }
   const ids = [];
-  for (let index = 0; index < value.length; index += 1) {
-    if (!Object.hasOwn(value, index)) {
-      throw createQueueBatchResultIntegrityError(`queue id at index ${index} must be present`);
+  for (let index = 0; index < expectedCount; index += 1) {
+    const descriptor = descriptors[String(index)];
+    if (!descriptor) {
+      throw createQueueResultIntegrityError('enqueueMany', `queue id at index ${index} must be present`);
+    }
+    if (!isOwnDataPropertyDescriptor(descriptor)) {
+      throw createQueueResultIntegrityError('enqueueMany', `queue id at index ${index} must be an own data property`);
     }
-    const entry = value[index];
+    const entry = descriptor.value;
     if (typeof entry !== 'string' || entry.length === 0) {
-      throw createQueueBatchResultIntegrityError(`queue id at index ${index} must be a non-empty string`);
+      throw createQueueResultIntegrityError('enqueueMany', `queue id at index ${index} must be a non-empty string`);
     }
     ids.push(entry);
   }
-  return ids;
+  return Object.freeze(ids);
+}
+function isOwnDataPropertyDescriptor(descriptor) {
+  return descriptor !== undefined && Object.hasOwn(descriptor, 'value') && !Object.hasOwn(descriptor, 'get') && !Object.hasOwn(descriptor, 'set');
+}
+function validateQueueDeliveryId(value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw createQueueResultIntegrityError('enqueue', 'queue id must be a non-empty string');
+  }
+  return value;
 }
-function createQueueBatchResultIntegrityError(message) {
-  const error = new Error(`Notifications queue adapter returned an invalid enqueueMany() result: ${message}.`);
-  error.name = 'NotificationQueueResultIntegrityError';
-  return error;
+function createQueueResultIntegrityError(operation, message) {
+  return new NotificationQueueResultIntegrityError(operation, message);
 }
 function createLifecyclePublicationFailureError(dispatchError, ...publicationErrors) {
   const primaryMessage = dispatchError instanceof Error ? dispatchError.message : 'Notification dispatch failed.';
   return new AggregateError([dispatchError, ...publicationErrors], `Notification dispatch failed, and failed lifecycle event publication also failed: ${primaryMessage}`);
 }
 function stableNotificationHash(notification) {
-  let hash = 0x811c9dc5;
-  const input = stableStringify(notification);
+  let hash = 0xcbf29ce484222325n;
+  const input = stableStringify(notification, createStableStringifyContext());
   for (let index = 0; index < input.length; index += 1) {
-    hash ^= input.charCodeAt(index);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
+    hash ^= BigInt(input.charCodeAt(index));
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n);
   }
-  return hash.toString(36).padStart(7, '0');
+  return hash.toString(36).padStart(13, '0');
+}
+function createStableStringifyContext() {
+  return {
+    nextReferenceId: 0,
+    seen: new WeakMap()
+  };
 }
-function stableStringify(value) {
-  if (value === null || typeof value !== 'object') {
+function enterStableObject(value, context) {
+  const existingReferenceId = context.seen.get(value);
+  if (existingReferenceId !== undefined) {
+    return existingReferenceId;
+  }
+  context.nextReferenceId += 1;
+  context.seen.set(value, context.nextReferenceId);
+  return undefined;
+}
+function createCollectionSortContext(parent) {
+  const context = createStableStringifyContext();
+  context.nextReferenceId = 1;
+  context.seen.set(parent, 1);
+  return context;
+}
+function stableCollectionSortKey(value, parent) {
+  return stableStringify(value, createCollectionSortContext(parent));
+}
+function compareStableString(left, right) {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}
+function stableStringify(value, context) {
+  if (value === null) {
+    return 'null';
+  }
+  if (typeof value !== 'object') {
+    if (typeof value === 'bigint') {
+      return `BigInt:${value.toString()}`;
+    }
     return JSON.stringify(value) ?? String(value);
   }
+  const circularReferenceId = enterStableObject(value, context);
+  if (circularReferenceId !== undefined) {
+    return `Circular:${circularReferenceId}`;
+  }
+  if (value instanceof ArrayBuffer) {
+    const serialized = `ArrayBuffer:{byteLength:${value.byteLength},bytes:${stableByteArray(new Uint8Array(value))}}`;
+    context.seen.delete(value);
+    return serialized;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const serialized = `ArrayBufferView:{view:${JSON.stringify(Object.prototype.toString.call(value).slice(8, -1))},byteOffset:${value.byteOffset},byteLength:${value.byteLength},bytes:${stableByteArray(new Uint8Array(value.buffer, value.byteOffset, value.byteLength))}}`;
+    context.seen.delete(value);
+    return serialized;
+  }
   if (value instanceof Date) {
-    return Number.isNaN(value.getTime()) ? 'Date:Invalid' : `Date:${JSON.stringify(value.toISOString())}`;
+    const serialized = Number.isNaN(value.getTime()) ? 'Date:Invalid' : `Date:${JSON.stringify(value.toISOString())}`;
+    context.seen.delete(value);
+    return serialized;
   }
   if (value instanceof URL) {
-    return `URL:${JSON.stringify(value.href)}`;
+    const serialized = `URL:${JSON.stringify(value.href)}`;
+    context.seen.delete(value);
+    return serialized;
   }
   if (value instanceof URLSearchParams) {
-    return `URLSearchParams:${JSON.stringify(value.toString())}`;
+    const serialized = `URLSearchParams:${JSON.stringify(value.toString())}`;
+    context.seen.delete(value);
+    return serialized;
   }
   if (value instanceof RegExp) {
-    return `RegExp:${JSON.stringify(value.source)}/${value.flags}`;
+    const serialized = `RegExp:${JSON.stringify(value.source)}/${value.flags}`;
+    context.seen.delete(value);
+    return serialized;
   }
   if (value instanceof Map) {
-    const entries = Array.from(value.entries()).map(([key, entry]) => `[${stableStringify(key)},${stableStringify(entry)}]`).sort();
+    const entries = Array.from(value.entries()).map(([key, entry]) => ({
+      entry,
+      key,
+      sortKey: `[${stableCollectionSortKey(key, value)},${stableCollectionSortKey(entry, value)}]`
+    })).sort((left, right) => compareStableString(left.sortKey, right.sortKey)).map(({
+      key,
+      entry
+    }) => `[${stableStringify(key, context)},${stableStringify(entry, context)}]`);
+    context.seen.delete(value);
     return `Map:{${entries.join(',')}}`;
   }
   if (value instanceof Set) {
-    const entries = Array.from(value.values()).map(entry => stableStringify(entry)).sort();
+    const entries = Array.from(value.values()).map(entry => ({
+      entry,
+      sortKey: stableCollectionSortKey(entry, value)
+    })).sort((left, right) => compareStableString(left.sortKey, right.sortKey)).map(({
+      entry
+    }) => stableStringify(entry, context));
+    context.seen.delete(value);
     return `Set:[${entries.join(',')}]`;
   }
   if (Array.isArray(value)) {
-    return `[${value.map(entry => stableStringify(entry)).join(',')}]`;
+    const serialized = `[${value.map(entry => stableStringify(entry, context)).join(',')}]`;
+    context.seen.delete(value);
+    return serialized;
   }
   const prototype = Object.getPrototypeOf(value);
   const objectTag = prototype && prototype !== Object.prototype ? `${prototype.constructor?.name ?? 'Object'}:` : '';
-  const entries = Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => left.localeCompare(right));
-  return `${objectTag}{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(',')}}`;
+  const entries = Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => compareStableString(left, right));
+  const serialized = `${objectTag}{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry, context)}`).join(',')}}`;
+  context.seen.delete(value);
+  return serialized;
+}
+function stableByteArray(bytes) {
+  return `[${Array.from(bytes).join(',')}]`;
 }

package/dist/snapshots.d.ts

@@ -0,0 +1,28 @@
+import type { NotificationDispatchRequest, NotificationLifecycleEvent } from './types.js';
+/**
+ * Copies and freezes one notification envelope at dispatch admission.
+ *
+ * @param notification Notification envelope supplied by the caller.
+ * @returns The immutable dispatch snapshot.
+ * @internal
+ */
+export declare function createNotificationDispatchSnapshot<TRequest extends NotificationDispatchRequest>(notification: TRequest): TRequest;
+/**
+ * Copies and freezes one lifecycle event before publication.
+ *
+ * @param event Lifecycle event details captured by the dispatch service.
+ * @returns The immutable lifecycle event snapshot.
+ * @internal
+ */
+export declare function createNotificationLifecycleEventSnapshot<TRequest extends NotificationDispatchRequest>(event: {
+    channel: string;
+    deliveryId?: string;
+    error?: {
+        message: string;
+        name: string;
+    };
+    name: NotificationLifecycleEvent<TRequest>['name'];
+    notification: TRequest;
+    occurredAt: string;
+}): NotificationLifecycleEvent<TRequest>;
+//# sourceMappingURL=snapshots.d.ts.map

package/dist/snapshots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshots.d.ts","sourceRoot":"","sources":["../src/snapshots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,2BAA2B,EAC3B,0BAA0B,EAU3B,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAAC,QAAQ,SAAS,2BAA2B,EAC7F,YAAY,EAAE,QAAQ,GACrB,QAAQ,CAEV;AAED;;;;;;GAMG;AACH,wBAAgB,wCAAwC,CAAC,QAAQ,SAAS,2BAA2B,EACnG,KAAK,EAAE;IACL,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,IAAI,EAAE,0BAA0B,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;IACnD,YAAY,EAAE,QAAQ,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB,GACA,0BAA0B,CAAC,QAAQ,CAAC,CAItC"}