@upyo/retry 0.5.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/retry
+===========
+
+*@upyo/retry* provides a retry and backoff decorator for Upyo transports.
+It wraps any `Transport` implementation without changing the transport
+interface, so it can be composed with SMTP, HTTP API transports, pool
+transports, and OpenTelemetry instrumentation.
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@upyo/retry
+pnpm add @upyo/retry
+~~~~
+
+
+Usage
+-----
+
+~~~~ typescript
+import { RetryTransport } from "@upyo/retry";
+import { MailgunTransport } from "@upyo/mailgun";
+
+const baseTransport = new MailgunTransport({
+  apiKey: "your-mailgun-api-key",
+  domain: "mg.example.com",
+});
+
+const transport = new RetryTransport(baseTransport, {
+  maxAttempts: 3,
+  backoff: {
+    baseDelayMilliseconds: 1000,
+    maxDelayMilliseconds: 30000,
+    factor: 2,
+  },
+});
+~~~~
+
+The retry transport uses structured Upyo failure receipts to distinguish
+transient failures, such as rate limits and temporary server errors, from
+permanent failures, such as validation or authentication errors.  It also
+honors provider-supplied `Retry-After` metadata when available.

package/dist/index.cjs

@@ -0,0 +1,328 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __upyo_core = __toESM(require("@upyo/core"));
+
+//#region src/config.ts
+/**
+* Creates a resolved retry configuration.
+*
+* @param config Retry configuration.
+* @returns The resolved configuration.
+* @throws {RangeError} If a numeric option is out of range.
+* @since 0.5.0
+*/
+function createRetryConfig(config = {}) {
+	const maxAttempts = config.maxAttempts ?? 3;
+	const baseDelayMilliseconds = config.backoff?.baseDelayMilliseconds ?? 1e3;
+	const maxDelayMilliseconds = config.backoff?.maxDelayMilliseconds ?? 3e4;
+	const factor = config.backoff?.factor ?? 2;
+	const maxConcurrent = config.sendMany?.maxConcurrent ?? 1;
+	const intervalMilliseconds = config.sendMany?.intervalMilliseconds ?? 0;
+	assertIntegerAtLeast(maxAttempts, 1, "maxAttempts");
+	assertFiniteAtLeast(baseDelayMilliseconds, 0, "backoff.baseDelayMilliseconds");
+	assertFiniteAtLeast(maxDelayMilliseconds, 0, "backoff.maxDelayMilliseconds");
+	assertFiniteAtLeast(factor, 1, "backoff.factor");
+	assertIntegerAtLeast(maxConcurrent, 1, "sendMany.maxConcurrent");
+	assertFiniteAtLeast(intervalMilliseconds, 0, "sendMany.intervalMilliseconds");
+	return {
+		maxAttempts,
+		backoff: {
+			baseDelayMilliseconds,
+			maxDelayMilliseconds,
+			factor
+		},
+		jitter: config.jitter ?? "full",
+		random: config.random ?? Math.random,
+		shouldRetry: config.shouldRetry,
+		wait: config.wait ?? defaultWait,
+		sendMany: {
+			maxConcurrent,
+			intervalMilliseconds
+		}
+	};
+}
+async function defaultWait(context, signal) {
+	signal?.throwIfAborted();
+	if (context.delayMilliseconds <= 0) return;
+	await new Promise((resolve, reject) => {
+		const cleanup = () => signal?.removeEventListener("abort", abort);
+		const timeout = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, context.delayMilliseconds);
+		const abort = () => {
+			clearTimeout(timeout);
+			cleanup();
+			reject(createAbortError());
+		};
+		if (signal?.aborted) {
+			abort();
+			return;
+		}
+		signal?.addEventListener("abort", abort, { once: true });
+	});
+}
+function assertIntegerAtLeast(value, minimum, name) {
+	if (!Number.isInteger(value) || value < minimum) throw new RangeError(`${name} must be an integer greater than or equal to ${minimum}.`);
+}
+function assertFiniteAtLeast(value, minimum, name) {
+	if (!Number.isFinite(value) || value < minimum) throw new RangeError(`${name} must be greater than or equal to ${minimum}.`);
+}
+function createAbortError() {
+	return new DOMException("The operation was aborted.", "AbortError");
+}
+
+//#endregion
+//#region src/retry-transport.ts
+/**
+* Transport decorator that retries transient delivery failures.
+*
+* @since 0.5.0
+*/
+var RetryTransport = class {
+	id;
+	/**
+	* Resolved retry configuration.
+	*/
+	config;
+	wrappedTransport;
+	/**
+	* Creates a retrying transport around another transport.
+	*
+	* @param transport The transport to wrap.
+	* @param config Retry configuration.
+	* @throws {RangeError} If retry configuration is invalid.
+	*/
+	constructor(transport, config = {}) {
+		this.wrappedTransport = transport;
+		this.id = transport.id;
+		this.config = createRetryConfig(config);
+	}
+	/**
+	* Sends one message, retrying retryable failures.
+	*
+	* @param message The message to send.
+	* @param options Optional transport options.
+	* @returns The final delivery receipt.
+	* @throws {DOMException} If the operation is aborted.
+	*/
+	async send(message, options) {
+		options?.signal?.throwIfAborted();
+		let lastThrownError;
+		for (let attempt = 1; attempt <= this.config.maxAttempts; attempt++) {
+			options?.signal?.throwIfAborted();
+			try {
+				const receipt = await this.wrappedTransport.send(message, options);
+				if (receipt.successful) return this.withSuccessMetadata(receipt, attempt);
+				const failedReceipt = this.withFailureMetadata(receipt, attempt);
+				if (attempt >= this.config.maxAttempts || !this.shouldRetryReceipt(failedReceipt)) return failedReceipt;
+				await this.waitBeforeRetry({
+					attempt,
+					nextAttempt: attempt + 1,
+					maxAttempts: this.config.maxAttempts,
+					delayMilliseconds: this.calculateDelay(attempt, failedReceipt),
+					receipt: failedReceipt,
+					reason: "retry"
+				}, options?.signal);
+			} catch (error) {
+				options?.signal?.throwIfAborted();
+				lastThrownError = error;
+				if (attempt >= this.config.maxAttempts || !this.shouldRetryError(error)) return this.createThrownFailure(error, attempt);
+				await this.waitBeforeRetry({
+					attempt,
+					nextAttempt: attempt + 1,
+					maxAttempts: this.config.maxAttempts,
+					delayMilliseconds: this.calculateDelay(attempt),
+					error,
+					reason: "retry"
+				}, options?.signal);
+			}
+		}
+		return this.createThrownFailure(lastThrownError, this.config.maxAttempts);
+	}
+	/**
+	* Sends messages with per-message retry behavior.
+	*
+	* Receipts are yielded in the same order as input messages.
+	*
+	* @param messages Messages to send.
+	* @param options Optional transport options.
+	* @returns An async iterable of receipts.
+	* @throws {DOMException} If the operation is aborted.
+	*/
+	async *sendMany(messages, options) {
+		const iterator = toAsyncIterator(messages);
+		const inFlight = /* @__PURE__ */ new Map();
+		const completed = /* @__PURE__ */ new Map();
+		let inputDone = false;
+		let nextLaunchIndex = 0;
+		let nextYieldIndex = 0;
+		const launchNext = async () => {
+			if (inputDone) return;
+			options?.signal?.throwIfAborted();
+			const next = await iterator.next();
+			if (next.done) {
+				inputDone = true;
+				return;
+			}
+			const index = nextLaunchIndex++;
+			if (index > 0) await this.waitBetweenSendMany(options?.signal);
+			const promise = this.send(next.value, options).then((receipt) => ({
+				index,
+				successful: true,
+				receipt
+			}), (error) => ({
+				index,
+				successful: false,
+				error
+			}));
+			inFlight.set(index, promise);
+		};
+		const launchAvailable = async () => {
+			while (!inputDone && inFlight.size < this.config.sendMany.maxConcurrent) await launchNext();
+		};
+		try {
+			await launchAvailable();
+			while (inFlight.size > 0 || completed.has(nextYieldIndex)) {
+				while (completed.has(nextYieldIndex)) {
+					const result$1 = completed.get(nextYieldIndex);
+					completed.delete(nextYieldIndex);
+					if (result$1 == null) break;
+					if (!result$1.successful) throw result$1.error;
+					yield result$1.receipt;
+					nextYieldIndex++;
+					await launchAvailable();
+				}
+				if (inFlight.size <= 0) break;
+				const result = await Promise.race(inFlight.values());
+				inFlight.delete(result.index);
+				completed.set(result.index, result);
+				if (result.index !== nextYieldIndex) await launchAvailable();
+			}
+		} finally {
+			if (!inputDone) await iterator.return?.();
+		}
+	}
+	/**
+	* Disposes the wrapped transport when it supports disposal.
+	*
+	* @since 0.5.0
+	*/
+	async [Symbol.asyncDispose]() {
+		const asyncDisposable = this.wrappedTransport;
+		const asyncDispose = asyncDisposable[Symbol.asyncDispose];
+		if (typeof asyncDispose === "function") {
+			await asyncDispose.call(asyncDisposable);
+			return;
+		}
+		const disposable = this.wrappedTransport;
+		const dispose = disposable[Symbol.dispose];
+		if (typeof dispose === "function") dispose.call(disposable);
+	}
+	withSuccessMetadata(receipt, attempts) {
+		return {
+			...receipt,
+			provider: receipt.provider ?? this.id,
+			attempts
+		};
+	}
+	withFailureMetadata(receipt, attempts) {
+		return {
+			...receipt,
+			provider: receipt.provider ?? this.id,
+			retryable: receipt.retryable ?? this.hasRetryableError(receipt.errors),
+			attempts
+		};
+	}
+	shouldRetryReceipt(receipt) {
+		if (this.config.shouldRetry != null) return this.config.shouldRetry(receipt);
+		if (receipt.retryable != null) return receipt.retryable;
+		return this.hasRetryableError(receipt.errors);
+	}
+	shouldRetryError(error) {
+		if (this.config.shouldRetry != null) return this.config.shouldRetry(error);
+		return (0, __upyo_core.classifyReceiptError)(error).retryable;
+	}
+	hasRetryableError(errors) {
+		return errors?.some((error) => error.retryable) ?? false;
+	}
+	calculateDelay(attempt, receipt) {
+		const retryAfterMilliseconds = getRetryAfterMilliseconds(receipt);
+		const cappedRetryAfter = retryAfterMilliseconds == null ? void 0 : Math.min(retryAfterMilliseconds, this.config.backoff.maxDelayMilliseconds);
+		if (cappedRetryAfter != null) return cappedRetryAfter;
+		const computedDelay = Math.min(this.config.backoff.baseDelayMilliseconds * Math.pow(this.config.backoff.factor, attempt - 1), this.config.backoff.maxDelayMilliseconds);
+		if (this.config.jitter === false || this.config.jitter === "none") return computedDelay;
+		return Math.floor(this.config.random() * computedDelay);
+	}
+	waitBeforeRetry(context, signal) {
+		return this.config.wait(context, signal);
+	}
+	waitBetweenSendMany(signal) {
+		const delayMilliseconds = this.config.sendMany.intervalMilliseconds;
+		if (delayMilliseconds <= 0) return Promise.resolve();
+		return this.config.wait({
+			attempt: 0,
+			nextAttempt: 0,
+			maxAttempts: this.config.maxAttempts,
+			delayMilliseconds,
+			reason: "sendMany-throttle"
+		}, signal);
+	}
+	createThrownFailure(error, attempts) {
+		const message = error instanceof Error ? error.message : String(error);
+		const classification = (0, __upyo_core.classifyReceiptError)(error);
+		return (0, __upyo_core.createFailedReceipt)((0, __upyo_core.createReceiptError)(message, {
+			provider: this.id,
+			category: classification.category,
+			code: classification.code,
+			retryable: classification.retryable
+		}), {
+			provider: this.id,
+			attempts
+		});
+	}
+};
+/**
+* Creates a retrying transport around another transport.
+*
+* @param baseTransport The transport to wrap.
+* @param config Retry configuration.
+* @returns A retrying transport decorator.
+* @throws {RangeError} If retry configuration is invalid.
+* @since 0.5.0
+*/
+function createRetryTransport(baseTransport, config = {}) {
+	return new RetryTransport(baseTransport, config);
+}
+function getRetryAfterMilliseconds(receipt) {
+	const receiptDelay = receipt?.errors?.map((error) => error.retryAfterMilliseconds).find((delay) => delay != null);
+	return receiptDelay;
+}
+async function* toAsyncIterator(values) {
+	for await (const value of values) yield value;
+}
+
+//#endregion
+exports.RetryTransport = RetryTransport;
+exports.createRetryTransport = createRetryTransport;

package/dist/index.d.cts

@@ -0,0 +1,246 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/config.d.ts
+
+/**
+ * Jitter mode for computed retry delays.
+ *
+ * @since 0.5.0
+ */
+type JitterConfig = false | "none" | "full";
+/**
+ * Exponential backoff settings for retry delays.
+ *
+ * @since 0.5.0
+ */
+interface BackoffConfig {
+  /**
+   * Delay before the first retry, in milliseconds.
+   *
+   * @default 1000
+   */
+  readonly baseDelayMilliseconds?: number;
+  /**
+   * Maximum computed delay, in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly maxDelayMilliseconds?: number;
+  /**
+   * Multiplier applied after each failed attempt.
+   *
+   * @default 2
+   */
+  readonly factor?: number;
+}
+/**
+ * Context passed to custom retry wait functions.
+ *
+ * @since 0.5.0
+ */
+interface DelayContext<TProviderId extends string = string> {
+  /**
+   * Attempt that just failed.
+   */
+  readonly attempt: number;
+  /**
+   * Attempt that will run after this delay.
+   */
+  readonly nextAttempt: number;
+  /**
+   * Maximum configured attempts.
+   */
+  readonly maxAttempts: number;
+  /**
+   * Delay to wait before retrying, in milliseconds.
+   */
+  readonly delayMilliseconds: number;
+  /**
+   * Failed receipt that caused the retry, when the transport returned one.
+   */
+  readonly receipt?: Receipt<TProviderId> & {
+    readonly successful: false;
+  };
+  /**
+   * Thrown error that caused the retry, when the transport rejected.
+   */
+  readonly error?: unknown;
+  /**
+   * Why the delay is being applied.
+   */
+  readonly reason: "retry" | "sendMany-throttle";
+}
+/**
+ * Function used to wait between attempts or throttled sends.
+ *
+ * @param context Information about the delay being applied.
+ * @param signal Abort signal that should cancel the wait.
+ * @returns A promise that resolves when the delay is complete.
+ * @throws {DOMException} If the wait is aborted.
+ * @since 0.5.0
+ */
+type WaitFunction<TProviderId extends string = string> = (context: DelayContext<TProviderId>, signal?: AbortSignal) => Promise<void>;
+/**
+ * Function that decides whether a failure should be retried.
+ *
+ * @param failure Failed receipt or thrown error.
+ * @returns Whether another attempt should be made.
+ * @since 0.5.0
+ */
+type RetryClassifier<TProviderId extends string = string> = (failure: (Receipt<TProviderId> & {
+  readonly successful: false;
+}) | unknown) => boolean;
+/**
+ * Retry behavior for `sendMany()`.
+ *
+ * @since 0.5.0
+ */
+interface SendManyRetryConfig {
+  /**
+   * Maximum number of messages to send at the same time.
+   *
+   * @default 1
+   */
+  readonly maxConcurrent?: number;
+  /**
+   * Minimum delay between launching message sends, in milliseconds.
+   *
+   * @default 0
+   */
+  readonly intervalMilliseconds?: number;
+}
+/**
+ * Configuration for the retry transport decorator.
+ *
+ * @since 0.5.0
+ */
+interface RetryConfig<TProviderId extends string = string> {
+  /**
+   * Total number of send attempts, including the first one.
+   *
+   * @default 3
+   */
+  readonly maxAttempts?: number;
+  /**
+   * Exponential backoff settings.
+   */
+  readonly backoff?: BackoffConfig;
+  /**
+   * Jitter mode applied to computed backoff delays.
+   *
+   * `Retry-After` delays are not jittered.
+   *
+   * @default "full"
+   */
+  readonly jitter?: JitterConfig;
+  /**
+   * Random number source for jitter.
+   *
+   * @default Math.random
+   */
+  readonly random?: () => number;
+  /**
+   * Custom retry classifier.
+   */
+  readonly shouldRetry?: RetryClassifier<TProviderId>;
+  /**
+   * Custom wait function for tests or host-controlled scheduling.
+   */
+  readonly wait?: WaitFunction<TProviderId>;
+  /**
+   * Retry and throttling behavior for `sendMany()`.
+   */
+  readonly sendMany?: SendManyRetryConfig;
+}
+/**
+ * Resolved retry configuration with defaults applied.
+ *
+ * @since 0.5.0
+ */
+interface ResolvedRetryConfig<TProviderId extends string = string> {
+  readonly maxAttempts: number;
+  readonly backoff: Required<BackoffConfig>;
+  readonly jitter: JitterConfig;
+  readonly random: () => number;
+  readonly shouldRetry?: RetryClassifier<TProviderId>;
+  readonly wait: WaitFunction<TProviderId>;
+  readonly sendMany: Required<SendManyRetryConfig>;
+}
+/**
+ * Creates a resolved retry configuration.
+ *
+ * @param config Retry configuration.
+ * @returns The resolved configuration.
+ * @throws {RangeError} If a numeric option is out of range.
+ * @since 0.5.0
+ */
+//#endregion
+//#region src/retry-transport.d.ts
+/**
+ * Transport decorator that retries transient delivery failures.
+ *
+ * @since 0.5.0
+ */
+declare class RetryTransport<TProviderId extends string = string> implements Transport<TProviderId>, AsyncDisposable {
+  readonly id: TProviderId;
+  /**
+   * Resolved retry configuration.
+   */
+  readonly config: ResolvedRetryConfig<TProviderId>;
+  private readonly wrappedTransport;
+  /**
+   * Creates a retrying transport around another transport.
+   *
+   * @param transport The transport to wrap.
+   * @param config Retry configuration.
+   * @throws {RangeError} If retry configuration is invalid.
+   */
+  constructor(transport: Transport<TProviderId>, config?: RetryConfig<TProviderId>);
+  /**
+   * Sends one message, retrying retryable failures.
+   *
+   * @param message The message to send.
+   * @param options Optional transport options.
+   * @returns The final delivery receipt.
+   * @throws {DOMException} If the operation is aborted.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
+  /**
+   * Sends messages with per-message retry behavior.
+   *
+   * Receipts are yielded in the same order as input messages.
+   *
+   * @param messages Messages to send.
+   * @param options Optional transport options.
+   * @returns An async iterable of receipts.
+   * @throws {DOMException} If the operation is aborted.
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId>>;
+  /**
+   * Disposes the wrapped transport when it supports disposal.
+   *
+   * @since 0.5.0
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+  private withSuccessMetadata;
+  private withFailureMetadata;
+  private shouldRetryReceipt;
+  private shouldRetryError;
+  private hasRetryableError;
+  private calculateDelay;
+  private waitBeforeRetry;
+  private waitBetweenSendMany;
+  private createThrownFailure;
+}
+/**
+ * Creates a retrying transport around another transport.
+ *
+ * @param baseTransport The transport to wrap.
+ * @param config Retry configuration.
+ * @returns A retrying transport decorator.
+ * @throws {RangeError} If retry configuration is invalid.
+ * @since 0.5.0
+ */
+declare function createRetryTransport<TProviderId extends string = string>(baseTransport: Transport<TProviderId>, config?: RetryConfig<TProviderId>): RetryTransport<TProviderId>;
+//#endregion
+export { BackoffConfig, DelayContext, JitterConfig, RetryClassifier, RetryConfig, RetryTransport, SendManyRetryConfig, WaitFunction, createRetryTransport };

package/dist/index.d.ts

@@ -0,0 +1,246 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/config.d.ts
+
+/**
+ * Jitter mode for computed retry delays.
+ *
+ * @since 0.5.0
+ */
+type JitterConfig = false | "none" | "full";
+/**
+ * Exponential backoff settings for retry delays.
+ *
+ * @since 0.5.0
+ */
+interface BackoffConfig {
+  /**
+   * Delay before the first retry, in milliseconds.
+   *
+   * @default 1000
+   */
+  readonly baseDelayMilliseconds?: number;
+  /**
+   * Maximum computed delay, in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly maxDelayMilliseconds?: number;
+  /**
+   * Multiplier applied after each failed attempt.
+   *
+   * @default 2
+   */
+  readonly factor?: number;
+}
+/**
+ * Context passed to custom retry wait functions.
+ *
+ * @since 0.5.0
+ */
+interface DelayContext<TProviderId extends string = string> {
+  /**
+   * Attempt that just failed.
+   */
+  readonly attempt: number;
+  /**
+   * Attempt that will run after this delay.
+   */
+  readonly nextAttempt: number;
+  /**
+   * Maximum configured attempts.
+   */
+  readonly maxAttempts: number;
+  /**
+   * Delay to wait before retrying, in milliseconds.
+   */
+  readonly delayMilliseconds: number;
+  /**
+   * Failed receipt that caused the retry, when the transport returned one.
+   */
+  readonly receipt?: Receipt<TProviderId> & {
+    readonly successful: false;
+  };
+  /**
+   * Thrown error that caused the retry, when the transport rejected.
+   */
+  readonly error?: unknown;
+  /**
+   * Why the delay is being applied.
+   */
+  readonly reason: "retry" | "sendMany-throttle";
+}
+/**
+ * Function used to wait between attempts or throttled sends.
+ *
+ * @param context Information about the delay being applied.
+ * @param signal Abort signal that should cancel the wait.
+ * @returns A promise that resolves when the delay is complete.
+ * @throws {DOMException} If the wait is aborted.
+ * @since 0.5.0
+ */
+type WaitFunction<TProviderId extends string = string> = (context: DelayContext<TProviderId>, signal?: AbortSignal) => Promise<void>;
+/**
+ * Function that decides whether a failure should be retried.
+ *
+ * @param failure Failed receipt or thrown error.
+ * @returns Whether another attempt should be made.
+ * @since 0.5.0
+ */
+type RetryClassifier<TProviderId extends string = string> = (failure: (Receipt<TProviderId> & {
+  readonly successful: false;
+}) | unknown) => boolean;
+/**
+ * Retry behavior for `sendMany()`.
+ *
+ * @since 0.5.0
+ */
+interface SendManyRetryConfig {
+  /**
+   * Maximum number of messages to send at the same time.
+   *
+   * @default 1
+   */
+  readonly maxConcurrent?: number;
+  /**
+   * Minimum delay between launching message sends, in milliseconds.
+   *
+   * @default 0
+   */
+  readonly intervalMilliseconds?: number;
+}
+/**
+ * Configuration for the retry transport decorator.
+ *
+ * @since 0.5.0
+ */
+interface RetryConfig<TProviderId extends string = string> {
+  /**
+   * Total number of send attempts, including the first one.
+   *
+   * @default 3
+   */
+  readonly maxAttempts?: number;
+  /**
+   * Exponential backoff settings.
+   */
+  readonly backoff?: BackoffConfig;
+  /**
+   * Jitter mode applied to computed backoff delays.
+   *
+   * `Retry-After` delays are not jittered.
+   *
+   * @default "full"
+   */
+  readonly jitter?: JitterConfig;
+  /**
+   * Random number source for jitter.
+   *
+   * @default Math.random
+   */
+  readonly random?: () => number;
+  /**
+   * Custom retry classifier.
+   */
+  readonly shouldRetry?: RetryClassifier<TProviderId>;
+  /**
+   * Custom wait function for tests or host-controlled scheduling.
+   */
+  readonly wait?: WaitFunction<TProviderId>;
+  /**
+   * Retry and throttling behavior for `sendMany()`.
+   */
+  readonly sendMany?: SendManyRetryConfig;
+}
+/**
+ * Resolved retry configuration with defaults applied.
+ *
+ * @since 0.5.0
+ */
+interface ResolvedRetryConfig<TProviderId extends string = string> {
+  readonly maxAttempts: number;
+  readonly backoff: Required<BackoffConfig>;
+  readonly jitter: JitterConfig;
+  readonly random: () => number;
+  readonly shouldRetry?: RetryClassifier<TProviderId>;
+  readonly wait: WaitFunction<TProviderId>;
+  readonly sendMany: Required<SendManyRetryConfig>;
+}
+/**
+ * Creates a resolved retry configuration.
+ *
+ * @param config Retry configuration.
+ * @returns The resolved configuration.
+ * @throws {RangeError} If a numeric option is out of range.
+ * @since 0.5.0
+ */
+//#endregion
+//#region src/retry-transport.d.ts
+/**
+ * Transport decorator that retries transient delivery failures.
+ *
+ * @since 0.5.0
+ */
+declare class RetryTransport<TProviderId extends string = string> implements Transport<TProviderId>, AsyncDisposable {
+  readonly id: TProviderId;
+  /**
+   * Resolved retry configuration.
+   */
+  readonly config: ResolvedRetryConfig<TProviderId>;
+  private readonly wrappedTransport;
+  /**
+   * Creates a retrying transport around another transport.
+   *
+   * @param transport The transport to wrap.
+   * @param config Retry configuration.
+   * @throws {RangeError} If retry configuration is invalid.
+   */
+  constructor(transport: Transport<TProviderId>, config?: RetryConfig<TProviderId>);
+  /**
+   * Sends one message, retrying retryable failures.
+   *
+   * @param message The message to send.
+   * @param options Optional transport options.
+   * @returns The final delivery receipt.
+   * @throws {DOMException} If the operation is aborted.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
+  /**
+   * Sends messages with per-message retry behavior.
+   *
+   * Receipts are yielded in the same order as input messages.
+   *
+   * @param messages Messages to send.
+   * @param options Optional transport options.
+   * @returns An async iterable of receipts.
+   * @throws {DOMException} If the operation is aborted.
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId>>;
+  /**
+   * Disposes the wrapped transport when it supports disposal.
+   *
+   * @since 0.5.0
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+  private withSuccessMetadata;
+  private withFailureMetadata;
+  private shouldRetryReceipt;
+  private shouldRetryError;
+  private hasRetryableError;
+  private calculateDelay;
+  private waitBeforeRetry;
+  private waitBetweenSendMany;
+  private createThrownFailure;
+}
+/**
+ * Creates a retrying transport around another transport.
+ *
+ * @param baseTransport The transport to wrap.
+ * @param config Retry configuration.
+ * @returns A retrying transport decorator.
+ * @throws {RangeError} If retry configuration is invalid.
+ * @since 0.5.0
+ */
+declare function createRetryTransport<TProviderId extends string = string>(baseTransport: Transport<TProviderId>, config?: RetryConfig<TProviderId>): RetryTransport<TProviderId>;
+//#endregion
+export { BackoffConfig, DelayContext, JitterConfig, RetryClassifier, RetryConfig, RetryTransport, SendManyRetryConfig, WaitFunction, createRetryTransport };

package/dist/index.js

@@ -0,0 +1,304 @@
+import { classifyReceiptError, createFailedReceipt, createReceiptError } from "@upyo/core";
+
+//#region src/config.ts
+/**
+* Creates a resolved retry configuration.
+*
+* @param config Retry configuration.
+* @returns The resolved configuration.
+* @throws {RangeError} If a numeric option is out of range.
+* @since 0.5.0
+*/
+function createRetryConfig(config = {}) {
+	const maxAttempts = config.maxAttempts ?? 3;
+	const baseDelayMilliseconds = config.backoff?.baseDelayMilliseconds ?? 1e3;
+	const maxDelayMilliseconds = config.backoff?.maxDelayMilliseconds ?? 3e4;
+	const factor = config.backoff?.factor ?? 2;
+	const maxConcurrent = config.sendMany?.maxConcurrent ?? 1;
+	const intervalMilliseconds = config.sendMany?.intervalMilliseconds ?? 0;
+	assertIntegerAtLeast(maxAttempts, 1, "maxAttempts");
+	assertFiniteAtLeast(baseDelayMilliseconds, 0, "backoff.baseDelayMilliseconds");
+	assertFiniteAtLeast(maxDelayMilliseconds, 0, "backoff.maxDelayMilliseconds");
+	assertFiniteAtLeast(factor, 1, "backoff.factor");
+	assertIntegerAtLeast(maxConcurrent, 1, "sendMany.maxConcurrent");
+	assertFiniteAtLeast(intervalMilliseconds, 0, "sendMany.intervalMilliseconds");
+	return {
+		maxAttempts,
+		backoff: {
+			baseDelayMilliseconds,
+			maxDelayMilliseconds,
+			factor
+		},
+		jitter: config.jitter ?? "full",
+		random: config.random ?? Math.random,
+		shouldRetry: config.shouldRetry,
+		wait: config.wait ?? defaultWait,
+		sendMany: {
+			maxConcurrent,
+			intervalMilliseconds
+		}
+	};
+}
+async function defaultWait(context, signal) {
+	signal?.throwIfAborted();
+	if (context.delayMilliseconds <= 0) return;
+	await new Promise((resolve, reject) => {
+		const cleanup = () => signal?.removeEventListener("abort", abort);
+		const timeout = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, context.delayMilliseconds);
+		const abort = () => {
+			clearTimeout(timeout);
+			cleanup();
+			reject(createAbortError());
+		};
+		if (signal?.aborted) {
+			abort();
+			return;
+		}
+		signal?.addEventListener("abort", abort, { once: true });
+	});
+}
+function assertIntegerAtLeast(value, minimum, name) {
+	if (!Number.isInteger(value) || value < minimum) throw new RangeError(`${name} must be an integer greater than or equal to ${minimum}.`);
+}
+function assertFiniteAtLeast(value, minimum, name) {
+	if (!Number.isFinite(value) || value < minimum) throw new RangeError(`${name} must be greater than or equal to ${minimum}.`);
+}
+function createAbortError() {
+	return new DOMException("The operation was aborted.", "AbortError");
+}
+
+//#endregion
+//#region src/retry-transport.ts
+/**
+* Transport decorator that retries transient delivery failures.
+*
+* @since 0.5.0
+*/
+var RetryTransport = class {
+	id;
+	/**
+	* Resolved retry configuration.
+	*/
+	config;
+	wrappedTransport;
+	/**
+	* Creates a retrying transport around another transport.
+	*
+	* @param transport The transport to wrap.
+	* @param config Retry configuration.
+	* @throws {RangeError} If retry configuration is invalid.
+	*/
+	constructor(transport, config = {}) {
+		this.wrappedTransport = transport;
+		this.id = transport.id;
+		this.config = createRetryConfig(config);
+	}
+	/**
+	* Sends one message, retrying retryable failures.
+	*
+	* @param message The message to send.
+	* @param options Optional transport options.
+	* @returns The final delivery receipt.
+	* @throws {DOMException} If the operation is aborted.
+	*/
+	async send(message, options) {
+		options?.signal?.throwIfAborted();
+		let lastThrownError;
+		for (let attempt = 1; attempt <= this.config.maxAttempts; attempt++) {
+			options?.signal?.throwIfAborted();
+			try {
+				const receipt = await this.wrappedTransport.send(message, options);
+				if (receipt.successful) return this.withSuccessMetadata(receipt, attempt);
+				const failedReceipt = this.withFailureMetadata(receipt, attempt);
+				if (attempt >= this.config.maxAttempts || !this.shouldRetryReceipt(failedReceipt)) return failedReceipt;
+				await this.waitBeforeRetry({
+					attempt,
+					nextAttempt: attempt + 1,
+					maxAttempts: this.config.maxAttempts,
+					delayMilliseconds: this.calculateDelay(attempt, failedReceipt),
+					receipt: failedReceipt,
+					reason: "retry"
+				}, options?.signal);
+			} catch (error) {
+				options?.signal?.throwIfAborted();
+				lastThrownError = error;
+				if (attempt >= this.config.maxAttempts || !this.shouldRetryError(error)) return this.createThrownFailure(error, attempt);
+				await this.waitBeforeRetry({
+					attempt,
+					nextAttempt: attempt + 1,
+					maxAttempts: this.config.maxAttempts,
+					delayMilliseconds: this.calculateDelay(attempt),
+					error,
+					reason: "retry"
+				}, options?.signal);
+			}
+		}
+		return this.createThrownFailure(lastThrownError, this.config.maxAttempts);
+	}
+	/**
+	* Sends messages with per-message retry behavior.
+	*
+	* Receipts are yielded in the same order as input messages.
+	*
+	* @param messages Messages to send.
+	* @param options Optional transport options.
+	* @returns An async iterable of receipts.
+	* @throws {DOMException} If the operation is aborted.
+	*/
+	async *sendMany(messages, options) {
+		const iterator = toAsyncIterator(messages);
+		const inFlight = /* @__PURE__ */ new Map();
+		const completed = /* @__PURE__ */ new Map();
+		let inputDone = false;
+		let nextLaunchIndex = 0;
+		let nextYieldIndex = 0;
+		const launchNext = async () => {
+			if (inputDone) return;
+			options?.signal?.throwIfAborted();
+			const next = await iterator.next();
+			if (next.done) {
+				inputDone = true;
+				return;
+			}
+			const index = nextLaunchIndex++;
+			if (index > 0) await this.waitBetweenSendMany(options?.signal);
+			const promise = this.send(next.value, options).then((receipt) => ({
+				index,
+				successful: true,
+				receipt
+			}), (error) => ({
+				index,
+				successful: false,
+				error
+			}));
+			inFlight.set(index, promise);
+		};
+		const launchAvailable = async () => {
+			while (!inputDone && inFlight.size < this.config.sendMany.maxConcurrent) await launchNext();
+		};
+		try {
+			await launchAvailable();
+			while (inFlight.size > 0 || completed.has(nextYieldIndex)) {
+				while (completed.has(nextYieldIndex)) {
+					const result$1 = completed.get(nextYieldIndex);
+					completed.delete(nextYieldIndex);
+					if (result$1 == null) break;
+					if (!result$1.successful) throw result$1.error;
+					yield result$1.receipt;
+					nextYieldIndex++;
+					await launchAvailable();
+				}
+				if (inFlight.size <= 0) break;
+				const result = await Promise.race(inFlight.values());
+				inFlight.delete(result.index);
+				completed.set(result.index, result);
+				if (result.index !== nextYieldIndex) await launchAvailable();
+			}
+		} finally {
+			if (!inputDone) await iterator.return?.();
+		}
+	}
+	/**
+	* Disposes the wrapped transport when it supports disposal.
+	*
+	* @since 0.5.0
+	*/
+	async [Symbol.asyncDispose]() {
+		const asyncDisposable = this.wrappedTransport;
+		const asyncDispose = asyncDisposable[Symbol.asyncDispose];
+		if (typeof asyncDispose === "function") {
+			await asyncDispose.call(asyncDisposable);
+			return;
+		}
+		const disposable = this.wrappedTransport;
+		const dispose = disposable[Symbol.dispose];
+		if (typeof dispose === "function") dispose.call(disposable);
+	}
+	withSuccessMetadata(receipt, attempts) {
+		return {
+			...receipt,
+			provider: receipt.provider ?? this.id,
+			attempts
+		};
+	}
+	withFailureMetadata(receipt, attempts) {
+		return {
+			...receipt,
+			provider: receipt.provider ?? this.id,
+			retryable: receipt.retryable ?? this.hasRetryableError(receipt.errors),
+			attempts
+		};
+	}
+	shouldRetryReceipt(receipt) {
+		if (this.config.shouldRetry != null) return this.config.shouldRetry(receipt);
+		if (receipt.retryable != null) return receipt.retryable;
+		return this.hasRetryableError(receipt.errors);
+	}
+	shouldRetryError(error) {
+		if (this.config.shouldRetry != null) return this.config.shouldRetry(error);
+		return classifyReceiptError(error).retryable;
+	}
+	hasRetryableError(errors) {
+		return errors?.some((error) => error.retryable) ?? false;
+	}
+	calculateDelay(attempt, receipt) {
+		const retryAfterMilliseconds = getRetryAfterMilliseconds(receipt);
+		const cappedRetryAfter = retryAfterMilliseconds == null ? void 0 : Math.min(retryAfterMilliseconds, this.config.backoff.maxDelayMilliseconds);
+		if (cappedRetryAfter != null) return cappedRetryAfter;
+		const computedDelay = Math.min(this.config.backoff.baseDelayMilliseconds * Math.pow(this.config.backoff.factor, attempt - 1), this.config.backoff.maxDelayMilliseconds);
+		if (this.config.jitter === false || this.config.jitter === "none") return computedDelay;
+		return Math.floor(this.config.random() * computedDelay);
+	}
+	waitBeforeRetry(context, signal) {
+		return this.config.wait(context, signal);
+	}
+	waitBetweenSendMany(signal) {
+		const delayMilliseconds = this.config.sendMany.intervalMilliseconds;
+		if (delayMilliseconds <= 0) return Promise.resolve();
+		return this.config.wait({
+			attempt: 0,
+			nextAttempt: 0,
+			maxAttempts: this.config.maxAttempts,
+			delayMilliseconds,
+			reason: "sendMany-throttle"
+		}, signal);
+	}
+	createThrownFailure(error, attempts) {
+		const message = error instanceof Error ? error.message : String(error);
+		const classification = classifyReceiptError(error);
+		return createFailedReceipt(createReceiptError(message, {
+			provider: this.id,
+			category: classification.category,
+			code: classification.code,
+			retryable: classification.retryable
+		}), {
+			provider: this.id,
+			attempts
+		});
+	}
+};
+/**
+* Creates a retrying transport around another transport.
+*
+* @param baseTransport The transport to wrap.
+* @param config Retry configuration.
+* @returns A retrying transport decorator.
+* @throws {RangeError} If retry configuration is invalid.
+* @since 0.5.0
+*/
+function createRetryTransport(baseTransport, config = {}) {
+	return new RetryTransport(baseTransport, config);
+}
+function getRetryAfterMilliseconds(receipt) {
+	const receiptDelay = receipt?.errors?.map((error) => error.retryAfterMilliseconds).find((delay) => delay != null);
+	return receiptDelay;
+}
+async function* toAsyncIterator(values) {
+	for await (const value of values) yield value;
+}
+
+//#endregion
+export { RetryTransport, createRetryTransport };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@upyo/retry",
+  "version": "0.5.0-dev.0",
+  "description": "Retry and backoff decorator transport for Upyo email library",
+  "keywords": [
+    "email",
+    "mail",
+    "retry",
+    "backoff",
+    "rate-limit"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://upyo.org/transports/retry",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/upyo.git",
+    "directory": "packages/retry/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/upyo/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@upyo/core": "0.5.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.7",
+    "typescript": "5.8.3"
+  },
+  "scripts": {
+    "prepublish": "mise run --no-deps :build"
+  }
+}