alepha 0.9.4 → 0.9.5

package/core.d.ts

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { TypeCheck } from "@sinclair/typebox/compiler";
 import * as TypeBoxValue from "@sinclair/typebox/value";
 import * as TypeBox from "@sinclair/typebox";
-import { ArrayOptions, FormatRegistry, IntegerOptions, NumberOptions, ObjectOptions, SchemaOptions, Static, Static as Static$1, StaticDecode, StaticEncode, StringOptions, TAny, TAny as TAny$1, TArray, TArray as TArray$1, TBoolean, TBoolean as TBoolean$1, TComposite, TInteger, TIntersect, TNull, TNumber, TNumber as TNumber$1, TObject, TObject as TObject$1, TOmit, TOptional, TOptionalWithFlag, TPartial, TPick, TProperties, TProperties as TProperties$1, TRecord, TRecord as TRecord$1, TSchema, TSchema as TSchema$1, TString, TString as TString$1, TUnion, TUnsafe, TypeGuard, UnsafeOptions } from "@sinclair/typebox";
+import { ArrayOptions, FormatRegistry, IntegerOptions, NumberOptions, ObjectOptions, SchemaOptions, Static, Static as Static$1, StaticDecode, StaticEncode, StringOptions, TAny, TAny as TAny$1, TArray, TArray as TArray$1, TBoolean, TBoolean as TBoolean$1, TComposite, TInteger, TIntersect, TNull, TNull as TNull$1, TNumber, TNumber as TNumber$1, TObject, TObject as TObject$1, TOmit, TOptional, TOptionalWithFlag, TPartial, TPick, TProperties, TProperties as TProperties$1, TRecord, TRecord as TRecord$1, TSchema, TSchema as TSchema$1, TString, TString as TString$1, TUnion, TUnion as TUnion$1, TUnsafe, TypeGuard, UnsafeOptions } from "@sinclair/typebox";
 import { ValueError } from "@sinclair/typebox/errors";
 import { Readable } from "node:stream";
 import { ReadableStream as ReadableStream$1 } from "node:stream/web";
@@ -118,47 +118,42 @@ declare const $inject: <T extends object>(type: Service<T>, opts?: InjectOptions
 declare class InjectDescriptor extends Descriptor {}
 interface InjectOptions<T extends object = any> {
   /**
-   * Ignore current existing instance.
-   */
-  skipCache?: boolean;
-  /**
-   * Don't store the instance in the registry.
+   * - 'transient' → Always a new instance on every inject. Zero caching.
+   * - 'singleton' → One instance per Alepha runtime (per-thread). Never disposed until Alepha shuts down. (default)
+   * - 'scoped' → One instance per AsyncLocalStorage context.
+   *   - A new scope is created when Alepha handles a request, a scheduled job, a queue worker task...
+   *   - You can also start a manual scope via alepha.context.run(() => { ... }).
+   *   - When the scope ends, the scoped registry is discarded.
+   *
+   * @default "singleton"
    */
-  skipRegistration?: boolean;
+  lifetime?: "transient" | "singleton" | "scoped";
   /**
    * Constructor arguments to pass when creating a new instance.
    */
   args?: ConstructorParameters<InstantiableClass<T>>;
   /**
-   * Parent service that requested the instance.
+   * Parent that requested the instance.
+   *
    * @internal
    */
   parent?: Service | null;
 }
 //#endregion
-//#region src/constants/OPTIONS.d.ts
-/**
- * Used for descriptors options.
- *
- * @internal
- */
-declare const OPTIONS: unique symbol;
-//#endregion
 //#region src/descriptors/$module.d.ts
 /**
- * Wrap services and descriptors into a module.
- *
- * Module is just a class.
- * You must attach a `name` to it.
+ * Wrap Services and Descriptors into a Module.
  *
- * It's recommended to use `project.module.submodule` format.
+ * - A module is just a Service extended {@link Module}.
+ * - You must attach a `name` to it.
+ * - Name must follow the pattern: `project.module.submodule`.
  *
  * @example
  * ```ts
  * import { $module } from "alepha";
  * import { MyService } from "./MyService.ts";
  *
- * // export MyService so it can be used everywhere
+ * // export MyService, so it can be used everywhere
  * export * from "./MyService.ts";
  *
  * export default $module({
@@ -168,9 +163,30 @@ declare const OPTIONS: unique symbol;
  * });
  * ```
  *
- * - Module is used for logging and other purposes.
- * - It's useful for large applications or libraries to group services and descriptors together.
- * - It's probably overkill for small applications.
+ * ## Why Modules?
+ *
+ * ### Logging
+ *
+ * By default, AlephaLogger will log the module name in the logs.
+ * This helps to identify where the logs are coming from.
+ *
+ * You can also set different log levels for different modules.
+ * It means you can set 'some.very.specific.module' to 'debug' and keep the rest of the application to 'info'.
+ *
+ * ### Modulith
+ *
+ * Force to structure your application in modules, even if it's a single deployable unit.
+ * It helps to keep a clean architecture and avoid monolithic applications.
+ *
+ * You can also use `MODULE_INCLUDE` and `MODULE_EXCLUDE` environment variables to load only specific modules.
+ *
+ * A strict mode is planned to enforce module boundaries. Throwing errors when a service from another module is injected.
+ *
+ * ### When not to use Modules?
+ *
+ * Small applications does not need modules. It's better to keep it simple.
+ * Modules are more useful when the application grows and needs to be structured.
+ * If we speak with `$actions`, a module should be used when you have more than 30 actions in a single module.
  */
 declare const $module: (options: ModuleDescriptorOptions) => Service<Module>;
 interface ModuleDescriptorOptions {
@@ -195,16 +211,25 @@ interface ModuleDescriptorOptions {
    */
   register?: (alepha: Alepha) => void;
 }
-interface Module {
-  [KIND]: "MODULE";
-  [OPTIONS]: ModuleDescriptorOptions;
-  register: (alepha: Alepha) => void;
+/**
+ * Base class for all modules.
+ */
+declare abstract class Module {
+  abstract readonly options: ModuleDescriptorOptions;
+  abstract register(alepha: Alepha): void;
+  static NAME_REGEX: RegExp;
+  /**
+   * Check if a Service is a Module.
+   */
+  static is(ctor: Service): boolean;
+  /**
+   * Get the Module of a Service.
+   */
+  static of(ctor: Service): Service<Module> | undefined;
 }
-type ServiceWithModule<T extends object = any> = T & {
+type WithModule<T extends object = any> = T & {
   [MODULE]?: Service;
 };
-declare const isModule: (value: unknown) => value is Module;
-declare const toModuleName: (name: string) => string;
 //#endregion
 //#region src/interfaces/Async.d.ts
 /**
@@ -364,6 +389,8 @@ declare class AlsProvider {
  * 		}
  * 	}
  * 	```
+ *
+ * 	@module alepha
  */
 declare class Alepha {
   /**
@@ -556,15 +583,27 @@ declare class Alepha {
     /**
      * Check if the entry is registered in the pending instantiation stack.
      *
-     * Default: true
+     * @default true
      */
     inStack?: boolean;
     /**
      * Check if the entry is registered in the container registry.
      *
-     * Default: true
+     * @default true
      */
     inRegistry?: boolean;
+    /**
+     * Check if the entry is registered in the substitutions.
+     *
+     * @default true
+     */
+    inSubstitutions?: boolean;
+    /**
+     * Where to look for registered services.
+     *
+     * @default this.registry
+     */
+    registry?: Map<Service, ServiceDefinition>;
   }): boolean;
   /**
    * Registers the specified service in the container.
@@ -596,14 +635,9 @@ declare class Alepha {
     default: ServiceEntry<T>;
   }): this;
   /**
-   * Get the instance of the specified service and apply some changes, depending on the options.
-   * - If the service is already registered, it will return the existing instance. (except if `skipCache` is true)
-   * - If the service is not registered, it will create a new instance and register it. (except if `skipRegistration` is true)
-   * - New instance can be created with custom constructor arguments. (`args` option)
-   *
-   * > This method is used by $inject() under the hood.
+   * Get an instance of the specified service from the container.
    *
-   * @return The instance of the specified class or type.
+   * @see {@link InjectOptions} for the available options.
    */
   inject<T extends object>(service: Service<T>, opts?: InjectOptions<T>): T;
   /**
@@ -660,6 +694,11 @@ declare class Alepha {
    * It uses the TypeBox library to validate the value against the schema.
    */
   parse<T extends TSchema$1>(schema: T, value?: any, opts?: {
+    /**
+     * Convert `null` to `undefined`
+     * @default true
+     */
+    convertNullToUndefined?: boolean;
     /**
      * Clone the value before parsing.
      * @default true
@@ -729,10 +768,6 @@ interface ServiceDefinition<T extends object = any> {
    * List of classes which use this class.
    */
   parents: Array<Service | null>;
-  /**
-   * If the service is provided by a module, the module definition.
-   */
-  module?: Service;
 }
 interface Env {
   [key: string]: string | boolean | number | undefined;
@@ -828,6 +863,14 @@ interface RunOptions {
   cluster?: boolean;
 }
 //#endregion
+//#region src/constants/OPTIONS.d.ts
+/**
+ * Used for descriptors options.
+ *
+ * @internal
+ */
+declare const OPTIONS: unique symbol;
+//#endregion
 //#region src/constants/PRIMITIVE.d.ts
 /**
  * Symbol to mark a value as a primitive.
@@ -993,25 +1036,31 @@ declare class AlephaError extends Error {
 }
 //#endregion
 //#region src/errors/AppNotStartedError.d.ts
-declare class AppNotStartedError extends Error {
+declare class AppNotStartedError extends AlephaError {
   readonly name = "AppNotStartedError";
   constructor();
 }
 //#endregion
 //#region src/errors/CircularDependencyError.d.ts
-declare class CircularDependencyError extends Error {
+declare class CircularDependencyError extends AlephaError {
   readonly name = "CircularDependencyError";
   constructor(provider: string, parents?: string[]);
 }
 //#endregion
 //#region src/errors/ContainerLockedError.d.ts
-declare class ContainerLockedError extends Error {
+declare class ContainerLockedError extends AlephaError {
   readonly name = "ContainerLockedError";
   constructor(message?: string);
 }
 //#endregion
+//#region src/errors/TooLateSubstitutionError.d.ts
+declare class TooLateSubstitutionError extends AlephaError {
+  readonly name = "TooLateSubstitutionError";
+  constructor(original: string, substitution: string);
+}
+//#endregion
 //#region src/errors/TypeBoxError.d.ts
-declare class TypeBoxError extends Error {
+declare class TypeBoxError extends AlephaError {
   readonly name = "TypeBoxError";
   readonly value: ValueError;
   constructor(value: ValueError);
@@ -1152,8 +1201,8 @@ declare class TypeProvider {
    * @param schema The schema to make nullable.
    * @param options The options for the schema.
    */
-  nullable<T extends TSchema$1>(schema: T, options?: ObjectOptions): TUnion<[TNull, T]>;
-  nullify: <T extends TSchema$1>(schema: T, options?: ObjectOptions) => TObject$1<TypeBox.Evaluate<TypeBox.TMappedFunctionReturnType<TypeBox.TIndexPropertyKeys<TypeBox.TKeyOf<T>>, TUnion<[TNull, TypeBox.TMappedResult<TypeBox.Evaluate<TypeBox.TIndexPropertyKeys<TypeBox.TKeyOf<T>> extends infer T_1 ? T_1 extends TypeBox.TIndexPropertyKeys<TypeBox.TKeyOf<T>> ? T_1 extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? /*elided*/any : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : {} : never : never>>]>, {}>>>;
+  nullable<T extends TSchema$1>(schema: T, options?: ObjectOptions): TUnion$1<[TNull$1, T]>;
+  nullify: <T extends TSchema$1>(schema: T, options?: ObjectOptions) => TObject$1<TypeBox.Evaluate<TypeBox.TMappedFunctionReturnType<TypeBox.TIndexPropertyKeys<TypeBox.TKeyOf<T>>, TUnion$1<[TNull$1, TypeBox.TMappedResult<TypeBox.Evaluate<TypeBox.TIndexPropertyKeys<TypeBox.TKeyOf<T>> extends infer T_1 ? T_1 extends TypeBox.TIndexPropertyKeys<TypeBox.TKeyOf<T>> ? T_1 extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? Right extends [infer Left extends PropertyKey, ...infer Right extends PropertyKey[]] ? /*elided*/any : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : { [_ in Left]: TypeBox.Assert<TypeBox.TIndexFromPropertyKey<T, Left>, TSchema$1> } : {} : never : never>>]>, {}>>>;
   /**
    * Map a schema to another schema.
    *
@@ -1272,7 +1321,6 @@ declare const isTypeFile: (value: TSchema$1) => value is TFile;
 declare const isFileLike: (value: any) => value is FileLike;
 type StreamLike = ReadableStream | ReadableStream$1 | Readable | NodeJS.ReadableStream;
 type TStream = TUnsafe<StreamLike>;
-declare const isTypeStream: (value: TSchema$1) => value is TStream;
 type TextLength = "short" | "long" | "rich";
 interface AlephaStringOptions extends StringOptions {
   size?: TextLength;
@@ -1297,5 +1345,5 @@ declare global {
  */
 declare const run: (entry: Alepha | Service | Array<Service>, opts?: RunOptions) => void;
 //#endregion
-export { $cursor, $env, $hook, $inject, $module, AbstractClass, Alepha, AlephaError, AlephaStringOptions, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, CircularDependencyError, ContainerLockedError, CursorDescriptor, Descriptor, DescriptorArgs, DescriptorConfig, DescriptorFactory, DescriptorFactoryLike, Env, FileLike, Hook, HookDescriptor, HookOptions, Hooks, InjectDescriptor, InjectOptions, InstantiableClass, KIND, LogLevel, LoggerInterface, MaybePromise, Module, ModuleDescriptorOptions, OPTIONS, PRIMITIVE, Service, ServiceEntry, ServiceSubstitution, ServiceWithModule, State, type Static, type StaticDecode, type StaticEncode, StreamLike, type TAny, type TArray, type TBoolean, TFile, type TNumber, type TObject, type TOptional, type TProperties, type TRecord, type TSchema, TStream, type TString, TextLength, TypeBox, TypeBoxError, TypeBoxValue, TypeGuard, TypeProvider, __alephaRef, createDescriptor, isEmail, isFileLike, isISODate, isISODateTime, isModule, isTypeFile, isTypeStream, isUUID, run, t, toModuleName };
+export { $cursor, $env, $hook, $inject, $module, AbstractClass, Alepha, AlephaError, AlephaStringOptions, AlsProvider, AppNotStartedError, Async, AsyncFn, AsyncLocalStorageData, CircularDependencyError, ContainerLockedError, CursorDescriptor, Descriptor, DescriptorArgs, DescriptorConfig, DescriptorFactory, DescriptorFactoryLike, Env, FileLike, Hook, HookDescriptor, HookOptions, Hooks, InjectDescriptor, InjectOptions, InstantiableClass, KIND, LogLevel, LoggerInterface, MaybePromise, Module, ModuleDescriptorOptions, OPTIONS, PRIMITIVE, Service, ServiceEntry, ServiceSubstitution, State, type Static, type StaticDecode, type StaticEncode, StreamLike, type TAny, type TArray, type TBoolean, TFile, type TNull, type TNumber, type TObject, type TOptional, type TProperties, type TRecord, type TSchema, TStream, type TString, type TUnion, TextLength, TooLateSubstitutionError, TypeBox, TypeBoxError, TypeBoxValue, TypeGuard, TypeProvider, WithModule, __alephaRef, createDescriptor, isEmail, isFileLike, isISODate, isISODateTime, isTypeFile, isUUID, run, t };
 //# 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'