@fluojs/notifications 1.0.1 → 1.0.3

package/README.ko.md

@@ -2,7 +2,7 @@
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
 
-fluo를 위한 채널 중립(notification channel-agnostic) 알림 오케스트레이션 패키지입니다. 알림 채널의 공통 계약을 고정하고, Nest-like 모듈 API를 제공하며, 선택적인 큐 기반 전달 심(seam)과 라이프사이클 이벤트 발행 심을 노출합니다.
+fluo를 위한 채널 중립(notification channel-agnostic) 알림 오케스트레이션 패키지입니다. 알림 채널의 공통 계약을 고정하고, 친숙한 dynamic-module 사용감을 가진 명시적 모듈 등록 API를 제공하며, 선택적인 큐 기반 전달 심(seam)과 라이프사이클 이벤트 발행 심을 노출합니다.
 
 ## 목차
 
@@ -34,7 +34,7 @@ npm install @fluojs/notifications
 
 ### 1. foundation 모듈 등록
 
-알림 모듈 등록은 `NotificationsModule.forRoot(...)` 또는 `NotificationsModule.forRootAsync(...)`로 구성합니다.
+알림 모듈 등록은 `channels`에 명시적인 `NotificationChannel` 값을 전달하는 `NotificationsModule.forRoot(...)` 또는 `NotificationsModule.forRootAsync(...)`로 구성합니다.
 
 ```typescript
 import { Module } from '@fluojs/core';
@@ -91,11 +91,13 @@ export class WelcomeService {
 
 `NotificationsModule.forRoot(...)`와 `NotificationsModule.forRootAsync(...)`는 기본적으로 `NotificationsService`, `NOTIFICATIONS`, `NOTIFICATION_CHANNELS`를 global provider로 export합니다. 이 provider들이 notifications module을 import한 module 안에서만 보이도록 유지하려면 `global: false`를 설정합니다. 애플리케이션 서비스는 fluo의 class-level `@Inject(...)` decorator로 의존성을 선언해야 standard-decorator DI container가 parameter decorator 없이 서비스를 resolve할 수 있습니다.
 
+Migration boundary: channel registration은 metadata 기반이 아니라 value 기반입니다. NestJS provider discovery, `@Injectable()` metadata, `emitDecoratorMetadata`에 기대어 channel이 등록된다고 가정하지 마세요. 애플리케이션 코드에서 `NotificationChannel` object를 만들거나 `NotificationsModule.forRootAsync({ inject, useFactory, global? })`에서 반환한 뒤, `channels` option으로 전달합니다.
+
 ## 일반적인 패턴
 
 ### 큐 기반 대량 전달
 
-많은 알림을 백그라운드 워커로 넘기고 싶다면 선택적인 queue seam을 사용합니다.
+많은 알림을 백그라운드 워커로 넘기고 싶다면 선택적인 queue seam을 사용합니다. Queue adapter는 애플리케이션 소유 integration이며, `@fluojs/notifications`는 abstract adapter contract만 호출합니다.
 
 ```typescript
 NotificationsModule.forRoot({
@@ -116,19 +118,19 @@ NotificationsModule.forRoot({
 
 Behavioral contract 메모:
 
-- 알림 개수가 `bulkThreshold` 이상이면 대량 큐 위임이 시작됩니다.
+- 알림 개수가 `bulkThreshold` 이상이면 대량 큐 위임이 시작되며, `dispatchMany(..., { queue: true })`는 batch가 threshold보다 작아도 queue-backed delivery를 명시적으로 강제합니다.
 - `dispatch()`는 queue adapter가 구성되어 있어도 기본적으로 직접 전달을 유지합니다. 단건 알림을 큐로 보내려면 `dispatch(..., { queue: true })`를 사용합니다.
 - queue adapter가 있어도 직접 전달을 강제하려면 `dispatch(..., { queue: false })`를 사용합니다.
-- 큐 기반 전달은 단건 dispatch에서는 opt-in이고, `dispatchMany(...)`에서는 threshold 기반으로 동작합니다.
-- Queue job에는 `notification.id`가 있으면 그 값을, 없으면 notification envelope에서 파생한 deterministic `id` idempotency key가 포함됩니다. Queue adapter는 deduplication을 지원하는 backing queue에 이 값을 전달해야 합니다.
+- 큐 기반 전달은 단건 dispatch에서는 opt-in이고, `dispatchMany(...)`에서는 caller가 `{ queue: true }`를 명시하지 않는 한 threshold 기반으로 동작합니다.
+- Queue job에는 `notification.id`가 있으면 그 값을, 없으면 notification envelope의 runtime-neutral serialization에서 파생한 deterministic fallback `id` idempotency key가 포함됩니다. Queue adapter는 deduplication을 지원하는 backing queue에 이 값을 전달해야 합니다. 생성된 fallback key는 cyclic opaque payload를 포함해 동등한 지원 입력에 대해 deterministic하지만, cross-release durable identity 계약은 아닙니다. 애플리케이션 또는 package upgrade를 넘어 안정적인 identity가 필요하면 `notification.id`를 설정하세요.
 - `dispatchMany(..., { continueOnError: true })`는 direct delivery 또는 순차 queue fallback enqueue에서 첫 실패를 던지는 대신 실패들을 수집합니다.
 - queue enqueue가 실패하면 서비스는 enqueue 에러를 다시 던지기 전에 결정적인 `notification.dispatch.failed` 라이프사이클 이벤트를 발행합니다. queued bulk dispatch는 queue 미구성, channel 해석, provider/adapter failure 경로를 포함해 이미 `requested`를 발행한 모든 notification에 대해 terminal `queued` 또는 `failed` 이벤트도 발행합니다.
 - `enqueueMany(...)`가 없으면 대량 queue delivery는 input order대로 각 job을 개별 enqueue하는 방식으로 fallback합니다. `continueOnError: true`이면 성공한 enqueue는 `results`에 남고 실패한 enqueue는 `failures`로 반환됩니다. 그렇지 않으면 첫 enqueue failure를 다시 던지기 전에 아직 terminal 상태가 없는 나머지 requested fallback job에 `failed` 라이프사이클 이벤트를 발행합니다.
-- foundation 패키지는 특정 큐 구현을 가정하거나 import하지 않습니다.
+- foundation 패키지는 특정 큐 구현을 가정하거나 import하지 않고, queue client/worker를 만들거나 애플리케이션 소유 queue resource를 close/drain하지 않습니다.
 
 ### 이벤트 발행자를 통한 라이프사이클 발행
 
-foundation 패키지를 `@fluojs/event-bus` 구현에 직접 결합하지 않고도 caller-visible 라이프사이클 이벤트를 발행할 수 있습니다.
+foundation 패키지를 `@fluojs/event-bus` 구현에 직접 결합하지 않고도 caller-visible 라이프사이클 이벤트를 발행할 수 있습니다. Event publisher 역시 애플리케이션 소유이며, foundation 패키지는 concrete event bus를 create/import/close/drain하지 않습니다.
 
 ```typescript
 NotificationsModule.forRoot({
@@ -151,7 +153,7 @@ NotificationsModule.forRoot({
 - `notification.dispatch.delivered`
 - `notification.dispatch.failed`
 
-`events.publisher`가 구성되어 있으면 `publishLifecycleEvents: false`를 설정하지 않는 한 lifecycle event publication은 기본으로 켜집니다. 채널 delivery가 `externalId`를 생략하면 시간이나 난수에 의존하지 않고 notification envelope에서 파생한 deterministic fallback delivery id가 부여되어 dispatch result가 호출자에게 안정적으로 유지됩니다. 채널 해석 실패는 `NotificationChannelNotFoundError`를 던지기 전에 `requested` 이후 `failed` 이벤트를 발행하며, 이는 영구적인 구성 오류로 취급해야 합니다. Queue enqueue와 provider delivery 실패도 `failed` 이벤트를 발행하지만, retry 여부는 underlying adapter/provider error를 기준으로 분류해야 합니다. 성공 경로 lifecycle event의 publication failure는 이미 전달된 알림을 애플리케이션 실패로 바꾸지 않도록 best-effort로 유지됩니다. `notification.dispatch.failed` publication failure는 원래 dispatch error와 publisher error를 모두 포함하는 `AggregateError`로 호출자에게 드러나므로 failed-event 보장이 조용히 약해지지 않습니다.
+`events.publisher`가 구성되어 있으면 `publishLifecycleEvents: false`를 설정하지 않는 한 lifecycle event publication은 기본으로 켜집니다. 채널 delivery가 `externalId`를 생략하면 시간이나 난수에 의존하지 않는 deterministic fallback delivery id가 부여되어 dispatch result가 호출자에게 안정적으로 유지됩니다. 생성된 fallback id는 현재 envelope shape를 위한 runtime-neutral key이지, 문서화된 full-payload hash 계약이 아닙니다. release를 넘어 durable identity가 필요하면 `notification.id`를 설정하세요. 채널 해석 실패는 `NotificationChannelNotFoundError`를 던지기 전에 `requested` 이후 `failed` 이벤트를 발행하며, 이는 영구적인 구성 오류로 취급해야 합니다. Queue enqueue와 provider delivery 실패도 `failed` 이벤트를 발행하지만, retry 여부는 underlying adapter/provider error를 기준으로 분류해야 합니다. 성공 경로 lifecycle event의 publication failure는 이미 전달된 알림을 애플리케이션 실패로 바꾸지 않도록 best-effort로 유지됩니다. `notification.dispatch.failed` publication failure는 원래 dispatch error와 publisher error를 모두 포함하는 `AggregateError`로 호출자에게 드러나므로 failed-event 보장이 조용히 약해지지 않습니다.
 
 ### 의도적인 제한 사항
 
@@ -160,6 +162,7 @@ foundation 패키지는 의도적으로 다음을 **포함하지 않습니다**:
 - 내장 email, Slack, Discord 구현
 - 직접적인 `process.env` 접근
 - `@fluojs/queue` 또는 `@fluojs/event-bus`의 concrete runtime 타입 의존성
+- concrete queue 또는 event-bus resource를 create/import/close/drain하는 것. Queue adapter와 event publisher는 애플리케이션 소유 integration입니다.
 - provider별 payload 의미를 공유 계약에 인코딩하는 것
 
 이 제한 사항은 leaf 패키지가 하나의 안정적인 오케스트레이션 계층 위에서 독립적으로 진화할 수 있도록 하는 package contract의 일부입니다.
@@ -207,8 +210,8 @@ foundation 패키지는 의도적으로 다음을 **포함하지 않습니다**:
 - `NotificationChannelNotFoundError`
 - `NotificationQueueNotConfiguredError`
 
-상태 snapshot은 platform diagnostics를 위해 `operationMode`, dependency diagnostics, ownership, readiness, health 필드를 포함합니다.
-Queue adapter가 구성되면 `details.dependencies`에 `notifications.queue-adapter`가 포함되고, lifecycle event가 event publisher를 통해 발행되면 `notifications.event-publisher`가 포함됩니다. 이러한 선택적 통합은 `ownership.externallyManaged: true`로 표시되지만, foundation 패키지가 concrete queue 또는 event-bus 리소스를 닫지 않으므로 `ownsResources: false`를 유지합니다.
+상태 snapshot은 platform diagnostics를 위해 `readiness`, `health`, `ownership`, 그리고 `details` object를 포함합니다.
+`operationMode`, `dependencies`, `bulkQueueThreshold`, `queueConfigured`, `eventPublisherConfigured`는 `details` 아래에 있으며 top-level snapshot field가 아닙니다. Queue adapter가 구성되면 `details.dependencies`에 `notifications.queue-adapter`가 포함되고, lifecycle event가 event publisher를 통해 발행되면 `notifications.event-publisher`가 포함됩니다. 이러한 선택적 통합은 `ownership.externallyManaged: true`로 표시되지만, foundation 패키지가 concrete queue 또는 event-bus 리소스를 create/close/drain하지 않으므로 `ownsResources: false`를 유지합니다.
 
 ## 관련 패키지
 

package/README.md

@@ -2,7 +2,7 @@
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
 
-Channel-agnostic notification orchestration for fluo. It freezes the shared contract for notification channels, provides a Nest-like module API, and exposes optional queue-backed delivery and lifecycle event publication seams.
+Channel-agnostic notification orchestration for fluo. It freezes the shared contract for notification channels, provides explicit module registration with familiar dynamic-module ergonomics, and exposes optional queue-backed delivery and lifecycle event publication seams.
 
 ## Table of Contents
 
@@ -34,7 +34,7 @@ npm install @fluojs/notifications
 
 ### 1. Register the foundation module
 
-Register notifications with `NotificationsModule.forRoot(...)` or `NotificationsModule.forRootAsync(...)`.
+Register notifications with `NotificationsModule.forRoot(...)` or `NotificationsModule.forRootAsync(...)` by passing explicit `NotificationChannel` values in `channels`.
 
 ```typescript
 import { Module } from '@fluojs/core';
@@ -91,11 +91,13 @@ export class WelcomeService {
 
 `NotificationsModule.forRoot(...)` and `NotificationsModule.forRootAsync(...)` export `NotificationsService`, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS` as global providers by default. Set `global: false` when these providers should stay visible only to the module that imports the notifications module. Application services should declare dependencies with fluo's class-level `@Inject(...)` decorator so the standard-decorator DI container can resolve the service without parameter decorators.
 
+Migration boundary: channel registration is value-based, not metadata-based. Do not rely on NestJS provider discovery, `@Injectable()` metadata, or `emitDecoratorMetadata` to register channels. Build `NotificationChannel` objects in application code or return them from `NotificationsModule.forRootAsync({ inject, useFactory, global? })`, then pass them through the `channels` option.
+
 ## Common Patterns
 
 ### Queue-backed bulk delivery
 
-Use the optional queue seam when many notifications should be deferred to background workers.
+Use the optional queue seam when many notifications should be deferred to background workers. The queue adapter is an application-owned integration; `@fluojs/notifications` only calls the abstract adapter contract.
 
 ```typescript
 NotificationsModule.forRoot({
@@ -116,19 +118,19 @@ NotificationsModule.forRoot({
 
 Behavioral contract notes:
 
-- Bulk queue delegation starts when the notification count reaches `bulkThreshold`.
+- Bulk queue delegation starts when the notification count reaches `bulkThreshold`, and `dispatchMany(..., { queue: true })` explicitly forces queue-backed delivery even when the batch is below that threshold.
 - `dispatch()` stays direct by default even when a queue adapter is configured. Use `dispatch(..., { queue: true })` to opt one single notification into queue-backed delivery.
 - Use `dispatch(..., { queue: false })` to force direct delivery even when a queue adapter exists.
-- Queue-backed delivery is opt-in for single dispatch and threshold-driven for `dispatchMany(...)`.
-- Queue jobs include a deterministic `id` idempotency key derived from `notification.id` when present, otherwise from the notification envelope. Queue adapters should pass this value to backing queues that support deduplication.
+- Queue-backed delivery is opt-in for single dispatch and threshold-driven for `dispatchMany(...)` unless the caller explicitly passes `{ queue: true }`.
+- Queue jobs include a deterministic fallback `id` idempotency key derived from `notification.id` when present, otherwise from a runtime-neutral serialization of the notification envelope. Queue adapters should pass this value to backing queues that support deduplication. The generated fallback key is deterministic for equivalent supported inputs, including cyclic opaque payloads, but it is not a durable cross-release identity contract; set `notification.id` when callers need stable identity across application or package upgrades.
 - `dispatchMany(..., { continueOnError: true })` collects failures instead of throwing on the first failed direct delivery or sequential queue fallback enqueue.
 - When queue enqueue fails, the service emits deterministic `notification.dispatch.failed` lifecycle events before rethrowing the enqueue error to the caller. Queued bulk dispatch also publishes a terminal `queued` or `failed` event for every notification that already emitted `requested`, including queue-missing, channel-resolution, and provider/adapter failure paths.
 - If `enqueueMany(...)` is unavailable, bulk queue delivery falls back to enqueueing each job individually in input order. With `continueOnError: true`, successful enqueues remain visible in `results` while failed enqueues are returned in `failures`; without it, the first enqueue failure is rethrown after the remaining requested fallback jobs receive `failed` lifecycle events.
-- The foundation package does not assume or import a concrete queue implementation.
+- The foundation package does not assume or import a concrete queue implementation, create queue clients/workers, or close/drain application-owned queue resources.
 
 ### Lifecycle publication through an event publisher
 
-Publish caller-visible lifecycle events without coupling the foundation package to `@fluojs/event-bus` directly.
+Publish caller-visible lifecycle events without coupling the foundation package to `@fluojs/event-bus` directly. The event publisher is also application-owned; the foundation package does not create, import, close, or drain a concrete event bus.
 
 ```typescript
 NotificationsModule.forRoot({
@@ -151,7 +153,7 @@ Published event names:
 - `notification.dispatch.delivered`
 - `notification.dispatch.failed`
 
-If `events.publisher` is configured, lifecycle event publication defaults to on unless `publishLifecycleEvents: false` is set. Channel deliveries that omit `externalId` receive a deterministic fallback delivery id derived from the notification envelope so dispatch results remain stable for callers without relying on time or random data. Channel resolution failures publish `requested` and then `failed` events before throwing `NotificationChannelNotFoundError`; treat those failures as permanent configuration errors. Queue enqueue and provider delivery failures also publish `failed` events, but callers should classify their retry behavior from the underlying adapter/provider error. Publication failures for success-path lifecycle events remain best-effort so a delivered notification is not converted into an application failure. Publication failures for `notification.dispatch.failed` are caller-visible as `AggregateError` values that include both the original dispatch error and the publisher error so failed-event guarantees are not silently weakened.
+If `events.publisher` is configured, lifecycle event publication defaults to on unless `publishLifecycleEvents: false` is set. Channel deliveries that omit `externalId` receive a deterministic fallback delivery id so dispatch results remain stable for callers without relying on time or random data. Generated fallback ids are runtime-neutral keys for the current envelope shape, not a documented full-payload hash contract; set `notification.id` when callers need durable identity across releases. Channel resolution failures publish `requested` and then `failed` events before throwing `NotificationChannelNotFoundError`; treat those failures as permanent configuration errors. Queue enqueue and provider delivery failures also publish `failed` events, but callers should classify their retry behavior from the underlying adapter/provider error. Publication failures for success-path lifecycle events remain best-effort so a delivered notification is not converted into an application failure. Publication failures for `notification.dispatch.failed` are caller-visible as `AggregateError` values that include both the original dispatch error and the publisher error so failed-event guarantees are not silently weakened.
 
 ### Intentional limitations
 
@@ -160,6 +162,7 @@ The foundation package intentionally does **not**:
 - ship built-in email, Slack, or Discord implementations
 - inspect `process.env` directly
 - depend on `@fluojs/queue` or `@fluojs/event-bus` concrete runtime types
+- create, import, close, or drain concrete queue or event-bus resources; queue adapters and event publishers are application-owned integrations
 - encode provider-specific payload semantics into the shared contract
 
 These limitations are part of the package contract so leaf packages can evolve independently while sharing one stable orchestration layer.
@@ -207,8 +210,8 @@ These limitations are part of the package contract so leaf packages can evolve i
 - `NotificationChannelNotFoundError`
 - `NotificationQueueNotConfiguredError`
 
-Status snapshots include `operationMode`, dependency diagnostics, ownership, readiness, and health fields for platform diagnostics.
-When a queue adapter is configured, `details.dependencies` includes `notifications.queue-adapter`; when lifecycle events are published through an event publisher, it includes `notifications.event-publisher`. Those optional integrations mark `ownership.externallyManaged: true` while the foundation package still reports `ownsResources: false` because it does not close concrete queue or event-bus resources.
+Status snapshots include `readiness`, `health`, `ownership`, and a `details` object for platform diagnostics.
+`operationMode`, `dependencies`, `bulkQueueThreshold`, `queueConfigured`, and `eventPublisherConfigured` live under `details`; they are not top-level snapshot fields. When a queue adapter is configured, `details.dependencies` includes `notifications.queue-adapter`; when lifecycle events are published through an event publisher, it includes `notifications.event-publisher`. Those optional integrations mark `ownership.externallyManaged: true` while the foundation package still reports `ownsResources: false` because it does not create, close, or drain concrete queue or event-bus resources.
 
 ## Related Packages
 

package/dist/service.d.ts

@@ -57,9 +57,10 @@ export declare class NotificationsService implements Notifications {
     private shouldQueueSingleDispatch;
     private shouldQueue;
     private publishLifecycleEvent;
-    private publishLifecycleEventSafely;
+    private publishLifecycleEventBestEffort;
     private publishFailureLifecycleEvent;
     private publishFailureLifecycleEvents;
+    private publishRequestedLifecycleEvents;
     private dispatchManyThroughSequentialQueueFallback;
 }
 //# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,oCAAoC,EACpC,mBAAmB,EACnB,+BAA+B,EAC/B,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAE1B,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,qBACa,oBAAqB,YAAW,aAAa;IAItD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0C;gBAGtD,OAAO,EAAE,oCAAoC,EAC9D,QAAQ,EAAE,SAAS,mBAAmB,EAAE;IAO1C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,QAAQ,SAAS,2BAA2B,EACzD,YAAY,EAAE,QAAQ,EACtB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC;IA+DtC;;;;;;;;OAQG;IACG,YAAY,CAAC,QAAQ,SAAS,2BAA2B,EAC7D,aAAa,EAAE,SAAS,QAAQ,EAAE,EAClC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,+BAA+B,CAAC,QAAQ,CAAC,CAAC;IAmGrD;;;;OAIG;IACH,4BAA4B;IAS5B,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,4BAA4B;IAQpC,OAAO,CAAC,yBAAyB;IAIjC,OAAO,CAAC,WAAW;YAYL,qBAAqB;YA4BrB,2BAA2B;YAc3B,4BAA4B;YAY5B,6BAA6B;YAoB7B,0CAA0C;CA2DzD"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,oCAAoC,EACpC,mBAAmB,EACnB,+BAA+B,EAC/B,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAE1B,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,qBACa,oBAAqB,YAAW,aAAa;IAItD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0C;gBAGtD,OAAO,EAAE,oCAAoC,EAC9D,QAAQ,EAAE,SAAS,mBAAmB,EAAE;IAO1C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,QAAQ,SAAS,2BAA2B,EACzD,YAAY,EAAE,QAAQ,EACtB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC;IAmEtC;;;;;;;;OAQG;IACG,YAAY,CAAC,QAAQ,SAAS,2BAA2B,EAC7D,aAAa,EAAE,SAAS,QAAQ,EAAE,EAClC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,+BAA+B,CAAC,QAAQ,CAAC,CAAC;IAiGrD;;;;OAIG;IACH,4BAA4B;IAS5B,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,4BAA4B;IAQpC,OAAO,CAAC,yBAAyB;IAIjC,OAAO,CAAC,WAAW;YAYL,qBAAqB;YA4BrB,+BAA+B;YAgB/B,4BAA4B;YAmB5B,6BAA6B;YA0B7B,+BAA+B;YAmB/B,0CAA0C;CA4DzD"}

package/dist/service.js

@@ -50,12 +50,12 @@ class NotificationsService {
    * ```
    */
   async dispatch(notification, options = {}) {
-    await this.publishLifecycleEventSafely('notification.dispatch.requested', notification, options);
+    const requestedPublicationError = await this.publishLifecycleEventBestEffort('notification.dispatch.requested', notification, options);
     if (this.shouldQueueSingleDispatch(options)) {
       try {
         this.requireChannel(notification.channel);
       } catch (error) {
-        await this.publishFailureLifecycleEvent(notification, options, error);
+        await this.publishFailureLifecycleEvent(notification, options, error, requestedPublicationError);
         throw error;
       }
       const job = this.createQueueJob(notification);
@@ -67,10 +67,10 @@ class NotificationsService {
           queued: true,
           status: 'queued'
         };
-        await this.publishLifecycleEventSafely('notification.dispatch.queued', notification, options, result.deliveryId);
+        await this.publishLifecycleEventBestEffort('notification.dispatch.queued', notification, options, result.deliveryId);
         return result;
       } catch (error) {
-        await this.publishFailureLifecycleEvent(notification, options, error);
+        await this.publishFailureLifecycleEvent(notification, options, error, requestedPublicationError);
         throw error;
       }
     }
@@ -78,7 +78,7 @@ class NotificationsService {
     try {
       channel = this.requireChannel(notification.channel);
     } catch (error) {
-      await this.publishFailureLifecycleEvent(notification, options, error);
+      await this.publishFailureLifecycleEvent(notification, options, error, requestedPublicationError);
       throw error;
     }
     try {
@@ -92,10 +92,10 @@ class NotificationsService {
         queued: delivery.status === 'queued',
         status: delivery.status ?? 'delivered'
       };
-      await this.publishLifecycleEventSafely(result.queued ? 'notification.dispatch.queued' : 'notification.dispatch.delivered', notification, options, result.deliveryId);
+      await this.publishLifecycleEventBestEffort(result.queued ? 'notification.dispatch.queued' : 'notification.dispatch.delivered', notification, options, result.deliveryId);
       return result;
     } catch (error) {
-      await this.publishFailureLifecycleEvent(notification, options, error);
+      await this.publishFailureLifecycleEvent(notification, options, error, requestedPublicationError);
       throw error;
     }
   }
@@ -120,14 +120,12 @@ class NotificationsService {
       };
     }
     if (this.shouldQueue(notifications.length, options)) {
-      for (const notification of notifications) {
-        await this.publishLifecycleEventSafely('notification.dispatch.requested', notification, options);
-      }
+      const requestedPublicationErrors = await this.publishRequestedLifecycleEvents(notifications, options);
       let queue;
       try {
         queue = this.requireQueueAdapter();
       } catch (error) {
-        await this.publishFailureLifecycleEvents(notifications, options, error);
+        await this.publishFailureLifecycleEvents(notifications, options, error, requestedPublicationErrors);
         throw error;
       }
       try {
@@ -135,18 +133,18 @@ class NotificationsService {
           this.requireChannel(notification.channel);
         }
       } catch (error) {
-        await this.publishFailureLifecycleEvents(notifications, options, error);
+        await this.publishFailureLifecycleEvents(notifications, options, error, requestedPublicationErrors);
         throw error;
       }
       const jobs = notifications.map(notification => this.createQueueJob(notification));
       if (!queue.enqueueMany) {
-        return this.dispatchManyThroughSequentialQueueFallback(notifications, jobs, options);
+        return this.dispatchManyThroughSequentialQueueFallback(notifications, jobs, options, requestedPublicationErrors);
       }
       let ids;
       try {
-        ids = await queue.enqueueMany(jobs);
+        ids = validateQueueBatchDeliveryIds(await queue.enqueueMany(jobs), jobs.length);
       } catch (error) {
-        await this.publishFailureLifecycleEvents(notifications, options, error);
+        await this.publishFailureLifecycleEvents(notifications, options, error, requestedPublicationErrors);
         throw error;
       }
       const results = notifications.map((notification, index) => ({
@@ -157,7 +155,7 @@ class NotificationsService {
       }));
       for (let index = 0; index < notifications.length; index += 1) {
         const notification = notifications[index];
-        await this.publishLifecycleEventSafely('notification.dispatch.queued', notification, options, results[index]?.deliveryId);
+        await this.publishLifecycleEventBestEffort('notification.dispatch.queued', notification, options, results[index]?.deliveryId);
       }
       return {
         failed: 0,
@@ -276,28 +274,45 @@ class NotificationsService {
     };
     await this.options.events.publisher.publish(event);
   }
-  async publishLifecycleEventSafely(name, notification, options, deliveryId, error) {
+  async publishLifecycleEventBestEffort(name, notification, options, deliveryId, error) {
     try {
       await this.publishLifecycleEvent(name, notification, options, deliveryId, error);
-    } catch {
-      return;
+    } catch (publicationError) {
+      return publicationError;
     }
+    return undefined;
   }
-  async publishFailureLifecycleEvent(notification, options, error) {
+  async publishFailureLifecycleEvent(notification, options, error, ...precedingPublicationErrors) {
+    const priorPublicationErrors = precedingPublicationErrors.filter(entry => entry !== undefined);
     try {
       await this.publishLifecycleEvent('notification.dispatch.failed', notification, options, undefined, error);
     } catch (publicationError) {
-      throw createLifecyclePublicationFailureError(error, publicationError);
+      throw createLifecyclePublicationFailureError(error, ...priorPublicationErrors, publicationError);
+    }
+    if (priorPublicationErrors.length > 0) {
+      throw createLifecyclePublicationFailureError(error, ...priorPublicationErrors);
     }
   }
-  async publishFailureLifecycleEvents(notifications, options, error) {
+  async publishFailureLifecycleEvents(notifications, options, error, precedingPublicationErrors = []) {
+    const priorPublicationErrors = precedingPublicationErrors.filter(entry => entry !== undefined);
     const failurePublicationResults = await Promise.allSettled(notifications.map(notification => this.publishLifecycleEvent('notification.dispatch.failed', notification, options, undefined, error)));
     const publicationFailures = failurePublicationResults.filter(result => result.status === 'rejected').map(result => result.reason);
     if (publicationFailures.length > 0) {
-      throw createLifecyclePublicationFailureError(error, ...publicationFailures);
+      throw createLifecyclePublicationFailureError(error, ...priorPublicationErrors, ...publicationFailures);
+    }
+    if (priorPublicationErrors.length > 0) {
+      throw createLifecyclePublicationFailureError(error, ...priorPublicationErrors);
+    }
+  }
+  async publishRequestedLifecycleEvents(notifications, options) {
+    const publicationErrors = [];
+    for (const notification of notifications) {
+      const publicationError = await this.publishLifecycleEventBestEffort('notification.dispatch.requested', notification, options);
+      publicationErrors.push(publicationError);
     }
+    return publicationErrors;
   }
-  async dispatchManyThroughSequentialQueueFallback(notifications, jobs, options) {
+  async dispatchManyThroughSequentialQueueFallback(notifications, jobs, options, requestedPublicationErrors) {
     const queue = this.requireQueueAdapter();
     const results = [];
     const failures = [];
@@ -316,18 +331,18 @@ class NotificationsService {
           status: 'queued'
         };
         results.push(result);
-        await this.publishLifecycleEventSafely('notification.dispatch.queued', notification, options, deliveryId);
+        await this.publishLifecycleEventBestEffort('notification.dispatch.queued', notification, options, deliveryId);
       } catch (error) {
         const failure = {
           error: error instanceof Error ? error : new Error('Notification queue enqueue failed.'),
           notification
         };
         if (!(options.continueOnError ?? false)) {
-          await this.publishFailureLifecycleEvents(notifications.slice(index), options, error);
+          await this.publishFailureLifecycleEvents(notifications.slice(index), options, error, requestedPublicationErrors.slice(index));
           throw error;
         }
         try {
-          await this.publishFailureLifecycleEvent(notification, options, error);
+          await this.publishFailureLifecycleEvent(notification, options, error, requestedPublicationErrors[index]);
         } catch (publicationError) {
           failure.error = publicationError instanceof Error ? publicationError : createLifecyclePublicationFailureError(error, publicationError);
         }
@@ -347,26 +362,142 @@ class NotificationsService {
   }
 }
 export { _NotificationsService as NotificationsService };
+function validateQueueBatchDeliveryIds(value, expectedCount) {
+  if (!Array.isArray(value)) {
+    throw createQueueBatchResultIntegrityError(`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 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`);
+    }
+    const entry = value[index];
+    if (typeof entry !== 'string' || entry.length === 0) {
+      throw createQueueBatchResultIntegrityError(`queue id at index ${index} must be a non-empty string`);
+    }
+    ids.push(entry);
+  }
+  return ids;
+}
+function createQueueBatchResultIntegrityError(message) {
+  const error = new Error(`Notifications queue adapter returned an invalid enqueueMany() result: ${message}.`);
+  error.name = 'NotificationQueueResultIntegrityError';
+  return error;
+}
 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);
+  const input = stableStringify(notification, createStableStringifyContext());
   for (let index = 0; index < input.length; index += 1) {
     hash ^= input.charCodeAt(index);
     hash = Math.imul(hash, 0x01000193) >>> 0;
   }
   return hash.toString(36).padStart(7, '0');
 }
-function stableStringify(value) {
-  if (value === null || typeof value !== 'object') {
+function createStableStringifyContext() {
+  return {
+    nextReferenceId: 0,
+    seen: new WeakMap()
+  };
+}
+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 Date) {
+    const serialized = Number.isNaN(value.getTime()) ? 'Date:Invalid' : `Date:${JSON.stringify(value.toISOString())}`;
+    context.seen.delete(value);
+    return serialized;
+  }
+  if (value instanceof URL) {
+    const serialized = `URL:${JSON.stringify(value.href)}`;
+    context.seen.delete(value);
+    return serialized;
+  }
+  if (value instanceof URLSearchParams) {
+    const serialized = `URLSearchParams:${JSON.stringify(value.toString())}`;
+    context.seen.delete(value);
+    return serialized;
+  }
+  if (value instanceof RegExp) {
+    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]) => ({
+      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 => ({
+      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 `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(',')}}`;
+  const serialized = `${objectTag}{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry, context)}`).join(',')}}`;
+  context.seen.delete(value);
+  return serialized;
 }

package/package.json

@@ -9,7 +9,7 @@
     "event-bus",
     "channels"
   ],
-  "version": "1.0.1",
+  "version": "1.0.3",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,12 +36,13 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.3",
-    "@fluojs/di": "^1.0.3",
-    "@fluojs/runtime": "^1.1.1"
+    "@fluojs/core": "^1.1.0",
+    "@fluojs/di": "^2.0.0",
+    "@fluojs/runtime": "^2.0.1"
   },
   "devDependencies": {
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@fluojs/testing": "^2.0.0"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",