alepha 0.9.5 → 0.10.0

package/email.d.ts

@@ -1,6 +1,6 @@
 import * as _alepha_core1 from "alepha";
 import { Descriptor, KIND, Service, Static, TSchema } from "alepha";
-import * as _alepha_logger0 from "alepha/logger";
+import * as _alepha_logger1 from "alepha/logger";
 import { Transporter } from "nodemailer";
 
 //#region src/providers/EmailProvider.d.ts
@@ -30,7 +30,7 @@ interface EmailRecord {
   sentAt: Date;
 }
 declare class MemoryEmailProvider implements EmailProvider {
-  protected readonly log: _alepha_logger0.Logger;
+  protected readonly log: _alepha_logger1.Logger;
   protected emails: EmailRecord[];
   send(to: string, subject: string, body: string): Promise<void>;
   /**
@@ -87,27 +87,109 @@ declare class TemplateService {
 //#endregion
 //#region src/descriptors/$email.d.ts
 /**
- * Create an email descriptor for sending templated emails.
+ * Creates an email descriptor for sending type-safe templated emails.
  *
- * @example
- * ```ts
- * import { $email } from "alepha/email";
- * import { t } from "alepha";
+ * The $email descriptor provides a powerful templating system for creating and sending emails
+ * with full type safety and validation. It supports multiple email providers, template variable
+ * validation, and automatic HTML rendering.
  *
- * 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()
- *     })
- *   });
+ * **Template Engine**
+ * - Simple {{variable}} syntax for dynamic content
+ * - Automatic template variable validation at runtime
+ * - Support for nested object properties in templates
+ * - HTML email support with rich formatting
  *
- *   async sendWelcome(userEmail: string, name: string, role: string) {
- *     await this.welcome.send(userEmail, { name, role });
- *   }
- * }
+ * **Type Safety**
+ * - Full TypeScript support with schema validation using TypeBox
+ * - Compile-time type checking for template variables
+ * - Runtime validation of email data before sending
+ * - Automatic type inference from schema definitions
+ *
+ * **Provider Flexibility**
+ * - Memory provider for development and testing
+ * - Support for SMTP, SendGrid, AWS SES, and other providers
+ * - Custom provider implementation for specialized services
+ * - Automatic fallback and error handling
+ *
+ * **Template Management**
+ * - Reusable email templates across your application
+ * - Centralized template configuration and maintenance
+ * - Template variable documentation through schemas
+ * - Easy testing and preview capabilities
+ *
+ * **Development Experience**
+ * - Clear error messages for missing template variables
+ * - Comprehensive logging for debugging email delivery
+ * - Memory provider captures emails for testing
+ * - Template validation before sending
+ *
+ * @example Welcome email template
+ * ```typescript
+ * const welcomeEmail = $email({
+ *   subject: "Welcome to {{companyName}}, {{firstName}}!",
+ *   body: `
+ *     <h1>Welcome {{firstName}} {{lastName}}!</h1>
+ *     <p>Thank you for joining {{companyName}}.</p>
+ *     <p>Your account role is: <strong>{{role}}</strong></p>
+ *     <p>Get started by visiting your <a href="{{dashboardUrl}}">dashboard</a>.</p>
+ *   `,
+ *   schema: t.object({
+ *     firstName: t.string(),
+ *     lastName: t.string(),
+ *     companyName: t.string(),
+ *     role: t.enum(["admin", "user", "manager"]),
+ *     dashboardUrl: t.string()
+ *   })
+ * });
+ *
+ * // Send with full type safety
+ * await welcomeEmail.send("user@example.com", {
+ *   firstName: "John",
+ *   lastName: "Doe",
+ *   companyName: "Acme Corp",
+ *   role: "user",
+ *   dashboardUrl: "https://app.acme.com/dashboard"
+ * });
+ * ```
+ *
+ * @example Order confirmation email
+ * ```typescript
+ * const orderConfirmation = $email({
+ *   subject: "Order #{{orderNumber}} confirmed - {{totalAmount}}",
+ *   body: `
+ *     <h1>Order Confirmed!</h1>
+ *     <p>Hi {{customerName}},</p>
+ *     <p>Your order #{{orderNumber}} has been confirmed.</p>
+ *     <h2>Order Details:</h2>
+ *     <p><strong>Total: {{totalAmount}}</strong></p>
+ *     <p>Estimated delivery: {{deliveryDate}}</p>
+ *   `,
+ *   schema: t.object({
+ *     customerName: t.string(),
+ *     orderNumber: t.string(),
+ *     totalAmount: t.string(),
+ *     deliveryDate: t.string()
+ *   })
+ * });
+ * ```
+ *
+ * @example Development with memory provider
+ * ```typescript
+ * const testEmail = $email({
+ *   subject: "Test: {{subject}}",
+ *   body: "<p>{{message}}</p>",
+ *   provider: "memory", // Captures emails for testing
+ *   schema: t.object({
+ *     subject: t.string(),
+ *     message: t.string()
+ *   })
+ * });
+ *
+ * // In tests - emails are captured, not actually sent
+ * await testEmail.send("test@example.com", {
+ *   subject: "Unit Test",
+ *   message: "This email was captured for testing"
+ * });
  * ```
  */
 declare const $email: {
@@ -142,7 +224,7 @@ interface EmailDescriptorOptions<T extends TSchema> {
   provider?: Service<EmailProvider> | "memory";
 }
 declare class EmailDescriptor<T extends TSchema> extends Descriptor<EmailDescriptorOptions<T>> {
-  protected readonly log: _alepha_logger0.Logger;
+  protected readonly log: _alepha_logger1.Logger;
   protected readonly templateService: TemplateService;
   readonly provider: EmailProvider | MemoryEmailProvider;
   get name(): string;
@@ -170,7 +252,7 @@ interface LocalEmailProviderOptions {
   directory?: string;
 }
 declare class LocalEmailProvider implements EmailProvider {
-  protected readonly log: _alepha_logger0.Logger;
+  protected readonly log: _alepha_logger1.Logger;
   protected readonly directory: string;
   constructor(options?: LocalEmailProviderOptions);
   send(to: string, subject: string, body: string): Promise<void>;
@@ -210,7 +292,7 @@ declare class NodemailerEmailProvider implements EmailProvider {
     EMAIL_FROM: string;
     EMAIL_SECURE: boolean;
   };
-  protected readonly log: _alepha_logger0.Logger;
+  protected readonly log: _alepha_logger1.Logger;
   protected transporter: Transporter;
   protected fromAddress: string;
   readonly options: NodemailerEmailProviderOptions;

package/logger.d.ts

@@ -1,6 +1,6 @@
 import * as _alepha_core0 from "alepha";
 import { Alepha, KIND, LogLevel, LoggerInterface, Static } from "alepha";
-import * as _sinclair_typebox0 from "@sinclair/typebox";
+import * as typebox0 from "typebox";
 
 //#region src/providers/LogDestinationProvider.d.ts
 declare abstract class LogDestinationProvider {
@@ -27,6 +27,7 @@ declare class Logger implements LoggerInterface {
   get context(): string | undefined;
   get level(): string;
   parseLevel(level: string, app: string): LogLevel;
+  private matchesPattern;
   asLogLevel(something: string): LogLevel;
   error(message: string, data?: unknown): void;
   warn(message: string, data?: unknown): void;
@@ -76,12 +77,7 @@ interface LoggerDescriptorOptions {
 //#endregion
 //#region src/providers/ConsoleColorProvider.d.ts
 declare class ConsoleColorProvider {
-  protected readonly env: {
-    NO_COLOR?: string | undefined;
-    FORCE_COLOR?: string | undefined;
-  };
-  protected readonly alepha: Alepha;
-  readonly colors: {
+  static readonly COLORS: {
     reset: string;
     grey: string;
     red: string;
@@ -98,10 +94,15 @@ declare class ConsoleColorProvider {
     debug: string;
     trace: string;
   };
+  protected readonly env: {
+    NO_COLOR?: string | undefined;
+    FORCE_COLOR?: string | undefined;
+  };
+  protected readonly alepha: Alepha;
   protected enabled: boolean;
   constructor();
   isEnabled(): boolean;
-  colorize(color: keyof typeof (void 0).colors, text: string, reset?: string): string;
+  colorize(color: keyof typeof ConsoleColorProvider.COLORS, text: string, reset?: string): string;
 }
 //#endregion
 //#region src/providers/ConsoleDestinationProvider.d.ts
@@ -168,6 +169,22 @@ declare class SimpleFormatterProvider extends LogFormatterProvider {
  * - SimpleFormatterProvider: formats logs as simple text (with colors when possible).
  * - RawFormatterProvider: formats logs as raw text without any formatting.
  *
+ * ### Event Emission
+ *
+ * The logger emits 'log' events that can be listened to by external code, allowing for custom log processing and destinations.
+ *
+ * ```ts
+ * class CustomDestination {
+ *   onLog = $hook({
+ *     on: "log",
+ *     handler: (ev) => {
+ *       // ev.message (formatted message)
+ *       // ev.entry (level, raw message, ...)
+ *     }
+ *   });
+ * }
+ * ```
+ *
  * ### Log Level
  *
  * You can configure the log level and format via environment variables:
@@ -181,11 +198,22 @@ declare class SimpleFormatterProvider extends LogFormatterProvider {
  *
  * Log level is also available in the state as `logLevel`, which can be used to dynamically change the log level at runtime.
  * ```ts
- * alepha.state("logLevel", "debug");
+ * alepha.state.set("logLevel", "debug");
  * ```
  *
  * Log level is $module aware, meaning you can set different log levels for different modules.
- * For example, you can set `LOG_LEVEL=my.module.name:debug,info` to set the log level to debug for `my.module.name` and info for all other modules.
+ *
+ * **Module-specific configuration:**
+ * - `LOG_LEVEL=my.module.name:debug,info` - debug for `my.module.name` (and submodules), info for others
+ * - `LOG_LEVEL=alepha:trace,my.app:error,info` - trace for alepha modules, error for my.app modules, info for others
+ *
+ * **Wildcard patterns (NEW):**
+ * - `LOG_LEVEL=alepha.*:debug,info` - debug for all alepha submodules
+ * - `LOG_LEVEL=*.test:silent,*.core:trace,info` - silent for test modules, trace for core modules
+ *
+ * **Robust parsing:**
+ * - Empty parts are gracefully skipped: `LOG_LEVEL=",,debug,,"` works fine
+ * - Better error messages: "Invalid log level 'bad' for module pattern 'alepha'"
  */
 declare const AlephaLogger: _alepha_core0.Service<_alepha_core0.Module>;
 declare const envSchema: _alepha_core0.TObject<{
@@ -212,16 +240,21 @@ declare const envSchema: _alepha_core0.TObject<{
    * - "text" - Simple text format, human-readable, with colors. {@link SimpleFormatterProvider}
    * - "raw" - Raw format, no formatting, just the message.  {@link RawFormatterProvider}
    */
-  LOG_FORMAT: _alepha_core0.TOptional<_sinclair_typebox0.TUnsafe<"json" | "text" | "raw">>;
+  LOG_FORMAT: _alepha_core0.TOptional<typebox0.TUnsafe<"json" | "text" | "raw">>;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
   interface State {
     logLevel?: string;
   }
+  interface Hooks {
+    log: {
+      message: string;
+      entry: LogEntry;
+    };
+  }
 }
 //# sourceMappingURL=index.d.ts.map
-
 //#endregion
 export { $logger, AlephaLogger, ConsoleColorProvider, ConsoleDestinationProvider, JsonFormatterProvider, LogDestinationProvider, LogEntry, LogFormatterProvider, Logger, LoggerDescriptorOptions, MemoryDestinationProvider, SimpleFormatterProvider };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "alepha",
-	"version": "0.9.5",
+	"version": "0.10.0",
 	"type": "module",
 	"engines": {
 		"node": ">=22.0.0"
@@ -15,52 +15,51 @@
 	"main": "./core.js",
 	"types": "./core.d.ts",
 	"dependencies": {
-		"@alepha/batch": "0.9.5",
-		"@alepha/bucket": "0.9.5",
-		"@alepha/cache": "0.9.5",
-		"@alepha/cache-redis": "0.9.5",
-		"@alepha/command": "0.9.5",
-		"@alepha/core": "0.9.5",
-		"@alepha/datetime": "0.9.5",
-		"@alepha/email": "0.9.5",
-		"@alepha/file": "0.9.5",
-		"@alepha/lock": "0.9.5",
-		"@alepha/lock-redis": "0.9.5",
-		"@alepha/logger": "0.9.5",
-		"@alepha/postgres": "0.9.5",
-		"@alepha/queue": "0.9.5",
-		"@alepha/queue-redis": "0.9.5",
-		"@alepha/react": "0.9.5",
-		"@alepha/react-auth": "0.9.5",
-		"@alepha/react-form": "0.9.5",
-		"@alepha/react-head": "0.9.5",
-		"@alepha/react-i18n": "0.9.5",
-		"@alepha/redis": "0.9.5",
-		"@alepha/retry": "0.9.5",
-		"@alepha/router": "0.9.5",
-		"@alepha/scheduler": "0.9.5",
-		"@alepha/security": "0.9.5",
-		"@alepha/server": "0.9.5",
-		"@alepha/server-cache": "0.9.5",
-		"@alepha/server-compress": "0.9.5",
-		"@alepha/server-cookies": "0.9.5",
-		"@alepha/server-cors": "0.9.5",
-		"@alepha/server-health": "0.9.5",
-		"@alepha/server-helmet": "0.9.5",
-		"@alepha/server-links": "0.9.5",
-		"@alepha/server-metrics": "0.9.5",
-		"@alepha/server-multipart": "0.9.5",
-		"@alepha/server-proxy": "0.9.5",
-		"@alepha/server-security": "0.9.5",
-		"@alepha/server-static": "0.9.5",
-		"@alepha/server-swagger": "0.9.5",
-		"@alepha/topic": "0.9.5",
-		"@alepha/topic-redis": "0.9.5",
-		"@alepha/vite": "0.9.5",
-		"react": "^19.1.1"
+		"@alepha/batch": "0.10.0",
+		"@alepha/bucket": "0.10.0",
+		"@alepha/cache": "0.10.0",
+		"@alepha/cache-redis": "0.10.0",
+		"@alepha/command": "0.10.0",
+		"@alepha/core": "0.10.0",
+		"@alepha/datetime": "0.10.0",
+		"@alepha/email": "0.10.0",
+		"@alepha/file": "0.10.0",
+		"@alepha/lock": "0.10.0",
+		"@alepha/lock-redis": "0.10.0",
+		"@alepha/logger": "0.10.0",
+		"@alepha/postgres": "0.10.0",
+		"@alepha/queue": "0.10.0",
+		"@alepha/queue-redis": "0.10.0",
+		"@alepha/react": "0.10.0",
+		"@alepha/react-auth": "0.10.0",
+		"@alepha/react-form": "0.10.0",
+		"@alepha/react-head": "0.10.0",
+		"@alepha/react-i18n": "0.10.0",
+		"@alepha/redis": "0.10.0",
+		"@alepha/retry": "0.10.0",
+		"@alepha/router": "0.10.0",
+		"@alepha/scheduler": "0.10.0",
+		"@alepha/security": "0.10.0",
+		"@alepha/server": "0.10.0",
+		"@alepha/server-cache": "0.10.0",
+		"@alepha/server-compress": "0.10.0",
+		"@alepha/server-cookies": "0.10.0",
+		"@alepha/server-cors": "0.10.0",
+		"@alepha/server-health": "0.10.0",
+		"@alepha/server-helmet": "0.10.0",
+		"@alepha/server-links": "0.10.0",
+		"@alepha/server-metrics": "0.10.0",
+		"@alepha/server-multipart": "0.10.0",
+		"@alepha/server-proxy": "0.10.0",
+		"@alepha/server-security": "0.10.0",
+		"@alepha/server-static": "0.10.0",
+		"@alepha/server-swagger": "0.10.0",
+		"@alepha/topic": "0.10.0",
+		"@alepha/topic-redis": "0.10.0",
+		"@alepha/vite": "0.10.0"
 	},
 	"devDependencies": {
-		"tsdown": "^0.15.1"
+		"tsdown": "^0.15.3"
 	},
 	"scripts": {
 		"build": "node build.ts"
@@ -70,6 +69,18 @@
 		"**/*.cjs",
 		"**/*.d.ts"
 	],
+	"peerDependencies": {
+		"react": "*",
+		"react-dom": "*"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"react-dom": {
+			"optional": true
+		}
+	},
 	"exports": {
 		".": {
 			"import": "./core.js",