📦 cache-api-local

A simple file-based caching wrapper for HTTP APIs using Node.js — ideal for prototyping, testing, and reducing redundant API calls.

🚀 Features

• ⚡ Fast Local Caching: Save API responses to the filesystem as .json files for quick retrieval.
• ⏱ Cache Expiration: Automatically refreshes data after a configurable maxAge (in seconds).
• 🔒 Safe File Naming: Sanitizes URL paths and query strings into valid, unique filenames.
• 🔄 Auto Fallback: If a live fetch fails, falls back to the most recent cached copy.
• 🧪 Test-Friendly: Easy to plug into testing pipelines or local dev environments.

📥 Installation

npm install cache-api-local

🧪 Example Usage

import CacheApi from "cache-api-local";

const api = new CacheApi("https://jsonplaceholder.typicode.com", "data", 300);

// Fetches from API (and caches)
const data1 = await api.getData("/photos/1?t=12", "photo");

// Within 300 seconds, this fetches from cache
const data2 = await api.getData("/photos/1?t=12", "photo");

console.log(data2);

🧰 Constructor

new CacheApi(baseUrl: string, cacheFolderName: string, maxAgeInSeconds?: number)

Parameters:

| Name | Type | Description | | ----------------- | -------- | ---------------------------------------------------- | | baseUrl | string | The base API URL (e.g. https://api.example.com) | | cacheFolderName | string | Folder (relative to caller) where cache is stored | | maxAgeInSeconds | number | Optional. Time after which cache is considered stale |

📂 How It Works

• Responses are saved as JSON files under the specified folder.
• URLs are converted to safe filenames (e.g. /posts/1?v=alpha → posts_1_v=alpha.json).
• Metadata is stored in .meta.json files to track freshness.
• If data is older than maxAge, it fetches fresh data and updates the cache.
• If fetching fails, it tries using the cached version.

✅ Good Use Cases

• Avoid rate-limiting or repeated API calls in development.
• Improve speed of integration tests.
• Work offline with previously fetched data.

🧼 Cache Cleanup

All cached data is stored under the directory you specify (e.g. data/, project_cache/), and can be safely deleted if needed.

📌 Notes

• Works in Node.js environments (not for browser).
• You can set maxAge to a large value (or leave it out) to avoid expiry.

🧱 Example Project Structure

my-project/
├── src/
│   └── index.ts
├── data/
│   └── photo/
│       └── photos_1_t=12.json
└── ...

📃 License

MIT © You