@upyo/pool 0.3.0-dev.36

package/dist/index.d.cts

@@ -0,0 +1,363 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/strategies/strategy.d.ts
+
+/**
+ * Result of transport selection by a strategy.
+ * @since 0.3.0
+ */
+interface TransportSelection {
+  /**
+   * The selected transport entry.
+   */
+  readonly entry: ResolvedTransportEntry;
+  /**
+   * Index of the selected transport in the original list.
+   */
+  readonly index: number;
+}
+/**
+ * Base interface for transport selection strategies.
+ * @since 0.3.0
+ */
+interface Strategy {
+  /**
+   * Selects a transport for sending a message.
+   *
+   * @param message The message to send.
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if no suitable transport is
+   *          available.
+   */
+  select(message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  /**
+   * Resets any internal state of the strategy.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Strategy for selecting transports in a pool.
+ * @since 0.3.0
+ */
+type PoolStrategy = "round-robin" | "weighted" | "priority" | "selector-based";
+/**
+ * Function that determines if a transport should handle a specific message.
+ * @since 0.3.0
+ */
+type TransportSelector = (message: Message) => boolean;
+/**
+ * Configuration for a transport entry in the pool.
+ * @since 0.3.0
+ */
+interface TransportEntry {
+  /**
+   * The transport instance to use.
+   */
+  readonly transport: Transport;
+  /**
+   * Weight for weighted distribution strategy.
+   * Higher values mean more traffic. Defaults to 1.
+   */
+  readonly weight?: number;
+  /**
+   * Priority for priority-based failover strategy.
+   * Higher values are tried first. Defaults to 0.
+   */
+  readonly priority?: number;
+  /**
+   * Selector function for selector-based routing.
+   * If provided, this transport will only be used for messages
+   * where the selector returns true.
+   */
+  readonly selector?: TransportSelector;
+  /**
+   * Whether this transport is enabled.
+   * Disabled transports are skipped. Defaults to true.
+   */
+  readonly enabled?: boolean;
+}
+/**
+ * Configuration options for the pool transport.
+ * @since 0.3.0
+ */
+interface PoolConfig {
+  /**
+   * The strategy to use for selecting transports.
+   * Can be a built-in strategy name or a custom Strategy instance.
+   */
+  readonly strategy: PoolStrategy | Strategy;
+  /**
+   * The transports in the pool.
+   */
+  readonly transports: readonly TransportEntry[];
+  /**
+   * Maximum number of retry attempts when a transport fails.
+   * Set to 0 to disable retries. Defaults to the number of transports.
+   */
+  readonly maxRetries?: number;
+  /**
+   * Timeout in milliseconds for each send attempt.
+   * If not specified, no timeout is applied.
+   */
+  readonly timeout?: number;
+  /**
+   * Whether to continue trying other transports after a successful send
+   * when using selector-based strategy. Defaults to false.
+   */
+  readonly continueOnSuccess?: boolean;
+}
+/**
+ * Resolved pool configuration with defaults applied.
+ * @since 0.3.0
+ */
+interface ResolvedPoolConfig {
+  readonly strategy: PoolStrategy | Strategy;
+  readonly transports: readonly ResolvedTransportEntry[];
+  readonly maxRetries: number;
+  readonly timeout?: number;
+  readonly continueOnSuccess: boolean;
+}
+/**
+ * Resolved transport entry with defaults applied.
+ * @since 0.3.0
+ */
+interface ResolvedTransportEntry {
+  readonly transport: Transport;
+  readonly weight: number;
+  readonly priority: number;
+  readonly selector?: TransportSelector;
+  readonly enabled: boolean;
+}
+/**
+ * Creates a resolved pool configuration with defaults applied.
+ *
+ * @param config The pool configuration.
+ * @returns The resolved configuration with defaults.
+ * @throws {Error} If the configuration is invalid.
+ * @since 0.3.0
+ */
+//#endregion
+//#region src/pool-transport.d.ts
+/**
+ * Pool transport that combines multiple transports with various load balancing
+ * and failover strategies.
+ *
+ * This transport implements the same `Transport` interface, making it a drop-in
+ * replacement for any single transport. It distributes messages across multiple
+ * underlying transports based on the configured strategy.
+ *
+ * @example Round-robin load balancing
+ * ```typescript
+ * import { PoolTransport } from "@upyo/pool";
+ *
+ * const transport = new PoolTransport({
+ *   strategy: "round-robin",
+ *   transports: [
+ *     { transport: mailgunTransport },
+ *     { transport: sendgridTransport },
+ *     { transport: sesTransport },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Priority-based failover
+ * ```typescript
+ * const transport = new PoolTransport({
+ *   strategy: "priority",
+ *   transports: [
+ *     { transport: primaryTransport, priority: 100 },
+ *     { transport: backupTransport, priority: 50 },
+ *     { transport: lastResortTransport, priority: 10 },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Custom routing with selectors
+ * ```typescript
+ * const transport = new PoolTransport({
+ *   strategy: "selector-based",
+ *   transports: [
+ *     {
+ *       transport: bulkEmailTransport,
+ *       selector: (msg) => msg.tags?.includes("newsletter"),
+ *     },
+ *     {
+ *       transport: transactionalTransport,
+ *       selector: (msg) => msg.priority === "high",
+ *     },
+ *     { transport: defaultTransport }, // Catches everything else
+ *   ],
+ * });
+ * ```
+ *
+ * @since 0.3.0
+ */
+declare class PoolTransport implements Transport, AsyncDisposable {
+  /**
+   * The resolved configuration used by this pool transport.
+   */
+  readonly config: ResolvedPoolConfig;
+  private readonly strategy;
+  /**
+   * Creates a new PoolTransport instance.
+   *
+   * @param config Configuration options for the pool transport.
+   * @throws {Error} If the configuration is invalid.
+   */
+  constructor(config: PoolConfig);
+  /**
+   * Sends a single email message using the pool strategy.
+   *
+   * The transport is selected based on the configured strategy. If the
+   * selected transport fails, the pool will retry with other transports
+   * up to the configured retry limit.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options including abort signal.
+   * @returns A promise that resolves to a receipt indicating success or failure.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  /**
+   * Sends multiple email messages using the pool strategy.
+   *
+   * Each message is sent individually using the `send` method, respecting
+   * the configured strategy and retry logic.
+   *
+   * @param messages An iterable or async iterable of messages to send.
+   * @param options Optional transport options including abort signal.
+   * @returns An async iterable of receipts, one for each message.
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  /**
+   * Disposes of all underlying transports that support disposal.
+   *
+   * This method is called automatically when using the `await using` syntax.
+   * It ensures proper cleanup of resources held by the underlying transports.
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+  /**
+   * Creates a strategy instance based on the strategy type or returns the provided strategy.
+   */
+  private createStrategy;
+  /**
+   * Creates send options with timeout if configured.
+   */
+  private createSendOptions;
+}
+//#endregion
+//#region src/strategies/round-robin-strategy.d.ts
+/**
+ * Round-robin strategy that cycles through transports in order.
+ *
+ * This strategy maintains an internal counter and selects transports
+ * in a circular fashion, ensuring even distribution of messages across
+ * all enabled transports.
+ * @since 0.3.0
+ */
+declare class RoundRobinStrategy implements Strategy {
+  private currentIndex;
+  /**
+   * Selects the next transport in round-robin order.
+   *
+   * @param _message The message to send (unused in this strategy).
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if all transports have been
+   *          attempted.
+   */
+  select(_message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  /**
+   * Resets the round-robin counter to start from the beginning.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/strategies/weighted-strategy.d.ts
+/**
+ * Weighted strategy that distributes traffic based on configured weights.
+ *
+ * This strategy uses weighted random selection to distribute messages
+ * across transports proportionally to their configured weights.
+ * A transport with weight 2 will receive approximately twice as many
+ * messages as a transport with weight 1.
+ * @since 0.3.0
+ */
+declare class WeightedStrategy implements Strategy {
+  /**
+   * Selects a transport based on weighted random distribution.
+   *
+   * @param _message The message to send (unused in this strategy).
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if all transports have been
+   *          attempted.
+   */
+  select(_message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  /**
+   * Resets the strategy (no-op for weighted strategy as it's stateless).
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/strategies/priority-strategy.d.ts
+/**
+ * Priority strategy that selects transports based on priority values.
+ *
+ * This strategy always attempts to use the highest priority transport
+ * first, falling back to lower priority transports only when higher
+ * priority ones fail. Transports with the same priority are considered
+ * equivalent and one is selected randomly.
+ * @since 0.3.0
+ */
+declare class PriorityStrategy implements Strategy {
+  /**
+   * Selects the highest priority transport that hasn't been attempted.
+   *
+   * @param _message The message to send (unused in this strategy).
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if all transports have been
+   *          attempted.
+   */
+  select(_message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  /**
+   * Resets the strategy (no-op for priority strategy as it's stateless).
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/strategies/selector-strategy.d.ts
+/**
+ * Selector strategy that routes messages based on custom selector functions.
+ *
+ * This strategy evaluates each transport's selector function (if provided)
+ * to determine if it should handle a specific message. Transports without
+ * selectors are considered as catch-all fallbacks. Among matching transports,
+ * one is selected randomly.
+ * @since 0.3.0
+ */
+declare class SelectorStrategy implements Strategy {
+  /**
+   * Selects a transport based on selector function matching.
+   *
+   * @param message The message to send.
+   * @param transports Available transports.
+   * @param attemptedIndices Indices of transports that have already been
+   *                         attempted.
+   * @returns The selected transport or `undefined` if no transport matches.
+   */
+  select(message: Message, transports: readonly ResolvedTransportEntry[], attemptedIndices: Set<number>): TransportSelection | undefined;
+  /**
+   * Resets the strategy (no-op for selector strategy as it's stateless).
+   */
+  reset(): void;
+}
+//#endregion
+export { PoolConfig, PoolStrategy, PoolTransport, PriorityStrategy, ResolvedPoolConfig, ResolvedTransportEntry, RoundRobinStrategy, SelectorStrategy, Strategy, TransportEntry, TransportSelection, TransportSelector, WeightedStrategy };