alepha 0.14.4 → 0.15.0

package/src/email/providers/LocalEmailProvider.spec.ts

@@ -1,42 +1,27 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
+import { Alepha } from "alepha";
+import { FileSystemProvider, MemoryFileSystemProvider } from "alepha/file";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { EmailError } from "../errors/EmailError.ts";
-import { LocalEmailProvider } from "../providers/LocalEmailProvider.ts";
+import {
+  LocalEmailProvider,
+  localEmailOptions,
+} from "../providers/LocalEmailProvider.ts";
 
-// Mock fs and path modules
-vi.mock("node:fs/promises");
-vi.mock("node:path");
+// ---------------------------------------------------------------------------------------------------------------------
 
-// Mock logger
-vi.mock("alepha/logger", () => ({
-  $logger: () => ({
-    debug: vi.fn(),
-    info: vi.fn(),
-    error: vi.fn(),
-  }),
-}));
-
-const mockedFs = vi.mocked(fs);
-const mockedPath = vi.mocked(path);
+const DEFAULT_DIRECTORY = localEmailOptions.options.default.directory;
 
 describe("LocalEmailProvider", () => {
-  let provider: LocalEmailProvider;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    // Setup default path.join mock
-    mockedPath.join.mockImplementation((...args) => args.join("/"));
-  });
-
   describe("send", () => {
-    beforeEach(() => {
-      provider = new LocalEmailProvider({ directory: "test-emails" });
-    });
-
     test("should successfully send email to local file", async () => {
-      mockedFs.mkdir.mockResolvedValue(undefined);
-      mockedFs.writeFile.mockResolvedValue();
+      const alepha = Alepha.create().with({
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      });
+
+      const provider = alepha.inject(LocalEmailProvider);
+      const memoryFs = alepha.inject(MemoryFileSystemProvider);
+      await alepha.start();
 
       const to = "test@example.com";
       const subject = "Test Subject";
@@ -48,19 +33,20 @@ describe("LocalEmailProvider", () => {
         body,
       });
 
-      expect(mockedFs.mkdir).toHaveBeenCalledWith("test-emails", {
-        recursive: true,
-      });
-      expect(mockedFs.writeFile).toHaveBeenCalledWith(
-        expect.stringContaining("test@example.com"),
-        expect.stringContaining(subject),
-        "utf8",
-      );
+      expect(memoryFs.writeFileCalls).toHaveLength(1);
+      expect(memoryFs.writeFileCalls[0].path).toContain("test@example.com");
+      expect(memoryFs.writeFileCalls[0].data).toContain(subject);
     });
 
     test("should create proper filename with sanitized email and timestamp", async () => {
-      mockedFs.mkdir.mockResolvedValue(undefined);
-      mockedFs.writeFile.mockResolvedValue();
+      const alepha = Alepha.create().with({
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      });
+
+      const provider = alepha.inject(LocalEmailProvider);
+      const memoryFs = alepha.inject(MemoryFileSystemProvider);
+      await alepha.start();
 
       const to = "user+test@example.com";
       const subject = "Test Subject";
@@ -76,17 +62,24 @@ describe("LocalEmailProvider", () => {
         body,
       });
 
-      expect(mockedPath.join).toHaveBeenCalledWith(
-        "test-emails",
+      expect(memoryFs.joinCalls).toHaveLength(1);
+      expect(memoryFs.joinCalls[0]).toEqual([
+        DEFAULT_DIRECTORY,
         "user_test@example.com+2023-01-01T12-00-00-000Z.html",
-      );
+      ]);
 
       vi.useRealTimers();
     });
 
     test("should sanitize special characters in email address", async () => {
-      mockedFs.mkdir.mockResolvedValue(undefined);
-      mockedFs.writeFile.mockResolvedValue();
+      const alepha = Alepha.create().with({
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      });
+
+      const provider = alepha.inject(LocalEmailProvider);
+      const memoryFs = alepha.inject(MemoryFileSystemProvider);
+      await alepha.start();
 
       const to = "user<script>@example.com";
       const subject = "Test Subject";
@@ -98,15 +91,21 @@ describe("LocalEmailProvider", () => {
         body,
       });
 
-      expect(mockedPath.join).toHaveBeenCalledWith(
-        "test-emails",
-        expect.stringMatching(/user_script_@example\.com\+.+\.html/),
+      expect(memoryFs.joinCalls).toHaveLength(1);
+      expect(memoryFs.joinCalls[0][1]).toMatch(
+        /user_script_@example\.com\+.+\.html/,
       );
     });
 
     test("should create proper HTML content", async () => {
-      mockedFs.mkdir.mockResolvedValue(undefined);
-      mockedFs.writeFile.mockResolvedValue();
+      const alepha = Alepha.create().with({
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      });
+
+      const provider = alepha.inject(LocalEmailProvider);
+      const memoryFs = alepha.inject(MemoryFileSystemProvider);
+      await alepha.start();
 
       const to = "test@example.com";
       const subject = "Test <Subject>";
@@ -118,8 +117,7 @@ describe("LocalEmailProvider", () => {
         body,
       });
 
-      const writeCall = mockedFs.writeFile.mock.calls[0];
-      const htmlContent = writeCall[1] as string;
+      const htmlContent = memoryFs.writeFileCalls[0].data;
 
       expect(htmlContent).toContain("<!DOCTYPE html>");
       expect(htmlContent).toContain("Test &lt;Subject&gt;"); // escaped subject
@@ -130,36 +128,17 @@ describe("LocalEmailProvider", () => {
       expect(htmlContent).toContain("Sent:");
     });
 
-    test("should throw EmailError when mkdir fails", async () => {
-      const mkdirError = new Error("Permission denied");
-      mockedFs.mkdir.mockRejectedValue(mkdirError);
-
-      const to = "test@example.com";
-      const subject = "Test Subject";
-      const body = "<p>Test body</p>";
+    test("should throw EmailError when writeFile fails", async () => {
+      const alepha = Alepha.create().with({
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      });
 
-      await expect(
-        provider.send({
-          to,
-          subject,
-          body,
-        }),
-      ).rejects.toThrow(EmailError);
-      await expect(
-        provider.send({
-          to,
-          subject,
-          body,
-        }),
-      ).rejects.toThrow(
-        "Failed to save email to local file: Permission denied",
-      );
-    });
+      const provider = alepha.inject(LocalEmailProvider);
+      const memoryFs = alepha.inject(MemoryFileSystemProvider);
+      await alepha.start();
 
-    test("should throw EmailError when writeFile fails", async () => {
-      mockedFs.mkdir.mockResolvedValue(undefined);
-      const writeError = new Error("Disk full");
-      mockedFs.writeFile.mockRejectedValue(writeError);
+      memoryFs.writeFileError = new Error("Disk full");
 
       const to = "test@example.com";
       const subject = "Test Subject";
@@ -172,6 +151,7 @@ describe("LocalEmailProvider", () => {
           body,
         }),
       ).rejects.toThrow(EmailError);
+
       await expect(
         provider.send({
           to,
@@ -182,8 +162,16 @@ describe("LocalEmailProvider", () => {
     });
 
     test("should handle non-Error exceptions", async () => {
-      mockedFs.mkdir.mockResolvedValue(undefined);
-      mockedFs.writeFile.mockRejectedValue("String error");
+      const alepha = Alepha.create().with({
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      });
+
+      const provider = alepha.inject(LocalEmailProvider);
+      const memoryFs = alepha.inject(MemoryFileSystemProvider);
+      await alepha.start();
+
+      memoryFs.writeFileError = "String error" as unknown as Error;
 
       const to = "test@example.com";
       const subject = "Test Subject";
@@ -196,6 +184,7 @@ describe("LocalEmailProvider", () => {
           body,
         }),
       ).rejects.toThrow(EmailError);
+
       await expect(
         provider.send({
           to,
@@ -204,11 +193,39 @@ describe("LocalEmailProvider", () => {
         }),
       ).rejects.toThrow("Failed to save email to local file: String error");
     });
+
+    test("should handle multiple recipients", async () => {
+      const alepha = Alepha.create().with({
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      });
+
+      const provider = alepha.inject(LocalEmailProvider);
+      const memoryFs = alepha.inject(MemoryFileSystemProvider);
+      await alepha.start();
+
+      await provider.send({
+        to: ["user1@example.com", "user2@example.com"],
+        subject: "Broadcast",
+        body: "<p>Hello all</p>",
+      });
+
+      expect(memoryFs.writeFileCalls).toHaveLength(2);
+      expect(memoryFs.writeFileCalls[0].path).toContain("user1@example.com");
+      expect(memoryFs.writeFileCalls[1].path).toContain("user2@example.com");
+    });
   });
 
   describe("createEmailHtml", () => {
-    beforeEach(() => {
-      provider = new LocalEmailProvider();
+    let provider: LocalEmailProvider;
+
+    beforeEach(async () => {
+      const alepha = Alepha.create().with({
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      });
+      provider = alepha.inject(LocalEmailProvider);
+      await alepha.start();
     });
 
     test("should create proper HTML structure", () => {
@@ -290,8 +307,15 @@ describe("LocalEmailProvider", () => {
   });
 
   describe("escapeHtml", () => {
-    beforeEach(() => {
-      provider = new LocalEmailProvider();
+    let provider: LocalEmailProvider;
+
+    beforeEach(async () => {
+      const alepha = Alepha.create().with({
+        provide: FileSystemProvider,
+        use: MemoryFileSystemProvider,
+      });
+      provider = alepha.inject(LocalEmailProvider);
+      await alepha.start();
     });
 
     test("should escape ampersands", () => {

package/src/email/providers/LocalEmailProvider.ts

@@ -1,24 +1,64 @@
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
+import { $atom, $hook, $inject, $use, type Static, t } from "alepha";
+import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import { EmailError } from "../errors/EmailError.ts";
 import type { EmailProvider, EmailSendOptions } from "./EmailProvider.ts";
 
-export interface LocalEmailProviderOptions {
-  /**
-   * Directory to save email files.
-   */
-  directory?: string;
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Local email provider configuration atom
+ */
+export const localEmailOptions = $atom({
+  name: "alepha.email.local.options",
+  schema: t.object({
+    directory: t.string({
+      description: "Directory path where email files will be stored",
+    }),
+  }),
+  default: {
+    directory: "node_modules/.alepha/emails",
+  },
+});
+
+export type LocalEmailProviderOptions = Static<typeof localEmailOptions.schema>;
+
+declare module "alepha" {
+  interface State {
+    [localEmailOptions.key]: LocalEmailProviderOptions;
+  }
 }
 
+// ---------------------------------------------------------------------------------------------------------------------
+
 export class LocalEmailProvider implements EmailProvider {
   protected readonly log = $logger();
-  protected readonly directory: string;
+  protected readonly fs = $inject(FileSystemProvider);
+  protected readonly options = $use(localEmailOptions);
 
-  constructor(options: LocalEmailProviderOptions = {}) {
-    this.directory = options.directory ?? "node_modules/.alepha/emails";
+  protected get directory(): string {
+    return this.options.directory;
   }
 
+  protected onStart = $hook({
+    on: "start",
+    handler: async () => {
+      try {
+        await this.fs.mkdir(this.directory, { recursive: true });
+        this.log.info("Email directory OK", {
+          directory: this.directory,
+        });
+      } catch (error) {
+        const message = `Failed to create email directory: ${error instanceof Error ? error.message : String(error)}`;
+        this.log.error(message, { directory: this.directory });
+        throw new EmailError(
+          message,
+          error instanceof Error ? error : undefined,
+        );
+      }
+    },
+  });
+
   public async send(options: EmailSendOptions): Promise<void> {
     const { to, subject, body } = options;
 
@@ -29,15 +69,12 @@ export class LocalEmailProvider implements EmailProvider {
     });
 
     try {
-      // Ensure directory exists
-      await fs.mkdir(this.directory, { recursive: true });
-
       // Create filename: emailcontact+date
       const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
       for (const recipient of Array.isArray(to) ? to : [to]) {
         const sanitizedEmail = recipient.replace(/[^a-zA-Z0-9@.-]/g, "_");
         const filename = `${sanitizedEmail}+${timestamp}.html`;
-        const filepath = path.join(this.directory, filename);
+        const filepath = this.fs.join(this.directory, filename);
 
         // Create HTML content
         const htmlContent = this.createEmailHtml({
@@ -47,7 +84,7 @@ export class LocalEmailProvider implements EmailProvider {
         });
 
         // Write to file
-        await fs.writeFile(filepath, htmlContent, "utf8");
+        await this.fs.writeFile(filepath, htmlContent);
 
         this.log.info("Email saved to local file", { filepath, to, subject });
       }

package/src/email/providers/NodemailerEmailProvider.ts

@@ -1,69 +1,173 @@
-import { $env, $hook, t } from "alepha";
+import { $atom, $env, $hook, $use, type Static, t } from "alepha";
 import { $logger } from "alepha/logger";
 import type { Transporter } from "nodemailer";
 import nodemailer from "nodemailer";
 import { EmailError } from "../errors/EmailError.ts";
 import type { EmailProvider, EmailSendOptions } from "./EmailProvider.ts";
 
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Environment variables for nodemailer configuration
+ */
 const envSchema = t.object({
-  EMAIL_HOST: t.text({
-    description: "SMTP server host",
-  }),
+  EMAIL_HOST: t.optional(
+    t.text({
+      description: "SMTP server host",
+    }),
+  ),
   EMAIL_PORT: t.number({
     default: 587,
     description: "SMTP server port",
   }),
-  EMAIL_USER: t.text({
-    description: "SMTP authentication username",
-  }),
-  EMAIL_PASS: t.text({
-    description: "SMTP authentication password",
-  }),
-  EMAIL_FROM: t.text({
-    description: "Default from email address",
-  }),
+  EMAIL_USER: t.optional(
+    t.text({
+      description: "SMTP authentication username",
+    }),
+  ),
+  EMAIL_PASS: t.optional(
+    t.text({
+      description: "SMTP authentication password",
+    }),
+  ),
+  EMAIL_FROM: t.optional(
+    t.text({
+      description: "Default from email address",
+    }),
+  ),
   EMAIL_SECURE: t.boolean({
     default: false,
     description: "Use secure connection (TLS)",
   }),
 });
 
-export interface NodemailerEmailProviderOptions {
-  /**
-   * Custom transporter configuration.
-   * If provided, will override environment variables.
-   */
-  transporter?: Transporter;
+// ---------------------------------------------------------------------------------------------------------------------
 
-  /**
-   * Custom from email address.
-   * If not provided, will use EMAIL_FROM from environment.
-   */
-  from?: string;
+/**
+ * Nodemailer connection pooling and rate limiting options
+ */
+export const nodemailerEmailOptions = $atom({
+  name: "alepha.email.nodemailer.options",
+  schema: t.object({
+    pool: t.optional(
+      t.boolean({
+        description: "Enable connection pooling",
+      }),
+    ),
+    maxConnections: t.optional(
+      t.number({
+        description: "Maximum number of connections in pool",
+      }),
+    ),
+    maxMessages: t.optional(
+      t.number({
+        description: "Maximum messages per connection",
+      }),
+    ),
+    rateDelta: t.optional(
+      t.number({
+        description: "Time in milliseconds between message sends",
+      }),
+    ),
+    rateLimit: t.optional(
+      t.number({
+        description: "Maximum number of messages per rateDelta",
+      }),
+    ),
+  }),
+  default: {},
+});
 
-  /**
-   * Additional nodemailer options.
-   */
-  options?: {
-    pool?: boolean;
-    maxConnections?: number;
-    maxMessages?: number;
-    rateDelta?: number;
-    rateLimit?: number;
-  };
+export type NodemailerEmailProviderOptions = Static<
+  typeof nodemailerEmailOptions.schema
+>;
+
+declare module "alepha" {
+  interface State {
+    [nodemailerEmailOptions.key]: NodemailerEmailProviderOptions;
+  }
 }
 
+// ---------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Email provider using Nodemailer for SMTP transport.
+ *
+ * Configuration is provided via environment variables:
+ * - EMAIL_HOST: SMTP server host
+ * - EMAIL_PORT: SMTP server port (default: 587)
+ * - EMAIL_USER: SMTP authentication username
+ * - EMAIL_PASS: SMTP authentication password
+ * - EMAIL_FROM: Default from email address
+ * - EMAIL_SECURE: Use secure connection (default: false)
+ *
+ * Advanced pooling/rate limiting options can be configured via atom:
+ * @see {@link nodemailerEmailOptions}
+ *
+ * @example
+ * ```typescript
+ * // Configure via environment variables
+ * // EMAIL_HOST=smtp.example.com
+ * // EMAIL_PORT=587
+ * // EMAIL_USER=user@example.com
+ * // EMAIL_PASS=secret
+ * // EMAIL_FROM=noreply@example.com
+ *
+ * // Optionally configure pooling via atom
+ * alepha.state.set(nodemailerEmailOptions.key, {
+ *   pool: true,
+ *   maxConnections: 5,
+ *   rateLimit: 10,
+ * });
+ * ```
+ */
 export class NodemailerEmailProvider implements EmailProvider {
   protected readonly env = $env(envSchema);
   protected readonly log = $logger();
-  protected transporter: Transporter;
-  protected fromAddress: string;
+  protected readonly options = $use(nodemailerEmailOptions);
+  protected transporter: Transporter | null = null;
 
-  public readonly options: NodemailerEmailProviderOptions = {};
+  protected get host(): string {
+    const host = this.env.EMAIL_HOST;
+    if (!host) {
+      throw new EmailError(
+        "Email host not configured. Set EMAIL_HOST env var.",
+      );
+    }
+    return host;
+  }
+
+  protected get port(): number {
+    return this.env.EMAIL_PORT;
+  }
+
+  protected get secure(): boolean {
+    return this.env.EMAIL_SECURE;
+  }
+
+  protected get user(): string | undefined {
+    return this.env.EMAIL_USER;
+  }
+
+  protected get pass(): string | undefined {
+    return this.env.EMAIL_PASS;
+  }
+
+  protected get fromAddress(): string {
+    const from = this.env.EMAIL_FROM;
+    if (!from) {
+      throw new EmailError(
+        "Email from address not configured. Set EMAIL_FROM env var.",
+      );
+    }
+    return from;
+  }
 
-  constructor() {
-    this.fromAddress = this.options.from ?? this.env.EMAIL_FROM;
-    this.transporter = this.createTransporter();
+  protected getTransporter(): Transporter {
+    if (!this.transporter) {
+      this.transporter = this.createTransporter();
+    }
+    return this.transporter;
   }
 
   public async send(options: EmailSendOptions): Promise<void> {
@@ -71,7 +175,7 @@ export class NodemailerEmailProvider implements EmailProvider {
     this.log.debug("Sending email via Nodemailer", { to, subject });
 
     try {
-      const result = await this.transporter.sendMail({
+      const result = await this.getTransporter().sendMail({
         from: this.fromAddress,
         to,
         subject,
@@ -92,26 +196,30 @@ export class NodemailerEmailProvider implements EmailProvider {
   }
 
   protected createTransporter(): Transporter {
-    if (this.options.transporter) {
-      return this.options.transporter;
-    }
-
     const transporterConfig = {
-      host: this.env.EMAIL_HOST,
-      port: this.env.EMAIL_PORT,
-      secure: this.env.EMAIL_SECURE,
-      auth: {
-        user: this.env.EMAIL_USER,
-        pass: this.env.EMAIL_PASS,
-      },
-      ...this.options.options,
+      host: this.host,
+      port: this.port,
+      secure: this.secure,
+      auth:
+        this.user && this.pass
+          ? {
+              user: this.user,
+              pass: this.pass,
+            }
+          : undefined,
+      pool: this.options.pool,
+      maxConnections: this.options.maxConnections,
+      maxMessages: this.options.maxMessages,
+      rateDelta: this.options.rateDelta,
+      rateLimit: this.options.rateLimit,
     };
 
     this.log.debug("Creating Nodemailer transporter", {
       host: transporterConfig.host,
       port: transporterConfig.port,
       secure: transporterConfig.secure,
-      user: transporterConfig.auth.user,
+      user: transporterConfig.auth?.user,
+      pool: transporterConfig.pool,
     });
 
     return nodemailer.createTransport(transporterConfig);
@@ -122,7 +230,7 @@ export class NodemailerEmailProvider implements EmailProvider {
    */
   public async verify(): Promise<boolean> {
     try {
-      await this.transporter.verify();
+      await this.getTransporter().verify();
       this.log.info("Email server connection verified");
       return true;
     } catch (error) {
@@ -135,7 +243,10 @@ export class NodemailerEmailProvider implements EmailProvider {
    * Close the transporter connection.
    */
   public close(): void {
-    this.transporter.close();
+    if (this.transporter) {
+      this.transporter.close();
+      this.transporter = null;
+    }
   }
 
   protected readonly onStart = $hook({

package/src/file/errors/FileError.ts

@@ -0,0 +1,7 @@
+export class FileError extends Error {
+  constructor(message: string, cause?: Error) {
+    super(message);
+    this.name = "FileError";
+    this.cause = cause;
+  }
+}