@mittwald/axios-cache-with-retry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mittwald CM Service GmbH & Co. KG and contributors
+
+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,185 @@
+# @mittwald/axios-cache-with-retry
+
+Coordinated retry, cache and in-flight dedupe for Axios — as a single adapter
+rather than three interceptors that each re-run the request behind each other's
+back.
+
+Retry and caching cannot be composed out of separate interceptors: a retry is a
+second dispatch, so it re-enters the interceptor chain and every layer around it
+sees a request the caller never made. Combining `axios-retry` with
+`axios-cache-interceptor` therefore multiplies requests instead of deduplicating
+them, and which of the two even gets to see a failure depends on
+`validateStatus`. [Why this exists](#why-this-exists) walks through a concrete
+example.
+
+## Installation
+
+```bash
+npm install @mittwald/axios-cache-with-retry
+```
+
+`axios` is a peer dependency (`^1`).
+
+## Usage
+
+```ts
+import axios from "axios";
+import { setupAxiosRetryCache } from "@mittwald/axios-cache-with-retry";
+
+const client = setupAxiosRetryCache(axios.create(), {
+  requestKey: ({ config }) => `${config.method ?? "get"}:${config.url}`,
+  cache: { ttl: 60_000, staleIfError: true },
+  retry: { retries: 3, retryOnStatus: [408, 429, 500, 502, 503, 504] },
+});
+
+await client.get("/users");
+await client.retryCache.invalidate("get:/users");
+```
+
+The retry decision is made for thrown Axios errors and for regular responses
+alike, so it keeps working under `validateStatus: () => true`.
+
+`setupAxiosRetryCache` replaces the instance's adapter and returns the same
+instance, typed with an added `retryCache` property. Calling it twice on one
+instance re-wraps the original adapter rather than stacking two layers.
+
+## Per-request options
+
+Every request config accepts a `retryCache` field that overrides the global
+options for that one request. The module augments Axios' own
+`AxiosRequestConfig`, so the field is typed wherever `axios` is.
+
+```ts
+await client.get("/users", { retryCache: { retry: { retries: 5 } } });
+await client.get("/metrics", { retryCache: { cache: false } });
+await client.get("/raw", { retryCache: false });
+```
+
+| Value               | Effect                                           |
+| ------------------- | ------------------------------------------------ |
+| `false`             | Bypasses the adapter entirely                    |
+| `true`              | Enables cache and retry with the global settings |
+| `{ cache, retry }`  | Merges into the global settings for this request |
+| `{ dedupe: false }` | Opts this request out of in-flight deduplication |
+
+## Options
+
+### `cache`
+
+| Option         | Default          | Description                                                  |
+| -------------- | ---------------- | ------------------------------------------------------------ |
+| `enabled`      | `true`           | Set to `false` to keep the cache off until a request opts in |
+| `ttl`          | `60000`          | Lifetime of an entry in milliseconds                         |
+| `methods`      | `["get","head"]` | Methods whose responses are cached                           |
+| `staleIfError` | `false`          | Serve an expired entry once retries are exhausted            |
+| `shouldCache`  | —                | Predicate deciding whether a response is stored              |
+
+### `retry`
+
+| Option                | Default                             | Description                                              |
+| --------------------- | ----------------------------------- | -------------------------------------------------------- |
+| `enabled`             | `true`                              | Set to `false` to keep retry off until a request opts in |
+| `retries`             | `2`                                 | Attempts after the initial one                           |
+| `methods`             | `["get","head","options"]`          | Methods that may be retried                              |
+| `retryOnStatus`       | `408, 425, 429, 500, 502, 503, 504` | Status codes that trigger a retry                        |
+| `retryOnNetworkError` | `true`                              | Retry errors that never produced a response              |
+| `respectRetryAfter`   | `true`                              | Honour a `Retry-After` response header                   |
+| `delay`               | exponential, capped at 30 s         | Fixed milliseconds or a function                         |
+| `shouldRetry`         | —                                   | Replaces the built-in decision entirely                  |
+
+### `requestKey`
+
+Cache and dedupe key for a request. Defaults to method, base URL, URL, a stably
+serialized `params` and — for non-`GET`/`HEAD` — a stably serialized body.
+Returning `undefined` excludes the request from both caching and deduplication.
+
+### `storage`
+
+Defaults to an in-memory store. Pass `createMemoryStorage({ maxEntries })` for a
+bounded one, or any object implementing `RetryCacheStorage`; every method may
+return a promise, so an async backend works as well.
+
+## Cache API
+
+`client.retryCache` exposes `get`, `set`, `invalidate`, `invalidatePrefix` and
+`clear`. `invalidatePrefix` needs a storage that implements either
+`deletePrefix` or `keys` — the built-in memory storage implements both.
+
+## Behaviour worth knowing
+
+- **Deduplication wraps the whole operation**, retries included: concurrent
+  callers with the same key wait for one shared result and each receive their
+  own shallow copy.
+- **A cache hit short-circuits before retry**, so a cached response never
+  produces a request.
+- **`staleIfError` only serves an expired entry after retries are exhausted**,
+  never instead of a retry.
+- **Only responses are cached, never errors.**
+
+## Why this exists
+
+Retry, cache and in-flight deduplication are three decisions about the _same_
+request, but an interceptor can only see a request on its way out and a response
+on its way back. It cannot wrap the dispatch itself — and a retry is by
+definition a second dispatch. So an interceptor-based retry has to re-send the
+config, which means re-entering the interceptor chain, which means every other
+layer sees a request the caller never made. Stacking the layers is the only
+composition the interceptor API offers, and both stacking orders are wrong.
+
+The popular packages each solve one third of the problem and sit in a position
+that collides with the others:
+
+- **`axios-retry`** and **`retry-axios`** hook the response (error) path and
+  retry by re-dispatching the request config.
+- **`axios-cache-interceptor`** caches _and_ deduplicates concurrent requests
+  from a request/response interceptor pair, with its own in-flight bookkeeping
+  keyed per request.
+- **`axios-cache-adapter`** (unmaintained) and **`axios-extensions`**
+  (`cacheAdapterEnhancer`, `throttleAdapterEnhancer`) take the adapter position
+  instead — so they cannot coexist with each other, or with anything else that
+  wants to own the adapter.
+
+### Where it snags
+
+Three components ask for `GET /users` at the same time. The endpoint answers
+`503` twice and then `200`. Retry is configured for two extra attempts, and the
+cache layer deduplicates in-flight requests. One logical request, one expected
+outcome: three responses out of three network calls.
+
+**Deduplication inside the retry** (cache layer closest to the request): dedupe
+collapses the three callers onto one dispatch, that dispatch fails with `503`,
+and the rejection fans back out to all three callers — each of which then runs
+its _own_ retry handler, because each call walks the interceptor chain
+separately. Three retry loops instead of one, up to nine network calls for one
+logical `GET`, and whichever loop happens to finish first decides what ends up
+in the cache while the others are still retrying.
+
+**Retry inside the deduplication** (retry layer closest to the request): every
+re-dispatch looks like a brand-new request to the cache layer above it, while
+that layer's in-flight entry for the first attempt is still open and still
+waiting to be settled by an attempt that has already been abandoned. Depending
+on how the cache keys its pending state, the second attempt either registers
+alongside the first — so the entry that gets stored is not the response the
+caller received — or waits on a promise the retry loop is never going to fulfil.
+
+**And the two layers disagree about what a failure is.** Retry lives on the
+error path, the cache lives on the success path, and which one a `503` takes is
+the caller's `validateStatus` setting. Accept non-2xx responses and the retry
+handler is never invoked at all, while the cache stores the `503` and serves it
+for the rest of its TTL.
+
+### What this package does instead
+
+All three concerns live in a single adapter, the one place that _does_ wrap the
+dispatch. One request key is resolved once, and one shared in-flight promise
+covers the entire operation: the cache lookup, the retry loop, and the cache
+write after the final attempt. Concurrent callers wait for that one result
+instead of starting their own loops, retries never re-enter the interceptor
+chain, and the retry decision is made for returned responses and thrown errors
+alike — so `validateStatus` stops being part of the retry semantics. The
+guarantees that follow from it are listed under
+[Behaviour worth knowing](#behaviour-worth-knowing) above.
+
+## License
+
+MIT

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { setupAxiosRetryCache } from "./setup.js";
+export { createMemoryStorage, MemoryRetryCacheStorage } from "./storage.js";

package/dist/esm/key.js

@@ -0,0 +1,58 @@
+export async function resolveRequestKey(key, config) {
+    if (typeof key === "function") {
+        return key({ config });
+    }
+    return defaultRequestKey(config);
+}
+export function defaultRequestKey(config) {
+    const method = (config.method ?? "get").toLowerCase();
+    const baseURL = config.baseURL ?? "";
+    const url = config.url ?? "";
+    const params = stableSerialize(config.params);
+    const data = method === "get" || method === "head" ? "" : stableSerialize(config.data);
+    if (!url) {
+        return undefined;
+    }
+    return [method, baseURL, url, params, data].join(" ");
+}
+export function stableSerialize(value) {
+    if (value === undefined || value === null || value === "") {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (isURLSearchParams(value)) {
+        return serializeURLSearchParams(value);
+    }
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (!isPlainRecord(value)) {
+        return value;
+    }
+    return Object.keys(value)
+        .sort()
+        .reduce((accumulator, key) => {
+        accumulator[key] = sortValue(value[key]);
+        return accumulator;
+    }, {});
+}
+function isPlainRecord(value) {
+    return (typeof value === "object" && value !== null && value.constructor === Object);
+}
+function isURLSearchParams(value) {
+    return (typeof URLSearchParams !== "undefined" && value instanceof URLSearchParams);
+}
+function serializeURLSearchParams(params) {
+    return JSON.stringify(Array.from(params.entries()).sort(([leftKey, leftValue], [rightKey, rightValue]) => {
+        const keyComparison = leftKey.localeCompare(rightKey);
+        if (keyComparison !== 0) {
+            return keyComparison;
+        }
+        return leftValue.localeCompare(rightValue);
+    }));
+}

package/dist/esm/response.js

@@ -0,0 +1,40 @@
+export function snapshotResponse(response) {
+    return {
+        data: response.data,
+        status: response.status,
+        statusText: response.statusText,
+        headers: normalizeHeaders(response.headers),
+    };
+}
+export function responseFromCache(entry, config) {
+    return {
+        data: entry.response.data,
+        status: entry.response.status,
+        statusText: entry.response.statusText,
+        headers: { ...entry.response.headers },
+        config,
+        request: undefined,
+    };
+}
+export function cloneResponse(response) {
+    return {
+        ...response,
+        headers: { ...response.headers },
+        config: { ...response.config },
+    };
+}
+function normalizeHeaders(headers) {
+    if (!headers || typeof headers !== "object") {
+        return {};
+    }
+    const output = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        output[key.toLowerCase()] = Array.isArray(value)
+            ? value.join(", ")
+            : String(value);
+    }
+    return output;
+}

package/dist/esm/retry.js

@@ -0,0 +1,66 @@
+export const DEFAULT_RETRY_STATUS = [408, 425, 429, 500, 502, 503, 504];
+export async function shouldRetry(context, retry) {
+    if (context.attempt > retry.retries) {
+        return false;
+    }
+    if (retry.shouldRetry) {
+        return retry.shouldRetry(context);
+    }
+    const method = (context.config.method ?? "get").toLowerCase();
+    const allowedMethods = retry.methods?.map((value) => value.toLowerCase());
+    if (allowedMethods && !allowedMethods.includes(method)) {
+        return false;
+    }
+    if (context.response) {
+        return (retry.retryOnStatus ?? DEFAULT_RETRY_STATUS).includes(context.response.status);
+    }
+    return (retry.retryOnNetworkError !== false &&
+        isRetryableNetworkError(context.error));
+}
+export async function retryDelay(context, retry) {
+    const retryAfter = retry.respectRetryAfter
+        ? parseRetryAfter(context.response?.headers?.["retry-after"])
+        : undefined;
+    if (retryAfter !== undefined) {
+        return retryAfter;
+    }
+    if (typeof retry.delay === "number") {
+        return retry.delay;
+    }
+    if (typeof retry.delay === "function") {
+        return retry.delay(context);
+    }
+    return Math.min(100 * 2 ** Math.max(context.attempt - 1, 0), 30_000);
+}
+export function sleep(ms) {
+    if (ms <= 0) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function isRetryableNetworkError(error) {
+    if (!error) {
+        return false;
+    }
+    const maybeAxiosError = error;
+    if (maybeAxiosError.response) {
+        return false;
+    }
+    return true;
+}
+function parseRetryAfter(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const seconds = Number(value);
+    if (Number.isFinite(seconds)) {
+        return Math.max(0, seconds * 1000);
+    }
+    const timestamp = Date.parse(value);
+    if (Number.isNaN(timestamp)) {
+        return undefined;
+    }
+    return Math.max(0, timestamp - Date.now());
+}

package/dist/esm/setup.js

@@ -0,0 +1,253 @@
+import axios from "axios";
+import { resolveRequestKey } from "./key.js";
+import { cloneResponse, responseFromCache, snapshotResponse, } from "./response.js";
+import { DEFAULT_RETRY_STATUS, retryDelay, shouldRetry, sleep, } from "./retry.js";
+import { createMemoryStorage, deletePrefix } from "./storage.js";
+const DEFAULT_CACHE = {
+    enabled: true,
+    ttl: 60_000,
+    methods: ["get", "head"],
+    staleIfError: false,
+};
+const DEFAULT_RETRY = {
+    enabled: true,
+    retries: 2,
+    methods: ["get", "head", "options"],
+    retryOnStatus: DEFAULT_RETRY_STATUS,
+    retryOnNetworkError: true,
+    respectRetryAfter: true,
+};
+const installedAdapters = new WeakMap();
+export function setupAxiosRetryCache(instance, options = {}) {
+    const storage = options.storage ?? createMemoryStorage();
+    const originalAdapter = installedAdapters.get(instance) ??
+        axios.getAdapter(instance.defaults.adapter);
+    const inflight = new Map();
+    installedAdapters.set(instance, originalAdapter);
+    instance.defaults.adapter = async (config) => {
+        const requestOptions = config.retryCache;
+        if (requestOptions === false) {
+            return originalAdapter(config);
+        }
+        const effective = resolveEffectiveOptions(options, requestOptions);
+        const method = (config.method ?? "get").toLowerCase();
+        const cacheEnabled = Boolean(effective.cache && methodAllowed(method, effective.cache.methods));
+        const retryEnabled = Boolean(effective.retry);
+        const dedupeEnabled = effective.dedupe !== false;
+        const requestKey = await resolveRequestKey(options.requestKey, config);
+        const cacheKey = requestKey;
+        const dedupeKey = requestKey;
+        if (!cacheEnabled && !retryEnabled) {
+            return originalAdapter(config);
+        }
+        if (cacheEnabled && cacheKey) {
+            const cached = await storage.get(cacheKey);
+            if (cached && isFresh(cached)) {
+                return responseFromCache(cached, config);
+            }
+        }
+        const operation = () => runOperation({
+            adapter: originalAdapter,
+            config,
+            cacheKey,
+            cacheEnabled,
+            retry: effective.retry,
+            cache: effective.cache,
+            staleEntry: cacheEnabled && cacheKey ? storage.get(cacheKey) : undefined,
+            storage,
+        });
+        if (dedupeEnabled && dedupeKey) {
+            const existing = inflight.get(dedupeKey);
+            if (existing) {
+                return cloneResponse(await existing);
+            }
+            const promise = operation().finally(() => {
+                inflight.delete(dedupeKey);
+            });
+            inflight.set(dedupeKey, promise);
+            return cloneResponse(await promise);
+        }
+        return operation();
+    };
+    const client = instance;
+    client.retryCache = {
+        async get(key) {
+            return storage.get(key);
+        },
+        async set(key, response, setOptions = {}) {
+            const now = Date.now();
+            await storage.set(key, {
+                key,
+                createdAt: now,
+                expiresAt: now + (setOptions.ttl ?? normalizeCacheOptions(options.cache).ttl),
+                response: snapshotResponse(response),
+            });
+        },
+        async invalidate(key) {
+            return storage.delete(key);
+        },
+        async invalidatePrefix(prefix) {
+            return deletePrefix(storage, prefix);
+        },
+        async clear() {
+            await storage.clear();
+        },
+    };
+    return client;
+}
+async function runOperation(input) {
+    const staleEntry = await input.staleEntry;
+    let attempt = 1;
+    let lastError;
+    while (true) {
+        try {
+            const response = await input.adapter(input.config);
+            const retryOptions = input.retry;
+            const retry = retryOptions
+                ? await shouldRetry({
+                    attempt,
+                    retries: retryOptions.retries,
+                    config: input.config,
+                    response,
+                }, retryOptions)
+                : false;
+            if (retry && retryOptions) {
+                await sleep(await retryDelay({
+                    attempt,
+                    retries: retryOptions.retries,
+                    config: input.config,
+                    response,
+                }, retryOptions));
+                attempt += 1;
+                continue;
+            }
+            if (input.cacheEnabled &&
+                input.cacheKey &&
+                input.cache &&
+                (await shouldCache(input.cacheKey, input.config, response, input.cache))) {
+                const now = Date.now();
+                await input.storage?.set(input.cacheKey, {
+                    key: input.cacheKey,
+                    createdAt: now,
+                    expiresAt: now + input.cache.ttl,
+                    response: snapshotResponse(response),
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            lastError = error;
+            const axiosError = error;
+            const errorResponse = axiosError?.response;
+            const retryOptions = input.retry;
+            const retry = retryOptions
+                ? await shouldRetry({
+                    attempt,
+                    retries: retryOptions.retries,
+                    config: input.config,
+                    response: errorResponse,
+                    error: error instanceof Error ? error : undefined,
+                }, retryOptions)
+                : false;
+            if (retry && retryOptions) {
+                await sleep(await retryDelay({
+                    attempt,
+                    retries: retryOptions.retries,
+                    config: input.config,
+                    response: errorResponse,
+                    error: error instanceof Error ? error : undefined,
+                }, retryOptions));
+                attempt += 1;
+                continue;
+            }
+            if (input.cache &&
+                input.cache.staleIfError &&
+                staleEntry &&
+                !isFresh(staleEntry)) {
+                return responseFromCache(staleEntry, input.config);
+            }
+            throw lastError;
+        }
+    }
+}
+function resolveEffectiveOptions(globalOptions, requestOptions) {
+    const requestOverrides = requestOptions === true
+        ? { cache: true, retry: true }
+        : typeof requestOptions === "object"
+            ? requestOptions
+            : undefined;
+    const cache = resolveCacheOptions(globalOptions.cache, requestOverrides?.cache);
+    const retry = resolveRetryOptions(globalOptions.retry, requestOverrides?.retry);
+    return {
+        cache,
+        retry,
+        dedupe: requestOverrides?.dedupe ?? globalOptions.dedupe ?? true,
+    };
+}
+function resolveCacheOptions(globalCache, requestCache) {
+    if (requestCache === false) {
+        return false;
+    }
+    if (requestCache === true) {
+        return {
+            ...normalizeCacheOptions(globalCache),
+            enabled: true,
+        };
+    }
+    if (globalCache === false &&
+        (typeof requestCache !== "object" || requestCache.enabled !== true)) {
+        return false;
+    }
+    const cache = {
+        ...normalizeCacheOptions(globalCache),
+        ...definedOptions(requestCache),
+    };
+    return cache.enabled === false ? false : cache;
+}
+function resolveRetryOptions(globalRetry, requestRetry) {
+    if (requestRetry === false) {
+        return false;
+    }
+    if (requestRetry === true) {
+        return {
+            ...normalizeRetryOptions(globalRetry),
+            enabled: true,
+        };
+    }
+    if (globalRetry === false &&
+        (typeof requestRetry !== "object" || requestRetry.enabled !== true)) {
+        return false;
+    }
+    const retry = {
+        ...normalizeRetryOptions(globalRetry),
+        ...definedOptions(requestRetry),
+    };
+    return retry.enabled === false ? false : retry;
+}
+function normalizeCacheOptions(cache) {
+    return {
+        ...DEFAULT_CACHE,
+        ...definedOptions(cache),
+    };
+}
+function normalizeRetryOptions(retry) {
+    return {
+        ...DEFAULT_RETRY,
+        ...definedOptions(retry),
+    };
+}
+function definedOptions(options) {
+    if (!options) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined));
+}
+function shouldCache(key, config, response, cache) {
+    return cache.shouldCache?.({ key, config, response }) ?? true;
+}
+function methodAllowed(method, methods) {
+    return (!methods || methods.map((value) => value.toLowerCase()).includes(method));
+}
+function isFresh(entry) {
+    return entry.expiresAt > Date.now();
+}

package/dist/esm/storage.js

@@ -0,0 +1,73 @@
+export class MemoryRetryCacheStorage {
+    options;
+    entries = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    get(key) {
+        return this.entries.get(key);
+    }
+    set(key, entry) {
+        this.entries.set(key, entry);
+        this.enforceMaxEntries();
+    }
+    delete(key) {
+        return this.entries.delete(key);
+    }
+    clear() {
+        this.entries.clear();
+    }
+    keys() {
+        return this.entries.keys();
+    }
+    deletePrefix(prefix) {
+        let deleted = 0;
+        for (const key of this.entries.keys()) {
+            if (key.startsWith(prefix) && this.entries.delete(key)) {
+                deleted += 1;
+            }
+        }
+        return deleted;
+    }
+    enforceMaxEntries() {
+        const { maxEntries } = this.options;
+        if (!maxEntries || this.entries.size <= maxEntries) {
+            return;
+        }
+        const overflow = this.entries.size - maxEntries;
+        const keys = this.entries.keys();
+        for (let index = 0; index < overflow; index += 1) {
+            const next = keys.next();
+            if (next.done) {
+                return;
+            }
+            this.entries.delete(next.value);
+        }
+    }
+}
+export function createMemoryStorage(options) {
+    return new MemoryRetryCacheStorage(options);
+}
+export async function deletePrefix(storage, prefix) {
+    if (storage.deletePrefix) {
+        return storage.deletePrefix(prefix);
+    }
+    if (!storage.keys) {
+        throw new Error("Storage backend does not support prefix invalidation.");
+    }
+    let deleted = 0;
+    const keys = await storage.keys();
+    for (const key of keys) {
+        if (!key.startsWith(prefix)) {
+            continue;
+        }
+        const didDelete = await storage.delete(key);
+        if (didDelete) {
+            deleted += 1;
+        }
+    }
+    return deleted;
+}
+export async function maybeAwait(value) {
+    return value;
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { setupAxiosRetryCache } from "./setup.js";
+export { createMemoryStorage, MemoryRetryCacheStorage } from "./storage.js";
+export type { AxiosRetryCacheInstance, CacheEntry, CachedResponse, CacheOptions, RequestKeyContext, RetryCacheApi, RetryCacheOptions, RetryCacheRequestKey, RetryCacheRequestOptions, RetryCacheStorage, RetryDecisionContext, RetryDelayContext, RetryOptions, } from "./types.js";

package/dist/types/key.d.ts

@@ -0,0 +1,5 @@
+import type { InternalAxiosRequestConfig } from "axios";
+import type { RetryCacheRequestKey } from "./types.js";
+export declare function resolveRequestKey(key: RetryCacheRequestKey | undefined, config: InternalAxiosRequestConfig): Promise<string | undefined>;
+export declare function defaultRequestKey(config: InternalAxiosRequestConfig): string | undefined;
+export declare function stableSerialize(value: unknown): string;

package/dist/types/response.d.ts

@@ -0,0 +1,5 @@
+import type { AxiosResponse, InternalAxiosRequestConfig } from "axios";
+import type { CacheEntry, CachedResponse } from "./types.js";
+export declare function snapshotResponse(response: AxiosResponse): CachedResponse;
+export declare function responseFromCache(entry: CacheEntry, config: InternalAxiosRequestConfig): AxiosResponse;
+export declare function cloneResponse(response: AxiosResponse): AxiosResponse;

package/dist/types/retry.d.ts

@@ -0,0 +1,5 @@
+import type { RetryDecisionContext, RetryDelayContext, RetryOptions } from "./types.js";
+export declare const DEFAULT_RETRY_STATUS: number[];
+export declare function shouldRetry(context: RetryDecisionContext, retry: RetryOptions): Promise<boolean>;
+export declare function retryDelay(context: RetryDelayContext, retry: RetryOptions): Promise<number>;
+export declare function sleep(ms: number): Promise<void>;

package/dist/types/setup.d.ts

@@ -0,0 +1,3 @@
+import { type AxiosInstance } from "axios";
+import type { AxiosRetryCacheInstance, RetryCacheOptions } from "./types.js";
+export declare function setupAxiosRetryCache(instance: AxiosInstance, options?: RetryCacheOptions): AxiosRetryCacheInstance;

package/dist/types/storage.d.ts

@@ -0,0 +1,19 @@
+import type { Awaitable, CacheEntry, RetryCacheStorage } from "./types.js";
+export interface MemoryStorageOptions {
+    maxEntries?: number;
+}
+export declare class MemoryRetryCacheStorage<T = unknown> implements RetryCacheStorage<T> {
+    private readonly options;
+    private readonly entries;
+    constructor(options?: MemoryStorageOptions);
+    get(key: string): CacheEntry<T> | undefined;
+    set(key: string, entry: CacheEntry<T>): void;
+    delete(key: string): boolean;
+    clear(): void;
+    keys(): Iterable<string>;
+    deletePrefix(prefix: string): number;
+    private enforceMaxEntries;
+}
+export declare function createMemoryStorage<T = unknown>(options?: MemoryStorageOptions): MemoryRetryCacheStorage<T>;
+export declare function deletePrefix(storage: RetryCacheStorage, prefix: string): Promise<number>;
+export declare function maybeAwait<T>(value: Awaitable<T>): Promise<T>;

package/dist/types/types.d.ts

@@ -0,0 +1,86 @@
+import type { AxiosAdapter, AxiosError, AxiosInstance, AxiosResponse, InternalAxiosRequestConfig } from "axios";
+export type Awaitable<T> = T | Promise<T>;
+export type RetryCacheRequestKey = (context: RequestKeyContext) => Awaitable<string | undefined>;
+export interface RequestKeyContext {
+    config: InternalAxiosRequestConfig;
+}
+export interface CacheOptions {
+    enabled?: boolean;
+    ttl: number;
+    methods?: string[];
+    staleIfError?: boolean;
+    shouldCache?: (context: CacheDecisionContext) => Awaitable<boolean>;
+}
+export interface CacheDecisionContext<T = unknown, D = unknown> {
+    key: string;
+    config: InternalAxiosRequestConfig<D>;
+    response: AxiosResponse<T, D>;
+}
+export interface RetryDecisionContext<T = unknown, D = unknown> {
+    attempt: number;
+    retries: number;
+    config: InternalAxiosRequestConfig<D>;
+    response?: AxiosResponse<T, D>;
+    error?: AxiosError<T, D> | Error;
+}
+export type RetryDelayContext<T = unknown, D = unknown> = RetryDecisionContext<T, D>;
+export interface RetryOptions {
+    enabled?: boolean;
+    retries: number;
+    methods?: string[];
+    retryOnStatus?: number[];
+    retryOnNetworkError?: boolean;
+    respectRetryAfter?: boolean;
+    delay?: number | ((context: RetryDelayContext) => Awaitable<number>);
+    shouldRetry?: (context: RetryDecisionContext) => Awaitable<boolean>;
+}
+export interface RetryCacheRequestOptions {
+    cache?: boolean | Partial<CacheOptions>;
+    retry?: boolean | Partial<RetryOptions>;
+    dedupe?: boolean;
+}
+export interface RetryCacheOptions {
+    requestKey?: RetryCacheRequestKey;
+    cache?: false | Partial<CacheOptions>;
+    retry?: false | Partial<RetryOptions>;
+    dedupe?: boolean;
+    storage?: RetryCacheStorage;
+}
+export interface CachedResponse<T = unknown> {
+    data: T;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+}
+export interface CacheEntry<T = unknown> {
+    key: string;
+    createdAt: number;
+    expiresAt: number;
+    response: CachedResponse<T>;
+}
+export interface RetryCacheStorage<T = unknown> {
+    get(key: string): Awaitable<CacheEntry<T> | undefined>;
+    set(key: string, entry: CacheEntry<T>): Awaitable<void>;
+    delete(key: string): Awaitable<boolean>;
+    clear(): Awaitable<void>;
+    keys?(): Awaitable<Iterable<string>>;
+    deletePrefix?(prefix: string): Awaitable<number>;
+}
+export interface RetryCacheApi {
+    get(key: string): Promise<CacheEntry | undefined>;
+    set(key: string, response: AxiosResponse, options?: {
+        ttl?: number;
+    }): Promise<void>;
+    invalidate(key: string): Promise<boolean>;
+    invalidatePrefix(prefix: string): Promise<number>;
+    clear(): Promise<void>;
+}
+export type AxiosRetryCacheInstance = AxiosInstance & {
+    retryCache: RetryCacheApi;
+};
+export type AdapterFactory = (adapter: AxiosAdapter) => AxiosAdapter;
+declare module "axios" {
+    interface AxiosRequestConfig<D = any> {
+        retryCache?: boolean | RetryCacheRequestOptions;
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@mittwald/axios-cache-with-retry",
+  "version": "0.1.0",
+  "packageManager": "pnpm@10.29.2",
+  "author": "Mittwald CM Service GmbH & Co. KG <opensource@mittwald.de>",
+  "contributors": [
+    "Marco Falkenberg <m.falkenberg@mittwald.de>"
+  ],
+  "type": "module",
+  "description": "Coordinated retry, cache and in-flight dedupe for Axios, as a single adapter",
+  "keywords": [
+    "adapter",
+    "axios",
+    "cache",
+    "dedupe",
+    "http",
+    "retry"
+  ],
+  "homepage": "https://github.com/mittwald/axios-cache-with-retry#readme",
+  "repository": "github:mittwald/axios-cache-with-retry",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "pnpm build:clean && pnpm tsc",
+    "build:clean": "rimraf dist",
+    "format": "prettier --write '**/*.{ts,yaml,yml,json,md}'",
+    "test": "pnpm test:tsc && pnpm test:lint && pnpm test:build && pnpm test:vitest",
+    "test:build": "pnpm build",
+    "test:lint": "eslint . --cache",
+    "test:tsc": "tsc --noEmit -p tsconfig.test.json",
+    "test:vitest": "vitest run"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^24.10.12",
+    "axios": "^1.19.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "prettier-plugin-jsdoc": "^1.8.0",
+    "prettier-plugin-pkgsort": "^0.3.0",
+    "prettier-plugin-sort-json": "^4.2.0",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "axios": "^1"
+  }
+}