alepha/dist/batch/index.d.ts

Easy-to-use modern TypeScript framework for building many kind of applications.

import { Alepha, KIND, Primitive, Static, TSchema } from "alepha";
import { CryptoProvider } from "alepha/crypto";
import { DateTimeProvider, DurationLike } from "alepha/datetime";
import { RetryBackoffOptions, RetryPrimitiveOptions, RetryProvider } from "alepha/retry";
//#region ../../src/batch/providers/BatchProvider.d.ts
interface BatchOptions<TItem, TResponse = any> {
  /**
   * The batch processing handler function that processes arrays of validated items.
   */
  handler: (items: TItem[]) => TResponse;
  /**
   * Maximum number of items to collect before automatically flushing the batch.
   *
   * @default 10
   */
  maxSize?: number;
  /**
   * Maximum number of items that can be queued in a single partition.
   * If exceeded, push() will throw an error.
   */
  maxQueueSize?: number;
  /**
   * Maximum time to wait before flushing a batch, even if it hasn't reached maxSize.
   *
   * @default [1, "second"]
   */
  maxDuration?: DurationLike;
  /**
   * Function to determine partition keys for grouping items into separate batches.
   */
  partitionBy?: (item: TItem) => string;
  /**
   * Maximum number of batch handlers that can execute simultaneously.
   *
   * @default 1
   */
  concurrency?: number;
  /**
   * Retry configuration for failed batch processing operations.
   */
  retry?: {
    /**
     * The maximum number of attempts.
     *
     * @default 3
     */
    max?: number;
    /**
     * The backoff strategy for delays between retries.
     * Can be a fixed number (in ms) or a configuration object for exponential backoff.
     *
     * @default { initial: 200, factor: 2, jitter: true }
     */
    backoff?: number | RetryBackoffOptions;
    /**
     * An overall time limit for all retry attempts combined.
     *
     * e.g., `[5, 'seconds']`
     */
    maxDuration?: DurationLike;
    /**
     * A function that determines if a retry should be attempted based on the error.
     *
     * @default (error) => true (retries on any error)
     */
    when?: (error: Error) => boolean;
    /**
     * A custom callback for when a retry attempt fails.
     * This is called before the delay.
     */
    onError?: (error: Error, attempt: number) => void;
  };
}
type BatchItemStatus = "pending" | "processing" | "completed" | "failed";
interface BatchItemState<TItem, TResponse> {
  id: string;
  item: TItem;
  partitionKey: string;
  status: BatchItemStatus;
  result?: TResponse;
  error?: Error;
  promise?: Promise<TResponse>;
  resolve?: (value: TResponse) => void;
  reject?: (error: Error) => void;
}
interface PartitionState {
  itemIds: string[];
  timeout?: {
    clear: () => void;
  };
  flushing: boolean;
}
/**
 * Context object that holds all state for a batch processor instance.
 */
interface BatchContext<TItem, TResponse> {
  options: BatchOptions<TItem, TResponse>;
  itemStates: Map<string, BatchItemState<TItem, TResponse>>;
  partitions: Map<string, PartitionState>;
  activeHandlers: PromiseWithResolvers<void>[];
  isShuttingDown: boolean;
  isReady: boolean;
  alepha: Alepha;
}
/**
 * Service for batch processing operations.
 * Provides methods to manage batches of items with automatic flushing based on size or time.
 */
declare class BatchProvider {
  protected readonly log: import("alepha/logger").Logger;
  protected readonly dateTime: DateTimeProvider;
  protected readonly retryProvider: RetryProvider;
  protected readonly crypto: CryptoProvider;
  /**
   * All active batch contexts managed by this provider.
   */
  protected readonly contexts: Set<BatchContext<any, any>>;
  /**
   * Creates a new batch context with the given options.
   */
  createContext<TItem, TResponse>(alepha: Alepha, options: BatchOptions<TItem, TResponse>): BatchContext<TItem, TResponse>;
  /**
   * Shutdown hook - flushes all batch contexts on application stop.
   */
  protected readonly onStop: import("alepha").HookPrimitive<"stop">;
  /**
   * Get the effective maxSize for a context.
   */
  protected getMaxSize<TItem, TResponse>(context: BatchContext<TItem, TResponse>): number;
  /**
   * Get the effective concurrency for a context.
   */
  protected getConcurrency<TItem, TResponse>(context: BatchContext<TItem, TResponse>): number;
  /**
   * Get the effective maxDuration for a context.
   */
  protected getMaxDuration<TItem, TResponse>(context: BatchContext<TItem, TResponse>): DurationLike;
  /**
   * Pushes an item into the batch and returns immediately with a unique ID.
   * The item will be processed asynchronously with other items when the batch is flushed.
   * Use wait(id) to get the processing result.
   *
   * @throws Error if maxQueueSize is exceeded
   */
  push<TItem, TResponse>(context: BatchContext<TItem, TResponse>, item: TItem): string;
  /**
   * Wait for a specific item to be processed and get its result.
   * @param id The item ID returned from push()
   * @returns The processing result
   * @throws If the item doesn't exist or processing failed
   */
  wait<TItem, TResponse>(context: BatchContext<TItem, TResponse>, id: string): Promise<TResponse>;
  /**
   * Get the current status of an item.
   * @param id The item ID returned from push()
   * @returns Status information or undefined if item doesn't exist
   */
  status<TItem, TResponse>(context: BatchContext<TItem, TResponse>, id: string): {
    status: "pending" | "processing";
  } | {
    status: "completed";
    result: TResponse;
  } | {
    status: "failed";
    error: Error;
  } | undefined;
  /**
   * Clears completed and failed items from the context to free memory.
   * Returns the number of items cleared.
   *
   * @param context The batch context
   * @param status Optional: only clear items with this specific status ('completed' or 'failed')
   * @returns The number of items cleared
   */
  clearCompleted<TItem, TResponse>(context: BatchContext<TItem, TResponse>, status?: "completed" | "failed"): number;
  /**
   * Flush all partitions or a specific partition.
   */
  flush<TItem, TResponse>(context: BatchContext<TItem, TResponse>, partitionKey?: string): Promise<void>;
  /**
   * Flush a specific partition.
   */
  protected flushPartition<TItem, TResponse>(context: BatchContext<TItem, TResponse>, partitionKey: string, limit?: number): Promise<void>;
  /**
   * Mark the context as ready and start processing buffered items.
   * Called after the "ready" hook.
   */
  markReady<TItem, TResponse>(context: BatchContext<TItem, TResponse>): Promise<void>;
  /**
   * Mark the context as shutting down and flush all remaining items.
   */
  shutdown<TItem, TResponse>(context: BatchContext<TItem, TResponse>): Promise<void>;
  /**
   * Called after the "ready" hook to start processing buffered items that were
   * pushed during startup. This checks all partitions and starts timeouts/flushes
   * for items that were accumulated before the app was ready.
   */
  protected startProcessing<TItem, TResponse>(context: BatchContext<TItem, TResponse>): Promise<void>;
}
//#endregion
//#region ../../src/batch/primitives/$batch.d.ts
/**
 * Creates a batch processing primitive for efficient grouping and processing of multiple operations.
 */
declare const $batch: {
  <TItem extends TSchema, TResponse>(options: BatchPrimitiveOptions<TItem, TResponse>): BatchPrimitive<TItem, TResponse>;
  [KIND]: typeof BatchPrimitive;
};
interface BatchPrimitiveOptions<TItem extends TSchema, TResponse = any> {
  /**
   * TypeBox schema for validating each item added to the batch.
   */
  schema: TItem;
  /**
   * The batch processing handler function that processes arrays of validated items.
   */
  handler: (items: Static<TItem>[]) => TResponse;
  /**
   * Maximum number of items to collect before automatically flushing the batch.
   */
  maxSize?: number;
  /**
   * Maximum number of items that can be queued in a single partition.
   * If exceeded, push() will throw an error.
   */
  maxQueueSize?: number;
  /**
   * Maximum time to wait before flushing a batch, even if it hasn't reached maxSize.
   */
  maxDuration?: DurationLike;
  /**
   * Function to determine partition keys for grouping items into separate batches.
   */
  partitionBy?: (item: Static<TItem>) => string;
  /**
   * Maximum number of batch handlers that can execute simultaneously.
   */
  concurrency?: number;
  /**
   * Retry configuration for failed batch processing operations.
   */
  retry?: Omit<RetryPrimitiveOptions<() => Array<Static<TItem>>>, "handler">;
}
declare class BatchPrimitive<TItem extends TSchema, TResponse = any> extends Primitive<BatchPrimitiveOptions<TItem, TResponse>> {
  protected readonly batchProvider: BatchProvider;
  protected readonly context: BatchContext<Static<TItem>, TResponse>;
  constructor(...args: ConstructorParameters<typeof Primitive<BatchPrimitiveOptions<TItem, TResponse>>>);
  /**
   * Pushes an item into the batch and returns immediately with a unique ID.
   * The item will be processed asynchronously with other items when the batch is flushed.
   * Use wait(id) to get the processing result.
   */
  push(item: Static<TItem>): Promise<string>;
  /**
   * Wait for a specific item to be processed and get its result.
   * @param id The item ID returned from push()
   * @returns The processing result
   * @throws If the item doesn't exist or processing failed
   */
  wait(id: string): Promise<TResponse>;
  /**
   * Get the current status of an item.
   * @param id The item ID returned from push()
   * @returns Status information or undefined if item doesn't exist
   */
  status(id: string): {
    status: "pending" | "processing";
  } | {
    status: "completed";
    result: TResponse;
  } | {
    status: "failed";
    error: Error;
  } | undefined;
  /**
   * Flush all partitions or a specific partition.
   */
  flush(partitionKey?: string): Promise<void>;
  /**
   * Clears completed and failed items from memory.
   * Call this periodically in long-running applications to prevent memory leaks.
   *
   * @param status Optional: only clear items with this specific status ('completed' or 'failed')
   * @returns The number of items cleared
   */
  clearCompleted(status?: "completed" | "failed"): number;
  protected readonly onReady: import("alepha").HookPrimitive<"ready">;
}
//#endregion
//#region ../../src/batch/index.d.ts
/**
 * Batch accumulation and processing.
 *
 * **Features:**
 * - Batch accumulator with handler
 * - Configurable batch size
 * - Time-based triggers
 * - Status tracking
 *
 * @module alepha.batch
 */
declare const AlephaBatch: import("alepha").Service<import("alepha").Module>;
//#endregion
export { $batch, AlephaBatch, BatchContext, BatchItemState, BatchItemStatus, BatchOptions, BatchPrimitive, BatchPrimitiveOptions, BatchProvider, PartitionState };
//# sourceMappingURL=index.d.ts.map