opticore-cache 1.0.0 → 1.0.2

package/README.md

@@ -1,39 +1,34 @@
 # opticore-cache
 
-### Enterprise‑grade Universal HTTP Cache for OptiCoreJs and also Node.js 
+### Enterprise‑grade Universal HTTP Cache for OptiCoreJs and 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)
+version](https://img.shields.io/npm/v/opticore-cache.svg)](https://www.npmjs.com/package/opticore-cache)
+[![license](https://img.shields.io/npm/l/opticore-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**
-:::
+High‑performance, flexible and production‑ready HTTP caching layer\
+compatible with **Express · Fetch · Axios · Native Node HTTP · cURL**
 
 
-
-# 📑 Table of Contents
+# 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)
+-   [HttpCacheFactory Usage](#HttpCacheFactory-Usage)
+-   [Configuration Options](#Configuration-Options)
+-   [Advanced Usage](#Advanced-Usage)
 -   [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?
+# Why opticore-cache?
 
 Modern applications require:
 
@@ -43,23 +38,21 @@ Modern applications require:
 -   Observability & metrics
 -   Flexible storage strategies
 
-`@opticore/http-cache` provides a **unified abstraction layer** over
-multiple HTTP clients with an extensible and configurable caching
-engine.
-
+`opticore-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
+-   Automatic HTTP response caching
+-   Multi-client support (Fetch, Axios, Node HTTP, cURL)
+-   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
+-   Instance lifecycle management (create / destroy)
 
 
 
@@ -69,7 +62,7 @@ engine.
 npm install opticore-cache
 ```
 
-### Optional Dependencies
+Optional dependencies:
 
 ``` bash
 npm install axios express
@@ -78,212 +71,515 @@ npm install axios express
 
 # Quick Start
 
-## Express Middleware (Zero‑Config)
-
 ``` ts
-import express from "express";
-import { createExpressMiddleware } from "opticore-cache";
+import { HttpCacheFactory } from "opticore-cache";
 
-const app = express();
+const cache = HttpCacheFactory.create("my-app");
 
-app.use(createExpressMiddleware({
-  cache: { ttl: 60000 }
-}));
+const data = await cache.getWithCache("https://api.example.com/users");
 
-app.get("/users/:id", (req, res) => {
-  res.json({ id: req.params.id, name: "John Doe" });
-});
-
-app.listen(3000);
+console.log(data);
 ```
 
 
+# [HttpCacheFactory Usage
 
-# 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" }
-  }
-};
-```
-
+The `HttpCacheFactory` is responsible for:
 
+-   Creating configured cache instances
+-   Managing instance reuse
+-   Supporting multiple HTTP clients
+-   Destroying instances when needed
+-   Adapting existing cache services
 
-# Usage Examples
 
-## Fetch Client
+## Create with Fetch (default)
 
 ``` ts
-import { HttpCacheFactory } from "@opticore/http-cache";
-
-const cache = HttpCacheFactory.create("my-app", {
+const cache = HttpCacheFactory.create("app-fetch", {
   clientType: "fetch",
   storageType: "disk",
-  diskDir: "./storage/cache/my-app",
+  diskDir: "./storage/cache",
   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
+## Create with Axios
 
 ``` ts
-const cache = HttpCacheFactory.create("axios-app", {
+const axiosCache = HttpCacheFactory.create("app-axios", {
   clientType: "axios",
   clientOptions: {
     baseURL: "https://jsonplaceholder.typicode.com",
     timeout: 5000
   }
 });
-
-const data = await cache.getWithCache("/users/1");
 ```
 
 
+## Create with Node HTTP
 
-# API Reference
+``` ts
+const nodeCache = HttpCacheFactory.create("app-node", {
+  clientType: "node-http",
+  clientOptions: {
+    timeout: 8000
+  }
+});
+```
 
-## Factory
+
+## Create with cURL
 
 ``` ts
-HttpCacheFactory.create(appName: string, config?: HttpCacheConfig)
+const curlCache = HttpCacheFactory.create("app-curl", {
+  clientType: "curl",
+  clientOptions: {
+    timeout: 10000
+  }
+});
 ```
 
-Returns: `IHttpCacheService`
 
+## Destroy an Instance
 
+``` ts
+HttpCacheFactory.destroy("app-fetch", "fetch");
+```
 
-## Core Methods
 
-### getWithCache`<T>`()
+## Adapt Existing Cache
 
 ``` ts
-getWithCache<T>(
-  url: string,
-  options?: RequestInit,
-  cacheOptions?: {
-    timeToLive?: number;
-    customKey?: string;
-    bypassCache?: boolean;
-    namespace?: string;
-  }
-): Promise<T>
+const adapted = HttpCacheFactory.createFromExistingCache(
+  customCacheService,
+  "custom-namespace"
+);
 ```
 
 
+## Configuration Options
 
-### postWithCache`<T>`()
+When creating an instance of the HTTP cache service using `HttpCacheFactory.create()`, you can pass an options object to customize its behavior. Below are the available options:
 
-Optional response caching for POST requests.
+| Option      | Type               | Description                                                                                                 | Exemple                                                  |
+|-------------|--------------------|-------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
+| storageType | 'memory' ou 'disk' | Defines the storage type: in-memory (faster, volatile) or on disk (persistent).                             | 'disk'                                                   |
+| diskDir     | string             | Required if `storageType: 'disk'`. Path to the directory where cache files will be stored.                  | 'src/core/cache/app'                                     |
+| defaultTTL  | number             | Default time-to-live for cache entries (in milliseconds). Used if no `timeToLive` is provided in a request. | 60000 (1 minute)                                         |
+| maxSize     | number             | Maximum number of entries in the cache. When exceeded, the oldest entries are removed (LRU).                | 100                                                      |
+| namespace   | string             | (Optional) Namespace used to isolate cache keys. Useful when using multiple instances.                      | 'external-api'                                           |
+| serializer  | object             | (Optional) Overrides the default serialization/deserialization functions (JSON by default).                 | {{ serialize: JSON.stringify, deserialize: JSON.parse }} |
 
 
+### Example initialization with all options:
 
-### invalidateCache(pattern: string)
+```typescript
+const httpCache = HttpCacheFactory.create('external-api', {
+    storageType: 'disk',
+    diskDir: 'src/core/cache/demo',
+    defaultTTL: 10000,        // 10 secondes
+    maxSize: 100,
+    namespace: 'api-v1'
+});
+```
 
-Wildcard invalidation:
 
-``` ts
-await cache.invalidateCache("users:*");
+# Advanced Usage
+
+The `IHttpCacheService` service offers several advanced features for fine-grained HTTP cache control.
+
+---
+
+## 1. Per-Request Cache Bypass
+
+You can bypass the cache for a specific request using the `bypassCache` option. This forces an API call and updates the cache with the new response.
+
+```typescript
+const cacheOptions = {
+    bypassCache: req.query.bypass === 'true',  // e.g. ?bypass=true
+    timeToLive: 60000
+};
+const data = await httpCache.getWithCache(url, {}, cacheOptions);
+```
+
+---
+
+## 2. Custom Time-To-Live
+
+The `timeToLive` option lets you define a custom expiration duration for a specific request, overriding the default value.
+
+---
+
+## 3. Caching POST Requests
+
+The `postWithCache` method allows you to cache the response of a POST request. This can be useful when the API always returns the same response for identical input data.
+
+```typescript
+const response = await httpCache.postWithCache(
+    url,
+    { title, body, userId },  // request body
+    {},                       // additional headers
+    true,                     // cache the response
+    { timeToLive: 30000 }     // cache options
+);
+```
+
+---
+
+## 4. Pattern-Based Invalidation
+
+You can invalidate all cache entries whose key matches a given pattern. This is useful for refreshing a set of related resources.
+
+```typescript
+const countExact   = await httpCache.invalidateCache('/posts/42');  // Invalidates an exact key
+const countPattern = await httpCache.invalidateCache('/posts/*');   // Invalidates all keys starting with /posts/
+```
+
+---
+
+## 5. Cache Statistics
+
+Retrieve information about the current state of the cache (number of entries, size, etc.).
+
+```typescript
+const stats = await httpCache.getStats();
+console.log(stats);
+// Example output:
+// { size: 45, maxSize: 100, hits: 120, misses: 30, ... }
+```
+
+---
+
+## 6. Full Cache Flush
+
+To completely clear the cache (all entries), use:
+
+```typescript
+await httpCache.clearHttpCache();
 ```
 
+---
+
+## 7. Response Metadata
+
+Every object returned by `getWithCache` or `postWithCache` includes a `_metadata` property containing information about the origin of the data.
+
+```typescript
+const data = await httpCache.getWithCache(url);
+console.log(data._metadata);
+// {
+//   source: 'cache' | 'api',
+//   cached: boolean,
+//   createdAt: timestamp,
+//   ttl: number
+// }
+```
 
+---
 
-### clearHttpCache()
+## 8. Error Handling
 
-Clears all entries.
+The service encapsulates both network errors and cache errors. You can intercept them as shown in the controller example.
 
+---
 
+## 9. Usage with Dynamic Parameters
 
-### getStats()
+Build the URL with variable parameters (such as `postId`) to create unique cache keys per resource.
+
+```typescript
+const url = `https://api.example.com/posts/${postId}`;
+```
+
+## Complete example 
+```typescript
+export class UserController {
+    private httpCache: IHttpCacheService;
+
+    constructor() {
+        this.httpCache = HttpCacheFactory.create('external-api', {
+            storageType: 'disk',
+            diskDir: 'src/core/cache/demo',
+            defaultTTL: 10000,
+            maxSize: 100
+        });
+    }
+
+    public async getPostById(req: Request, res: Response) {
+        const postId = req.params.id;
+        const bypassCache = req.query.bypass === 'true'; // Allows bypassing the cache with ?bypass=true
+
+        try {
+            const url = `https://jsonplaceholder.typicode.com/posts/${postId}`;
+
+            const cacheOptions = {
+                bypassCache: bypassCache,
+                timeToLive: 60000 // 1 minute (or use the default value)
+            };
+
+            console.log(`Requête pour le post ${postId}, bypass: ${bypassCache}`);
+
+            const post = await this.httpCache.getWithCache(url, {}, cacheOptions);
+
+            // Add information about the source (cache or API)
+            const source = post?._metadata?.source || 'unknown';
+            const cached = post?._metadata?.cached || false;
+
+            res.json({
+                success: true,
+                data: post,
+                source: source,
+                cached: cached,
+                timestamp: new Date().toISOString()
+            });
+
+        } catch (error: any) {
+            console.error(`Erreur lors de la récupération du post ${postId}:`, error);
+            res.status(500).json({
+                success: false,
+                error: error.message
+            });
+        }
+    }
+
+    // Method to retrieve comments for a post, using cache
+    public async getCommentsByPostId(req: Request, res: Response) {
+        const postId = req.params.id;
+        const bypassCache = req.query.bypass === 'true';
+
+        try {
+            const url = `https://jsonplaceholder.typicode.com/posts/${postId}/comments`;
+
+            const cacheOptions = {
+                bypassCache: bypassCache,
+                timeToLive: 300000 // 5 minutes
+            };
+
+            const comments: unknown = await this.httpCache.getWithCache(url, {}, cacheOptions);
+            
+            const source: any = comments?._metadata ? comments?._metadata.source : 'unknown';
+            const cached: any = comments?._metadata ? comments?._metadata?.cached : false;
+
+            res.json({
+                success: true,
+                data: comments,
+                source: source,
+                cached: cached,
+                count: Array.isArray(comments) ? comments.length : 1,
+                timestamp: new Date().toISOString()
+            });
+
+        } catch (error: any) {
+            console.error(`Erreur pour les commentaires du post ${postId}:`, error);
+            res.status(500).json({
+                success: false,
+                error: error.message
+            });
+        }
+    }
+
+    // Method for making a POST request with optional caching
+    public async createPost(req: Request, res: Response) {
+        const { title, body, userId, cacheResponse } = req.body;
+        try {
+            const url = 'https://jsonplaceholder.typicode.com/posts';
+            const response = await this.httpCache.postWithCache(
+                url,
+                { title, body, userId },
+                {},
+                cacheResponse || true,
+                { timeToLive: 30000 }
+            );
+            res.json({
+                success: true,
+                data: response,
+                cached: cacheResponse || false,
+                timestamp: new Date().toISOString()
+            });
+        } catch (error: any) {
+            console.error('Erreur création de post:', error);
+            res.status(500).json({
+                success: false,
+                error: error.message
+            });
+        }
+    }
+
+    // Method for obtaining HTTP cache statistics
+    public async getCacheStats(req: Request, res: Response) {
+        try {
+            const stats = await this.httpCache.getStats();
+            res.json(stats);
+        } catch (error: any) {
+            res.status(500).json({
+                success: false,
+                error: error.message
+            });
+        }
+    }
+
+    // Method to clear the HTTP cache
+    public async clearHttpCache(req: Request, res: Response) {
+        try {
+            await this.httpCache.clearHttpCache();
+            res.json({
+                success: true,
+                message: 'Cache HTTP vidé avec succès',
+                timestamp: new Date().toISOString()
+            });
+        } catch (error: any) {
+            res.status(500).json({
+                success: false,
+                error: error.message
+            });
+        }
+    }
+
+    // Method to invalidate a pattern in the HTTP cache
+    public async invalidateCachePattern(req: Request, res: Response) {
+        const pattern = req.query.pattern as string;
+        if (!pattern) {
+            return res.status(400).json({
+                success: false,
+                error: 'Le paramètre "pattern" est requis'
+            });
+        }
+
+        try {
+            const count = await this.httpCache.invalidateCache(pattern);
+            res.json({
+                success: true,
+                message: `Cache invalidé pour le pattern: ${pattern}`,
+                invalidatedCount: count,
+                timestamp: new Date().toISOString()
+            });
+        } catch (error: any) {
+            res.status(500).json({
+                success: false,
+                error: error.message
+            });
+        }
+    }
+} 
+```
+
+
+
+# API Reference
+
+## Factory
 
 ``` ts
-interface HttpCacheStats {
-  totalRequests: number;
-  cacheHits: number;
-  cacheMisses: number;
-  cacheSize: number;
-  hitRate: number;
-  cachedUrls: string[];
-  timestamp: string;
-  enabled: boolean;
-}
+HttpCacheFactory.create(appName?: string, config?)
 ```
 
+Returns: `IHttpCacheService`
 
 
-# Cache Strategy & Architecture
 
-Supported storage strategies:
+## Core Methods
 
-Strategy   Use Case
-  ---------- ----------------------------------
-memory     High-speed, short-lived cache
-disk       Persistent cache across restarts
-hybrid     Memory-first with disk fallback
+### getWithCache
 
-### Hybrid Mode
+``` ts
+await cache.getWithCache("https://api.example.com/data");
+```
 
--   Memory lookup first
--   Disk fallback
--   Background refresh supported
+### postWithCache
 
+``` ts
+await cache.postWithCache("https://api.example.com/data", payload, {}, true);
+```
 
+### invalidateCache
 
-# Performance Considerations
+``` ts
+await cache.invalidateCache("users:*");
+```
 
--   Reduces outbound API calls
--   Improves P95 & P99 latency
--   Reduces infrastructure cost
--   Prevents API rate-limit exhaustion
+### clearHttpCache
 
-Recommended for:
+``` ts
+await cache.clearHttpCache();
+```
 
--   Microservices
--   SaaS platforms
--   Multi-tenant APIs
--   Serverless environments
+### getStats
 
+``` ts
+const stats = await cache.getStats();
+console.log(stats.hitRate);
+```
 
 
 # Testing
 
 ``` bash
-npm test
+Run the example project by this command :
+tsx example/src/bootstrap.ts
+
+then run :
+
+Method POST :
+curl -X POST "http://localhost:4200/api/users/posts" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://jsonplaceholder.typicode.com/posts",
+    "data": {
+      "title": "test",
+      "body": "content",
+      "userId": 2
+    },
+    "cacheResponse": true
+  }'
+  
+  
+  Response : 
+  {
+      "success":true,
+      "data": {
+          "id": 101,
+          "_metadata": {
+              "cached": true,
+              "timestamp": "2026-02-20T10:56:25.444Z",
+              "url": "https://jsonplaceholder.typicode.com/posts",
+              "method": "POST", 
+              "responseTime":433
+          }
+      },
+      "cached": true,
+      "timestamp": "2026-02-20T10:56:25.444Z"
+  }
+  
+  
+  Method GET
+  curl -X GET "http://localhost:4200/api/users/posts/1"
+  
+  Response :
+  {
+  "success": true,
+  "data": {
+    "userId": 1,
+    "id": 1,
+    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
+    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto",
+    "_metadata": {
+      "cached": false,
+      "timestamp": "2026-02-20T14:20:38.751Z",
+      "url": "https://jsonplaceholder.typicode.com/posts/1",
+      "method": "GET",
+      "responseTime": 103,
+      "cacheHit": false
+    }
+  },
+  "source": "unknown",
+  "cached": false,
+  "timestamp": "2026-02-20T14:20:38.751Z"
+}
 ```
 
 
-
 # Security
 
 -   No automatic caching of sensitive headers
@@ -292,13 +588,11 @@ npm test
 -   Safe retry mechanism
 
 
-
 # License
 
 MIT
 
 
-
 # Contributing
 
 Contributions are welcome.
@@ -308,7 +602,4 @@ Contributions are welcome.
 3.  Submit a Pull Request
 
 
-
-:::
-Built for scalable OptiCoreJs and any Node.js applications
-:::
+Built for scalable OptiCoreJs and Node.js applications.