llm-fns 1.0.22 → 1.0.24

package/dist/IterativeRefiner.d.ts

@@ -0,0 +1,24 @@
+export interface RefinerOptions {
+    maxRetries: number;
+}
+export interface EvaluationResult {
+    success: boolean;
+    feedback?: string;
+}
+export interface IterationHistory<TConfig> {
+    config?: TConfig;
+    feedback?: string;
+    error?: string;
+}
+export declare abstract class IterativeRefiner<TInput, TConfig, TOutput> {
+    protected options: RefinerOptions;
+    constructor(options: RefinerOptions);
+    protected abstract generate(input: TInput, history: IterationHistory<TConfig>[]): Promise<TConfig>;
+    protected abstract execute(config: TConfig, input: TInput): Promise<TOutput>;
+    protected abstract evaluate(input: TInput, config: TConfig, output: TOutput): Promise<EvaluationResult>;
+    run(input: TInput): Promise<{
+        config: TConfig;
+        output?: TOutput;
+        iterations: number;
+    }>;
+}

package/dist/IterativeRefiner.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IterativeRefiner = void 0;
+class IterativeRefiner {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async run(input) {
+        const history = [];
+        let currentConfig;
+        let lastOutput;
+        for (let i = 0; i < this.options.maxRetries; i++) {
+            console.log(`[IterativeRefiner] Iteration ${i + 1}/${this.options.maxRetries}`);
+            // 1. Generate
+            try {
+                currentConfig = await this.generate(input, history);
+            }
+            catch (e) {
+                console.error(`[IterativeRefiner] Generation failed: ${e.message}`);
+                // If generation fails, we record it and try again
+                history.push({
+                    error: e.message,
+                    feedback: `Previous generation failed with error: ${e.message}. Please fix the configuration structure.`
+                });
+                continue;
+            }
+            // 2. Execute
+            try {
+                lastOutput = await this.execute(currentConfig, input);
+            }
+            catch (e) {
+                console.error(`[IterativeRefiner] Execution failed: ${e.message}`);
+                // Execution errors are valid feedback for the LLM
+                history.push({
+                    config: currentConfig,
+                    error: e.message,
+                    feedback: `The configuration caused an execution error: ${e.message}. Please fix the configuration to avoid this error.`
+                });
+                continue;
+            }
+            // 3. Evaluate
+            const evaluation = await this.evaluate(input, currentConfig, lastOutput);
+            if (evaluation.success) {
+                console.log(`[IterativeRefiner] Success on iteration ${i + 1}`);
+                return { config: currentConfig, output: lastOutput, iterations: i + 1 };
+            }
+            console.log(`[IterativeRefiner] Feedback: ${evaluation.feedback}`);
+            history.push({
+                config: currentConfig,
+                feedback: evaluation.feedback
+            });
+        }
+        if (!currentConfig) {
+            throw new Error("Failed to generate any valid configuration.");
+        }
+        console.warn(`[IterativeRefiner] Max retries reached. Returning last result.`);
+        return { config: currentConfig, output: lastOutput, iterations: this.options.maxRetries };
+    }
+}
+exports.IterativeRefiner = IterativeRefiner;

package/dist/completionToAssistantMessage.d.ts

@@ -0,0 +1,10 @@
+import OpenAI from 'openai';
+/**
+ * Converts an OpenAI ChatCompletion object into an assistant message parameter.
+ * Handles text, audio, refusals, tool calls, and custom image attachments.
+ *
+ * @param completion The ChatCompletion object.
+ * @returns An OpenAI ChatCompletionMessageParam with role 'assistant'.
+ * @throws Error if the input is not a valid ChatCompletion object.
+ */
+export declare function completionToMessage(completion: OpenAI.Chat.Completions.ChatCompletion): OpenAI.Chat.Completions.ChatCompletionMessageParam;

package/dist/completionToAssistantMessage.js

@@ -0,0 +1,77 @@
+/**
+ * Converts an OpenAI ChatCompletion object into an assistant message parameter.
+ * Handles text, audio, refusals, tool calls, and custom image attachments.
+ *
+ * @param completion The ChatCompletion object.
+ * @returns An OpenAI ChatCompletionMessageParam with role 'assistant'.
+ * @throws Error if the input is not a valid ChatCompletion object.
+ */
+export function completionToMessage(completion) {
+    if (!completion.choices || completion.choices.length === 0) {
+        throw new Error("Invalid completion object: No choices found.");
+    }
+    const message = completion.choices[0].message;
+    // Base message structure
+    const messageParam = {
+        role: 'assistant',
+    };
+    // Preserve standard fields
+    if (message.content !== undefined)
+        messageParam.content = message.content;
+    if (message.refusal !== undefined)
+        messageParam.refusal = message.refusal;
+    if (message.tool_calls !== undefined)
+        messageParam.tool_calls = message.tool_calls;
+    if (message.function_call !== undefined)
+        messageParam.function_call = message.function_call;
+    // Handle Content Normalization for Extensions (Images/Audio)
+    // If the provider returned images or audio in top-level fields (like OpenRouter or OpenAI Audio),
+    // we merge them into the content parts array to ensure they are preserved in history.
+    const images = message.images;
+    const audio = message.audio;
+    if ((images && Array.isArray(images) && images.length > 0) || (audio && audio.data)) {
+        let parts = [];
+        // Convert existing content to parts if it's a string
+        if (typeof messageParam.content === 'string') {
+            parts.push({ type: 'text', text: messageParam.content });
+        }
+        else if (Array.isArray(messageParam.content)) {
+            parts = [...messageParam.content];
+        }
+        // Add images from extension field if not already present in parts
+        if (images && Array.isArray(images)) {
+            for (const img of images) {
+                const url = img.image_url?.url || img.url;
+                if (url && !parts.some(p => p.type === 'image_url' && p.image_url?.url === url)) {
+                    parts.push({
+                        type: 'image_url',
+                        image_url: { url }
+                    });
+                }
+            }
+        }
+        // Add audio from extension field if not already present in parts
+        if (audio && audio.data) {
+            if (!parts.some(p => p.type === 'input_audio' && p.input_audio?.data === audio.data)) {
+                parts.push({
+                    type: 'input_audio',
+                    input_audio: {
+                        data: audio.data,
+                        format: audio.format || undefined
+                    }
+                });
+            }
+        }
+        if (parts.length > 0) {
+            // If we only have one text part, we can keep it as a string for simplicity,
+            // but if we have media, we must use the array format.
+            if (parts.length === 1 && parts[0].type === 'text') {
+                messageParam.content = parts[0].text;
+            }
+            else {
+                messageParam.content = parts;
+            }
+        }
+    }
+    return messageParam;
+}

package/dist/createAiLoggingFetcher.d.ts

@@ -0,0 +1,3 @@
+export declare function isAiRequest(url: string | URL | Request, init?: RequestInit): boolean;
+export declare function handleAiRequest(url: RequestInfo | URL, init: RequestInit | undefined, originalFetch: (url: RequestInfo | URL, init?: RequestInit) => Promise<Response>): Promise<Response>;
+export declare function createAiLoggingFetcher(fetcher?: (url: RequestInfo | URL, init?: RequestInit) => Promise<Response>): (url: RequestInfo | URL, init?: RequestInit) => Promise<Response>;

package/dist/createAiLoggingFetcher.js

@@ -0,0 +1,79 @@
+import { getPromptSummary } from "./util.js";
+export function isAiRequest(url, init) {
+    const urlString = typeof url === 'string' ? url : url.toString();
+    // Check for chat completions endpoint pattern
+    if (urlString.includes('/chat/completions') ||
+        urlString.includes('/v1/completions') ||
+        urlString.includes('/v1/images/generations')) {
+        return true;
+    }
+    // Check if body looks like an AI request
+    if (init?.body && typeof init.body === 'string') {
+        try {
+            if (init.body.trim().startsWith('{')) {
+                const body = JSON.parse(init.body);
+                if (body.messages && Array.isArray(body.messages)) {
+                    return true;
+                }
+                if (body.model && (body.prompt || body.messages)) {
+                    return true;
+                }
+            }
+        }
+        catch {
+            // Not JSON, not an AI request
+        }
+    }
+    return false;
+}
+export async function handleAiRequest(url, init, originalFetch) {
+    let requestModel = 'unknown';
+    // Log Request
+    try {
+        if (init?.body && typeof init.body === 'string') {
+            const body = JSON.parse(init.body);
+            if (body.model) {
+                requestModel = body.model;
+            }
+            if (body.messages && Array.isArray(body.messages)) {
+                console.log(`[LLM] [${requestModel}] Executing: ${getPromptSummary(body.messages)}`);
+            }
+        }
+    }
+    catch {
+        // Ignore logging errors
+    }
+    // Execute
+    const response = await originalFetch(url, init);
+    // Log Response
+    const clone = response.clone();
+    try {
+        const contentType = clone.headers.get('content-type');
+        if (contentType && contentType.includes('application/json')) {
+            const data = await clone.json();
+            const responseModel = data.model || requestModel;
+            if (data.choices && data.choices[0]?.message?.content) {
+                console.log(`[LLM] [${responseModel}] DONE ${response.status}: ${getPromptSummary([{ role: 'assistant', content: data.choices[0].message.content }])}`);
+            }
+            else if (data.error) {
+                console.error(`[LLM] [${responseModel}] ERROR ${response.status}:`, data.error);
+            }
+            else {
+                console.log(`[LLM] [${responseModel}] DONE ${response.status}`);
+            }
+        }
+    }
+    catch {
+        // Ignore logging errors
+    }
+    return response;
+}
+export function createAiLoggingFetcher(fetcher) {
+    const originalFetch = fetcher || globalThis.fetch;
+    return async (url, init) => {
+        if (isAiRequest(url, init)) {
+            return handleAiRequest(url, init, originalFetch);
+        }
+        return originalFetch(url, init);
+    };
+}

package/dist/createCachedFetcher.js

@@ -1,12 +1,5 @@
-"use strict";
-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"));
-class CachedResponse extends Response {
+import crypto from 'crypto';
+export class CachedResponse extends Response {
     #finalUrl;
     constructor(body, init, finalUrl) {
         super(body, init);
@@ -16,7 +9,6 @@ class CachedResponse extends Response {
         return this.#finalUrl;
     }
 }
-exports.CachedResponse = CachedResponse;
 /**
  * Creates a deterministic hash of headers for cache key generation.
  * Headers are sorted alphabetically to ensure consistency.
@@ -41,14 +33,14 @@ function hashHeaders(headers) {
     const headerString = headerEntries
         .map(([key, value]) => `${key}:${value}`)
         .join('|');
-    return crypto_1.default.createHash('md5').update(headerString).digest('hex');
+    return crypto.createHash('md5').update(headerString).digest('hex');
 }
 /**
  * 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) {
+export function createCachedFetcher(deps) {
     const { cache, prefix = 'http-cache', ttl, timeout, userAgent, fetch: customFetch, shouldCache } = deps;
     const fetchImpl = customFetch ?? fetch;
     const fetchWithTimeout = async (url, options) => {
@@ -121,7 +113,7 @@ function createCachedFetcher(deps) {
                     bodyStr = 'unserializable';
                 }
             }
-            const bodyHash = crypto_1.default.createHash('md5').update(bodyStr).digest('hex');
+            const bodyHash = crypto.createHash('md5').update(bodyStr).digest('hex');
             cacheKey += `:body:${bodyHash}`;
         }
         // Hash all request headers into cache key

package/dist/createCandidateSelector.d.ts

@@ -0,0 +1,41 @@
+export interface SelectionResult {
+    bestCandidateIndex: number;
+    reason: string;
+}
+export interface CandidateResult<TCandidate> {
+    candidate: TCandidate;
+    originalIndex: number;
+}
+export interface CreateCandidateSelectorParams<TInput, TCandidate> {
+    /**
+     * Number of candidates to generate.
+     */
+    candidateCount: number;
+    /**
+     * Function to generate a single candidate.
+     * @param input The input data.
+     * @param index The index of the candidate being generated (0 to candidateCount-1).
+     * @param salt A unique salt string for this candidate.
+     */
+    generate: (input: TInput, index: number, salt: string) => Promise<TCandidate>;
+    /**
+     * Function to select the best candidate.
+     * @param input The original input data.
+     * @param candidates The list of successfully generated candidates.
+     */
+    judge: (input: TInput, candidates: TCandidate[]) => Promise<SelectionResult>;
+    /**
+     * Optional callback for when a candidate generation fails.
+     */
+    onCandidateError?: (error: any, index: number) => void;
+}
+export declare function createCandidateSelector<TInput, TCandidate>(params: CreateCandidateSelectorParams<TInput, TCandidate>): {
+    run: (input: TInput, baseSalt?: string | number) => Promise<{
+        winner: TCandidate;
+        winnerIndex: number;
+        candidates: TCandidate[];
+        reason: string;
+        skippedJudge: boolean;
+    }>;
+};
+export type CandidateSelector = ReturnType<typeof createCandidateSelector>;

package/dist/createCandidateSelector.js

@@ -0,0 +1,52 @@
+import crypto from 'crypto';
+export function createCandidateSelector(params) {
+    const { candidateCount, generate, judge, onCandidateError } = params;
+    async function run(input, baseSalt = crypto.randomUUID()) {
+        // 1. Generate Candidates in Parallel
+        const promises = [];
+        for (let i = 0; i < candidateCount; i++) {
+            const salt = `${baseSalt}:${i}`;
+            promises.push(generate(input, i, salt)
+                .then(candidate => ({ candidate, originalIndex: i }))
+                .catch(err => {
+                if (onCandidateError) {
+                    onCandidateError(err, i);
+                }
+                return null;
+            }));
+        }
+        const results = await Promise.all(promises);
+        const successfulCandidates = results.filter((r) => r !== null);
+        // 2. Handle Failure Scenarios
+        if (successfulCandidates.length === 0) {
+            throw new Error(`All ${candidateCount} candidates failed to generate.`);
+        }
+        // 3. Short-circuit if only one candidate succeeded
+        if (successfulCandidates.length === 1) {
+            return {
+                winner: successfulCandidates[0].candidate,
+                winnerIndex: successfulCandidates[0].originalIndex,
+                candidates: successfulCandidates.map(c => c.candidate),
+                reason: "Only one candidate succeeded; skipping judge.",
+                skippedJudge: true
+            };
+        }
+        // 4. Judge
+        // We pass only the candidate objects to the judge, stripping metadata
+        const candidatesForJudge = successfulCandidates.map(c => c.candidate);
+        const selection = await judge(input, candidatesForJudge);
+        // Validate judge output
+        if (selection.bestCandidateIndex < 0 || selection.bestCandidateIndex >= successfulCandidates.length) {
+            throw new Error(`Judge returned invalid index ${selection.bestCandidateIndex}. Must be between 0 and ${successfulCandidates.length - 1}.`);
+        }
+        const winnerResult = successfulCandidates[selection.bestCandidateIndex];
+        return {
+            winner: winnerResult.candidate,
+            winnerIndex: winnerResult.originalIndex,
+            candidates: candidatesForJudge,
+            reason: selection.reason,
+            skippedJudge: false
+        };
+    }
+    return { run };
+}

package/dist/createConversation.d.ts

@@ -0,0 +1,41 @@
+import OpenAI from 'openai';
+import { CreateLlmClientParams } from './createLlmClient.js';
+/**
+ * Abstract interface for managing conversation history.
+ * System messages are explicitly excluded from the conversation history.
+ */
+export interface ConversationState {
+    /** Returns a read-only copy of the current message history (excluding system messages) */
+    getMessages(): OpenAI.Chat.Completions.ChatCompletionMessageParam[];
+    /** Returns the initial system messages */
+    getSystemMessages(): OpenAI.Chat.Completions.ChatCompletionMessageParam[];
+    /** Adds a raw message parameter to the history. System messages are ignored. */
+    add(message: OpenAI.Chat.Completions.ChatCompletionMessageParam): void;
+    /** Normalizes and adds a full completion to the history as an assistant message */
+    addCompletion(completion: OpenAI.Chat.Completions.ChatCompletion): void;
+    /** Shorthand to add a user message. Supports strings or content parts. */
+    addUserMessage(content: string | OpenAI.Chat.Completions.ChatCompletionContentPart[]): void;
+    /** Shorthand to add an assistant message. Supports strings, content parts, or null. */
+    addAssistantMessage(content: string | OpenAI.Chat.Completions.ChatCompletionContentPart[] | null): void;
+    /** Removes the last N messages from the history */
+    pop(count?: number): OpenAI.Chat.Completions.ChatCompletionMessageParam[];
+    /** Clears all messages */
+    clear(): void;
+}
+/**
+ * Creates a simple in-memory implementation of ConversationState.
+ * Filters out system messages from initial input and prevents them from being added.
+ */
+export declare function createConversationState(initialMessages?: OpenAI.Chat.Completions.ChatCompletionMessageParam[]): ConversationState;
+/**
+ * Creates a stateful conversation client.
+ * Every call to a prompt method will:
+ * 1. Capture the normalized user message(s) from the first call of the turn.
+ * 2. Execute the call using the full history from the state.
+ * 3. Capture the final assistant response and append it to the state.
+ *
+ * System messages are used for the duration of a call but are never stored in history.
+ */
+export declare function createConversation(params: CreateLlmClientParams, initialMessages?: OpenAI.Chat.Completions.ChatCompletionMessageParam[]): ConversationState & {
+    [k: string]: any;
+};

package/dist/createConversation.js

@@ -0,0 +1,134 @@
+import { completionToMessage } from './completionToAssistantMessage.js';
+import { createLlm } from './llmFactory.js';
+import { concatSystemContent } from './util.js';
+/**
+ * Creates a simple in-memory implementation of ConversationState.
+ * Filters out system messages from initial input and prevents them from being added.
+ */
+export function createConversationState(initialMessages = []) {
+    const systemMessages = initialMessages.filter(m => m.role === 'system');
+    let messages = initialMessages.filter(m => m.role !== 'system');
+    const add = (m) => {
+        if (m.role !== 'system') {
+            messages.push(m);
+        }
+    };
+    const addCompletion = (completion) => {
+        add(completionToMessage(completion));
+    };
+    const addUserMessage = (content) => {
+        add({ role: 'user', content: content });
+    };
+    const addAssistantMessage = (content) => {
+        add({ role: 'assistant', content: content });
+    };
+    return {
+        getMessages: () => [...messages],
+        getSystemMessages: () => [...systemMessages],
+        add,
+        addCompletion,
+        addUserMessage,
+        addAssistantMessage,
+        pop: (count = 1) => messages.splice(-count),
+        clear: () => { messages = []; }
+    };
+}
+/**
+ * Creates a stateful conversation client.
+ * Every call to a prompt method will:
+ * 1. Capture the normalized user message(s) from the first call of the turn.
+ * 2. Execute the call using the full history from the state.
+ * 3. Capture the final assistant response and append it to the state.
+ *
+ * System messages are used for the duration of a call but are never stored in history.
+ */
+export function createConversation(params, initialMessages) {
+    const state = createConversationState(initialMessages);
+    // Turn-specific tracking state
+    let isFirstCallInTurn = true;
+    let turnInitialMessages = [];
+    let lastCompletionInTurn;
+    /**
+     * Low-level SDK Spy.
+     * Intercepts every call to OpenAI to inject history and manage system messages.
+     */
+    const spiedOpenAi = {
+        ...params.openai,
+        chat: {
+            ...params.openai.chat,
+            completions: {
+                ...params.openai.chat.completions,
+                create: async (createParams, createOptions) => {
+                    const incomingMessages = createParams.messages;
+                    if (isFirstCallInTurn) {
+                        // Capture the "clean" prompt messages from the start of the turn (excluding system)
+                        turnInitialMessages = incomingMessages.filter(m => m.role !== 'system');
+                        isFirstCallInTurn = false;
+                    }
+                    const historyMessages = state.getMessages();
+                    const baseSystemMessages = state.getSystemMessages();
+                    const callSystemMessages = incomingMessages.filter(m => m.role === 'system');
+                    const currentWithoutSystem = incomingMessages.filter(m => m.role !== 'system');
+                    // Combine all system messages (initial + call-specific)
+                    // We cast to the expected type because TS infers a wider type for content (including Refusal parts)
+                    // from the generic ChatCompletionMessageParam, but we know system messages are compatible.
+                    const finalSystemContent = concatSystemContent([
+                        ...baseSystemMessages.map(m => m.content),
+                        ...callSystemMessages.map(m => m.content)
+                    ]);
+                    let finalSystemMessage;
+                    if (finalSystemContent) {
+                        finalSystemMessage = { role: 'system', content: finalSystemContent };
+                    }
+                    // Rebuild the full message array for the actual SDK call
+                    const finalMessages = finalSystemMessage
+                        ? [finalSystemMessage, ...historyMessages, ...currentWithoutSystem]
+                        : [...historyMessages, ...currentWithoutSystem];
+                    const result = await params.openai.chat.completions.create({
+                        ...createParams,
+                        messages: finalMessages
+                    }, createOptions);
+                    lastCompletionInTurn = result;
+                    return result;
+                }
+            }
+        }
+    };
+    // Create a standard LLM client using the spied OpenAI instance
+    const client = createLlm({
+        ...params,
+        openai: spiedOpenAi
+    });
+    /**
+     * High-level Turn Wrapper.
+     * Defines the boundaries of a single user interaction.
+     */
+    const wrapMethod = (methodName) => {
+        const originalMethod = client[methodName];
+        if (typeof originalMethod !== 'function')
+            return originalMethod;
+        return async (...args) => {
+            // Reset turn context
+            isFirstCallInTurn = true;
+            turnInitialMessages = [];
+            lastCompletionInTurn = undefined;
+            const result = await originalMethod.apply(client, args);
+            // Turn finished successfully. Commit the turn to the long-term history.
+            for (const m of turnInitialMessages) {
+                state.add(m);
+            }
+            if (lastCompletionInTurn) {
+                state.addCompletion(lastCompletionInTurn);
+            }
+            return result;
+        };
+    };
+    // Wrap all high-level methods to ensure they are treated as stateful turns
+    const wrappedMethods = Object.fromEntries(Object.keys(client)
+        .filter(key => key !== 'createConversation')
+        .map(key => [key, wrapMethod(key)]));
+    return {
+        ...state,
+        ...wrappedMethods
+    };
+}

package/dist/createDnsFetcher.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Creates a fetch-like function that uses specific DNS servers for hostname resolution.
+ * Defaults to Google's DNS servers (8.8.8.8, 8.8.4.4).
+ *
+ * This implementation uses Node.js's http/https agents with a custom lookup function.
+ * It is primarily compatible with fetch implementations that respect the `agent` option
+ * (like node-fetch or the built-in fetch in Node.js 18+).
+ *
+ * @param dnsServers Array of DNS server IP addresses. Defaults to Google DNS.
+ * @param innerFetch Optional fetch implementation to wrap. Defaults to global fetch.
+ */
+export declare function createDnsFetcher(dnsServers?: string[], innerFetch?: typeof fetch): (url: RequestInfo | URL, init?: RequestInit) => Promise<Response>;

package/dist/createDnsFetcher.js

@@ -0,0 +1,49 @@
+import dns from 'dns';
+import https from 'https';
+import http from 'http';
+/**
+ * Creates a fetch-like function that uses specific DNS servers for hostname resolution.
+ * Defaults to Google's DNS servers (8.8.8.8, 8.8.4.4).
+ *
+ * This implementation uses Node.js's http/https agents with a custom lookup function.
+ * It is primarily compatible with fetch implementations that respect the `agent` option
+ * (like node-fetch or the built-in fetch in Node.js 18+).
+ *
+ * @param dnsServers Array of DNS server IP addresses. Defaults to Google DNS.
+ * @param innerFetch Optional fetch implementation to wrap. Defaults to global fetch.
+ */
+export function createDnsFetcher(dnsServers = ['8.8.8.8', '8.8.4.4'], innerFetch) {
+    const resolver = new dns.Resolver();
+    resolver.setServers(dnsServers);
+    const lookup = (hostname, options, callback) => {
+        const cb = typeof options === 'function' ? options : callback;
+        const opts = typeof options === 'object' ? options : {};
+        // If the caller requested all addresses, fallback to system lookup for simplicity
+        if (opts.all) {
+            return dns.lookup(hostname, opts, cb);
+        }
+        // Attempt to resolve IPv4 via configured DNS servers
+        resolver.resolve4(hostname, (err, addresses) => {
+            if (err || !addresses || addresses.length === 0) {
+                // Fallback to system DNS lookup if custom DNS fails or doesn't return IPv4
+                return dns.lookup(hostname, opts, cb);
+            }
+            // Return the first resolved address
+            cb(null, addresses[0], 4);
+        });
+    };
+    const httpAgent = new http.Agent({ lookup });
+    const httpsAgent = new https.Agent({ lookup });
+    const fetchImpl = innerFetch || globalThis.fetch;
+    return (url, init) => {
+        const urlString = typeof url === 'string'
+            ? url
+            : (url instanceof Request ? url.url : url.toString());
+        const isHttps = urlString.startsWith('https');
+        return fetchImpl(url, {
+            ...init,
+            // Pass agents for libraries like node-fetch
+            agent: isHttps ? httpsAgent : httpAgent,
+        });
+    };
+}

package/dist/createGoogleDnsFetcher.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/createGoogleDnsFetcher.js

@@ -0,0 +1 @@
+export {};