@cacheable/net/dist/index.d.ts

High Performance Network Caching for Node.js with fetch, request, http 1.1, and http 2 support

import { Cacheable, CacheableOptions } from 'cacheable';
import { HookifiedOptions, Hookified } from 'hookified';
import { RequestInit, Response as Response$1 } from 'undici';

type FetchOptions = Omit<RequestInit, "cache"> & {
    cache?: Cacheable;
    /**
     * Enable HTTP cache semantics for intelligent response caching.
     *
     * When enabled (default), the fetch function will:
     * - Respect standard HTTP cache headers (Cache-Control, ETag, Last-Modified, Expires)
     * - Store and validate cache policies according to RFC 7234
     * - Handle conditional requests with If-None-Match and If-Modified-Since headers
     * - Process 304 Not Modified responses to update cached entries
     * - Only cache responses that are considered "storable" per HTTP specifications
     * - Automatically revalidate stale cache entries when needed
     * - **Set cache TTL based on HTTP headers (e.g., max-age directive)**
     * - Refresh TTL when receiving 304 Not Modified responses
     *
     * When disabled, the fetch function will:
     * - Use simple key-based caching without considering HTTP headers
     * - Cache all successful GET responses regardless of cache directives
     * - Never revalidate cached entries
     * - Ignore cache-control directives from the server
     * - **Use the default TTL from the Cacheable instance**
     *
     * @default true
     */
    httpCachePolicy?: boolean;
};
/**
 * Fetch data from a URL with optional request options.
 *
 * When `httpCachePolicy` is enabled (default), cache entries will have their TTL
 * set based on HTTP cache headers (e.g., Cache-Control: max-age). When disabled,
 * the default TTL from the Cacheable instance is used.
 *
 * If no cache is provided, the request will be made without any caching.
 *
 * @param {string} url The URL to fetch.
 * @param {FetchOptions} options Optional request options. If `cache` is not provided, no caching will be used.
 * @returns {Promise<UndiciResponse>} The response from the fetch.
 */
declare function fetch(url: string, options: FetchOptions): Promise<Response$1>;
type DataResponse<T = unknown> = {
    data: T;
    response: Response$1;
};
type GetResponse<T = unknown> = DataResponse<T>;
/**
 * Perform a GET request to a URL with optional request options.
 * @param {string} url The URL to fetch.
 * @param {Omit<FetchOptions, 'method'>} options Optional request options. The `cache` property is required.
 * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
 */
declare function get<T = unknown>(url: string, options: Omit<FetchOptions, "method">): Promise<DataResponse<T>>;
/**
 * Perform a POST request to a URL with data and optional request options.
 * @param {string} url The URL to fetch.
 * @param {unknown} data The data to send in the request body.
 * @param {Omit<FetchOptions, 'method' | 'body'>} options Optional request options. The `cache` property is required.
 * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
 */
declare function post<T = unknown>(url: string, data: unknown, options: Omit<FetchOptions, "method" | "body">): Promise<DataResponse<T>>;
/**
 * Perform a PATCH request to a URL with data and optional request options.
 * @param {string} url The URL to fetch.
 * @param {unknown} data The data to send in the request body.
 * @param {Omit<FetchOptions, 'method' | 'body'>} options Optional request options. The `cache` property is required.
 * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
 */
declare function patch<T = unknown>(url: string, data: unknown, options: Omit<FetchOptions, "method" | "body">): Promise<DataResponse<T>>;
/**
 * Perform a DELETE request to a URL with optional data and request options.
 * @param {string} url The URL to fetch.
 * @param {unknown} data Optional data to send in the request body.
 * @param {Omit<FetchOptions, 'method' | 'body'>} options Optional request options. The `cache` property is required.
 * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
 */
declare function del<T = unknown>(url: string, data?: unknown, options?: Omit<FetchOptions, "method" | "body">): Promise<DataResponse<T>>;
/**
 * Perform a HEAD request to a URL with optional request options.
 * @param {string} url The URL to fetch.
 * @param {Omit<FetchOptions, 'method'>} options Optional request options. The `cache` property is required.
 * @returns {Promise<UndiciResponse>} The response from the fetch (no body).
 */
declare function head(url: string, options: Omit<FetchOptions, "method">): Promise<Response$1>;
type Response = Response$1;

type NetFetchOptions = {
    /**
     * Controls whether caching is enabled for this specific request.
     * - `true`: Enable caching for this request
     * - `false`: Disable caching for this request
     * - `undefined`: Use default caching behavior based on the method (GET/HEAD are cached by default)
     * @default undefined
     */
    caching?: boolean;
    /**
     * Custom function for converting JavaScript values to strings for this request.
     * Overrides the instance-level stringify function if provided.
     * @example
     * // Use custom serialization for this request only
     * stringify: (value) => superjson.stringify(value)
     */
    stringify?: StringifyType;
    /**
     * Custom function for parsing strings back to JavaScript values for this request.
     * Overrides the instance-level parse function if provided.
     * @example
     * // Use custom parsing for this request only
     * parse: (text) => superjson.parse(text)
     */
    parse?: ParseType;
} & Omit<FetchOptions, "method" | "cache">;
type CacheableNetOptions = {
    /**
     * The cache instance or configuration options for caching responses.
     * Can be either an existing Cacheable instance or options to create a new one.
     * If not provided, a default Cacheable instance will be created.
     * @default new Cacheable()
     */
    cache?: Cacheable | CacheableOptions;
    /**
     * Enable HTTP cache semantics for intelligent response caching.
     *
     * When enabled (default), fetch operations will:
     * - Respect standard HTTP cache headers (Cache-Control, ETag, Last-Modified, Expires)
     * - Store and validate cache policies according to RFC 7234
     * - Handle conditional requests with If-None-Match and If-Modified-Since headers
     * - Process 304 Not Modified responses to update cached entries
     * - Only cache responses that are considered "storable" per HTTP specifications
     * - Automatically revalidate stale cache entries when needed
     * - **Set cache TTL based on HTTP headers (e.g., max-age directive)**
     * - Refresh TTL when receiving 304 Not Modified responses
     *
     * When disabled, fetch operations will:
     * - Use simple key-based caching without considering HTTP headers
     * - Cache all successful GET responses regardless of cache directives
     * - Never revalidate cached entries
     * - Ignore cache-control directives from the server
     * - **Use the default TTL from the Cacheable instance**
     *
     * @default true
     */
    httpCachePolicy?: boolean;
    /**
     * Custom function for converting JavaScript values to strings.
     * This is used when serializing request bodies for POST, PUT, PATCH, and DELETE methods.
     * Useful for handling complex data types that JSON.stringify doesn't support natively.
     * @default JSON.stringify
     * @example
     * // Using superjson for enhanced serialization
     * stringify: (value) => superjson.stringify(value)
     */
    stringify?: StringifyType;
    /**
     * Custom function for parsing strings back to JavaScript values.
     * This is used when deserializing response bodies.
     * Should be compatible with the stringify function for proper round-trip serialization.
     * @default JSON.parse
     * @example
     * // Using superjson for enhanced parsing
     * parse: (text) => superjson.parse(text)
     */
    parse?: ParseType;
} & HookifiedOptions;
/**
 * Function type for converting JavaScript values to strings.
 * Used for serializing request bodies and data.
 * @param value - The JavaScript value to stringify
 * @returns The string representation of the value
 */
type StringifyType = (value: unknown) => string;
/**
 * Function type for parsing strings back to JavaScript values.
 * Used for deserializing response bodies.
 * @param value - The string to parse
 * @returns The parsed JavaScript value
 */
type ParseType = (value: string) => unknown;
declare class CacheableNet extends Hookified {
    private _cache;
    private _httpCachePolicy;
    private _stringify;
    private _parse;
    constructor(options?: CacheableNetOptions);
    /**
     * Get the stringify function used for converting objects to strings.
     * @returns {StringifyType} The current stringify function
     */
    get stringify(): StringifyType;
    /**
     * Set the stringify function for converting objects to strings.
     * @param {StringifyType} value - The stringify function to use
     */
    set stringify(value: StringifyType);
    /**
     * Get the parse function used for converting strings to objects.
     * @returns {ParseType} The current parse function
     */
    get parse(): ParseType;
    /**
     * Set the parse function for converting strings to objects.
     * @param {ParseType} value - The parse function to use
     */
    set parse(value: ParseType);
    /**
     * Get the Cacheable instance used for caching fetch operations.
     * @returns {Cacheable} The current Cacheable instance
     */
    get cache(): Cacheable;
    /**
     * Set the Cacheable instance for caching fetch operations.
     * @param {Cacheable} value - The Cacheable instance to use for caching
     */
    set cache(value: Cacheable);
    /**
     * Get the current HTTP cache policy setting.
     * @returns {boolean} Whether HTTP cache semantics are enabled
     */
    get httpCachePolicy(): boolean;
    /**
     * Set whether to use HTTP cache semantics.
     * @param {boolean} value - Enable or disable HTTP cache semantics
     */
    set httpCachePolicy(value: boolean);
    /**
     * Fetch data from a URL with optional request options. Will use the cache that is already set in the instance.
     *
     * When `httpCachePolicy` is enabled (default), cache entries will have their TTL
     * set based on HTTP cache headers (e.g., Cache-Control: max-age). When disabled,
     * the default TTL from the Cacheable instance is used.
     *
     * @param {string} url The URL to fetch.
     * @param {Omit<FetchOptions, "cache">} options Optional request options.
     * @returns {Promise<FetchResponse>} The response from the fetch.
     */
    fetch(url: string, options?: Omit<FetchOptions, "cache">): Promise<Response>;
    /**
     * Perform a GET request to a URL with optional request options. By default caching is enabled on all requests. To
     * disable set `options.caching` to false.
     * @param {string} url The URL to fetch.
     * @param {NetFetchOptions} options Optional request options (method will be set to GET).
     * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
     */
    get<T = unknown>(url: string, options?: NetFetchOptions): Promise<DataResponse<T>>;
    /**
     * Perform a POST request to a URL with data and optional request options. By default caching is not enabled. To enable it
     * set `options.caching` to true. Note, setting caching to tru means it will not post if the data is the same.
     * @param {string} url The URL to fetch.
     * @param {unknown} data The data to send in the request body.
     * @param {Omit<NetFetchOptions, "method" | "body" >} options Optional request options (method and body will be set).
     * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
     */
    post<T = unknown>(url: string, data?: unknown, options?: Omit<NetFetchOptions, "method" | "body">): Promise<DataResponse<T>>;
    /**
     * Perform a HEAD request to a URL with optional request options. By default caching is enabled on all requests. To
     * disable set `options.caching` to false.
     * @param {string} url The URL to fetch.
     * @param {NetFetchOptions} options Optional request options (method will be set to HEAD).
     * @returns {Promise<FetchResponse>} The response from the fetch (no body).
     */
    head(url: string, options?: NetFetchOptions): Promise<Response>;
    /**
     * Perform a PUT request to a URL with data and optional request options. By default caching is not enabled. To enable it
     * set `options.caching` to true. Note, setting caching to true means it will not put if the data is the same.
     * @param {string} url The URL to fetch.
     * @param {unknown} data The data to send in the request body.
     * @param {Omit<NetFetchOptions, 'method' | 'body'>} options Optional request options (method and body will be set).
     * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
     */
    put<T = unknown>(url: string, data?: unknown, options?: Omit<NetFetchOptions, "method" | "body">): Promise<DataResponse<T>>;
    /**
     * Perform a PATCH request to a URL with data and optional request options. By default caching is not enabled. To enable it
     * set `options.caching` to true. Note, setting caching to true means it will not patch if the data is the same.
     * @param {string} url The URL to fetch.
     * @param {unknown} data The data to send in the request body.
     * @param {Omit<NetFetchOptions, 'method' | 'body'>} options Optional request options (method and body will be set).
     * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
     */
    patch<T = unknown>(url: string, data?: unknown, options?: Omit<NetFetchOptions, "method" | "body">): Promise<DataResponse<T>>;
    /**
     * Perform a DELETE request to a URL with optional data and request options. By default caching is not enabled. To enable it
     * set `options.caching` to true. Note, setting caching to true means it will not delete if the data is the same.
     * @param {string} url The URL to fetch.
     * @param {unknown} data Optional data to send in the request body.
     * @param {Omit<NetFetchOptions, 'method' | 'body'>} options Optional request options (method and body will be set).
     * @returns {Promise<DataResponse<T>>} The typed data and response from the fetch.
     */
    delete<T = unknown>(url: string, data?: unknown, options?: Omit<NetFetchOptions, "method" | "body">): Promise<DataResponse<T>>;
}
declare const Net: typeof CacheableNet;

export { CacheableNet, type CacheableNetOptions, type DataResponse, type FetchOptions, type Response as FetchResponse, type GetResponse, Net, type NetFetchOptions, type ParseType, type StringifyType, del, fetch, get, head, patch, post };