@fluojs/email 1.0.0-beta.3 → 1.0.0-beta.5

package/README.ko.md

@@ -86,8 +86,9 @@ export class AppModule {}
 import { Inject } from '@fluojs/core';
 import { EmailService } from '@fluojs/email';
 
+@Inject(EmailService)
 export class WelcomeService {
-  constructor(@Inject(EmailService) private readonly email: EmailService) {}
+  constructor(private readonly email: EmailService) {}
 
   async sendWelcome(address: string) {
     await this.email.send({
@@ -139,6 +140,7 @@ Behavioral contract 메모:
 - `createNodemailerEmailTransportFactory(...)`는 Node 전용이며 `@fluojs/email/node`에서만 export됩니다.
 - 이 factory는 자신이 생성한 Nodemailer transporter 리소스를 소유하므로 `EmailService`가 bootstrap 시 검증하고 shutdown 시 닫을 수 있습니다.
 - `createNodemailerEmailTransport(...)`는 이미 존재하는 Nodemailer transporter를 감싸지만 리소스 소유권은 호출자에게 남깁니다.
+- Nodemailer display-name 주소는 구조화된 address object로 전달되며, newline 문자가 포함되면 provider handoff 전에 거부됩니다.
 - SMTP 자격 증명은 여전히 명시적인 옵션 또는 DI를 통해 들어와야 합니다. 루트 패키지와 Node 서브패스 모두 `process.env`를 직접 읽지 않습니다.
 
 ### `EmailService`를 이용한 standalone 전달
@@ -162,10 +164,15 @@ EmailModule.forRootAsync({
 Behavioral contract 메모:
 
 - `EmailService.send(...)`는 전달 전에 `defaultFrom`과 `defaultReplyTo`를 해석합니다.
+- `EmailService.send(...)`는 빈 `to` 수신자를 transport handoff 전에 거부하므로 transport가 빈 전달 대상을 받지 않습니다.
+- `EmailService.send(...)`와 `EmailService.sendNotification(...)`은 이미 abort된 `AbortSignal`을 템플릿 렌더링 또는 transport handoff 전에 반영합니다.
 - `EmailService.send(...)`는 `accepted`, `pending`, `rejected` 수신자를 분리해 보존하므로 provider의 부분 실패가 호출자에게 그대로 보입니다.
 - `EmailService.sendMany(...)`는 기본적으로 fail-fast입니다. 실패를 batch result에 수집하려면 `continueOnError: true`를 전달합니다.
 - `EmailService.createPlatformStatusSnapshot()`은 diagnostics를 위해 lifecycle, readiness, health, transport ownership details를 노출합니다.
-- 서비스는 모듈 bootstrap 시 transport를 초기화하고, factory가 소유한 리소스만 애플리케이션 shutdown 시 닫습니다.
+- 서비스는 모듈 bootstrap 시 transport를 초기화하며, `verifyOnModuleInit: true`인 경우 bootstrap 검증이 성공적으로 끝날 때까지 delivery가 transport handoff로 진행되지 않습니다.
+- 거부된 `forRootAsync(...)` 옵션 factory 결과는 영구 memoize되지 않으며, 다음 provider resolution에서 configuration lookup을 다시 시도할 수 있습니다.
+- shutdown이 시작된 뒤에는 `EmailService.send(...)`와 `EmailService.sendNotification(...)`이 transport를 재사용하거나 lazy 생성하지 않고 `EmailLifecycleError`로 실패합니다. 진행 중인 factory 소유 transport 생성은 shutdown이 기다린 뒤 닫습니다.
+- transport `verify()`와 `close()`에서 발생한 provider error는 diagnostics를 위해 lifecycle failure의 `cause`로 보존됩니다.
 - 모듈 옵션은 provider wiring 전에 trim 및 normalize됩니다. 여기에는 sender 기본값, notification channel 이름, transport factory 소유권이 포함됩니다.
 - 이 패키지는 절대로 `process.env`를 직접 읽지 않습니다. 모든 설정은 명시적인 옵션 또는 DI를 통해 들어와야 합니다.
 
@@ -209,6 +216,7 @@ Behavioral contract 메모:
 
 - `EmailChannel`은 `pending` 또는 `rejected` 수신자가 하나라도 있으면 전달을 성공으로 보고하지 않고 notification dispatch를 실패로 처리합니다.
 - `EmailService.sendNotification(...)`은 렌더링된 template output을 payload 및 notification metadata와 병합합니다. payload 필드는 notification fallback보다 우선합니다.
+- Template rendering에는 notification `payload`, `metadata`, `locale`, `subject`, `template`이 전달되며, payload `text`, `html`과 notification `subject`가 렌더링된 fallback보다 우선합니다.
 
 ### 큐 기반 대량 전달
 
@@ -306,6 +314,7 @@ email 패키지는 의도적으로 다음을 **포함하지 않습니다**:
 
 - `createEmailPlatformStatusSnapshot(...)`
 - `EmailConfigurationError`
+- `EmailLifecycleError`: lifecycle로 차단된 전달, transport 초기화 또는 검증, 소유 리소스 shutdown 실패에서 발생합니다. 애플리케이션 teardown과 전송이 경합할 수 있다면 이 에러를 catch하세요.
 - `EmailMessageValidationError`
 
 ### Node 전용 서브패스

package/README.md

@@ -86,8 +86,9 @@ export class AppModule {}
 import { Inject } from '@fluojs/core';
 import { EmailService } from '@fluojs/email';
 
+@Inject(EmailService)
 export class WelcomeService {
-  constructor(@Inject(EmailService) private readonly email: EmailService) {}
+  constructor(private readonly email: EmailService) {}
 
   async sendWelcome(address: string) {
     await this.email.send({
@@ -139,6 +140,7 @@ Behavioral contract notes:
 - `createNodemailerEmailTransportFactory(...)` is Node-only and is exported exclusively from `@fluojs/email/node`.
 - The factory owns the Nodemailer transporter it creates, so `EmailService` can verify it on bootstrap and close it during shutdown.
 - `createNodemailerEmailTransport(...)` wraps an existing Nodemailer transporter without transferring resource ownership.
+- Nodemailer display-name addresses are forwarded as structured address objects and reject newline characters before provider handoff.
 - SMTP credentials still enter through explicit options or DI. Neither the root package nor the Node subpath reads `process.env` directly.
 
 ### Standalone delivery with `EmailService`
@@ -162,10 +164,15 @@ EmailModule.forRootAsync({
 Behavioral contract notes:
 
 - `EmailService.send(...)` resolves `defaultFrom` and `defaultReplyTo` before delivery.
+- `EmailService.send(...)` rejects blank `to` recipients before handoff so transports never receive an empty delivery target.
+- `EmailService.send(...)` and `EmailService.sendNotification(...)` honor an already-aborted `AbortSignal` before template rendering or transport handoff.
 - `EmailService.send(...)` preserves `accepted`, `pending`, and `rejected` recipients separately so partial provider failures stay caller-visible.
 - `EmailService.sendMany(...)` is fail-fast by default; pass `continueOnError: true` to collect failures in a batch result.
 - `EmailService.createPlatformStatusSnapshot()` exposes lifecycle, readiness, health, and transport ownership details for diagnostics.
-- The service initializes the configured transport during module bootstrap and closes factory-owned resources during application shutdown.
+- The service initializes the configured transport during module bootstrap and, when `verifyOnModuleInit: true`, delivery waits until bootstrap verification has completed successfully before transport handoff.
+- Rejected `forRootAsync(...)` option factories are not memoized permanently; the next provider resolution can retry configuration lookup.
+- Once shutdown starts, `EmailService.send(...)` and `EmailService.sendNotification(...)` fail with `EmailLifecycleError` instead of reusing or lazily creating transports; any in-flight factory-owned transport creation is awaited and closed by shutdown.
+- Transport `verify()` and `close()` provider errors are preserved as the `cause` of lifecycle failures for diagnostics.
 - Module options are trimmed and normalized before provider wiring, including sender defaults, notification channel names, and transport factory ownership.
 - The package never reads `process.env` directly. All configuration must enter through explicit options or DI.
 
@@ -209,6 +216,7 @@ Behavioral contract notes:
 
 - `EmailChannel` treats any `pending` or `rejected` recipients as a failed notification dispatch instead of reporting the delivery as successful.
 - `EmailService.sendNotification(...)` merges rendered template output with payload and notification metadata; payload fields override notification fallbacks.
+- Template rendering receives notification `payload`, `metadata`, `locale`, `subject`, and `template`; payload `text`, `html`, and notification `subject` override rendered fallbacks.
 
 ### Queue-backed bulk delivery
 
@@ -306,6 +314,7 @@ These limitations are part of the package contract so transport selection, templ
 
 - `createEmailPlatformStatusSnapshot(...)`
 - `EmailConfigurationError`
+- `EmailLifecycleError`: thrown by lifecycle-gated delivery, transport initialization or verification, and owned-resource shutdown failures. Catch this error when sends can race with application teardown.
 - `EmailMessageValidationError`
 
 ### Node-only subpath

package/dist/errors.d.ts

@@ -10,4 +10,10 @@ export declare class EmailConfigurationError extends Error {
 export declare class EmailMessageValidationError extends Error {
     constructor(message: string);
 }
+/**
+ * Thrown when email delivery is requested after the service lifecycle has started shutting down.
+ */
+export declare class EmailLifecycleError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD"}

package/dist/errors.js

@@ -16,4 +16,14 @@ export class EmailMessageValidationError extends Error {
     super(message);
     this.name = 'EmailMessageValidationError';
   }
+}
+
+/**
+ * Thrown when email delivery is requested after the service lifecycle has started shutting down.
+ */
+export class EmailLifecycleError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'EmailLifecycleError';
+  }
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { EmailConfigurationError, EmailMessageValidationError, } from './errors.js';
+export { EmailConfigurationError, EmailLifecycleError, EmailMessageValidationError, } from './errors.js';
 export { EmailChannel } from './channel.js';
 export { EmailModule } from './module.js';
 export { EmailService } from './service.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,iCAAiC,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC7G,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,gCAAgC,EAChC,wBAAwB,EACxB,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,iCAAiC,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC7G,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,gCAAgC,EAChC,wBAAwB,EACxB,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,4 @@
-export { EmailConfigurationError, EmailMessageValidationError } from './errors.js';
+export { EmailConfigurationError, EmailLifecycleError, EmailMessageValidationError } from './errors.js';
 export { EmailChannel } from './channel.js';
 export { EmailModule } from './module.js';
 export { EmailService } from './service.js';

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMhE,OAAO,KAAK,EAGV,uBAAuB,EAGvB,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AAyHpB,kFAAkF;AAClF,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;QAgBI;IACJ,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU;IAIvD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU;CAGlE"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAMhE,OAAO,KAAK,EAGV,uBAAuB,EAGvB,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AA8HpB,kFAAkF;AAClF,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;QAgBI;IACJ,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU;IAIvD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU;CAGlE"}

package/dist/module.js

@@ -85,7 +85,10 @@ function buildEmailModuleAsync(options) {
   let cachedResult;
   const memoizedFactory = (...deps) => {
     if (!cachedResult) {
-      cachedResult = Promise.resolve(factory(...deps)).then(resolved => normalizeEmailModuleOptions(resolved));
+      cachedResult = Promise.resolve(factory(...deps)).then(resolved => normalizeEmailModuleOptions(resolved)).catch(error => {
+        cachedResult = undefined;
+        throw error;
+      });
     }
     return cachedResult;
   };

package/dist/node/nodemailer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodemailer.d.ts","sourceRoot":"","sources":["../../src/node/nodemailer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAC9C,OAAO,KAAK,aAAa,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAEV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB,4FAA4F;AAC5F,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,+BAA+B;IAC9C,iFAAiF;IACjF,WAAW,EAAE,qBAAqB,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sCAAsC;IACrD,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,iGAAiG;IACjG,IAAI,EAAE,aAAa,CAAC,OAAO,GAAG,MAAM,CAAC;CACtC;AAoDD;;;;;;GAMG;AACH,qBAAa,wBAAyB,YAAW,cAAc;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,qBAAqB;IAE/D;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAa5G;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,+BAA+B,GAAG,cAAc,CAEvG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,sCAAsC,GAC9C,qBAAqB,CAQvB"}
+{"version":3,"file":"nodemailer.d.ts","sourceRoot":"","sources":["../../src/node/nodemailer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAC9C,OAAO,KAAK,aAAa,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAEV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAGrB,4FAA4F;AAC5F,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,+BAA+B;IAC9C,iFAAiF;IACjF,WAAW,EAAE,qBAAqB,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sCAAsC;IACrD,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,iGAAiG;IACjG,IAAI,EAAE,aAAa,CAAC,OAAO,GAAG,MAAM,CAAC;CACtC;AAiED;;;;;;GAMG;AACH,qBAAa,wBAAyB,YAAW,cAAc;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,qBAAqB;IAE/D;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAa5G;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,+BAA+B,GAAG,cAAc,CAEvG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,sCAAsC,GAC9C,qBAAqB,CAQvB"}

package/dist/node/nodemailer.js

@@ -1,5 +1,6 @@
 import { Buffer } from 'node:buffer';
 import nodemailer from 'nodemailer';
+import { EmailMessageValidationError } from '../errors.js';
 
 /** Node-only Nodemailer transporter type used by the explicit `@fluojs/email/node` seam. */
 
@@ -21,8 +22,21 @@ import nodemailer from 'nodemailer';
  * isolated to the Node-only subpath.
  */
 
+function assertSafeAddressPart(value, label) {
+  if (/\r|\n/.test(value)) {
+    throw new EmailMessageValidationError(`Nodemailer ${label} must not contain newline characters.`);
+  }
+}
 function createAddress(address) {
-  return address.name ? `${address.name} <${address.address}>` : address.address;
+  assertSafeAddressPart(address.address, 'address');
+  if (address.name) {
+    assertSafeAddressPart(address.name, 'display name');
+    return {
+      address: address.address,
+      name: address.name
+    };
+  }
+  return address.address;
 }
 function createAddressList(addresses) {
   if (addresses.length === 0) {

package/dist/service.d.ts

@@ -11,11 +11,13 @@ import type { Email, EmailMessage, EmailNotificationDispatchRequest, EmailSendBa
 export declare class EmailService implements Email, OnModuleInit, OnApplicationShutdown {
     private readonly options;
     private lifecycleState;
+    private bootstrapPromise;
     private resolvedTransport;
     private transportPromise;
     constructor(options: NormalizedEmailModuleOptions);
     onApplicationShutdown(): Promise<void>;
     onModuleInit(): Promise<void>;
+    private startTransport;
     /**
      * Creates a platform status snapshot for the active email transport wiring.
      *
@@ -75,6 +77,10 @@ export declare class EmailService implements Email, OnModuleInit, OnApplicationS
      */
     sendNotification(notification: EmailNotificationDispatchRequest, options?: EmailSendOptions): Promise<EmailSendResult>;
     private ensureTransport;
+    private ensureReadyForDelivery;
+    private getLifecycleState;
+    private assertCanCreateOrUseTransport;
+    private assertCanDeliver;
     private normalizeMessage;
     private renderNotification;
 }

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAM3E,OAAO,KAAK,EACV,KAAK,EAGL,YAAY,EACZ,gCAAgC,EAC9B,oBAAoB,EAEpB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EAKf,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AA2CtB;;;;;;;GAOG;AACH,qBACa,YAAa,YAAW,KAAK,EAAE,YAAY,EAAE,qBAAqB;IAKjE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,cAAc,CAAmF;IACzG,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,gBAAgB,CAAsC;gBAEjC,OAAO,EAAE,4BAA4B;IAE5D,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAetC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBnC;;;;OAIG;IACH,4BAA4B;IAY5B;;;;;;;;;;;;;;;;;OAiBG;IACG,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAoB3F;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA6BpH;;;;;;;;;;;;;;;;;OAiBG;IACG,gBAAgB,CACpB,YAAY,EAAE,gCAAgC,EAC9C,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC;YA0Bb,eAAe;IAe7B,OAAO,CAAC,gBAAgB;YAuBV,kBAAkB;CAejC"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAM3E,OAAO,KAAK,EACV,KAAK,EAGL,YAAY,EACZ,gCAAgC,EAChC,oBAAoB,EAEpB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EAKf,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AAqEpB;;;;;;;GAOG;AACH,qBACa,YAAa,YAAW,KAAK,EAAE,YAAY,EAAE,qBAAqB;IAMjE,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,cAAc,CAAyC;IAC/D,OAAO,CAAC,gBAAgB,CAA4B;IACpD,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,gBAAgB,CAAsC;gBAEjC,OAAO,EAAE,4BAA4B;IAE5D,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBtC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;YAgBrB,cAAc;IAiC5B;;;;OAIG;IACH,4BAA4B;IAY5B;;;;;;;;;;;;;;;;;OAiBG;IACG,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B3F;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA6BpH;;;;;;;;;;;;;;;;;OAiBG;IACG,gBAAgB,CACpB,YAAY,EAAE,gCAAgC,EAC9C,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC;YA+Bb,eAAe;YAiBf,sBAAsB;IAwBpC,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,6BAA6B;IAMrC,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,gBAAgB;YAuBV,kBAAkB;CAkBjC"}

package/dist/service.js

@@ -6,7 +6,7 @@ function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.descrip
 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 { DEFAULT_EMAIL_QUEUE_WORKER_OPTIONS } from './constants.js';
-import { EmailMessageValidationError } from './errors.js';
+import { EmailLifecycleError, EmailMessageValidationError } from './errors.js';
 import { createEmailPlatformStatusSnapshot } from './status.js';
 import { EMAIL_OPTIONS } from './tokens.js';
 function normalizeAddress(address) {
@@ -35,10 +35,29 @@ function createAbortError() {
   error.name = 'AbortError';
   return error;
 }
+function assertNotAborted(signal) {
+  if (signal?.aborted) {
+    throw createAbortError();
+  }
+}
+function createLifecycleError(message, cause) {
+  return new EmailLifecycleError(message, {
+    cause
+  });
+}
+function createDeliveryLifecycleError(state) {
+  return new EmailLifecycleError(`Email delivery cannot start while the service lifecycle is ${state}.`);
+}
+function isShutdownLifecycleState(state) {
+  return state === 'stopping' || state === 'stopped';
+}
 function assertMessageContent(message) {
   if (message.to.length === 0) {
     throw new EmailMessageValidationError('Email messages require at least one recipient in `to`.');
   }
+  if (message.to.some(entry => entry.address.length === 0)) {
+    throw new EmailMessageValidationError('Email messages require non-empty recipients in `to`.');
+  }
   if (!message.from.address) {
     throw new EmailMessageValidationError('Email messages require a resolved `from` address.');
   }
@@ -61,6 +80,7 @@ class EmailService {
     [_EmailService, _initClass] = _applyDecs(this, [Inject(EMAIL_OPTIONS)], []).c;
   }
   lifecycleState = 'created';
+  bootstrapPromise;
   resolvedTransport;
   transportPromise;
   constructor(options) {
@@ -69,26 +89,52 @@ class EmailService {
   async onApplicationShutdown() {
     this.lifecycleState = 'stopping';
     try {
-      if (this.resolvedTransport && this.options.transport.ownsResources && this.resolvedTransport.close) {
-        await this.resolvedTransport.close();
+      const transport = this.resolvedTransport ?? (this.transportPromise ? await this.transportPromise : undefined);
+      if (transport && this.options.transport.ownsResources && transport.close) {
+        await transport.close();
       }
       this.lifecycleState = 'stopped';
-    } catch {
+    } catch (error) {
       this.lifecycleState = 'failed';
-      throw new Error('Email transport failed to close cleanly.');
+      throw createLifecycleError('Email transport failed to close cleanly.', error);
     }
   }
   async onModuleInit() {
+    if (this.bootstrapPromise) {
+      return this.bootstrapPromise;
+    }
+    this.bootstrapPromise = this.startTransport();
+    try {
+      await this.bootstrapPromise;
+    } finally {
+      if (this.lifecycleState === 'failed') {
+        this.bootstrapPromise = undefined;
+      }
+    }
+  }
+  async startTransport() {
+    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped') {
+      return;
+    }
     this.lifecycleState = 'starting';
     try {
       const transport = await this.ensureTransport();
+      if (this.lifecycleState !== 'starting') {
+        return;
+      }
       if (this.options.verifyOnModuleInit && transport.verify) {
         await transport.verify();
       }
+      if (this.lifecycleState !== 'starting') {
+        return;
+      }
       this.lifecycleState = 'ready';
-    } catch {
+    } catch (error) {
+      if (isShutdownLifecycleState(this.lifecycleState)) {
+        throw error;
+      }
       this.lifecycleState = 'failed';
-      throw new Error('Email transport failed to initialize.');
+      throw createLifecycleError('Email transport failed to initialize.', error);
     }
   }
 
@@ -128,12 +174,21 @@ class EmailService {
    * ```
    */
   async send(message, options = {}) {
-    if (options.signal?.aborted) {
-      throw createAbortError();
+    assertNotAborted(options.signal);
+    if (this.options.verifyOnModuleInit) {
+      await this.ensureReadyForDelivery();
+    } else {
+      this.assertCanDeliver();
     }
     const transport = await this.ensureTransport();
     const normalized = this.normalizeMessage(message);
     assertMessageContent(normalized);
+    assertNotAborted(options.signal);
+    if (this.options.verifyOnModuleInit) {
+      await this.ensureReadyForDelivery();
+    } else {
+      this.assertCanDeliver();
+    }
     const result = await transport.send(normalized, options);
     return {
       accepted: result.accepted ?? [],
@@ -202,8 +257,11 @@ class EmailService {
    * ```
    */
   async sendNotification(notification, options = {}) {
+    assertNotAborted(options.signal);
+    this.assertCanDeliver();
     const payload = notification.payload;
-    const rendered = await this.renderNotification(notification);
+    const rendered = await this.renderNotification(notification, options.signal);
+    assertNotAborted(options.signal);
     return this.send({
       attachments: payload.attachments,
       bcc: payload.bcc,
@@ -225,6 +283,7 @@ class EmailService {
     }, options);
   }
   async ensureTransport() {
+    this.assertCanCreateOrUseTransport();
     if (this.resolvedTransport) {
       return this.resolvedTransport;
     }
@@ -236,6 +295,34 @@ class EmailService {
     }
     return this.transportPromise;
   }
+  async ensureReadyForDelivery() {
+    this.assertCanDeliver();
+    if (!this.options.verifyOnModuleInit) {
+      return;
+    }
+    if (this.lifecycleState === 'ready') {
+      return;
+    }
+    if (this.lifecycleState === 'created' || this.lifecycleState === 'starting') {
+      await this.onModuleInit();
+    }
+    this.assertCanDeliver();
+    const state = this.getLifecycleState();
+    if (state !== 'ready') {
+      throw createDeliveryLifecycleError(state);
+    }
+  }
+  getLifecycleState() {
+    return this.lifecycleState;
+  }
+  assertCanCreateOrUseTransport() {
+    if (this.lifecycleState === 'stopping' || this.lifecycleState === 'stopped' || this.lifecycleState === 'failed') {
+      throw createDeliveryLifecycleError(this.lifecycleState);
+    }
+  }
+  assertCanDeliver() {
+    this.assertCanCreateOrUseTransport();
+  }
   normalizeMessage(message) {
     const from = message.from ? normalizeAddress(message.from) : this.options.defaultFrom;
     const replyTo = normalizeAddressList(message.replyTo);
@@ -256,10 +343,11 @@ class EmailService {
       to: normalizeAddressList(message.to)
     };
   }
-  async renderNotification(notification) {
+  async renderNotification(notification, signal) {
     if (!notification.template || !this.options.renderer) {
       return undefined;
     }
+    assertNotAborted(signal);
     return this.options.renderer.render({
       locale: notification.locale,
       metadata: notification.metadata,

package/package.json

@@ -10,7 +10,7 @@
     "queue",
     "mailer"
   ],
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -52,14 +52,14 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.4",
-    "@fluojs/di": "^1.0.0-beta.6",
-    "@fluojs/notifications": "^1.0.0-beta.3",
-    "@fluojs/runtime": "^1.0.0-beta.11"
+    "@fluojs/core": "^1.0.0-beta.6",
+    "@fluojs/notifications": "^1.0.0-beta.5",
+    "@fluojs/di": "^1.0.0-beta.8",
+    "@fluojs/runtime": "^1.0.0-beta.12"
   },
   "peerDependencies": {
     "nodemailer": "^6.10.1",
-    "@fluojs/queue": "^1.0.0-beta.4"
+    "@fluojs/queue": "^1.0.0-beta.5"
   },
   "peerDependenciesMeta": {
     "@fluojs/queue": {
@@ -72,7 +72,7 @@
   "devDependencies": {
     "@types/nodemailer": "^8.0.0",
     "vitest": "^3.2.4",
-    "@fluojs/queue": "^1.0.0-beta.4"
+    "@fluojs/queue": "^1.0.0-beta.5"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",