alepha 0.21.2 → 0.23.0

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

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

package/dist/queue/redis/index.d.ts

@@ -1,15 +1,13 @@
-import * as _$alepha from "alepha";
 import { Static } from "alepha";
 import { QueueProvider } from "alepha/queue";
 import { RedisProvider } from "alepha/redis";
-import * as _$typebox from "typebox";
 
 //#region ../../src/queue/redis/providers/RedisQueueProvider.d.ts
 /**
  * Redis queue configuration atom.
  */
-declare const redisQueueOptions: _$alepha.Atom<_$typebox.TObject<{
-  prefix: _$typebox.TString;
+declare const redisQueueOptions: import("alepha").Atom<import("typebox").TObject<{
+  prefix: import("typebox").TString;
 }>, "alepha.queue.redis.options">;
 type RedisQueueOptions = Static<typeof redisQueueOptions.schema>;
 declare module "alepha" {
@@ -34,7 +32,7 @@ declare class RedisQueueProvider implements QueueProvider {
  * @see {@link RedisQueueProvider}
  * @module alepha.queue.redis
  */
-declare const AlephaQueueRedis: _$alepha.Service<_$alepha.Module>;
+declare const AlephaQueueRedis: import("alepha").Service<import("alepha").Module>;
 //#endregion
 export { AlephaQueueRedis, RedisQueueOptions, RedisQueueProvider, redisQueueOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/queue/redis/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/queue/redis/providers/RedisQueueProvider.ts","../../../src/queue/redis/index.ts"],"mappings":";;;;;;;;;;cASa,iBAAA,EAAiB,QAAA,CAAA,IAAA,WAAA,OAAA;UAW5B,SAAA,CAAA,OAAA;AAAA;AAAA,KAEU,iBAAA,GAAoB,MAAA,QAAc,iBAAA,CAAkB,MAAA;AAAA;EAAA,UAGpD,KAAA;IAAA,CACP,iBAAA,CAAkB,GAAA,GAAM,iBAAA;EAAA;AAAA;AAAA,cAMhB,kBAAA,YAA8B,aAAA;EAAA,mBACtB,OAAA,EAAO,QAAA;;;qBACP,aAAA,EAAe,aAAA;EAE3B,MAAA,CAAO,KAAA;EAID,IAAA,CAAK,KAAA,UAAe,OAAA,WAAkB,OAAA;EAItC,GAAA,CAAI,KAAA,WAAgB,OAAA;AAAA;;;;;;;;;cC5BtB,gBAAA,EAAgB,QAAA,CAAA,OAAA,CAW3B,QAAA,CAX2B,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/queue/redis/providers/RedisQueueProvider.ts","../../../src/queue/redis/index.ts"],"mappings":";;;;;;;AASA;cAAa,iBAAA,mBAAiB,IAAA,mBAAA,OAAA;;;KAalB,iBAAA,GAAoB,MAAM,QAAQ,iBAAA,CAAkB,MAAA;AAAA;EAAA,UAGpD,KAAA;IAAA,CACP,iBAAA,CAAkB,GAAG,GAAG,iBAAA;EAAA;AAAA;AAAA,cAMhB,kBAAA,YAA8B,aAAA;EAAA,mBACtB,OAAA,EAAO,QAAA;;;qBACP,aAAA,EAAe,aAAA;EAE3B,MAAA,CAAO,KAAA;EAID,IAAA,CAAK,KAAA,UAAe,OAAA,WAAkB,OAAA;EAItC,GAAA,CAAI,KAAA,WAAgB,OAAA;AAAA;;;;;;;AAnCnC;;cCOa,gBAAA,mBAAgB,OAAA,kBAAA,MAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/queue/redis/providers/RedisQueueProvider.ts","../../../src/queue/redis/index.ts"],"sourcesContent":["import { $atom, $inject, $state, type Static, t } from \"alepha\";\nimport type { QueueProvider } from \"alepha/queue\";\nimport { RedisProvider } from \"alepha/redis\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Redis queue configuration atom.\n */\nexport const redisQueueOptions = $atom({\n  name: \"alepha.queue.redis.options\",\n  schema: t.object({\n    prefix: t.text({\n      default: \"queue\",\n      description: \"Prefix for all queue keys in Redis.\",\n    }),\n  }),\n  default: {\n    prefix: \"queue\",\n  },\n});\n\nexport type RedisQueueOptions = Static<typeof redisQueueOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [redisQueueOptions.key]: RedisQueueOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class RedisQueueProvider implements QueueProvider {\n  protected readonly options = $state(redisQueueOptions);\n  protected readonly redisProvider: RedisProvider = $inject(RedisProvider);\n\n  public prefix(queue: string): string {\n    return `${this.options.prefix}:${queue}`;\n  }\n\n  public async push(queue: string, message: string): Promise<void> {\n    await this.redisProvider.lpush(this.prefix(queue), message);\n  }\n\n  public async pop(queue: string): Promise<string | undefined> {\n    return this.redisProvider.rpop(this.prefix(queue));\n  }\n}\n","import { $module, type Alepha } from \"alepha\";\nimport { AlephaQueue, QueueProvider } from \"alepha/queue\";\nimport { RedisQueueProvider } from \"./providers/RedisQueueProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/RedisQueueProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Queue that provides Redis queue capabilities.\n *\n * @see {@link RedisQueueProvider}\n * @module alepha.queue.redis\n */\nexport const AlephaQueueRedis = $module({\n  name: \"alepha.queue.redis\",\n  services: [RedisQueueProvider],\n  register: (alepha: Alepha) =>\n    alepha\n      .with({\n        optional: true,\n        provide: QueueProvider,\n        use: RedisQueueProvider,\n      })\n      .with(AlephaQueue),\n});\n"],"mappings":";;;;;;;AASA,MAAa,oBAAoB,MAAM;CACrC,MAAM;CACN,QAAQ,EAAE,OAAO,EACf,QAAQ,EAAE,KAAK;EACb,SAAS;EACT,aAAa;EACd,CAAC,EACH,CAAC;CACF,SAAS,EACP,QAAQ,SACT;CACF,CAAC;AAYF,IAAa,qBAAb,MAAyD;CACvD,UAA6B,OAAO,kBAAkB;CACtD,gBAAkD,QAAQ,cAAc;CAExE,OAAc,OAAuB;EACnC,OAAO,GAAG,KAAK,QAAQ,OAAO,GAAG;;CAGnC,MAAa,KAAK,OAAe,SAAgC;EAC/D,MAAM,KAAK,cAAc,MAAM,KAAK,OAAO,MAAM,EAAE,QAAQ;;CAG7D,MAAa,IAAI,OAA4C;EAC3D,OAAO,KAAK,cAAc,KAAK,KAAK,OAAO,MAAM,CAAC;;;;;;;;;;;AC7BtD,MAAa,mBAAmB,QAAQ;CACtC,MAAM;CACN,UAAU,CAAC,mBAAmB;CAC9B,WAAW,WACT,OACG,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;EACN,CAAC,CACD,KAAK,YAAY;CACvB,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/queue/redis/providers/RedisQueueProvider.ts","../../../src/queue/redis/index.ts"],"sourcesContent":["import { $atom, $inject, $state, type Static, t } from \"alepha\";\nimport type { QueueProvider } from \"alepha/queue\";\nimport { RedisProvider } from \"alepha/redis\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Redis queue configuration atom.\n */\nexport const redisQueueOptions = $atom({\n  name: \"alepha.queue.redis.options\",\n  schema: t.object({\n    prefix: t.text({\n      default: \"queue\",\n      description: \"Prefix for all queue keys in Redis.\",\n    }),\n  }),\n  default: {\n    prefix: \"queue\",\n  },\n});\n\nexport type RedisQueueOptions = Static<typeof redisQueueOptions.schema>;\n\ndeclare module \"alepha\" {\n  interface State {\n    [redisQueueOptions.key]: RedisQueueOptions;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class RedisQueueProvider implements QueueProvider {\n  protected readonly options = $state(redisQueueOptions);\n  protected readonly redisProvider: RedisProvider = $inject(RedisProvider);\n\n  public prefix(queue: string): string {\n    return `${this.options.prefix}:${queue}`;\n  }\n\n  public async push(queue: string, message: string): Promise<void> {\n    await this.redisProvider.lpush(this.prefix(queue), message);\n  }\n\n  public async pop(queue: string): Promise<string | undefined> {\n    return this.redisProvider.rpop(this.prefix(queue));\n  }\n}\n","import { $module, type Alepha } from \"alepha\";\nimport { AlephaQueue, QueueProvider } from \"alepha/queue\";\nimport { RedisQueueProvider } from \"./providers/RedisQueueProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./providers/RedisQueueProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Plugin for Alepha Queue that provides Redis queue capabilities.\n *\n * @see {@link RedisQueueProvider}\n * @module alepha.queue.redis\n */\nexport const AlephaQueueRedis = $module({\n  name: \"alepha.queue.redis\",\n  services: [RedisQueueProvider],\n  register: (alepha: Alepha) =>\n    alepha\n      .with({\n        optional: true,\n        provide: QueueProvider,\n        use: RedisQueueProvider,\n      })\n      .with(AlephaQueue),\n});\n"],"mappings":";;;;;;;AASA,MAAa,oBAAoB,MAAM;CACrC,MAAM;CACN,QAAQ,EAAE,OAAO,EACf,QAAQ,EAAE,KAAK;EACb,SAAS;EACT,aAAa;CACf,CAAC,EACH,CAAC;CACD,SAAS,EACP,QAAQ,QACV;AACF,CAAC;AAYD,IAAa,qBAAb,MAAyD;CACvD,UAA6B,OAAO,iBAAiB;CACrD,gBAAkD,QAAQ,aAAa;CAEvE,OAAc,OAAuB;EACnC,OAAO,GAAG,KAAK,QAAQ,OAAO,GAAG;CACnC;CAEA,MAAa,KAAK,OAAe,SAAgC;EAC/D,MAAM,KAAK,cAAc,MAAM,KAAK,OAAO,KAAK,GAAG,OAAO;CAC5D;CAEA,MAAa,IAAI,OAA4C;EAC3D,OAAO,KAAK,cAAc,KAAK,KAAK,OAAO,KAAK,CAAC;CACnD;AACF;;;;;;;;;AC/BA,MAAa,mBAAmB,QAAQ;CACtC,MAAM;CACN,UAAU,CAAC,kBAAkB;CAC7B,WAAW,WACT,OACG,KAAK;EACJ,UAAU;EACV,SAAS;EACT,KAAK;CACP,CAAC,EACA,KAAK,WAAW;AACvB,CAAC"}

package/dist/react/auth/index.browser.js

@@ -94,8 +94,15 @@ const useAuth = () => {
 		login: async (provider, options = {}) => {
 			await alepha.inject(ReactAuth).login(provider, options);
 		},
-		can: (name) => {
-			return alepha.inject(LinkProvider).can(name);
+		/**
+		* UI permission check — does the current user hold this permission?
+		* Supports exact and wildcard names (e.g. `"admin:*"`, `"admin:user:read"`).
+		*
+		* UI affordance only (show/hide/disable). Real access control is enforced
+		* server-side via `$secure` on the route/action.
+		*/
+		has: (permission) => {
+			return alepha.inject(LinkProvider).can(permission);
 		}
 	};
 };

package/dist/react/auth/index.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.browser.js","names":[],"sources":["../../../src/react/auth/services/ReactAuth.ts","../../../src/react/auth/hooks/useAuth.ts","../../../src/react/auth/index.browser.ts"],"sourcesContent":["import { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { ReactBrowserProvider, Redirection } from \"alepha/react/router\";\nimport { currentUserAtom, type UserAccountToken } from \"alepha/security\";\nimport { HttpClient } from \"alepha/server\";\nimport {\n  alephaServerAuthRoutes,\n  type Tokens,\n  tokenResponseSchema,\n  userinfoResponseSchema,\n} from \"alepha/server/auth\";\nimport { LinkProvider } from \"alepha/server/links\";\n\n/**\n * Browser, SSR friendly, service to handle authentication.\n */\nexport class ReactAuth {\n  protected readonly log = $logger();\n  protected readonly alepha = $inject(Alepha);\n  protected readonly httpClient = $inject(HttpClient);\n  protected readonly linkProvider = $inject(LinkProvider);\n\n  protected readonly onBeginTransition = $hook({\n    on: \"react:transition:begin\",\n    handler: async (event) => {\n      if (this.alepha.isBrowser()) {\n        Object.defineProperty(event.state, \"user\", {\n          get: () => this.user,\n        });\n      }\n    },\n  });\n\n  protected readonly onFetchRequest = $hook({\n    on: \"client:onRequest\",\n    handler: async ({ request }) => {\n      if (this.alepha.isBrowser() && this.user) {\n        // ensure cookies are sent with requests and refresh-able\n        request.credentials ??= \"include\";\n      }\n    },\n  });\n\n  /**\n   * Get the current authenticated user.\n   *\n   * Alias for `alepha.state.get(\"user\")`\n   */\n  public get user(): UserAccountToken | undefined {\n    return this.alepha.store.get(currentUserAtom) as\n      | UserAccountToken\n      | undefined;\n  }\n\n  public async ping() {\n    const { data } = await this.httpClient.fetch(\n      alephaServerAuthRoutes.userinfo,\n      {\n        schema: { response: userinfoResponseSchema },\n      },\n    );\n\n    this.alepha.store.set(\"alepha.server.request.apiLinks\", data.api);\n    this.alepha.store.set(currentUserAtom, data.user);\n\n    return data.user;\n  }\n\n  public can(action: string): boolean {\n    if (!this.user) {\n      return false;\n    }\n\n    return this.linkProvider.can(action);\n  }\n\n  public async login(\n    provider: string,\n    options: {\n      hostname?: string;\n      username?: string;\n      password?: string;\n      redirect?: string;\n      realm?: string;\n      [extra: string]: any;\n    },\n  ): Promise<Tokens> {\n    const realmParam = options.realm\n      ? `&realm=${encodeURIComponent(options.realm)}`\n      : \"\";\n\n    if (options.username || options.password) {\n      const { data } = await this.httpClient.fetch(\n        `${options.hostname || \"\"}${alephaServerAuthRoutes.token}?provider=${provider}${realmParam}`,\n        {\n          method: \"POST\",\n          body: JSON.stringify({\n            username: options.username,\n            password: options.password,\n          }),\n          schema: { response: tokenResponseSchema },\n        },\n      );\n\n      this.alepha.store.set(\"alepha.server.request.apiLinks\", data.api);\n      this.alepha.store.set(currentUserAtom, data.user);\n\n      return data;\n    }\n\n    if (this.alepha.isBrowser()) {\n      const browser = this.alepha.inject(ReactBrowserProvider);\n      const redirect =\n        options.redirect ||\n        (browser.transitioning\n          ? window.location.origin + browser.transitioning.to\n          : window.location.href);\n\n      const href = `${window.location.origin}${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${encodeURIComponent(redirect)}`;\n\n      if (browser.transitioning) {\n        throw new Redirection(href);\n      } else {\n        window.location.href = href;\n        return {} as Tokens;\n      }\n    }\n\n    throw new Redirection(\n      `${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${options.redirect || \"/\"}`,\n    );\n  }\n\n  public logout() {\n    const form = document.createElement(\"form\");\n    form.method = \"POST\";\n    form.action = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;\n    form.style.display = \"none\";\n    document.body.appendChild(form);\n    form.submit();\n  }\n}\n","import { useAlepha, useStore } from \"alepha/react\";\nimport { currentUserAtom } from \"alepha/security\";\nimport { type HttpVirtualClient, LinkProvider } from \"alepha/server/links\";\nimport { ReactAuth } from \"../services/ReactAuth.ts\";\n\nexport const useAuth = <T extends object = any>() => {\n  const alepha = useAlepha();\n  const [user] = useStore(currentUserAtom);\n\n  return {\n    user,\n    logout: () => {\n      alepha.inject(ReactAuth).logout();\n    },\n    login: async (\n      provider: keyof T,\n      options: {\n        username?: string;\n        password?: string;\n        redirect?: string;\n        realm?: string;\n        [extra: string]: any;\n      } = {},\n    ) => {\n      await alepha.inject(ReactAuth).login(provider as string, options);\n    },\n    can: <Api extends object = any>(\n      name: keyof HttpVirtualClient<Api>,\n    ): boolean => {\n      return alepha.inject(LinkProvider).can(name as string);\n    },\n  };\n};\n","import { $module } from \"alepha\";\nimport { ReactAuth } from \"./services/ReactAuth.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./index.shared.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport const AlephaReactAuth = $module({\n  name: \"alepha.react.auth\",\n  services: [ReactAuth],\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.browser.js","names":[],"sources":["../../../src/react/auth/services/ReactAuth.ts","../../../src/react/auth/hooks/useAuth.ts","../../../src/react/auth/index.browser.ts"],"sourcesContent":["import { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { ReactBrowserProvider, Redirection } from \"alepha/react/router\";\nimport { currentUserAtom, type UserAccountToken } from \"alepha/security\";\nimport { HttpClient } from \"alepha/server\";\nimport {\n  alephaServerAuthRoutes,\n  type Tokens,\n  tokenResponseSchema,\n  userinfoResponseSchema,\n} from \"alepha/server/auth\";\nimport { LinkProvider } from \"alepha/server/links\";\n\n/**\n * Browser, SSR friendly, service to handle authentication.\n */\nexport class ReactAuth {\n  protected readonly log = $logger();\n  protected readonly alepha = $inject(Alepha);\n  protected readonly httpClient = $inject(HttpClient);\n  protected readonly linkProvider = $inject(LinkProvider);\n\n  protected readonly onBeginTransition = $hook({\n    on: \"react:transition:begin\",\n    handler: async (event) => {\n      if (this.alepha.isBrowser()) {\n        Object.defineProperty(event.state, \"user\", {\n          get: () => this.user,\n        });\n      }\n    },\n  });\n\n  protected readonly onFetchRequest = $hook({\n    on: \"client:onRequest\",\n    handler: async ({ request }) => {\n      if (this.alepha.isBrowser() && this.user) {\n        // ensure cookies are sent with requests and refresh-able\n        request.credentials ??= \"include\";\n      }\n    },\n  });\n\n  /**\n   * Get the current authenticated user.\n   *\n   * Alias for `alepha.state.get(\"user\")`\n   */\n  public get user(): UserAccountToken | undefined {\n    return this.alepha.store.get(currentUserAtom) as\n      | UserAccountToken\n      | undefined;\n  }\n\n  public async ping() {\n    const { data } = await this.httpClient.fetch(\n      alephaServerAuthRoutes.userinfo,\n      {\n        schema: { response: userinfoResponseSchema },\n      },\n    );\n\n    this.alepha.store.set(\"alepha.server.request.apiLinks\", data.api);\n    this.alepha.store.set(currentUserAtom, data.user);\n\n    return data.user;\n  }\n\n  public can(action: string): boolean {\n    if (!this.user) {\n      return false;\n    }\n\n    return this.linkProvider.can(action);\n  }\n\n  public async login(\n    provider: string,\n    options: {\n      hostname?: string;\n      username?: string;\n      password?: string;\n      redirect?: string;\n      realm?: string;\n      [extra: string]: any;\n    },\n  ): Promise<Tokens> {\n    const realmParam = options.realm\n      ? `&realm=${encodeURIComponent(options.realm)}`\n      : \"\";\n\n    if (options.username || options.password) {\n      const { data } = await this.httpClient.fetch(\n        `${options.hostname || \"\"}${alephaServerAuthRoutes.token}?provider=${provider}${realmParam}`,\n        {\n          method: \"POST\",\n          body: JSON.stringify({\n            username: options.username,\n            password: options.password,\n          }),\n          schema: { response: tokenResponseSchema },\n        },\n      );\n\n      this.alepha.store.set(\"alepha.server.request.apiLinks\", data.api);\n      this.alepha.store.set(currentUserAtom, data.user);\n\n      return data;\n    }\n\n    if (this.alepha.isBrowser()) {\n      const browser = this.alepha.inject(ReactBrowserProvider);\n      const redirect =\n        options.redirect ||\n        (browser.transitioning\n          ? window.location.origin + browser.transitioning.to\n          : window.location.href);\n\n      const href = `${window.location.origin}${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${encodeURIComponent(redirect)}`;\n\n      if (browser.transitioning) {\n        throw new Redirection(href);\n      } else {\n        window.location.href = href;\n        return {} as Tokens;\n      }\n    }\n\n    throw new Redirection(\n      `${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${options.redirect || \"/\"}`,\n    );\n  }\n\n  public logout() {\n    const form = document.createElement(\"form\");\n    form.method = \"POST\";\n    form.action = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;\n    form.style.display = \"none\";\n    document.body.appendChild(form);\n    form.submit();\n  }\n}\n","import { useAlepha, useStore } from \"alepha/react\";\nimport { currentUserAtom } from \"alepha/security\";\nimport { LinkProvider } from \"alepha/server/links\";\nimport { ReactAuth } from \"../services/ReactAuth.ts\";\n\nexport const useAuth = <T extends object = any>() => {\n  const alepha = useAlepha();\n  const [user] = useStore(currentUserAtom);\n\n  return {\n    user,\n    logout: () => {\n      alepha.inject(ReactAuth).logout();\n    },\n    login: async (\n      provider: keyof T,\n      options: {\n        username?: string;\n        password?: string;\n        redirect?: string;\n        realm?: string;\n        [extra: string]: any;\n      } = {},\n    ) => {\n      await alepha.inject(ReactAuth).login(provider as string, options);\n    },\n    /**\n     * UI permission check — does the current user hold this permission?\n     * Supports exact and wildcard names (e.g. `\"admin:*\"`, `\"admin:user:read\"`).\n     *\n     * UI affordance only (show/hide/disable). Real access control is enforced\n     * server-side via `$secure` on the route/action.\n     */\n    has: (permission: string): boolean => {\n      return alepha.inject(LinkProvider).can(permission);\n    },\n  };\n};\n","import { $module } from \"alepha\";\nimport { ReactAuth } from \"./services/ReactAuth.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./index.shared.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport const AlephaReactAuth = $module({\n  name: \"alepha.react.auth\",\n  services: [ReactAuth],\n});\n"],"mappings":"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"}

package/dist/react/auth/index.d.ts

@@ -1,9 +1,7 @@
-import * as _$alepha from "alepha";
 import { Alepha } from "alepha";
 import { Tokens } from "alepha/server/auth";
-import { HttpVirtualClient, LinkProvider } from "alepha/server/links";
+import { LinkProvider } from "alepha/server/links";
 import { UserAccount, UserAccountToken } from "alepha/security";
-import * as _$alepha_logger0 from "alepha/logger";
 import { HttpClient } from "alepha/server";
 
 //#region ../../src/react/auth/hooks/useAuth.d.ts
@@ -27,7 +25,14 @@ declare const useAuth: <T extends object = any>() => {
     realm?: string;
     [extra: string]: any;
   }) => Promise<void>;
-  can: <Api extends object = any>(name: keyof HttpVirtualClient<Api>) => boolean;
+  /**
+   * UI permission check — does the current user hold this permission?
+   * Supports exact and wildcard names (e.g. `"admin:*"`, `"admin:user:read"`).
+   *
+   * UI affordance only (show/hide/disable). Real access control is enforced
+   * server-side via `$secure` on the route/action.
+   */
+  has: (permission: string) => boolean;
 };
 //#endregion
 //#region ../../src/react/auth/services/ReactAuth.d.ts
@@ -35,12 +40,12 @@ declare const useAuth: <T extends object = any>() => {
  * Browser, SSR friendly, service to handle authentication.
  */
 declare class ReactAuth {
-  protected readonly log: _$alepha_logger0.Logger;
+  protected readonly log: import("alepha/logger").Logger;
   protected readonly alepha: Alepha;
   protected readonly httpClient: HttpClient;
   protected readonly linkProvider: LinkProvider;
-  protected readonly onBeginTransition: _$alepha.HookPrimitive<"react:transition:begin">;
-  protected readonly onFetchRequest: _$alepha.HookPrimitive<"client:onRequest">;
+  protected readonly onBeginTransition: import("alepha").HookPrimitive<"react:transition:begin">;
+  protected readonly onFetchRequest: import("alepha").HookPrimitive<"client:onRequest">;
   /**
    * Get the current authenticated user.
    *
@@ -73,7 +78,7 @@ declare class ReactAuth {
 //#region ../../src/react/auth/providers/ReactAuthProvider.d.ts
 declare class ReactAuthProvider {
   protected readonly alepha: Alepha;
-  readonly onRender: _$alepha.HookPrimitive<"react:server:render:begin">;
+  readonly onRender: import("alepha").HookPrimitive<"react:server:render:begin">;
 }
 //#endregion
 //#region ../../src/react/auth/index.d.ts
@@ -92,7 +97,7 @@ declare module "alepha/react/router" {
  *
  * @module alepha.react.auth
  */
-declare const AlephaReactAuth: _$alepha.Service<_$alepha.Module>;
+declare const AlephaReactAuth: import("alepha").Service<import("alepha").Module>;
 //#endregion
 export { AlephaReactAuth, ReactAuth, ReactAuthProvider, useAuth };
 //# sourceMappingURL=index.d.ts.map

package/dist/react/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/react/auth/hooks/useAuth.ts","../../../src/react/auth/services/ReactAuth.ts","../../../src/react/auth/providers/ReactAuthProvider.ts","../../../src/react/auth/index.ts"],"mappings":";;;;;;;;;cAKa,OAAA;;;;;;;;;;;;;0BAUS,CAAA,EAAC,OAAA;IAEf,QAAA;IACA,QAAA;IACA,QAAA;IACA,KAAA;IAAA,CACC,KAAA;EAAA,MACF,OAAA;kCAIqB,IAAA,QACV,iBAAA,CAAkB,GAAA;AAAA;;;;;;cCXvB,SAAA;EAAA,mBACQ,GAAA,EADC,gBAAA,CACE,MAAA;EAAA,mBACH,MAAA,EAAM,MAAA;EAAA,mBACN,UAAA,EAAU,UAAA;EAAA,mBACV,YAAA,EAAY,YAAA;EAAA,mBAEZ,iBAAA,EAFY,QAAA,CAEK,aAAA;EAAA,mBAWjB,cAAA,EAXiB,QAAA,CAWH,aAAA;EDNjB;;;;;EAAA,ICqBL,IAAA,CAAA,GAAQ,gBAAA;EAMN,IAAA,CAAA,GAAI,OAAA;;;;;;;;;;;EAcV,GAAA,CAAI,MAAA;EAQE,KAAA,CACX,QAAA,UACA,OAAA;IACE,QAAA;IACA,QAAA;IACA,QAAA;IACA,QAAA;IACA,KAAA;IAAA,CACC,KAAA;EAAA,IAEF,OAAA,CAAQ,MAAA;EA+CJ,MAAA,CAAA;AAAA;;;cClII,iBAAA;EAAA,mBACQ,MAAA,EAAM,MAAA;EAAA,SAET,QAAA,EAFS,QAAA,CAED,aAAA;AAAA;;;;YCUd,gBAAA;IACR,IAAA,GAAO,WAAA;EAAA;AAAA;;AHZX;;;;;;;;;cG4Ba,eAAA,EAAe,QAAA,CAAA,OAAA,CAU1B,QAAA,CAV0B,MAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/react/auth/hooks/useAuth.ts","../../../src/react/auth/services/ReactAuth.ts","../../../src/react/auth/providers/ReactAuthProvider.ts","../../../src/react/auth/index.ts"],"mappings":";;;;;;;cAKa,OAAA;;;;;;;;;;;;;0BAUS,CAAA,EAAC,OAAA;IAEf,QAAA;IACA,QAAA;IACA,QAAA;IACA,KAAA;IAAA,CACC,KAAA;EAAA,MACF,OAAA;;;;;;;;;;;;;;AAjBP;cCWa,SAAA;EAAA,mBACQ,GAAA,0BAAG,MAAA;EAAA,mBACH,MAAA,EAAM,MAAA;EAAA,mBACN,UAAA,EAAU,UAAA;EAAA,mBACV,YAAA,EAAY,YAAA;EAAA,mBAEZ,iBAAA,mBAAiB,aAAA;EAAA,mBAWjB,cAAA,mBAAc,aAAA;;;;;;MAetB,IAAA,IAAQ,gBAAA;EAMN,IAAA,IAAI,OAAA;;;;;;;;;;;EAcV,GAAA,CAAI,MAAA;EAQE,KAAA,CACX,QAAA,UACA,OAAA;IACE,QAAA;IACA,QAAA;IACA,QAAA;IACA,QAAA;IACA,KAAA;IAAA,CACC,KAAA;EAAA,IAEF,OAAA,CAAQ,MAAA;EA+CJ,MAAA;AAAA;;;cClII,iBAAA;EAAA,mBACQ,MAAA,EAAM,MAAA;EAAA,SAET,QAAA,mBAAQ,aAAA;AAAA;;;;YCUd,gBAAA;IACR,IAAA,GAAO,WAAW;EAAA;AAAA;;;;;;;;;;;cAgBT,eAAA,mBAAe,OAAA,kBAAA,MAAA"}

package/dist/react/auth/index.js

@@ -109,8 +109,15 @@ const useAuth = () => {
 		login: async (provider, options = {}) => {
 			await alepha.inject(ReactAuth).login(provider, options);
 		},
-		can: (name) => {
-			return alepha.inject(LinkProvider).can(name);
+		/**
+		* UI permission check — does the current user hold this permission?
+		* Supports exact and wildcard names (e.g. `"admin:*"`, `"admin:user:read"`).
+		*
+		* UI affordance only (show/hide/disable). Real access control is enforced
+		* server-side via `$secure` on the route/action.
+		*/
+		has: (permission) => {
+			return alepha.inject(LinkProvider).can(permission);
 		}
 	};
 };

package/dist/react/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/react/auth/providers/ReactAuthProvider.ts","../../../src/react/auth/services/ReactAuth.ts","../../../src/react/auth/hooks/useAuth.ts","../../../src/react/auth/index.ts"],"sourcesContent":["import { $hook, $inject, Alepha } from \"alepha\";\nimport { currentUserAtom } from \"alepha/security\";\n\nexport class ReactAuthProvider {\n  protected readonly alepha = $inject(Alepha);\n\n  public readonly onRender = $hook({\n    on: \"react:server:render:begin\",\n    handler: async ({ request, state }) => {\n      if (request?.user) {\n        const { token, realm, ...user } = request.user; // do not send token and realm to the client\n        this.alepha.store.set(currentUserAtom, user);\n        state.user = user;\n      }\n    },\n  });\n}\n","import { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { ReactBrowserProvider, Redirection } from \"alepha/react/router\";\nimport { currentUserAtom, type UserAccountToken } from \"alepha/security\";\nimport { HttpClient } from \"alepha/server\";\nimport {\n  alephaServerAuthRoutes,\n  type Tokens,\n  tokenResponseSchema,\n  userinfoResponseSchema,\n} from \"alepha/server/auth\";\nimport { LinkProvider } from \"alepha/server/links\";\n\n/**\n * Browser, SSR friendly, service to handle authentication.\n */\nexport class ReactAuth {\n  protected readonly log = $logger();\n  protected readonly alepha = $inject(Alepha);\n  protected readonly httpClient = $inject(HttpClient);\n  protected readonly linkProvider = $inject(LinkProvider);\n\n  protected readonly onBeginTransition = $hook({\n    on: \"react:transition:begin\",\n    handler: async (event) => {\n      if (this.alepha.isBrowser()) {\n        Object.defineProperty(event.state, \"user\", {\n          get: () => this.user,\n        });\n      }\n    },\n  });\n\n  protected readonly onFetchRequest = $hook({\n    on: \"client:onRequest\",\n    handler: async ({ request }) => {\n      if (this.alepha.isBrowser() && this.user) {\n        // ensure cookies are sent with requests and refresh-able\n        request.credentials ??= \"include\";\n      }\n    },\n  });\n\n  /**\n   * Get the current authenticated user.\n   *\n   * Alias for `alepha.state.get(\"user\")`\n   */\n  public get user(): UserAccountToken | undefined {\n    return this.alepha.store.get(currentUserAtom) as\n      | UserAccountToken\n      | undefined;\n  }\n\n  public async ping() {\n    const { data } = await this.httpClient.fetch(\n      alephaServerAuthRoutes.userinfo,\n      {\n        schema: { response: userinfoResponseSchema },\n      },\n    );\n\n    this.alepha.store.set(\"alepha.server.request.apiLinks\", data.api);\n    this.alepha.store.set(currentUserAtom, data.user);\n\n    return data.user;\n  }\n\n  public can(action: string): boolean {\n    if (!this.user) {\n      return false;\n    }\n\n    return this.linkProvider.can(action);\n  }\n\n  public async login(\n    provider: string,\n    options: {\n      hostname?: string;\n      username?: string;\n      password?: string;\n      redirect?: string;\n      realm?: string;\n      [extra: string]: any;\n    },\n  ): Promise<Tokens> {\n    const realmParam = options.realm\n      ? `&realm=${encodeURIComponent(options.realm)}`\n      : \"\";\n\n    if (options.username || options.password) {\n      const { data } = await this.httpClient.fetch(\n        `${options.hostname || \"\"}${alephaServerAuthRoutes.token}?provider=${provider}${realmParam}`,\n        {\n          method: \"POST\",\n          body: JSON.stringify({\n            username: options.username,\n            password: options.password,\n          }),\n          schema: { response: tokenResponseSchema },\n        },\n      );\n\n      this.alepha.store.set(\"alepha.server.request.apiLinks\", data.api);\n      this.alepha.store.set(currentUserAtom, data.user);\n\n      return data;\n    }\n\n    if (this.alepha.isBrowser()) {\n      const browser = this.alepha.inject(ReactBrowserProvider);\n      const redirect =\n        options.redirect ||\n        (browser.transitioning\n          ? window.location.origin + browser.transitioning.to\n          : window.location.href);\n\n      const href = `${window.location.origin}${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${encodeURIComponent(redirect)}`;\n\n      if (browser.transitioning) {\n        throw new Redirection(href);\n      } else {\n        window.location.href = href;\n        return {} as Tokens;\n      }\n    }\n\n    throw new Redirection(\n      `${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${options.redirect || \"/\"}`,\n    );\n  }\n\n  public logout() {\n    const form = document.createElement(\"form\");\n    form.method = \"POST\";\n    form.action = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;\n    form.style.display = \"none\";\n    document.body.appendChild(form);\n    form.submit();\n  }\n}\n","import { useAlepha, useStore } from \"alepha/react\";\nimport { currentUserAtom } from \"alepha/security\";\nimport { type HttpVirtualClient, LinkProvider } from \"alepha/server/links\";\nimport { ReactAuth } from \"../services/ReactAuth.ts\";\n\nexport const useAuth = <T extends object = any>() => {\n  const alepha = useAlepha();\n  const [user] = useStore(currentUserAtom);\n\n  return {\n    user,\n    logout: () => {\n      alepha.inject(ReactAuth).logout();\n    },\n    login: async (\n      provider: keyof T,\n      options: {\n        username?: string;\n        password?: string;\n        redirect?: string;\n        realm?: string;\n        [extra: string]: any;\n      } = {},\n    ) => {\n      await alepha.inject(ReactAuth).login(provider as string, options);\n    },\n    can: <Api extends object = any>(\n      name: keyof HttpVirtualClient<Api>,\n    ): boolean => {\n      return alepha.inject(LinkProvider).can(name as string);\n    },\n  };\n};\n","import { $module } from \"alepha\";\nimport { AlephaReact } from \"alepha/react\";\nimport type { UserAccount } from \"alepha/security\";\nimport { $auth, AlephaServerAuth } from \"alepha/server/auth\";\nimport { AlephaServerLinks } from \"alepha/server/links\";\nimport { ReactAuthProvider } from \"./providers/ReactAuthProvider.ts\";\nimport { ReactAuth } from \"./services/ReactAuth.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./index.shared.ts\";\nexport * from \"./providers/ReactAuthProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/react/router\" {\n  interface ReactRouterState {\n    user?: UserAccount;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Auth-related React components and hooks.\n *\n * **Features:**\n * - Login/logout components\n * - Protected route wrappers\n * - Auth state hooks\n *\n * @module alepha.react.auth\n */\nexport const AlephaReactAuth = $module({\n  name: \"alepha.react.auth\",\n  primitives: [$auth],\n  services: [\n    AlephaReact,\n    AlephaServerLinks,\n    AlephaServerAuth,\n    ReactAuthProvider,\n    ReactAuth,\n  ],\n});\n"],"mappings":";;;;;;;;;AAGA,IAAa,oBAAb,MAA+B;CAC7B,SAA4B,QAAQ,OAAO;CAE3C,WAA2B,MAAM;EAC/B,IAAI;EACJ,SAAS,OAAO,EAAE,SAAS,YAAY;GACrC,IAAI,SAAS,MAAM;IACjB,MAAM,EAAE,OAAO,OAAO,GAAG,SAAS,QAAQ;IAC1C,KAAK,OAAO,MAAM,IAAI,iBAAiB,KAAK;IAC5C,MAAM,OAAO;;;EAGlB,CAAC;;;;;;;ACCJ,IAAa,YAAb,MAAuB;CACrB,MAAyB,SAAS;CAClC,SAA4B,QAAQ,OAAO;CAC3C,aAAgC,QAAQ,WAAW;CACnD,eAAkC,QAAQ,aAAa;CAEvD,oBAAuC,MAAM;EAC3C,IAAI;EACJ,SAAS,OAAO,UAAU;GACxB,IAAI,KAAK,OAAO,WAAW,EACzB,OAAO,eAAe,MAAM,OAAO,QAAQ,EACzC,WAAW,KAAK,MACjB,CAAC;;EAGP,CAAC;CAEF,iBAAoC,MAAM;EACxC,IAAI;EACJ,SAAS,OAAO,EAAE,cAAc;GAC9B,IAAI,KAAK,OAAO,WAAW,IAAI,KAAK,MAElC,QAAQ,gBAAgB;;EAG7B,CAAC;;;;;;CAOF,IAAW,OAAqC;EAC9C,OAAO,KAAK,OAAO,MAAM,IAAI,gBAAgB;;CAK/C,MAAa,OAAO;EAClB,MAAM,EAAE,SAAS,MAAM,KAAK,WAAW,MACrC,uBAAuB,UACvB,EACE,QAAQ,EAAE,UAAU,wBAAwB,EAC7C,CACF;EAED,KAAK,OAAO,MAAM,IAAI,kCAAkC,KAAK,IAAI;EACjE,KAAK,OAAO,MAAM,IAAI,iBAAiB,KAAK,KAAK;EAEjD,OAAO,KAAK;;CAGd,IAAW,QAAyB;EAClC,IAAI,CAAC,KAAK,MACR,OAAO;EAGT,OAAO,KAAK,aAAa,IAAI,OAAO;;CAGtC,MAAa,MACX,UACA,SAQiB;EACjB,MAAM,aAAa,QAAQ,QACvB,UAAU,mBAAmB,QAAQ,MAAM,KAC3C;EAEJ,IAAI,QAAQ,YAAY,QAAQ,UAAU;GACxC,MAAM,EAAE,SAAS,MAAM,KAAK,WAAW,MACrC,GAAG,QAAQ,YAAY,KAAK,uBAAuB,MAAM,YAAY,WAAW,cAChF;IACE,QAAQ;IACR,MAAM,KAAK,UAAU;KACnB,UAAU,QAAQ;KAClB,UAAU,QAAQ;KACnB,CAAC;IACF,QAAQ,EAAE,UAAU,qBAAqB;IAC1C,CACF;GAED,KAAK,OAAO,MAAM,IAAI,kCAAkC,KAAK,IAAI;GACjE,KAAK,OAAO,MAAM,IAAI,iBAAiB,KAAK,KAAK;GAEjD,OAAO;;EAGT,IAAI,KAAK,OAAO,WAAW,EAAE;GAC3B,MAAM,UAAU,KAAK,OAAO,OAAO,qBAAqB;GACxD,MAAM,WACJ,QAAQ,aACP,QAAQ,gBACL,OAAO,SAAS,SAAS,QAAQ,cAAc,KAC/C,OAAO,SAAS;GAEtB,MAAM,OAAO,GAAG,OAAO,SAAS,SAAS,uBAAuB,MAAM,YAAY,WAAW,WAAW,gBAAgB,mBAAmB,SAAS;GAEpJ,IAAI,QAAQ,eACV,MAAM,IAAI,YAAY,KAAK;QACtB;IACL,OAAO,SAAS,OAAO;IACvB,OAAO,EAAE;;;EAIb,MAAM,IAAI,YACR,GAAG,uBAAuB,MAAM,YAAY,WAAW,WAAW,gBAAgB,QAAQ,YAAY,MACvG;;CAGH,SAAgB;EACd,MAAM,OAAO,SAAS,cAAc,OAAO;EAC3C,KAAK,SAAS;EACd,KAAK,SAAS,GAAG,uBAAuB,OAAO,4BAA4B,mBAAmB,OAAO,SAAS,OAAO;EACrH,KAAK,MAAM,UAAU;EACrB,SAAS,KAAK,YAAY,KAAK;EAC/B,KAAK,QAAQ;;;;;ACtIjB,MAAa,gBAAwC;CACnD,MAAM,SAAS,WAAW;CAC1B,MAAM,CAAC,QAAQ,SAAS,gBAAgB;CAExC,OAAO;EACL;EACA,cAAc;GACZ,OAAO,OAAO,UAAU,CAAC,QAAQ;;EAEnC,OAAO,OACL,UACA,UAMI,EAAE,KACH;GACH,MAAM,OAAO,OAAO,UAAU,CAAC,MAAM,UAAoB,QAAQ;;EAEnE,MACE,SACY;GACZ,OAAO,OAAO,OAAO,aAAa,CAAC,IAAI,KAAe;;EAEzD;;;;;;;;;;;;;;ACEH,MAAa,kBAAkB,QAAQ;CACrC,MAAM;CACN,YAAY,CAAC,MAAM;CACnB,UAAU;EACR;EACA;EACA;EACA;EACA;EACD;CACF,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/react/auth/providers/ReactAuthProvider.ts","../../../src/react/auth/services/ReactAuth.ts","../../../src/react/auth/hooks/useAuth.ts","../../../src/react/auth/index.ts"],"sourcesContent":["import { $hook, $inject, Alepha } from \"alepha\";\nimport { currentUserAtom } from \"alepha/security\";\n\nexport class ReactAuthProvider {\n  protected readonly alepha = $inject(Alepha);\n\n  public readonly onRender = $hook({\n    on: \"react:server:render:begin\",\n    handler: async ({ request, state }) => {\n      if (request?.user) {\n        const { token, realm, ...user } = request.user; // do not send token and realm to the client\n        this.alepha.store.set(currentUserAtom, user);\n        state.user = user;\n      }\n    },\n  });\n}\n","import { $hook, $inject, Alepha } from \"alepha\";\nimport { $logger } from \"alepha/logger\";\nimport { ReactBrowserProvider, Redirection } from \"alepha/react/router\";\nimport { currentUserAtom, type UserAccountToken } from \"alepha/security\";\nimport { HttpClient } from \"alepha/server\";\nimport {\n  alephaServerAuthRoutes,\n  type Tokens,\n  tokenResponseSchema,\n  userinfoResponseSchema,\n} from \"alepha/server/auth\";\nimport { LinkProvider } from \"alepha/server/links\";\n\n/**\n * Browser, SSR friendly, service to handle authentication.\n */\nexport class ReactAuth {\n  protected readonly log = $logger();\n  protected readonly alepha = $inject(Alepha);\n  protected readonly httpClient = $inject(HttpClient);\n  protected readonly linkProvider = $inject(LinkProvider);\n\n  protected readonly onBeginTransition = $hook({\n    on: \"react:transition:begin\",\n    handler: async (event) => {\n      if (this.alepha.isBrowser()) {\n        Object.defineProperty(event.state, \"user\", {\n          get: () => this.user,\n        });\n      }\n    },\n  });\n\n  protected readonly onFetchRequest = $hook({\n    on: \"client:onRequest\",\n    handler: async ({ request }) => {\n      if (this.alepha.isBrowser() && this.user) {\n        // ensure cookies are sent with requests and refresh-able\n        request.credentials ??= \"include\";\n      }\n    },\n  });\n\n  /**\n   * Get the current authenticated user.\n   *\n   * Alias for `alepha.state.get(\"user\")`\n   */\n  public get user(): UserAccountToken | undefined {\n    return this.alepha.store.get(currentUserAtom) as\n      | UserAccountToken\n      | undefined;\n  }\n\n  public async ping() {\n    const { data } = await this.httpClient.fetch(\n      alephaServerAuthRoutes.userinfo,\n      {\n        schema: { response: userinfoResponseSchema },\n      },\n    );\n\n    this.alepha.store.set(\"alepha.server.request.apiLinks\", data.api);\n    this.alepha.store.set(currentUserAtom, data.user);\n\n    return data.user;\n  }\n\n  public can(action: string): boolean {\n    if (!this.user) {\n      return false;\n    }\n\n    return this.linkProvider.can(action);\n  }\n\n  public async login(\n    provider: string,\n    options: {\n      hostname?: string;\n      username?: string;\n      password?: string;\n      redirect?: string;\n      realm?: string;\n      [extra: string]: any;\n    },\n  ): Promise<Tokens> {\n    const realmParam = options.realm\n      ? `&realm=${encodeURIComponent(options.realm)}`\n      : \"\";\n\n    if (options.username || options.password) {\n      const { data } = await this.httpClient.fetch(\n        `${options.hostname || \"\"}${alephaServerAuthRoutes.token}?provider=${provider}${realmParam}`,\n        {\n          method: \"POST\",\n          body: JSON.stringify({\n            username: options.username,\n            password: options.password,\n          }),\n          schema: { response: tokenResponseSchema },\n        },\n      );\n\n      this.alepha.store.set(\"alepha.server.request.apiLinks\", data.api);\n      this.alepha.store.set(currentUserAtom, data.user);\n\n      return data;\n    }\n\n    if (this.alepha.isBrowser()) {\n      const browser = this.alepha.inject(ReactBrowserProvider);\n      const redirect =\n        options.redirect ||\n        (browser.transitioning\n          ? window.location.origin + browser.transitioning.to\n          : window.location.href);\n\n      const href = `${window.location.origin}${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${encodeURIComponent(redirect)}`;\n\n      if (browser.transitioning) {\n        throw new Redirection(href);\n      } else {\n        window.location.href = href;\n        return {} as Tokens;\n      }\n    }\n\n    throw new Redirection(\n      `${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${options.redirect || \"/\"}`,\n    );\n  }\n\n  public logout() {\n    const form = document.createElement(\"form\");\n    form.method = \"POST\";\n    form.action = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;\n    form.style.display = \"none\";\n    document.body.appendChild(form);\n    form.submit();\n  }\n}\n","import { useAlepha, useStore } from \"alepha/react\";\nimport { currentUserAtom } from \"alepha/security\";\nimport { LinkProvider } from \"alepha/server/links\";\nimport { ReactAuth } from \"../services/ReactAuth.ts\";\n\nexport const useAuth = <T extends object = any>() => {\n  const alepha = useAlepha();\n  const [user] = useStore(currentUserAtom);\n\n  return {\n    user,\n    logout: () => {\n      alepha.inject(ReactAuth).logout();\n    },\n    login: async (\n      provider: keyof T,\n      options: {\n        username?: string;\n        password?: string;\n        redirect?: string;\n        realm?: string;\n        [extra: string]: any;\n      } = {},\n    ) => {\n      await alepha.inject(ReactAuth).login(provider as string, options);\n    },\n    /**\n     * UI permission check — does the current user hold this permission?\n     * Supports exact and wildcard names (e.g. `\"admin:*\"`, `\"admin:user:read\"`).\n     *\n     * UI affordance only (show/hide/disable). Real access control is enforced\n     * server-side via `$secure` on the route/action.\n     */\n    has: (permission: string): boolean => {\n      return alepha.inject(LinkProvider).can(permission);\n    },\n  };\n};\n","import { $module } from \"alepha\";\nimport { AlephaReact } from \"alepha/react\";\nimport type { UserAccount } from \"alepha/security\";\nimport { $auth, AlephaServerAuth } from \"alepha/server/auth\";\nimport { AlephaServerLinks } from \"alepha/server/links\";\nimport { ReactAuthProvider } from \"./providers/ReactAuthProvider.ts\";\nimport { ReactAuth } from \"./services/ReactAuth.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./index.shared.ts\";\nexport * from \"./providers/ReactAuthProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\ndeclare module \"alepha/react/router\" {\n  interface ReactRouterState {\n    user?: UserAccount;\n  }\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Auth-related React components and hooks.\n *\n * **Features:**\n * - Login/logout components\n * - Protected route wrappers\n * - Auth state hooks\n *\n * @module alepha.react.auth\n */\nexport const AlephaReactAuth = $module({\n  name: \"alepha.react.auth\",\n  primitives: [$auth],\n  services: [\n    AlephaReact,\n    AlephaServerLinks,\n    AlephaServerAuth,\n    ReactAuthProvider,\n    ReactAuth,\n  ],\n});\n"],"mappings":";;;;;;;;;AAGA,IAAa,oBAAb,MAA+B;CAC7B,SAA4B,QAAQ,MAAM;CAE1C,WAA2B,MAAM;EAC/B,IAAI;EACJ,SAAS,OAAO,EAAE,SAAS,YAAY;GACrC,IAAI,SAAS,MAAM;IACjB,MAAM,EAAE,OAAO,OAAO,GAAG,SAAS,QAAQ;IAC1C,KAAK,OAAO,MAAM,IAAI,iBAAiB,IAAI;IAC3C,MAAM,OAAO;GACf;EACF;CACF,CAAC;AACH;;;;;;ACAA,IAAa,YAAb,MAAuB;CACrB,MAAyB,QAAQ;CACjC,SAA4B,QAAQ,MAAM;CAC1C,aAAgC,QAAQ,UAAU;CAClD,eAAkC,QAAQ,YAAY;CAEtD,oBAAuC,MAAM;EAC3C,IAAI;EACJ,SAAS,OAAO,UAAU;GACxB,IAAI,KAAK,OAAO,UAAU,GACxB,OAAO,eAAe,MAAM,OAAO,QAAQ,EACzC,WAAW,KAAK,KAClB,CAAC;EAEL;CACF,CAAC;CAED,iBAAoC,MAAM;EACxC,IAAI;EACJ,SAAS,OAAO,EAAE,cAAc;GAC9B,IAAI,KAAK,OAAO,UAAU,KAAK,KAAK,MAElC,QAAQ,gBAAgB;EAE5B;CACF,CAAC;;;;;;CAOD,IAAW,OAAqC;EAC9C,OAAO,KAAK,OAAO,MAAM,IAAI,eAAe;CAG9C;CAEA,MAAa,OAAO;EAClB,MAAM,EAAE,SAAS,MAAM,KAAK,WAAW,MACrC,uBAAuB,UACvB,EACE,QAAQ,EAAE,UAAU,uBAAuB,EAC7C,CACF;EAEA,KAAK,OAAO,MAAM,IAAI,kCAAkC,KAAK,GAAG;EAChE,KAAK,OAAO,MAAM,IAAI,iBAAiB,KAAK,IAAI;EAEhD,OAAO,KAAK;CACd;CAEA,IAAW,QAAyB;EAClC,IAAI,CAAC,KAAK,MACR,OAAO;EAGT,OAAO,KAAK,aAAa,IAAI,MAAM;CACrC;CAEA,MAAa,MACX,UACA,SAQiB;EACjB,MAAM,aAAa,QAAQ,QACvB,UAAU,mBAAmB,QAAQ,KAAK,MAC1C;EAEJ,IAAI,QAAQ,YAAY,QAAQ,UAAU;GACxC,MAAM,EAAE,SAAS,MAAM,KAAK,WAAW,MACrC,GAAG,QAAQ,YAAY,KAAK,uBAAuB,MAAM,YAAY,WAAW,cAChF;IACE,QAAQ;IACR,MAAM,KAAK,UAAU;KACnB,UAAU,QAAQ;KAClB,UAAU,QAAQ;IACpB,CAAC;IACD,QAAQ,EAAE,UAAU,oBAAoB;GAC1C,CACF;GAEA,KAAK,OAAO,MAAM,IAAI,kCAAkC,KAAK,GAAG;GAChE,KAAK,OAAO,MAAM,IAAI,iBAAiB,KAAK,IAAI;GAEhD,OAAO;EACT;EAEA,IAAI,KAAK,OAAO,UAAU,GAAG;GAC3B,MAAM,UAAU,KAAK,OAAO,OAAO,oBAAoB;GACvD,MAAM,WACJ,QAAQ,aACP,QAAQ,gBACL,OAAO,SAAS,SAAS,QAAQ,cAAc,KAC/C,OAAO,SAAS;GAEtB,MAAM,OAAO,GAAG,OAAO,SAAS,SAAS,uBAAuB,MAAM,YAAY,WAAW,WAAW,gBAAgB,mBAAmB,QAAQ;GAEnJ,IAAI,QAAQ,eACV,MAAM,IAAI,YAAY,IAAI;QACrB;IACL,OAAO,SAAS,OAAO;IACvB,OAAO,CAAC;GACV;EACF;EAEA,MAAM,IAAI,YACR,GAAG,uBAAuB,MAAM,YAAY,WAAW,WAAW,gBAAgB,QAAQ,YAAY,KACxG;CACF;CAEA,SAAgB;EACd,MAAM,OAAO,SAAS,cAAc,MAAM;EAC1C,KAAK,SAAS;EACd,KAAK,SAAS,GAAG,uBAAuB,OAAO,4BAA4B,mBAAmB,OAAO,SAAS,MAAM;EACpH,KAAK,MAAM,UAAU;EACrB,SAAS,KAAK,YAAY,IAAI;EAC9B,KAAK,OAAO;CACd;AACF;;;ACxIA,MAAa,gBAAwC;CACnD,MAAM,SAAS,UAAU;CACzB,MAAM,CAAC,QAAQ,SAAS,eAAe;CAEvC,OAAO;EACL;EACA,cAAc;GACZ,OAAO,OAAO,SAAS,EAAE,OAAO;EAClC;EACA,OAAO,OACL,UACA,UAMI,CAAC,MACF;GACH,MAAM,OAAO,OAAO,SAAS,EAAE,MAAM,UAAoB,OAAO;EAClE;;;;;;;;EAQA,MAAM,eAAgC;GACpC,OAAO,OAAO,OAAO,YAAY,EAAE,IAAI,UAAU;EACnD;CACF;AACF;;;;;;;;;;;;;ACJA,MAAa,kBAAkB,QAAQ;CACrC,MAAM;CACN,YAAY,CAAC,KAAK;CAClB,UAAU;EACR;EACA;EACA;EACA;EACA;CACF;AACF,CAAC"}

package/dist/react/core/index.d.ts

@@ -1,8 +1,5 @@
-import * as _$alepha from "alepha";
 import { Alepha, Async, Atom, Hook, Hooks, Service, State, Static, TAtomObject } from "alepha";
-import * as _$react from "react";
 import React, { DependencyList, ErrorInfo, PropsWithChildren, ReactNode } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
 import { DurationLike } from "alepha/datetime";
 import { ClientScope, HttpVirtualClient } from "alepha/server/links";
 
@@ -82,7 +79,7 @@ declare class ErrorBoundary extends React.Component<PropsWithChildren<ErrorBound
 /**
  * React context to provide the Alepha instance throughout the component tree.
  */
-declare const AlephaContext: _$react.Context<Alepha | undefined>;
+declare const AlephaContext: import("react").Context<Alepha | undefined>;
 //#endregion
 //#region ../../src/react/core/contexts/AlephaProvider.d.ts
 interface AlephaProviderProps {
@@ -95,7 +92,7 @@ interface AlephaProviderProps {
  *
  * This isn't recommended for apps using `alepha/react/router`, as Router will handle this for you.
  */
-declare const AlephaProvider: (props: AlephaProviderProps) => string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | _$react.ReactPortal | _$react.ReactElement<unknown, string | _$react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | _$react_jsx_runtime0.JSX.Element | null | undefined;
+declare const AlephaProvider: (props: AlephaProviderProps) => string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
 //#endregion
 //#region ../../src/react/core/hooks/useAction.d.ts
 /**
@@ -473,7 +470,9 @@ interface UseQueryReturn<Result> {
    */
   data: Result | undefined;
   /**
-   * Loading state — `true` while a fetch is in flight.
+   * Loading state — `true` while a fetch is in flight, and also from the
+   * first render until the initial auto-run settles (for enabled queries
+   * with no `initialData`), so a skeleton can render without a flash.
    */
   loading: boolean;
   /**
@@ -560,7 +559,7 @@ declare module "alepha" {
  *
  * @module alepha.react
  */
-declare const AlephaReact: _$alepha.Service<_$alepha.Module>;
+declare const AlephaReact: import("alepha").Service<import("alepha").Module>;
 //#endregion
-export { ActionContext, AlephaContext, AlephaProvider, AlephaProviderProps, AlephaReact, ClientOnly, ClientOnlyProps, ErrorBoundary, ErrorBoundaryProps, UseActionOptions, UseActionReturn, UseQueryOptions, UseQueryReturn, UseStoreReturn, useAction, useAlepha, useClient, useEvents, useInject, useQuery, useStore };
+export { ActionContext, AlephaContext, AlephaProvider, AlephaProviderProps, AlephaReact, ClientOnly, type ClientOnlyProps, ErrorBoundary, type ErrorBoundaryProps, UseActionOptions, UseActionReturn, UseQueryOptions, UseQueryReturn, UseStoreReturn, useAction, useAlepha, useClient, useEvents, useInject, useQuery, useStore };
 //# sourceMappingURL=index.d.ts.map

package/dist/react/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/react/core/components/ClientOnly.tsx","../../../src/react/core/components/ErrorBoundary.tsx","../../../src/react/core/contexts/AlephaContext.ts","../../../src/react/core/contexts/AlephaProvider.tsx","../../../src/react/core/hooks/useAction.ts","../../../src/react/core/hooks/useAlepha.ts","../../../src/react/core/hooks/useClient.ts","../../../src/react/core/hooks/useEvents.ts","../../../src/react/core/hooks/useInject.ts","../../../src/react/core/hooks/useQuery.ts","../../../src/react/core/hooks/useStore.ts","../../../src/react/core/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/react/core/components/ClientOnly.tsx","../../../src/react/core/components/ErrorBoundary.tsx","../../../src/react/core/contexts/AlephaContext.ts","../../../src/react/core/contexts/AlephaProvider.tsx","../../../src/react/core/hooks/useAction.ts","../../../src/react/core/hooks/useAlepha.ts","../../../src/react/core/hooks/useClient.ts","../../../src/react/core/hooks/useEvents.ts","../../../src/react/core/hooks/useInject.ts","../../../src/react/core/hooks/useQuery.ts","../../../src/react/core/hooks/useStore.ts","../../../src/react/core/index.ts"],"mappings":"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"}

package/dist/react/core/index.js

@@ -258,6 +258,7 @@ function useAction(options, deps) {
 				abortControllerRef.current.abort();
 				abortControllerRef.current = void 0;
 			}
+			isExecutingRef.current = false;
 		};
 	}, []);
 	const executeAction = useCallback(async (...args) => {
@@ -293,7 +294,6 @@ function useAction(options, deps) {
 				error
 			});
 			if (options.onError) await options.onError(error);
-			else throw error;
 		} finally {
 			isExecutingRef.current = false;
 			if (isMountedRef.current) setLoading(false);
@@ -446,15 +446,18 @@ const useEvents = (opts, deps) => {
 * ```
 */
 function useQuery(options, deps) {
+	const enabled = options.enabled !== false;
 	const [data, setData] = useState(options.initialData);
+	const settledRef = useRef(false);
 	const action = useAction({
 		id: options.id,
 		handler: options.handler,
-		runOnInit: options.enabled !== false,
+		runOnInit: enabled,
 		runEvery: options.runEvery,
 		debounce: options.debounce,
 		onError: options.onError,
 		onSuccess: async (result) => {
+			settledRef.current = true;
 			setData(result);
 			if (options.onSuccess) await options.onSuccess(result);
 		}
@@ -462,7 +465,7 @@ function useQuery(options, deps) {
 	const refetch = useCallback(() => action.run(), [action.run]);
 	return {
 		data,
-		loading: action.loading,
+		loading: action.loading || enabled && options.initialData === void 0 && !settledRef.current && action.error === void 0,
 		error: action.error,
 		refetch,
 		cancel: action.cancel