llm-fns 1.0.11 → 1.0.12

package/dist/createCachedFetcher.d.ts

@@ -0,0 +1,34 @@
+export interface CacheLike {
+    get<T>(key: string): Promise<T | undefined | null>;
+    set(key: string, value: any, ttl?: number): Promise<any>;
+}
+export type FetcherOptions = RequestInit & {
+    /** Optional TTL override for this specific request, in milliseconds. */
+    ttl?: number;
+};
+export type Fetcher = (url: string | URL | Request, options?: FetcherOptions) => Promise<Response>;
+export interface CreateFetcherDependencies {
+    /** The cache instance (e.g., from cache-manager). */
+    cache?: CacheLike;
+    /** A prefix for all cache keys to avoid collisions. Defaults to 'http-cache'. */
+    prefix?: string;
+    /** Time-to-live for cache entries, in milliseconds. */
+    ttl?: number;
+    /** Request timeout in milliseconds. If not provided, no timeout is applied. */
+    timeout?: number;
+    /** User-Agent string for requests. */
+    userAgent?: string;
+    /** Optional custom fetch implementation. Defaults to global fetch. */
+    fetch?: (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+}
+export declare class CachedResponse extends Response {
+    #private;
+    constructor(body: BodyInit | null, init: ResponseInit, finalUrl: string);
+    get url(): string;
+}
+/**
+ * Factory function that creates a `fetch` replacement with a caching layer.
+ * @param deps - Dependencies including the cache instance, prefix, TTL, and timeout.
+ * @returns A function with the same signature as native `fetch`.
+ */
+export declare function createCachedFetcher(deps: CreateFetcherDependencies): Fetcher;

package/dist/createCachedFetcher.js

@@ -0,0 +1,145 @@
+"use strict";
+// src/createCachedFetcher.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CachedResponse = void 0;
+exports.createCachedFetcher = createCachedFetcher;
+const crypto_1 = __importDefault(require("crypto"));
+// A custom Response class to correctly handle the `.url` property on cache HITs.
+// This is an implementation detail and doesn't need to be exported.
+class CachedResponse extends Response {
+    #finalUrl;
+    constructor(body, init, finalUrl) {
+        super(body, init);
+        this.#finalUrl = finalUrl;
+    }
+    // Override the read-only `url` property
+    get url() {
+        return this.#finalUrl;
+    }
+}
+exports.CachedResponse = CachedResponse;
+/**
+ * Factory function that creates a `fetch` replacement with a caching layer.
+ * @param deps - Dependencies including the cache instance, prefix, TTL, and timeout.
+ * @returns A function with the same signature as native `fetch`.
+ */
+function createCachedFetcher(deps) {
+    const { cache, prefix = 'http-cache', ttl, timeout, userAgent, fetch: customFetch } = deps;
+    const fetchImpl = customFetch ?? fetch;
+    const fetchWithTimeout = async (url, options) => {
+        // Correctly merge headers using Headers API to handle various input formats (plain object, Headers instance, array)
+        // and avoid issues with spreading Headers objects which can lead to lost headers or Symbol errors.
+        const headers = new Headers(options?.headers);
+        if (userAgent) {
+            headers.set('User-Agent', userAgent);
+        }
+        const finalOptions = {
+            ...options,
+            headers,
+        };
+        if (!timeout) {
+            try {
+                return await fetchImpl(url, finalOptions);
+            }
+            catch (error) {
+                throw error;
+            }
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+            const urlString = typeof url === 'string' ? url : url.toString();
+            console.log(`[Fetch Timeout] Request timed out after ${timeout}ms for: ${urlString}`);
+            controller.abort();
+        }, timeout);
+        finalOptions.signal = controller.signal;
+        try {
+            const response = await fetchImpl(url, finalOptions);
+            return response;
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError') {
+                const urlString = typeof url === 'string' ? url : url.toString();
+                throw new Error(`Request to ${urlString} timed out after ${timeout}ms`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    };
+    // This is the actual fetcher implementation, returned by the factory.
+    // It "closes over" the dependencies provided to the factory.
+    return async (url, options) => {
+        // Determine the request method. Default to GET for fetch.
+        let method = 'GET';
+        if (options?.method) {
+            method = options.method;
+        }
+        else if (url instanceof Request) {
+            method = url.method;
+        }
+        const urlString = typeof url === 'string' ? url : url.toString();
+        if (!cache) {
+            console.log(`[Cache SKIP] Cache not configured for request to: ${urlString}`);
+            return fetchWithTimeout(url, options);
+        }
+        let cacheKey = `${prefix}:${urlString}`;
+        // If POST (or others with body), append hash of body to cache key
+        if (method.toUpperCase() === 'POST' && options?.body) {
+            let bodyStr = '';
+            if (typeof options.body === 'string') {
+                bodyStr = options.body;
+            }
+            else if (options.body instanceof URLSearchParams) {
+                bodyStr = options.body.toString();
+            }
+            else {
+                // Fallback for other types, though mostly we expect string/JSON here
+                try {
+                    bodyStr = JSON.stringify(options.body);
+                }
+                catch (e) {
+                    bodyStr = 'unserializable';
+                }
+            }
+            const hash = crypto_1.default.createHash('md5').update(bodyStr).digest('hex');
+            cacheKey += `:${hash}`;
+        }
+        // 1. Check the cache
+        const cachedItem = await cache.get(cacheKey);
+        if (cachedItem) {
+            // Decode the base64 body back into a Buffer.
+            const body = Buffer.from(cachedItem.bodyBase64, 'base64');
+            return new CachedResponse(body, {
+                status: cachedItem.status,
+                headers: cachedItem.headers,
+            }, cachedItem.finalUrl);
+        }
+        // 2. Perform the actual fetch if not in cache
+        const fetchAndCache = async () => {
+            const response = await fetchWithTimeout(url, options);
+            // 3. Store in cache on success
+            if (response.ok) {
+                const responseClone = response.clone();
+                const bodyBuffer = await responseClone.arrayBuffer();
+                // Convert ArrayBuffer to a base64 string for safe JSON serialization.
+                const bodyBase64 = Buffer.from(bodyBuffer).toString('base64');
+                const headers = Object.fromEntries(response.headers.entries());
+                const itemToCache = {
+                    bodyBase64,
+                    headers,
+                    status: response.status,
+                    finalUrl: response.url,
+                };
+                await cache.set(cacheKey, itemToCache, options?.ttl ?? ttl);
+                console.log(`[Cache SET] for: ${cacheKey}`);
+            }
+            // 4. Return the original response
+            return response;
+        };
+        return fetchAndCache();
+    };
+}

package/dist/createJsonSchemaLlmClient.d.ts

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { PromptFunction, LlmPromptOptions, IsPromptCachedFunction } from "./createLlmClient.js";
+import { PromptFunction, LlmPromptOptions } from "./createLlmClient.js";
 export type JsonSchemaLlmClientOptions = Omit<LlmPromptOptions, 'messages' | 'response_format'> & {
     maxRetries?: number;
     /**
@@ -25,13 +25,11 @@ export type JsonSchemaLlmClientOptions = Omit<LlmPromptOptions, 'messages' | 're
 };
 export interface CreateJsonSchemaLlmClientParams {
     prompt: PromptFunction;
-    isPromptCached: IsPromptCachedFunction;
     fallbackPrompt?: PromptFunction;
     disableJsonFixer?: boolean;
 }
 export declare function createJsonSchemaLlmClient(params: CreateJsonSchemaLlmClientParams): {
     promptJson: <T>(messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], schema: Record<string, any>, options?: JsonSchemaLlmClientOptions) => Promise<T>;
-    isPromptJsonCached: (messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], schema: Record<string, any>, options?: JsonSchemaLlmClientOptions) => Promise<boolean>;
 };
 export type JsonSchemaClient = ReturnType<typeof createJsonSchemaLlmClient>;
 export type PromptJsonFunction = JsonSchemaClient['promptJson'];

package/dist/createJsonSchemaLlmClient.js

@@ -7,7 +7,7 @@ exports.createJsonSchemaLlmClient = createJsonSchemaLlmClient;
 const ajv_1 = __importDefault(require("ajv"));
 const createLlmRetryClient_js_1 = require("./createLlmRetryClient.js");
 function createJsonSchemaLlmClient(params) {
-    const { prompt, isPromptCached, fallbackPrompt, disableJsonFixer = false } = params;
+    const { prompt, fallbackPrompt, disableJsonFixer = false } = params;
     const llmRetryClient = (0, createLlmRetryClient_js_1.createLlmRetryClient)({ prompt, fallbackPrompt });
     const ajv = new ajv_1.default({ strict: false }); // Initialize AJV
     async function _tryToFixJson(brokenResponse, schemaJsonString, errorDetails, options) {
@@ -198,14 +198,5 @@ The response was valid JSON but did not conform to the required schema. Please r
         };
         return llmRetryClient.promptTextRetry(retryOptions);
     }
-    async function isPromptJsonCached(messages, schema, options) {
-        const { finalMessages, response_format } = _getJsonPromptConfig(messages, schema, options);
-        const { maxRetries, useResponseFormat: _u, beforeValidation, validator, ...restOptions } = options || {};
-        return isPromptCached({
-            messages: finalMessages,
-            response_format,
-            ...restOptions
-        });
-    }
-    return { promptJson, isPromptJsonCached };
+    return { promptJson };
 }

package/dist/createLlmClient.d.ts

@@ -1,5 +1,4 @@
 import OpenAI from "openai";
-import type { Cache } from 'cache-manager';
 import type PQueue from 'p-queue';
 export declare function countChars(message: OpenAI.Chat.Completions.ChatCompletionMessageParam): number;
 export declare function truncateSingleMessage(message: OpenAI.Chat.Completions.ChatCompletionMessageParam, charLimit: number): OpenAI.Chat.Completions.ChatCompletionMessageParam;
@@ -29,7 +28,6 @@ export type OpenRouterResponseFormat = {
 export interface LlmPromptOptions extends Omit<OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming, 'model' | 'response_format' | 'modalities' | 'messages'> {
     messages: string | OpenAI.Chat.Completions.ChatCompletionMessageParam[];
     model?: ModelConfig;
-    ttl?: number;
     retries?: number;
     /** @deprecated Use `reasoning` object instead. */
     response_format?: OpenRouterResponseFormat;
@@ -44,26 +42,21 @@ export interface LlmPromptOptions extends Omit<OpenAI.Chat.Completions.ChatCompl
  */
 export interface CreateLlmClientParams {
     openai: OpenAI;
-    cache?: Cache;
     defaultModel: ModelConfig;
     maxConversationChars?: number;
     queue?: PQueue;
 }
 export declare function normalizeOptions(arg1: string | LlmPromptOptions, arg2?: Omit<LlmPromptOptions, 'messages'>): LlmPromptOptions;
 /**
- * Factory function that creates a GPT "prompt" function, with optional caching.
- * @param params - The core dependencies (API key, base URL, default model, and optional cache instance).
- * @returns An async function `prompt` ready to make OpenAI calls, with caching if configured.
+ * Factory function that creates a GPT "prompt" function.
+ * @param params - The core dependencies (API key, base URL, default model).
+ * @returns An async function `prompt` ready to make OpenAI calls.
  */
 export declare function createLlmClient(params: CreateLlmClientParams): {
     prompt: {
         (content: string, options?: Omit<LlmPromptOptions, "messages">): Promise<OpenAI.Chat.Completions.ChatCompletion>;
         (options: LlmPromptOptions): Promise<OpenAI.Chat.Completions.ChatCompletion>;
     };
-    isPromptCached: {
-        (content: string, options?: Omit<LlmPromptOptions, "messages">): Promise<boolean>;
-        (options: LlmPromptOptions): Promise<boolean>;
-    };
     promptText: {
         (content: string, options?: Omit<LlmPromptOptions, "messages">): Promise<string>;
         (options: LlmPromptOptions): Promise<string>;
@@ -74,6 +67,5 @@ export declare function createLlmClient(params: CreateLlmClientParams): {
     };
 };
 export type PromptFunction = ReturnType<typeof createLlmClient>['prompt'];
-export type IsPromptCachedFunction = ReturnType<typeof createLlmClient>['isPromptCached'];
 export type PromptTextFunction = ReturnType<typeof createLlmClient>['promptText'];
 export type PromptImageFunction = ReturnType<typeof createLlmClient>['promptImage'];

package/dist/createLlmClient.js

@@ -1,14 +1,10 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.countChars = countChars;
 exports.truncateSingleMessage = truncateSingleMessage;
 exports.truncateMessages = truncateMessages;
 exports.normalizeOptions = normalizeOptions;
 exports.createLlmClient = createLlmClient;
-const crypto_1 = __importDefault(require("crypto"));
 const retryUtils_js_1 = require("./retryUtils.js");
 function countChars(message) {
     if (!message.content)
@@ -170,14 +166,14 @@ function normalizeOptions(arg1, arg2) {
     return options;
 }
 /**
- * Factory function that creates a GPT "prompt" function, with optional caching.
- * @param params - The core dependencies (API key, base URL, default model, and optional cache instance).
- * @returns An async function `prompt` ready to make OpenAI calls, with caching if configured.
+ * Factory function that creates a GPT "prompt" function.
+ * @param params - The core dependencies (API key, base URL, default model).
+ * @returns An async function `prompt` ready to make OpenAI calls.
  */
 function createLlmClient(params) {
-    const { openai, cache: cacheInstance, defaultModel: factoryDefaultModel, maxConversationChars, queue } = params;
-    const getCompletionParamsAndCacheKey = (options) => {
-        const { ttl, model: callSpecificModel, messages, reasoning_effort, retries, ...restApiOptions } = options;
+    const { openai, defaultModel: factoryDefaultModel, maxConversationChars, queue } = params;
+    const getCompletionParams = (options) => {
+        const { model: callSpecificModel, messages, reasoning_effort, retries, ...restApiOptions } = options;
         // Ensure messages is an array (it should be if normalized, but for safety/types)
         const messagesArray = typeof messages === 'string'
             ? [{ role: 'user', content: messages }]
@@ -200,29 +196,13 @@ function createLlmClient(params) {
             messages: finalMessages,
             ...restApiOptions,
         };
-        let cacheKey;
-        if (cacheInstance) {
-            const cacheKeyString = JSON.stringify(completionParams);
-            cacheKey = `gptask:${crypto_1.default.createHash('md5').update(cacheKeyString).digest('hex')}`;
-        }
-        return { completionParams, cacheKey, ttl, modelToUse, finalMessages, retries };
+        return { completionParams, modelToUse, finalMessages, retries };
     };
     async function prompt(arg1, arg2) {
         const options = normalizeOptions(arg1, arg2);
-        const { completionParams, cacheKey, ttl, modelToUse, finalMessages, retries } = getCompletionParamsAndCacheKey(options);
-        if (cacheInstance && cacheKey) {
-            try {
-                const cachedResponse = await cacheInstance.get(cacheKey);
-                if (cachedResponse !== undefined && cachedResponse !== null) {
-                    return JSON.parse(cachedResponse);
-                }
-            }
-            catch (error) {
-                console.warn("Cache get error:", error);
-            }
-        }
+        const { completionParams, finalMessages, retries } = getCompletionParams(options);
         const promptSummary = getPromptSummary(finalMessages);
-        const apiCallAndCache = async () => {
+        const apiCall = async () => {
             const task = () => (0, retryUtils_js_1.executeWithRetry)(async () => {
                 return openai.chat.completions.create(completionParams);
             }, async (completion) => {
@@ -235,32 +215,9 @@ function createLlmClient(params) {
                 return true;
             });
             const response = (await (queue ? queue.add(task, { id: promptSummary, messages: finalMessages }) : task()));
-            if (cacheInstance && response && cacheKey) {
-                try {
-                    await cacheInstance.set(cacheKey, JSON.stringify(response), ttl);
-                }
-                catch (error) {
-                    console.warn("Cache set error:", error);
-                }
-            }
             return response;
         };
-        return apiCallAndCache();
-    }
-    async function isPromptCached(arg1, arg2) {
-        const options = normalizeOptions(arg1, arg2);
-        const { cacheKey } = getCompletionParamsAndCacheKey(options);
-        if (!cacheInstance || !cacheKey) {
-            return false;
-        }
-        try {
-            const cachedResponse = await cacheInstance.get(cacheKey);
-            return cachedResponse !== undefined && cachedResponse !== null;
-        }
-        catch (error) {
-            console.warn("Cache get error:", error);
-            return false;
-        }
+        return apiCall();
     }
     async function promptText(arg1, arg2) {
         const options = normalizeOptions(arg1, arg2);
@@ -291,5 +248,5 @@ function createLlmClient(params) {
         }
         throw new Error("LLM returned no image content.");
     }
-    return { prompt, isPromptCached, promptText, promptImage };
+    return { prompt, promptText, promptImage };
 }

package/dist/createZodLlmClient.d.ts

@@ -19,12 +19,6 @@ export declare function createZodLlmClient(params: CreateZodLlmClientParams): {
         <T extends ZodTypeAny>(prompt: string, schema: T, options?: ZodLlmClientOptions): Promise<z.infer<T>>;
         <T extends ZodTypeAny>(mainInstruction: string, userMessagePayload: string | OpenAI.Chat.Completions.ChatCompletionContentPart[], dataExtractionSchema: T, options?: ZodLlmClientOptions): Promise<z.infer<T>>;
     };
-    isPromptZodCached: {
-        <T extends ZodTypeAny>(schema: T, options?: ZodLlmClientOptions): Promise<boolean>;
-        <T extends ZodTypeAny>(messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[], schema: T, options?: ZodLlmClientOptions): Promise<boolean>;
-        <T extends ZodTypeAny>(prompt: string, schema: T, options?: ZodLlmClientOptions): Promise<boolean>;
-        <T extends ZodTypeAny>(mainInstruction: string, userMessagePayload: string | OpenAI.Chat.Completions.ChatCompletionContentPart[], dataExtractionSchema: T, options?: ZodLlmClientOptions): Promise<boolean>;
-    };
 };
 export type ZodLlmClient = ReturnType<typeof createZodLlmClient>;
 export type PromptZodFunction = ZodLlmClient['promptZod'];

package/dist/createZodLlmClient.js

@@ -102,12 +102,5 @@ function createZodLlmClient(params) {
         });
         return result;
     }
-    async function isPromptZodCached(arg1, arg2, arg3, arg4) {
-        const { messages, dataExtractionSchema, options } = normalizeZodArgs(arg1, arg2, arg3, arg4);
-        const schema = z.toJSONSchema(dataExtractionSchema, {
-            unrepresentable: 'any'
-        });
-        return jsonSchemaClient.isPromptJsonCached(messages, schema, options);
-    }
-    return { promptZod, isPromptZodCached };
+    return { promptZod };
 }

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from './createZodLlmClient.js';
 export * from './createJsonSchemaLlmClient.js';
 export * from './llmFactory.js';
 export * from './retryUtils.js';
+export * from './createCachedFetcher.js';

package/dist/index.js

@@ -20,3 +20,4 @@ __exportStar(require("./createZodLlmClient.js"), exports);
 __exportStar(require("./createJsonSchemaLlmClient.js"), exports);
 __exportStar(require("./llmFactory.js"), exports);
 __exportStar(require("./retryUtils.js"), exports);
+__exportStar(require("./createCachedFetcher.js"), exports);

package/dist/llmFactory.d.ts

@@ -8,14 +8,7 @@ export declare function createLlm(params: CreateLlmFactoryParams): {
         <T extends import("zod").ZodType>(prompt: string, schema: T, options?: import("./createZodLlmClient.js").ZodLlmClientOptions): Promise<import("zod").infer<T>>;
         <T extends import("zod").ZodType>(mainInstruction: string, userMessagePayload: string | import("openai/resources/index.js").ChatCompletionContentPart[], dataExtractionSchema: T, options?: import("./createZodLlmClient.js").ZodLlmClientOptions): Promise<import("zod").infer<T>>;
     };
-    isPromptZodCached: {
-        <T extends import("zod").ZodType>(schema: T, options?: import("./createZodLlmClient.js").ZodLlmClientOptions): Promise<boolean>;
-        <T extends import("zod").ZodType>(messages: import("openai/resources/index.js").ChatCompletionMessageParam[], schema: T, options?: import("./createZodLlmClient.js").ZodLlmClientOptions): Promise<boolean>;
-        <T extends import("zod").ZodType>(prompt: string, schema: T, options?: import("./createZodLlmClient.js").ZodLlmClientOptions): Promise<boolean>;
-        <T extends import("zod").ZodType>(mainInstruction: string, userMessagePayload: string | import("openai/resources/index.js").ChatCompletionContentPart[], dataExtractionSchema: T, options?: import("./createZodLlmClient.js").ZodLlmClientOptions): Promise<boolean>;
-    };
     promptJson: <T>(messages: import("openai/resources/index.js").ChatCompletionMessageParam[], schema: Record<string, any>, options?: import("./createJsonSchemaLlmClient.js").JsonSchemaLlmClientOptions) => Promise<T>;
-    isPromptJsonCached: (messages: import("openai/resources/index.js").ChatCompletionMessageParam[], schema: Record<string, any>, options?: import("./createJsonSchemaLlmClient.js").JsonSchemaLlmClientOptions) => Promise<boolean>;
     promptRetry: {
         <T = import("openai/resources/index.js").ChatCompletion>(content: string, options?: Omit<import("./createLlmRetryClient.js").LlmRetryOptions<T>, "messages">): Promise<T>;
         <T = import("openai/resources/index.js").ChatCompletion>(options: import("./createLlmRetryClient.js").LlmRetryOptions<T>): Promise<T>;
@@ -32,10 +25,6 @@ export declare function createLlm(params: CreateLlmFactoryParams): {
         (content: string, options?: Omit<import("./createLlmClient.js").LlmPromptOptions, "messages">): Promise<import("openai/resources/index.js").ChatCompletion>;
         (options: import("./createLlmClient.js").LlmPromptOptions): Promise<import("openai/resources/index.js").ChatCompletion>;
     };
-    isPromptCached: {
-        (content: string, options?: Omit<import("./createLlmClient.js").LlmPromptOptions, "messages">): Promise<boolean>;
-        (options: import("./createLlmClient.js").LlmPromptOptions): Promise<boolean>;
-    };
     promptText: {
         (content: string, options?: Omit<import("./createLlmClient.js").LlmPromptOptions, "messages">): Promise<string>;
         (options: import("./createLlmClient.js").LlmPromptOptions): Promise<string>;

package/dist/llmFactory.js

@@ -11,8 +11,7 @@ function createLlm(params) {
         prompt: baseClient.prompt
     });
     const jsonSchemaClient = (0, createJsonSchemaLlmClient_js_1.createJsonSchemaLlmClient)({
-        prompt: baseClient.prompt,
-        isPromptCached: baseClient.isPromptCached
+        prompt: baseClient.prompt
     });
     const zodClient = (0, createZodLlmClient_js_1.createZodLlmClient)({
         jsonSchemaClient

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-fns",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +13,7 @@
   "dependencies": {
     "ajv": "^8.17.1",
     "openai": "^6.9.1",
+    "undici": "^7.16.0",
     "zod": "^4.1.13"
   },
   "devDependencies": {
@@ -20,6 +21,7 @@
     "@types/node": "^20.11.0",
     "cache-manager": "^7.2.5",
     "dotenv": "^16.6.1",
+    "keyv": "^5.5.5",
     "p-queue": "^9.0.1",
     "typescript": "^5.9.3",
     "vitest": "^1.2.1"