alepha 0.12.1 → 0.13.1

package/dist/queue/index.d.cts

@@ -1,1265 +0,0 @@
-import * as alepha1 from "alepha";
-import { Alepha, Descriptor, KIND, Service, Static, TSchema } from "alepha";
-import * as alepha_logger1 from "alepha/logger";
-import { DateTimeProvider } from "alepha/datetime";
-
-//#region src/queue/interfaces/QueueJob.d.ts
-/**
- * Represents a job in the queue system.
- *
- * Jobs are the core unit of work in the queue. They contain the payload to be processed,
- * options for controlling behavior (priority, retries, delays), and state tracking.
- */
-interface QueueJob<T = unknown> {
-  /**
-   * Unique identifier for the job.
-   */
-  id: string;
-  /**
-   * The queue this job belongs to.
-   */
-  queue: string;
-  /**
-   * The actual data to be processed.
-   */
-  payload: T;
-  /**
-   * Job configuration options.
-   */
-  options: QueueJobOptions;
-  /**
-   * Current state of the job.
-   */
-  state: QueueJobState;
-}
-/**
- * Options for configuring job behavior.
- */
-interface QueueJobOptions {
-  /**
-   * Job priority. Lower values = higher priority.
-   * Jobs with lower priority values are processed first.
-   *
-   * @default 0
-   */
-  priority?: number;
-  /**
-   * Delay in milliseconds before the job becomes available for processing.
-   * The job will be in "delayed" status until the delay expires.
-   *
-   * @default 0 (no delay)
-   */
-  delay?: number;
-  /**
-   * Maximum number of processing attempts before the job is marked as failed.
-   * Includes the initial attempt.
-   *
-   * @default 1 (no retries)
-   */
-  maxAttempts?: number;
-  /**
-   * Backoff configuration for retries.
-   * Controls the delay between retry attempts.
-   */
-  backoff?: QueueJobBackoff;
-  /**
-   * Maximum time in milliseconds a job can be processed before it's considered stalled.
-   * If the worker doesn't complete or extend the lock within this time, the job
-   * can be picked up by another worker.
-   *
-   * @default 30000 (30 seconds)
-   */
-  lockDuration?: number;
-  /**
-   * Automatically remove jobs when they complete successfully.
-   * - `true`: Remove immediately after completion
-   * - `false`: Keep in completed list (default)
-   * - `number`: Keep this many most recent completed jobs, remove older ones
-   *
-   * @default false
-   */
-  removeOnComplete?: boolean | number;
-  /**
-   * Automatically remove jobs when they fail permanently (after all retries exhausted).
-   * - `true`: Remove immediately after failure
-   * - `false`: Keep in failed list (default)
-   * - `number`: Keep this many most recent failed jobs, remove older ones
-   *
-   * @default false
-   */
-  removeOnFail?: boolean | number;
-}
-/**
- * Backoff configuration for job retries.
- */
-interface QueueJobBackoff {
-  /**
-   * Type of backoff strategy.
-   * - "fixed": Same delay between all retries
-   * - "exponential": Delay doubles with each retry
-   */
-  type: "fixed" | "exponential";
-  /**
-   * Base delay in milliseconds.
-   * - For "fixed": The delay between all retries
-   * - For "exponential": Initial delay, then multiplied by 2^attempt
-   *
-   * @default 1000
-   */
-  delay?: number;
-  /**
-   * Maximum delay in milliseconds (for exponential backoff).
-   *
-   * @default 30000
-   */
-  maxDelay?: number;
-}
-/**
- * Current state of a job.
- */
-interface QueueJobState {
-  /**
-   * Current status of the job.
-   */
-  status: QueueJobStatus;
-  /**
-   * Number of processing attempts made (starts at 0, incremented before each attempt).
-   */
-  attempts: number;
-  /**
-   * Worker ID that currently holds the lock on this job.
-   * Only set when status is "active".
-   */
-  lockedBy?: string;
-  /**
-   * Timestamp (ms) when the current lock expires.
-   * If processing isn't completed by this time, the job is considered stalled.
-   */
-  lockedUntil?: number;
-  /**
-   * Error message from the last failed attempt.
-   */
-  error?: string;
-  /**
-   * Stack trace from the last failed attempt.
-   */
-  stackTrace?: string;
-  /**
-   * Result returned by the handler on successful completion.
-   */
-  result?: unknown;
-  /**
-   * Timestamp (ms) when the job was created.
-   */
-  createdAt: number;
-  /**
-   * Timestamp (ms) when the job should become available for processing.
-   * Used for delayed jobs.
-   */
-  availableAt?: number;
-  /**
-   * Timestamp (ms) when the job started processing (last attempt).
-   */
-  processedAt?: number;
-  /**
-   * Timestamp (ms) when the job completed successfully.
-   */
-  completedAt?: number;
-  /**
-   * Timestamp (ms) when the job failed (after all retries exhausted).
-   */
-  failedAt?: number;
-}
-/**
- * Possible statuses for a job.
- */
-type QueueJobStatus = "waiting" | "delayed" | "active" | "completed" | "failed";
-/**
- * Job counts by status.
- */
-type QueueJobCounts = Record<QueueJobStatus, number>;
-/**
- * Options for adding a job to the queue.
- * Simplified version of QueueJobOptions for the public API.
- */
-interface QueueAddJobOptions {
-  /**
-   * Job priority. Lower values = higher priority.
-   * @default 0
-   */
-  priority?: number;
-  /**
-   * Delay in milliseconds before processing.
-   * @default 0
-   */
-  delay?: number;
-}
-/**
- * Result of acquiring a job for processing.
- */
-interface QueueAcquiredJob<T = unknown> {
-  /**
-   * The queue the job was acquired from.
-   */
-  queue: string;
-  /**
-   * The acquired job.
-   */
-  job: QueueJob<T>;
-}
-/**
- * Options for cleaning old jobs.
- */
-interface QueueCleanOptions {
-  /**
-   * Maximum age in milliseconds. Jobs older than this will be removed.
-   */
-  maxAge?: number;
-  /**
-   * Maximum number of jobs to keep. Oldest jobs beyond this count are removed.
-   */
-  maxCount?: number;
-}
-/**
- * Options for querying jobs.
- */
-interface QueueGetJobsOptions {
-  /**
-   * Maximum number of jobs to return.
-   * @default 100
-   */
-  limit?: number;
-  /**
-   * Number of jobs to skip (for pagination).
-   * @default 0
-   */
-  offset?: number;
-}
-/**
- * Event types emitted by the queue system.
- */
-type QueueEventType = "waiting" | "active" | "completed" | "failed" | "stalled" | "progress" | "retrying" | "removed";
-/**
- * Base interface for all queue events.
- */
-interface QueueEventBase {
-  /**
-   * The queue name where the event occurred.
-   */
-  queue: string;
-  /**
-   * The job ID associated with the event.
-   */
-  jobId: string;
-  /**
-   * Timestamp when the event occurred.
-   */
-  timestamp: number;
-}
-/**
- * Event emitted when a job is added to the waiting queue.
- */
-interface QueueEventWaiting extends QueueEventBase {
-  type: "waiting";
-  /**
-   * The job that was added.
-   */
-  job: QueueJob;
-}
-/**
- * Event emitted when a job starts processing.
- */
-interface QueueEventActive extends QueueEventBase {
-  type: "active";
-  /**
-   * The worker ID that acquired the job.
-   */
-  workerId: string;
-  /**
-   * Current attempt number.
-   */
-  attempt: number;
-}
-/**
- * Event emitted when a job completes successfully.
- */
-interface QueueEventCompleted extends QueueEventBase {
-  type: "completed";
-  /**
-   * The result returned by the job handler.
-   */
-  result?: unknown;
-  /**
-   * Total processing time in milliseconds.
-   */
-  duration: number;
-}
-/**
- * Event emitted when a job fails permanently (all retries exhausted).
- */
-interface QueueEventFailed extends QueueEventBase {
-  type: "failed";
-  /**
-   * The error message.
-   */
-  error: string;
-  /**
-   * The stack trace if available.
-   */
-  stackTrace?: string;
-  /**
-   * Number of attempts made.
-   */
-  attempts: number;
-}
-/**
- * Event emitted when a job is detected as stalled.
- */
-interface QueueEventStalled extends QueueEventBase {
-  type: "stalled";
-  /**
-   * The worker ID that was processing the job.
-   */
-  workerId?: string;
-  /**
-   * Whether the job will be retried.
-   */
-  willRetry: boolean;
-}
-/**
- * Event emitted when a job reports progress.
- */
-interface QueueEventProgress extends QueueEventBase {
-  type: "progress";
-  /**
-   * Progress data (0-100 or custom object).
-   */
-  progress: number | Record<string, unknown>;
-}
-/**
- * Event emitted when a job is being retried after a failure.
- */
-interface QueueEventRetrying extends QueueEventBase {
-  type: "retrying";
-  /**
-   * The error from the previous attempt.
-   */
-  error: string;
-  /**
-   * The attempt number that will be made.
-   */
-  attempt: number;
-  /**
-   * Delay in milliseconds before retry.
-   */
-  delay: number;
-}
-/**
- * Event emitted when a job is removed from the queue.
- */
-interface QueueEventRemoved extends QueueEventBase {
-  type: "removed";
-  /**
-   * The status the job was in when removed.
-   */
-  previousStatus: QueueJobStatus;
-}
-/**
- * Union type of all queue events.
- */
-type QueueEvent = QueueEventWaiting | QueueEventActive | QueueEventCompleted | QueueEventFailed | QueueEventStalled | QueueEventProgress | QueueEventRetrying | QueueEventRemoved;
-/**
- * Handler function for queue events.
- */
-type QueueEventHandler<T extends QueueEvent = QueueEvent> = (event: T) => void | Promise<void>;
-/**
- * Map of event types to their corresponding event interfaces.
- */
-interface QueueEventMap {
-  waiting: QueueEventWaiting;
-  active: QueueEventActive;
-  completed: QueueEventCompleted;
-  failed: QueueEventFailed;
-  stalled: QueueEventStalled;
-  progress: QueueEventProgress;
-  retrying: QueueEventRetrying;
-  removed: QueueEventRemoved;
-}
-//#endregion
-//#region src/queue/providers/QueueProvider.d.ts
-/**
- * Queue provider interface supporting both simple message-based and advanced job-based operations.
- *
- * The simple API (push/pop/popBlocking) is for basic fire-and-forget messaging.
- * The job API provides crash recovery, retries, delayed jobs, priorities, and job history.
- */
-declare abstract class QueueProvider {
-  protected eventHandlers: Map<QueueEventType | "*", Set<QueueEventHandler<QueueEvent>>>;
-  /**
-   * Subscribe to queue events.
-   *
-   * @param event Event type to listen for, or "*" for all events.
-   * @param handler Handler function to call when event occurs.
-   * @returns Unsubscribe function.
-   *
-   * @example
-   * ```ts
-   * // Listen for completed events
-   * const unsubscribe = provider.on("completed", (event) => {
-   *   console.log(`Job ${event.jobId} completed in ${event.duration}ms`);
-   * });
-   *
-   * // Listen for all events
-   * provider.on("*", (event) => {
-   *   console.log(`Event: ${event.type} for job ${event.jobId}`);
-   * });
-   *
-   * // Unsubscribe later
-   * unsubscribe();
-   * ```
-   */
-  on<T extends QueueEventType>(event: T, handler: QueueEventHandler<QueueEventMap[T]>): () => void;
-  on(event: "*", handler: QueueEventHandler<QueueEvent>): () => void;
-  /**
-   * Emit a queue event to all registered handlers.
-   *
-   * @param event The event to emit.
-   */
-  protected emit(event: QueueEvent): Promise<void>;
-  /**
-   * Push a message to the queue.
-   *
-   * @param queue Name of the queue to push the message to.
-   * @param message String message to be pushed to the queue.
-   */
-  abstract push(queue: string, message: string): Promise<void>;
-  /**
-   * Pop a message from the queue.
-   *
-   * @param queue Name of the queue to pop the message from.
-   * @returns The message popped or `undefined` if the queue is empty.
-   */
-  abstract pop(queue: string): Promise<string | undefined>;
-  /**
-   * Pop a message from one of the specified queues, blocking until available or timeout.
-   *
-   * @param queues Array of queue names to listen on.
-   * @param timeoutSeconds Maximum time to wait in seconds.
-   * @returns Object with queue name and message, or `undefined` if timeout expired.
-   */
-  abstract popBlocking(queues: string[], timeoutSeconds: number): Promise<{
-    queue: string;
-    message: string;
-  } | undefined>;
-  /**
-   * Add a job to the queue.
-   *
-   * @param queue Queue name.
-   * @param payload Job data to process.
-   * @param options Job options (priority, delay, retries, etc.).
-   * @returns The created job.
-   */
-  abstract addJob<T>(queue: string, payload: T, options?: QueueJobOptions): Promise<QueueJob<T>>;
-  /**
-   * Acquire the next available job for processing.
-   *
-   * This atomically:
-   * 1. Finds the highest priority job that is ready for processing
-   * 2. Moves it to "active" status
-   * 3. Sets a lock with the worker ID
-   *
-   * @param queues Queue names to check (in order of preference).
-   * @param workerId Unique identifier for the worker acquiring the job.
-   * @param timeoutSeconds Maximum time to wait for a job.
-   * @returns The acquired job or undefined if timeout.
-   */
-  abstract acquireJob(queues: string[], workerId: string, timeoutSeconds: number): Promise<QueueAcquiredJob | undefined>;
-  /**
-   * Mark a job as completed successfully.
-   *
-   * @param queue Queue name.
-   * @param jobId Job ID.
-   * @param result Optional result data from processing.
-   */
-  abstract completeJob(queue: string, jobId: string, result?: unknown): Promise<void>;
-  /**
-   * Mark a job as failed.
-   *
-   * If the job has remaining retry attempts, it will be moved to "delayed" status
-   * (for backoff) or "waiting" status. Otherwise, it will be moved to "failed" status.
-   *
-   * @param queue Queue name.
-   * @param jobId Job ID.
-   * @param error Error message.
-   * @param stackTrace Optional stack trace.
-   */
-  abstract failJob(queue: string, jobId: string, error: string, stackTrace?: string): Promise<void>;
-  /**
-   * Extend the lock on an active job.
-   *
-   * Workers should call this periodically while processing long-running jobs
-   * to prevent them from being considered stalled.
-   *
-   * @param queue Queue name.
-   * @param jobId Job ID.
-   * @param workerId Worker ID (must match the lock holder).
-   * @returns True if lock was extended, false if job is not locked by this worker.
-   */
-  abstract renewJobLock(queue: string, jobId: string, workerId: string): Promise<boolean>;
-  /**
-   * Get a job by ID.
-   *
-   * @param queue Queue name.
-   * @param jobId Job ID.
-   * @returns The job or undefined if not found.
-   */
-  abstract getJob(queue: string, jobId: string): Promise<QueueJob | undefined>;
-  /**
-   * Get jobs by status.
-   *
-   * @param queue Queue name.
-   * @param status Job status to filter by.
-   * @param options Pagination options.
-   * @returns Array of jobs.
-   */
-  abstract getJobs(queue: string, status: QueueJobStatus, options?: QueueGetJobsOptions): Promise<QueueJob[]>;
-  /**
-   * Get job counts by status.
-   *
-   * @param queue Queue name.
-   * @returns Object with counts for each status.
-   */
-  abstract getJobCounts(queue: string): Promise<QueueJobCounts>;
-  /**
-   * Promote delayed jobs that are ready for processing.
-   *
-   * Moves jobs from "delayed" to "waiting" status when their availableAt time has passed.
-   *
-   * @param queue Queue name.
-   * @returns Number of jobs promoted.
-   */
-  abstract promoteDelayedJobs(queue: string): Promise<number>;
-  /**
-   * Recover stalled jobs.
-   *
-   * Finds jobs in "active" status whose locks have expired and either:
-   * - Moves them back to "waiting" for retry (if attempts remaining)
-   * - Moves them to "failed" (if no attempts remaining)
-   *
-   * @param queue Queue name.
-   * @param stalledThresholdMs Jobs with expired locks older than this are considered stalled.
-   * @returns Array of recovered job IDs.
-   */
-  abstract recoverStalledJobs(queue: string, stalledThresholdMs: number): Promise<string[]>;
-  /**
-   * Remove old completed or failed jobs.
-   *
-   * @param queue Queue name.
-   * @param status Status to clean ("completed" or "failed").
-   * @param options Cleaning options (maxAge, maxCount).
-   * @returns Number of jobs removed.
-   */
-  abstract cleanJobs(queue: string, status: "completed" | "failed", options?: QueueCleanOptions): Promise<number>;
-  /**
-   * Remove a specific job.
-   *
-   * @param queue Queue name.
-   * @param jobId Job ID.
-   */
-  abstract removeJob(queue: string, jobId: string): Promise<void>;
-  /**
-   * Cancel all pending waiters.
-   *
-   * This is called during shutdown to immediately release all blocking
-   * acquireJob calls, preventing shutdown delays.
-   */
-  abstract cancelWaiters(): void;
-}
-//#endregion
-//#region src/queue/providers/MemoryQueueProvider.d.ts
-interface MessageWaiter {
-  queues: Set<string>;
-  resolve: (result: {
-    queue: string;
-    message: string;
-  } | undefined) => void;
-  timer: ReturnType<typeof setTimeout>;
-}
-interface JobWaiter {
-  queues: Set<string>;
-  workerId: string;
-  resolve: (result: QueueAcquiredJob | undefined) => void;
-  timer: ReturnType<typeof setTimeout>;
-}
-/**
- * In-memory queue provider with full job support.
- *
- * This provider stores all data in memory and is suitable for:
- * - Development and testing
- * - Single-instance applications
- * - Scenarios where job persistence across restarts is not required
- */
-declare class MemoryQueueProvider extends QueueProvider {
-  protected readonly log: alepha_logger1.Logger;
-  protected messageQueues: Record<string, string[]>;
-  protected messageWaiters: Set<MessageWaiter>;
-  protected jobs: Map<string, Map<string, QueueJob>>;
-  protected waiting: Map<string, string[]>;
-  protected delayed: Map<string, string[]>;
-  protected active: Map<string, Set<string>>;
-  protected completed: Map<string, string[]>;
-  protected failed: Map<string, string[]>;
-  protected jobWaiters: Set<JobWaiter>;
-  protected jobIdCounter: number;
-  push(queue: string, ...messages: string[]): Promise<void>;
-  pop(queue: string): Promise<string | undefined>;
-  popBlocking(queues: string[], timeoutSeconds: number): Promise<{
-    queue: string;
-    message: string;
-  } | undefined>;
-  protected findMessageWaiter(queue: string): MessageWaiter | undefined;
-  protected removeMessageWaiter(waiter: MessageWaiter): void;
-  protected generateJobId(): string;
-  protected ensureQueueStructures(queue: string): void;
-  addJob<T>(queue: string, payload: T, options?: QueueJobOptions): Promise<QueueJob<T>>;
-  protected insertWaiting(queue: string, job: QueueJob): void;
-  protected insertDelayed(queue: string, job: QueueJob): void;
-  protected notifyJobWaiters(queue: string): void;
-  protected removeJobWaiter(waiter: JobWaiter): void;
-  protected tryAcquireJob(queues: string[], workerId: string): QueueAcquiredJob | undefined;
-  acquireJob(queues: string[], workerId: string, timeoutSeconds: number): Promise<QueueAcquiredJob | undefined>;
-  completeJob(queue: string, jobId: string, result?: unknown): Promise<void>;
-  failJob(queue: string, jobId: string, error: string, stackTrace?: string): Promise<void>;
-  protected calculateBackoff(job: QueueJob): number;
-  renewJobLock(queue: string, jobId: string, workerId: string): Promise<boolean>;
-  getJob(queue: string, jobId: string): Promise<QueueJob | undefined>;
-  getJobs(queue: string, status: QueueJobStatus, options?: QueueGetJobsOptions): Promise<QueueJob[]>;
-  getJobCounts(queue: string): Promise<QueueJobCounts>;
-  promoteDelayedJobs(queue: string): Promise<number>;
-  recoverStalledJobs(queue: string, stalledThresholdMs: number): Promise<string[]>;
-  cleanJobs(queue: string, status: "completed" | "failed", options?: QueueCleanOptions): Promise<number>;
-  removeJob(queue: string, jobId: string): Promise<void>;
-  cancelWaiters(): void;
-}
-//#endregion
-//#region src/queue/descriptors/$queue.d.ts
-/**
- * Creates a queue descriptor for asynchronous message processing with background workers.
- *
- * The $queue descriptor 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.
- *
- * **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
- *
- * **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
- *
- * **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
- * ```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"]))
- *   }),
- *   handler: async (message) => {
- *     await emailService.send(message.payload);
- *     console.log(`Email sent to ${message.payload.to}`);
- *   }
- * });
- *
- * // Push messages for background processing
- * await emailQueue.push({
- *   to: "user@example.com",
- *   subject: "Welcome!",
- *   body: "Welcome to our platform",
- *   priority: "high"
- * });
- * ```
- *
- * @example Batch processing with Redis
- * ```typescript
- * const imageQueue = $queue({
- *   name: "image-processing",
- *   provider: RedisQueueProvider,
- *   schema: t.object({
- *     imageId: t.text(),
- *     operations: t.array(t.enum(["resize", "compress", "thumbnail"]))
- *   }),
- *   handler: async (message) => {
- *     for (const op of message.payload.operations) {
- *       await processImage(message.payload.imageId, op);
- *     }
- *   }
- * });
- *
- * // Batch processing multiple images
- * await imageQueue.push(
- *   { imageId: "img1", operations: ["resize", "thumbnail"] },
- *   { imageId: "img2", operations: ["compress"] },
- *   { imageId: "img3", operations: ["resize", "compress", "thumbnail"] }
- * );
- * ```
- *
- * @example Development with memory provider
- * ```typescript
- * const taskQueue = $queue({
- *   name: "dev-tasks",
- *   provider: "memory",
- *   schema: t.object({
- *     taskType: t.enum(["cleanup", "backup", "report"]),
- *     data: t.record(t.text(), t.any())
- *   }),
- *   handler: async (message) => {
- *     switch (message.payload.taskType) {
- *       case "cleanup":
- *         await performCleanup(message.payload.data);
- *         break;
- *       case "backup":
- *         await createBackup(message.payload.data);
- *         break;
- *       case "report":
- *         await generateReport(message.payload.data);
- *         break;
- *     }
- *   }
- * });
- * ```
- */
-declare const $queue: {
-  <T extends TSchema>(options: QueueDescriptorOptions<T>): QueueDescriptor<T>;
-  [KIND]: typeof QueueDescriptor;
-};
-interface QueueDescriptorOptions<T extends TSchema> {
-  /**
-   * Unique name for the queue.
-   *
-   * This name is used for:
-   * - Queue identification across the system
-   * - Storage backend key generation
-   * - Logging and monitoring
-   * - Worker assignment and routing
-   *
-   * If not provided, defaults to the property key where the queue is declared.
-   *
-   * @example "email-notifications"
-   * @example "image-processing"
-   * @example "order-fulfillment"
-   */
-  name?: string;
-  /**
-   * Human-readable description of the queue's purpose.
-   *
-   * Used for:
-   * - Documentation generation
-   * - Monitoring dashboards
-   * - Development team communication
-   * - Queue management interfaces
-   *
-   * @example "Process user registration emails and welcome sequences"
-   * @example "Handle image uploads, resizing, and thumbnail generation"
-   * @example "Manage order processing, payment, and shipping workflows"
-   */
-  description?: string;
-  /**
-   * Queue storage provider configuration.
-   *
-   * Options:
-   * - **"memory"**: In-memory queue (default for development, lost on restart)
-   * - **Service<QueueProvider>**: Custom provider class (e.g., RedisQueueProvider)
-   * - **undefined**: Uses the default queue provider from dependency injection
-   *
-   * **Provider Selection Guidelines**:
-   * - Development: Use "memory" for fast, simple testing
-   * - Production: Use Redis or database-backed providers for persistence
-   * - High-throughput: Use specialized providers with connection pooling
-   * - Distributed systems: Use Redis or message brokers for scalability
-   *
-   * @default Uses injected QueueProvider
-   * @example "memory"
-   * @example RedisQueueProvider
-   * @example DatabaseQueueProvider
-   */
-  provider?: "memory" | Service<QueueProvider>;
-  /**
-   * TypeBox schema defining the structure of messages in this queue.
-   *
-   * This schema:
-   * - Validates all messages pushed to the queue
-   * - Provides full TypeScript type inference
-   * - Ensures type safety between producers and consumers
-   * - Enables automatic serialization/deserialization
-   *
-   * **Schema Design Best Practices**:
-   * - Keep schemas simple and focused on the specific task
-   * - Use optional fields for data that might not always be available
-   * - Include version fields for schema evolution
-   * - Use union types for different message types in the same queue
-   *
-   * @example
-   * ```ts
-   * t.object({
-   *   userId: t.text(),
-   *   action: t.enum(["create", "update"]),
-   *   data: t.record(t.text(), t.any()),
-   *   timestamp: t.optional(t.number())
-   * })
-   * ```
-   */
-  schema: T;
-  /**
-   * Message handler function that processes queue messages.
-   *
-   * This function:
-   * - Runs in background worker threads for non-blocking processing
-   * - Receives type-safe message payloads based on the schema
-   * - Should be idempotent to handle potential retries
-   * - Can throw errors to trigger retry mechanisms
-   * - Has access to the full Alepha dependency injection container
-   *
-   * **Handler Best Practices**:
-   * - Keep handlers focused on a single responsibility
-   * - Use proper error handling and logging
-   * - Make operations idempotent when possible
-   * - Validate critical business logic within handlers
-   * - Consider using transactions for data consistency
-   *
-   * @param message - The queue message with validated payload
-   * @returns Promise that resolves when processing is complete
-   *
-   * @example
-   * ```ts
-   * handler: async (message) => {
-   *   const { userId, email, template } = message.payload;
-   *
-   *   try {
-   *     await this.emailService.send({
-   *       to: email,
-   *       template,
-   *       data: { userId }
-   *     });
-   *
-   *     await this.userService.markEmailSent(userId, template);
-   *   } catch (error) {
-   *     // Log error and let the queue system handle retries
-   *     this.logger.error(`Failed to send email to ${email}`, error);
-   *     throw error;
-   *   }
-   * }
-   * ```
-   */
-  handler?: (message: QueueMessage<T>) => Promise<void>;
-  /**
-   * Maximum number of processing attempts before the job is marked as failed.
-   * Includes the initial attempt.
-   *
-   * Set this to enable automatic retries on failure.
-   *
-   * @default 1 (no retries)
-   * @example 3 // Allows 2 retries after initial failure
-   */
-  maxAttempts?: number;
-  /**
-   * Backoff configuration for retries.
-   * Controls the delay between retry attempts.
-   *
-   * @example
-   * ```ts
-   * backoff: {
-   *   type: "exponential",
-   *   delay: 1000,      // Initial delay: 1 second
-   *   maxDelay: 60000   // Maximum delay: 1 minute
-   * }
-   * ```
-   */
-  backoff?: QueueJobBackoff;
-  /**
-   * Maximum time in milliseconds a job can be processed before it's considered stalled.
-   * If the worker doesn't complete or extend the lock within this time, the job
-   * can be picked up by another worker.
-   *
-   * Increase this for long-running jobs.
-   *
-   * @default 30000 (30 seconds)
-   */
-  lockDuration?: number;
-  /**
-   * Automatically remove jobs when they complete successfully.
-   * - `true`: Remove immediately after completion
-   * - `false`: Keep in completed list (default)
-   * - `number`: Keep this many most recent completed jobs, remove older ones
-   *
-   * @default false
-   * @example
-   * ```ts
-   * // Remove immediately after completion
-   * removeOnComplete: true
-   *
-   * // Keep only the last 100 completed jobs
-   * removeOnComplete: 100
-   * ```
-   */
-  removeOnComplete?: boolean | number;
-  /**
-   * Automatically remove jobs when they fail permanently (after all retries exhausted).
-   * - `true`: Remove immediately after failure
-   * - `false`: Keep in failed list (default)
-   * - `number`: Keep this many most recent failed jobs, remove older ones
-   *
-   * @default false
-   * @example
-   * ```ts
-   * // Remove immediately after failure
-   * removeOnFail: true
-   *
-   * // Keep only the last 50 failed jobs for debugging
-   * removeOnFail: 50
-   * ```
-   */
-  removeOnFail?: boolean | number;
-}
-declare class QueueDescriptor<T extends TSchema> extends Descriptor<QueueDescriptorOptions<T>> {
-  protected readonly log: alepha_logger1.Logger;
-  readonly provider: QueueProvider | MemoryQueueProvider;
-  /**
-   * Push one or more payloads to the queue for background processing.
-   *
-   * Jobs will be processed with crash recovery, retries (if configured),
-   * and proper lifecycle management.
-   *
-   * @param payloads - One or more payloads to queue
-   */
-  push(...payloads: Array<Static<T>>): Promise<void>;
-  /**
-   * Push a payload to the queue with specific options.
-   *
-   * @param payload - The payload to queue
-   * @param options - Job options (priority, delay)
-   */
-  push(payload: Static<T>, options: QueueAddJobOptions): Promise<void>;
-  /**
-   * Get default job options from descriptor configuration.
-   */
-  protected getDefaultJobOptions(): {
-    maxAttempts: number | undefined;
-    backoff: QueueJobBackoff | undefined;
-    lockDuration: number | undefined;
-    removeOnComplete: number | boolean | undefined;
-    removeOnFail: number | boolean | undefined;
-  };
-  get name(): string;
-  protected $provider(): QueueProvider | MemoryQueueProvider;
-}
-interface QueueMessageSchema {
-  payload: TSchema;
-}
-interface QueueMessage<T extends TSchema> {
-  payload: Static<T>;
-}
-//#endregion
-//#region src/queue/descriptors/$consumer.d.ts
-/**
- * Creates a consumer descriptor to process messages from a specific queue.
- *
- * Provides a dedicated message consumer that connects to a queue and processes messages
- * with custom handler logic, enabling scalable architectures where multiple consumers
- * can process messages from the same queue.
- *
- * **Key Features**
- * - Seamless integration with any $queue descriptor
- * - Full type safety inherited from queue schema
- * - Automatic worker management for background processing
- * - Built-in error handling and retry mechanisms
- * - Support for multiple consumers per queue for horizontal scaling
- *
- * **Common Use Cases**
- * - Email sending and notification services
- * - Image and media processing workers
- * - Data synchronization and background jobs
- *
- * @example
- * ```ts
- * class EmailService {
- *   emailQueue = $queue({
- *     name: "emails",
- *     schema: t.object({
- *       to: t.text(),
- *       subject: t.text(),
- *       body: t.text()
- *     })
- *   });
- *
- *   emailConsumer = $consumer({
- *     queue: this.emailQueue,
- *     handler: async (message) => {
- *       const { to, subject, body } = message.payload;
- *       await this.sendEmail(to, subject, body);
- *     }
- *   });
- *
- *   async sendWelcomeEmail(userEmail: string) {
- *     await this.emailQueue.push({
- *       to: userEmail,
- *       subject: "Welcome!",
- *       body: "Thanks for joining."
- *     });
- *   }
- * }
- * ```
- */
-declare const $consumer: {
-  <T extends TSchema>(options: ConsumerDescriptorOptions<T>): ConsumerDescriptor<T>;
-  [KIND]: typeof ConsumerDescriptor;
-};
-interface ConsumerDescriptorOptions<T extends TSchema> {
-  /**
-   * The queue descriptor that this consumer will process messages from.
-   *
-   * This establishes the connection between the consumer and its source queue:
-   * - The consumer inherits the queue's message schema for type safety
-   * - Messages pushed to the queue will be automatically routed to this consumer
-   * - Multiple consumers can be attached to the same queue for parallel processing
-   * - The consumer will use the queue's provider and configuration settings
-   *
-   * **Queue Integration Benefits**:
-   * - Type safety: Consumer handler gets fully typed message payloads
-   * - Schema validation: Messages are validated before reaching the consumer
-   * - Error handling: Failed messages can be retried or moved to dead letter queues
-   * - Monitoring: Queue metrics include consumer processing statistics
-   *
-   * @example
-   * ```ts
-   * // First, define a queue
-   * emailQueue = $queue({
-   *   name: "emails",
-   *   schema: t.object({ to: t.text(), subject: t.text() })
-   * });
-   *
-   * // Then, create a consumer for that queue
-   * emailConsumer = $consumer({
-   *   queue: this.emailQueue,  // Reference the queue descriptor
-   *   handler: async (message) => { } // process email
-   * });
-   * ```
-   */
-  queue: QueueDescriptor<T>;
-  /**
-   * Message handler function that processes individual messages from the queue.
-   *
-   * This function:
-   * - Receives fully typed and validated message payloads from the connected queue
-   * - Runs in the background worker system for non-blocking operation
-   * - Should implement the core business logic for processing this message type
-   * - Can throw errors to trigger the queue's retry mechanisms
-   * - Has access to the full Alepha dependency injection container
-   * - Should be idempotent to handle potential duplicate deliveries
-   *
-   * **Handler Design Guidelines**:
-   * - Keep handlers focused on a single responsibility
-   * - Use proper error handling and meaningful error messages
-   * - Log important processing steps for debugging and monitoring
-   * - Consider transaction boundaries for data consistency
-   * - Make operations idempotent when possible
-   * - Validate business rules within the handler logic
-   *
-   * **Error Handling Strategy**:
-   * - Throw errors for temporary failures that should be retried
-   * - Log and handle permanent failures gracefully
-   * - Use specific error types to control retry behavior
-   * - Consider implementing circuit breakers for external service calls
-   *
-   * @param message - The queue message containing the validated payload
-   * @param message.payload - The typed message data based on the queue's schema
-   * @returns Promise that resolves when processing is complete
-   *
-   * @example
-   * ```ts
-   * handler: async (message) => {
-   *   const { userId, action, data } = message.payload;
-   *
-   *   try {
-   *     // Log processing start
-   *     this.logger.info(`Processing ${action} for user ${userId}`);
-   *
-   *     // Validate business rules
-   *     if (!await this.userService.exists(userId)) {
-   *       throw new Error(`User ${userId} not found`);
-   *     }
-   *
-   *     // Perform the main processing logic
-   *     switch (action) {
-   *       case "create":
-   *         await this.processCreation(userId, data);
-   *         break;
-   *       case "update":
-   *         await this.processUpdate(userId, data);
-   *         break;
-   *       default:
-   *         throw new Error(`Unknown action: ${action}`);
-   *     }
-   *
-   *     // Log successful completion
-   *     this.logger.info(`Successfully processed ${action} for user ${userId}`);
-   *
-   *   } catch (error) {
-   *     // Log error with context
-   *     this.logger.error(`Failed to process ${action} for user ${userId}`, {
-   *       error: error.message,
-   *       userId,
-   *       action,
-   *       data
-   *     });
-   *
-   *     // Re-throw to trigger queue retry mechanism
-   *     throw error;
-   *   }
-   * }
-   * ```
-   */
-  handler: (message: {
-    payload: Static<T>;
-  }) => Promise<void>;
-}
-declare class ConsumerDescriptor<T extends TSchema> extends Descriptor<ConsumerDescriptorOptions<T>> {}
-//#endregion
-//#region src/queue/providers/WorkerProvider.d.ts
-declare const envSchema: alepha1.TObject<{
-  /**
-   * The timeout in seconds for blocking job acquisition.
-   * Workers will check for shutdown after each timeout period.
-   */
-  QUEUE_WORKER_BLOCKING_TIMEOUT: alepha1.TInteger;
-  /**
-   * The number of workers to run concurrently. Defaults to 1.
-   * Useful only if you are doing a lot of I/O.
-   */
-  QUEUE_WORKER_CONCURRENCY: alepha1.TInteger;
-  /**
-   * Interval in milliseconds for renewing job locks during processing.
-   * Should be less than the job's lock duration.
-   */
-  QUEUE_WORKER_LOCK_RENEWAL_INTERVAL: alepha1.TInteger;
-  /**
-   * Interval in milliseconds for the scheduler to check delayed jobs and stalled jobs.
-   */
-  QUEUE_SCHEDULER_INTERVAL: alepha1.TInteger;
-  /**
-   * Threshold in milliseconds after lock expiration to consider a job stalled.
-   */
-  QUEUE_STALLED_THRESHOLD: alepha1.TInteger;
-}>;
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-}
-declare class WorkerProvider {
-  protected readonly log: alepha_logger1.Logger;
-  protected readonly env: {
-    QUEUE_WORKER_BLOCKING_TIMEOUT: number;
-    QUEUE_WORKER_CONCURRENCY: number;
-    QUEUE_WORKER_LOCK_RENEWAL_INTERVAL: number;
-    QUEUE_SCHEDULER_INTERVAL: number;
-    QUEUE_STALLED_THRESHOLD: number;
-  };
-  protected readonly alepha: Alepha;
-  protected readonly queueProvider: QueueProvider;
-  protected readonly dateTime: DateTimeProvider;
-  protected workerPromises: Array<Promise<void>>;
-  protected workersRunning: number;
-  protected shouldStop: boolean;
-  protected consumers: Array<Consumer>;
-  protected consumersByProvider: Map<QueueProvider, Consumer[]>;
-  protected schedulerPromise: Promise<void> | undefined;
-  protected schedulerRunning: boolean;
-  protected abortController: AbortController | undefined;
-  protected workerId: string;
-  get isRunning(): boolean;
-  protected readonly start: alepha1.HookDescriptor<"start">;
-  /**
-   * Start the workers.
-   * Each worker acquires jobs and processes them with proper lifecycle management.
-   */
-  protected startWorkers(): void;
-  /**
-   * Start the scheduler for delayed job promotion and stalled job recovery.
-   */
-  protected startScheduler(): void;
-  /**
-   * Run one cycle of the scheduler.
-   * Promotes delayed jobs and recovers stalled jobs.
-   */
-  protected runSchedulerCycle(): Promise<void>;
-  protected readonly stop: alepha1.HookDescriptor<"stop">;
-  /**
-   * Acquire the next available job from any provider.
-   */
-  protected acquireNextJob(localWorkerId: string): Promise<AcquiredJobWithConsumer | undefined>;
-  /**
-   * Process a job with proper lifecycle management.
-   * - Starts a lock renewal interval
-   * - Calls the handler
-   * - Marks job as completed or failed
-   */
-  protected processJob({
-    acquired,
-    consumer,
-    provider
-  }: AcquiredJobWithConsumer, localWorkerId: string): Promise<void>;
-  /**
-   * Stop the workers and scheduler.
-   */
-  protected stopWorkers(): Promise<void>;
-}
-interface Consumer<T extends TSchema = TSchema> {
-  queue: QueueDescriptor<T>;
-  handler: (message: QueueMessage<T>) => Promise<void>;
-}
-interface AcquiredJobWithConsumer {
-  acquired: QueueAcquiredJob;
-  consumer: Consumer;
-  provider: QueueProvider;
-}
-//#endregion
-//#region src/queue/index.d.ts
-/**
- * Provides asynchronous message queuing and processing capabilities through declarative queue descriptors.
- *
- * The queue module enables reliable background job processing and message passing using the `$queue` descriptor
- * on class properties. It supports schema validation, automatic retries, and multiple queue backends for
- * building scalable, decoupled applications with robust error handling.
- *
- * @see {@link $queue}
- * @see {@link $consumer}
- * @module alepha.queue
- */
-declare const AlephaQueue: alepha1.Service<alepha1.Module>;
-//#endregion
-export { $consumer, $queue, AcquiredJobWithConsumer, AlephaQueue, Consumer, ConsumerDescriptor, ConsumerDescriptorOptions, MemoryQueueProvider, type QueueAcquiredJob, type QueueAddJobOptions, type QueueCleanOptions, QueueDescriptor, QueueDescriptorOptions, type QueueEvent, type QueueEventActive, type QueueEventBase, type QueueEventCompleted, type QueueEventFailed, type QueueEventHandler, type QueueEventMap, type QueueEventProgress, type QueueEventRemoved, type QueueEventRetrying, type QueueEventStalled, type QueueEventType, type QueueEventWaiting, type QueueGetJobsOptions, type QueueJob, type QueueJobBackoff, type QueueJobCounts, type QueueJobOptions, type QueueJobState, type QueueJobStatus, QueueMessage, QueueMessageSchema, QueueProvider, WorkerProvider };
-//# sourceMappingURL=index.d.cts.map