stratal 0.0.21 → 0.0.23

package/dist/index-DUzWs0z7.d.mts

@@ -1,494 +0,0 @@
-import { d as ApplicationError, gn as AsyncModuleOptions, vn as DynamicModule } from "./index-ByOyTmqf.mjs";
-import { t as StratalEnv } from "./env-D1rcZ8_r.mjs";
-import { b as II18nService } from "./index-Bnpfq6uk.mjs";
-import { r as QueueMessage, t as ConsumerRegistry } from "./consumer-registry-B7yUNh0q.mjs";
-
-//#region src/queue/queue-manager.d.ts
-/**
- * Queue Manager
- *
- * Singleton service for processing queue message batches.
- * Routes messages to consumers based on message type.
- *
- * **Message Routing:**
- * - Consumers declare message types they handle (e.g., ['email.send'])
- * - When a message arrives, consumers matching the message type are invoked
- * - A consumer can handle messages from ANY queue (routing is by type, not queue)
- *
- * **Note:** For sending messages to queues, use IQueueSender instances
- * obtained via @InjectQueue('queue-name') or module bindings.
- *
- * @example Processing a queue batch
- * ```typescript
- * // In Cloudflare Worker queue handler
- * await queueManager.processBatch('notifications-queue', batch)
- * ```
- */
-declare class QueueManager {
-  private readonly registry;
-  constructor(registry: ConsumerRegistry);
-  /**
-   * Process a batch of queue messages
-   *
-   * Routes messages to registered consumers based on message type.
-   * Uses ConsumerRegistry to find matching consumers.
-   *
-   * @param _queueName - Name of the queue (for logging, not used for routing)
-   * @param batch - Batch of messages from Cloudflare Queue
-   */
-  processBatch(_queueName: string, batch: MessageBatch): Promise<void>;
-}
-//#endregion
-//#region src/queue/queue-name.d.ts
-/**
- * Queue Name Type System with Module Augmentation
- *
- * This file provides a type-safe queue naming system using module augmentation.
- * Applications augment the QueueNames interface to get autocomplete for queue names.
- *
- * @example In apps/backend/src/types/queues.ts:
- * ```typescript
- * declare module 'stratal' {
- *   interface QueueNames {
- *     'notifications-queue': true
- *     'batch-notifications-queue': true
- *   }
- * }
- * ```
- *
- * When QueueNames is augmented, QueueName provides autocomplete.
- * When not augmented, QueueName falls back to string for flexibility.
- */
-/**
- * Augmentable interface for queue names.
- *
- * Applications extend this interface via module augmentation to define
- * their queue names. The keys become the valid queue name union type.
- *
- * @example
- * ```typescript
- * // In your application's type declarations
- * declare module 'stratal' {
- *   interface QueueNames {
- *     'notifications-queue': true
- *     'batch-notifications-queue': true
- *   }
- * }
- * ```
- */
-interface QueueNames {}
-/**
- * Queue name type - extracts keys from QueueNames or falls back to string.
- *
- * When QueueNames is augmented with queue name keys, this type provides:
- * - Type safety: Only declared queue names are valid
- * - Autocomplete: IDE suggestions for available queue names
- *
- * When QueueNames is empty (not augmented), falls back to string
- * for flexibility during development or in non-typed contexts.
- */
-type QueueName = keyof QueueNames extends never ? string : keyof QueueNames;
-//#endregion
-//#region src/queue/queue-sender.interface.d.ts
-/**
- * Message input for queue dispatch (without auto-generated fields)
- *
- * When dispatching a message, the id and timestamp are auto-generated.
- * You only need to provide the type, payload, and optional metadata.
- */
-type DispatchMessage<T = unknown> = Omit<QueueMessage<T>, 'id' | 'timestamp'>;
-/**
- * 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)
-   * - `timestamp`: Current timestamp in milliseconds
-   * - `metadata.locale`: Current locale from i18n context
-   *
-   * @param message - Message to dispatch (without id/timestamp)
-   */
-  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>(queueName: string, message: QueueMessage<T>): Promise<void> {
- *     // Custom implementation
- *   }
- * }
- * ```
- */
-interface IQueueProvider {
-  /**
-   * Send a message to a queue
-   *
-   * Provider handles the actual delivery mechanism:
-   * - CloudflareQueueProvider: Resolves CF binding and calls queue.send()
-   * - SyncQueueProvider: Finds matching consumers and calls handle() directly
-   *
-   * @param queueName - Queue name
-   * @param message - Complete message with id, timestamp, and metadata
-   */
-  send<T>(queueName: 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 bindings from the environment.
- * Used in production environments where Cloudflare Workers handle queue processing.
- *
- * **Binding Resolution:**
- * Queue names are converted to binding names:
- * - `notifications-queue` → `NOTIFICATIONS_QUEUE`
- *
- * @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 queueName - Queue name (e.g., 'notifications-queue')
-   * @param message - Complete message with id, timestamp, and payload
-   * @throws {QueueBindingNotFoundError} If queue binding is not configured
-   */
-  send<T>(queueName: string, message: QueueMessage<T>): Promise<void>;
-  /**
-   * Resolve queue binding from Cloudflare environment
-   *
-   * Converts kebab-case queue name to UPPER_SNAKE_CASE binding name.
-   *
-   * @param queueName - Queue name (e.g., 'notifications-queue')
-   * @returns Cloudflare Queue binding
-   * @throws {QueueBindingNotFoundError} If binding not found in env
-   */
-  private getQueue;
-}
-//#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
- *
- * @example Testing with sync provider
- * ```typescript
- * const provider = new SyncQueueProvider(registry)
- * await provider.send('notifications-queue', {
- *   id: '123',
- *   timestamp: Date.now(),
- *   type: 'email.send',
- *   payload: { to: 'test@example.com' }
- * })
- * // Consumer's handle() is called immediately!
- * ```
- */
-declare class SyncQueueProvider implements IQueueProvider {
-  private readonly registry;
-  constructor(registry: ConsumerRegistry);
-  /**
-   * Process a message synchronously
-   *
-   * Finds all matching consumers by message type and calls their handle() method.
-   * If any consumer throws, onError() is called and the error is re-thrown.
-   *
-   * @param _queueName - Queue name (not used for routing, consumers match by message type)
-   * @param message - Complete message with id, timestamp, and payload
-   * @throws Re-throws any error from consumer.handle() after calling onError()
-   */
-  send<T>(_queueName: string, message: QueueMessage<T>): Promise<void>;
-}
-//#endregion
-//#region src/queue/queue-sender.d.ts
-/**
- * Queue Sender
- *
- * Implementation of IQueueSender bound to a specific queue name.
- * Created by QueueRegistry for each registered queue.
- *
- * Automatically enriches messages with:
- * - `id`: UUID generated via crypto.randomUUID()
- * - `timestamp`: Current time in milliseconds
- * - `metadata.locale`: Current locale from I18n context
- *
- * @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 queueName;
-  private readonly provider;
-  private readonly i18n;
-  constructor(queueName: string, provider: IQueueProvider, i18n: II18nService);
-  /**
-   * Dispatch a message to this queue.
-   *
-   * @param message - Message to dispatch (without id/timestamp)
-   */
-  dispatch<T>(message: DispatchMessage<T>): Promise<void>;
-}
-//#endregion
-//#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';
-}
-declare class QueueModule {
-  /**
-   * 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 for injection.
-   *
-   * The queue name serves as both the identifier and the DI injection token.
-   * Queue names are typed via module augmentation of QueueNames interface.
-   *
-   * @param name - Queue name (typed with autocomplete if QueueNames is augmented)
-   * @returns Dynamic module that provides the queue sender
-   *
-   * @example
-   * ```typescript
-   * // In AppModule imports
-   * QueueModule.registerQueue('notifications-queue')
-   *
-   * // Then inject using the queue name
-   * constructor(@InjectQueue('notifications-queue') private queue: IQueueSender) {}
-   * ```
-   */
-  static registerQueue(name: QueueName): DynamicModule;
-}
-//#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 options?;
-  constructor(env: StratalEnv, registry: ConsumerRegistry, options?: QueueModuleOptions | undefined);
-  /**
-   * Create a queue provider based on module configuration
-   *
-   * @returns Queue provider instance
-   * @throws {QueueProviderNotSupportedError} 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 queue name within the request scope.
- *
- * This service is used internally by QueueModule.registerQueue() to provide
- * IQueueSender instances for each registered queue.
- *
- * **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 queue name.
-   *
-   * Senders are cached per queue name within the request scope.
-   *
-   * @param queueName - The queue name to get a sender for
-   * @returns QueueSender bound to the specified queue
-   */
-  getQueue(queueName: string): IQueueSender;
-}
-//#endregion
-//#region src/queue/decorators/inject-queue.decorator.d.ts
-/**
- * Inject a queue sender by name.
- *
- * Queue names are typed via module augmentation of QueueNames interface.
- * The queue name serves as both the identifier and the DI injection token.
- *
- * @param name - Queue name (typed with autocomplete if QueueNames is augmented)
- * @returns Parameter decorator for constructor injection
- *
- * @example
- * ```typescript
- * // Direct injection by queue name
- * constructor(
- *   @InjectQueue('notifications-queue') private queue: IQueueSender
- * ) {}
- *
- * // Usage
- * await this.queue.dispatch({
- *   type: 'email.send',
- *   payload: { to: 'user@example.com', subject: 'Hello' }
- * })
- * ```
- *
- * @remarks
- * The queue must be registered via `QueueModule.registerQueue(name)` before injection.
- * For module-internal queue bindings (e.g., EmailModule), use `@inject(TOKEN)` with
- * `useExisting` provider binding instead.
- */
-declare function InjectQueue(name: QueueName): ParameterDecorator;
-//#endregion
-//#region src/queue/queue.tokens.d.ts
-declare const QUEUE_TOKENS: {
-  readonly QueueProviderFactory: symbol;
-  readonly QueueRegistry: symbol;
-  readonly QueueModuleOptions: symbol;
-};
-type QueueToken = (typeof QUEUE_TOKENS)[keyof typeof QUEUE_TOKENS];
-//#endregion
-//#region src/queue/errors/queue-binding-not-found.error.d.ts
-/**
- * QueueBindingNotFoundError
- *
- * Thrown when attempting to access a Cloudflare Queue binding that hasn't been configured.
- * This typically indicates that the queue binding is missing from wrangler.jsonc
- * or the environment variables are not properly set.
- */
-declare class QueueBindingNotFoundError extends ApplicationError {
-  constructor(queueName: string, bindingName: string);
-}
-//#endregion
-//#region src/queue/errors/queue-provider-not-supported.error.d.ts
-/**
- * QueueProviderNotSupportedError
- *
- * Thrown when attempting to use a queue provider that is not supported.
- * Valid providers are: 'cloudflare', 'sync'
- *
- * This typically indicates an invalid QUEUE_PROVIDER environment variable.
- */
-declare class QueueProviderNotSupportedError extends ApplicationError {
-  constructor(provider: string);
-}
-//#endregion
-export { QueueNames as _, InjectQueue as a, QueueModule as c, SyncQueueProvider as d, CloudflareQueueProvider as f, QueueName as g, IQueueSender as h, QueueToken as i, QueueModuleOptions as l, DispatchMessage as m, QueueBindingNotFoundError as n, QueueRegistry as o, IQueueProvider as p, QUEUE_TOKENS as r, QueueProviderFactory as s, QueueProviderNotSupportedError as t, QueueSender as u, QueueManager as v };
-//# sourceMappingURL=index-DUzWs0z7.d.mts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index-DUzWs0z7.d.mts","names":[],"sources":["../src/queue/queue-manager.ts","../src/queue/queue-name.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/queue.module.ts","../src/queue/services/queue-provider-factory.ts","../src/queue/queue-registry.ts","../src/queue/decorators/inject-queue.decorator.ts","../src/queue/queue.tokens.ts","../src/queue/errors/queue-binding-not-found.error.ts","../src/queue/errors/queue-provider-not-supported.error.ts"],"mappings":"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"}

package/dist/index.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/stratal.ts"],"mappings":";;;;;;AAqBA;;;;;;;;;;;;cAAa,OAAA,aAAoB,UAAA,GAAa,UAAA;EAAA,QACpC,GAAA;EAAA,QACA,WAAA;EAAA,eAEO,YAAA;EAAA,eACA,WAAA;EAAA,eACA,iBAAA;cAEH,MAAA,EAAQ,iBAAA;EAiBd,KAAA,CAAM,OAAA,EAAS,OAAA,EAAS,GAAA,EAAK,GAAA,EAAK,GAAA,EAAK,gBAAA,GAAmB,OAAA,CAAQ,QAAA;EAMlE,KAAA,CAAM,KAAA,EAAO,YAAA,GAAe,OAAA;EAK5B,SAAA,CAAU,UAAA,EAAY,mBAAA,GAAsB,OAAA;EAAA,IAK9C,IAAA,CAAA,GAAQ,OAAA,CAAQ,OAAA;EAId,QAAA,CAAA,GAAY,OAAA;EA7C0B;;;;;;EAAA,OA2DrC,kBAAA,CAAA,GAAsB,OAAA,CAAQ,WAAA;EAAA,QAOvB,WAAA;EAAA,QAKA,UAAA;AAAA"}