@jeromeetienne/openai-cache 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerome Etienne
+
+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,43 @@
+# Cache OpenAI
+This is a simple caching layer for OpenAI API requests using local file storage. 
+It helps to reduce redundant API calls by storing responses in a cache directory `./.openai_cache`.
+
+## Usage
+
+```ts
+import OpenAI from "openai";
+import { OpenAICache } from "./src/openai_cache"; // for repo-local usage
+// If published to npm, replace with your package import.
+
+const openaiCache = new OpenAICache({
+  cacheDir: ".cache/openai",
+  debug: true,
+});
+
+const client = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  fetch: openaiCache.getFetchFn(),
+});
+
+const response = await client.responses.create({
+  model: "gpt-4.1-mini",
+  input: "Say hello in one short sentence.",
+});
+
+console.log(response.output_text);
+```
+
+## PRO/CON
+- **PRO**: Reduces redundant API calls, saving time and costs.
+data.
+- **NOTE**: When `temperature === 0`, caching works optimally as responses are deterministic. However, with `temperature > 0`, caching may reduce variety across multiple calls since identical prompts will return cached results instead of generating new varied responses.
+
+
+## Possible improvements
+- dont cache if temporature > 0 or top_p < 1, You’ll freeze randomness if cached
+- implement with keyv https://keyv.org/, instead of custom file system
+  - various storage backends (filesystem, redis, etc)
+  - built in TTL support
+- check errors, and dont cache if error
+  - 429/500 errors should not be cached, but other errors (like invalid request) could be cached to prevent repeated bad requests
+  - tools requests errors should not be cached

package/dist/openai_cache.d.ts

@@ -0,0 +1,38 @@
+import { RequestInfo } from "openai/internal/builtin-types";
+import { Cacheable } from "cacheable";
+/**
+ * OpenAICachingCacheable is a wrapper around the Fetch API that adds caching capabilities for OpenAI requests.
+ * It uses a Cacheable instance to store and retrieve cached responses based on a hash of the request details.
+ */
+export default class OpenAICache {
+    private readonly _cache;
+    constructor(cache?: Cacheable);
+    /**
+     * Cleans the OpenAI cache by deleting all cached values.
+     */
+    cleanCache(): Promise<void>;
+    /**
+     * return a fetch function that can be passed to OpenAI client for caching support
+     *
+     * ```js
+     * const openai = new OpenAI({
+     *   fetch: openaiCache.getFetchFn()
+     * });
+     * ```
+     */
+    getFetchFn(): (input: RequestInfo, init?: RequestInit) => Promise<Response>;
+    /**
+     * This is the fetch() implementation that adds caching for OpenAI requests.
+     *
+     * @param input The resource that you wish to fetch.
+     * @param init An options object containing any custom settings that you want to apply to the request.
+     * @returns A Promise that resolves to the Response to that request.
+     */
+    private _fetch;
+    /**
+     * Remove transfer/content encodings that no longer apply once the body is materialized
+     * and optionally set a correct content-length for the cached payload.
+     */
+    private static _normalizeHeaders;
+    private static _serializeBodyForHash;
+}

package/dist/openai_cache.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// node imports
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_buffer_1 = require("node:buffer");
+const cacheable_1 = require("cacheable");
+/**
+ * OpenAICachingCacheable is a wrapper around the Fetch API that adds caching capabilities for OpenAI requests.
+ * It uses a Cacheable instance to store and retrieve cached responses based on a hash of the request details.
+ */
+class OpenAICache {
+    constructor(cache) {
+        this._cache = cache !== null && cache !== void 0 ? cache : new cacheable_1.Cacheable();
+    }
+    /**
+     * Cleans the OpenAI cache by deleting all cached values.
+     */
+    async cleanCache() {
+        await this._cache.clear();
+    }
+    /**
+     * return a fetch function that can be passed to OpenAI client for caching support
+     *
+     * ```js
+     * const openai = new OpenAI({
+     *   fetch: openaiCache.getFetchFn()
+     * });
+     * ```
+     */
+    getFetchFn() {
+        return this._fetch.bind(this);
+    }
+    /**
+     * This is the fetch() implementation that adds caching for OpenAI requests.
+     *
+     * @param input The resource that you wish to fetch.
+     * @param init An options object containing any custom settings that you want to apply to the request.
+     * @returns A Promise that resolves to the Response to that request.
+     */
+    async _fetch(input, init) {
+        var _a;
+        // Extract the URL from the input (string or Request)
+        const url = typeof input === "string" ? input : input instanceof Request ? input.url : input.toString();
+        // Normalize HTTP method
+        const method = ((init === null || init === void 0 ? void 0 : init.method) || "GET").toUpperCase();
+        // Generate body hash payload
+        const bodyForHash = OpenAICache._serializeBodyForHash(init === null || init === void 0 ? void 0 : init.body);
+        // If body type unsupported, skip caching
+        if (bodyForHash === null)
+            return fetch(input, init);
+        // Build cache key and file path
+        const cacheKey = node_crypto_1.default.createHash("sha256")
+            .update(`${method}:${url}:${bodyForHash}`)
+            .digest("hex");
+        const cached = (await this._cache.get(cacheKey));
+        if (cached !== undefined) {
+            const bodyEncoding = (_a = cached.bodyEncoding) !== null && _a !== void 0 ? _a : "utf8";
+            const cachedBody = node_buffer_1.Buffer.from(cached.body, bodyEncoding);
+            // Return cached response
+            return new Response(cachedBody, {
+                status: cached.status,
+                headers: cached.headers,
+            });
+        }
+        // Perform network fetch
+        const response = await fetch(input, init);
+        const clonedResponse = response.clone();
+        // Materialize response body for caching
+        const responseBuffer = node_buffer_1.Buffer.from(await clonedResponse.arrayBuffer());
+        // Collect headers and normalize them
+        const headers = Array.from(clonedResponse.headers.entries());
+        const normalizedHeaders = OpenAICache._normalizeHeaders(headers, responseBuffer.length);
+        await this._cache.set(cacheKey, {
+            status: clonedResponse.status,
+            headers: normalizedHeaders,
+            body: responseBuffer.toString("base64"),
+            bodyEncoding: "base64",
+        });
+        // Return live response (body already buffered)
+        return new Response(responseBuffer, { status: response.status, headers: normalizedHeaders });
+    }
+    ///////////////////////////////////////////////////////////////////////////////
+    ///////////////////////////////////////////////////////////////////////////////
+    //	Private functions
+    ///////////////////////////////////////////////////////////////////////////////
+    ///////////////////////////////////////////////////////////////////////////////
+    /**
+     * Remove transfer/content encodings that no longer apply once the body is materialized
+     * and optionally set a correct content-length for the cached payload.
+     */
+    static _normalizeHeaders(headers, bodyLength) {
+        const drop = new Set([
+            "content-encoding", // body is already decoded by fetch()
+            "transfer-encoding",
+            "content-length", // will be recalculated
+        ]);
+        const filtered = headers.filter(([name]) => drop.has(name.toLowerCase()) === false);
+        if (bodyLength !== undefined) {
+            filtered.push(["content-length", String(bodyLength)]);
+        }
+        return filtered;
+    }
+    // Serialize body into a deterministic string for hashing
+    static _serializeBodyForHash(body) {
+        if (body === undefined || body === null)
+            return "";
+        if (typeof body === "string")
+            return body;
+        if (node_buffer_1.Buffer.isBuffer(body))
+            return body.toString("base64");
+        if (body instanceof ArrayBuffer)
+            return node_buffer_1.Buffer.from(body).toString("base64");
+        if (ArrayBuffer.isView(body))
+            return node_buffer_1.Buffer.from(body.buffer, body.byteOffset, body.byteLength).toString("base64");
+        return null; // unsupported body type
+    }
+}
+exports.default = OpenAICache;

package/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "@jeromeetienne/openai-cache",
+	"version": "1.0.0",
+	"main": "dist/openai_cache.js",
+	"types": "dist/openai_cache.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/openai_cache.d.ts",
+			"default": "./dist/openai_cache.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"example:openai_cache": "tsx examples/openai_cache_example.ts",
+		"example:tts": "tsx examples/tts_example.ts",
+		"example:image_generation": "tsx examples/image_generation_example.ts",
+		"example:image_understanding": "tsx examples/image_understanding_example.ts",
+		"clean_cache": "rm -f ./examples/.openai_cache.sqlite",
+		"build": "tsc -p tsconfig.json",
+		"clean": "rm -rf dist",
+		"prepublishOnly": "npm run test && npm run build",
+		"test": "tsx --test ./test/*_test.ts",
+		"test:watch": "tsx --test --watch ./test/*_test.ts",
+		"version:patch": "npm version patch",
+		"version:minor": "npm version minor",
+		"version:major": "npm version major",
+		"version:prerelease": "npm version prerelease --preid=rc"
+	},
+	"keywords": [
+		"openai",
+		"cache",
+		"caching",
+		"keyv",
+		"sqlite",
+		"typescript"
+	],
+	"author": "jerome etienne <jerome.etienne@example.com>",
+	"license": "MIT",
+	"description": "A caching layer for OpenAI API calls, designed to improve performance and reduce costs.",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jeromeetienne/democracy.ai.git",
+		"directory": "packages/openai_cache"
+	},
+	"homepage": "https://github.com/jeromeetienne/democracy.ai/tree/main/packages/openai_cache",
+	"bugs": {
+		"url": "https://github.com/jeromeetienne/democracy.ai/issues"
+	},
+	"devDependencies": {
+		"@keyv/sqlite": "^4.0.8",
+		"@types/node": "^25.1.0",
+		"keyv": "^5.6.0",
+		"openai": "^6.17.0",
+		"ts-node": "^10.9.2",
+		"tsx": "^4.21.0",
+		"typescript": "^5.9.3",
+		"zod": "^4.3.6"
+	},
+	"dependencies": {
+		"cacheable": "^2.3.3"
+	}
+}