alepha/batch.d.ts

Alepha is a convention-driven TypeScript framework for building robust, end-to-end type-safe applications, from serverless APIs to full-stack React apps.

import * as _alepha_core1 from "alepha";
import * as _alepha_core0 from "alepha";
import { Descriptor, KIND, Static, TSchema } from "alepha";
import { DateTimeProvider, DurationLike } from "alepha/datetime";
import * as _alepha_retry0 from "alepha/retry";
import { RetryDescriptorOptions } from "alepha/retry";

//#region src/descriptors/$batch.d.ts
/**
 * Creates a batch processor. This is useful for grouping multiple operations
 * (like API calls or database writes) into a single one to improve performance.
 */
declare const $batch: {
  <TItem extends TSchema, TResponse>(options: BatchDescriptorOptions<TItem, TResponse>): BatchDescriptor<TItem, TResponse>;
  [KIND]: typeof BatchDescriptor;
};
interface BatchDescriptorOptions<TItem extends TSchema, TResponse = any> {
  /**
   * A TypeBox schema to validate each item pushed to the batch.
   */
  schema: TItem;
  /**
   * The handler function that processes a batch of items.
   */
  handler: (items: Static<TItem>[]) => TResponse;
  /**
   * The maximum number of items in a batch. When this size is reached,
   * the batch is flushed automatically.
   * @default 10
   */
  maxSize?: number;
  /**
   * The maximum duration to wait before flushing a batch, even if it's not full.
   * Starts from the moment the first item is added to a partition.
   * @default [1, "second"]
   */
  maxDuration?: DurationLike;
  /**
   * A function to determine the partition key for an item. Items with the
   * same key are batched together. If not provided, all items are placed in a single, default partition.
   */
  partitionBy?: (item: Static<TItem>) => string;
  /**
   * The maximum number of concurrent `handler` executions.
   * @default 1
   */
  concurrency?: number;
  /**
   * Retry options for the batch handler if it fails.
   * Leverages the `@alepha/retry` module.
   */
  retry?: Omit<RetryDescriptorOptions<() => Array<Static<TItem>>>, "handler">;
}
declare class BatchDescriptor<TItem extends TSchema, TResponse = any> extends Descriptor<BatchDescriptorOptions<TItem, TResponse>> {
  protected readonly log: _alepha_core1.Logger;
  protected readonly dateTime: DateTimeProvider;
  protected readonly partitions: Map<any, any>;
  protected activeHandlers: PromiseWithResolvers<void>[];
  protected retry: _alepha_retry0.RetryDescriptorFn<(items: (TItem & {
    params: [];
  })["static"][]) => TResponse>;
  /**
   * Pushes an item into the batch. The item will be processed
   * asynchronously with other items when the batch is flushed.
   */
  push(item: Static<TItem>): Promise<TResponse>;
  flush(partitionKey?: string): Promise<void>;
  protected flushPartition(partitionKey: string): Promise<void>;
  protected readonly dispose: _alepha_core1.HookDescriptor<"stop">;
}
//# sourceMappingURL=$batch.d.ts.map
//#endregion
//#region src/index.d.ts
/**
 * This module allows you to group multiple asynchronous operations into a single "batch," which is then processed together.
 * This is an essential pattern for improving performance, reducing I/O, and interacting efficiently with rate-limited APIs or databases.
 *
 * ```ts
 * import { Alepha, $hook, run, t } from "alepha";
 * import { $batch } from "alepha/batch";
 *
 * class LoggingService {
 *   // define the batch processor
 *   logBatch = $batch({
 *     schema: t.string(),
 *     maxSize: 10,
 *     maxDuration: [5, "seconds"],
 *     handler: async (items) => {
 *       console.log(`[BATCH LOG] Processing ${items.length} events:`, items);
 *     },
 *   });
 *
 *   // example of how to use it
 *   onReady = $hook({
 *     on: "ready",
 *     handler: async () => {
 *       this.logBatch.push("Application started.");
 *       this.logBatch.push("User authenticated.");
 *       // ... more events pushed from elsewhere in the app
 *     },
 *   });
 * }
 * ```
 *
 * @see {@link $batch}
 * @module alepha.batch
 */
declare const AlephaBatch: _alepha_core0.Service<_alepha_core0.Module>;
//# sourceMappingURL=index.d.ts.map

//#endregion
export { $batch, AlephaBatch, BatchDescriptor, BatchDescriptorOptions };
//# sourceMappingURL=index.d.ts.map