alepha 0.22.0 → 0.24.0

package/dist/batch/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/batch/providers/BatchProvider.ts","../../src/batch/primitives/$batch.ts","../../src/batch/index.ts"],"sourcesContent":["import { $hook, $inject, type Alepha, AlephaError } from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { DateTimeProvider, type DurationLike } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { type RetryBackoffOptions, RetryProvider } from \"alepha/retry\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BatchOptions<TItem, TResponse = any> {\n  /**\n   * The batch processing handler function that processes arrays of validated items.\n   */\n  handler: (items: TItem[]) => TResponse;\n\n  /**\n   * Maximum number of items to collect before automatically flushing the batch.\n   *\n   * @default 10\n   */\n  maxSize?: number;\n\n  /**\n   * Maximum number of items that can be queued in a single partition.\n   * If exceeded, push() will throw an error.\n   */\n  maxQueueSize?: number;\n\n  /**\n   * Maximum time to wait before flushing a batch, even if it hasn't reached maxSize.\n   *\n   * @default [1, \"second\"]\n   */\n  maxDuration?: DurationLike;\n\n  /**\n   * Function to determine partition keys for grouping items into separate batches.\n   */\n  partitionBy?: (item: TItem) => string;\n\n  /**\n   * Maximum number of batch handlers that can execute simultaneously.\n   *\n   * @default 1\n   */\n  concurrency?: number;\n\n  /**\n   * Retry configuration for failed batch processing operations.\n   */\n  retry?: {\n    /**\n     * The maximum number of attempts.\n     *\n     * @default 3\n     */\n    max?: number;\n\n    /**\n     * The backoff strategy for delays between retries.\n     * Can be a fixed number (in ms) or a configuration object for exponential backoff.\n     *\n     * @default { initial: 200, factor: 2, jitter: true }\n     */\n    backoff?: number | RetryBackoffOptions;\n\n    /**\n     * An overall time limit for all retry attempts combined.\n     *\n     * e.g., `[5, 'seconds']`\n     */\n    maxDuration?: DurationLike;\n\n    /**\n     * A function that determines if a retry should be attempted based on the error.\n     *\n     * @default (error) => true (retries on any error)\n     */\n    when?: (error: Error) => boolean;\n\n    /**\n     * A custom callback for when a retry attempt fails.\n     * This is called before the delay.\n     */\n    onError?: (error: Error, attempt: number) => void;\n  };\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport type BatchItemStatus = \"pending\" | \"processing\" | \"completed\" | \"failed\";\n\nexport interface BatchItemState<TItem, TResponse> {\n  id: string;\n  item: TItem;\n  partitionKey: string;\n  status: BatchItemStatus;\n  result?: TResponse;\n  error?: Error;\n  promise?: Promise<TResponse>;\n  resolve?: (value: TResponse) => void;\n  reject?: (error: Error) => void;\n}\n\nexport interface PartitionState {\n  itemIds: string[];\n  timeout?: { clear: () => void };\n  flushing: boolean;\n}\n\n/**\n * Context object that holds all state for a batch processor instance.\n */\nexport interface BatchContext<TItem, TResponse> {\n  options: BatchOptions<TItem, TResponse>;\n  itemStates: Map<string, BatchItemState<TItem, TResponse>>;\n  partitions: Map<string, PartitionState>;\n  activeHandlers: PromiseWithResolvers<void>[];\n  isShuttingDown: boolean;\n  isReady: boolean;\n  alepha: Alepha;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Service for batch processing operations.\n * Provides methods to manage batches of items with automatic flushing based on size or time.\n */\nexport class BatchProvider {\n  protected readonly log = $logger();\n  protected readonly dateTime = $inject(DateTimeProvider);\n  protected readonly retryProvider = $inject(RetryProvider);\n  protected readonly crypto = $inject(CryptoProvider);\n\n  /**\n   * All active batch contexts managed by this provider.\n   */\n  protected readonly contexts = new Set<BatchContext<any, any>>();\n\n  /**\n   * Creates a new batch context with the given options.\n   */\n  createContext<TItem, TResponse>(\n    alepha: Alepha,\n    options: BatchOptions<TItem, TResponse>,\n  ): BatchContext<TItem, TResponse> {\n    const context: BatchContext<TItem, TResponse> = {\n      options,\n      itemStates: new Map(),\n      partitions: new Map(),\n      activeHandlers: [],\n      isShuttingDown: false,\n      isReady: false,\n      alepha,\n    };\n    this.contexts.add(context);\n    return context;\n  }\n\n  /**\n   * Shutdown hook - flushes all batch contexts on application stop.\n   */\n  protected readonly onStop = $hook({\n    on: \"stop\",\n    priority: \"first\",\n    handler: async () => {\n      if (this.contexts.size === 0) {\n        return;\n      }\n      this.log.debug(`Shutting down ${this.contexts.size} batch context(s)...`);\n      const promises: Promise<void>[] = [];\n      for (const context of this.contexts) {\n        promises.push(this.shutdown(context));\n      }\n      await Promise.all(promises);\n      this.log.debug(\"All batch contexts shut down\");\n    },\n  });\n\n  /**\n   * Get the effective maxSize for a context.\n   */\n  protected getMaxSize<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): number {\n    return context.options.maxSize ?? 10;\n  }\n\n  /**\n   * Get the effective concurrency for a context.\n   */\n  protected getConcurrency<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): number {\n    return context.options.concurrency ?? 1;\n  }\n\n  /**\n   * Get the effective maxDuration for a context.\n   */\n  protected getMaxDuration<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): DurationLike {\n    return context.options.maxDuration ?? [1, \"second\"];\n  }\n\n  /**\n   * Pushes an item into the batch and returns immediately with a unique ID.\n   * The item will be processed asynchronously with other items when the batch is flushed.\n   * Use wait(id) to get the processing result.\n   *\n   * @throws Error if maxQueueSize is exceeded\n   */\n  push<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    item: TItem,\n  ): string {\n    // 1. Generate unique ID\n    const id = this.crypto.randomUUID();\n\n    // 2. Determine the partition key (with error handling)\n    let partitionKey: string;\n    try {\n      partitionKey = context.options.partitionBy\n        ? context.options.partitionBy(item)\n        : \"default\";\n    } catch (error) {\n      this.log.warn(\n        \"partitionBy function threw an error, using 'default' partition\",\n        { error },\n      );\n      partitionKey = \"default\";\n    }\n\n    // 3. Create item state\n    const itemState: BatchItemState<TItem, TResponse> = {\n      id,\n      item,\n      partitionKey,\n      status: \"pending\",\n    };\n\n    // CAUTION: Do not log.debug/info here as it may cause infinite loops if logging is batched\n\n    context.itemStates.set(id, itemState);\n\n    // 4. Get or create the partition state\n    if (!context.partitions.has(partitionKey)) {\n      context.partitions.set(partitionKey, {\n        itemIds: [],\n        flushing: false,\n      });\n    }\n    const partition = context.partitions.get(partitionKey)!;\n\n    // 5. Check maxQueueSize before adding\n    if (\n      context.options.maxQueueSize !== undefined &&\n      partition.itemIds.length >= context.options.maxQueueSize\n    ) {\n      throw new AlephaError(\n        `Batch queue size exceeded for partition '${partitionKey}' (max: ${context.options.maxQueueSize})`,\n      );\n    }\n\n    // 6. Add item ID to partition\n    partition.itemIds.push(id);\n\n    const maxSize = this.getMaxSize(context);\n    const maxDuration = this.getMaxDuration(context);\n\n    // 7. Only start processing if the app is ready (after \"ready\" hook)\n    // During startup, items are just buffered in memory\n    if (context.isReady) {\n      // Check if the batch is full\n      if (partition.itemIds.length >= maxSize) {\n        this.log.trace(\n          `Batch partition '${partitionKey}' is full, flushing...`,\n        );\n        this.flushPartition(context, partitionKey).catch((error) =>\n          this.log.error(\n            `Failed to flush batch partition '${partitionKey}' on max size`,\n            error,\n          ),\n        );\n      } else if (!partition.timeout && !partition.flushing) {\n        // 8. Start the timeout if it's not already running for this partition and not currently flushing\n        partition.timeout = this.dateTime.createTimeout(() => {\n          this.log.trace(\n            `Batch partition '${partitionKey}' timed out, flushing...`,\n          );\n          this.flushPartition(context, partitionKey).catch((error) =>\n            this.log.error(\n              `Failed to flush batch partition '${partitionKey}' on timeout`,\n              error,\n            ),\n          );\n        }, maxDuration);\n      }\n    } else {\n      // Not ready yet - just buffer items, no size checks or timeouts\n      this.log.trace(\n        `Buffering item in partition '${partitionKey}' (app not ready yet, ${partition.itemIds.length} items buffered)`,\n      );\n    }\n\n    // 9. Return ID immediately\n    return id;\n  }\n\n  /**\n   * Wait for a specific item to be processed and get its result.\n   * @param id The item ID returned from push()\n   * @returns The processing result\n   * @throws If the item doesn't exist or processing failed\n   */\n  async wait<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    id: string,\n  ): Promise<TResponse> {\n    const itemState = context.itemStates.get(id);\n    if (!itemState) {\n      throw new AlephaError(`Item with id '${id}' not found`);\n    }\n\n    // If already completed or failed, return immediately\n    if (itemState.status === \"completed\") {\n      return itemState.result!;\n    }\n    if (itemState.status === \"failed\") {\n      throw itemState.error!;\n    }\n\n    // Create promise on-demand if not already created\n    if (!itemState.promise) {\n      itemState.promise = new Promise<TResponse>((resolve, reject) => {\n        itemState.resolve = resolve;\n        itemState.reject = reject;\n      });\n    }\n\n    return itemState.promise;\n  }\n\n  /**\n   * Get the current status of an item.\n   * @param id The item ID returned from push()\n   * @returns Status information or undefined if item doesn't exist\n   */\n  status<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    id: string,\n  ):\n    | { status: \"pending\" | \"processing\" }\n    | { status: \"completed\"; result: TResponse }\n    | { status: \"failed\"; error: Error }\n    | undefined {\n    const itemState = context.itemStates.get(id);\n    if (!itemState) {\n      return undefined;\n    }\n\n    if (itemState.status === \"completed\") {\n      return { status: \"completed\", result: itemState.result! };\n    }\n    if (itemState.status === \"failed\") {\n      return { status: \"failed\", error: itemState.error! };\n    }\n    return { status: itemState.status };\n  }\n\n  /**\n   * Clears completed and failed items from the context to free memory.\n   * Returns the number of items cleared.\n   *\n   * @param context The batch context\n   * @param status Optional: only clear items with this specific status ('completed' or 'failed')\n   * @returns The number of items cleared\n   */\n  clearCompleted<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    status?: \"completed\" | \"failed\",\n  ): number {\n    let count = 0;\n    for (const [id, state] of context.itemStates) {\n      if (status) {\n        if (state.status === status) {\n          context.itemStates.delete(id);\n          count++;\n        }\n      } else if (state.status === \"completed\" || state.status === \"failed\") {\n        context.itemStates.delete(id);\n        count++;\n      }\n    }\n    return count;\n  }\n\n  /**\n   * Flush all partitions or a specific partition.\n   */\n  async flush<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    partitionKey?: string,\n  ): Promise<void> {\n    const promises: Promise<void>[] = [];\n    if (partitionKey) {\n      if (context.partitions.has(partitionKey)) {\n        promises.push(this.flushPartition(context, partitionKey));\n      }\n    } else {\n      for (const key of context.partitions.keys()) {\n        promises.push(this.flushPartition(context, key));\n      }\n    }\n    await Promise.all(promises);\n  }\n\n  /**\n   * Flush a specific partition.\n   */\n  protected async flushPartition<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    partitionKey: string,\n    limit?: number,\n  ): Promise<void> {\n    const partition = context.partitions.get(partitionKey);\n    if (!partition || partition.itemIds.length === 0) {\n      context.partitions.delete(partitionKey);\n      return;\n    }\n\n    // Clear the timeout and grab the item IDs (up to limit if specified)\n    partition.timeout?.clear();\n    partition.timeout = undefined;\n    const itemsToTake =\n      limit !== undefined\n        ? Math.min(limit, partition.itemIds.length)\n        : partition.itemIds.length;\n    const itemIdsToProcess = partition.itemIds.splice(0, itemsToTake);\n\n    // Mark partition as flushing to prevent race conditions\n    partition.flushing = true;\n\n    // Get the items and mark them as processing\n    const itemsToProcess: TItem[] = [];\n    for (const id of itemIdsToProcess) {\n      const itemState = context.itemStates.get(id);\n      if (itemState) {\n        itemState.status = \"processing\";\n        itemsToProcess.push(itemState.item);\n      }\n    }\n\n    const concurrency = this.getConcurrency(context);\n    const maxDuration = this.getMaxDuration(context);\n\n    // Wait until there's a free slot (if at concurrency limit)\n    while (context.activeHandlers.length >= concurrency) {\n      this.log.trace(\n        `Batch handler is at concurrency limit, waiting for a slot...`,\n      );\n      // Wait for any single handler to complete, not all of them\n      await Promise.race(context.activeHandlers.map((it) => it.promise));\n    }\n\n    const promise = Promise.withResolvers<void>();\n    context.activeHandlers.push(promise);\n    let result: any;\n    try {\n      result = await context.alepha.context.run(() =>\n        // during shutdown, call handler directly to avoid retry cancellation\n        context.isShuttingDown\n          ? context.options.handler(itemsToProcess)\n          : this.retryProvider.retry(\n              {\n                ...context.options.retry,\n                handler: context.options.handler,\n              },\n              itemsToProcess,\n            ),\n      );\n\n      // Mark all items as completed and resolve their promises\n      for (const id of itemIdsToProcess) {\n        const itemState = context.itemStates.get(id);\n        if (itemState) {\n          itemState.status = \"completed\";\n          itemState.result = result;\n          // Only resolve if someone is waiting\n          itemState.resolve?.(result);\n        }\n      }\n    } catch (error) {\n      this.log.error(`Batch handler failed`, error);\n\n      // Mark all items as failed and reject their promises\n      for (const id of itemIdsToProcess) {\n        const itemState = context.itemStates.get(id);\n        if (itemState) {\n          itemState.status = \"failed\";\n          itemState.error = error as Error;\n          // Only reject if someone is waiting (promise was created)\n          itemState.reject?.(error as Error);\n        }\n      }\n    } finally {\n      promise.resolve();\n      context.activeHandlers = context.activeHandlers.filter(\n        (it) => it !== promise,\n      );\n\n      // Only delete partition if no new items arrived during processing\n      const currentPartition = context.partitions.get(partitionKey);\n      if (currentPartition?.flushing && currentPartition.itemIds.length === 0) {\n        context.partitions.delete(partitionKey);\n      } else if (currentPartition) {\n        // Reset flushing flag if partition still exists with items\n        currentPartition.flushing = false;\n\n        // Restart timeout for items that arrived during flush\n        if (currentPartition.itemIds.length > 0 && !currentPartition.timeout) {\n          currentPartition.timeout = this.dateTime.createTimeout(() => {\n            this.log.trace(\n              `Batch partition '${partitionKey}' timed out, flushing...`,\n            );\n            this.flushPartition(context, partitionKey).catch((error) =>\n              this.log.error(\n                `Failed to flush batch partition '${partitionKey}' on timeout`,\n                error,\n              ),\n            );\n          }, maxDuration);\n        }\n      }\n    }\n  }\n\n  /**\n   * Mark the context as ready and start processing buffered items.\n   * Called after the \"ready\" hook.\n   */\n  async markReady<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): Promise<void> {\n    this.log.debug(\n      \"Batch processor is now ready, starting to process buffered items...\",\n    );\n    context.isReady = true;\n    await this.startProcessing(context);\n  }\n\n  /**\n   * Mark the context as shutting down and flush all remaining items.\n   */\n  async shutdown<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): Promise<void> {\n    this.log.debug(\"Flushing all remaining batch partitions on shutdown...\");\n    context.isShuttingDown = true;\n    await this.flush(context);\n    this.log.debug(\"All batch partitions flushed\");\n  }\n\n  /**\n   * Called after the \"ready\" hook to start processing buffered items that were\n   * pushed during startup. This checks all partitions and starts timeouts/flushes\n   * for items that were accumulated before the app was ready.\n   */\n  protected async startProcessing<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): Promise<void> {\n    const maxSize = this.getMaxSize(context);\n    const maxDuration = this.getMaxDuration(context);\n\n    for (const [partitionKey, partition] of context.partitions.entries()) {\n      if (partition.itemIds.length === 0) {\n        continue;\n      }\n\n      this.log.trace(\n        `Starting processing for partition '${partitionKey}' with ${partition.itemIds.length} buffered items`,\n      );\n\n      // Flush batches of maxSize while we have items >= maxSize\n      while (partition.itemIds.length >= maxSize) {\n        this.log.trace(\n          `Partition '${partitionKey}' has ${partition.itemIds.length} items, flushing batch of ${maxSize}...`,\n        );\n        await this.flushPartition(context, partitionKey, maxSize);\n      }\n\n      // After flushing full batches, start timeout for any remaining items\n      if (\n        partition.itemIds.length > 0 &&\n        !partition.timeout &&\n        !partition.flushing\n      ) {\n        this.log.trace(\n          `Starting timeout for partition '${partitionKey}' with ${partition.itemIds.length} remaining items`,\n        );\n        partition.timeout = this.dateTime.createTimeout(() => {\n          this.log.trace(\n            `Batch partition '${partitionKey}' timed out, flushing...`,\n          );\n          this.flushPartition(context, partitionKey).catch((error) =>\n            this.log.error(\n              `Failed to flush partition '${partitionKey}' on timeout after startup`,\n              error,\n            ),\n          );\n        }, maxDuration);\n      }\n    }\n  }\n}\n","import {\n  $hook,\n  $inject,\n  createPrimitive,\n  KIND,\n  Primitive,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport type { DurationLike } from \"alepha/datetime\";\nimport type { RetryPrimitiveOptions } from \"alepha/retry\";\nimport {\n  type BatchContext,\n  type BatchItemState,\n  type BatchItemStatus,\n  BatchProvider,\n} from \"../providers/BatchProvider.ts\";\n\n/**\n * Creates a batch processing primitive for efficient grouping and processing of multiple operations.\n */\nexport const $batch = <TItem extends TSchema, TResponse>(\n  options: BatchPrimitiveOptions<TItem, TResponse>,\n): BatchPrimitive<TItem, TResponse> =>\n  createPrimitive(BatchPrimitive<TItem, TResponse>, options);\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BatchPrimitiveOptions<TItem extends TSchema, TResponse = any> {\n  /**\n   * TypeBox schema for validating each item added to the batch.\n   */\n  schema: TItem;\n\n  /**\n   * The batch processing handler function that processes arrays of validated items.\n   */\n  handler: (items: Static<TItem>[]) => TResponse;\n\n  /**\n   * Maximum number of items to collect before automatically flushing the batch.\n   */\n  maxSize?: number;\n\n  /**\n   * Maximum number of items that can be queued in a single partition.\n   * If exceeded, push() will throw an error.\n   */\n  maxQueueSize?: number;\n\n  /**\n   * Maximum time to wait before flushing a batch, even if it hasn't reached maxSize.\n   */\n  maxDuration?: DurationLike;\n\n  /**\n   * Function to determine partition keys for grouping items into separate batches.\n   */\n  partitionBy?: (item: Static<TItem>) => string;\n\n  /**\n   * Maximum number of batch handlers that can execute simultaneously.\n   */\n  concurrency?: number;\n\n  /**\n   * Retry configuration for failed batch processing operations.\n   */\n  retry?: Omit<RetryPrimitiveOptions<() => Array<Static<TItem>>>, \"handler\">;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport type { BatchItemState, BatchItemStatus };\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class BatchPrimitive<\n  TItem extends TSchema,\n  TResponse = any,\n> extends Primitive<BatchPrimitiveOptions<TItem, TResponse>> {\n  protected readonly batchProvider = $inject(BatchProvider);\n  protected readonly context: BatchContext<Static<TItem>, TResponse>;\n\n  constructor(\n    ...args: ConstructorParameters<\n      typeof Primitive<BatchPrimitiveOptions<TItem, TResponse>>\n    >\n  ) {\n    super(...args);\n    this.context = this.batchProvider.createContext(this.alepha, {\n      handler: this.options.handler,\n      maxSize: this.options.maxSize,\n      maxQueueSize: this.options.maxQueueSize,\n      maxDuration: this.options.maxDuration,\n      partitionBy: this.options.partitionBy,\n      concurrency: this.options.concurrency,\n      retry: this.options.retry,\n    });\n  }\n\n  /**\n   * Pushes an item into the batch and returns immediately with a unique ID.\n   * The item will be processed asynchronously with other items when the batch is flushed.\n   * Use wait(id) to get the processing result.\n   */\n  public async push(item: Static<TItem>): Promise<string> {\n    // Validate the item against the schema\n    const validatedItem = this.alepha.codec.validate(this.options.schema, item);\n    return this.batchProvider.push(this.context, validatedItem);\n  }\n\n  /**\n   * Wait for a specific item to be processed and get its result.\n   * @param id The item ID returned from push()\n   * @returns The processing result\n   * @throws If the item doesn't exist or processing failed\n   */\n  public async wait(id: string): Promise<TResponse> {\n    return this.batchProvider.wait(this.context, id);\n  }\n\n  /**\n   * Get the current status of an item.\n   * @param id The item ID returned from push()\n   * @returns Status information or undefined if item doesn't exist\n   */\n  public status(\n    id: string,\n  ):\n    | { status: \"pending\" | \"processing\" }\n    | { status: \"completed\"; result: TResponse }\n    | { status: \"failed\"; error: Error }\n    | undefined {\n    return this.batchProvider.status(this.context, id);\n  }\n\n  /**\n   * Flush all partitions or a specific partition.\n   */\n  public async flush(partitionKey?: string): Promise<void> {\n    return this.batchProvider.flush(this.context, partitionKey);\n  }\n\n  /**\n   * Clears completed and failed items from memory.\n   * Call this periodically in long-running applications to prevent memory leaks.\n   *\n   * @param status Optional: only clear items with this specific status ('completed' or 'failed')\n   * @returns The number of items cleared\n   */\n  public clearCompleted(status?: \"completed\" | \"failed\"): number {\n    return this.batchProvider.clearCompleted(this.context, status);\n  }\n\n  protected readonly onReady = $hook({\n    on: \"ready\",\n    handler: async () => {\n      await this.batchProvider.markReady(this.context);\n    },\n  });\n}\n\n$batch[KIND] = BatchPrimitive;\n","import { $module } from \"alepha\";\nimport { $batch } from \"./primitives/$batch.ts\";\nimport { BatchProvider } from \"./providers/BatchProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$batch.ts\";\nexport * from \"./providers/BatchProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Batch accumulation and processing.\n *\n * **Features:**\n * - Batch accumulator with handler\n * - Configurable batch size\n * - Time-based triggers\n * - Status tracking\n *\n * @module alepha.batch\n */\nexport const AlephaBatch = $module({\n  name: \"alepha.batch\",\n  primitives: [$batch],\n  services: [BatchProvider],\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/batch/providers/BatchProvider.ts","../../src/batch/primitives/$batch.ts","../../src/batch/index.ts"],"sourcesContent":["import { $hook, $inject, type Alepha, AlephaError } from \"alepha\";\nimport { CryptoProvider } from \"alepha/crypto\";\nimport { DateTimeProvider, type DurationLike } from \"alepha/datetime\";\nimport { $logger } from \"alepha/logger\";\nimport { type RetryBackoffOptions, RetryProvider } from \"alepha/retry\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BatchOptions<TItem, TResponse = any> {\n  /**\n   * The batch processing handler function that processes arrays of validated items.\n   */\n  handler: (items: TItem[]) => TResponse;\n\n  /**\n   * Maximum number of items to collect before automatically flushing the batch.\n   *\n   * @default 10\n   */\n  maxSize?: number;\n\n  /**\n   * Maximum number of items that can be queued in a single partition.\n   * If exceeded, push() will throw an error.\n   */\n  maxQueueSize?: number;\n\n  /**\n   * Maximum time to wait before flushing a batch, even if it hasn't reached maxSize.\n   *\n   * @default [1, \"second\"]\n   */\n  maxDuration?: DurationLike;\n\n  /**\n   * Function to determine partition keys for grouping items into separate batches.\n   */\n  partitionBy?: (item: TItem) => string;\n\n  /**\n   * Maximum number of batch handlers that can execute simultaneously.\n   *\n   * @default 1\n   */\n  concurrency?: number;\n\n  /**\n   * Retry configuration for failed batch processing operations.\n   */\n  retry?: {\n    /**\n     * The maximum number of attempts.\n     *\n     * @default 3\n     */\n    max?: number;\n\n    /**\n     * The backoff strategy for delays between retries.\n     * Can be a fixed number (in ms) or a configuration object for exponential backoff.\n     *\n     * @default { initial: 200, factor: 2, jitter: true }\n     */\n    backoff?: number | RetryBackoffOptions;\n\n    /**\n     * An overall time limit for all retry attempts combined.\n     *\n     * e.g., `[5, 'seconds']`\n     */\n    maxDuration?: DurationLike;\n\n    /**\n     * A function that determines if a retry should be attempted based on the error.\n     *\n     * @default (error) => true (retries on any error)\n     */\n    when?: (error: Error) => boolean;\n\n    /**\n     * A custom callback for when a retry attempt fails.\n     * This is called before the delay.\n     */\n    onError?: (error: Error, attempt: number) => void;\n  };\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport type BatchItemStatus = \"pending\" | \"processing\" | \"completed\" | \"failed\";\n\nexport interface BatchItemState<TItem, TResponse> {\n  id: string;\n  item: TItem;\n  partitionKey: string;\n  status: BatchItemStatus;\n  result?: TResponse;\n  error?: Error;\n  promise?: Promise<TResponse>;\n  resolve?: (value: TResponse) => void;\n  reject?: (error: Error) => void;\n}\n\nexport interface PartitionState {\n  itemIds: string[];\n  timeout?: { clear: () => void };\n  flushing: boolean;\n}\n\n/**\n * Context object that holds all state for a batch processor instance.\n */\nexport interface BatchContext<TItem, TResponse> {\n  options: BatchOptions<TItem, TResponse>;\n  itemStates: Map<string, BatchItemState<TItem, TResponse>>;\n  partitions: Map<string, PartitionState>;\n  activeHandlers: PromiseWithResolvers<void>[];\n  isShuttingDown: boolean;\n  isReady: boolean;\n  alepha: Alepha;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Service for batch processing operations.\n * Provides methods to manage batches of items with automatic flushing based on size or time.\n */\nexport class BatchProvider {\n  protected readonly log = $logger();\n  protected readonly dateTime = $inject(DateTimeProvider);\n  protected readonly retryProvider = $inject(RetryProvider);\n  protected readonly crypto = $inject(CryptoProvider);\n\n  /**\n   * All active batch contexts managed by this provider.\n   */\n  protected readonly contexts = new Set<BatchContext<any, any>>();\n\n  /**\n   * Creates a new batch context with the given options.\n   */\n  createContext<TItem, TResponse>(\n    alepha: Alepha,\n    options: BatchOptions<TItem, TResponse>,\n  ): BatchContext<TItem, TResponse> {\n    const context: BatchContext<TItem, TResponse> = {\n      options,\n      itemStates: new Map(),\n      partitions: new Map(),\n      activeHandlers: [],\n      isShuttingDown: false,\n      isReady: false,\n      alepha,\n    };\n    this.contexts.add(context);\n    return context;\n  }\n\n  /**\n   * Shutdown hook - flushes all batch contexts on application stop.\n   */\n  protected readonly onStop = $hook({\n    on: \"stop\",\n    priority: \"first\",\n    handler: async () => {\n      if (this.contexts.size === 0) {\n        return;\n      }\n      this.log.debug(`Shutting down ${this.contexts.size} batch context(s)...`);\n      const promises: Promise<void>[] = [];\n      for (const context of this.contexts) {\n        promises.push(this.shutdown(context));\n      }\n      await Promise.all(promises);\n      this.log.debug(\"All batch contexts shut down\");\n    },\n  });\n\n  /**\n   * Get the effective maxSize for a context.\n   */\n  protected getMaxSize<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): number {\n    return context.options.maxSize ?? 10;\n  }\n\n  /**\n   * Get the effective concurrency for a context.\n   */\n  protected getConcurrency<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): number {\n    return context.options.concurrency ?? 1;\n  }\n\n  /**\n   * Get the effective maxDuration for a context.\n   */\n  protected getMaxDuration<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): DurationLike {\n    return context.options.maxDuration ?? [1, \"second\"];\n  }\n\n  /**\n   * Pushes an item into the batch and returns immediately with a unique ID.\n   * The item will be processed asynchronously with other items when the batch is flushed.\n   * Use wait(id) to get the processing result.\n   *\n   * @throws Error if maxQueueSize is exceeded\n   */\n  push<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    item: TItem,\n  ): string {\n    // 1. Generate unique ID\n    const id = this.crypto.randomUUID();\n\n    // 2. Determine the partition key (with error handling)\n    let partitionKey: string;\n    try {\n      partitionKey = context.options.partitionBy\n        ? context.options.partitionBy(item)\n        : \"default\";\n    } catch (error) {\n      this.log.warn(\n        \"partitionBy function threw an error, using 'default' partition\",\n        { error },\n      );\n      partitionKey = \"default\";\n    }\n\n    // 3. Create item state\n    const itemState: BatchItemState<TItem, TResponse> = {\n      id,\n      item,\n      partitionKey,\n      status: \"pending\",\n    };\n\n    // CAUTION: Do not log.debug/info here as it may cause infinite loops if logging is batched\n\n    context.itemStates.set(id, itemState);\n\n    // 4. Get or create the partition state\n    if (!context.partitions.has(partitionKey)) {\n      context.partitions.set(partitionKey, {\n        itemIds: [],\n        flushing: false,\n      });\n    }\n    const partition = context.partitions.get(partitionKey)!;\n\n    // 5. Check maxQueueSize before adding\n    if (\n      context.options.maxQueueSize !== undefined &&\n      partition.itemIds.length >= context.options.maxQueueSize\n    ) {\n      throw new AlephaError(\n        `Batch queue size exceeded for partition '${partitionKey}' (max: ${context.options.maxQueueSize})`,\n      );\n    }\n\n    // 6. Add item ID to partition\n    partition.itemIds.push(id);\n\n    const maxSize = this.getMaxSize(context);\n    const maxDuration = this.getMaxDuration(context);\n\n    // 7. Only start processing if the app is ready (after \"ready\" hook)\n    // During startup, items are just buffered in memory\n    if (context.isReady) {\n      // Check if the batch is full\n      if (partition.itemIds.length >= maxSize) {\n        this.log.trace(\n          `Batch partition '${partitionKey}' is full, flushing...`,\n        );\n        this.flushPartition(context, partitionKey).catch((error) =>\n          this.log.error(\n            `Failed to flush batch partition '${partitionKey}' on max size`,\n            error,\n          ),\n        );\n      } else if (!partition.timeout && !partition.flushing) {\n        // 8. Start the timeout if it's not already running for this partition and not currently flushing\n        partition.timeout = this.dateTime.createTimeout(() => {\n          this.log.trace(\n            `Batch partition '${partitionKey}' timed out, flushing...`,\n          );\n          this.flushPartition(context, partitionKey).catch((error) =>\n            this.log.error(\n              `Failed to flush batch partition '${partitionKey}' on timeout`,\n              error,\n            ),\n          );\n        }, maxDuration);\n      }\n    } else {\n      // Not ready yet - just buffer items, no size checks or timeouts\n      this.log.trace(\n        `Buffering item in partition '${partitionKey}' (app not ready yet, ${partition.itemIds.length} items buffered)`,\n      );\n    }\n\n    // 9. Return ID immediately\n    return id;\n  }\n\n  /**\n   * Wait for a specific item to be processed and get its result.\n   * @param id The item ID returned from push()\n   * @returns The processing result\n   * @throws If the item doesn't exist or processing failed\n   */\n  async wait<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    id: string,\n  ): Promise<TResponse> {\n    const itemState = context.itemStates.get(id);\n    if (!itemState) {\n      throw new AlephaError(`Item with id '${id}' not found`);\n    }\n\n    // If already completed or failed, return immediately\n    if (itemState.status === \"completed\") {\n      return itemState.result!;\n    }\n    if (itemState.status === \"failed\") {\n      throw itemState.error!;\n    }\n\n    // Create promise on-demand if not already created\n    if (!itemState.promise) {\n      itemState.promise = new Promise<TResponse>((resolve, reject) => {\n        itemState.resolve = resolve;\n        itemState.reject = reject;\n      });\n    }\n\n    return itemState.promise;\n  }\n\n  /**\n   * Get the current status of an item.\n   * @param id The item ID returned from push()\n   * @returns Status information or undefined if item doesn't exist\n   */\n  status<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    id: string,\n  ):\n    | { status: \"pending\" | \"processing\" }\n    | { status: \"completed\"; result: TResponse }\n    | { status: \"failed\"; error: Error }\n    | undefined {\n    const itemState = context.itemStates.get(id);\n    if (!itemState) {\n      return undefined;\n    }\n\n    if (itemState.status === \"completed\") {\n      return { status: \"completed\", result: itemState.result! };\n    }\n    if (itemState.status === \"failed\") {\n      return { status: \"failed\", error: itemState.error! };\n    }\n    return { status: itemState.status };\n  }\n\n  /**\n   * Clears completed and failed items from the context to free memory.\n   * Returns the number of items cleared.\n   *\n   * @param context The batch context\n   * @param status Optional: only clear items with this specific status ('completed' or 'failed')\n   * @returns The number of items cleared\n   */\n  clearCompleted<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    status?: \"completed\" | \"failed\",\n  ): number {\n    let count = 0;\n    for (const [id, state] of context.itemStates) {\n      if (status) {\n        if (state.status === status) {\n          context.itemStates.delete(id);\n          count++;\n        }\n      } else if (state.status === \"completed\" || state.status === \"failed\") {\n        context.itemStates.delete(id);\n        count++;\n      }\n    }\n    return count;\n  }\n\n  /**\n   * Flush all partitions or a specific partition.\n   */\n  async flush<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    partitionKey?: string,\n  ): Promise<void> {\n    const promises: Promise<void>[] = [];\n    if (partitionKey) {\n      if (context.partitions.has(partitionKey)) {\n        promises.push(this.flushPartition(context, partitionKey));\n      }\n    } else {\n      for (const key of context.partitions.keys()) {\n        promises.push(this.flushPartition(context, key));\n      }\n    }\n    await Promise.all(promises);\n  }\n\n  /**\n   * Flush a specific partition.\n   */\n  protected async flushPartition<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n    partitionKey: string,\n    limit?: number,\n  ): Promise<void> {\n    const partition = context.partitions.get(partitionKey);\n    if (!partition || partition.itemIds.length === 0) {\n      context.partitions.delete(partitionKey);\n      return;\n    }\n\n    // Clear the timeout and grab the item IDs (up to limit if specified)\n    partition.timeout?.clear();\n    partition.timeout = undefined;\n    const itemsToTake =\n      limit !== undefined\n        ? Math.min(limit, partition.itemIds.length)\n        : partition.itemIds.length;\n    const itemIdsToProcess = partition.itemIds.splice(0, itemsToTake);\n\n    // Mark partition as flushing to prevent race conditions\n    partition.flushing = true;\n\n    // Get the items and mark them as processing\n    const itemsToProcess: TItem[] = [];\n    for (const id of itemIdsToProcess) {\n      const itemState = context.itemStates.get(id);\n      if (itemState) {\n        itemState.status = \"processing\";\n        itemsToProcess.push(itemState.item);\n      }\n    }\n\n    const concurrency = this.getConcurrency(context);\n    const maxDuration = this.getMaxDuration(context);\n\n    // Wait until there's a free slot (if at concurrency limit)\n    while (context.activeHandlers.length >= concurrency) {\n      this.log.trace(\n        `Batch handler is at concurrency limit, waiting for a slot...`,\n      );\n      // Wait for any single handler to complete, not all of them\n      await Promise.race(context.activeHandlers.map((it) => it.promise));\n    }\n\n    const promise = Promise.withResolvers<void>();\n    context.activeHandlers.push(promise);\n    let result: any;\n    try {\n      result = await context.alepha.context.run(() =>\n        // during shutdown, call handler directly to avoid retry cancellation\n        context.isShuttingDown\n          ? context.options.handler(itemsToProcess)\n          : this.retryProvider.retry(\n              {\n                ...context.options.retry,\n                handler: context.options.handler,\n              },\n              itemsToProcess,\n            ),\n      );\n\n      // Mark all items as completed and resolve their promises\n      for (const id of itemIdsToProcess) {\n        const itemState = context.itemStates.get(id);\n        if (itemState) {\n          itemState.status = \"completed\";\n          itemState.result = result;\n          // Only resolve if someone is waiting\n          itemState.resolve?.(result);\n        }\n      }\n    } catch (error) {\n      this.log.error(`Batch handler failed`, error);\n\n      // Mark all items as failed and reject their promises\n      for (const id of itemIdsToProcess) {\n        const itemState = context.itemStates.get(id);\n        if (itemState) {\n          itemState.status = \"failed\";\n          itemState.error = error as Error;\n          // Only reject if someone is waiting (promise was created)\n          itemState.reject?.(error as Error);\n        }\n      }\n    } finally {\n      promise.resolve();\n      context.activeHandlers = context.activeHandlers.filter(\n        (it) => it !== promise,\n      );\n\n      // Only delete partition if no new items arrived during processing\n      const currentPartition = context.partitions.get(partitionKey);\n      if (currentPartition?.flushing && currentPartition.itemIds.length === 0) {\n        context.partitions.delete(partitionKey);\n      } else if (currentPartition) {\n        // Reset flushing flag if partition still exists with items\n        currentPartition.flushing = false;\n\n        // Restart timeout for items that arrived during flush\n        if (currentPartition.itemIds.length > 0 && !currentPartition.timeout) {\n          currentPartition.timeout = this.dateTime.createTimeout(() => {\n            this.log.trace(\n              `Batch partition '${partitionKey}' timed out, flushing...`,\n            );\n            this.flushPartition(context, partitionKey).catch((error) =>\n              this.log.error(\n                `Failed to flush batch partition '${partitionKey}' on timeout`,\n                error,\n              ),\n            );\n          }, maxDuration);\n        }\n      }\n    }\n  }\n\n  /**\n   * Mark the context as ready and start processing buffered items.\n   * Called after the \"ready\" hook.\n   */\n  async markReady<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): Promise<void> {\n    this.log.debug(\n      \"Batch processor is now ready, starting to process buffered items...\",\n    );\n    context.isReady = true;\n    await this.startProcessing(context);\n  }\n\n  /**\n   * Mark the context as shutting down and flush all remaining items.\n   */\n  async shutdown<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): Promise<void> {\n    this.log.debug(\"Flushing all remaining batch partitions on shutdown...\");\n    context.isShuttingDown = true;\n    await this.flush(context);\n    this.log.debug(\"All batch partitions flushed\");\n  }\n\n  /**\n   * Called after the \"ready\" hook to start processing buffered items that were\n   * pushed during startup. This checks all partitions and starts timeouts/flushes\n   * for items that were accumulated before the app was ready.\n   */\n  protected async startProcessing<TItem, TResponse>(\n    context: BatchContext<TItem, TResponse>,\n  ): Promise<void> {\n    const maxSize = this.getMaxSize(context);\n    const maxDuration = this.getMaxDuration(context);\n\n    for (const [partitionKey, partition] of context.partitions.entries()) {\n      if (partition.itemIds.length === 0) {\n        continue;\n      }\n\n      this.log.trace(\n        `Starting processing for partition '${partitionKey}' with ${partition.itemIds.length} buffered items`,\n      );\n\n      // Flush batches of maxSize while we have items >= maxSize\n      while (partition.itemIds.length >= maxSize) {\n        this.log.trace(\n          `Partition '${partitionKey}' has ${partition.itemIds.length} items, flushing batch of ${maxSize}...`,\n        );\n        await this.flushPartition(context, partitionKey, maxSize);\n      }\n\n      // After flushing full batches, start timeout for any remaining items\n      if (\n        partition.itemIds.length > 0 &&\n        !partition.timeout &&\n        !partition.flushing\n      ) {\n        this.log.trace(\n          `Starting timeout for partition '${partitionKey}' with ${partition.itemIds.length} remaining items`,\n        );\n        partition.timeout = this.dateTime.createTimeout(() => {\n          this.log.trace(\n            `Batch partition '${partitionKey}' timed out, flushing...`,\n          );\n          this.flushPartition(context, partitionKey).catch((error) =>\n            this.log.error(\n              `Failed to flush partition '${partitionKey}' on timeout after startup`,\n              error,\n            ),\n          );\n        }, maxDuration);\n      }\n    }\n  }\n}\n","import {\n  $hook,\n  $inject,\n  createPrimitive,\n  KIND,\n  Primitive,\n  type Static,\n  type TSchema,\n} from \"alepha\";\nimport type { DurationLike } from \"alepha/datetime\";\nimport type { RetryPrimitiveOptions } from \"alepha/retry\";\nimport {\n  type BatchContext,\n  type BatchItemState,\n  type BatchItemStatus,\n  BatchProvider,\n} from \"../providers/BatchProvider.ts\";\n\n/**\n * Creates a batch processing primitive for efficient grouping and processing of multiple operations.\n */\nexport const $batch = <TItem extends TSchema, TResponse>(\n  options: BatchPrimitiveOptions<TItem, TResponse>,\n): BatchPrimitive<TItem, TResponse> =>\n  createPrimitive(BatchPrimitive<TItem, TResponse>, options);\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport interface BatchPrimitiveOptions<TItem extends TSchema, TResponse = any> {\n  /**\n   * TypeBox schema for validating each item added to the batch.\n   */\n  schema: TItem;\n\n  /**\n   * The batch processing handler function that processes arrays of validated items.\n   */\n  handler: (items: Static<TItem>[]) => TResponse;\n\n  /**\n   * Maximum number of items to collect before automatically flushing the batch.\n   */\n  maxSize?: number;\n\n  /**\n   * Maximum number of items that can be queued in a single partition.\n   * If exceeded, push() will throw an error.\n   */\n  maxQueueSize?: number;\n\n  /**\n   * Maximum time to wait before flushing a batch, even if it hasn't reached maxSize.\n   */\n  maxDuration?: DurationLike;\n\n  /**\n   * Function to determine partition keys for grouping items into separate batches.\n   */\n  partitionBy?: (item: Static<TItem>) => string;\n\n  /**\n   * Maximum number of batch handlers that can execute simultaneously.\n   */\n  concurrency?: number;\n\n  /**\n   * Retry configuration for failed batch processing operations.\n   */\n  retry?: Omit<RetryPrimitiveOptions<() => Array<Static<TItem>>>, \"handler\">;\n}\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport type { BatchItemState, BatchItemStatus };\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport class BatchPrimitive<\n  TItem extends TSchema,\n  TResponse = any,\n> extends Primitive<BatchPrimitiveOptions<TItem, TResponse>> {\n  protected readonly batchProvider = $inject(BatchProvider);\n  protected readonly context: BatchContext<Static<TItem>, TResponse>;\n\n  constructor(\n    ...args: ConstructorParameters<\n      typeof Primitive<BatchPrimitiveOptions<TItem, TResponse>>\n    >\n  ) {\n    super(...args);\n    this.context = this.batchProvider.createContext(this.alepha, {\n      handler: this.options.handler,\n      maxSize: this.options.maxSize,\n      maxQueueSize: this.options.maxQueueSize,\n      maxDuration: this.options.maxDuration,\n      partitionBy: this.options.partitionBy,\n      concurrency: this.options.concurrency,\n      retry: this.options.retry,\n    });\n  }\n\n  /**\n   * Pushes an item into the batch and returns immediately with a unique ID.\n   * The item will be processed asynchronously with other items when the batch is flushed.\n   * Use wait(id) to get the processing result.\n   */\n  public async push(item: Static<TItem>): Promise<string> {\n    // Validate the item against the schema\n    const validatedItem = this.alepha.codec.validate(this.options.schema, item);\n    return this.batchProvider.push(this.context, validatedItem);\n  }\n\n  /**\n   * Wait for a specific item to be processed and get its result.\n   * @param id The item ID returned from push()\n   * @returns The processing result\n   * @throws If the item doesn't exist or processing failed\n   */\n  public async wait(id: string): Promise<TResponse> {\n    return this.batchProvider.wait(this.context, id);\n  }\n\n  /**\n   * Get the current status of an item.\n   * @param id The item ID returned from push()\n   * @returns Status information or undefined if item doesn't exist\n   */\n  public status(\n    id: string,\n  ):\n    | { status: \"pending\" | \"processing\" }\n    | { status: \"completed\"; result: TResponse }\n    | { status: \"failed\"; error: Error }\n    | undefined {\n    return this.batchProvider.status(this.context, id);\n  }\n\n  /**\n   * Flush all partitions or a specific partition.\n   */\n  public async flush(partitionKey?: string): Promise<void> {\n    return this.batchProvider.flush(this.context, partitionKey);\n  }\n\n  /**\n   * Clears completed and failed items from memory.\n   * Call this periodically in long-running applications to prevent memory leaks.\n   *\n   * @param status Optional: only clear items with this specific status ('completed' or 'failed')\n   * @returns The number of items cleared\n   */\n  public clearCompleted(status?: \"completed\" | \"failed\"): number {\n    return this.batchProvider.clearCompleted(this.context, status);\n  }\n\n  protected readonly onReady = $hook({\n    on: \"ready\",\n    handler: async () => {\n      await this.batchProvider.markReady(this.context);\n    },\n  });\n}\n\n$batch[KIND] = BatchPrimitive;\n","import { $module } from \"alepha\";\nimport { $batch } from \"./primitives/$batch.ts\";\nimport { BatchProvider } from \"./providers/BatchProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\nexport * from \"./primitives/$batch.ts\";\nexport * from \"./providers/BatchProvider.ts\";\n\n// ---------------------------------------------------------------------------------------------------------------------\n\n/**\n * Batch accumulation and processing.\n *\n * **Features:**\n * - Batch accumulator with handler\n * - Configurable batch size\n * - Time-based triggers\n * - Status tracking\n *\n * @module alepha.batch\n */\nexport const AlephaBatch = $module({\n  name: \"alepha.batch\",\n  primitives: [$batch],\n  services: [BatchProvider],\n});\n"],"mappings":"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"}

package/dist/bin/index.js

@@ -6,7 +6,7 @@ const alepha = Alepha.create({ env: {
 	APP_NAME: "CLI",
 	CLI_NAME: "alepha",
 	CLI_DESCRIPTION: `Alepha CLI v${version} - Create and manage Alepha projects.`,
-	LOG_FORMAT: process.env.LOG_FORMAT ?? "raw",
+	LOG_FORMAT: process.env.LOG_FORMAT ?? "cli",
 	LOG_LEVEL: process.env.LOG_LEVEL ?? "alepha.core:warn,info"
 } });
 alepha.with(AlephaCli);

package/dist/bin/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/bin/index.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { Alepha, run } from \"alepha\";\nimport { AlephaCli, version } from \"alepha/cli\";\n\nconst alepha = Alepha.create({\n  env: {\n    APP_NAME: \"CLI\",\n    CLI_NAME: \"alepha\",\n    CLI_DESCRIPTION: `Alepha CLI v${version} - Create and manage Alepha projects.`,\n    LOG_FORMAT: (process.env.LOG_FORMAT ?? \"raw\") as any,\n    LOG_LEVEL: process.env.LOG_LEVEL ?? \"alepha.core:warn,info\",\n  },\n});\n\nalepha.with(AlephaCli);\n\nrun(alepha);\n"],"mappings":";;;;AAIA,MAAM,SAAS,OAAO,OAAO,EAC3B,KAAK;CACH,UAAU;CACV,UAAU;CACV,iBAAiB,eAAe,QAAQ;CACxC,YAAa,QAAQ,IAAI,cAAc;CACvC,WAAW,QAAQ,IAAI,aAAa;AACtC,EACF,CAAC;AAED,OAAO,KAAK,SAAS;AAErB,IAAI,MAAM"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/bin/index.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { Alepha, run } from \"alepha\";\nimport { AlephaCli, version } from \"alepha/cli\";\n\nconst alepha = Alepha.create({\n  env: {\n    APP_NAME: \"CLI\",\n    CLI_NAME: \"alepha\",\n    CLI_DESCRIPTION: `Alepha CLI v${version} - Create and manage Alepha projects.`,\n    LOG_FORMAT: (process.env.LOG_FORMAT ?? \"cli\") as any,\n    LOG_LEVEL: process.env.LOG_LEVEL ?? \"alepha.core:warn,info\",\n  },\n});\n\nalepha.with(AlephaCli);\n\nrun(alepha);\n"],"mappings":";;;;AAIA,MAAM,SAAS,OAAO,OAAO,EAC3B,KAAK;CACH,UAAU;CACV,UAAU;CACV,iBAAiB,eAAe,QAAQ;CACxC,YAAa,QAAQ,IAAI,cAAc;CACvC,WAAW,QAAQ,IAAI,aAAa;AACtC,EACF,CAAC;AAED,OAAO,KAAK,SAAS;AAErB,IAAI,MAAM"}

package/dist/bucket/index.d.ts

@@ -4,7 +4,6 @@ import { CryptoProvider } from "alepha/crypto";
 import * as fs from "node:fs";
 import { S3mini } from "s3mini";
 import { R2Bucket } from "@cloudflare/workers-types";
-
 //#region ../../src/bucket/providers/FileStorageProvider.d.ts
 declare abstract class FileStorageProvider {
   /**
@@ -70,6 +69,7 @@ interface StoredFile {
 }
 declare class MemoryFileStorageProvider implements FileStorageProvider {
   readonly files: Record<string, StoredFile>;
+  protected readonly alepha: Alepha;
   protected readonly fileSystem: FileSystemProvider;
   protected readonly fileDetector: FileDetector;
   protected readonly crypto: CryptoProvider;
@@ -79,6 +79,11 @@ declare class MemoryFileStorageProvider implements FileStorageProvider {
   delete(bucketName: string, fileId: string): Promise<void>;
   deleteMany(bucketName: string, fileIds: string[]): Promise<void>;
   list(bucketName: string): Promise<string[]>;
+  /**
+   * In-memory key, tenant-scoped when a tenant is active (`currentTenantAtom`),
+   * mirroring the R2/Local/S3 layout: `{tenantId}/{bucket}/{fileId}`.
+   */
+  protected key(bucket: string, fileId?: string): string;
   protected createId(): string;
 }
 //#endregion
@@ -331,9 +336,9 @@ declare class FileNotFoundError extends AlephaError {
 /**
  * Local file storage configuration atom
  */
-declare const localFileStorageOptions: import("alepha").Atom<import("typebox").TObject<{
-  storagePath: import("typebox").TString;
-}>, "alepha.bucket.local.options">;
+declare const localFileStorageOptions: import("alepha").Atom<import("zod").ZodObject<{
+  storagePath: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "alepha.bucket.local.options">;
 type LocalFileStorageProviderOptions = Static<typeof localFileStorageOptions.schema>;
 declare module "alepha" {
   interface State {
@@ -435,7 +440,12 @@ declare class R2FileStorageProvider implements FileStorageProvider {
   deleteMany(bucketName: string, fileIds: string[]): Promise<void>;
   list(bucketName: string): Promise<string[]>;
   /**
-   * Build the full R2 key: {prefix}/{bucketName}/{fileId}
+   * Build the full R2 key: {prefix}/{tenantId}/{bucketName}/{fileId}
+   *
+   * When a tenant is active on the current request/job (`currentTenantAtom`),
+   * its id is inserted as a directory so a pooled multi-tenant worker keeps
+   * each tenant's objects isolated. No tenant → the historical
+   * `{prefix}/{bucketName}/{fileId}` layout is unchanged.
    */
   protected key(bucketName: string, fileId: string): string;
   protected getR2(): R2Bucket;
@@ -443,32 +453,12 @@ declare class R2FileStorageProvider implements FileStorageProvider {
 }
 //#endregion
 //#region ../../src/bucket/providers/S3FileStorageProvider.d.ts
-declare const envSchema: import("alepha").TObject<{
-  /**
-   * S3 endpoint URL. The bucket name is appended (path-style) per request.
-   *
-   * Examples:
-   * - AWS S3: `https://s3.us-east-1.amazonaws.com`
-   * - Cloudflare R2: `https://<account-id>.r2.cloudflarestorage.com`
-   * - MinIO: `http://localhost:9000`
-   * - DigitalOcean Spaces: `https://<region>.digitaloceanspaces.com`
-   */
-  S3_ENDPOINT: import("alepha").TString;
-  /**
-   * AWS region or "auto" for R2.
-   *
-   * @default "auto"
-   */
-  S3_REGION: import("alepha").TOptional<import("alepha").TString>;
-  /**
-   * Access key ID for S3 authentication.
-   */
-  S3_ACCESS_KEY_ID: import("alepha").TString;
-  /**
-   * Secret access key for S3 authentication.
-   */
-  S3_SECRET_ACCESS_KEY: import("alepha").TString;
-}>;
+declare const envSchema: import("zod").ZodObject<{
+  S3_ENDPOINT: import("zod").ZodString;
+  S3_REGION: import("zod").ZodOptional<import("zod").ZodString>;
+  S3_ACCESS_KEY_ID: import("zod").ZodString;
+  S3_SECRET_ACCESS_KEY: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
 }
@@ -483,8 +473,8 @@ declare module "alepha" {
 declare class S3FileStorageProvider implements FileStorageProvider {
   protected readonly log: import("alepha/logger").Logger;
   protected readonly env: {
-    S3_REGION?: string | undefined;
     S3_ENDPOINT: string;
+    S3_REGION?: string | undefined;
     S3_ACCESS_KEY_ID: string;
     S3_SECRET_ACCESS_KEY: string;
   };
@@ -500,6 +490,11 @@ declare class S3FileStorageProvider implements FileStorageProvider {
   convertName(name: string): string;
   protected getClient(bucketName: string): S3mini;
   protected readonly onStart: import("alepha").HookPrimitive<"start">;
+  /**
+   * Object key, tenant-scoped when a tenant is active (`currentTenantAtom`):
+   * `{tenantId}/{fileId}` within the per-bucket S3 bucket. No tenant → `{fileId}`.
+   */
+  protected key(fileId: string): string;
   protected createId(mimeType: string): string;
   upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
   download(bucketName: string, fileId: string): Promise<FileLike>;

package/dist/bucket/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/bucket/providers/FileStorageProvider.ts","../../src/bucket/providers/MemoryFileStorageProvider.ts","../../src/bucket/primitives/$bucket.ts","../../src/bucket/errors/FileNotFoundError.ts","../../src/bucket/providers/LocalFileStorageProvider.ts","../../src/bucket/providers/R2FileStorageProvider.ts","../../src/bucket/providers/S3FileStorageProvider.ts","../../src/bucket/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/bucket/providers/FileStorageProvider.ts","../../src/bucket/providers/MemoryFileStorageProvider.ts","../../src/bucket/primitives/$bucket.ts","../../src/bucket/errors/FileNotFoundError.ts","../../src/bucket/providers/LocalFileStorageProvider.ts","../../src/bucket/providers/R2FileStorageProvider.ts","../../src/bucket/providers/S3FileStorageProvider.ts","../../src/bucket/index.ts"],"mappings":"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"}

package/dist/bucket/index.js

@@ -1,6 +1,7 @@
-import { $atom, $env, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, Primitive, createPrimitive, t } from "alepha";
+import { $atom, $env, $hook, $inject, $module, $state, Alepha, AlephaError, KIND, Primitive, createPrimitive, z } from "alepha";
 import { FileDetector, FileSystemProvider } from "alepha/system";
 import { CryptoProvider } from "alepha/crypto";
+import { currentTenantAtom } from "alepha/security";
 import { createReadStream } from "node:fs";
 import { mkdir, readdir, stat, unlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -25,6 +26,7 @@ var FileNotFoundError = class extends AlephaError {
 //#region ../../src/bucket/providers/MemoryFileStorageProvider.ts
 var MemoryFileStorageProvider = class {
 	files = {};
+	alepha = $inject(Alepha);
 	fileSystem = $inject(FileSystemProvider);
 	fileDetector = $inject(FileDetector);
 	crypto = $inject(CryptoProvider);
@@ -33,7 +35,7 @@ var MemoryFileStorageProvider = class {
 		const chunks = [];
 		for await (const chunk of file.stream()) chunks.push(chunk);
 		const buffer = Buffer.concat(chunks);
-		this.files[`${bucketName}/${fileId}`] = {
+		this.files[this.key(bucketName, fileId)] = {
 			buffer,
 			name: file.name,
 			type: file.type,
@@ -42,7 +44,7 @@ var MemoryFileStorageProvider = class {
 		return fileId;
 	}
 	async download(bucketName, fileId) {
-		const fileKey = `${bucketName}/${fileId}`;
+		const fileKey = this.key(bucketName, fileId);
 		const stored = this.files[fileKey];
 		if (!stored) throw new FileNotFoundError(`File with ID ${fileId} not found.`);
 		return this.fileSystem.createFile({
@@ -53,20 +55,28 @@ var MemoryFileStorageProvider = class {
 		});
 	}
 	async exists(bucketName, fileId) {
-		return `${bucketName}/${fileId}` in this.files;
+		return this.key(bucketName, fileId) in this.files;
 	}
 	async delete(bucketName, fileId) {
-		const fileKey = `${bucketName}/${fileId}`;
+		const fileKey = this.key(bucketName, fileId);
 		if (!(fileKey in this.files)) throw new FileNotFoundError(`File with ID ${fileId} not found.`);
 		delete this.files[fileKey];
 	}
 	async deleteMany(bucketName, fileIds) {
-		for (const id of fileIds) delete this.files[`${bucketName}/${id}`];
+		for (const id of fileIds) delete this.files[this.key(bucketName, id)];
 	}
 	async list(bucketName) {
-		const prefix = `${bucketName}/`;
+		const prefix = this.key(bucketName, "");
 		return Object.keys(this.files).filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
 	}
+	/**
+	* In-memory key, tenant-scoped when a tenant is active (`currentTenantAtom`),
+	* mirroring the R2/Local/S3 layout: `{tenantId}/{bucket}/{fileId}`.
+	*/
+	key(bucket, fileId = "") {
+		const tenantId = this.alepha.store.get(currentTenantAtom)?.id;
+		return tenantId ? `${tenantId}/${bucket}/${fileId}` : `${bucket}/${fileId}`;
+	}
 	createId() {
 		return this.crypto.randomUUID();
 	}
@@ -227,7 +237,7 @@ $bucket[KIND] = BucketPrimitive;
 */
 const localFileStorageOptions = $atom({
 	name: "alepha.bucket.local.options",
-	schema: t.object({ storagePath: t.string({ description: "Directory path where files will be stored" }) }),
+	schema: z.object({ storagePath: z.string().describe("Directory path where files will be stored") }),
 	default: { storagePath: "node_modules/.alepha/buckets" }
 });
 var LocalFileStorageProvider = class {
@@ -262,6 +272,7 @@ var LocalFileStorageProvider = class {
 	async upload(bucketName, file, fileId) {
 		fileId ??= this.createId(file.type);
 		this.log.trace(`Uploading file to ${bucketName}`);
+		await mkdir(this.path(bucketName), { recursive: true });
 		await this.fileSystemProvider.writeFile(this.path(bucketName, fileId), file);
 		return fileId;
 	}
@@ -320,7 +331,8 @@ var LocalFileStorageProvider = class {
 		return `${this.crypto.randomUUID()}.${ext}`;
 	}
 	path(bucket, fileId = "") {
-		return join(this.storagePath, bucket, fileId);
+		const tenantId = this.alepha.store.get(currentTenantAtom)?.id;
+		return tenantId ? join(this.storagePath, tenantId, bucket, fileId) : join(this.storagePath, bucket, fileId);
 	}
 	isErrorNoEntry(error) {
 		return error instanceof Error && "code" in error && error.code === "ENOENT";
@@ -328,7 +340,7 @@ var LocalFileStorageProvider = class {
 };
 //#endregion
 //#region ../../src/bucket/providers/S3FileStorageProvider.ts
-const envSchema = t.object({
+const envSchema = z.object({
 	/**
 	* S3 endpoint URL. The bucket name is appended (path-style) per request.
 	*
@@ -338,21 +350,21 @@ const envSchema = t.object({
 	* - MinIO: `http://localhost:9000`
 	* - DigitalOcean Spaces: `https://<region>.digitaloceanspaces.com`
 	*/
-	S3_ENDPOINT: t.string(),
+	S3_ENDPOINT: z.string(),
 	/**
 	* AWS region or "auto" for R2.
 	*
 	* @default "auto"
 	*/
-	S3_REGION: t.optional(t.string()),
+	S3_REGION: z.string().optional(),
 	/**
 	* Access key ID for S3 authentication.
 	*/
-	S3_ACCESS_KEY_ID: t.string(),
+	S3_ACCESS_KEY_ID: z.string(),
 	/**
 	* Secret access key for S3 authentication.
 	*/
-	S3_SECRET_ACCESS_KEY: t.string()
+	S3_SECRET_ACCESS_KEY: z.string()
 });
 /**
 * S3-compatible file storage provider for Node.js.
@@ -408,6 +420,14 @@ var S3FileStorageProvider = class {
 			}
 		}
 	});
+	/**
+	* Object key, tenant-scoped when a tenant is active (`currentTenantAtom`):
+	* `{tenantId}/{fileId}` within the per-bucket S3 bucket. No tenant → `{fileId}`.
+	*/
+	key(fileId) {
+		const tenantId = this.alepha.store.get(currentTenantAtom)?.id;
+		return tenantId ? `${tenantId}/${fileId}` : fileId;
+	}
 	createId(mimeType) {
 		const ext = this.fileDetector.getExtensionFromMimeType(mimeType);
 		return `${this.crypto.randomUUID()}.${ext}`;
@@ -418,7 +438,7 @@ var S3FileStorageProvider = class {
 		const client = this.getClient(bucketName);
 		try {
 			const buffer = new Uint8Array(await file.arrayBuffer());
-			await client.putObject(fileId, buffer, file.type || "application/octet-stream", void 0, { "x-amz-meta-name": encodeURIComponent(file.name) }, file.size);
+			await client.putObject(this.key(fileId), buffer, file.type || "application/octet-stream", void 0, { "x-amz-meta-name": encodeURIComponent(file.name) }, file.size);
 			this.log.trace(`File uploaded successfully: ${fileId}`);
 			return fileId;
 		} catch (error) {
@@ -429,7 +449,7 @@ var S3FileStorageProvider = class {
 	}
 	async download(bucketName, fileId) {
 		this.log.trace(`Downloading file '${fileId}' from bucket '${bucketName}'...`);
-		const response = await this.getClient(bucketName).getObjectResponse(fileId);
+		const response = await this.getClient(bucketName).getObjectResponse(this.key(fileId));
 		if (!response) throw new FileNotFoundError(`File '${fileId}' not found in bucket '${bucketName}'`);
 		const mimeType = response.headers.get("content-type") || this.fileDetector.getContentType(fileId);
 		const metaName = response.headers.get("x-amz-meta-name");
@@ -450,13 +470,13 @@ var S3FileStorageProvider = class {
 	}
 	async exists(bucketName, fileId) {
 		this.log.trace(`Checking existence of file '${fileId}' in bucket '${bucketName}'...`);
-		return await this.getClient(bucketName).objectExists(fileId) === true;
+		return await this.getClient(bucketName).objectExists(this.key(fileId)) === true;
 	}
 	async delete(bucketName, fileId) {
 		this.log.trace(`Deleting file '${fileId}' from bucket '${bucketName}'...`);
 		const client = this.getClient(bucketName);
 		try {
-			await client.deleteObject(fileId);
+			await client.deleteObject(this.key(fileId));
 		} catch (error) {
 			this.log.error(`Failed to delete file: ${error}`);
 			if (error instanceof Error) throw new FileNotFoundError("Error deleting file", { cause: error });
@@ -465,20 +485,23 @@ var S3FileStorageProvider = class {
 	}
 	async list(bucketName) {
 		this.log.trace(`Listing files in bucket '${bucketName}'...`);
-		const objects = await this.getClient(bucketName).listObjects();
+		const client = this.getClient(bucketName);
+		const tenantId = this.alepha.store.get(currentTenantAtom)?.id;
+		const prefix = tenantId ? `${tenantId}/` : void 0;
+		const objects = await client.listObjects(void 0, prefix);
 		if (!objects) return [];
-		return objects.map((object) => object.Key);
+		return objects.map((object) => prefix && object.Key.startsWith(prefix) ? object.Key.slice(prefix.length) : object.Key);
 	}
 	async deleteMany(bucketName, fileIds) {
 		if (fileIds.length === 0) return;
 		this.log.trace(`Deleting ${fileIds.length} files from bucket '${bucketName}'...`);
 		const client = this.getClient(bucketName);
 		for (let i = 0; i < fileIds.length; i += 1e3) {
-			const chunk = fileIds.slice(i, i + 1e3);
+			const keys = fileIds.slice(i, i + 1e3).map((id) => this.key(id));
 			try {
 				const batch = client.deleteObjects;
-				if (typeof batch === "function") await batch.call(client, chunk);
-				else await Promise.all(chunk.map((id) => client.deleteObject(id)));
+				if (typeof batch === "function") await batch.call(client, keys);
+				else await Promise.all(keys.map((key) => client.deleteObject(key)));
 			} catch (error) {
 				this.log.error(`Failed to delete files: ${error}`);
 				if (error instanceof Error) throw new FileNotFoundError("Error deleting files", { cause: error });
@@ -538,11 +561,11 @@ var R2FileStorageProvider = class {
 	alepha = $inject(Alepha);
 	log = $logger();
 	crypto = $inject(CryptoProvider);
-	env = $env(t.object({ 
+	env = $env(z.object({ 
 	/**
 	* The actual R2 bucket name in Cloudflare.
 	*/
-R2_BUCKET_NAME: t.string({ description: "R2 bucket name in Cloudflare" }) }));
+R2_BUCKET_NAME: z.string().describe("R2 bucket name in Cloudflare") }));
 	r2;
 	/**
 	* Get the R2 bucket name from environment.
@@ -631,10 +654,17 @@ R2_BUCKET_NAME: t.string({ description: "R2 bucket name in Cloudflare" }) }));
 		return (await r2.list({ prefix: keyPrefix })).objects.map((object) => object.key.slice(keyPrefix.length));
 	}
 	/**
-	* Build the full R2 key: {prefix}/{bucketName}/{fileId}
+	* Build the full R2 key: {prefix}/{tenantId}/{bucketName}/{fileId}
+	*
+	* When a tenant is active on the current request/job (`currentTenantAtom`),
+	* its id is inserted as a directory so a pooled multi-tenant worker keeps
+	* each tenant's objects isolated. No tenant → the historical
+	* `{prefix}/{bucketName}/{fileId}` layout is unchanged.
 	*/
 	key(bucketName, fileId) {
 		const parts = [bucketName, fileId];
+		const tenantId = this.alepha.store.get(currentTenantAtom)?.id;
+		if (tenantId) parts.unshift(tenantId);
 		if (this.prefix) parts.unshift(this.prefix);
 		return parts.join("/");
 	}