alepha 0.9.3 → 0.9.5

package/datetime.d.ts

@@ -1,6 +1,6 @@
 import * as _alepha_core1 from "alepha";
-import * as _alepha_core0 from "alepha";
 import { Alepha, Descriptor, KIND } from "alepha";
+import * as _alepha_logger0 from "alepha/logger";
 import dayjs, { Dayjs, ManipulateType } from "dayjs";
 import dayjsDuration from "dayjs/plugin/duration.js";
 
@@ -11,7 +11,7 @@ type Duration = dayjsDuration.Duration;
 type DurationLike = number | dayjsDuration.Duration | [number, ManipulateType];
 declare class DateTimeProvider {
   protected alepha: Alepha;
-  protected log: _alepha_core1.Logger;
+  protected log: _alepha_logger0.Logger;
   protected ref: DateTime | null;
   protected readonly timeouts: Timeout[];
   protected readonly intervals: Interval[];
@@ -103,7 +103,6 @@ interface Timeout {
   callback: () => void;
   clear: () => void;
 }
-//# sourceMappingURL=DateTimeProvider.d.ts.map
 //#endregion
 //#region src/descriptors/$interval.d.ts
 /**
@@ -130,12 +129,9 @@ declare class IntervalDescriptor extends Descriptor<IntervalDescriptorOptions> {
   called: number;
   protected onInit(): void;
 }
-//# sourceMappingURL=$interval.d.ts.map
 //#endregion
 //#region src/index.d.ts
-declare const AlephaDateTime: _alepha_core0.Service<_alepha_core0.Module>;
-//# sourceMappingURL=index.d.ts.map
-
+declare const AlephaDateTime: _alepha_core1.Service<_alepha_core1.Module>;
 //#endregion
 export { $interval, AlephaDateTime, DateTime, DateTimeApi, DateTimeProvider, Duration, DurationLike, Interval, IntervalDescriptor, IntervalDescriptorOptions, Timeout };
 //# sourceMappingURL=index.d.ts.map

package/email.cjs

@@ -0,0 +1,8 @@
+'use strict';
+var m = require('@alepha/email');
+Object.keys(m).forEach(function (k) {
+	if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function () { return m[k]; }
+	});
+});

package/email.d.ts

@@ -0,0 +1,246 @@
+import * as _alepha_core1 from "alepha";
+import { Descriptor, KIND, Service, Static, TSchema } from "alepha";
+import * as _alepha_logger0 from "alepha/logger";
+import { Transporter } from "nodemailer";
+
+//#region src/providers/EmailProvider.d.ts
+/**
+ * Email provider interface.
+ *
+ * All methods are asynchronous and return promises.
+ */
+declare abstract class EmailProvider {
+  /**
+   * Send an email.
+   *
+   * @param to The recipient email address.
+   * @param subject The email subject.
+   * @param body The email body (HTML content).
+   *
+   * @return Promise that resolves when the email is sent.
+   */
+  abstract send(to: string, subject: string, body: string): Promise<void>;
+}
+//#endregion
+//#region src/providers/MemoryEmailProvider.d.ts
+interface EmailRecord {
+  to: string;
+  subject: string;
+  body: string;
+  sentAt: Date;
+}
+declare class MemoryEmailProvider implements EmailProvider {
+  protected readonly log: _alepha_logger0.Logger;
+  protected emails: EmailRecord[];
+  send(to: string, subject: string, body: string): Promise<void>;
+  /**
+   * Get all emails sent through this provider (for testing purposes).
+   */
+  getEmails(): EmailRecord[];
+  /**
+   * Clear all stored emails (for testing purposes).
+   */
+  clearEmails(): void;
+  /**
+   * Get the last email sent (for testing purposes).
+   */
+  getLastEmail(): EmailRecord | undefined;
+}
+//#endregion
+//#region src/services/TemplateService.d.ts
+/**
+ * Minimal template service with Handlebars-like syntax for email templating.
+ * Supports simple variable substitution with {{variableName}} syntax.
+ */
+declare class TemplateService {
+  /**
+   * Compile a template string with the provided values.
+   *
+   * @param template Template string with {{variableName}} placeholders
+   * @param values Object containing values to substitute
+   * @returns Compiled template string with values substituted
+   *
+   * @example
+   * ```ts
+   * const service = new TemplateService();
+   * const result = service.compile("Hello {{name}}!", { name: "John" });
+   * // Result: "Hello John!"
+   * ```
+   */
+  compile(template: string, values: Record<string, unknown>): string;
+  /**
+   * Validate that all required template variables are provided.
+   *
+   * @param template Template string
+   * @param values Values object
+   * @returns Array of missing variable names
+   */
+  validateTemplate(template: string, values: Record<string, unknown>): string[];
+  /**
+   * Extract all variable names from a template.
+   *
+   * @param template Template string
+   * @returns Array of variable names found in the template
+   */
+  extractVariables(template: string): string[];
+}
+//#endregion
+//#region src/descriptors/$email.d.ts
+/**
+ * Create an email descriptor for sending templated emails.
+ *
+ * @example
+ * ```ts
+ * import { $email } from "alepha/email";
+ * import { t } from "alepha";
+ *
+ * class App {
+ *   welcome = $email({
+ *     subject: "Welcome {{name}}!",
+ *     body: "<h1>Welcome {{name}}!</h1><p>Your role is {{role}}.</p>",
+ *     schema: t.object({
+ *       name: t.string(),
+ *       role: t.string()
+ *     })
+ *   });
+ *
+ *   async sendWelcome(userEmail: string, name: string, role: string) {
+ *     await this.welcome.send(userEmail, { name, role });
+ *   }
+ * }
+ * ```
+ */
+declare const $email: {
+  <T extends TSchema>(options: EmailDescriptorOptions<T>): EmailDescriptor<T>;
+  [KIND]: typeof EmailDescriptor;
+};
+interface EmailDescriptorOptions<T extends TSchema> {
+  /**
+   * Email subject template. Supports {{variableName}} syntax.
+   */
+  subject: string;
+  /**
+   * Email body template (HTML content). Supports {{variableName}} syntax.
+   */
+  body: string;
+  /**
+   * Schema defining the structure of template variables.
+   */
+  schema: T;
+  /**
+   * Optional name of the email template.
+   * @default Descriptor key
+   */
+  name?: string;
+  /**
+   * Optional description of the email template.
+   */
+  description?: string;
+  /**
+   * Email provider to use. If not provided, the default provider will be used.
+   */
+  provider?: Service<EmailProvider> | "memory";
+}
+declare class EmailDescriptor<T extends TSchema> extends Descriptor<EmailDescriptorOptions<T>> {
+  protected readonly log: _alepha_logger0.Logger;
+  protected readonly templateService: TemplateService;
+  readonly provider: EmailProvider | MemoryEmailProvider;
+  get name(): string;
+  /**
+   * Send an email using the template with the provided values.
+   *
+   * @param to Recipient email address
+   * @param values Template variable values
+   */
+  send(to: string, values: Static<T>): Promise<void>;
+  protected $provider(): EmailProvider | MemoryEmailProvider;
+}
+//#endregion
+//#region src/errors/EmailError.d.ts
+declare class EmailError extends Error {
+  constructor(message: string, cause?: Error);
+}
+//#endregion
+//#region src/providers/LocalEmailProvider.d.ts
+interface LocalEmailProviderOptions {
+  /**
+   * Directory to save email files.
+   * @default "email" (relative to project root)
+   */
+  directory?: string;
+}
+declare class LocalEmailProvider implements EmailProvider {
+  protected readonly log: _alepha_logger0.Logger;
+  protected readonly directory: string;
+  constructor(options?: LocalEmailProviderOptions);
+  send(to: string, subject: string, body: string): Promise<void>;
+  protected createEmailHtml(to: string, subject: string, body: string): string;
+  protected escapeHtml(text: string): string;
+}
+//#endregion
+//#region src/providers/NodemailerEmailProvider.d.ts
+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;
+  /**
+   * Additional nodemailer options.
+   */
+  options?: {
+    pool?: boolean;
+    maxConnections?: number;
+    maxMessages?: number;
+    rateDelta?: number;
+    rateLimit?: number;
+  };
+}
+declare class NodemailerEmailProvider implements EmailProvider {
+  protected readonly env: {
+    EMAIL_HOST: string;
+    EMAIL_PORT: number;
+    EMAIL_USER: string;
+    EMAIL_PASS: string;
+    EMAIL_FROM: string;
+    EMAIL_SECURE: boolean;
+  };
+  protected readonly log: _alepha_logger0.Logger;
+  protected transporter: Transporter;
+  protected fromAddress: string;
+  readonly options: NodemailerEmailProviderOptions;
+  constructor();
+  send(to: string, subject: string, body: string): Promise<void>;
+  protected createTransporter(): Transporter;
+  /**
+   * Verify the connection to the email server.
+   */
+  verify(): Promise<boolean>;
+  /**
+   * Close the transporter connection.
+   */
+  close(): void;
+  protected readonly onStart: _alepha_core1.HookDescriptor<"start">;
+  protected readonly onStop: _alepha_core1.HookDescriptor<"stop">;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Provides email sending capabilities for Alepha applications with multiple provider backends.
+ *
+ * The email module enables declarative email sending through the `$email` descriptor, allowing you to send
+ * emails through different providers: memory (for testing), local file system, or SMTP via Nodemailer.
+ * It supports HTML email content and automatic provider selection based on environment configuration.
+ *
+ * @see {@link EmailProvider}
+ * @module alepha.email
+ */
+declare const AlephaEmail: _alepha_core1.Service<_alepha_core1.Module>;
+//#endregion
+export { $email, AlephaEmail, EmailDescriptor, EmailDescriptorOptions, EmailError, EmailProvider, EmailRecord, LocalEmailProvider, LocalEmailProviderOptions, MemoryEmailProvider, NodemailerEmailProvider, NodemailerEmailProviderOptions, TemplateService };
+//# sourceMappingURL=index.d.ts.map

package/email.js

@@ -0,0 +1 @@
+export * from '@alepha/email'

package/file.d.ts

@@ -35,7 +35,6 @@ declare const streamToBuffer: (streamLike: StreamLike) => Promise<Buffer>;
  */
 declare const bufferToArrayBuffer: (buffer: Buffer) => ArrayBuffer;
 declare const isReadableStream: (obj: unknown) => obj is NodeJS.ReadableStream;
-//# sourceMappingURL=createFile.d.ts.map
 //#endregion
 //#region src/helpers/getContentType.d.ts
 /**
@@ -49,8 +48,6 @@ declare const mimeMap: Record<string, string>;
  * @see {mimeMap}
  */
 declare const getContentType: (filename: string) => string;
-//# sourceMappingURL=getContentType.d.ts.map
-
 //#endregion
 export { bufferToArrayBuffer, createFile, createFileFromBuffer, createFileFromStream, createFileFromUrl, createFileFromWebFile, getContentType, isReadableStream, mimeMap, streamToBuffer };
 //# sourceMappingURL=index.d.ts.map

package/lock/redis.d.ts

@@ -1,16 +1,15 @@
 import * as _alepha_core0 from "alepha";
-import { Logger } from "alepha";
 import { LockProvider } from "alepha/lock";
+import * as _alepha_logger0 from "alepha/logger";
 import { RedisProvider } from "alepha/redis";
 
 //#region src/providers/RedisLockProvider.d.ts
 declare class RedisLockProvider implements LockProvider {
-  protected readonly log: Logger;
+  protected readonly log: _alepha_logger0.Logger;
   protected readonly redisProvider: RedisProvider;
   set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
   del(...keys: string[]): Promise<void>;
 }
-//# sourceMappingURL=RedisLockProvider.d.ts.map
 //#endregion
 //#region src/index.d.ts
 /**
@@ -20,8 +19,6 @@ declare class RedisLockProvider implements LockProvider {
  * @module alepha.lock.redis
  */
 declare const AlephaLockRedis: _alepha_core0.Service<_alepha_core0.Module>;
-//# sourceMappingURL=index.d.ts.map
-
 //#endregion
 export { AlephaLockRedis, RedisLockProvider };
 //# sourceMappingURL=index.d.ts.map