stratal 0.0.20 → 0.0.22

package/dist/{index-CjaQ6_tZ.d.mts → index-CW1YHSft.d.mts}

@@ -1,93 +1,30 @@
-import { d as ApplicationError, gn as AsyncModuleOptions, vn as DynamicModule } from "./index-D0US0X14.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";
+import { Sn as AsyncModuleOptions, wn as DynamicModule, xr as ApplicationError } from "./index-DEncMcC6.mjs";
+import { t as StratalEnv } from "./env-DKSbuBi5.mjs";
+import { p as II18nService } from "./zod-DvWTfRpI.mjs";
+import { r as LoggerService } from "./index-BtlE9RuO.mjs";
+import { r as QueueMessage, t as ConsumerRegistry } from "./consumer-registry-DHQtypr1.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>;
+  private readonly logger;
+  constructor(registry: ConsumerRegistry, logger: LoggerService);
+  processBatch(queueName: string, batch: MessageBatch): Promise<void>;
 }
 //#endregion
-//#region src/queue/queue-name.d.ts
+//#region src/queue/queue-binding.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
- *   }
- * }
- * ```
+ * String keys of `StratalEnv` whose value type is `Queue`.
  */
-interface QueueNames {}
+type QueueBindingFromEnv = Extract<{ [K in keyof StratalEnv]: StratalEnv[K] extends Queue ? K : never }[keyof StratalEnv], string>;
 /**
- * Queue name type - extracts keys from QueueNames or falls back to string.
+ * Type-safe queue binding identifier.
  *
- * 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.
+ * Resolves to the union of `Queue`-typed binding keys on the augmented
+ * `StratalEnv`. Falls back to `string` when no `Queue` bindings are visible
+ * (e.g. library code compiled outside an app's env context).
  */
-type QueueName = keyof QueueNames extends never ? string : keyof QueueNames;
+type QueueBinding = [QueueBindingFromEnv] extends [never] ? string : QueueBindingFromEnv;
 //#endregion
 //#region src/queue/queue-sender.interface.d.ts
 /**
@@ -149,7 +86,7 @@ interface IQueueSender {
  * @example Implementing a custom provider
  * ```typescript
  * export class CustomQueueProvider implements IQueueProvider {
- *   async send<T>(queueName: string, message: QueueMessage<T>): Promise<void> {
+ *   async send<T>(binding: string, message: QueueMessage<T>): Promise<void> {
  *     // Custom implementation
  *   }
  * }
@@ -160,30 +97,27 @@ interface IQueueProvider {
    * Send a message to a queue
    *
    * Provider handles the actual delivery mechanism:
-   * - CloudflareQueueProvider: Resolves CF binding and calls queue.send()
+   * - CloudflareQueueProvider: Looks up the binding on env and calls queue.send()
    * - SyncQueueProvider: Finds matching consumers and calls handle() directly
    *
-   * @param queueName - Queue name
+   * @param binding - Queue binding identifier
    * @param message - Complete message with id, timestamp, and metadata
    */
-  send<T>(queueName: string, message: QueueMessage<T>): Promise<void>;
+  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 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`
+ * 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)
+ * await provider.send('NOTIFICATIONS_QUEUE', message)
  * ```
  */
 declare class CloudflareQueueProvider implements IQueueProvider {
@@ -192,21 +126,11 @@ declare class CloudflareQueueProvider implements IQueueProvider {
   /**
    * Send a message to a Cloudflare Queue
    *
-   * @param queueName - Queue name (e.g., 'notifications-queue')
+   * @param binding - Queue binding identifier (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
+   * @throws {QueueError} If the binding is not configured on env
    */
-  private getQueue;
+  send<T>(binding: string, message: QueueMessage<T>): Promise<void>;
 }
 //#endregion
 //#region src/queue/providers/sync-queue.provider.d.ts
@@ -230,7 +154,7 @@ declare class CloudflareQueueProvider implements IQueueProvider {
  * @example Testing with sync provider
  * ```typescript
  * const provider = new SyncQueueProvider(registry)
- * await provider.send('notifications-queue', {
+ * await provider.send('NOTIFICATIONS_QUEUE', {
  *   id: '123',
  *   timestamp: Date.now(),
  *   type: 'email.send',
@@ -248,19 +172,19 @@ declare class SyncQueueProvider implements IQueueProvider {
    * 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 _binding - Queue binding (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>;
+  send<T>(_binding: 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.
+ * 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()
@@ -270,7 +194,7 @@ declare class SyncQueueProvider implements IQueueProvider {
  * @example
  * ```typescript
  * // Created by QueueRegistry, not directly instantiated
- * const sender = registry.getQueue('notifications-queue')
+ * const sender = registry.getQueue('NOTIFICATIONS_QUEUE')
  *
  * await sender.dispatch({
  *   type: 'email.send',
@@ -279,10 +203,10 @@ declare class SyncQueueProvider implements IQueueProvider {
  * ```
  */
 declare class QueueSender implements IQueueSender {
-  private readonly queueName;
+  private readonly binding;
   private readonly provider;
   private readonly i18n;
-  constructor(queueName: string, provider: IQueueProvider, i18n: II18nService);
+  constructor(binding: string, provider: IQueueProvider, i18n: II18nService);
   /**
    * Dispatch a message to this queue.
    *
@@ -324,24 +248,26 @@ declare class QueueModule {
    */
   static forRootAsync(options: AsyncModuleOptions<QueueModuleOptions>): DynamicModule;
   /**
-   * Register a queue for injection.
+   * Register a queue binding 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.
+   * 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 name - Queue name (typed with autocomplete if QueueNames is augmented)
+   * @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')
+   * QueueModule.registerQueue('NOTIFICATIONS_QUEUE')
    *
-   * // Then inject using the queue name
-   * constructor(@InjectQueue('notifications-queue') private queue: IQueueSender) {}
+   * // Then inject using the binding name
+   * constructor(@InjectQueue('NOTIFICATIONS_QUEUE') private queue: IQueueSender) {}
    * ```
    */
-  static registerQueue(name: QueueName): DynamicModule;
+  static registerQueue(binding: QueueBinding): DynamicModule;
 }
 //#endregion
 //#region src/queue/services/queue-provider-factory.d.ts
@@ -377,7 +303,7 @@ declare class QueueProviderFactory {
    * Create a queue provider based on module configuration
    *
    * @returns Queue provider instance
-   * @throws {QueueProviderNotSupportedError} If provider type is not supported
+   * @throws {QueueError} If provider type is not supported
    */
   create(): IQueueProvider;
 }
@@ -387,10 +313,10 @@ declare class QueueProviderFactory {
  * Queue Registry
  *
  * Request-scoped factory service for creating QueueSender instances.
- * Caches senders per queue name within the request scope.
+ * Caches senders per binding within the request scope.
  *
  * This service is used internally by QueueModule.registerQueue() to provide
- * IQueueSender instances for each registered queue.
+ * IQueueSender instances for each registered binding.
  *
  * **Why request-scoped?**
  * - Needs access to I18nService for locale-aware message metadata
@@ -400,12 +326,12 @@ declare class QueueProviderFactory {
  * @example
  * ```typescript
  * // Used internally by QueueModule.registerQueue()
- * QueueModule.registerQueue('notifications-queue')
+ * QueueModule.registerQueue('NOTIFICATIONS_QUEUE')
  *
  * // The module creates a factory provider:
  * {
- *   provide: 'notifications-queue',
- *   useFactory: (registry: QueueRegistry) => registry.getQueue('notifications-queue'),
+ *   provide: 'NOTIFICATIONS_QUEUE',
+ *   useFactory: (registry: QueueRegistry) => registry.getQueue('NOTIFICATIONS_QUEUE'),
  *   inject: [QUEUE_TOKENS.QueueRegistry],
  * }
  * ```
@@ -416,34 +342,34 @@ declare class QueueRegistry {
   private readonly senders;
   constructor(providerFactory: QueueProviderFactory, i18n: II18nService);
   /**
-   * Get or create a QueueSender for the specified queue name.
+   * Get or create a QueueSender for the specified binding.
    *
-   * Senders are cached per queue name within the request scope.
+   * Senders are cached per binding within the request scope.
    *
-   * @param queueName - The queue name to get a sender for
-   * @returns QueueSender bound to the specified queue
+   * @param binding - The queue binding to get a sender for
+   * @returns QueueSender bound to the specified binding
    */
-  getQueue(queueName: string): IQueueSender;
+  getQueue(binding: string): IQueueSender;
 }
 //#endregion
 //#region src/queue/decorators/inject-queue.decorator.d.ts
 /**
- * Inject a queue sender by name.
+ * Inject a queue sender by binding name.
  *
- * Queue names are typed via module augmentation of QueueNames interface.
- * The queue name serves as both the identifier and the DI injection token.
+ * 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 name - Queue name (typed with autocomplete if QueueNames is augmented)
+ * @param binding - Queue binding identifier (typed against `StratalEnv`).
  * @returns Parameter decorator for constructor injection
  *
  * @example
  * ```typescript
- * // Direct injection by queue name
  * constructor(
- *   @InjectQueue('notifications-queue') private queue: IQueueSender
+ *   @InjectQueue('NOTIFICATIONS_QUEUE') private queue: IQueueSender
  * ) {}
  *
- * // Usage
  * await this.queue.dispatch({
  *   type: 'email.send',
  *   payload: { to: 'user@example.com', subject: 'Hello' }
@@ -451,11 +377,11 @@ declare class QueueRegistry {
  * ```
  *
  * @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.
+ * 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(name: QueueName): ParameterDecorator;
+declare function InjectQueue(binding: QueueBinding): ParameterDecorator;
 //#endregion
 //#region src/queue/queue.tokens.d.ts
 declare const QUEUE_TOKENS: {
@@ -465,30 +391,8 @@ declare const QUEUE_TOKENS: {
 };
 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);
-}
+//#region src/queue/queue.error.d.ts
+declare class QueueError extends ApplicationError {}
 //#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-CjaQ6_tZ.d.mts.map
+export { QueueRegistry as a, QueueModuleOptions as c, CloudflareQueueProvider as d, IQueueProvider as f, QueueManager as g, QueueBinding as h, InjectQueue as i, QueueSender as l, IQueueSender as m, QUEUE_TOKENS as n, QueueProviderFactory as o, DispatchMessage as p, QueueToken as r, QueueModule as s, QueueError as t, SyncQueueProvider as u };
+//# sourceMappingURL=index-CW1YHSft.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-CW1YHSft.d.mts","names":[],"sources":["../src/queue/queue-manager.ts","../src/queue/queue-binding.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/queue.error.ts"],"mappings":";;;;;;;cAQa,YAAA;EAAA,iBAE4C,QAAA;EAAA,iBACC,MAAA;cADD,QAAA,EAAU,gBAAA,EACT,MAAA,EAAQ,aAAA;EAG1D,YAAA,CAAa,SAAA,UAAmB,KAAA,EAAO,YAAA,GAAe,OAAA;AAAA;;;;;;KCUzD,mBAAA,GAAsB,OAAA,eACX,UAAA,GAAa,UAAA,CAAW,CAAA,UAAW,KAAA,GAAQ,CAAA,iBAAkB,UAAA;;;;;;;;KAWjE,YAAA,IAAgB,mBAAA,6BAExB,mBAAA;;;;;;;;;KC9BQ,eAAA,gBAA+B,IAAA,CAAK,YAAA,CAAa,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;UA0B5C,YAAA;EDVZ;;;;;;;;;;ECqBH,QAAA,IAAY,OAAA,EAAS,eAAA,CAAgB,CAAA,IAAK,OAAA;AAAA;;;;;;;;;AFtC5C;;;;;;;;;;;;;UGciB,cAAA;EHViD;;;;;;;;;;EGqBhE,IAAA,IAAQ,OAAA,UAAiB,OAAA,EAAS,YAAA,CAAa,CAAA,IAAK,OAAA;AAAA;;;;;;;AHzBtD;;;;;;;;;cIea,uBAAA,YAAmC,cAAA;EAAA,iBAEM,GAAA;cAAA,GAAA,EAAK,UAAA;EJdQ;;;;;;;EIwB3D,IAAA,GAAA,CAAQ,OAAA,UAAiB,OAAA,EAAS,YAAA,CAAa,CAAA,IAAK,OAAA;AAAA;;;;;;;AJ3B5D;;;;;;;;;;;;;;;;;;;;;;;;;cK8Ba,iBAAA,YAA6B,cAAA;EAAA,iBAEe,QAAA;cAAA,QAAA,EAAU,gBAAA;;;;;;;;;;;EAa3D,IAAA,GAAA,CAAQ,QAAA,UAAkB,OAAA,EAAS,YAAA,CAAa,CAAA,IAAK,OAAA;AAAA;;;;;;;AL7C7D;;;;;;;;;;;;;;;;;;cMoBa,WAAA,YAAuB,YAAA;EAAA,iBAEf,OAAA;EAAA,iBACA,QAAA;EAAA,iBACA,IAAA;cAFA,OAAA,UACA,QAAA,EAAU,cAAA,EACV,IAAA,EAAM,YAAA;;;;ALZa;;EKoBhC,QAAA,GAAA,CAAY,OAAA,EAAS,eAAA,CAAgB,CAAA,IAAK,OAAA;AAAA;;;;;;UCCjC,kBAAA;;ANrBuB;;;;EM2BtC,QAAA;AAAA;AAAA,cAUW,WAAA;EN/B8C;;;;;;;;;;;;;;;AAW3D;;;EAX2D,OMkDlD,YAAA,CAAa,OAAA,EAAS,kBAAA,CAAmB,kBAAA,IAAsB,aAAA;ENrCjD;;;;AC9BvB;;;;;;;;;;;;;;AA0BA;;EDIuB,OMsEd,aAAA,CAAc,OAAA,EAAS,YAAA,GAAe,aAAA;AAAA;;;;;;APrG/C;;;;;;;;;;;;;;;;;;;;cQ2Ba,oBAAA;EAAA,iBAEyC,GAAA;EAAA,iBACG,QAAA;EAAA,iBAC2B,OAAA;cAF9B,GAAA,EAAK,UAAA,EACF,QAAA,EAAU,gBAAA,EACiB,OAAA,GAAU,kBAAA;;APnBtD;;;;;EO4BtC,MAAA,CAAA,GAAU,cAAA;AAAA;;;;;;;ARxCZ;;;;;;;;;;;;;;;;;;;;;;;cS+Ba,aAAA;EAAA,iBAMyC,IAAA;EAAA,iBALnC,QAAA;EAAA,iBACA,OAAA;cAG4B,eAAA,EAAiB,oBAAA,EACV,IAAA,EAAM,YAAA;;;;;;;;;EAa1D,QAAA,CAAS,OAAA,WAAkB,YAAA;AAAA;;;;;;;;;ATlD7B;;;;;;;;;;;;;;;;;;;;;;iBUwBgB,WAAA,CAAY,OAAA,EAAS,YAAA,GAAe,kBAAA;;;cC/BvC,YAAA;EAAA;;;;KAMD,UAAA,WAAqB,YAAA,eAA2B,YAAA;;;cCJ/C,UAAA,SAAmB,gBAAA"}