alepha 0.15.1 → 0.15.3

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

@@ -1,6 +1,6 @@
 import * as alepha1 from "alepha";
 import { Alepha, KIND, Primitive, Service, Static, TSchema } from "alepha";
-import * as alepha_logger0 from "alepha/logger";
+import * as alepha_logger1 from "alepha/logger";
 import { DateTimeProvider } from "alepha/datetime";
 
 //#region ../../src/queue/core/providers/QueueProvider.d.ts
@@ -29,7 +29,7 @@ declare abstract class QueueProvider {
 //#endregion
 //#region ../../src/queue/core/providers/MemoryQueueProvider.d.ts
 declare class MemoryQueueProvider implements QueueProvider {
-  protected readonly log: alepha_logger0.Logger;
+  protected readonly log: alepha_logger1.Logger;
   protected queueList: Record<string, string[]>;
   push(queue: string, ...messages: string[]): Promise<void>;
   pop(queue: string): Promise<string | undefined>;
@@ -55,7 +55,7 @@ declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
 }
 declare class WorkerProvider {
-  protected readonly log: alepha_logger0.Logger;
+  protected readonly log: alepha_logger1.Logger;
   protected readonly env: {
     QUEUE_WORKER_INTERVAL: number;
     QUEUE_WORKER_MAX_INTERVAL: number;
@@ -351,7 +351,7 @@ interface QueuePrimitiveOptions<T extends TSchema> {
   handler?: (message: QueueMessage<T>) => Promise<void>;
 }
 declare class QueuePrimitive<T extends TSchema> extends Primitive<QueuePrimitiveOptions<T>> {
-  protected readonly log: alepha_logger0.Logger;
+  protected readonly log: alepha_logger1.Logger;
   protected readonly workerProvider: WorkerProvider;
   readonly provider: QueueProvider | MemoryQueueProvider;
   push(...payloads: Array<Static<T>>): Promise<void>;
@@ -532,14 +532,22 @@ declare class ConsumerPrimitive<T extends TSchema> extends Primitive<ConsumerPri
 //#endregion
 //#region ../../src/queue/core/index.d.ts
 /**
- * Provides asynchronous message queuing and processing capabilities through declarative queue descriptors.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | epic | stable |
  *
- * The queue module enables reliable background job processing and message passing using the `$queue` descriptor
- * on class properties. It supports schema validation, automatic retries, and multiple queue backends for
- * building scalable, decoupled applications with robust error handling.
+ * Asynchronous message processing with automatic worker management.
+ *
+ * **Features:**
+ * - Background job queues with type-safe payloads
+ * - Queue consumer handlers
+ * - Automatic worker threads for non-blocking processing
+ * - Retry mechanisms with exponential backoff
+ * - Dead letter queues for failed messages
+ * - Batch processing support
+ * - Configurable concurrency and worker pools
+ * - Providers: Memory (dev), Redis (production)
  *
- * @see {@link $queue}
- * @see {@link $consumer}
  * @module alepha.queue
  */
 declare const AlephaQueue: alepha1.Service<alepha1.Module>;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/queue/core/providers/QueueProvider.ts","../../../src/queue/core/providers/MemoryQueueProvider.ts","../../../src/queue/core/providers/WorkerProvider.ts","../../../src/queue/core/primitives/$queue.ts","../../../src/queue/core/primitives/$consumer.ts","../../../src/queue/core/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../../src/queue/core/providers/QueueProvider.ts","../../../src/queue/core/providers/MemoryQueueProvider.ts","../../../src/queue/core/providers/WorkerProvider.ts","../../../src/queue/core/primitives/$queue.ts","../../../src/queue/core/primitives/$consumer.ts","../../../src/queue/core/index.ts"],"mappings":";;;;;;;;;;;uBAKsB,aAAA;EAAA;;;;;;EAAA,SAOJ,IAAA,CAAK,KAAA,UAAe,OAAA,WAAkB,OAAA;EAAA;;;;;;;EAAA,SAStC,GAAA,CAAI,KAAA,WAAgB,OAAA;AAAA;;;cClBzB,mBAAA,YAA+B,aAAA;EAAA,mBACvB,GAAA,EADY,cAAA,CACT,MAAA;EAAA,UACZ,SAAA,EAAW,MAAA;EAER,IAAA,CAAK,KAAA,aAAkB,QAAA,aAAqB,OAAA;EAQ5C,GAAA,CAAI,KAAA,WAAgB,OAAA;AAAA;;;cCI7B,SAAA,UAAS,OAAA;;AFdf;;yBEkCE,OAAA,CAAA,QAAA;EFlB2C;;;;EATW;;;;;;;YE8B5C,GAAA,SAAY,OAAA,CAAQ,MAAA,QAAc,SAAA;AAAA;AAAA,cAGjC,cAAA;EAAA,mBACQ,GAAA,EADM,cAAA,CACH,MAAA;EAAA,mBACH,GAAA;;;;;qBACA,MAAA,EAAM,MAAA;EAAA,mBACN,aAAA,EAAa,aAAA;EAAA,mBACb,gBAAA,EAAgB,gBAAA;EAAA,UAEzB,cAAA,EAAgB,KAAA,CAAM,OAAA;EAAA,UACtB,cAAA;EAAA,UACA,eAAA,EAAe,eAAA;EAAA,UACf,eAAA,EAAiB,MAAA;EAAA,UACjB,SAAA,EAAW,KAAA,CAAM,QAAA;EAAA,IAEhB,SAAA,CAAA;EAAA,mBAIQ,KAAA,EANO,OAAA,CAMF,aAAA;EDvDiC;;;;EAAA,UC4F/C,YAAA,CAAA;EAAA,mBAoCS,IAAA,EAzEK,OAAA,CAyED,aAAA;;;;AAtH0B;;YAoIjC,kBAAA,CAAmB,CAAA,WAAY,OAAA;EA9G/C;;;EAAA,UAyIgB,cAAA,CAAA,GAAkB,OAAA,aAAoB,WAAA;EA7JzC;;;EAAA,UA0KG,cAAA,CAAe,QAAA;IAC7B,OAAA;IACA,QAAA,EAAU,QAAA;EAAA,IACX,OAAA;;;;;;YAoBe,WAAA,CAAA,GAAW,OAAA;;;;EAapB,MAAA,CAAA;AAAA;AAAA,UAUQ,QAAA,WAAmB,OAAA,GAAU,OAAA;EAC5C,KAAA,EAAO,cAAA,CAAe,CAAA;EACtB,OAAA,GAAU,OAAA,EAAS,YAAA,CAAa,CAAA,MAAO,OAAA;AAAA;AAAA,UAGxB,WAAA;EACf,QAAA,EAAU,QAAA;EACV,OAAA;AAAA;;;;;AF7OF;;;;;;;;;;;;;;;;ACFA;;;;;;;;;;;;;;;;;;;;;;;;;;;ACcmD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cCgFa,MAAA;EAAA,WAAoB,OAAA,EAAO,OAAA,EAC7B,qBAAA,CAAsB,CAAA,IAC9B,cAAA,CAAe,CAAA;EAAA;;UAMD,qBAAA,WAAgC,OAAA;EDhFrC;;;;;;;;;;;;;;;ECgGV,IAAA;EDA+C;;;;;;;;;;;;;ECe/C,WAAA;ED6Da;AAUf;;;;;;;;;;;;;;;;;;EClDE,QAAA,cAAsB,OAAA,CAAQ,aAAA;EDoDX;;;;;;AAGrB;;;;;;;;;;;;ACnHA;;;;;;;EAuFE,MAAA,EAAQ,CAAA;;;;;;;;;;;;;;;;AA/EV;;;;;;;;;;;;;;;;;;;;;;;;;;EA0HE,OAAA,IAAW,OAAA,EAAS,YAAA,CAAa,CAAA,MAAO,OAAA;AAAA;AAAA,cAK7B,cAAA,WAAyB,OAAA,UAAiB,SAAA,CACrD,qBAAA,CAAsB,CAAA;EAAA,mBAEH,GAAA,EAFE,cAAA,CAEC,MAAA;EAAA,mBACH,cAAA,EAAc,cAAA;EAAA,SACjB,QAAA,EAAQ,aAAA,GAAA,mBAAA;EAEX,IAAA,CAAA,GAAQ,QAAA,EAAU,KAAA,CAAM,MAAA,CAAO,CAAA,KAAG,OAAA;EAAA,IAiBpC,IAAA,CAAA;EAAA,UAID,SAAA,CAAA,GAAS,aAAA,GAAA,mBAAA;AAAA;AAAA,UAeJ,kBAAA;EACf,OAAA,EAAS,OAAA;AAAA;AAAA,UAGM,YAAA,WAAuB,OAAA;EACtC,OAAA,EAAS,MAAA,CAAO,CAAA;AAAA;;;;;;;AH/SlB;;;;;;;;;;;;;;;;ACFA;;;;;;;;;;;;;;;;;;;;;;;;;;;ACcmD;;cEyCtC,SAAA;EAAA,WAAuB,OAAA,EAAO,OAAA,EAChC,wBAAA,CAAyB,CAAA,IACjC,iBAAA,CAAkB,CAAA;EAAA;;UAMJ,wBAAA,WAAmC,OAAA;EF/CrC;;;;;;;;;;;;;;;;;;;;;;;;;;AA0Bf;;;;EEoDE,KAAA,EAAO,cAAA,CAAe,CAAA;EFhDU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0LlC;;;;;;;;;EE/DE,OAAA,GAAU,OAAA;IAAW,OAAA,EAAS,MAAA,CAAO,CAAA;EAAA,MAAS,OAAA;AAAA;AAAA,cAKnC,iBAAA,WAA4B,OAAA,UAAiB,SAAA,CACxD,wBAAA,CAAyB,CAAA;;;;AJ7K3B;;;;;;;;;;;;;;;;ACFA;;cIiCa,WAAA,EAAW,OAAA,CAAA,OAAA,CAYtB,OAAA,CAZsB,MAAA"}

package/dist/queue/core/index.js

@@ -361,14 +361,22 @@ $queue[KIND] = QueuePrimitive;
 //#endregion
 //#region ../../src/queue/core/index.ts
 /**
-* Provides asynchronous message queuing and processing capabilities through declarative queue descriptors.
+* | type | quality | stability |
+* |------|---------|-----------|
+* | backend | epic | stable |
 *
-* The queue module enables reliable background job processing and message passing using the `$queue` descriptor
-* on class properties. It supports schema validation, automatic retries, and multiple queue backends for
-* building scalable, decoupled applications with robust error handling.
+* Asynchronous message processing with automatic worker management.
+*
+* **Features:**
+* - Background job queues with type-safe payloads
+* - Queue consumer handlers
+* - Automatic worker threads for non-blocking processing
+* - Retry mechanisms with exponential backoff
+* - Dead letter queues for failed messages
+* - Batch processing support
+* - Configurable concurrency and worker pools
+* - Providers: Memory (dev), Redis (production)
 *
-* @see {@link $queue}
-* @see {@link $consumer}
 * @module alepha.queue
 */
 const AlephaQueue = $module({

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/queue/core/primitives/$consumer.ts","../../../src/queue/core/providers/MemoryQueueProvider.ts","../../../src/queue/core/providers/QueueProvider.ts","../../../src/queue/core/providers/WorkerProvider.ts","../../../src/queue/core/primitives/$queue.ts","../../../src/queue/core/index.ts"],"sourcesContent":["import {\n  createPrimitive,\n  KIND,\n  Primitive,\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  /**\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 Primitive<\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  $env,\n  $hook,\n  $inject,\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\nconst envSchema = t.object({\n  /**\n   * The interval in milliseconds to wait before checking for new messages.\n   */\n  QUEUE_WORKER_INTERVAL: t.integer({\n    default: 1000,\n  }),\n  /**\n   * The maximum interval in milliseconds to wait before checking for new messages.\n   */\n  QUEUE_WORKER_MAX_INTERVAL: t.integer({\n    default: 32000,\n  }),\n  /**\n   * The number of workers to run concurrently. Defaults to 1.\n   * Useful only if you are doing a lot of I/O.\n   */\n  QUEUE_WORKER_CONCURRENCY: t.integer({\n    default: 1,\n  }),\n});\n\ndeclare module \"alepha\" {\n  interface Env extends Partial<Static<typeof envSchema>> {}\n}\n\nexport class WorkerProvider {\n  protected readonly log = $logger();\n  protected readonly env = $env(envSchema);\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 = new AbortController();\n  protected workerIntervals: Record<number, number> = {};\n  protected consumers: Array<Consumer> = [];\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(consumer.options);\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.env.QUEUE_WORKER_CONCURRENCY} worker${\n            this.env.QUEUE_WORKER_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    const workerToStart =\n      this.env.QUEUE_WORKER_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 -= 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.env.QUEUE_WORKER_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.env.QUEUE_WORKER_MAX_INTERVAL) {\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    for (const consumer of this.consumers) {\n      const provider = consumer.queue.provider;\n      const message = await provider.pop(consumer.queue.name);\n      if (message) {\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 { $module, type Alepha } from \"alepha\";\nimport { $consumer } from \"./primitives/$consumer.ts\";\nimport { $queue } from \"./primitives/$queue.ts\";\nimport { MemoryQueueProvider } from \"./providers/MemoryQueueProvider.ts\";\nimport { QueueProvider } from \"./providers/QueueProvider.ts\";\nimport { WorkerProvider } from \"./providers/WorkerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$consumer.ts\";\nexport * from \"./primitives/$queue.ts\";\nexport * from \"./providers/MemoryQueueProvider.ts\";\nexport * from \"./providers/QueueProvider.ts\";\nexport * from \"./providers/WorkerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Provides asynchronous message queuing and processing capabilities through declarative queue descriptors.\n *\n * The queue module enables reliable background job processing and message passing using the `$queue` descriptor\n * on class properties. It supports schema validation, automatic retries, and multiple queue backends for\n * building scalable, decoupled applications with robust error handling.\n *\n * @see {@link $queue}\n * @see {@link $consumer}\n * @module alepha.queue\n */\nexport const AlephaQueue = $module({\n  name: \"alepha.queue\",\n  primitives: [$queue, $consumer],\n  services: [QueueProvider, MemoryQueueProvider, WorkerProvider],\n  register: (alepha: Alepha) =>\n    alepha\n      .with({\n        optional: true,\n        provide: QueueProvider,\n        use: MemoryQueueProvider,\n      })\n      .with(WorkerProvider),\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/queue/core/primitives/$consumer.ts","../../../src/queue/core/providers/MemoryQueueProvider.ts","../../../src/queue/core/providers/QueueProvider.ts","../../../src/queue/core/providers/WorkerProvider.ts","../../../src/queue/core/primitives/$queue.ts","../../../src/queue/core/index.ts"],"sourcesContent":["import {\n  createPrimitive,\n  KIND,\n  Primitive,\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  /**\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 Primitive<\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  $env,\n  $hook,\n  $inject,\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\nconst envSchema = t.object({\n  /**\n   * The interval in milliseconds to wait before checking for new messages.\n   */\n  QUEUE_WORKER_INTERVAL: t.integer({\n    default: 1000,\n  }),\n  /**\n   * The maximum interval in milliseconds to wait before checking for new messages.\n   */\n  QUEUE_WORKER_MAX_INTERVAL: t.integer({\n    default: 32000,\n  }),\n  /**\n   * The number of workers to run concurrently. Defaults to 1.\n   * Useful only if you are doing a lot of I/O.\n   */\n  QUEUE_WORKER_CONCURRENCY: t.integer({\n    default: 1,\n  }),\n});\n\ndeclare module \"alepha\" {\n  interface Env extends Partial<Static<typeof envSchema>> {}\n}\n\nexport class WorkerProvider {\n  protected readonly log = $logger();\n  protected readonly env = $env(envSchema);\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 = new AbortController();\n  protected workerIntervals: Record<number, number> = {};\n  protected consumers: Array<Consumer> = [];\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(consumer.options);\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.env.QUEUE_WORKER_CONCURRENCY} worker${\n            this.env.QUEUE_WORKER_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    const workerToStart =\n      this.env.QUEUE_WORKER_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 -= 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.env.QUEUE_WORKER_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.env.QUEUE_WORKER_MAX_INTERVAL) {\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    for (const consumer of this.consumers) {\n      const provider = consumer.queue.provider;\n      const message = await provider.pop(consumer.queue.name);\n      if (message) {\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 { $module, type Alepha } from \"alepha\";\nimport { $consumer } from \"./primitives/$consumer.ts\";\nimport { $queue } from \"./primitives/$queue.ts\";\nimport { MemoryQueueProvider } from \"./providers/MemoryQueueProvider.ts\";\nimport { QueueProvider } from \"./providers/QueueProvider.ts\";\nimport { WorkerProvider } from \"./providers/WorkerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$consumer.ts\";\nexport * from \"./primitives/$queue.ts\";\nexport * from \"./providers/MemoryQueueProvider.ts\";\nexport * from \"./providers/QueueProvider.ts\";\nexport * from \"./providers/WorkerProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * | type | quality | stability |\n * |------|---------|-----------|\n * | backend | epic | stable |\n *\n * Asynchronous message processing with automatic worker management.\n *\n * **Features:**\n * - Background job queues with type-safe payloads\n * - Queue consumer handlers\n * - Automatic worker threads for non-blocking processing\n * - Retry mechanisms with exponential backoff\n * - Dead letter queues for failed messages\n * - Batch processing support\n * - Configurable concurrency and worker pools\n * - Providers: Memory (dev), Redis (production)\n *\n * @module alepha.queue\n */\nexport const AlephaQueue = $module({\n  name: \"alepha.queue\",\n  primitives: [$queue, $consumer],\n  services: [QueueProvider, MemoryQueueProvider, WorkerProvider],\n  register: (alepha: Alepha) =>\n    alepha\n      .with({\n        optional: true,\n        provide: QueueProvider,\n        use: MemoryQueueProvider,\n      })\n      .with(WorkerProvider),\n});\n"],"mappings":"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"}

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

@@ -0,0 +1,108 @@
+import { $hook, $inject, $module, Alepha } from "alepha";
+import { $logger } from "alepha/logger";
+import { ReactBrowserProvider, Redirection } from "alepha/react/router";
+import { HttpClient } from "alepha/server";
+import { alephaServerAuthRoutes, tokenResponseSchema, userinfoResponseSchema } from "alepha/server/auth";
+import { LinkProvider } from "alepha/server/links";
+import { useAlepha, useStore } from "alepha/react";
+
+//#region ../../src/react/auth/services/ReactAuth.ts
+/**
+* Browser, SSR friendly, service to handle authentication.
+*/
+var ReactAuth = class {
+	log = $logger();
+	alepha = $inject(Alepha);
+	httpClient = $inject(HttpClient);
+	linkProvider = $inject(LinkProvider);
+	onBeginTransition = $hook({
+		on: "react:transition:begin",
+		handler: async (event) => {
+			if (this.alepha.isBrowser()) Object.defineProperty(event.state, "user", { get: () => this.user });
+		}
+	});
+	onFetchRequest = $hook({
+		on: "client:onRequest",
+		handler: async ({ request }) => {
+			if (this.alepha.isBrowser() && this.user) request.credentials ??= "include";
+		}
+	});
+	/**
+	* Get the current authenticated user.
+	*
+	* Alias for `alepha.state.get("user")`
+	*/
+	get user() {
+		return this.alepha.store.get("alepha.server.request.user");
+	}
+	async ping() {
+		const { data } = await this.httpClient.fetch(alephaServerAuthRoutes.userinfo, { schema: { response: userinfoResponseSchema } });
+		this.alepha.store.set("alepha.server.request.apiLinks", data.api);
+		this.alepha.store.set("alepha.server.request.user", data.user);
+		return data.user;
+	}
+	can(action) {
+		if (!this.user) return false;
+		return this.linkProvider.can(action);
+	}
+	async login(provider, options) {
+		const realmParam = options.realm ? `&realm=${encodeURIComponent(options.realm)}` : "";
+		if (options.username || options.password) {
+			const { data } = await this.httpClient.fetch(`${options.hostname || ""}${alephaServerAuthRoutes.token}?provider=${provider}${realmParam}`, {
+				method: "POST",
+				body: JSON.stringify({
+					username: options.username,
+					password: options.password
+				}),
+				schema: { response: tokenResponseSchema }
+			});
+			this.alepha.store.set("alepha.server.request.apiLinks", data.api);
+			this.alepha.store.set("alepha.server.request.user", data.user);
+			return data;
+		}
+		if (this.alepha.isBrowser()) {
+			const browser = this.alepha.inject(ReactBrowserProvider);
+			const redirect = options.redirect || (browser.transitioning ? window.location.origin + browser.transitioning.to : window.location.href);
+			const href = `${window.location.origin}${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${encodeURIComponent(redirect)}`;
+			if (browser.transitioning) throw new Redirection(href);
+			else {
+				window.location.href = href;
+				return {};
+			}
+		}
+		throw new Redirection(`${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${options.redirect || "/"}`);
+	}
+	logout() {
+		window.location.href = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;
+	}
+};
+
+//#endregion
+//#region ../../src/react/auth/hooks/useAuth.ts
+const useAuth = () => {
+	const alepha = useAlepha();
+	const [user] = useStore("alepha.server.request.user");
+	return {
+		user,
+		logout: () => {
+			alepha.inject(ReactAuth).logout();
+		},
+		login: async (provider, options = {}) => {
+			await alepha.inject(ReactAuth).login(provider, options);
+		},
+		can: (name) => {
+			return alepha.inject(LinkProvider).can(name);
+		}
+	};
+};
+
+//#endregion
+//#region ../../src/react/auth/index.browser.ts
+const AlephaReactAuth = $module({
+	name: "alepha.react.auth",
+	services: [ReactAuth]
+});
+
+//#endregion
+export { AlephaReactAuth, ReactAuth, useAuth };
+//# sourceMappingURL=index.browser.js.map

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

@@ -0,0 +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 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(\"alepha.server.request.user\");\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(\"alepha.server.request.user\", 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(\"alepha.server.request.user\", 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    window.location.href = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;\n  }\n}\n","import { useAlepha, useStore } from \"alepha/react\";\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(\"alepha.server.request.user\");\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":";;;;;;;;;;;;AAgBA,IAAa,YAAb,MAAuB;CACrB,AAAmB,MAAM,SAAS;CAClC,AAAmB,SAAS,QAAQ,OAAO;CAC3C,AAAmB,aAAa,QAAQ,WAAW;CACnD,AAAmB,eAAe,QAAQ,aAAa;CAEvD,AAAmB,oBAAoB,MAAM;EAC3C,IAAI;EACJ,SAAS,OAAO,UAAU;AACxB,OAAI,KAAK,OAAO,WAAW,CACzB,QAAO,eAAe,MAAM,OAAO,QAAQ,EACzC,WAAW,KAAK,MACjB,CAAC;;EAGP,CAAC;CAEF,AAAmB,iBAAiB,MAAM;EACxC,IAAI;EACJ,SAAS,OAAO,EAAE,cAAc;AAC9B,OAAI,KAAK,OAAO,WAAW,IAAI,KAAK,KAElC,SAAQ,gBAAgB;;EAG7B,CAAC;;;;;;CAOF,IAAW,OAAqC;AAC9C,SAAO,KAAK,OAAO,MAAM,IAAI,6BAA6B;;CAG5D,MAAa,OAAO;EAClB,MAAM,EAAE,SAAS,MAAM,KAAK,WAAW,MACrC,uBAAuB,UACvB,EACE,QAAQ,EAAE,UAAU,wBAAwB,EAC7C,CACF;AAED,OAAK,OAAO,MAAM,IAAI,kCAAkC,KAAK,IAAI;AACjE,OAAK,OAAO,MAAM,IAAI,8BAA8B,KAAK,KAAK;AAE9D,SAAO,KAAK;;CAGd,AAAO,IAAI,QAAyB;AAClC,MAAI,CAAC,KAAK,KACR,QAAO;AAGT,SAAO,KAAK,aAAa,IAAI,OAAO;;CAGtC,MAAa,MACX,UACA,SAQiB;EACjB,MAAM,aAAa,QAAQ,QACvB,UAAU,mBAAmB,QAAQ,MAAM,KAC3C;AAEJ,MAAI,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;AAED,QAAK,OAAO,MAAM,IAAI,kCAAkC,KAAK,IAAI;AACjE,QAAK,OAAO,MAAM,IAAI,8BAA8B,KAAK,KAAK;AAE9D,UAAO;;AAGT,MAAI,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;AAEpJ,OAAI,QAAQ,cACV,OAAM,IAAI,YAAY,KAAK;QACtB;AACL,WAAO,SAAS,OAAO;AACvB,WAAO,EAAE;;;AAIb,QAAM,IAAI,YACR,GAAG,uBAAuB,MAAM,YAAY,WAAW,WAAW,gBAAgB,QAAQ,YAAY,MACvG;;CAGH,AAAO,SAAS;AACd,SAAO,SAAS,OAAO,GAAG,uBAAuB,OAAO,4BAA4B,mBAAmB,OAAO,SAAS,OAAO;;;;;;AChIlI,MAAa,gBAAwC;CACnD,MAAM,SAAS,WAAW;CAC1B,MAAM,CAAC,QAAQ,SAAS,6BAA6B;AAErD,QAAO;EACL;EACA,cAAc;AACZ,UAAO,OAAO,UAAU,CAAC,QAAQ;;EAEnC,OAAO,OACL,UACA,UAMI,EAAE,KACH;AACH,SAAM,OAAO,OAAO,UAAU,CAAC,MAAM,UAAoB,QAAQ;;EAEnE,MACE,SACY;AACZ,UAAO,OAAO,OAAO,aAAa,CAAC,IAAI,KAAe;;EAEzD;;;;;ACrBH,MAAa,kBAAkB,QAAQ;CACrC,MAAM;CACN,UAAU,CAAC,UAAU;CACtB,CAAC"}

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

@@ -0,0 +1,100 @@
+import * as alepha2 from "alepha";
+import { Alepha } from "alepha";
+import { Tokens } from "alepha/server/auth";
+import { HttpVirtualClient, LinkProvider } from "alepha/server/links";
+import * as alepha_logger0 from "alepha/logger";
+import { HttpClient } from "alepha/server";
+import { UserAccount, UserAccountToken } from "alepha/security";
+
+//#region ../../src/react/auth/hooks/useAuth.d.ts
+declare const useAuth: <T extends object = any>() => {
+  user: {
+    name?: string | undefined;
+    email?: string | undefined;
+    username?: string | undefined;
+    picture?: string | undefined;
+    sessionId?: string | undefined;
+    organizations?: string[] | undefined;
+    roles?: string[] | undefined;
+    id: string;
+  } | undefined;
+  logout: () => void;
+  login: (provider: keyof T, options?: {
+    username?: string;
+    password?: string;
+    redirect?: string;
+    realm?: string;
+    [extra: string]: any;
+  }) => Promise<void>;
+  can: <Api extends object = any>(name: keyof HttpVirtualClient<Api>) => boolean;
+};
+//#endregion
+//#region ../../src/react/auth/services/ReactAuth.d.ts
+/**
+ * Browser, SSR friendly, service to handle authentication.
+ */
+declare class ReactAuth {
+  protected readonly log: alepha_logger0.Logger;
+  protected readonly alepha: Alepha;
+  protected readonly httpClient: HttpClient;
+  protected readonly linkProvider: LinkProvider;
+  protected readonly onBeginTransition: alepha2.HookPrimitive<"react:transition:begin">;
+  protected readonly onFetchRequest: alepha2.HookPrimitive<"client:onRequest">;
+  /**
+   * Get the current authenticated user.
+   *
+   * Alias for `alepha.state.get("user")`
+   */
+  get user(): UserAccountToken | undefined;
+  ping(): Promise<{
+    name?: string | undefined;
+    email?: string | undefined;
+    username?: string | undefined;
+    picture?: string | undefined;
+    sessionId?: string | undefined;
+    organizations?: string[] | undefined;
+    roles?: string[] | undefined;
+    id: string;
+  } | undefined>;
+  can(action: string): boolean;
+  login(provider: string, options: {
+    hostname?: string;
+    username?: string;
+    password?: string;
+    redirect?: string;
+    realm?: string;
+    [extra: string]: any;
+  }): Promise<Tokens>;
+  logout(): void;
+}
+//#endregion
+//#region ../../src/react/auth/providers/ReactAuthProvider.d.ts
+declare class ReactAuthProvider {
+  protected readonly alepha: Alepha;
+  readonly onRender: alepha2.HookPrimitive<"react:server:render:begin">;
+}
+//#endregion
+//#region ../../src/react/auth/index.d.ts
+declare module "alepha/react/router" {
+  interface ReactRouterState {
+    user?: UserAccount;
+  }
+}
+/**
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | frontend | rare | stable |
+ *
+ * Auth-related React components and hooks.
+ *
+ * **Features:**
+ * - Login/logout components
+ * - Protected route wrappers
+ * - Auth state hooks
+ *
+ * @module alepha.react.auth
+ */
+declare const AlephaReactAuth: alepha2.Service<alepha2.Module>;
+//#endregion
+export { AlephaReactAuth, ReactAuth, ReactAuthProvider, useAuth };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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":";;;;;;;;;cAIa,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;;;;;;cCVvB,SAAA;EAAA,mBACQ,GAAA,EADC,cAAA,CACE,MAAA;EAAA,mBACH,MAAA,EAAM,MAAA;EAAA,mBACN,UAAA,EAAU,UAAA;EAAA,mBACV,YAAA,EAAY,YAAA;EAAA,mBAEZ,iBAAA,EAFY,OAAA,CAEK,aAAA;EAAA,mBAWjB,cAAA,EAXiB,OAAA,CAWH,aAAA;EDPjB;;;;;EAAA,ICsBL,IAAA,CAAA,GAAQ,gBAAA;EAIN,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;;;cCjII,iBAAA;EAAA,mBACQ,MAAA,EAAM,MAAA;EAAA,SAET,QAAA,EAFS,OAAA,CAED,aAAA;AAAA;;;;YCWd,gBAAA;IACR,IAAA,GAAO,WAAA;EAAA;AAAA;;AHbX;;;;;;;;;;;;;cGiCa,eAAA,EAAe,OAAA,CAAA,OAAA,CAU1B,OAAA,CAV0B,MAAA"}

package/dist/react/auth/index.js

@@ -0,0 +1,145 @@
+import { $hook, $inject, $module, Alepha } from "alepha";
+import { AlephaReact, useAlepha, useStore } from "alepha/react";
+import { $auth, AlephaServerAuth, alephaServerAuthRoutes, tokenResponseSchema, userinfoResponseSchema } from "alepha/server/auth";
+import { AlephaServerLinks, LinkProvider } from "alepha/server/links";
+import { $logger } from "alepha/logger";
+import { ReactBrowserProvider, Redirection } from "alepha/react/router";
+import { HttpClient } from "alepha/server";
+
+//#region ../../src/react/auth/providers/ReactAuthProvider.ts
+var ReactAuthProvider = class {
+	alepha = $inject(Alepha);
+	onRender = $hook({
+		on: "react:server:render:begin",
+		handler: async ({ request, state }) => {
+			if (request?.user) {
+				const { token, realm, ...user } = request.user;
+				this.alepha.store.set("alepha.server.request.user", user);
+				state.user = user;
+			}
+		}
+	});
+};
+
+//#endregion
+//#region ../../src/react/auth/services/ReactAuth.ts
+/**
+* Browser, SSR friendly, service to handle authentication.
+*/
+var ReactAuth = class {
+	log = $logger();
+	alepha = $inject(Alepha);
+	httpClient = $inject(HttpClient);
+	linkProvider = $inject(LinkProvider);
+	onBeginTransition = $hook({
+		on: "react:transition:begin",
+		handler: async (event) => {
+			if (this.alepha.isBrowser()) Object.defineProperty(event.state, "user", { get: () => this.user });
+		}
+	});
+	onFetchRequest = $hook({
+		on: "client:onRequest",
+		handler: async ({ request }) => {
+			if (this.alepha.isBrowser() && this.user) request.credentials ??= "include";
+		}
+	});
+	/**
+	* Get the current authenticated user.
+	*
+	* Alias for `alepha.state.get("user")`
+	*/
+	get user() {
+		return this.alepha.store.get("alepha.server.request.user");
+	}
+	async ping() {
+		const { data } = await this.httpClient.fetch(alephaServerAuthRoutes.userinfo, { schema: { response: userinfoResponseSchema } });
+		this.alepha.store.set("alepha.server.request.apiLinks", data.api);
+		this.alepha.store.set("alepha.server.request.user", data.user);
+		return data.user;
+	}
+	can(action) {
+		if (!this.user) return false;
+		return this.linkProvider.can(action);
+	}
+	async login(provider, options) {
+		const realmParam = options.realm ? `&realm=${encodeURIComponent(options.realm)}` : "";
+		if (options.username || options.password) {
+			const { data } = await this.httpClient.fetch(`${options.hostname || ""}${alephaServerAuthRoutes.token}?provider=${provider}${realmParam}`, {
+				method: "POST",
+				body: JSON.stringify({
+					username: options.username,
+					password: options.password
+				}),
+				schema: { response: tokenResponseSchema }
+			});
+			this.alepha.store.set("alepha.server.request.apiLinks", data.api);
+			this.alepha.store.set("alepha.server.request.user", data.user);
+			return data;
+		}
+		if (this.alepha.isBrowser()) {
+			const browser = this.alepha.inject(ReactBrowserProvider);
+			const redirect = options.redirect || (browser.transitioning ? window.location.origin + browser.transitioning.to : window.location.href);
+			const href = `${window.location.origin}${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${encodeURIComponent(redirect)}`;
+			if (browser.transitioning) throw new Redirection(href);
+			else {
+				window.location.href = href;
+				return {};
+			}
+		}
+		throw new Redirection(`${alephaServerAuthRoutes.login}?provider=${provider}${realmParam}&redirect_uri=${options.redirect || "/"}`);
+	}
+	logout() {
+		window.location.href = `${alephaServerAuthRoutes.logout}?post_logout_redirect_uri=${encodeURIComponent(window.location.origin)}`;
+	}
+};
+
+//#endregion
+//#region ../../src/react/auth/hooks/useAuth.ts
+const useAuth = () => {
+	const alepha = useAlepha();
+	const [user] = useStore("alepha.server.request.user");
+	return {
+		user,
+		logout: () => {
+			alepha.inject(ReactAuth).logout();
+		},
+		login: async (provider, options = {}) => {
+			await alepha.inject(ReactAuth).login(provider, options);
+		},
+		can: (name) => {
+			return alepha.inject(LinkProvider).can(name);
+		}
+	};
+};
+
+//#endregion
+//#region ../../src/react/auth/index.ts
+/**
+* | type | quality | stability |
+* |------|---------|-----------|
+* | frontend | rare | stable |
+*
+* Auth-related React components and hooks.
+*
+* **Features:**
+* - Login/logout components
+* - Protected route wrappers
+* - Auth state hooks
+*
+* @module alepha.react.auth
+*/
+const AlephaReactAuth = $module({
+	name: "alepha.react.auth",
+	primitives: [$auth],
+	services: [
+		AlephaReact,
+		AlephaServerLinks,
+		AlephaServerAuth,
+		ReactAuthProvider,
+		ReactAuth
+	]
+});
+
+//#endregion
+export { AlephaReactAuth, ReactAuth, ReactAuthProvider, useAuth };
+//# sourceMappingURL=index.js.map