opticore-cache 1.0.0

package/README.md

@@ -0,0 +1,314 @@
+# opticore-cache
+
+### Enterprise‑grade Universal HTTP Cache for OptiCoreJs and also Node.js 
+
+[![npm
+version](https://img.shields.io/npm/v/@opticore/http-cache.svg)](https://www.npmjs.com/package/opticore-cache)
+[![license](https://img.shields.io/npm/l/@opticore/http-cache.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+
+High‑performance, flexible and production‑ready HTTP caching layer
+compatible with\
+**Express · Fetch · Axios · Native Node HTTP · cURL**
+:::
+
+
+
+# 📑 Table of Contents
+
+-   [Why opticore-cache ?](#why-opticore-cache)
+-   [Key Features](#key-features)
+-   [Installation](#installation)
+-   [Quick Start](#quick-start)
+-   [Configuration](#configuration)
+-   [Usage Examples](#usage-examples)
+-   [API Reference](#api-reference)
+-   [Cache Strategy & Architecture](#cache-strategy--architecture)
+-   [Performance Considerations](#performance-considerations)
+-   [Testing](#testing)
+-   [Security](#security)
+-   [License](#license)
+-   [Contributing](#contributing)
+
+
+
+#  Why opticore-cache?
+
+Modern applications require:
+
+-   High availability
+-   Reduced external API load
+-   Faster response times
+-   Observability & metrics
+-   Flexible storage strategies
+
+`@opticore/http-cache` provides a **unified abstraction layer** over
+multiple HTTP clients with an extensible and configurable caching
+engine.
+
+
+
+# Key Features
+
+-   ✅ Automatic HTTP response caching
+-   ✅ Multi-client support (Fetch, Axios, Node HTTP, cURL, Express middleware)
+-   ✅ Memory, Disk or Hybrid storage
+-   ✅ Per-request TTL override
+-   ✅ Pattern-based invalidation (wildcards supported)
+-   ✅ Built-in statistics & hit-rate tracking
+-   ✅ Namespaces for multi-tenant systems
+-   ✅ TypeScript-first design
+-   ✅ Production-safe retry & timeout handling
+
+
+
+# Installation
+
+``` bash
+npm install opticore-cache
+```
+
+### Optional Dependencies
+
+``` bash
+npm install axios express
+```
+
+
+# Quick Start
+
+## Express Middleware (Zero‑Config)
+
+``` ts
+import express from "express";
+import { createExpressMiddleware } from "opticore-cache";
+
+const app = express();
+
+app.use(createExpressMiddleware({
+  cache: { ttl: 60000 }
+}));
+
+app.get("/users/:id", (req, res) => {
+  res.json({ id: req.params.id, name: "John Doe" });
+});
+
+app.listen(3000);
+```
+
+
+
+# Configuration
+
+## Default Configuration
+
+``` ts
+const defaultConfig = {
+  cache: {
+    enabled: true,
+    ttl: 300000,
+    maxSize: 10000,
+    storage: "disk", // memory | disk | hybrid
+    storageOptions: {
+      diskDir: "./storage/cache/http"
+    }
+  },
+  http: {
+    defaultClient: "fetch",
+    timeout: 30000,
+    retries: 3,
+    retryDelay: 1000
+  },
+  clients: {
+    fetch: { credentials: "omit" },
+    axios: { baseURL: "" },
+    nodeHttp: { keepAlive: true },
+    curl: { binaryPath: "/usr/bin/curl" }
+  }
+};
+```
+
+
+
+# Usage Examples
+
+## Fetch Client
+
+``` ts
+import { HttpCacheFactory } from "@opticore/http-cache";
+
+const cache = HttpCacheFactory.create("my-app", {
+  clientType: "fetch",
+  storageType: "disk",
+  diskDir: "./storage/cache/my-app",
+  defaultTTL: 60000
+});
+
+const user = await cache.getWithCache(
+  "https://jsonplaceholder.typicode.com/users/1",
+  {},
+  { timeToLive: 30000 }
+);
+
+console.log(user._metadata.cached ? "From cache" : "From API");
+```
+
+
+
+## Axios Client
+
+``` ts
+const cache = HttpCacheFactory.create("axios-app", {
+  clientType: "axios",
+  clientOptions: {
+    baseURL: "https://jsonplaceholder.typicode.com",
+    timeout: 5000
+  }
+});
+
+const data = await cache.getWithCache("/users/1");
+```
+
+
+
+# API Reference
+
+## Factory
+
+``` ts
+HttpCacheFactory.create(appName: string, config?: HttpCacheConfig)
+```
+
+Returns: `IHttpCacheService`
+
+
+
+## Core Methods
+
+### getWithCache`<T>`()
+
+``` ts
+getWithCache<T>(
+  url: string,
+  options?: RequestInit,
+  cacheOptions?: {
+    timeToLive?: number;
+    customKey?: string;
+    bypassCache?: boolean;
+    namespace?: string;
+  }
+): Promise<T>
+```
+
+
+
+### postWithCache`<T>`()
+
+Optional response caching for POST requests.
+
+
+
+### invalidateCache(pattern: string)
+
+Wildcard invalidation:
+
+``` ts
+await cache.invalidateCache("users:*");
+```
+
+
+
+### clearHttpCache()
+
+Clears all entries.
+
+
+
+### getStats()
+
+``` ts
+interface HttpCacheStats {
+  totalRequests: number;
+  cacheHits: number;
+  cacheMisses: number;
+  cacheSize: number;
+  hitRate: number;
+  cachedUrls: string[];
+  timestamp: string;
+  enabled: boolean;
+}
+```
+
+
+
+# Cache Strategy & Architecture
+
+Supported storage strategies:
+
+Strategy   Use Case
+  ---------- ----------------------------------
+memory     High-speed, short-lived cache
+disk       Persistent cache across restarts
+hybrid     Memory-first with disk fallback
+
+### Hybrid Mode
+
+-   Memory lookup first
+-   Disk fallback
+-   Background refresh supported
+
+
+
+# Performance Considerations
+
+-   Reduces outbound API calls
+-   Improves P95 & P99 latency
+-   Reduces infrastructure cost
+-   Prevents API rate-limit exhaustion
+
+Recommended for:
+
+-   Microservices
+-   SaaS platforms
+-   Multi-tenant APIs
+-   Serverless environments
+
+
+
+# Testing
+
+``` bash
+npm test
+```
+
+
+
+# Security
+
+-   No automatic caching of sensitive headers
+-   Namespace isolation supported
+-   Manual invalidation available
+-   Safe retry mechanism
+
+
+
+# License
+
+MIT
+
+
+
+# Contributing
+
+Contributions are welcome.
+
+1.  Fork the repository
+2.  Create a feature branch
+3.  Submit a Pull Request
+
+
+
+:::
+Built for scalable OptiCoreJs and any Node.js applications
+:::