stratal 0.0.21 → 0.0.23

package/dist/index-B5JBRcWD.d.mts

@@ -0,0 +1,544 @@
+import { Dn as AsyncModuleOptions, Dr as ApplicationError, In as OnInitialize, Nn as ModuleContext, Y as Container, kn as DynamicModule } from "./index-B_JoEl3V.mjs";
+import { t as StratalEnv } from "./env-ug22bJj7.mjs";
+import { m as II18nService } from "./zod-wecrEVAs.mjs";
+import { r as LoggerService } from "./index-BUt92sAE.mjs";
+import { t as Constructor } from "./types-CmV_9xBD.mjs";
+import { t as TieredCacheService } from "./tiered-cache.service-Dv3BhxxE.mjs";
+import { t as CronJob } from "./cron-job-NesZRk8F.mjs";
+import { a as QueueBinding, i as QueueMessage, n as ConsumerRegistry } from "./consumer-registry-D3iMTSdy.mjs";
+
+//#region src/queue/queue.module.d.ts
+/**
+ * Queue module configuration options
+ */
+interface QueueModuleOptions {
+  /**
+   * Queue provider type
+   * - 'cloudflare': Production provider using Cloudflare Queue bindings
+   * - 'sync': Testing provider that processes messages immediately
+   */
+  provider: 'cloudflare' | 'sync';
+  /**
+   * KV binding for queue state (idempotency keys + failed jobs).
+   * Defaults to the `CACHE` binding if omitted.
+   */
+  store?: {
+    /**
+     * KV namespace binding name.
+     * @default CACHE
+     */
+    binding?: string;
+  };
+  /**
+   * Idempotency configuration.
+   *
+   * Delivery is **at-least-once with best-effort de-duplication**, not
+   * exactly-once. Every dispatch carries an idempotency key (an explicit
+   * `metadata.idempotencyKey`, otherwise a deterministic SHA-256 hash of `type`
+   * + `payload`), and a message already recorded as processed is skipped. The
+   * processed marker is written only after a handler succeeds, and KV `get`/`put`
+   * are eventually consistent — so a message redelivered concurrently (or after
+   * a crash before the marker was durable) can still run more than once. Make
+   * handlers idempotent; don't rely on this as a hard exactly-once guarantee.
+   * `ttl` bounds how long processed keys are remembered.
+   */
+  idempotency?: {
+    /** TTL in seconds for processed idempotency keys. Default: 86400 (24h) */ttl?: number;
+  };
+  /**
+   * Failed-job configuration.
+   *
+   * Failed jobs persist indefinitely until retried or purged. To bound growth,
+   * register the opt-in `FailedJobCleanupJob` cron in a module's `jobs` array;
+   * it deletes failed jobs older than `retention`.
+   */
+  failedJobs?: {
+    /**
+     * Age in seconds beyond which `FailedJobCleanupJob` deletes a failed job.
+     * Default: 604800 (7d). Has no effect unless the cron is registered.
+     */
+    retention?: number;
+  };
+  /** Max retry attempts before storing as failed job. Default: 3 */
+  maxRetries?: number;
+}
+declare class QueueModule implements OnInitialize {
+  /**
+   * Fail fast at boot if the configured KV store binding is missing, rather
+   * than letting every queue invocation hard-fail lazily. The binding backs
+   * idempotency claims and failed-job storage, so without it the queue
+   * subsystem cannot function.
+   */
+  onInitialize({
+    container
+  }: ModuleContext): void;
+  /**
+   * Configure queue infrastructure with async factory.
+   *
+   * Use when provider configuration depends on other services like ConfigService.
+   *
+   * @param options - Async configuration with factory and inject tokens
+   * @returns Dynamic module with queue infrastructure
+   *
+   * @example
+   * ```typescript
+   * QueueModule.forRootAsync({
+   *   inject: [CONFIG_TOKENS.ConfigService],
+   *   useFactory: (config: IConfigService) => ({
+   *     provider: config.get('queue').provider
+   *   })
+   * })
+   * ```
+   */
+  static forRootAsync(options: AsyncModuleOptions<QueueModuleOptions>): DynamicModule;
+  /**
+   * Register a queue binding for injection.
+   *
+   * The binding name doubles as the DI injection token and the
+   * `env`-lookup key. Binding names are typed against `StratalEnv`
+   * (autocomplete works once an app augments `StratalEnv` with its
+   * Cloudflare bindings).
+   *
+   * @param binding - Queue binding identifier (e.g. `NOTIFICATIONS_QUEUE`).
+   * @returns Dynamic module that provides the queue sender
+   *
+   * @example
+   * ```typescript
+   * // In AppModule imports
+   * QueueModule.registerQueue('NOTIFICATIONS_QUEUE')
+   *
+   * // Then inject using the binding name
+   * constructor(@InjectQueue('NOTIFICATIONS_QUEUE') private queue: IQueueSender) {}
+   * ```
+   */
+  static registerQueue(binding: QueueBinding): DynamicModule;
+}
+//#endregion
+//#region src/queue/failed-job.d.ts
+interface FailedJobMetadata {
+  /** Cloudflare queue name the message was consumed from (display/filtering). */
+  queue: string;
+  /** Producer binding to re-enqueue through on retry. */
+  binding: string;
+  type: string;
+  consumer: string;
+  attempts: number;
+  failedAt: string;
+}
+interface FailedJob extends FailedJobMetadata {
+  id: string;
+  message: QueueMessage;
+  error: {
+    name: string;
+    message: string;
+    stack?: string;
+  };
+}
+//#endregion
+//#region src/queue/queue-store.d.ts
+/** Default KV binding name used for queue state when none is configured. */
+declare const DEFAULT_STORE_BINDING = "CACHE";
+/**
+ * Persists queue idempotency claims and failed jobs.
+ *
+ * Backed by {@link TieredCacheService} (isolate-local L1 + KV). The L1 is what
+ * makes `markProcessed` → `isProcessed` reliable within an isolate: a claim
+ * written on this isolate is read back from memory, so a message redelivered to
+ * the same warm isolate is de-duplicated even inside KV's eventual-consistency
+ * window. Idempotency markers are set-once, the pattern the L1 tier is designed
+ * for. Cross-isolate duplicates still rely on KV (eventually consistent) —
+ * delivery remains at-least-once with best-effort de-duplication, not
+ * exactly-once.
+ */
+declare class QueueStore {
+  private readonly cache;
+  private readonly idempotencyTtl;
+  constructor(cache: TieredCacheService, options: QueueModuleOptions);
+  isProcessed(key: string): Promise<boolean>;
+  markProcessed(key: string): Promise<void>;
+  storeFailedJob(job: FailedJob): Promise<void>;
+  getFailedJob(messageId: string): Promise<FailedJob | null>;
+  removeFailedJob(messageId: string): Promise<void>;
+  listFailedJobs(options?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<{
+    keys: {
+      id: string;
+      metadata: FailedJobMetadata;
+    }[];
+    cursor?: string;
+  }>;
+  purgeFailedJobs(): Promise<void>;
+  /**
+   * Delete failed jobs older than `retentionSeconds` (by their `failedAt`
+   * timestamp). Returns the number removed. Backs the opt-in
+   * {@link FailedJobCleanupJob} cron — failed jobs otherwise persist
+   * indefinitely until retried or purged.
+   */
+  purgeFailedJobsOlderThan(retentionSeconds: number): Promise<number>;
+}
+//#endregion
+//#region src/queue/queue-manager.d.ts
+declare class QueueManager {
+  private readonly registry;
+  private readonly logger;
+  private readonly store;
+  private readonly maxRetries;
+  constructor(registry: ConsumerRegistry, logger: LoggerService, store: QueueStore, options: QueueModuleOptions);
+  processBatch(queueName: string, batch: MessageBatch): Promise<void>;
+}
+//#endregion
+//#region src/queue/queue-sender.interface.d.ts
+/**
+ * Message input for queue dispatch (without auto-generated fields)
+ *
+ * When dispatching a message, the id is auto-generated.
+ * You only need to provide the type, payload, and optional metadata.
+ */
+type DispatchMessage<T = unknown> = Omit<QueueMessage<T>, 'id'>;
+/**
+ * Queue sender interface for dispatching messages to a queue.
+ *
+ * Each IQueueSender instance is bound to a specific queue name.
+ * Messages are dispatched with auto-generated id, timestamp, and locale metadata.
+ *
+ * @example
+ * ```typescript
+ * // Injected via @InjectQueue or token binding
+ * constructor(
+ *   @InjectQueue('notifications-queue') private queue: IQueueSender
+ * ) {}
+ *
+ * // Dispatch a message
+ * await this.queue.dispatch({
+ *   type: 'email.send',
+ *   payload: {
+ *     to: 'user@example.com',
+ *     subject: 'Welcome',
+ *     html: '<h1>Hello!</h1>'
+ *   }
+ * })
+ * ```
+ */
+interface IQueueSender {
+  /**
+   * Dispatch a message to this queue.
+   *
+   * Auto-adds:
+   * - `id`: Unique message identifier (UUID)
+   * - `metadata.locale`: Current locale from i18n context
+   * - `metadata.idempotencyKey`: Deterministic SHA-256 hash of type + payload (if not provided)
+   *
+   * @param message - Message to dispatch (without id)
+   */
+  dispatch<T>(message: DispatchMessage<T>): Promise<void>;
+}
+//#endregion
+//#region src/queue/providers/queue-provider.interface.d.ts
+/**
+ * Queue Provider Interface
+ *
+ * Defines the contract for queue providers. Each provider handles
+ * the actual message delivery mechanism.
+ *
+ * **Available Providers:**
+ * - `cloudflare`: Uses Cloudflare Queue bindings (production)
+ * - `sync`: Processes messages immediately (testing/development)
+ *
+ * @example Implementing a custom provider
+ * ```typescript
+ * export class CustomQueueProvider implements IQueueProvider {
+ *   async send<T>(binding: string, message: QueueMessage<T>): Promise<void> {
+ *     // Custom implementation
+ *   }
+ * }
+ * ```
+ */
+interface IQueueProvider {
+  /**
+   * Send a message to a queue
+   *
+   * Provider handles the actual delivery mechanism:
+   * - CloudflareQueueProvider: Looks up the binding on env and calls queue.send()
+   * - SyncQueueProvider: Finds matching consumers and calls handle() directly
+   *
+   * @param binding - Queue binding identifier
+   * @param message - Complete message with id and metadata
+   */
+  send<T>(binding: string, message: QueueMessage<T>): Promise<void>;
+}
+//#endregion
+//#region src/queue/providers/cloudflare-queue.provider.d.ts
+/**
+ * Cloudflare Queue Provider
+ *
+ * Sends messages to Cloudflare Queues by resolving the binding directly on
+ * the worker's `env`. Used in production environments where Cloudflare Workers
+ * handle queue processing.
+ *
+ * @example
+ * ```typescript
+ * const provider = new CloudflareQueueProvider(env)
+ * await provider.send('NOTIFICATIONS_QUEUE', message)
+ * ```
+ */
+declare class CloudflareQueueProvider implements IQueueProvider {
+  private readonly env;
+  constructor(env: StratalEnv);
+  /**
+   * Send a message to a Cloudflare Queue
+   *
+   * @param binding - Queue binding identifier (e.g., 'NOTIFICATIONS_QUEUE')
+   * @param message - Complete message with id and payload
+   * @throws {QueueError} If the binding is not configured on env
+   */
+  send<T>(binding: string, message: QueueMessage<T>): Promise<void>;
+}
+//#endregion
+//#region src/queue/providers/sync-queue.provider.d.ts
+/**
+ * Sync Queue Provider
+ *
+ * Processes messages immediately by finding matching consumers and calling
+ * their handle() method directly. Used for testing and development where
+ * real queue infrastructure is not available.
+ *
+ * **Behavior:**
+ * - Messages are processed synchronously when send() is called
+ * - Matching consumers are found via ConsumerRegistry by message type
+ * - All matching consumers are called sequentially
+ * - Errors are re-thrown after onError() is called (fail-fast for testing)
+ *
+ * **Consumer Matching:**
+ * - Consumers are matched by message type, not queue name
+ * - Wildcard ('*') matches all message types
+ */
+declare class SyncQueueProvider implements IQueueProvider {
+  private readonly registry;
+  private readonly root;
+  constructor(registry: ConsumerRegistry, root: Container);
+  /**
+   * Process a message synchronously.
+   *
+   * Runs inside the active request scope when dispatch happens within one (an
+   * HTTP request, or `runInScope` for queues/cron/commands). When dispatched
+   * with no ambient scope — e.g. a service invoked directly in a test — it
+   * establishes its own request scope (mirroring the production queue handler)
+   * so consumers and their request-scoped dependencies resolve correctly.
+   *
+   * @param _binding - Queue binding (not used for routing, consumers match by message type)
+   * @param message - Complete message with id and payload
+   * @throws Re-throws any error from consumer.handle() after calling onError()
+   */
+  send<T>(_binding: string, message: QueueMessage<T>): Promise<void>;
+  /**
+   * Resolve a fresh consumer per message from `container` (matched by type) and
+   * invoke each sequentially, fail-fast on the first error after `onError`.
+   */
+  private process;
+}
+//#endregion
+//#region src/queue/queue-sender.d.ts
+/**
+ * Queue Sender
+ *
+ * Implementation of IQueueSender bound to a specific queue binding.
+ * Created by QueueRegistry for each registered binding.
+ *
+ * Automatically enriches messages with:
+ * - `id`: UUID generated via crypto.randomUUID()
+ * - `metadata.locale`: Current locale from I18n context
+ * - `metadata.idempotencyKey`: Deterministic SHA-256 hash of type + payload (if not provided)
+ *
+ * @example
+ * ```typescript
+ * // Created by QueueRegistry, not directly instantiated
+ * const sender = registry.getQueue('NOTIFICATIONS_QUEUE')
+ *
+ * await sender.dispatch({
+ *   type: 'email.send',
+ *   payload: { to: 'user@example.com', subject: 'Hello' }
+ * })
+ * ```
+ */
+declare class QueueSender implements IQueueSender {
+  private readonly binding;
+  private readonly provider;
+  private readonly i18n;
+  constructor(binding: string, provider: IQueueProvider, i18n: II18nService);
+  /**
+   * Dispatch a message to this queue.
+   *
+   * @param message - Message to dispatch (without id)
+   */
+  dispatch<T>(message: DispatchMessage<T>): Promise<void>;
+  private generateIdempotencyKey;
+}
+//#endregion
+//#region src/queue/services/queue-provider-factory.d.ts
+/**
+ * Queue Provider Factory
+ *
+ * Creates the appropriate queue provider based on configuration provided
+ * via QueueModule.forRootAsync().
+ *
+ * **Provider Selection:**
+ * - `cloudflare`: Production provider using Cloudflare Queue bindings
+ * - `sync`: Testing provider that processes messages immediately
+ *
+ * @example
+ * ```typescript
+ * // Configuration via QueueModule.forRootAsync()
+ * QueueModule.forRootAsync({
+ *   inject: [CONFIG_TOKENS.ConfigService],
+ *   useFactory: (config) => ({ provider: config.get('queue').provider })
+ * })
+ *
+ * // Factory usage (internal)
+ * const factory = container.resolve(QueueProviderFactory)
+ * const provider = factory.create()
+ * ```
+ */
+declare class QueueProviderFactory {
+  private readonly env;
+  private readonly registry;
+  private readonly container;
+  private readonly options?;
+  constructor(env: StratalEnv, registry: ConsumerRegistry, container: Container, options?: QueueModuleOptions | undefined);
+  /**
+   * Create a queue provider based on module configuration
+   *
+   * @returns Queue provider instance
+   * @throws {QueueError} If provider type is not supported
+   */
+  create(): IQueueProvider;
+}
+//#endregion
+//#region src/queue/queue-registry.d.ts
+/**
+ * Queue Registry
+ *
+ * Request-scoped factory service for creating QueueSender instances.
+ * Caches senders per binding within the request scope.
+ *
+ * This service is used internally by QueueModule.registerQueue() to provide
+ * IQueueSender instances for each registered binding.
+ *
+ * **Why request-scoped?**
+ * - Needs access to I18nService for locale-aware message metadata
+ * - Provider is created once per request for consistency
+ * - Queue senders are cached per request to avoid recreating them
+ *
+ * @example
+ * ```typescript
+ * // Used internally by QueueModule.registerQueue()
+ * QueueModule.registerQueue('NOTIFICATIONS_QUEUE')
+ *
+ * // The module creates a factory provider:
+ * {
+ *   provide: 'NOTIFICATIONS_QUEUE',
+ *   useFactory: (registry: QueueRegistry) => registry.getQueue('NOTIFICATIONS_QUEUE'),
+ *   inject: [QUEUE_TOKENS.QueueRegistry],
+ * }
+ * ```
+ */
+declare class QueueRegistry {
+  private readonly i18n;
+  private readonly provider;
+  private readonly senders;
+  constructor(providerFactory: QueueProviderFactory, i18n: II18nService);
+  /**
+   * Get or create a QueueSender for the specified binding.
+   *
+   * Senders are cached per binding within the request scope.
+   *
+   * @param binding - The queue binding to get a sender for
+   * @returns QueueSender bound to the specified binding
+   */
+  getQueue(binding: string): IQueueSender;
+}
+//#endregion
+//#region src/queue/jobs/failed-job-cleanup.job.d.ts
+/**
+ * Opt-in cron job that deletes failed jobs older than `failedJobs.retention`
+ * (default 7 days). Failed jobs are persisted indefinitely by default; register
+ * this job only if you want automatic cleanup.
+ *
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     QueueModule.forRoot({ provider: 'cloudflare', failedJobs: { retention: 1209600 } }),
+ *   ],
+ *   jobs: [FailedJobCleanupJob], // daily at 00:00 UTC
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * Add a matching cron trigger to `wrangler.jsonc` (`"0 0 * * *"` for the
+ * default schedule), or use {@link failedJobCleanupJob} for a custom one.
+ */
+declare class FailedJobCleanupJob implements CronJob {
+  private readonly store;
+  private readonly options;
+  private readonly logger;
+  static schedule: string;
+  constructor(store: QueueStore, options: QueueModuleOptions, logger: LoggerService);
+  execute(): Promise<void>;
+}
+/**
+ * Create a {@link FailedJobCleanupJob} bound to a custom cron schedule (which
+ * must match a `wrangler.jsonc` trigger). Use when the default daily schedule
+ * isn't desired:
+ *
+ * ```ts
+ * @Module({ jobs: [failedJobCleanupJob('0 3 * * 0')] }) // weekly, Sundays 03:00
+ * ```
+ */
+declare function failedJobCleanupJob(schedule: string): Constructor<CronJob>;
+//#endregion
+//#region src/queue/decorators/inject-queue.decorator.d.ts
+/**
+ * Inject a queue sender by binding name.
+ *
+ * The binding name matches the `binding` field declared under `queues.producers`
+ * in `wrangler.jsonc` (e.g. `BACKGROUND_QUEUE`). Stratal looks the binding up
+ * directly on the worker's `env`; the underlying Cloudflare queue can be any
+ * env-specific name (e.g. `background-queue-dev`) without affecting code.
+ *
+ * @param binding - Queue binding identifier (typed against `StratalEnv`).
+ * @returns Parameter decorator for constructor injection
+ *
+ * @example
+ * ```typescript
+ * constructor(
+ *   @InjectQueue('NOTIFICATIONS_QUEUE') private queue: IQueueSender
+ * ) {}
+ *
+ * await this.queue.dispatch({
+ *   type: 'email.send',
+ *   payload: { to: 'user@example.com', subject: 'Hello' }
+ * })
+ * ```
+ *
+ * @remarks
+ * The binding must be registered via `QueueModule.registerQueue(binding)`
+ * before injection. For module-internal bindings (e.g. EmailModule),
+ * use `@inject(TOKEN)` with `useExisting` provider binding instead.
+ */
+declare function InjectQueue(binding: QueueBinding): ParameterDecorator;
+//#endregion
+//#region src/queue/queue.tokens.d.ts
+declare const QUEUE_TOKENS: {
+  readonly QueueProviderFactory: symbol;
+  readonly QueueRegistry: symbol;
+  readonly QueueModuleOptions: symbol;
+  readonly QueueStore: symbol;
+};
+type QueueToken = (typeof QUEUE_TOKENS)[keyof typeof QUEUE_TOKENS];
+//#endregion
+//#region src/queue/queue.error.d.ts
+declare class QueueError extends ApplicationError {}
+//#endregion
+export { QueueStore as _, FailedJobCleanupJob as a, QueueModule as b, QueueProviderFactory as c, CloudflareQueueProvider as d, IQueueProvider as f, DEFAULT_STORE_BINDING as g, QueueManager as h, InjectQueue as i, QueueSender as l, IQueueSender as m, QUEUE_TOKENS as n, failedJobCleanupJob as o, DispatchMessage as p, QueueToken as r, QueueRegistry as s, QueueError as t, SyncQueueProvider as u, FailedJob as v, QueueModuleOptions as x, FailedJobMetadata as y };
+//# sourceMappingURL=index-B5JBRcWD.d.mts.map

package/dist/index-B5JBRcWD.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-B5JBRcWD.d.mts","names":[],"sources":["../src/queue/queue.module.ts","../src/queue/failed-job.ts","../src/queue/queue-store.ts","../src/queue/queue-manager.ts","../src/queue/queue-sender.interface.ts","../src/queue/providers/queue-provider.interface.ts","../src/queue/providers/cloudflare-queue.provider.ts","../src/queue/providers/sync-queue.provider.ts","../src/queue/queue-sender.ts","../src/queue/services/queue-provider-factory.ts","../src/queue/queue-registry.ts","../src/queue/jobs/failed-job-cleanup.job.ts","../src/queue/decorators/inject-queue.decorator.ts","../src/queue/queue.tokens.ts","../src/queue/queue.error.ts"],"mappings":"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"}

package/dist/index-BUt92sAE.d.mts

@@ -0,0 +1,124 @@
+//#region src/logger/logger.tokens.d.ts
+declare const LOGGER_TOKENS: {
+  readonly LoggerService: symbol;
+  readonly Formatter: symbol;
+  readonly LogLevelOptions: symbol;
+};
+//#endregion
+//#region src/logger/contracts/log-level.d.ts
+/**
+ * Log severity levels
+ * Ordered from least to most severe
+ */
+declare enum LogLevel {
+  DEBUG = "debug",
+  INFO = "info",
+  WARN = "warn",
+  ERROR = "error"
+}
+/**
+ * Map log levels to numeric priorities (for filtering)
+ * Higher numbers = more severe = higher priority
+ */
+declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
+//#endregion
+//#region src/logger/contracts/log-context.d.ts
+/**
+ * Structured metadata attached to log entries
+ * Supports arbitrary key-value pairs for context enrichment
+ */
+type LogContext = Record<string, unknown>;
+/**
+ * Internal context automatically added by LoggerService
+ * Contains request metadata, etc.
+ */
+interface InternalLogContext extends LogContext {
+  userId?: string;
+  timestamp: number;
+}
+//#endregion
+//#region src/logger/contracts/log-entry.d.ts
+/**
+ * Complete log entry structure passed to transports
+ * Combines message, level, and enriched context
+ */
+interface LogEntry {
+  level: LogLevel;
+  message: string;
+  context: InternalLogContext;
+  error?: {
+    message: string;
+    stack?: string;
+    name?: string;
+  };
+}
+//#endregion
+//#region src/logger/formatters/formatter.interface.d.ts
+/**
+ * Formatter contract
+ * Transforms LogEntry into string representation for transport output
+ */
+interface ILogFormatter {
+  /**
+   * Format log entry into string
+   * @param entry - Complete log entry with context
+   * @returns Formatted string ready for transport
+   */
+  format(entry: LogEntry): string;
+}
+//#endregion
+//#region src/logger/services/logger.service.d.ts
+declare class LoggerService {
+  private readonly logLevel;
+  private readonly formatter;
+  constructor(logLevel: LogLevel, formatter: ILogFormatter);
+  debug(message: string, context?: LogContext): void;
+  info(message: string, context?: LogContext): void;
+  warn(message: string, context?: LogContext): void;
+  error(message: string, error: Error, context?: LogContext): void;
+  error(message: string, context?: LogContext): void;
+  private log;
+  private writeToConsole;
+  private enrichContext;
+  private serializeError;
+}
+//#endregion
+//#region src/logger/formatters/json-formatter.d.ts
+/**
+ * JSON Formatter
+ *
+ * Produces structured JSON logs for production environments.
+ * Optimized for log aggregation systems (Cloudflare Analytics, Datadog, etc.)
+ *
+ * Output format:
+ * {
+ *   "level": "info",
+ *   "message": "User logged in",
+ *   "timestamp": 1234567890,
+ *   "userId": "user_456",
+ *   "error": { "message": "...", "stack": "..." }
+ * }
+ */
+declare class JsonFormatter implements ILogFormatter {
+  format(entry: LogEntry): string;
+}
+//#endregion
+//#region src/logger/formatters/pretty-formatter.d.ts
+/**
+ * Pretty Formatter
+ *
+ * Human-readable colored output for development environments.
+ * Uses ANSI color codes for terminal output.
+ *
+ * Output format:
+ * [2024-01-15 10:30:45] INFO: User logged in
+ *   userId: user_456
+ */
+declare class PrettyFormatter implements ILogFormatter {
+  private readonly colors;
+  private readonly reset;
+  format(entry: LogEntry): string;
+}
+//#endregion
+export { InternalLogContext as a, LogLevel as c, LogEntry as i, LOGGER_TOKENS as l, JsonFormatter as n, LogContext as o, LoggerService as r, LOG_LEVEL_PRIORITY as s, PrettyFormatter as t };
+//# sourceMappingURL=index-BUt92sAE.d.mts.map

package/dist/index-BUt92sAE.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-BUt92sAE.d.mts","names":[],"sources":["../src/logger/logger.tokens.ts","../src/logger/contracts/log-level.ts","../src/logger/contracts/log-context.ts","../src/logger/contracts/log-entry.ts","../src/logger/formatters/formatter.interface.ts","../src/logger/services/logger.service.ts","../src/logger/formatters/json-formatter.ts","../src/logger/formatters/pretty-formatter.ts"],"mappings":";cAAa,aAAA;EAAA;;;;;;;AAAb;;;aCIY,QAAA;EACV,KAAA;EACA,IAAA;EACA,IAAA;EACA,KAAA;AAAA;;;;AAJF;cAWa,kBAAA,EAAoB,MAAM,CAAC,QAAA;;;;ADfxC;;;KEIY,UAAA,GAAa,MAAM;;;;;UAMd,kBAAA,SAA2B,UAAU;EACpD,MAAA;EACA,SAAA;AAAA;;;;;;;UCLe,QAAA;EACf,KAAA,EAAO,QAAA;EACP,OAAA;EACA,OAAA,EAAS,kBAAkB;EAC3B,KAAA;IACE,OAAA;IACA,KAAA;IACA,IAAA;EAAA;AAAA;;;AHdJ;;;;AAAA,UIMiB,aAAA;;;;;;EAMf,MAAA,CAAO,KAAA,EAAO,QAAQ;AAAA;;;cCJX,aAAA;EAAA,iBAGQ,QAAA;EAAA,iBAGA,SAAA;cAHA,QAAA,EAAU,QAAA,EAGV,SAAA,EAAW,aAAA;EAG9B,KAAA,CAAM,OAAA,UAAiB,OAAA,GAAU,UAAA;EAIjC,IAAA,CAAK,OAAA,UAAiB,OAAA,GAAU,UAAA;EAIhC,IAAA,CAAK,OAAA,UAAiB,OAAA,GAAU,UAAA;EAIhC,KAAA,CAAM,OAAA,UAAiB,KAAA,EAAO,KAAA,EAAO,OAAA,GAAU,UAAA;EAC/C,KAAA,CAAM,OAAA,UAAiB,OAAA,GAAU,UAAA;EAAA,QAezB,GAAA;EAAA,QAqBA,cAAA;EAAA,QAiBA,aAAA;EAAA,QAOA,cAAA;AAAA;;;;;;;;;;;;;;AJtFV;;;;cKca,aAAA,YAAyB,aAAa;EACjD,MAAA,CAAO,KAAA,EAAO,QAAA;AAAA;;;;;;;;;;;;;cCLH,eAAA,YAA2B,aAAa;EAAA,iBAClC,MAAA;EAAA,iBAOA,KAAA;EAEjB,MAAA,CAAO,KAAA,EAAO,QAAA;AAAA"}