ai-retry 0.3.0 → 0.4.1

package/README.md

@@ -171,6 +171,39 @@ const retryable = createRetryable({
 });
 ```
 
+#### Retry After Delay
+
+Handle retryable errors with delays and respect `retry-after` headers from rate-limited responses. This is useful for handling 429 (Too Many Requests) and 503 (Service Unavailable) errors.
+
+> [!NOTE] 
+> If the response contains a [`retry-after`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After) header, it will be prioritized over the configured delay.
+
+
+```typescript
+import { retryAfterDelay } from 'ai-retry/retryables';
+
+const retryableModel = createRetryable({
+  model: openai('gpt-4'), // Base model
+  retries: [
+    // Retry base model 3 times with fixed 2s delay
+    retryAfterDelay({ delay: 2000, maxAttempts: 3 }),
+
+    // Or retry with exponential backoff (2s, 4s, 8s)
+    retryAfterDelay({ delay: 2000, backoffFactor: 2, maxAttempts: 3 }),
+    
+    // Or switch to a different model after delay
+    retryAfterDelay(openai('gpt-4-mini'), { delay: 1000 }),
+  ],
+});
+```
+
+**Options:**
+- `delay` (required): Delay in milliseconds before retrying
+- `backoffFactor` (optional): Multiplier for exponential backoff (delay × backoffFactor^attempt). If not provided, uses fixed delay.
+- `maxAttempts` (optional): Maximum number of retry attempts for this model
+
+By default, if a [`retry-after-ms`](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/provisioned-get-started#what-should--i-do-when-i-receive-a-429-response) or `retry-after` header is present in the response, it will be prioritized over the configured delay. The delay from the header will be capped at 60 seconds for safety. If no headers are present, the configured delay or exponential backoff will be used.
+
 #### Fallbacks
 
 If you always want to fallback to a different model on any error, you can simply provide a list of models.
@@ -247,6 +280,8 @@ try {
 }
 ```
 
+### Options
+
 #### Retry Delays
 
 You can add delays before retrying to handle rate limiting or give services time to recover. The delay respects abort signals, so requests can still be cancelled during the delay period.
@@ -267,6 +302,13 @@ const retryableModel = createRetryable({
     }),
   ],
 });
+
+const result = await generateText({
+  model: retryableModel,
+  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+  // Will be respected during delays
+  abortSignal: AbortSignal.timeout(60_000), 
+});
 ```
 
 You can also use delays with built-in retryables:
@@ -283,6 +325,26 @@ const retryableModel = createRetryable({
 });
 ```
 
+#### Max Attempts
+
+By default, each retryable will only attempt to retry once per model to avoid infinite loops. You can customize this behavior by returning a `maxAttempts` value from your retryable function. Note that the initial request with the base model is counted as the first attempt.
+
+```typescript
+const retryableModel = createRetryable({
+  model: openai('gpt-4'),
+  retries: [
+    // Try this once
+    anthropic('claude-3-haiku-20240307'), 
+    // Try this one more time (initial + 1 retry)
+    () => ({ model: openai('gpt-4'), maxAttempts: 2 }), 
+    // Already tried, won't be retried again
+    anthropic('claude-3-haiku-20240307') 
+  ],
+});
+```
+
+The attempts are counted per unique model (provider + modelId). That means if multiple retryables return the same model, it won't be retried again once the `maxAttempts` is reached.
+
 #### Logging
 
 You can use the following callbacks to log retry attempts and errors:
@@ -321,11 +383,10 @@ There are several built-in retryables:
 - [`contentFilterTriggered`](./src/retryables/content-filter-triggered.ts): Content filter was triggered based on the prompt or completion.
 - [`requestTimeout`](./src/retryables/request-timeout.ts): Request timeout occurred.
 - [`requestNotRetryable`](./src/retryables/request-not-retryable.ts): Request failed with a non-retryable error.
+- [`retryAfterDelay`](./src/retryables/retry-after-delay.ts): Retry with exponential backoff and respect `retry-after` headers for rate limiting.
 - [`serviceOverloaded`](./src/retryables/service-overloaded.ts): Response with status code 529 (service overloaded).
   - Use this retryable to handle Anthropic's overloaded errors.
 
-By default, each retryable will only attempt to retry once per model to avoid infinite loops. You can customize this behavior by returning a `maxAttempts` value from your retryable function.
-
 ### API Reference
 
 #### `createRetryable(options: RetryableModelOptions): LanguageModelV2 | EmbeddingModelV2`

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { EmbeddingModelV2, EmbeddingModelV2CallOptions, EmbeddingModelV2Embed, LanguageModelV2, LanguageModelV2Generate, LanguageModelV2Stream, Retries, RetryAttempt, RetryContext, RetryErrorAttempt, RetryModel, RetryResultAttempt, Retryable, RetryableModelOptions } from "./types-BrJaHkFh.js";
+import * as _ai_sdk_provider0 from "@ai-sdk/provider";
+import { LanguageModelV2StreamPart } from "@ai-sdk/provider";
 
 //#region src/create-retryable-model.d.ts
 declare function createRetryable<MODEL extends LanguageModelV2>(options: RetryableModelOptions<MODEL>): LanguageModelV2;
@@ -10,4 +12,56 @@ declare function createRetryable<MODEL extends EmbeddingModelV2>(options: Retrya
  */
 declare const getModelKey: (model: LanguageModelV2 | EmbeddingModelV2) => string;
 //#endregion
-export { EmbeddingModelV2, EmbeddingModelV2CallOptions, EmbeddingModelV2Embed, LanguageModelV2, LanguageModelV2Generate, LanguageModelV2Stream, Retries, RetryAttempt, RetryContext, RetryErrorAttempt, RetryModel, RetryResultAttempt, Retryable, RetryableModelOptions, createRetryable, getModelKey };
+//#region src/utils.d.ts
+declare const isObject: (value: unknown) => value is Record<string, unknown>;
+declare const isString: (value: unknown) => value is string;
+declare const isStreamResult: (result: LanguageModelV2Generate | LanguageModelV2Stream) => result is LanguageModelV2Stream;
+declare const isGenerateResult: (result: LanguageModelV2Generate | LanguageModelV2Stream) => result is LanguageModelV2Generate;
+/**
+ * Type guard to check if a retry attempt is an error attempt
+ */
+declare function isErrorAttempt(attempt: RetryAttempt<any>): attempt is RetryErrorAttempt<any>;
+/**
+ * Type guard to check if a retry attempt is a result attempt
+ */
+declare function isResultAttempt(attempt: RetryAttempt<any>): attempt is RetryResultAttempt;
+/**
+ * Check if a stream part is a content part (e.g., text delta, reasoning delta, source, tool call, tool result).
+ * These types are also emitted by `onChunk` callbacks.
+ * @see https://github.com/vercel/ai/blob/1fe4bd4144bff927f5319d9d206e782a73979ccb/packages/ai/src/generate-text/stream-text.ts#L686-L697
+ */
+declare const isStreamContentPart: (part: LanguageModelV2StreamPart) => part is _ai_sdk_provider0.LanguageModelV2Source | _ai_sdk_provider0.LanguageModelV2ToolCall | {
+  type: "tool-result";
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+  isError?: boolean;
+  providerExecuted?: boolean;
+  providerMetadata?: _ai_sdk_provider0.SharedV2ProviderMetadata;
+} | {
+  type: "text-delta";
+  id: string;
+  providerMetadata?: _ai_sdk_provider0.SharedV2ProviderMetadata;
+  delta: string;
+} | {
+  type: "reasoning-delta";
+  id: string;
+  providerMetadata?: _ai_sdk_provider0.SharedV2ProviderMetadata;
+  delta: string;
+} | {
+  type: "tool-input-start";
+  id: string;
+  toolName: string;
+  providerMetadata?: _ai_sdk_provider0.SharedV2ProviderMetadata;
+  providerExecuted?: boolean;
+} | {
+  type: "tool-input-delta";
+  id: string;
+  delta: string;
+  providerMetadata?: _ai_sdk_provider0.SharedV2ProviderMetadata;
+} | {
+  type: "raw";
+  rawValue: unknown;
+};
+//#endregion
+export { EmbeddingModelV2, EmbeddingModelV2CallOptions, EmbeddingModelV2Embed, LanguageModelV2, LanguageModelV2Generate, LanguageModelV2Stream, Retries, RetryAttempt, RetryContext, RetryErrorAttempt, RetryModel, RetryResultAttempt, Retryable, RetryableModelOptions, createRetryable, getModelKey, isErrorAttempt, isGenerateResult, isObject, isResultAttempt, isStreamContentPart, isStreamResult, isString };

package/dist/index.js

@@ -1,17 +1,8 @@
-import { isErrorAttempt, isGenerateResult, isResultAttempt, isStreamContentPart } from "./utils-lRsC105f.js";
+import { getModelKey, isErrorAttempt, isGenerateResult, isObject, isResultAttempt, isStreamContentPart, isStreamResult, isString } from "./utils-Dojn0elD.js";
 import { delay } from "@ai-sdk/provider-utils";
 import { getErrorMessage } from "@ai-sdk/provider";
 import { RetryError } from "ai";
 
-//#region src/get-model-key.ts
-/**
-* Generate a unique key for a LanguageModelV2 instance.
-*/
-const getModelKey = (model) => {
-	return `${model.provider}/${model.modelId}`;
-};
-
-//#endregion
 //#region src/find-retry-model.ts
 /**
 * Find the next model to retry with based on the retry context
@@ -415,4 +406,4 @@ function createRetryable(options) {
 }
 
 //#endregion
-export { createRetryable, getModelKey };
+export { createRetryable, getModelKey, isErrorAttempt, isGenerateResult, isObject, isResultAttempt, isStreamContentPart, isStreamResult, isString };

package/dist/retryables/index.d.ts

@@ -21,6 +21,19 @@ declare function requestNotRetryable<MODEL extends LanguageModelV2 | EmbeddingMo
  */
 declare function requestTimeout<MODEL extends LanguageModelV2 | EmbeddingModelV2>(model: MODEL, options?: Omit<RetryModel<MODEL>, 'model'>): Retryable<MODEL>;
 //#endregion
+//#region src/retryables/retry-after-delay.d.ts
+type RetryAfterDelayOptions<MODEL extends LanguageModelV2 | EmbeddingModelV2> = Omit<RetryModel<MODEL>, 'model' | 'delay'> & {
+  delay: number;
+  backoffFactor?: number;
+};
+/**
+ * Retry with the same or a different model if the error is retryable with a delay.
+ * Uses the `Retry-After` or `Retry-After-Ms` headers if present.
+ * Otherwise uses the specified `delay`, or exponential backoff if `backoffFactor` is provided.
+ */
+declare function retryAfterDelay<MODEL extends LanguageModelV2 | EmbeddingModelV2>(model: MODEL, options?: RetryAfterDelayOptions<MODEL>): Retryable<MODEL>;
+declare function retryAfterDelay<MODEL extends LanguageModelV2 | EmbeddingModelV2>(options: RetryAfterDelayOptions<MODEL>): Retryable<MODEL>;
+//#endregion
 //#region src/retryables/service-overloaded.d.ts
 /**
  * Fallback to a different model if the provider returns an overloaded error.
@@ -31,4 +44,4 @@ declare function requestTimeout<MODEL extends LanguageModelV2 | EmbeddingModelV2
  */
 declare function serviceOverloaded<MODEL extends LanguageModelV2 | EmbeddingModelV2>(model: MODEL, options?: Omit<RetryModel<MODEL>, 'model'>): Retryable<MODEL>;
 //#endregion
-export { contentFilterTriggered, requestNotRetryable, requestTimeout, serviceOverloaded };
+export { contentFilterTriggered, requestNotRetryable, requestTimeout, retryAfterDelay, serviceOverloaded };

package/dist/retryables/index.js

@@ -1,4 +1,4 @@
-import { isErrorAttempt, isObject, isResultAttempt, isString } from "../utils-lRsC105f.js";
+import { getModelKey, isErrorAttempt, isObject, isResultAttempt, isString } from "../utils-Dojn0elD.js";
 import { isAbortError } from "@ai-sdk/provider-utils";
 import { APICallError } from "ai";
 
@@ -69,6 +69,68 @@ function requestTimeout(model, options) {
 	};
 }
 
+//#endregion
+//#region src/calculate-exponential-backoff.ts
+/**
+* Calculates the exponential backoff delay.
+*/
+function calculateExponentialBackoff(baseDelay, backoffFactor, attempts) {
+	return baseDelay * backoffFactor ** attempts;
+}
+
+//#endregion
+//#region src/parse-retry-headers.ts
+function parseRetryHeaders(headers) {
+	if (!headers) return null;
+	const retryAfterMs = headers["retry-after-ms"];
+	if (retryAfterMs) {
+		const delayMs = Number.parseFloat(retryAfterMs);
+		if (!Number.isNaN(delayMs) && delayMs >= 0) return delayMs;
+	}
+	const retryAfter = headers["retry-after"];
+	if (retryAfter) {
+		const seconds = Number.parseFloat(retryAfter);
+		if (!Number.isNaN(seconds)) return seconds * 1e3;
+		const date = Date.parse(retryAfter);
+		if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+	}
+	return null;
+}
+
+//#endregion
+//#region src/retryables/retry-after-delay.ts
+const MAX_RETRY_AFTER_MS = 6e4;
+function retryAfterDelay(modelOrOptions, options) {
+	const model = modelOrOptions && "delay" in modelOrOptions ? void 0 : modelOrOptions;
+	const opts = modelOrOptions && "delay" in modelOrOptions ? modelOrOptions : options;
+	if (!opts?.delay) throw new Error("retryAfterDelay: delay is required");
+	const delay$1 = opts.delay;
+	const backoffFactor = Math.max(opts.backoffFactor ?? 1, 1);
+	return (context) => {
+		const { current, attempts } = context;
+		if (isErrorAttempt(current)) {
+			const { error } = current;
+			if (APICallError.isInstance(error) && error.isRetryable === true) {
+				const targetModel = model ?? current.model;
+				const modelKey = getModelKey(targetModel);
+				const modelAttempts = attempts.filter((a) => getModelKey(a.model) === modelKey);
+				const headerDelay = parseRetryHeaders(error.responseHeaders);
+				if (headerDelay !== null) return {
+					model: targetModel,
+					delay: Math.min(headerDelay, MAX_RETRY_AFTER_MS),
+					maxAttempts: opts.maxAttempts
+				};
+				const calculatedDelay = calculateExponentialBackoff(delay$1, backoffFactor, modelAttempts.length);
+				return {
+					model: targetModel,
+					delay: calculatedDelay,
+					maxAttempts: opts.maxAttempts
+				};
+			}
+		}
+	};
+}
+
 //#endregion
 //#region src/retryables/service-overloaded.ts
 /**
@@ -100,4 +162,4 @@ function serviceOverloaded(model, options) {
 }
 
 //#endregion
-export { contentFilterTriggered, requestNotRetryable, requestTimeout, serviceOverloaded };
+export { contentFilterTriggered, requestNotRetryable, requestTimeout, retryAfterDelay, serviceOverloaded };

package/dist/{utils-lRsC105f.js → utils-Dojn0elD.js}

@@ -1,6 +1,16 @@
+//#region src/get-model-key.ts
+/**
+* Generate a unique key for a LanguageModelV2 instance.
+*/
+const getModelKey = (model) => {
+	return `${model.provider}/${model.modelId}`;
+};
+
+//#endregion
 //#region src/utils.ts
 const isObject = (value) => typeof value === "object" && value !== null;
 const isString = (value) => typeof value === "string";
+const isStreamResult = (result) => "stream" in result;
 const isGenerateResult = (result) => "content" in result;
 /**
 * Type guard to check if a retry attempt is an error attempt
@@ -24,4 +34,4 @@ const isStreamContentPart = (part) => {
 };
 
 //#endregion
-export { isErrorAttempt, isGenerateResult, isObject, isResultAttempt, isStreamContentPart, isString };
+export { getModelKey, isErrorAttempt, isGenerateResult, isObject, isResultAttempt, isStreamContentPart, isStreamResult, isString };

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "ai-retry",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "AI SDK Retry",
-  "packageManager": "pnpm@9.0.0",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -18,14 +17,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "prepublishOnly": "pnpm build",
-    "publish:alpha": "pnpm version prerelease --preid alpha && pnpm publish --tag alpha",
-    "build": "tsdown",
-    "test": "vitest",
-    "lint": "biome check . --write",
-    "prepare": "husky"
-  },
   "keywords": [
     "ai",
     "ai-sdk",
@@ -64,5 +55,11 @@
   "dependencies": {
     "@ai-sdk/provider": "^2.0.0",
     "@ai-sdk/provider-utils": "^3.0.9"
+  },
+  "scripts": {
+    "publish:alpha": "pnpm version prerelease --preid alpha && pnpm publish --tag alpha",
+    "build": "tsdown",
+    "test": "vitest",
+    "lint": "biome check . --write"
   }
-}
+}