@cloudwerk/queue 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Squirrelsoft Dev Tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,723 @@
+import { ZodType } from 'zod';
+
+/**
+ * @cloudwerk/queue - Type Definitions
+ *
+ * Core types for queue producers and consumers.
+ */
+
+/**
+ * Type that can be either a value or a Promise of that value.
+ * Used throughout the queue package for async-friendly APIs.
+ */
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Represents a message received from a queue for processing.
+ *
+ * @typeParam T - The message body type
+ *
+ * @example
+ * ```typescript
+ * export default defineQueue<EmailMessage>({
+ *   async process(message) {
+ *     console.log(message.id)        // Unique message ID
+ *     console.log(message.body)      // { to, subject, body }
+ *     console.log(message.attempts)  // Number of delivery attempts
+ *
+ *     await sendEmail(message.body)
+ *     message.ack()  // Acknowledge successful processing
+ *   }
+ * })
+ * ```
+ */
+interface QueueMessage<T = unknown> {
+    /** Unique identifier for the message */
+    readonly id: string;
+    /** The message payload */
+    readonly body: T;
+    /** When the message was originally sent */
+    readonly timestamp: Date;
+    /** Number of delivery attempts for this message */
+    readonly attempts: number;
+    /**
+     * Acknowledge successful message processing.
+     * The message will be removed from the queue.
+     */
+    ack(): void;
+    /**
+     * Request retry of this message.
+     * The message will be requeued with optional delay.
+     *
+     * @param options - Retry options
+     * @param options.delaySeconds - Delay before retry (default: queue's retryDelay)
+     */
+    retry(options?: {
+        delaySeconds?: number;
+    }): void;
+    /**
+     * Mark this message as failed and send to dead letter queue.
+     * Only works if DLQ is configured for this queue.
+     *
+     * @param reason - Reason for sending to DLQ
+     */
+    deadLetter(reason?: string): void;
+}
+/**
+ * Message sent to a dead letter queue when processing fails.
+ *
+ * @typeParam T - The original message body type
+ *
+ * @example
+ * ```typescript
+ * export default defineQueue<DeadLetterMessage<EmailMessage>>({
+ *   name: 'email-dlq',
+ *   async process(message) {
+ *     // Log failed message for manual inspection
+ *     await logFailedMessage({
+ *       originalQueue: message.body.originalQueue,
+ *       originalMessage: message.body.originalMessage,
+ *       error: message.body.error,
+ *       attempts: message.body.attempts,
+ *     })
+ *     message.ack()
+ *   }
+ * })
+ * ```
+ */
+interface DeadLetterMessage<T = unknown> {
+    /** Name of the original queue that failed processing */
+    originalQueue: string;
+    /** The original message that failed */
+    originalMessage: T;
+    /** Error message from the last failure */
+    error: string;
+    /** Error stack trace (if available) */
+    stack?: string;
+    /** Number of processing attempts before DLQ */
+    attempts: number;
+    /** ISO timestamp when the message was sent to DLQ */
+    failedAt: string;
+    /** Original message ID */
+    originalMessageId: string;
+}
+/**
+ * Configuration for queue processing behavior.
+ *
+ * @example
+ * ```typescript
+ * export default defineQueue({
+ *   config: {
+ *     batchSize: 10,
+ *     maxRetries: 5,
+ *     retryDelay: '2m',
+ *     deadLetterQueue: 'my-dlq',
+ *     batchTimeout: '30s',
+ *   },
+ *   async process(message) {
+ *     // ...
+ *   }
+ * })
+ * ```
+ */
+interface QueueProcessingConfig {
+    /**
+     * Maximum number of messages to deliver in a batch.
+     * @default 10
+     */
+    batchSize?: number;
+    /**
+     * Maximum number of retry attempts before sending to DLQ.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Delay between retries. Supports duration strings like '1m', '30s', '1h'.
+     * @default '1m'
+     */
+    retryDelay?: string | number;
+    /**
+     * Dead letter queue name for failed messages.
+     * Messages exceeding maxRetries will be sent here.
+     */
+    deadLetterQueue?: string;
+    /**
+     * Maximum time to wait for a batch to fill.
+     * Supports duration strings like '5s', '30s'.
+     * @default '5s'
+     */
+    batchTimeout?: string | number;
+}
+/**
+ * Full configuration for defining a queue consumer.
+ *
+ * @typeParam T - The message body type
+ *
+ * @example
+ * ```typescript
+ * // Simple queue with single message processing
+ * export default defineQueue<EmailMessage>({
+ *   async process(message) {
+ *     await sendEmail(message.body)
+ *     message.ack()
+ *   }
+ * })
+ *
+ * // Queue with batch processing and configuration
+ * export default defineQueue<ImageJob>({
+ *   config: {
+ *     batchSize: 50,
+ *     maxRetries: 5,
+ *     deadLetterQueue: 'image-dlq',
+ *   },
+ *   async processBatch(messages) {
+ *     const jobs = messages.map(m => m.body)
+ *     await processImageBatch(jobs)
+ *     messages.forEach(m => m.ack())
+ *   }
+ * })
+ *
+ * // Queue with Zod schema validation
+ * export default defineQueue({
+ *   schema: z.object({
+ *     to: z.string().email(),
+ *     subject: z.string(),
+ *     body: z.string(),
+ *   }),
+ *   async process(message) {
+ *     // message.body is validated and typed
+ *     await sendEmail(message.body)
+ *     message.ack()
+ *   }
+ * })
+ * ```
+ */
+interface QueueConfig<T = unknown> {
+    /**
+     * Optional queue name override.
+     * By default, the queue name is derived from the filename.
+     * - `app/queues/email.ts` -> `email`
+     * - `app/queues/image-processing.ts` -> `imageProcessing`
+     */
+    name?: string;
+    /**
+     * Optional Zod schema for runtime validation of message bodies.
+     * If provided, messages that fail validation will be rejected.
+     */
+    schema?: ZodType<T>;
+    /**
+     * Queue processing configuration.
+     */
+    config?: QueueProcessingConfig;
+    /**
+     * Process a single message.
+     * Called for each message in the batch unless processBatch is defined.
+     *
+     * @param message - The message to process
+     */
+    process?: (message: QueueMessage<T>) => Awaitable<void>;
+    /**
+     * Process a batch of messages.
+     * If defined, this is called instead of process() for the entire batch.
+     * More efficient for bulk operations.
+     *
+     * @param messages - Array of messages to process
+     */
+    processBatch?: (messages: QueueMessage<T>[]) => Awaitable<void>;
+    /**
+     * Error handler for processing failures.
+     * Called when process() or processBatch() throws an error.
+     *
+     * @param error - The error that occurred
+     * @param message - The message that was being processed (or first message in batch)
+     */
+    onError?: (error: Error, message: QueueMessage<T>) => Awaitable<void>;
+}
+/**
+ * A defined queue consumer, returned by defineQueue().
+ *
+ * @typeParam T - The message body type
+ */
+interface QueueDefinition<T = unknown> {
+    /** Internal marker identifying this as a queue definition */
+    readonly __brand: 'cloudwerk-queue';
+    /** Queue name (derived from filename or explicitly set) */
+    readonly name: string | undefined;
+    /** Zod schema for validation (if provided) */
+    readonly schema: ZodType<T> | undefined;
+    /** Processing configuration */
+    readonly config: QueueProcessingConfig;
+    /** Single message processor */
+    readonly process: ((message: QueueMessage<T>) => Awaitable<void>) | undefined;
+    /** Batch message processor */
+    readonly processBatch: ((messages: QueueMessage<T>[]) => Awaitable<void>) | undefined;
+    /** Error handler */
+    readonly onError: ((error: Error, message: QueueMessage<T>) => Awaitable<void>) | undefined;
+}
+/**
+ * Options for sending messages to a queue.
+ */
+interface SendOptions {
+    /**
+     * Delay delivery of this message by the specified number of seconds.
+     * The message will not be available for processing until after this delay.
+     */
+    delaySeconds?: number;
+    /**
+     * Content type of the message body.
+     * @default 'json'
+     */
+    contentType?: 'json' | 'text' | 'bytes' | 'v8';
+}
+/**
+ * A typed queue producer for sending messages.
+ *
+ * @typeParam T - The message body type
+ *
+ * @example
+ * ```typescript
+ * import { queues } from '@cloudwerk/core/bindings'
+ *
+ * // Send a single message
+ * await queues.email.send({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome!',
+ *   body: 'Thanks for signing up.',
+ * })
+ *
+ * // Send with delay
+ * await queues.email.send(message, { delaySeconds: 60 })
+ *
+ * // Send a batch
+ * await queues.notifications.sendBatch([
+ *   { userId: '1', event: 'login' },
+ *   { userId: '2', event: 'purchase' },
+ * ])
+ * ```
+ */
+interface Queue<T = unknown> {
+    /**
+     * Send a single message to the queue.
+     *
+     * @param message - The message body to send
+     * @param options - Optional send options
+     */
+    send(message: T, options?: SendOptions): Promise<void>;
+    /**
+     * Send multiple messages to the queue in a single operation.
+     *
+     * @param messages - Array of message bodies to send
+     * @param options - Optional send options (applied to all messages)
+     */
+    sendBatch(messages: T[], options?: SendOptions): Promise<void>;
+}
+/**
+ * A scanned queue file from the app/queues/ directory.
+ */
+interface ScannedQueue {
+    /** Relative path from app/queues/ (e.g., 'email.ts') */
+    relativePath: string;
+    /** Absolute filesystem path */
+    absolutePath: string;
+    /** File name without extension (e.g., 'email') */
+    name: string;
+    /** File extension (e.g., '.ts') */
+    extension: string;
+}
+/**
+ * Result of scanning the app/queues/ directory.
+ */
+interface QueueScanResult {
+    /** All discovered queue files */
+    queues: ScannedQueue[];
+}
+/**
+ * A compiled queue entry in the manifest.
+ */
+interface QueueEntry {
+    /** Queue name derived from filename (e.g., 'email', 'imageProcessing') */
+    name: string;
+    /** Binding name for wrangler.toml (e.g., 'EMAIL_QUEUE') */
+    bindingName: string;
+    /** Actual queue name in Cloudflare (e.g., 'cloudwerk-email') */
+    queueName: string;
+    /** Relative path to the queue definition file */
+    filePath: string;
+    /** Absolute path to the queue definition file */
+    absolutePath: string;
+    /** Processing configuration from the queue definition */
+    config: QueueProcessingConfig;
+    /** Whether processBatch is defined */
+    hasProcessBatch: boolean;
+    /** Whether onError handler is defined */
+    hasOnError: boolean;
+    /** TypeScript type name for the message body (if extractable) */
+    messageType?: string;
+}
+/**
+ * Validation error for a queue definition.
+ */
+interface QueueValidationError$1 {
+    /** Queue file path */
+    file: string;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: 'NO_HANDLER' | 'INVALID_CONFIG' | 'DUPLICATE_NAME' | 'INVALID_NAME';
+}
+/**
+ * Validation warning for a queue definition.
+ */
+interface QueueValidationWarning {
+    /** Queue file path */
+    file: string;
+    /** Warning message */
+    message: string;
+    /** Warning code */
+    code: 'NO_DLQ' | 'LOW_RETRIES' | 'MISSING_ERROR_HANDLER';
+}
+/**
+ * Complete queue manifest generated during build.
+ */
+interface QueueManifest {
+    /** All compiled queue entries */
+    queues: QueueEntry[];
+    /** Validation errors (queue won't be registered) */
+    errors: QueueValidationError$1[];
+    /** Validation warnings (queue will be registered with warning) */
+    warnings: QueueValidationWarning[];
+    /** When the manifest was generated */
+    generatedAt: Date;
+    /** Root directory of the app */
+    rootDir: string;
+}
+
+/**
+ * @cloudwerk/queue - Error Classes
+ *
+ * Custom error classes for queue processing.
+ */
+/**
+ * Base error class for queue-related errors.
+ */
+declare class QueueError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when a queue message fails schema validation.
+ *
+ * @example
+ * ```typescript
+ * export default defineQueue({
+ *   schema: z.object({ email: z.string().email() }),
+ *   async process(message) {
+ *     // If message.body doesn't match schema, QueueValidationError is thrown
+ *   }
+ * })
+ * ```
+ */
+declare class QueueValidationError extends QueueError {
+    /** The validation errors from Zod */
+    readonly validationErrors: unknown[];
+    constructor(message: string, validationErrors: unknown[]);
+}
+/**
+ * Error thrown when queue message processing fails.
+ */
+declare class QueueProcessingError extends QueueError {
+    /** The message ID that failed processing */
+    readonly messageId: string;
+    /** Number of attempts made */
+    readonly attempts: number;
+    constructor(message: string, messageId: string, attempts: number, options?: ErrorOptions);
+}
+/**
+ * Error thrown when max retries are exceeded.
+ */
+declare class QueueMaxRetriesError extends QueueError {
+    /** The message ID that exceeded retries */
+    readonly messageId: string;
+    /** Maximum retries configured */
+    readonly maxRetries: number;
+    constructor(messageId: string, maxRetries: number);
+}
+/**
+ * Error thrown when queue configuration is invalid.
+ */
+declare class QueueConfigError extends QueueError {
+    /** The configuration field that is invalid */
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+/**
+ * Error thrown when no message handler is defined.
+ */
+declare class QueueNoHandlerError extends QueueError {
+    constructor(queueName: string);
+}
+/**
+ * Error thrown when accessing a queue outside of request context.
+ */
+declare class QueueContextError extends QueueError {
+    constructor();
+}
+/**
+ * Error thrown when a queue binding is not found.
+ */
+declare class QueueNotFoundError extends QueueError {
+    /** The queue name that was not found */
+    readonly queueName: string;
+    /** Available queue names */
+    readonly availableQueues: string[];
+    constructor(queueName: string, availableQueues: string[]);
+}
+
+/**
+ * @cloudwerk/queue - defineQueue()
+ *
+ * Factory function for creating queue consumer definitions.
+ */
+
+/**
+ * Parse a duration string into seconds.
+ *
+ * Supports formats like:
+ * - '30s' - 30 seconds
+ * - '5m' - 5 minutes
+ * - '1h' - 1 hour
+ * - 60 - number of seconds
+ *
+ * @param duration - Duration string or number
+ * @returns Duration in seconds
+ */
+declare function parseDuration(duration: string | number): number;
+/**
+ * Define a queue consumer.
+ *
+ * This function creates a queue definition that will be automatically
+ * discovered and registered by Cloudwerk during build.
+ *
+ * @typeParam T - The message body type
+ * @param config - Queue configuration
+ * @returns Queue definition
+ *
+ * @example
+ * ```typescript
+ * // app/queues/email.ts
+ * import { defineQueue } from '@cloudwerk/queue'
+ *
+ * interface EmailMessage {
+ *   to: string
+ *   subject: string
+ *   body: string
+ * }
+ *
+ * export default defineQueue<EmailMessage>({
+ *   async process(message) {
+ *     await sendEmail(message.body)
+ *     message.ack()
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With Zod schema validation
+ * import { defineQueue } from '@cloudwerk/queue'
+ * import { z } from 'zod'
+ *
+ * const EmailSchema = z.object({
+ *   to: z.string().email(),
+ *   subject: z.string().min(1),
+ *   body: z.string(),
+ * })
+ *
+ * export default defineQueue({
+ *   schema: EmailSchema,
+ *   config: {
+ *     maxRetries: 5,
+ *     deadLetterQueue: 'email-dlq',
+ *   },
+ *   async process(message) {
+ *     // message.body is validated and typed as { to: string, subject: string, body: string }
+ *     await sendEmail(message.body)
+ *     message.ack()
+ *   },
+ *   async onError(error, message) {
+ *     console.error(`Failed to send email to ${message.body.to}:`, error)
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Batch processing
+ * import { defineQueue } from '@cloudwerk/queue'
+ *
+ * interface ImageJob {
+ *   imageId: string
+ *   operation: 'resize' | 'crop' | 'compress'
+ *   params: Record<string, unknown>
+ * }
+ *
+ * export default defineQueue<ImageJob>({
+ *   config: {
+ *     batchSize: 50,
+ *     batchTimeout: '30s',
+ *   },
+ *   async processBatch(messages) {
+ *     // Process all images in parallel for efficiency
+ *     await Promise.all(
+ *       messages.map(async (msg) => {
+ *         await processImage(msg.body)
+ *         msg.ack()
+ *       })
+ *     )
+ *   }
+ * })
+ * ```
+ */
+declare function defineQueue<T = unknown>(config: QueueConfig<T>): QueueDefinition<T>;
+/**
+ * Check if a value is a queue definition created by defineQueue().
+ *
+ * @param value - Value to check
+ * @returns true if value is a QueueDefinition
+ */
+declare function isQueueDefinition(value: unknown): value is QueueDefinition;
+
+/**
+ * @cloudwerk/queue - Dead Letter Queue Utilities
+ *
+ * Utilities for working with dead letter queues.
+ */
+
+/**
+ * Create a dead letter message from a failed queue message.
+ *
+ * @param originalMessage - The original message that failed processing
+ * @param originalQueue - Name of the queue where the message failed
+ * @param error - The error that caused the failure
+ * @returns Dead letter message ready to be sent to DLQ
+ *
+ * @example
+ * ```typescript
+ * import { createDeadLetterMessage } from '@cloudwerk/queue'
+ *
+ * export default defineQueue<EmailMessage>({
+ *   config: {
+ *     deadLetterQueue: 'email-dlq',
+ *   },
+ *   async process(message) {
+ *     try {
+ *       await sendEmail(message.body)
+ *       message.ack()
+ *     } catch (error) {
+ *       // Message will automatically go to DLQ after max retries
+ *       // Or manually send to DLQ:
+ *       message.deadLetter(error.message)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function createDeadLetterMessage<T>(originalMessage: QueueMessage<T>, originalQueue: string, error: Error): DeadLetterMessage<T>;
+/**
+ * Configuration for dead letter queue handling.
+ */
+interface DLQConfig {
+    /**
+     * Name of the dead letter queue.
+     */
+    queueName: string;
+    /**
+     * Maximum retries before sending to DLQ.
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Custom handler called before sending to DLQ.
+     * Return false to prevent the message from being sent to DLQ.
+     */
+    beforeDLQ?: <T>(message: QueueMessage<T>, error: Error) => Awaitable<boolean | void>;
+    /**
+     * Custom handler called after sending to DLQ.
+     */
+    afterDLQ?: <T>(dlqMessage: DeadLetterMessage<T>) => Awaitable<void>;
+}
+/**
+ * Create DLQ configuration with defaults.
+ *
+ * @param queueName - Name of the dead letter queue
+ * @param options - Optional configuration overrides
+ * @returns Complete DLQ configuration
+ */
+declare function createDLQConfig(queueName: string, options?: Partial<Omit<DLQConfig, 'queueName'>>): DLQConfig;
+/**
+ * Validate DLQ configuration.
+ *
+ * @param config - DLQ configuration to validate
+ * @returns Array of validation error messages (empty if valid)
+ */
+declare function validateDLQConfig(config: DLQConfig): string[];
+/**
+ * Check if a message should be sent to DLQ based on attempts.
+ *
+ * @param message - The queue message
+ * @param maxRetries - Maximum retry attempts (default: 3)
+ * @returns true if message has exceeded max retries
+ */
+declare function shouldSendToDLQ<T>(message: QueueMessage<T>, maxRetries?: number): boolean;
+/**
+ * Extract original message from a DLQ message.
+ *
+ * @param dlqMessage - Dead letter message
+ * @returns The original message body
+ */
+declare function extractOriginalMessage<T>(dlqMessage: DeadLetterMessage<T>): T;
+/**
+ * Check if a message is a dead letter message.
+ *
+ * @param message - Message to check
+ * @returns true if message is a DeadLetterMessage
+ */
+declare function isDeadLetterMessage(message: unknown): message is DeadLetterMessage;
+/**
+ * Create a DLQ consumer configuration.
+ *
+ * This is a convenience helper for defining DLQ consumers with appropriate
+ * defaults and error handling.
+ *
+ * @param handler - Handler for processing dead letter messages
+ * @returns Queue config for the DLQ consumer
+ *
+ * @example
+ * ```typescript
+ * // app/queues/email-dlq.ts
+ * import { defineDLQConsumer } from '@cloudwerk/queue'
+ *
+ * export default defineDLQConsumer<EmailMessage>(async (dlqMessage) => {
+ *   // Log failed message for manual inspection
+ *   await logFailedMessage({
+ *     queue: dlqMessage.originalQueue,
+ *     error: dlqMessage.error,
+ *     attempts: dlqMessage.attempts,
+ *     message: dlqMessage.originalMessage,
+ *   })
+ *
+ *   // Optionally alert on critical failures
+ *   if (dlqMessage.attempts > 10) {
+ *     await sendAlert(`Critical: ${dlqMessage.originalQueue} message failed`)
+ *   }
+ * })
+ * ```
+ */
+declare function defineDLQConsumer<T>(handler: (dlqMessage: DeadLetterMessage<T>) => Awaitable<void>): {
+    config: {
+        maxRetries: number;
+    };
+    process: (message: QueueMessage<DeadLetterMessage<T>>) => Promise<void>;
+};
+
+export { type Awaitable, type DLQConfig, type DeadLetterMessage, type Queue, type QueueConfig, QueueConfigError, QueueContextError, type QueueDefinition, type QueueEntry, QueueError, type QueueManifest, QueueMaxRetriesError, type QueueMessage, QueueNoHandlerError, QueueNotFoundError, type QueueProcessingConfig, QueueProcessingError, type QueueScanResult, QueueValidationError, type QueueValidationWarning, type ScannedQueue, type SendOptions, createDLQConfig, createDeadLetterMessage, defineDLQConsumer, defineQueue, extractOriginalMessage, isDeadLetterMessage, isQueueDefinition, parseDuration, shouldSendToDLQ, validateDLQConfig };

package/dist/index.js

@@ -0,0 +1,268 @@
+// src/errors.ts
+var QueueError = class extends Error {
+  /** Error code for programmatic handling */
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "QueueError";
+    this.code = code;
+  }
+};
+var QueueValidationError = class extends QueueError {
+  /** The validation errors from Zod */
+  validationErrors;
+  constructor(message, validationErrors) {
+    super("VALIDATION_ERROR", message);
+    this.name = "QueueValidationError";
+    this.validationErrors = validationErrors;
+  }
+};
+var QueueProcessingError = class extends QueueError {
+  /** The message ID that failed processing */
+  messageId;
+  /** Number of attempts made */
+  attempts;
+  constructor(message, messageId, attempts, options) {
+    super("PROCESSING_ERROR", message, options);
+    this.name = "QueueProcessingError";
+    this.messageId = messageId;
+    this.attempts = attempts;
+  }
+};
+var QueueMaxRetriesError = class extends QueueError {
+  /** The message ID that exceeded retries */
+  messageId;
+  /** Maximum retries configured */
+  maxRetries;
+  constructor(messageId, maxRetries) {
+    super(
+      "MAX_RETRIES_EXCEEDED",
+      `Message ${messageId} exceeded maximum retries (${maxRetries})`
+    );
+    this.name = "QueueMaxRetriesError";
+    this.messageId = messageId;
+    this.maxRetries = maxRetries;
+  }
+};
+var QueueConfigError = class extends QueueError {
+  /** The configuration field that is invalid */
+  field;
+  constructor(message, field) {
+    super("CONFIG_ERROR", message);
+    this.name = "QueueConfigError";
+    this.field = field;
+  }
+};
+var QueueNoHandlerError = class extends QueueError {
+  constructor(queueName) {
+    super(
+      "NO_HANDLER",
+      `Queue '${queueName}' must define either process() or processBatch()`
+    );
+    this.name = "QueueNoHandlerError";
+  }
+};
+var QueueContextError = class extends QueueError {
+  constructor() {
+    super(
+      "CONTEXT_ERROR",
+      "Queue accessed outside of request handler. Queues can only be accessed during request handling."
+    );
+    this.name = "QueueContextError";
+  }
+};
+var QueueNotFoundError = class extends QueueError {
+  /** The queue name that was not found */
+  queueName;
+  /** Available queue names */
+  availableQueues;
+  constructor(queueName, availableQueues) {
+    const available = availableQueues.length > 0 ? `Available queues: ${availableQueues.join(", ")}` : "No queues are configured";
+    super(
+      "QUEUE_NOT_FOUND",
+      `Queue '${queueName}' not found in environment. ${available}`
+    );
+    this.name = "QueueNotFoundError";
+    this.queueName = queueName;
+    this.availableQueues = availableQueues;
+  }
+};
+
+// src/define-queue.ts
+var DEFAULT_CONFIG = {
+  batchSize: 10,
+  maxRetries: 3,
+  retryDelay: "1m",
+  deadLetterQueue: "",
+  batchTimeout: "5s"
+};
+function parseDuration(duration) {
+  if (typeof duration === "number") {
+    return duration;
+  }
+  const match = duration.match(/^(\d+)(s|m|h)$/);
+  if (!match) {
+    throw new QueueConfigError(
+      `Invalid duration format: '${duration}'. Expected format like '30s', '5m', or '1h'`,
+      "retryDelay"
+    );
+  }
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  switch (unit) {
+    case "s":
+      return value;
+    case "m":
+      return value * 60;
+    case "h":
+      return value * 3600;
+    default:
+      throw new QueueConfigError(`Unknown duration unit: ${unit}`, "retryDelay");
+  }
+}
+function validateConfig(config) {
+  if (!config.process && !config.processBatch) {
+    throw new QueueNoHandlerError(config.name || "unknown");
+  }
+  if (config.config) {
+    const { batchSize, maxRetries, retryDelay, batchTimeout } = config.config;
+    if (batchSize !== void 0) {
+      if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 100) {
+        throw new QueueConfigError(
+          "batchSize must be an integer between 1 and 100",
+          "batchSize"
+        );
+      }
+    }
+    if (maxRetries !== void 0) {
+      if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 100) {
+        throw new QueueConfigError(
+          "maxRetries must be an integer between 0 and 100",
+          "maxRetries"
+        );
+      }
+    }
+    if (retryDelay !== void 0) {
+      parseDuration(retryDelay);
+    }
+    if (batchTimeout !== void 0) {
+      parseDuration(batchTimeout);
+    }
+  }
+  if (config.name !== void 0) {
+    if (typeof config.name !== "string" || config.name.length === 0) {
+      throw new QueueConfigError("name must be a non-empty string", "name");
+    }
+    if (!/^[a-z][a-z0-9-]*$/.test(config.name)) {
+      throw new QueueConfigError(
+        "name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens",
+        "name"
+      );
+    }
+  }
+}
+function defineQueue(config) {
+  validateConfig(config);
+  const mergedConfig = {
+    ...DEFAULT_CONFIG,
+    ...config.config
+  };
+  const definition = {
+    __brand: "cloudwerk-queue",
+    name: config.name,
+    schema: config.schema,
+    config: mergedConfig,
+    process: config.process,
+    processBatch: config.processBatch,
+    onError: config.onError
+  };
+  return definition;
+}
+function isQueueDefinition(value) {
+  return typeof value === "object" && value !== null && "__brand" in value && value.__brand === "cloudwerk-queue";
+}
+
+// src/dlq.ts
+function createDeadLetterMessage(originalMessage, originalQueue, error) {
+  return {
+    originalQueue,
+    originalMessage: originalMessage.body,
+    error: error.message,
+    stack: error.stack,
+    attempts: originalMessage.attempts,
+    failedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    originalMessageId: originalMessage.id
+  };
+}
+function createDLQConfig(queueName, options) {
+  return {
+    queueName,
+    maxRetries: options?.maxRetries ?? 3,
+    beforeDLQ: options?.beforeDLQ,
+    afterDLQ: options?.afterDLQ
+  };
+}
+function validateDLQConfig(config) {
+  const errors = [];
+  if (!config.queueName || config.queueName.trim() === "") {
+    errors.push("DLQ queue name is required");
+  }
+  if (config.queueName && !/^[a-z][a-z0-9-]*$/.test(config.queueName)) {
+    errors.push(
+      "DLQ queue name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens"
+    );
+  }
+  if (config.maxRetries !== void 0) {
+    if (!Number.isInteger(config.maxRetries) || config.maxRetries < 0) {
+      errors.push("maxRetries must be a non-negative integer");
+    }
+  }
+  return errors;
+}
+function shouldSendToDLQ(message, maxRetries = 3) {
+  return message.attempts > maxRetries;
+}
+function extractOriginalMessage(dlqMessage) {
+  return dlqMessage.originalMessage;
+}
+function isDeadLetterMessage(message) {
+  if (typeof message !== "object" || message === null) {
+    return false;
+  }
+  const dlm = message;
+  return typeof dlm.originalQueue === "string" && "originalMessage" in dlm && typeof dlm.error === "string" && typeof dlm.attempts === "number" && typeof dlm.failedAt === "string" && typeof dlm.originalMessageId === "string";
+}
+function defineDLQConsumer(handler) {
+  return {
+    config: {
+      // DLQ consumers typically shouldn't retry much
+      // to avoid infinite loops
+      maxRetries: 1
+    },
+    async process(message) {
+      await handler(message.body);
+      message.ack();
+    }
+  };
+}
+export {
+  QueueConfigError,
+  QueueContextError,
+  QueueError,
+  QueueMaxRetriesError,
+  QueueNoHandlerError,
+  QueueNotFoundError,
+  QueueProcessingError,
+  QueueValidationError,
+  createDLQConfig,
+  createDeadLetterMessage,
+  defineDLQConsumer,
+  defineQueue,
+  extractOriginalMessage,
+  isDeadLetterMessage,
+  isQueueDefinition,
+  parseDuration,
+  shouldSendToDLQ,
+  validateDLQConfig
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/define-queue.ts","../src/dlq.ts"],"sourcesContent":["/**\n * @cloudwerk/queue - Error Classes\n *\n * Custom error classes for queue processing.\n */\n\n// ============================================================================\n// Base Error\n// ============================================================================\n\n/**\n * Base error class for queue-related errors.\n */\nexport class QueueError extends Error {\n  /** Error code for programmatic handling */\n  readonly code: string\n\n  constructor(code: string, message: string, options?: ErrorOptions) {\n    super(message, options)\n    this.name = 'QueueError'\n    this.code = code\n  }\n}\n\n// ============================================================================\n// Validation Errors\n// ============================================================================\n\n/**\n * Error thrown when a queue message fails schema validation.\n *\n * @example\n * ```typescript\n * export default defineQueue({\n *   schema: z.object({ email: z.string().email() }),\n *   async process(message) {\n *     // If message.body doesn't match schema, QueueValidationError is thrown\n *   }\n * })\n * ```\n */\nexport class QueueValidationError extends QueueError {\n  /** The validation errors from Zod */\n  readonly validationErrors: unknown[]\n\n  constructor(message: string, validationErrors: unknown[]) {\n    super('VALIDATION_ERROR', message)\n    this.name = 'QueueValidationError'\n    this.validationErrors = validationErrors\n  }\n}\n\n// ============================================================================\n// Processing Errors\n// ============================================================================\n\n/**\n * Error thrown when queue message processing fails.\n */\nexport class QueueProcessingError extends QueueError {\n  /** The message ID that failed processing */\n  readonly messageId: string\n\n  /** Number of attempts made */\n  readonly attempts: number\n\n  constructor(\n    message: string,\n    messageId: string,\n    attempts: number,\n    options?: ErrorOptions\n  ) {\n    super('PROCESSING_ERROR', message, options)\n    this.name = 'QueueProcessingError'\n    this.messageId = messageId\n    this.attempts = attempts\n  }\n}\n\n/**\n * Error thrown when max retries are exceeded.\n */\nexport class QueueMaxRetriesError extends QueueError {\n  /** The message ID that exceeded retries */\n  readonly messageId: string\n\n  /** Maximum retries configured */\n  readonly maxRetries: number\n\n  constructor(messageId: string, maxRetries: number) {\n    super(\n      'MAX_RETRIES_EXCEEDED',\n      `Message ${messageId} exceeded maximum retries (${maxRetries})`\n    )\n    this.name = 'QueueMaxRetriesError'\n    this.messageId = messageId\n    this.maxRetries = maxRetries\n  }\n}\n\n// ============================================================================\n// Configuration Errors\n// ============================================================================\n\n/**\n * Error thrown when queue configuration is invalid.\n */\nexport class QueueConfigError extends QueueError {\n  /** The configuration field that is invalid */\n  readonly field?: string\n\n  constructor(message: string, field?: string) {\n    super('CONFIG_ERROR', message)\n    this.name = 'QueueConfigError'\n    this.field = field\n  }\n}\n\n/**\n * Error thrown when no message handler is defined.\n */\nexport class QueueNoHandlerError extends QueueError {\n  constructor(queueName: string) {\n    super(\n      'NO_HANDLER',\n      `Queue '${queueName}' must define either process() or processBatch()`\n    )\n    this.name = 'QueueNoHandlerError'\n  }\n}\n\n// ============================================================================\n// Runtime Errors\n// ============================================================================\n\n/**\n * Error thrown when accessing a queue outside of request context.\n */\nexport class QueueContextError extends QueueError {\n  constructor() {\n    super(\n      'CONTEXT_ERROR',\n      'Queue accessed outside of request handler. Queues can only be accessed during request handling.'\n    )\n    this.name = 'QueueContextError'\n  }\n}\n\n/**\n * Error thrown when a queue binding is not found.\n */\nexport class QueueNotFoundError extends QueueError {\n  /** The queue name that was not found */\n  readonly queueName: string\n\n  /** Available queue names */\n  readonly availableQueues: string[]\n\n  constructor(queueName: string, availableQueues: string[]) {\n    const available =\n      availableQueues.length > 0\n        ? `Available queues: ${availableQueues.join(', ')}`\n        : 'No queues are configured'\n\n    super(\n      'QUEUE_NOT_FOUND',\n      `Queue '${queueName}' not found in environment. ${available}`\n    )\n    this.name = 'QueueNotFoundError'\n    this.queueName = queueName\n    this.availableQueues = availableQueues\n  }\n}\n","/**\n * @cloudwerk/queue - defineQueue()\n *\n * Factory function for creating queue consumer definitions.\n */\n\nimport type {\n  QueueConfig,\n  QueueDefinition,\n  QueueProcessingConfig,\n} from './types.js'\nimport { QueueConfigError, QueueNoHandlerError } from './errors.js'\n\n// ============================================================================\n// Default Configuration\n// ============================================================================\n\nconst DEFAULT_CONFIG: Required<QueueProcessingConfig> = {\n  batchSize: 10,\n  maxRetries: 3,\n  retryDelay: '1m',\n  deadLetterQueue: '',\n  batchTimeout: '5s',\n}\n\n// ============================================================================\n// Validation\n// ============================================================================\n\n/**\n * Parse a duration string into seconds.\n *\n * Supports formats like:\n * - '30s' - 30 seconds\n * - '5m' - 5 minutes\n * - '1h' - 1 hour\n * - 60 - number of seconds\n *\n * @param duration - Duration string or number\n * @returns Duration in seconds\n */\nexport function parseDuration(duration: string | number): number {\n  if (typeof duration === 'number') {\n    return duration\n  }\n\n  const match = duration.match(/^(\\d+)(s|m|h)$/)\n  if (!match) {\n    throw new QueueConfigError(\n      `Invalid duration format: '${duration}'. Expected format like '30s', '5m', or '1h'`,\n      'retryDelay'\n    )\n  }\n\n  const value = parseInt(match[1], 10)\n  const unit = match[2]\n\n  switch (unit) {\n    case 's':\n      return value\n    case 'm':\n      return value * 60\n    case 'h':\n      return value * 3600\n    default:\n      throw new QueueConfigError(`Unknown duration unit: ${unit}`, 'retryDelay')\n  }\n}\n\n/**\n * Validate queue configuration.\n *\n * @param config - Queue configuration to validate\n * @throws QueueConfigError if configuration is invalid\n * @throws QueueNoHandlerError if no handler is defined\n */\nfunction validateConfig<T>(config: QueueConfig<T>): void {\n  // Must have either process or processBatch\n  if (!config.process && !config.processBatch) {\n    throw new QueueNoHandlerError(config.name || 'unknown')\n  }\n\n  // Validate processing config\n  if (config.config) {\n    const { batchSize, maxRetries, retryDelay, batchTimeout } = config.config\n\n    if (batchSize !== undefined) {\n      if (!Number.isInteger(batchSize) || batchSize < 1 || batchSize > 100) {\n        throw new QueueConfigError(\n          'batchSize must be an integer between 1 and 100',\n          'batchSize'\n        )\n      }\n    }\n\n    if (maxRetries !== undefined) {\n      if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 100) {\n        throw new QueueConfigError(\n          'maxRetries must be an integer between 0 and 100',\n          'maxRetries'\n        )\n      }\n    }\n\n    if (retryDelay !== undefined) {\n      // This will throw if invalid\n      parseDuration(retryDelay)\n    }\n\n    if (batchTimeout !== undefined) {\n      // This will throw if invalid\n      parseDuration(batchTimeout)\n    }\n  }\n\n  // Validate name if provided\n  if (config.name !== undefined) {\n    if (typeof config.name !== 'string' || config.name.length === 0) {\n      throw new QueueConfigError('name must be a non-empty string', 'name')\n    }\n\n    // Queue names should be lowercase alphanumeric with hyphens\n    if (!/^[a-z][a-z0-9-]*$/.test(config.name)) {\n      throw new QueueConfigError(\n        'name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens',\n        'name'\n      )\n    }\n  }\n}\n\n// ============================================================================\n// defineQueue()\n// ============================================================================\n\n/**\n * Define a queue consumer.\n *\n * This function creates a queue definition that will be automatically\n * discovered and registered by Cloudwerk during build.\n *\n * @typeParam T - The message body type\n * @param config - Queue configuration\n * @returns Queue definition\n *\n * @example\n * ```typescript\n * // app/queues/email.ts\n * import { defineQueue } from '@cloudwerk/queue'\n *\n * interface EmailMessage {\n *   to: string\n *   subject: string\n *   body: string\n * }\n *\n * export default defineQueue<EmailMessage>({\n *   async process(message) {\n *     await sendEmail(message.body)\n *     message.ack()\n *   }\n * })\n * ```\n *\n * @example\n * ```typescript\n * // With Zod schema validation\n * import { defineQueue } from '@cloudwerk/queue'\n * import { z } from 'zod'\n *\n * const EmailSchema = z.object({\n *   to: z.string().email(),\n *   subject: z.string().min(1),\n *   body: z.string(),\n * })\n *\n * export default defineQueue({\n *   schema: EmailSchema,\n *   config: {\n *     maxRetries: 5,\n *     deadLetterQueue: 'email-dlq',\n *   },\n *   async process(message) {\n *     // message.body is validated and typed as { to: string, subject: string, body: string }\n *     await sendEmail(message.body)\n *     message.ack()\n *   },\n *   async onError(error, message) {\n *     console.error(`Failed to send email to ${message.body.to}:`, error)\n *   }\n * })\n * ```\n *\n * @example\n * ```typescript\n * // Batch processing\n * import { defineQueue } from '@cloudwerk/queue'\n *\n * interface ImageJob {\n *   imageId: string\n *   operation: 'resize' | 'crop' | 'compress'\n *   params: Record<string, unknown>\n * }\n *\n * export default defineQueue<ImageJob>({\n *   config: {\n *     batchSize: 50,\n *     batchTimeout: '30s',\n *   },\n *   async processBatch(messages) {\n *     // Process all images in parallel for efficiency\n *     await Promise.all(\n *       messages.map(async (msg) => {\n *         await processImage(msg.body)\n *         msg.ack()\n *       })\n *     )\n *   }\n * })\n * ```\n */\nexport function defineQueue<T = unknown>(\n  config: QueueConfig<T>\n): QueueDefinition<T> {\n  // Validate configuration\n  validateConfig(config)\n\n  // Merge with defaults\n  const mergedConfig: QueueProcessingConfig = {\n    ...DEFAULT_CONFIG,\n    ...config.config,\n  }\n\n  // Create the definition object\n  const definition: QueueDefinition<T> = {\n    __brand: 'cloudwerk-queue',\n    name: config.name,\n    schema: config.schema,\n    config: mergedConfig,\n    process: config.process,\n    processBatch: config.processBatch,\n    onError: config.onError,\n  }\n\n  return definition\n}\n\n/**\n * Check if a value is a queue definition created by defineQueue().\n *\n * @param value - Value to check\n * @returns true if value is a QueueDefinition\n */\nexport function isQueueDefinition(value: unknown): value is QueueDefinition {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    '__brand' in value &&\n    (value as QueueDefinition).__brand === 'cloudwerk-queue'\n  )\n}\n","/**\n * @cloudwerk/queue - Dead Letter Queue Utilities\n *\n * Utilities for working with dead letter queues.\n */\n\nimport type { DeadLetterMessage, QueueMessage, Awaitable } from './types.js'\n\n// ============================================================================\n// DLQ Message Creation\n// ============================================================================\n\n/**\n * Create a dead letter message from a failed queue message.\n *\n * @param originalMessage - The original message that failed processing\n * @param originalQueue - Name of the queue where the message failed\n * @param error - The error that caused the failure\n * @returns Dead letter message ready to be sent to DLQ\n *\n * @example\n * ```typescript\n * import { createDeadLetterMessage } from '@cloudwerk/queue'\n *\n * export default defineQueue<EmailMessage>({\n *   config: {\n *     deadLetterQueue: 'email-dlq',\n *   },\n *   async process(message) {\n *     try {\n *       await sendEmail(message.body)\n *       message.ack()\n *     } catch (error) {\n *       // Message will automatically go to DLQ after max retries\n *       // Or manually send to DLQ:\n *       message.deadLetter(error.message)\n *     }\n *   }\n * })\n * ```\n */\nexport function createDeadLetterMessage<T>(\n  originalMessage: QueueMessage<T>,\n  originalQueue: string,\n  error: Error\n): DeadLetterMessage<T> {\n  return {\n    originalQueue,\n    originalMessage: originalMessage.body,\n    error: error.message,\n    stack: error.stack,\n    attempts: originalMessage.attempts,\n    failedAt: new Date().toISOString(),\n    originalMessageId: originalMessage.id,\n  }\n}\n\n// ============================================================================\n// DLQ Configuration\n// ============================================================================\n\n/**\n * Configuration for dead letter queue handling.\n */\nexport interface DLQConfig {\n  /**\n   * Name of the dead letter queue.\n   */\n  queueName: string\n\n  /**\n   * Maximum retries before sending to DLQ.\n   * @default 3\n   */\n  maxRetries?: number\n\n  /**\n   * Custom handler called before sending to DLQ.\n   * Return false to prevent the message from being sent to DLQ.\n   */\n  beforeDLQ?: <T>(\n    message: QueueMessage<T>,\n    error: Error\n  ) => Awaitable<boolean | void>\n\n  /**\n   * Custom handler called after sending to DLQ.\n   */\n  afterDLQ?: <T>(\n    dlqMessage: DeadLetterMessage<T>\n  ) => Awaitable<void>\n}\n\n/**\n * Create DLQ configuration with defaults.\n *\n * @param queueName - Name of the dead letter queue\n * @param options - Optional configuration overrides\n * @returns Complete DLQ configuration\n */\nexport function createDLQConfig(\n  queueName: string,\n  options?: Partial<Omit<DLQConfig, 'queueName'>>\n): DLQConfig {\n  return {\n    queueName,\n    maxRetries: options?.maxRetries ?? 3,\n    beforeDLQ: options?.beforeDLQ,\n    afterDLQ: options?.afterDLQ,\n  }\n}\n\n// ============================================================================\n// DLQ Validation\n// ============================================================================\n\n/**\n * Validate DLQ configuration.\n *\n * @param config - DLQ configuration to validate\n * @returns Array of validation error messages (empty if valid)\n */\nexport function validateDLQConfig(config: DLQConfig): string[] {\n  const errors: string[] = []\n\n  if (!config.queueName || config.queueName.trim() === '') {\n    errors.push('DLQ queue name is required')\n  }\n\n  if (config.queueName && !/^[a-z][a-z0-9-]*$/.test(config.queueName)) {\n    errors.push(\n      'DLQ queue name must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens'\n    )\n  }\n\n  if (config.maxRetries !== undefined) {\n    if (!Number.isInteger(config.maxRetries) || config.maxRetries < 0) {\n      errors.push('maxRetries must be a non-negative integer')\n    }\n  }\n\n  return errors\n}\n\n// ============================================================================\n// DLQ Processing Helpers\n// ============================================================================\n\n/**\n * Check if a message should be sent to DLQ based on attempts.\n *\n * @param message - The queue message\n * @param maxRetries - Maximum retry attempts (default: 3)\n * @returns true if message has exceeded max retries\n */\nexport function shouldSendToDLQ<T>(\n  message: QueueMessage<T>,\n  maxRetries: number = 3\n): boolean {\n  return message.attempts > maxRetries\n}\n\n/**\n * Extract original message from a DLQ message.\n *\n * @param dlqMessage - Dead letter message\n * @returns The original message body\n */\nexport function extractOriginalMessage<T>(\n  dlqMessage: DeadLetterMessage<T>\n): T {\n  return dlqMessage.originalMessage\n}\n\n/**\n * Check if a message is a dead letter message.\n *\n * @param message - Message to check\n * @returns true if message is a DeadLetterMessage\n */\nexport function isDeadLetterMessage(\n  message: unknown\n): message is DeadLetterMessage {\n  if (typeof message !== 'object' || message === null) {\n    return false\n  }\n\n  const dlm = message as Record<string, unknown>\n  return (\n    typeof dlm.originalQueue === 'string' &&\n    'originalMessage' in dlm &&\n    typeof dlm.error === 'string' &&\n    typeof dlm.attempts === 'number' &&\n    typeof dlm.failedAt === 'string' &&\n    typeof dlm.originalMessageId === 'string'\n  )\n}\n\n// ============================================================================\n// DLQ Queue Definition Helper\n// ============================================================================\n\n/**\n * Create a DLQ consumer configuration.\n *\n * This is a convenience helper for defining DLQ consumers with appropriate\n * defaults and error handling.\n *\n * @param handler - Handler for processing dead letter messages\n * @returns Queue config for the DLQ consumer\n *\n * @example\n * ```typescript\n * // app/queues/email-dlq.ts\n * import { defineDLQConsumer } from '@cloudwerk/queue'\n *\n * export default defineDLQConsumer<EmailMessage>(async (dlqMessage) => {\n *   // Log failed message for manual inspection\n *   await logFailedMessage({\n *     queue: dlqMessage.originalQueue,\n *     error: dlqMessage.error,\n *     attempts: dlqMessage.attempts,\n *     message: dlqMessage.originalMessage,\n *   })\n *\n *   // Optionally alert on critical failures\n *   if (dlqMessage.attempts > 10) {\n *     await sendAlert(`Critical: ${dlqMessage.originalQueue} message failed`)\n *   }\n * })\n * ```\n */\nexport function defineDLQConsumer<T>(\n  handler: (dlqMessage: DeadLetterMessage<T>) => Awaitable<void>\n): {\n  config: { maxRetries: number }\n  process: (message: QueueMessage<DeadLetterMessage<T>>) => Promise<void>\n} {\n  return {\n    config: {\n      // DLQ consumers typically shouldn't retry much\n      // to avoid infinite loops\n      maxRetries: 1,\n    },\n    async process(message: QueueMessage<DeadLetterMessage<T>>) {\n      await handler(message.body)\n      message.ack()\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@cloudwerk/queue",
+  "version": "0.0.1",
+  "description": "Queue producers and consumers for Cloudwerk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/squirrelsoft-dev/cloudwerk.git",
+    "directory": "packages/queue"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@cloudwerk/core": "0.12.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.0.0",
+    "tsup": "^8.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0",
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest --run",
+    "test:watch": "vitest"
+  }
+}