axios-revalidation-cache 1.0.0

package/README.md

@@ -0,0 +1,362 @@
+# axios-revalidation-cache
+
+Small axios response cache for frontend applications with explicit TTL-based revalidation.
+
+This package is designed for browser apps where you want a simple cache layer in front of `axios.get(...)` without pulling in a larger data-fetching framework.
+
+## What it does
+
+- Returns `network` on the first request.
+- Returns `cache` while the entry is still fresh.
+- Returns `revalidated` after the TTL expires and a new API call refreshes the cached value.
+- Supports manual refresh with `revalidate(...)` when the user clicks refresh or after a mutation.
+- Dedupes concurrent requests for the same key and reports them as `in-flight`.
+
+## Best fit
+
+Use this library when:
+
+- You already use axios in the frontend.
+- You want a lightweight cache for GET requests.
+- You want predictable TTL-based refresh behavior.
+- You prefer keeping cache control in your own service layer.
+
+If you need pagination orchestration, mutations, retries, background sync, devtools, or stale-while-revalidate UX out of the box, a larger library like TanStack Query may still be a better fit.
+
+## Install
+
+```bash
+npm install axios-revalidation-cache axios
+```
+
+## Core idea
+
+```js
+const axios = require("axios");
+const { createAxiosCache } = require("axios-revalidation-cache");
+
+const apiCache = createAxiosCache({
+  client: axios.create({
+    baseURL: "https://jsonplaceholder.typicode.com",
+  }),
+  ttl: 5_000,
+  maxSize: 100,
+});
+
+async function run() {
+  const first = await apiCache.get("/todos/1");
+  console.log(first.meta.source); // network
+
+  const second = await apiCache.get("/todos/1");
+  console.log(second.meta.source); // cache
+
+  await new Promise((resolve) => setTimeout(resolve, 5_100));
+
+  const third = await apiCache.get("/todos/1");
+  console.log(third.meta.source); // revalidated
+
+  const forced = await apiCache.revalidate("/todos/1");
+  console.log(forced.meta.source); // revalidated
+}
+```
+
+## Frontend setup
+
+Create the axios client and cache once, outside your components.
+
+```js
+// api/client.js
+import axios from "axios";
+import { createAxiosCache } from "axios-revalidation-cache";
+
+export const apiClient = axios.create({
+  baseURL: "https://jsonplaceholder.typicode.com",
+  timeout: 8000,
+});
+
+export const apiCache = createAxiosCache({
+  client: apiClient,
+  ttl: 30_000,
+  maxSize: 200,
+});
+```
+
+Important:
+
+- Do not create the cache inside a React component or hook body.
+- Treat the cache as a singleton service in the browser app.
+- Use `revalidate(...)` after actions that make existing cached data stale.
+
+## React example
+
+### Simple service layer
+
+```js
+// api/todos.js
+import { apiCache } from "./client";
+
+export async function getTodo(todoId) {
+  const result = await apiCache.get(`/todos/${todoId}`);
+  return result;
+}
+
+export async function refreshTodo(todoId) {
+  const result = await apiCache.revalidate(`/todos/${todoId}`);
+  return result;
+}
+```
+
+### React component example
+
+```jsx
+// TodoCard.jsx
+import { useEffect, useState } from "react";
+import { getTodo, refreshTodo } from "./api/todos";
+
+export function TodoCard({ todoId }) {
+  const [todo, setTodo] = useState(null);
+  const [source, setSource] = useState("idle");
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function load() {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await getTodo(todoId);
+
+        if (!cancelled) {
+          setTodo(result.data);
+          setSource(result.meta.source);
+        }
+      } catch (requestError) {
+        if (!cancelled) {
+          setError(requestError);
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    }
+
+    load();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [todoId]);
+
+  async function handleRefresh() {
+    setLoading(true);
+    setError(null);
+
+    try {
+      const result = await refreshTodo(todoId);
+      setTodo(result.data);
+      setSource(result.meta.source);
+    } catch (requestError) {
+      setError(requestError);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  if (loading) {
+    return <p>Loading...</p>;
+  }
+
+  if (error) {
+    return <p>Failed to load todo.</p>;
+  }
+
+  return (
+    <section>
+      <h2>{todo.title}</h2>
+      <p>Status: {todo.completed ? "Done" : "Pending"}</p>
+      <p>Source: {source}</p>
+      <button onClick={handleRefresh}>Refresh</button>
+    </section>
+  );
+}
+```
+
+### React custom hook example
+
+```js
+// hooks/useCachedTodo.js
+import { useEffect, useState } from "react";
+import { apiCache } from "../api/client";
+
+export function useCachedTodo(todoId) {
+  const [data, setData] = useState(null);
+  const [meta, setMeta] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function load() {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const result = await apiCache.get(`/todos/${todoId}`);
+
+        if (!cancelled) {
+          setData(result.data);
+          setMeta(result.meta);
+        }
+      } catch (requestError) {
+        if (!cancelled) {
+          setError(requestError);
+        }
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    }
+
+    load();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [todoId]);
+
+  async function revalidate() {
+    setLoading(true);
+    setError(null);
+
+    try {
+      const result = await apiCache.revalidate(`/todos/${todoId}`);
+      setData(result.data);
+      setMeta(result.meta);
+      return result;
+    } catch (requestError) {
+      setError(requestError);
+      throw requestError;
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return {
+    data,
+    meta,
+    loading,
+    error,
+    revalidate,
+  };
+}
+```
+
+## Other frontend libraries
+
+The same pattern works in Vue, Svelte, Solid, or plain JavaScript: keep the cache in a shared module and call it from your store, composable, or service.
+
+```js
+// services/posts.js
+import { apiCache } from "./client";
+
+export function getPost(postId) {
+  return apiCache.get(`/posts/${postId}`);
+}
+
+export function refreshPost(postId) {
+  return apiCache.revalidate(`/posts/${postId}`);
+}
+```
+
+Examples by framework:
+
+- Vue: call the service from a composable like `usePost()`.
+- Svelte: call the service from a store or `load` helper.
+- Solid: call the service inside `createResource`.
+- Plain JS: call the service from event handlers and update the DOM manually.
+
+## When to revalidate
+
+You should call `revalidate(...)` when:
+
+- The TTL has not expired yet, but you know the server data changed.
+- A user clicks a refresh button.
+- A POST, PUT, PATCH, or DELETE likely invalidated the cached GET response.
+- You return to a screen and want guaranteed fresh data instead of a cached value.
+
+Example after a mutation:
+
+```js
+await apiClient.patch(`/todos/${todoId}`, { completed: true });
+await apiCache.revalidate(`/todos/${todoId}`);
+```
+
+## API
+
+### `createAxiosCache(options)`
+
+Creates a cache manager for an axios-compatible client.
+
+Options:
+
+- `client`: Required. Any object with a `get(path, config)` function.
+- `ttl`: Optional. Freshness window in milliseconds. Default `60000`.
+- `maxSize`: Optional. Maximum number of cache entries. Default `100`.
+- `getKey`: Optional. Custom cache key function with signature `(path, config) => string`.
+
+### `cache.get(path, config?, requestOptions?)`
+
+Returns:
+
+```js
+{
+  data,
+  meta: {
+    cacheKey,
+    source, // network | cache | revalidated | in-flight
+    fromCache,
+    deduped,
+    revalidated,
+    cachedAt,
+  },
+}
+```
+
+Notes:
+
+- `config` is passed directly to `axios.get(path, config)`.
+- If the cached entry is still valid, the cached value is returned.
+- If the TTL has expired, `get(...)` makes a fresh API call and updates the cached value.
+- `requestOptions.revalidate = true` forces a fresh request even if the entry is still valid.
+
+### `cache.revalidate(path, config?)`
+
+Bypasses cache, fetches fresh data, and replaces the stored entry.
+
+### `cache.invalidate(path, config?)`
+
+Deletes a single cached entry.
+
+### `cache.clear()`
+
+Deletes all cached entries.
+
+### `cache.size()`
+
+Returns the current number of cache entries.
+
+## Publish checklist
+
+Before publishing, verify:
+
+1. The package name in [package.json](package.json) is available on npm.
+2. The `version` in [package.json](package.json) is correct.
+3. `npm test` passes.
+4. The README reflects your final public API.
+5. `npm publish --access public` is run from the package root.

package/index.js

@@ -0,0 +1,5 @@
+const { createAxiosCache } = require("./src/createAxiosCache");
+
+module.exports = {
+  createAxiosCache,
+};

package/index.mjs

@@ -0,0 +1,4 @@
+import cachePackage from "./index.js";
+
+export const { createAxiosCache } = cachePackage;
+export default cachePackage;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "axios-revalidation-cache",
+  "version": "1.0.0",
+  "description": "A small axios response cache with TTL-based revalidation and manual refresh support.",
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "require": "./index.js",
+      "import": "./index.mjs"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "axios",
+    "frontend",
+    "browser",
+    "cache",
+    "revalidate",
+    "react",
+    "ttl",
+    "http"
+  ],
+  "scripts": {
+    "demo": "node cache.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "axios": "^1.13.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/createAxiosCache.js

@@ -0,0 +1,177 @@
+function createAxiosCache(options = {}) {
+  const {
+    client,
+    ttl = 60_000,
+    maxSize = 100,
+    getKey = defaultGetKey,
+  } = options;
+
+  if (!client || typeof client.get !== "function") {
+    throw new TypeError(
+      "createAxiosCache requires an axios-compatible client with a get method.",
+    );
+  }
+
+  if (!Number.isInteger(maxSize) || maxSize < 1) {
+    throw new TypeError("maxSize must be an integer greater than 0.");
+  }
+
+  if (typeof ttl !== "number" || Number.isNaN(ttl) || ttl < 0) {
+    throw new TypeError("ttl must be a non-negative number.");
+  }
+
+  const cache = new Map();
+
+  function get(path, config = {}, requestOptions = {}) {
+    const cacheKey = getKey(path, config);
+    const existingEntry = cache.get(cacheKey);
+    const forceRefresh = Boolean(requestOptions.revalidate);
+
+    if (!forceRefresh && existingEntry) {
+      if (existingEntry.status === "pending") {
+        return existingEntry.promise.then((data) =>
+          buildResult({
+            cacheKey,
+            data,
+            source: "in-flight",
+            cachedAt: existingEntry.cachedAt,
+          }),
+        );
+      }
+
+      if (!isExpired(existingEntry.cachedAt, ttl)) {
+        touchEntry(existingEntry);
+        return Promise.resolve(
+          buildResult({
+            cacheKey,
+            data: existingEntry.data,
+            source: "cache",
+            cachedAt: existingEntry.cachedAt,
+          }),
+        );
+      }
+    }
+
+    const source = existingEntry ? "revalidated" : "network";
+    return requestAndCache({ cacheKey, path, config, source });
+  }
+
+  function revalidate(path, config = {}) {
+    return get(path, config, { revalidate: true });
+  }
+
+  function invalidate(path, config = {}) {
+    return cache.delete(getKey(path, config));
+  }
+
+  function clear() {
+    cache.clear();
+  }
+
+  function size() {
+    return cache.size;
+  }
+
+  async function requestAndCache({ cacheKey, path, config, source }) {
+    const pendingEntry = {
+      status: "pending",
+      cachedAt: Date.now(),
+      lastAccessedAt: Date.now(),
+      promise: null,
+      data: undefined,
+    };
+
+    cache.delete(cacheKey);
+    cache.set(cacheKey, pendingEntry);
+    trimCache(cache, maxSize);
+
+    const requestPromise = client
+      .get(path, config)
+      .then((response) => response.data);
+
+    pendingEntry.promise = requestPromise;
+
+    try {
+      const data = await requestPromise;
+      pendingEntry.status = "resolved";
+      pendingEntry.data = data;
+      pendingEntry.cachedAt = Date.now();
+      pendingEntry.promise = Promise.resolve(data);
+      touchEntry(pendingEntry);
+
+      return buildResult({
+        cacheKey,
+        data,
+        source,
+        cachedAt: pendingEntry.cachedAt,
+      });
+    } catch (error) {
+      cache.delete(cacheKey);
+      throw error;
+    }
+  }
+
+  return {
+    get,
+    revalidate,
+    invalidate,
+    clear,
+    size,
+  };
+}
+
+function buildResult({ cacheKey, data, source, cachedAt }) {
+  return {
+    data,
+    meta: {
+      cacheKey,
+      source,
+      fromCache: source === "cache",
+      deduped: source === "in-flight",
+      revalidated: source === "revalidated",
+      cachedAt,
+    },
+  };
+}
+
+function isExpired(cachedAt, ttl) {
+  if (ttl === 0) {
+    return true;
+  }
+
+  return Date.now() - cachedAt > ttl;
+}
+
+function touchEntry(entry) {
+  entry.lastAccessedAt = Date.now();
+}
+
+function trimCache(cache, maxSize) {
+  while (cache.size > maxSize) {
+    const oldestKey = cache.keys().next().value;
+    cache.delete(oldestKey);
+  }
+}
+
+function defaultGetKey(path, config = {}) {
+  return `${path}::${stableStringify(config)}`;
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${keys
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+      .join(",")}}`;
+  }
+
+  return JSON.stringify(value);
+}
+
+module.exports = {
+  createAxiosCache,
+};