alepha 0.23.0 → 0.24.0

package/dist/queue/core/index.js

@@ -1,4 +1,4 @@
-import { $atom, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, PipelinePrimitive, Primitive, createPrimitive, t } from "alepha";
+import { $atom, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, PipelinePrimitive, Primitive, createPrimitive, z } from "alepha";
 import { $logger } from "alepha/logger";
 import { DateTimeProvider } from "alepha/datetime";
 //#region ../../src/queue/core/primitives/$consumer.ts
@@ -26,10 +26,10 @@ import { DateTimeProvider } from "alepha/datetime";
 * class EmailService {
 *   emailQueue = $queue({
 *     name: "emails",
-*     schema: t.object({
-*       to: t.text(),
-*       subject: t.text(),
-*       body: t.text()
+*     schema: z.object({
+*       to: z.text(),
+*       subject: z.text(),
+*       body: z.text()
 *     })
 *   });
 *
@@ -84,19 +84,10 @@ var QueueProvider = class {};
 */
 const queueWorkerOptions = $atom({
 	name: "alepha.queue.worker.options",
-	schema: t.object({
-		interval: t.integer({
-			default: 1e3,
-			description: "Interval in milliseconds to wait before checking for new messages."
-		}),
-		maxInterval: t.integer({
-			default: 32e3,
-			description: "Maximum interval in milliseconds to wait before checking for new messages."
-		}),
-		concurrency: t.integer({
-			default: 1,
-			description: "Number of workers to run concurrently. Useful only if you are doing a lot of I/O."
-		})
+	schema: z.object({
+		interval: z.integer().describe("Interval in milliseconds to wait before checking for new messages.").default(1e3),
+		maxInterval: z.integer().describe("Maximum interval in milliseconds to wait before checking for new messages.").default(32e3),
+		concurrency: z.integer().describe("Number of workers to run concurrently. Useful only if you are doing a lot of I/O.").default(1)
 	}),
 	default: {
 		interval: 1e3,
@@ -250,62 +241,43 @@ var WorkerProvider = class {
 /**
 * Creates a queue primitive for asynchronous message processing with background workers.
 *
-* The $queue primitive enables powerful asynchronous communication patterns in your application.
-* It provides type-safe message queuing with automatic worker processing, making it perfect for
-* decoupling components and handling background tasks efficiently.
+* `$queue` is the **raw transport layer**: it fans messages out to background
+* workers over the configured backend with type-safe payloads. Delivery is
+* **at-most-once** — a message is popped from the backend before the handler
+* runs, so a handler error or a process crash loses it. There is no retry,
+* no dead-letter queue, and no delivery guarantee at this layer.
 *
-* **Background Processing**
-* - Automatic worker threads for non-blocking message processing
-* - Built-in retry mechanisms and error handling
-* - Dead letter queues for failed message handling
-* - Graceful shutdown and worker lifecycle management
+* **For work that must not be lost, use `$job` (alepha/api/jobs) instead.**
+* It layers a durable, DB-backed outbox over this transport: at-least-once
+* delivery, retries, idempotency keys, priorities, crash recovery via a
+* reconciliation sweep, and failure records.
 *
-* **Type Safety**
-* - Full TypeScript support with schema validation using TypeBox
-* - Type-safe message payloads with automatic inference
-* - Runtime validation of all queued messages
-* - Compile-time errors for invalid message structures
+* **What $queue gives you**
+* - Type-safe payloads with schema validation at push and receive
+* - Background workers with graceful shutdown and lifecycle management
+* - Pluggable backends: memory (dev/test), Redis, Cloudflare Queues
+* - Cheap fire-and-forget fan-out where occasional loss is acceptable
+*   (cache invalidation, presence pings, metrics, live notifications)
 *
-* **Storage Flexibility**
-* - Memory provider for development and testing
-* - Redis provider for production scalability and persistence
-* - Custom provider support for specialized backends
-* - Automatic failover and connection pooling
-*
-* **Performance & Scalability**
-* - Batch processing support for high-throughput scenarios
-* - Horizontal scaling with distributed queue backends
-* - Configurable concurrency and worker pools
-* - Efficient serialization and message routing
-*
-* **Reliability**
-* - Message persistence across application restarts
-* - Automatic retry with exponential backoff
-* - Dead letter handling for permanently failed messages
-* - Comprehensive logging and monitoring integration
-*
-* @example Basic notification queue
+* @example Loss-tolerant event fan-out
 * ```typescript
-* const emailQueue = $queue({
-*   name: "email-notifications",
-*   schema: t.object({
-*     to: t.text(),
-*     subject: t.text(),
-*     body: t.text(),
-*     priority: t.optional(t.enum(["high", "normal"]))
+* const activityQueue = $queue({
+*   name: "activity-events",
+*   schema: z.object({
+*     userId: z.text(),
+*     event: z.text(),
+*     at: z.number()
 *   }),
 *   handler: async (message) => {
-*     await emailService.send(message.payload);
-*     console.log(`Email sent to ${message.payload.to}`);
+*     await metrics.track(message.payload);
 *   }
 * });
 *
 * // Push messages for background processing
-* await emailQueue.push({
-*   to: "user@example.com",
-*   subject: "Welcome!",
-*   body: "Welcome to our platform",
-*   priority: "high"
+* await activityQueue.push({
+*   userId: "u1",
+*   event: "page-view",
+*   at: 1700000000000
 * });
 * ```
 *
@@ -314,9 +286,9 @@ var WorkerProvider = class {
 * const imageQueue = $queue({
 *   name: "image-processing",
 *   provider: RedisQueueProvider,
-*   schema: t.object({
-*     imageId: t.text(),
-*     operations: t.array(t.enum(["resize", "compress", "thumbnail"]))
+*   schema: z.object({
+*     imageId: z.text(),
+*     operations: z.array(z.enum(["resize", "compress", "thumbnail"]))
 *   }),
 *   handler: async (message) => {
 *     for (const op of message.payload.operations) {
@@ -338,9 +310,9 @@ var WorkerProvider = class {
 * const taskQueue = $queue({
 *   name: "dev-tasks",
 *   provider: "memory",
-*   schema: t.object({
-*     taskType: t.enum(["cleanup", "backup", "report"]),
-*     data: t.record(t.text(), t.any())
+*   schema: z.object({
+*     taskType: z.enum(["cleanup", "backup", "report"]),
+*     data: z.record(z.text(), z.any())
 *   }),
 *   handler: async (message) => {
 *     switch (message.payload.taskType) {
@@ -390,6 +362,11 @@ $queue[KIND] = QueuePrimitive;
 */
 const QUEUE_DEFAULT_BINDING = "JOBS_QUEUE";
 /**
+* How many times Cloudflare redelivers a message before routing it to the
+* consumer's dead-letter queue. Matches Cloudflare's own default.
+*/
+const QUEUE_DEFAULT_MAX_RETRIES = 3;
+/**
 * Cloudflare Queue provider.
 *
 * Uses a Queue binding for message dispatch. Messages are wrapped with the
@@ -465,6 +442,6 @@ const AlephaQueue = $module({
 	}).with(WorkerProvider)
 });
 //#endregion
-export { $consumer, $queue, AlephaQueue, CloudflareQueueProvider, ConsumerPrimitive, MemoryQueueProvider, QUEUE_DEFAULT_BINDING, QueuePrimitive, QueueProvider, WorkerProvider, queueWorkerOptions };
+export { $consumer, $queue, AlephaQueue, CloudflareQueueProvider, ConsumerPrimitive, MemoryQueueProvider, QUEUE_DEFAULT_BINDING, QUEUE_DEFAULT_MAX_RETRIES, QueuePrimitive, QueueProvider, WorkerProvider, queueWorkerOptions };
 
 //# sourceMappingURL=index.js.map

package/dist/queue/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/queue/core/primitives/$consumer.ts","../../../src/queue/core/providers/MemoryQueueProvider.ts","../../../src/queue/core/providers/QueueProvider.ts","../../../src/queue/core/providers/WorkerProvider.ts","../../../src/queue/core/primitives/$queue.ts","../../../src/queue/core/providers/CloudflareQueueProvider.ts","../../../src/queue/core/index.ts"],"sourcesContent":["import {\n  createPrimitive,\n  KIND,\n  PipelinePrimitive,\n  type PipelinePrimitiveOptions,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport type { QueuePrimitive } from \"./$queue.ts\";\n\n/**\n * Creates a consumer primitive to process messages from a specific queue.\n *\n * Provides a dedicated message consumer that connects to a queue and processes messages\n * with custom handler logic, enabling scalable architectures where multiple consumers\n * can process messages from the same queue.\n *\n * **Key Features**\n * - Seamless integration with any $queue primitive\n * - Full type safety inherited from queue schema\n * - Automatic worker management for background processing\n * - Built-in error handling and retry mechanisms\n * - Support for multiple consumers per queue for horizontal scaling\n *\n * **Common Use Cases**\n * - Email sending and notification services\n * - Image and media processing workers\n * - Data synchronization and background jobs\n *\n * @example\n * ```ts\n * class EmailService {\n *   emailQueue = $queue({\n *     name: \"emails\",\n *     schema: t.object({\n *       to: t.text(),\n *       subject: t.text(),\n *       body: t.text()\n *     })\n *   });\n *\n *   emailConsumer = $consumer({\n *     queue: this.emailQueue,\n *     handler: async (message) => {\n *       const { to, subject, body } = message.payload;\n *       await this.sendEmail(to, subject, body);\n *     }\n *   });\n *\n *   async sendWelcomeEmail(userEmail: string) {\n *     await this.emailQueue.push({\n *       to: userEmail,\n *       subject: \"Welcome!\",\n *       body: \"Thanks for joining.\"\n *     });\n *   }\n * }\n * ```\n */\nexport const $consumer = <T extends TSchema>(\n  options: ConsumerPrimitiveOptions<T>,\n): ConsumerPrimitive<T> => {\n  return createPrimitive(ConsumerPrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface ConsumerPrimitiveOptions<T extends TSchema>\n  extends PipelinePrimitiveOptions {\n  /**\n   * The queue primitive that this consumer will process messages from.\n   *\n   * This establishes the connection between the consumer and its source queue:\n   * - The consumer inherits the queue's message schema for type safety\n   * - Messages pushed to the queue will be automatically routed to this consumer\n   * - Multiple consumers can be attached to the same queue for parallel processing\n   * - The consumer will use the queue's provider and configuration settings\n   *\n   * **Queue Integration Benefits**:\n   * - Type safety: Consumer handler gets fully typed message payloads\n   * - Schema validation: Messages are validated before reaching the consumer\n   * - Error handling: Failed messages can be retried or moved to dead letter queues\n   * - Monitoring: Queue metrics include consumer processing statistics\n   *\n   * @example\n   * ```ts\n   * // First, define a queue\n   * emailQueue = $queue({\n   *   name: \"emails\",\n   *   schema: t.object({ to: t.text(), subject: t.text() })\n   * });\n   *\n   * // Then, create a consumer for that queue\n   * emailConsumer = $consumer({\n   *   queue: this.emailQueue,  // Reference the queue primitive\n   *   handler: async (message) => { } // process email\n   * });\n   * ```\n   */\n  queue: QueuePrimitive<T>;\n\n  /**\n   * Message handler function that processes individual messages from the queue.\n   *\n   * This function:\n   * - Receives fully typed and validated message payloads from the connected queue\n   * - Runs in the background worker system for non-blocking operation\n   * - Should implement the core business logic for processing this message type\n   * - Can throw errors to trigger the queue's retry mechanisms\n   * - Has access to the full Alepha dependency injection container\n   * - Should be idempotent to handle potential duplicate deliveries\n   *\n   * **Handler Design Guidelines**:\n   * - Keep handlers focused on a single responsibility\n   * - Use proper error handling and meaningful error messages\n   * - Log important processing steps for debugging and monitoring\n   * - Consider transaction boundaries for data consistency\n   * - Make operations idempotent when possible\n   * - Validate business rules within the handler logic\n   *\n   * **Error Handling Strategy**:\n   * - Throw errors for temporary failures that should be retried\n   * - Log and handle permanent failures gracefully\n   * - Use specific error types to control retry behavior\n   * - Consider implementing circuit breakers for external service calls\n   *\n   * @param message - The queue message containing the validated payload\n   * @param message.payload - The typed message data based on the queue's schema\n   * @returns Promise that resolves when processing is complete\n   *\n   * @example\n   * ```ts\n   * handler: async (message) => {\n   *   const { userId, action, data } = message.payload;\n   *\n   *   try {\n   *     // Log processing start\n   *     this.logger.info(`Processing ${action} for user ${userId}`);\n   *\n   *     // Validate business rules\n   *     if (!await this.userService.exists(userId)) {\n   *       throw new Error(`User ${userId} not found`);\n   *     }\n   *\n   *     // Perform the main processing logic\n   *     switch (action) {\n   *       case \"create\":\n   *         await this.processCreation(userId, data);\n   *         break;\n   *       case \"update\":\n   *         await this.processUpdate(userId, data);\n   *         break;\n   *       default:\n   *         throw new Error(`Unknown action: ${action}`);\n   *     }\n   *\n   *     // Log successful completion\n   *     this.logger.info(`Successfully processed ${action} for user ${userId}`);\n   *\n   *   } catch (error) {\n   *     // Log error with context\n   *     this.logger.error(`Failed to process ${action} for user ${userId}`, {\n   *       error: error.message,\n   *       userId,\n   *       action,\n   *       data\n   *     });\n   *\n   *     // Re-throw to trigger queue retry mechanism\n   *     throw error;\n   *   }\n   * }\n   * ```\n   */\n  handler: (message: { payload: Static<T> }) => Promise<void>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class ConsumerPrimitive<T extends TSchema> extends PipelinePrimitive<\n  ConsumerPrimitiveOptions<T>\n> {}\n\n$consumer[KIND] = ConsumerPrimitive;\n","import { $logger } from \"alepha/logger\";\nimport type { QueueProvider } from \"./QueueProvider.ts\";\n\nexport class MemoryQueueProvider implements QueueProvider {\n  protected readonly log = $logger();\n  protected queueList: Record<string, string[]> = {};\n\n  public async push(queue: string, ...messages: string[]): Promise<void> {\n    if (this.queueList[queue] == null) {\n      this.queueList[queue] = [];\n    }\n\n    this.queueList[queue].push(...messages);\n  }\n\n  public async pop(queue: string): Promise<string | undefined> {\n    return this.queueList[queue]?.shift();\n  }\n}\n","/**\n * Minimalist Queue interface.\n *\n * Will be probably enhanced in the future to support more advanced features. But for now, it's enough!\n */\nexport abstract class QueueProvider {\n  /**\n   * Push a message to the queue.\n   *\n   * @param queue Name of the queue to push the message to.\n   * @param message String message to be pushed to the queue. Buffer messages are not supported for now.\n   */\n  public abstract push(queue: string, message: string): Promise<void>;\n\n  /**\n   * Pop a message from the queue.\n   *\n   * @param queue Name of the queue to pop the message from.\n   *\n   * @returns The message popped or `undefined` if the queue is empty.\n   */\n  public abstract pop(queue: string): Promise<string | undefined>;\n}\n","import {\n  $atom,\n  $hook,\n  $inject,\n  $state,\n  Alepha,\n  type Static,\n  type TSchema,\n  t,\n} from \"alepha\";\nimport { DateTimeProvider } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { $consumer } from \"../primitives/$consumer.ts\";\nimport {\n  $queue,\n  type QueueMessage,\n  type QueuePrimitive,\n} from \"../primitives/$queue.ts\";\nimport { QueueProvider } from \"./QueueProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Queue worker configuration atom.\n */\nexport const queueWorkerOptions = $atom({\n  name: \"alepha.queue.worker.options\",\n  schema: t.object({\n    interval: t.integer({\n      default: 1000,\n      description:\n        \"Interval in milliseconds to wait before checking for new messages.\",\n    }),\n    maxInterval: t.integer({\n      default: 32000,\n      description:\n        \"Maximum interval in milliseconds to wait before checking for new messages.\",\n    }),\n    concurrency: t.integer({\n      default: 1,\n      description:\n        \"Number of workers to run concurrently. Useful only if you are doing a lot of I/O.\",\n    }),\n  }),\n  default: {\n    interval: 1000,\n    maxInterval: 32000,\n    concurrency: 1,\n  },\n});\n\nexport type QueueWorkerOptions = Static<typeof queueWorkerOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [queueWorkerOptions.key]: QueueWorkerOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class WorkerProvider {\n  protected readonly log = $logger();\n  protected readonly options = $state(queueWorkerOptions);\n  protected readonly alepha = $inject(Alepha);\n  protected readonly queueProvider = $inject(QueueProvider);\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n\n  protected workerPromises: Array<Promise<void>> = [];\n  protected workersRunning = 0;\n  protected abortController: AbortController | undefined;\n  protected workerIntervals: Record<number, number> = {};\n  protected consumers: Array<Consumer> = [];\n  protected nextConsumerIndex = 0;\n\n  public get isRunning(): boolean {\n    return this.workersRunning > 0;\n  }\n\n  protected readonly start = $hook({\n    on: \"start\",\n    priority: \"last\",\n    handler: () => {\n      for (const queue of this.alepha.primitives($queue)) {\n        const handler = queue.options.handler;\n        if (handler) {\n          this.consumers.push({\n            handler,\n            queue,\n          });\n        }\n      }\n\n      for (const consumer of this.alepha.primitives($consumer)) {\n        this.consumers.push({\n          queue: consumer.options.queue,\n          handler: (msg) => consumer.handler.run(msg),\n        });\n      }\n\n      if (this.consumers.length > 0) {\n        this.startWorkers();\n        this.log.debug(\n          `Watching for ${this.consumers.length} queue${this.consumers.length > 1 ? \"s\" : \"\"} with ${this.options.concurrency} worker${\n            this.options.concurrency > 1 ? \"s\" : \"\"\n          }.`,\n        );\n      }\n    },\n  });\n\n  // -------------------------------------------------------------------------------------------------------------------\n\n  // Engine part - this is the part that will run the workers and process the messages\n\n  /**\n   * Start the workers.\n   * This method will create an endless loop that will check for new messages!\n   */\n  protected startWorkers(): void {\n    this.abortController ??= new AbortController();\n    const workerToStart = this.options.concurrency - this.workersRunning;\n\n    for (let i = 0; i < workerToStart; i++) {\n      this.workersRunning += 1;\n      this.log.debug(`Starting worker n-${i}`);\n\n      const workerLoop = async () => {\n        while (this.workersRunning > 0) {\n          this.log.trace(`Worker n-${i} is checking for new messages`);\n          const next = await this.getNextMessage();\n          if (next) {\n            this.workerIntervals[i] = 0;\n            await this.processMessage(next);\n          } else {\n            await this.waitForNextMessage(i);\n          }\n        }\n        this.log.info(`Worker n-${i} has stopped`);\n        // Only decrement if we're not already at 0 (shutdown case)\n        if (this.workersRunning > 0) {\n          this.workersRunning -= 1;\n        }\n      };\n\n      this.workerPromises.push(\n        workerLoop().catch((e) => {\n          this.log.error(`Worker n-${i} has crashed`, e);\n          // Always decrement on crash, regardless of shutdown state\n          this.workersRunning = Math.max(0, this.workersRunning - 1);\n        }),\n      );\n    }\n  }\n\n  protected readonly stop = $hook({\n    on: \"stop\",\n    handler: async () => {\n      if (this.consumers.length > 0) {\n        await this.stopWorkers();\n      }\n    },\n  });\n\n  /**\n   * Wait for the next message, where `n` is the worker number.\n   *\n   * This method will wait for a certain amount of time, increasing the wait time again if no message is found.\n   */\n  protected async waitForNextMessage(n: number): Promise<void> {\n    const intervals = this.workerIntervals;\n    const milliseconds = intervals[n] || this.options.interval;\n\n    this.log.trace(`Worker n-${n} is waiting for ${milliseconds}ms.`);\n\n    if (this.abortController?.signal.aborted) {\n      this.log.warn(`Worker n-${n} aborted.`);\n      return;\n    }\n\n    await this.dateTimeProvider.wait(milliseconds, {\n      signal: this.abortController?.signal,\n    });\n\n    if (intervals[n]) {\n      if (intervals[n] < this.options.maxInterval) {\n        intervals[n] = intervals[n] * 2;\n      }\n    } else {\n      intervals[n] = milliseconds;\n    }\n  }\n\n  /**\n   * Get the next message.\n   */\n  protected async getNextMessage(): Promise<undefined | NextMessage> {\n    const len = this.consumers.length;\n    for (let i = 0; i < len; i++) {\n      const idx = (this.nextConsumerIndex + i) % len;\n      const consumer = this.consumers[idx];\n      const provider = consumer.queue.provider;\n      const message = await provider.pop(consumer.queue.name);\n      if (message) {\n        this.nextConsumerIndex = (idx + 1) % len;\n        return { message, consumer };\n      }\n    }\n  }\n\n  /**\n   * Process a message from a queue.\n   */\n  protected async processMessage(response: {\n    message: any;\n    consumer: Consumer;\n  }) {\n    const { message, consumer } = response;\n\n    try {\n      const json = JSON.parse(message);\n      const payload = this.alepha.codec.decode(\n        consumer.queue.options.schema,\n        json.payload,\n      );\n      await this.alepha.context.run(() => consumer.handler({ payload }));\n    } catch (e) {\n      this.log.error(\"Failed to process message\", e);\n    }\n  }\n\n  /**\n   * Stop the workers.\n   *\n   * This method will stop the workers and wait for them to finish processing.\n   */\n  protected async stopWorkers() {\n    this.workersRunning = 0;\n\n    this.log.trace(\"Stopping workers...\");\n    this.abortController?.abort();\n\n    this.log.trace(\"Waiting for workers to finish...\");\n    await Promise.all(this.workerPromises);\n  }\n\n  /**\n   * Force the workers to get back to work.\n   */\n  public wakeUp(): void {\n    this.log.debug(\"Waking up workers...\");\n    this.abortController?.abort();\n    this.abortController = new AbortController();\n\n    // if no workers are running, start them, (should not happen, but just in case)\n    this.startWorkers();\n  }\n}\n\nexport interface Consumer<T extends TSchema = TSchema> {\n  queue: QueuePrimitive<T>;\n  handler: (message: QueueMessage<T>) => Promise<void>;\n}\n\nexport interface NextMessage {\n  consumer: Consumer;\n  message: string;\n}\n","import {\n  $inject,\n  createPrimitive,\n  KIND,\n  Primitive,\n  type Service,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { MemoryQueueProvider } from \"../providers/MemoryQueueProvider.ts\";\nimport { QueueProvider } from \"../providers/QueueProvider.ts\";\nimport { WorkerProvider } from \"../providers/WorkerProvider.ts\";\n\n/**\n * Creates a queue primitive for asynchronous message processing with background workers.\n *\n * The $queue primitive enables powerful asynchronous communication patterns in your application.\n * It provides type-safe message queuing with automatic worker processing, making it perfect for\n * decoupling components and handling background tasks efficiently.\n *\n * **Background Processing**\n * - Automatic worker threads for non-blocking message processing\n * - Built-in retry mechanisms and error handling\n * - Dead letter queues for failed message handling\n * - Graceful shutdown and worker lifecycle management\n *\n * **Type Safety**\n * - Full TypeScript support with schema validation using TypeBox\n * - Type-safe message payloads with automatic inference\n * - Runtime validation of all queued messages\n * - Compile-time errors for invalid message structures\n *\n * **Storage Flexibility**\n * - Memory provider for development and testing\n * - Redis provider for production scalability and persistence\n * - Custom provider support for specialized backends\n * - Automatic failover and connection pooling\n *\n * **Performance & Scalability**\n * - Batch processing support for high-throughput scenarios\n * - Horizontal scaling with distributed queue backends\n * - Configurable concurrency and worker pools\n * - Efficient serialization and message routing\n *\n * **Reliability**\n * - Message persistence across application restarts\n * - Automatic retry with exponential backoff\n * - Dead letter handling for permanently failed messages\n * - Comprehensive logging and monitoring integration\n *\n * @example Basic notification queue\n * ```typescript\n * const emailQueue = $queue({\n *   name: \"email-notifications\",\n *   schema: t.object({\n *     to: t.text(),\n *     subject: t.text(),\n *     body: t.text(),\n *     priority: t.optional(t.enum([\"high\", \"normal\"]))\n *   }),\n *   handler: async (message) => {\n *     await emailService.send(message.payload);\n *     console.log(`Email sent to ${message.payload.to}`);\n *   }\n * });\n *\n * // Push messages for background processing\n * await emailQueue.push({\n *   to: \"user@example.com\",\n *   subject: \"Welcome!\",\n *   body: \"Welcome to our platform\",\n *   priority: \"high\"\n * });\n * ```\n *\n * @example Batch processing with Redis\n * ```typescript\n * const imageQueue = $queue({\n *   name: \"image-processing\",\n *   provider: RedisQueueProvider,\n *   schema: t.object({\n *     imageId: t.text(),\n *     operations: t.array(t.enum([\"resize\", \"compress\", \"thumbnail\"]))\n *   }),\n *   handler: async (message) => {\n *     for (const op of message.payload.operations) {\n *       await processImage(message.payload.imageId, op);\n *     }\n *   }\n * });\n *\n * // Batch processing multiple images\n * await imageQueue.push(\n *   { imageId: \"img1\", operations: [\"resize\", \"thumbnail\"] },\n *   { imageId: \"img2\", operations: [\"compress\"] },\n *   { imageId: \"img3\", operations: [\"resize\", \"compress\", \"thumbnail\"] }\n * );\n * ```\n *\n * @example Development with memory provider\n * ```typescript\n * const taskQueue = $queue({\n *   name: \"dev-tasks\",\n *   provider: \"memory\",\n *   schema: t.object({\n *     taskType: t.enum([\"cleanup\", \"backup\", \"report\"]),\n *     data: t.record(t.text(), t.any())\n *   }),\n *   handler: async (message) => {\n *     switch (message.payload.taskType) {\n *       case \"cleanup\":\n *         await performCleanup(message.payload.data);\n *         break;\n *       case \"backup\":\n *         await createBackup(message.payload.data);\n *         break;\n *       case \"report\":\n *         await generateReport(message.payload.data);\n *         break;\n *     }\n *   }\n * });\n * ```\n */\nexport const $queue = <T extends TSchema>(\n  options: QueuePrimitiveOptions<T>,\n): QueuePrimitive<T> => {\n  return createPrimitive(QueuePrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface QueuePrimitiveOptions<T extends TSchema> {\n  /**\n   * Unique name for the queue.\n   *\n   * This name is used for:\n   * - Queue identification across the system\n   * - Storage backend key generation\n   * - Logging and monitoring\n   * - Worker assignment and routing\n   *\n   * If not provided, defaults to the property key where the queue is declared.\n   *\n   * @example \"email-notifications\"\n   * @example \"image-processing\"\n   * @example \"order-fulfillment\"\n   */\n  name?: string;\n\n  /**\n   * Human-readable description of the queue's purpose.\n   *\n   * Used for:\n   * - Documentation generation\n   * - Monitoring dashboards\n   * - Development team communication\n   * - Queue management interfaces\n   *\n   * @example \"Process user registration emails and welcome sequences\"\n   * @example \"Handle image uploads, resizing, and thumbnail generation\"\n   * @example \"Manage order processing, payment, and shipping workflows\"\n   */\n  description?: string;\n\n  /**\n   * Queue storage provider configuration.\n   *\n   * Options:\n   * - **\"memory\"**: In-memory queue (default for development, lost on restart)\n   * - **Service<QueueProvider>**: Custom provider class (e.g., RedisQueueProvider)\n   * - **undefined**: Uses the default queue provider from dependency injection\n   *\n   * **Provider Selection Guidelines**:\n   * - Development: Use \"memory\" for fast, simple testing\n   * - Production: Use Redis or database-backed providers for persistence\n   * - High-throughput: Use specialized providers with connection pooling\n   * - Distributed systems: Use Redis or message brokers for scalability\n   *\n   * @default Uses injected QueueProvider\n   * @example \"memory\"\n   * @example RedisQueueProvider\n   * @example DatabaseQueueProvider\n   */\n  provider?: \"memory\" | Service<QueueProvider>;\n\n  /**\n   * TypeBox schema defining the structure of messages in this queue.\n   *\n   * This schema:\n   * - Validates all messages pushed to the queue\n   * - Provides full TypeScript type inference\n   * - Ensures type safety between producers and consumers\n   * - Enables automatic serialization/deserialization\n   *\n   * **Schema Design Best Practices**:\n   * - Keep schemas simple and focused on the specific task\n   * - Use optional fields for data that might not always be available\n   * - Include version fields for schema evolution\n   * - Use union types for different message types in the same queue\n   *\n   * @example\n   * ```ts\n   * t.object({\n   *   userId: t.text(),\n   *   action: t.enum([\"create\", \"update\"]),\n   *   data: t.record(t.text(), t.any()),\n   *   timestamp: t.optional(t.number())\n   * })\n   * ```\n   */\n  schema: T;\n\n  /**\n   * Message handler function that processes queue messages.\n   *\n   * This function:\n   * - Runs in background worker threads for non-blocking processing\n   * - Receives type-safe message payloads based on the schema\n   * - Should be idempotent to handle potential retries\n   * - Can throw errors to trigger retry mechanisms\n   * - Has access to the full Alepha dependency injection container\n   *\n   * **Handler Best Practices**:\n   * - Keep handlers focused on a single responsibility\n   * - Use proper error handling and logging\n   * - Make operations idempotent when possible\n   * - Validate critical business logic within handlers\n   * - Consider using transactions for data consistency\n   *\n   * @param message - The queue message with validated payload\n   * @returns Promise that resolves when processing is complete\n   *\n   * @example\n   * ```ts\n   * handler: async (message) => {\n   *   const { userId, email, template } = message.payload;\n   *\n   *   try {\n   *     await this.emailService.send({\n   *       to: email,\n   *       template,\n   *       data: { userId }\n   *     });\n   *\n   *     await this.userService.markEmailSent(userId, template);\n   *   } catch (error) {\n   *     // Log error and let the queue system handle retries\n   *     this.logger.error(`Failed to send email to ${email}`, error);\n   *     throw error;\n   *   }\n   * }\n   * ```\n   */\n  handler?: (message: QueueMessage<T>) => Promise<void>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class QueuePrimitive<T extends TSchema> extends Primitive<\n  QueuePrimitiveOptions<T>\n> {\n  protected readonly log = $logger();\n  protected readonly workerProvider = $inject(WorkerProvider);\n  public readonly provider = this.$provider();\n\n  public async push(...payloads: Array<Static<T>>) {\n    await Promise.all(\n      payloads.map((payload) =>\n        this.provider.push(\n          this.name,\n          JSON.stringify({\n            headers: {},\n            payload: this.alepha.codec.decode(this.options.schema, payload),\n          }),\n        ),\n      ),\n    );\n\n    this.log.debug(`Pushed to queue ${this.name}`, payloads);\n    this.workerProvider.wakeUp();\n  }\n\n  public get name() {\n    return this.options.name || this.config.propertyKey;\n  }\n\n  protected $provider() {\n    if (!this.options.provider) {\n      return this.alepha.inject(QueueProvider);\n    }\n    if (this.options.provider === \"memory\") {\n      return this.alepha.inject(MemoryQueueProvider);\n    }\n    return this.alepha.inject(this.options.provider);\n  }\n}\n\n$queue[KIND] = QueuePrimitive;\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface QueueMessageSchema {\n  payload: TSchema;\n}\n\nexport interface QueueMessage<T extends TSchema> {\n  payload: Static<T>;\n}\n","import { $hook, $inject, Alepha, AlephaError } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { QueueProvider } from \"./QueueProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Cloudflare Queue interface matching the CF Workers Queue API.\n */\nexport interface CloudflareQueue {\n  send(message: unknown): Promise<void>;\n  sendBatch(messages: Array<{ body: unknown }>): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Default queue binding name used in wrangler configuration.\n */\nexport const QUEUE_DEFAULT_BINDING = \"JOBS_QUEUE\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Cloudflare Queue provider.\n *\n * Uses a Queue binding for message dispatch. Messages are wrapped with the\n * logical queue name so the consumer can route them to the correct handler.\n *\n * **Required Cloudflare binding:**\n * - `JOBS_QUEUE` - A Queue binding in wrangler configuration\n *\n * @example\n * ```toml\n * # wrangler.toml - automatically generated by alepha build\n * [[queues.producers]]\n * binding = \"JOBS_QUEUE\"\n * queue = \"my-app-queue\"\n * ```\n */\nexport class CloudflareQueueProvider extends QueueProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n\n  protected queue?: CloudflareQueue;\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      const cloudflareEnv = this.alepha.store.get(\"cloudflare.env\") as\n        | Record<string, unknown>\n        | undefined;\n      if (!cloudflareEnv) {\n        throw new AlephaError(\n          \"Cloudflare Workers environment not found in Alepha store under 'cloudflare.env'.\",\n        );\n      }\n\n      const binding = cloudflareEnv[QUEUE_DEFAULT_BINDING] as\n        | CloudflareQueue\n        | undefined;\n      if (!binding) {\n        throw new AlephaError(\n          `Queue binding '${QUEUE_DEFAULT_BINDING}' not found in Cloudflare Workers environment.`,\n        );\n      }\n\n      this.queue = binding;\n      this.log.info(\"Cloudflare Queue ready\");\n    },\n  });\n\n  public async push(queue: string, message: string): Promise<void> {\n    await this.getQueue().send({ queue, message });\n  }\n\n  /**\n   * Not used on Cloudflare — queue consumption is push-based via the `queue` handler.\n   */\n  public async pop(_queue: string): Promise<string | undefined> {\n    return undefined;\n  }\n\n  protected getQueue(): CloudflareQueue {\n    if (!this.queue) {\n      throw new AlephaError(\n        \"Queue binding not initialized. Call start() first.\",\n      );\n    }\n    return this.queue;\n  }\n}\n","import { $module, type Alepha } from \"alepha\";\nimport { $consumer } from \"./primitives/$consumer.ts\";\nimport { $queue } from \"./primitives/$queue.ts\";\nimport { MemoryQueueProvider } from \"./providers/MemoryQueueProvider.ts\";\nimport { QueueProvider } from \"./providers/QueueProvider.ts\";\nimport { WorkerProvider } from \"./providers/WorkerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$consumer.ts\";\nexport * from \"./primitives/$queue.ts\";\nexport * from \"./providers/CloudflareQueueProvider.ts\";\nexport * from \"./providers/MemoryQueueProvider.ts\";\nexport * from \"./providers/QueueProvider.ts\";\nexport * from \"./providers/WorkerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Asynchronous message processing with automatic worker management.\n *\n * **Features:**\n * - Background job queues with type-safe payloads\n * - Queue consumer handlers\n * - Automatic worker threads for non-blocking processing\n * - Retry mechanisms with exponential backoff\n * - Dead letter queues for failed messages\n * - Batch processing support\n * - Configurable concurrency and worker pools\n * - Providers: Memory (dev), Redis (production)\n *\n * @module alepha.queue\n */\nexport const AlephaQueue = $module({\n  name: \"alepha.queue\",\n  primitives: [$queue, $consumer],\n  services: [QueueProvider, WorkerProvider],\n  variants: [MemoryQueueProvider],\n  register: (alepha: Alepha) =>\n    alepha\n      .with({\n        optional: true,\n        provide: QueueProvider,\n        use: MemoryQueueProvider,\n      })\n      .with(WorkerProvider),\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/queue/core/primitives/$consumer.ts","../../../src/queue/core/providers/MemoryQueueProvider.ts","../../../src/queue/core/providers/QueueProvider.ts","../../../src/queue/core/providers/WorkerProvider.ts","../../../src/queue/core/primitives/$queue.ts","../../../src/queue/core/providers/CloudflareQueueProvider.ts","../../../src/queue/core/index.ts"],"sourcesContent":["import {\n  createPrimitive,\n  KIND,\n  PipelinePrimitive,\n  type PipelinePrimitiveOptions,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport type { QueuePrimitive } from \"./$queue.ts\";\n\n/**\n * Creates a consumer primitive to process messages from a specific queue.\n *\n * Provides a dedicated message consumer that connects to a queue and processes messages\n * with custom handler logic, enabling scalable architectures where multiple consumers\n * can process messages from the same queue.\n *\n * **Key Features**\n * - Seamless integration with any $queue primitive\n * - Full type safety inherited from queue schema\n * - Automatic worker management for background processing\n * - Built-in error handling and retry mechanisms\n * - Support for multiple consumers per queue for horizontal scaling\n *\n * **Common Use Cases**\n * - Email sending and notification services\n * - Image and media processing workers\n * - Data synchronization and background jobs\n *\n * @example\n * ```ts\n * class EmailService {\n *   emailQueue = $queue({\n *     name: \"emails\",\n *     schema: z.object({\n *       to: z.text(),\n *       subject: z.text(),\n *       body: z.text()\n *     })\n *   });\n *\n *   emailConsumer = $consumer({\n *     queue: this.emailQueue,\n *     handler: async (message) => {\n *       const { to, subject, body } = message.payload;\n *       await this.sendEmail(to, subject, body);\n *     }\n *   });\n *\n *   async sendWelcomeEmail(userEmail: string) {\n *     await this.emailQueue.push({\n *       to: userEmail,\n *       subject: \"Welcome!\",\n *       body: \"Thanks for joining.\"\n *     });\n *   }\n * }\n * ```\n */\nexport const $consumer = <T extends TSchema>(\n  options: ConsumerPrimitiveOptions<T>,\n): ConsumerPrimitive<T> => {\n  return createPrimitive(ConsumerPrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface ConsumerPrimitiveOptions<T extends TSchema>\n  extends PipelinePrimitiveOptions {\n  /**\n   * The queue primitive that this consumer will process messages from.\n   *\n   * This establishes the connection between the consumer and its source queue:\n   * - The consumer inherits the queue's message schema for type safety\n   * - Messages pushed to the queue will be automatically routed to this consumer\n   * - Multiple consumers can be attached to the same queue for parallel processing\n   * - The consumer will use the queue's provider and configuration settings\n   *\n   * **Queue Integration Benefits**:\n   * - Type safety: Consumer handler gets fully typed message payloads\n   * - Schema validation: Messages are validated before reaching the consumer\n   * - Error handling: Failed messages can be retried or moved to dead letter queues\n   * - Monitoring: Queue metrics include consumer processing statistics\n   *\n   * @example\n   * ```ts\n   * // First, define a queue\n   * emailQueue = $queue({\n   *   name: \"emails\",\n   *   schema: z.object({ to: z.text(), subject: z.text() })\n   * });\n   *\n   * // Then, create a consumer for that queue\n   * emailConsumer = $consumer({\n   *   queue: this.emailQueue,  // Reference the queue primitive\n   *   handler: async (message) => { } // process email\n   * });\n   * ```\n   */\n  queue: QueuePrimitive<T>;\n\n  /**\n   * Message handler function that processes individual messages from the queue.\n   *\n   * This function:\n   * - Receives fully typed and validated message payloads from the connected queue\n   * - Runs in the background worker system for non-blocking operation\n   * - Should implement the core business logic for processing this message type\n   * - Can throw errors to trigger the queue's retry mechanisms\n   * - Has access to the full Alepha dependency injection container\n   * - Should be idempotent to handle potential duplicate deliveries\n   *\n   * **Handler Design Guidelines**:\n   * - Keep handlers focused on a single responsibility\n   * - Use proper error handling and meaningful error messages\n   * - Log important processing steps for debugging and monitoring\n   * - Consider transaction boundaries for data consistency\n   * - Make operations idempotent when possible\n   * - Validate business rules within the handler logic\n   *\n   * **Error Handling Strategy**:\n   * - Throw errors for temporary failures that should be retried\n   * - Log and handle permanent failures gracefully\n   * - Use specific error types to control retry behavior\n   * - Consider implementing circuit breakers for external service calls\n   *\n   * @param message - The queue message containing the validated payload\n   * @param message.payload - The typed message data based on the queue's schema\n   * @returns Promise that resolves when processing is complete\n   *\n   * @example\n   * ```ts\n   * handler: async (message) => {\n   *   const { userId, action, data } = message.payload;\n   *\n   *   try {\n   *     // Log processing start\n   *     this.logger.info(`Processing ${action} for user ${userId}`);\n   *\n   *     // Validate business rules\n   *     if (!await this.userService.exists(userId)) {\n   *       throw new Error(`User ${userId} not found`);\n   *     }\n   *\n   *     // Perform the main processing logic\n   *     switch (action) {\n   *       case \"create\":\n   *         await this.processCreation(userId, data);\n   *         break;\n   *       case \"update\":\n   *         await this.processUpdate(userId, data);\n   *         break;\n   *       default:\n   *         throw new Error(`Unknown action: ${action}`);\n   *     }\n   *\n   *     // Log successful completion\n   *     this.logger.info(`Successfully processed ${action} for user ${userId}`);\n   *\n   *   } catch (error) {\n   *     // Log error with context\n   *     this.logger.error(`Failed to process ${action} for user ${userId}`, {\n   *       error: error.message,\n   *       userId,\n   *       action,\n   *       data\n   *     });\n   *\n   *     // Re-throw to trigger queue retry mechanism\n   *     throw error;\n   *   }\n   * }\n   * ```\n   */\n  handler: (message: { payload: Static<T> }) => Promise<void>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class ConsumerPrimitive<T extends TSchema> extends PipelinePrimitive<\n  ConsumerPrimitiveOptions<T>\n> {}\n\n$consumer[KIND] = ConsumerPrimitive;\n","import { $logger } from \"alepha/logger\";\nimport type { QueueProvider } from \"./QueueProvider.ts\";\n\nexport class MemoryQueueProvider implements QueueProvider {\n  protected readonly log = $logger();\n  protected queueList: Record<string, string[]> = {};\n\n  public async push(queue: string, ...messages: string[]): Promise<void> {\n    if (this.queueList[queue] == null) {\n      this.queueList[queue] = [];\n    }\n\n    this.queueList[queue].push(...messages);\n  }\n\n  public async pop(queue: string): Promise<string | undefined> {\n    return this.queueList[queue]?.shift();\n  }\n}\n","/**\n * Minimalist Queue interface.\n *\n * Will be probably enhanced in the future to support more advanced features. But for now, it's enough!\n */\nexport abstract class QueueProvider {\n  /**\n   * Push a message to the queue.\n   *\n   * @param queue Name of the queue to push the message to.\n   * @param message String message to be pushed to the queue. Buffer messages are not supported for now.\n   */\n  public abstract push(queue: string, message: string): Promise<void>;\n\n  /**\n   * Pop a message from the queue.\n   *\n   * @param queue Name of the queue to pop the message from.\n   *\n   * @returns The message popped or `undefined` if the queue is empty.\n   */\n  public abstract pop(queue: string): Promise<string | undefined>;\n}\n","import {\n  $atom,\n  $hook,\n  $inject,\n  $state,\n  Alepha,\n  type Static,\n  type TSchema,\n  z,\n} from \"alepha\";\nimport { DateTimeProvider } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { $consumer } from \"../primitives/$consumer.ts\";\nimport {\n  $queue,\n  type QueueMessage,\n  type QueuePrimitive,\n} from \"../primitives/$queue.ts\";\nimport { QueueProvider } from \"./QueueProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Queue worker configuration atom.\n */\nexport const queueWorkerOptions = $atom({\n  name: \"alepha.queue.worker.options\",\n  schema: z.object({\n    interval: z\n      .integer()\n      .describe(\n        \"Interval in milliseconds to wait before checking for new messages.\",\n      )\n      .default(1000),\n    maxInterval: z\n      .integer()\n      .describe(\n        \"Maximum interval in milliseconds to wait before checking for new messages.\",\n      )\n      .default(32000),\n    concurrency: z\n      .integer()\n      .describe(\n        \"Number of workers to run concurrently. Useful only if you are doing a lot of I/O.\",\n      )\n      .default(1),\n  }),\n  default: {\n    interval: 1000,\n    maxInterval: 32000,\n    concurrency: 1,\n  },\n});\n\nexport type QueueWorkerOptions = Static<typeof queueWorkerOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [queueWorkerOptions.key]: QueueWorkerOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class WorkerProvider {\n  protected readonly log = $logger();\n  protected readonly options = $state(queueWorkerOptions);\n  protected readonly alepha = $inject(Alepha);\n  protected readonly queueProvider = $inject(QueueProvider);\n  protected readonly dateTimeProvider = $inject(DateTimeProvider);\n\n  protected workerPromises: Array<Promise<void>> = [];\n  protected workersRunning = 0;\n  protected abortController: AbortController | undefined;\n  protected workerIntervals: Record<number, number> = {};\n  protected consumers: Array<Consumer> = [];\n  protected nextConsumerIndex = 0;\n\n  public get isRunning(): boolean {\n    return this.workersRunning > 0;\n  }\n\n  protected readonly start = $hook({\n    on: \"start\",\n    priority: \"last\",\n    handler: () => {\n      for (const queue of this.alepha.primitives($queue)) {\n        const handler = queue.options.handler;\n        if (handler) {\n          this.consumers.push({\n            handler,\n            queue,\n          });\n        }\n      }\n\n      for (const consumer of this.alepha.primitives($consumer)) {\n        this.consumers.push({\n          queue: consumer.options.queue,\n          handler: (msg) => consumer.handler.run(msg),\n        });\n      }\n\n      if (this.consumers.length > 0) {\n        this.startWorkers();\n        this.log.debug(\n          `Watching for ${this.consumers.length} queue${this.consumers.length > 1 ? \"s\" : \"\"} with ${this.options.concurrency} worker${\n            this.options.concurrency > 1 ? \"s\" : \"\"\n          }.`,\n        );\n      }\n    },\n  });\n\n  // -------------------------------------------------------------------------------------------------------------------\n\n  // Engine part - this is the part that will run the workers and process the messages\n\n  /**\n   * Start the workers.\n   * This method will create an endless loop that will check for new messages!\n   */\n  protected startWorkers(): void {\n    this.abortController ??= new AbortController();\n    const workerToStart = this.options.concurrency - this.workersRunning;\n\n    for (let i = 0; i < workerToStart; i++) {\n      this.workersRunning += 1;\n      this.log.debug(`Starting worker n-${i}`);\n\n      const workerLoop = async () => {\n        while (this.workersRunning > 0) {\n          this.log.trace(`Worker n-${i} is checking for new messages`);\n          const next = await this.getNextMessage();\n          if (next) {\n            this.workerIntervals[i] = 0;\n            await this.processMessage(next);\n          } else {\n            await this.waitForNextMessage(i);\n          }\n        }\n        this.log.info(`Worker n-${i} has stopped`);\n        // Only decrement if we're not already at 0 (shutdown case)\n        if (this.workersRunning > 0) {\n          this.workersRunning -= 1;\n        }\n      };\n\n      this.workerPromises.push(\n        workerLoop().catch((e) => {\n          this.log.error(`Worker n-${i} has crashed`, e);\n          // Always decrement on crash, regardless of shutdown state\n          this.workersRunning = Math.max(0, this.workersRunning - 1);\n        }),\n      );\n    }\n  }\n\n  protected readonly stop = $hook({\n    on: \"stop\",\n    handler: async () => {\n      if (this.consumers.length > 0) {\n        await this.stopWorkers();\n      }\n    },\n  });\n\n  /**\n   * Wait for the next message, where `n` is the worker number.\n   *\n   * This method will wait for a certain amount of time, increasing the wait time again if no message is found.\n   */\n  protected async waitForNextMessage(n: number): Promise<void> {\n    const intervals = this.workerIntervals;\n    const milliseconds = intervals[n] || this.options.interval;\n\n    this.log.trace(`Worker n-${n} is waiting for ${milliseconds}ms.`);\n\n    if (this.abortController?.signal.aborted) {\n      this.log.warn(`Worker n-${n} aborted.`);\n      return;\n    }\n\n    await this.dateTimeProvider.wait(milliseconds, {\n      signal: this.abortController?.signal,\n    });\n\n    if (intervals[n]) {\n      if (intervals[n] < this.options.maxInterval) {\n        intervals[n] = intervals[n] * 2;\n      }\n    } else {\n      intervals[n] = milliseconds;\n    }\n  }\n\n  /**\n   * Get the next message.\n   */\n  protected async getNextMessage(): Promise<undefined | NextMessage> {\n    const len = this.consumers.length;\n    for (let i = 0; i < len; i++) {\n      const idx = (this.nextConsumerIndex + i) % len;\n      const consumer = this.consumers[idx];\n      const provider = consumer.queue.provider;\n      const message = await provider.pop(consumer.queue.name);\n      if (message) {\n        this.nextConsumerIndex = (idx + 1) % len;\n        return { message, consumer };\n      }\n    }\n  }\n\n  /**\n   * Process a message from a queue.\n   */\n  protected async processMessage(response: {\n    message: any;\n    consumer: Consumer;\n  }) {\n    const { message, consumer } = response;\n\n    try {\n      const json = JSON.parse(message);\n      const payload = this.alepha.codec.decode(\n        consumer.queue.options.schema,\n        json.payload,\n      );\n      await this.alepha.context.run(() => consumer.handler({ payload }));\n    } catch (e) {\n      this.log.error(\"Failed to process message\", e);\n    }\n  }\n\n  /**\n   * Stop the workers.\n   *\n   * This method will stop the workers and wait for them to finish processing.\n   */\n  protected async stopWorkers() {\n    this.workersRunning = 0;\n\n    this.log.trace(\"Stopping workers...\");\n    this.abortController?.abort();\n\n    this.log.trace(\"Waiting for workers to finish...\");\n    await Promise.all(this.workerPromises);\n  }\n\n  /**\n   * Force the workers to get back to work.\n   */\n  public wakeUp(): void {\n    this.log.debug(\"Waking up workers...\");\n    this.abortController?.abort();\n    this.abortController = new AbortController();\n\n    // if no workers are running, start them, (should not happen, but just in case)\n    this.startWorkers();\n  }\n}\n\nexport interface Consumer<T extends TSchema = TSchema> {\n  queue: QueuePrimitive<T>;\n  handler: (message: QueueMessage<T>) => Promise<void>;\n}\n\nexport interface NextMessage {\n  consumer: Consumer;\n  message: string;\n}\n","import {\n  $inject,\n  createPrimitive,\n  KIND,\n  Primitive,\n  type Service,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { MemoryQueueProvider } from \"../providers/MemoryQueueProvider.ts\";\nimport { QueueProvider } from \"../providers/QueueProvider.ts\";\nimport { WorkerProvider } from \"../providers/WorkerProvider.ts\";\n\n/**\n * Creates a queue primitive for asynchronous message processing with background workers.\n *\n * `$queue` is the **raw transport layer**: it fans messages out to background\n * workers over the configured backend with type-safe payloads. Delivery is\n * **at-most-once** — a message is popped from the backend before the handler\n * runs, so a handler error or a process crash loses it. There is no retry,\n * no dead-letter queue, and no delivery guarantee at this layer.\n *\n * **For work that must not be lost, use `$job` (alepha/api/jobs) instead.**\n * It layers a durable, DB-backed outbox over this transport: at-least-once\n * delivery, retries, idempotency keys, priorities, crash recovery via a\n * reconciliation sweep, and failure records.\n *\n * **What $queue gives you**\n * - Type-safe payloads with schema validation at push and receive\n * - Background workers with graceful shutdown and lifecycle management\n * - Pluggable backends: memory (dev/test), Redis, Cloudflare Queues\n * - Cheap fire-and-forget fan-out where occasional loss is acceptable\n *   (cache invalidation, presence pings, metrics, live notifications)\n *\n * @example Loss-tolerant event fan-out\n * ```typescript\n * const activityQueue = $queue({\n *   name: \"activity-events\",\n *   schema: z.object({\n *     userId: z.text(),\n *     event: z.text(),\n *     at: z.number()\n *   }),\n *   handler: async (message) => {\n *     await metrics.track(message.payload);\n *   }\n * });\n *\n * // Push messages for background processing\n * await activityQueue.push({\n *   userId: \"u1\",\n *   event: \"page-view\",\n *   at: 1700000000000\n * });\n * ```\n *\n * @example Batch processing with Redis\n * ```typescript\n * const imageQueue = $queue({\n *   name: \"image-processing\",\n *   provider: RedisQueueProvider,\n *   schema: z.object({\n *     imageId: z.text(),\n *     operations: z.array(z.enum([\"resize\", \"compress\", \"thumbnail\"]))\n *   }),\n *   handler: async (message) => {\n *     for (const op of message.payload.operations) {\n *       await processImage(message.payload.imageId, op);\n *     }\n *   }\n * });\n *\n * // Batch processing multiple images\n * await imageQueue.push(\n *   { imageId: \"img1\", operations: [\"resize\", \"thumbnail\"] },\n *   { imageId: \"img2\", operations: [\"compress\"] },\n *   { imageId: \"img3\", operations: [\"resize\", \"compress\", \"thumbnail\"] }\n * );\n * ```\n *\n * @example Development with memory provider\n * ```typescript\n * const taskQueue = $queue({\n *   name: \"dev-tasks\",\n *   provider: \"memory\",\n *   schema: z.object({\n *     taskType: z.enum([\"cleanup\", \"backup\", \"report\"]),\n *     data: z.record(z.text(), z.any())\n *   }),\n *   handler: async (message) => {\n *     switch (message.payload.taskType) {\n *       case \"cleanup\":\n *         await performCleanup(message.payload.data);\n *         break;\n *       case \"backup\":\n *         await createBackup(message.payload.data);\n *         break;\n *       case \"report\":\n *         await generateReport(message.payload.data);\n *         break;\n *     }\n *   }\n * });\n * ```\n */\nexport const $queue = <T extends TSchema>(\n  options: QueuePrimitiveOptions<T>,\n): QueuePrimitive<T> => {\n  return createPrimitive(QueuePrimitive<T>, options);\n};\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface QueuePrimitiveOptions<T extends TSchema> {\n  /**\n   * Unique name for the queue.\n   *\n   * This name is used for:\n   * - Queue identification across the system\n   * - Storage backend key generation\n   * - Logging and monitoring\n   * - Worker assignment and routing\n   *\n   * If not provided, defaults to the property key where the queue is declared.\n   *\n   * @example \"email-notifications\"\n   * @example \"image-processing\"\n   * @example \"order-fulfillment\"\n   */\n  name?: string;\n\n  /**\n   * Human-readable description of the queue's purpose.\n   *\n   * Used for:\n   * - Documentation generation\n   * - Monitoring dashboards\n   * - Development team communication\n   * - Queue management interfaces\n   *\n   * @example \"Process user registration emails and welcome sequences\"\n   * @example \"Handle image uploads, resizing, and thumbnail generation\"\n   * @example \"Manage order processing, payment, and shipping workflows\"\n   */\n  description?: string;\n\n  /**\n   * Queue storage provider configuration.\n   *\n   * Options:\n   * - **\"memory\"**: In-memory queue (default for development, lost on restart)\n   * - **Service<QueueProvider>**: Custom provider class (e.g., RedisQueueProvider)\n   * - **undefined**: Uses the default queue provider from dependency injection\n   *\n   * **Provider Selection Guidelines**:\n   * - Development: Use \"memory\" for fast, simple testing\n   * - Production: Use Redis so multiple instances share one queue (note:\n   *   a popped message is gone — the at-most-once caveat above applies)\n   * - High-throughput: Use specialized providers with connection pooling\n   * - Distributed systems: Use Redis or message brokers for scalability\n   *\n   * @default Uses injected QueueProvider\n   * @example \"memory\"\n   * @example RedisQueueProvider\n   * @example DatabaseQueueProvider\n   */\n  provider?: \"memory\" | Service<QueueProvider>;\n\n  /**\n   * TypeBox schema defining the structure of messages in this queue.\n   *\n   * This schema:\n   * - Validates all messages pushed to the queue\n   * - Provides full TypeScript type inference\n   * - Ensures type safety between producers and consumers\n   * - Enables automatic serialization/deserialization\n   *\n   * **Schema Design Best Practices**:\n   * - Keep schemas simple and focused on the specific task\n   * - Use optional fields for data that might not always be available\n   * - Include version fields for schema evolution\n   * - Use union types for different message types in the same queue\n   *\n   * @example\n   * ```ts\n   * z.object({\n   *   userId: z.text(),\n   *   action: z.enum([\"create\", \"update\"]),\n   *   data: z.record(z.text(), z.any()),\n   *   timestamp: z.number().optional()\n   * })\n   * ```\n   */\n  schema: T;\n\n  /**\n   * Message handler function that processes queue messages.\n   *\n   * This function:\n   * - Runs in background worker threads for non-blocking processing\n   * - Receives type-safe message payloads based on the schema\n   * - Has access to the full Alepha dependency injection container\n   * - **Loses the message if it throws** — errors are logged, not retried.\n   *   Use `$job` when failed work must be retried or recorded.\n   *\n   * **Handler Best Practices**:\n   * - Keep handlers focused on a single responsibility\n   * - Use proper error handling and logging\n   * - Make operations idempotent when possible\n   * - Validate critical business logic within handlers\n   * - Consider using transactions for data consistency\n   *\n   * @param message - The queue message with validated payload\n   * @returns Promise that resolves when processing is complete\n   *\n   * @example\n   * ```ts\n   * handler: async (message) => {\n   *   const { userId, email, template } = message.payload;\n   *\n   *   try {\n   *     await this.emailService.send({\n   *       to: email,\n   *       template,\n   *       data: { userId }\n   *     });\n   *\n   *     await this.userService.markEmailSent(userId, template);\n   *   } catch (error) {\n   *     // The message is NOT redelivered after a throw — record the\n   *     // failure yourself, or use $job for retryable work.\n   *     this.logger.error(`Failed to send email to ${email}`, error);\n   *     throw error;\n   *   }\n   * }\n   * ```\n   */\n  handler?: (message: QueueMessage<T>) => Promise<void>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class QueuePrimitive<T extends TSchema> extends Primitive<\n  QueuePrimitiveOptions<T>\n> {\n  protected readonly log = $logger();\n  protected readonly workerProvider = $inject(WorkerProvider);\n  public readonly provider = this.$provider();\n\n  public async push(...payloads: Array<Static<T>>) {\n    await Promise.all(\n      payloads.map((payload) =>\n        this.provider.push(\n          this.name,\n          JSON.stringify({\n            headers: {},\n            payload: this.alepha.codec.decode(this.options.schema, payload),\n          }),\n        ),\n      ),\n    );\n\n    this.log.debug(`Pushed to queue ${this.name}`, payloads);\n    this.workerProvider.wakeUp();\n  }\n\n  public get name() {\n    return this.options.name || this.config.propertyKey;\n  }\n\n  protected $provider() {\n    if (!this.options.provider) {\n      return this.alepha.inject(QueueProvider);\n    }\n    if (this.options.provider === \"memory\") {\n      return this.alepha.inject(MemoryQueueProvider);\n    }\n    return this.alepha.inject(this.options.provider);\n  }\n}\n\n$queue[KIND] = QueuePrimitive;\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface QueueMessageSchema {\n  payload: TSchema;\n}\n\nexport interface QueueMessage<T extends TSchema> {\n  payload: Static<T>;\n}\n","import { $hook, $inject, Alepha, AlephaError } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { QueueProvider } from \"./QueueProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Cloudflare Queue interface matching the CF Workers Queue API.\n */\nexport interface CloudflareQueue {\n  send(message: unknown): Promise<void>;\n  sendBatch(messages: Array<{ body: unknown }>): Promise<void>;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Default queue binding name used in wrangler configuration.\n */\nexport const QUEUE_DEFAULT_BINDING = \"JOBS_QUEUE\";\n\n/**\n * How many times Cloudflare redelivers a message before routing it to the\n * consumer's dead-letter queue. Matches Cloudflare's own default.\n */\nexport const QUEUE_DEFAULT_MAX_RETRIES = 3;\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Cloudflare Queue provider.\n *\n * Uses a Queue binding for message dispatch. Messages are wrapped with the\n * logical queue name so the consumer can route them to the correct handler.\n *\n * **Required Cloudflare binding:**\n * - `JOBS_QUEUE` - A Queue binding in wrangler configuration\n *\n * @example\n * ```toml\n * # wrangler.toml - automatically generated by alepha build\n * [[queues.producers]]\n * binding = \"JOBS_QUEUE\"\n * queue = \"my-app-queue\"\n * ```\n */\nexport class CloudflareQueueProvider extends QueueProvider {\n  protected readonly alepha = $inject(Alepha);\n  protected readonly log = $logger();\n\n  protected queue?: CloudflareQueue;\n\n  protected readonly onStart = $hook({\n    on: \"start\",\n    handler: async () => {\n      const cloudflareEnv = this.alepha.store.get(\"cloudflare.env\") as\n        | Record<string, unknown>\n        | undefined;\n      if (!cloudflareEnv) {\n        throw new AlephaError(\n          \"Cloudflare Workers environment not found in Alepha store under 'cloudflare.env'.\",\n        );\n      }\n\n      const binding = cloudflareEnv[QUEUE_DEFAULT_BINDING] as\n        | CloudflareQueue\n        | undefined;\n      if (!binding) {\n        throw new AlephaError(\n          `Queue binding '${QUEUE_DEFAULT_BINDING}' not found in Cloudflare Workers environment.`,\n        );\n      }\n\n      this.queue = binding;\n      this.log.info(\"Cloudflare Queue ready\");\n    },\n  });\n\n  public async push(queue: string, message: string): Promise<void> {\n    await this.getQueue().send({ queue, message });\n  }\n\n  /**\n   * Not used on Cloudflare — queue consumption is push-based via the `queue` handler.\n   */\n  public async pop(_queue: string): Promise<string | undefined> {\n    return undefined;\n  }\n\n  protected getQueue(): CloudflareQueue {\n    if (!this.queue) {\n      throw new AlephaError(\n        \"Queue binding not initialized. Call start() first.\",\n      );\n    }\n    return this.queue;\n  }\n}\n","import { $module, type Alepha } from \"alepha\";\nimport { $consumer } from \"./primitives/$consumer.ts\";\nimport { $queue } from \"./primitives/$queue.ts\";\nimport { MemoryQueueProvider } from \"./providers/MemoryQueueProvider.ts\";\nimport { QueueProvider } from \"./providers/QueueProvider.ts\";\nimport { WorkerProvider } from \"./providers/WorkerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$consumer.ts\";\nexport * from \"./primitives/$queue.ts\";\nexport * from \"./providers/CloudflareQueueProvider.ts\";\nexport * from \"./providers/MemoryQueueProvider.ts\";\nexport * from \"./providers/QueueProvider.ts\";\nexport * from \"./providers/WorkerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Asynchronous message processing with automatic worker management.\n *\n * **Features:**\n * - Background job queues with type-safe payloads\n * - Queue consumer handlers\n * - Automatic worker threads for non-blocking processing\n * - Retry mechanisms with exponential backoff\n * - Dead letter queues for failed messages\n * - Batch processing support\n * - Configurable concurrency and worker pools\n * - Providers: Memory (dev), Redis (production)\n *\n * @module alepha.queue\n */\nexport const AlephaQueue = $module({\n  name: \"alepha.queue\",\n  primitives: [$queue, $consumer],\n  services: [QueueProvider, WorkerProvider],\n  variants: [MemoryQueueProvider],\n  register: (alepha: Alepha) =>\n    alepha\n      .with({\n        optional: true,\n        provide: QueueProvider,\n        use: MemoryQueueProvider,\n      })\n      .with(WorkerProvider),\n});\n"],"mappings":"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"}

package/dist/queue/core/index.workerd.js

@@ -1,4 +1,4 @@
-import { $atom, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, PipelinePrimitive, Primitive, createPrimitive, t } from "alepha";
+import { $atom, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, PipelinePrimitive, Primitive, createPrimitive, z } from "alepha";
 import { $logger } from "alepha/logger";
 import { DateTimeProvider } from "alepha/datetime";
 //#region ../../src/queue/core/primitives/$consumer.ts
@@ -26,10 +26,10 @@ import { DateTimeProvider } from "alepha/datetime";
 * class EmailService {
 *   emailQueue = $queue({
 *     name: "emails",
-*     schema: t.object({
-*       to: t.text(),
-*       subject: t.text(),
-*       body: t.text()
+*     schema: z.object({
+*       to: z.text(),
+*       subject: z.text(),
+*       body: z.text()
 *     })
 *   });
 *
@@ -84,19 +84,10 @@ var QueueProvider = class {};
 */
 const queueWorkerOptions = $atom({
 	name: "alepha.queue.worker.options",
-	schema: t.object({
-		interval: t.integer({
-			default: 1e3,
-			description: "Interval in milliseconds to wait before checking for new messages."
-		}),
-		maxInterval: t.integer({
-			default: 32e3,
-			description: "Maximum interval in milliseconds to wait before checking for new messages."
-		}),
-		concurrency: t.integer({
-			default: 1,
-			description: "Number of workers to run concurrently. Useful only if you are doing a lot of I/O."
-		})
+	schema: z.object({
+		interval: z.integer().describe("Interval in milliseconds to wait before checking for new messages.").default(1e3),
+		maxInterval: z.integer().describe("Maximum interval in milliseconds to wait before checking for new messages.").default(32e3),
+		concurrency: z.integer().describe("Number of workers to run concurrently. Useful only if you are doing a lot of I/O.").default(1)
 	}),
 	default: {
 		interval: 1e3,
@@ -250,62 +241,43 @@ var WorkerProvider = class {
 /**
 * Creates a queue primitive for asynchronous message processing with background workers.
 *
-* The $queue primitive enables powerful asynchronous communication patterns in your application.
-* It provides type-safe message queuing with automatic worker processing, making it perfect for
-* decoupling components and handling background tasks efficiently.
+* `$queue` is the **raw transport layer**: it fans messages out to background
+* workers over the configured backend with type-safe payloads. Delivery is
+* **at-most-once** — a message is popped from the backend before the handler
+* runs, so a handler error or a process crash loses it. There is no retry,
+* no dead-letter queue, and no delivery guarantee at this layer.
 *
-* **Background Processing**
-* - Automatic worker threads for non-blocking message processing
-* - Built-in retry mechanisms and error handling
-* - Dead letter queues for failed message handling
-* - Graceful shutdown and worker lifecycle management
+* **For work that must not be lost, use `$job` (alepha/api/jobs) instead.**
+* It layers a durable, DB-backed outbox over this transport: at-least-once
+* delivery, retries, idempotency keys, priorities, crash recovery via a
+* reconciliation sweep, and failure records.
 *
-* **Type Safety**
-* - Full TypeScript support with schema validation using TypeBox
-* - Type-safe message payloads with automatic inference
-* - Runtime validation of all queued messages
-* - Compile-time errors for invalid message structures
+* **What $queue gives you**
+* - Type-safe payloads with schema validation at push and receive
+* - Background workers with graceful shutdown and lifecycle management
+* - Pluggable backends: memory (dev/test), Redis, Cloudflare Queues
+* - Cheap fire-and-forget fan-out where occasional loss is acceptable
+*   (cache invalidation, presence pings, metrics, live notifications)
 *
-* **Storage Flexibility**
-* - Memory provider for development and testing
-* - Redis provider for production scalability and persistence
-* - Custom provider support for specialized backends
-* - Automatic failover and connection pooling
-*
-* **Performance & Scalability**
-* - Batch processing support for high-throughput scenarios
-* - Horizontal scaling with distributed queue backends
-* - Configurable concurrency and worker pools
-* - Efficient serialization and message routing
-*
-* **Reliability**
-* - Message persistence across application restarts
-* - Automatic retry with exponential backoff
-* - Dead letter handling for permanently failed messages
-* - Comprehensive logging and monitoring integration
-*
-* @example Basic notification queue
+* @example Loss-tolerant event fan-out
 * ```typescript
-* const emailQueue = $queue({
-*   name: "email-notifications",
-*   schema: t.object({
-*     to: t.text(),
-*     subject: t.text(),
-*     body: t.text(),
-*     priority: t.optional(t.enum(["high", "normal"]))
+* const activityQueue = $queue({
+*   name: "activity-events",
+*   schema: z.object({
+*     userId: z.text(),
+*     event: z.text(),
+*     at: z.number()
 *   }),
 *   handler: async (message) => {
-*     await emailService.send(message.payload);
-*     console.log(`Email sent to ${message.payload.to}`);
+*     await metrics.track(message.payload);
 *   }
 * });
 *
 * // Push messages for background processing
-* await emailQueue.push({
-*   to: "user@example.com",
-*   subject: "Welcome!",
-*   body: "Welcome to our platform",
-*   priority: "high"
+* await activityQueue.push({
+*   userId: "u1",
+*   event: "page-view",
+*   at: 1700000000000
 * });
 * ```
 *
@@ -314,9 +286,9 @@ var WorkerProvider = class {
 * const imageQueue = $queue({
 *   name: "image-processing",
 *   provider: RedisQueueProvider,
-*   schema: t.object({
-*     imageId: t.text(),
-*     operations: t.array(t.enum(["resize", "compress", "thumbnail"]))
+*   schema: z.object({
+*     imageId: z.text(),
+*     operations: z.array(z.enum(["resize", "compress", "thumbnail"]))
 *   }),
 *   handler: async (message) => {
 *     for (const op of message.payload.operations) {
@@ -338,9 +310,9 @@ var WorkerProvider = class {
 * const taskQueue = $queue({
 *   name: "dev-tasks",
 *   provider: "memory",
-*   schema: t.object({
-*     taskType: t.enum(["cleanup", "backup", "report"]),
-*     data: t.record(t.text(), t.any())
+*   schema: z.object({
+*     taskType: z.enum(["cleanup", "backup", "report"]),
+*     data: z.record(z.text(), z.any())
 *   }),
 *   handler: async (message) => {
 *     switch (message.payload.taskType) {
@@ -390,6 +362,11 @@ $queue[KIND] = QueuePrimitive;
 */
 const QUEUE_DEFAULT_BINDING = "JOBS_QUEUE";
 /**
+* How many times Cloudflare redelivers a message before routing it to the
+* consumer's dead-letter queue. Matches Cloudflare's own default.
+*/
+const QUEUE_DEFAULT_MAX_RETRIES = 3;
+/**
 * Cloudflare Queue provider.
 *
 * Uses a Queue binding for message dispatch. Messages are wrapped with the
@@ -533,6 +510,6 @@ const AlephaQueue = $module({
 	})
 });
 //#endregion
-export { $consumer, $queue, AlephaQueue, CloudflareQueueProvider, ConsumerPrimitive, MemoryQueueProvider, QUEUE_DEFAULT_BINDING, QueuePrimitive, QueueProvider, WorkerProvider, WorkerdWorkerProvider, queueWorkerOptions };
+export { $consumer, $queue, AlephaQueue, CloudflareQueueProvider, ConsumerPrimitive, MemoryQueueProvider, QUEUE_DEFAULT_BINDING, QUEUE_DEFAULT_MAX_RETRIES, QueuePrimitive, QueueProvider, WorkerProvider, WorkerdWorkerProvider, queueWorkerOptions };
 
 //# sourceMappingURL=index.workerd.js.map