@sap-cloud-sdk/http-client/dist/compress-request-middleware.d.ts

SAP Cloud SDK for JavaScript http-client

import type * as zlibType from 'node:zlib';
import type { HttpMiddleware } from './http-client-types';
interface CompressorsMap {
    brotli?: (data: zlibType.InputType, options?: RequestCompressorOptions['brotli']) => Promise<Buffer>;
    gzip?: (data: zlibType.InputType, options?: RequestCompressorOptions['gzip']) => Promise<Buffer>;
    deflate?: (data: zlibType.InputType, options?: RequestCompressorOptions['deflate']) => Promise<Buffer>;
    zstd?: (data: zlibType.InputType, options?: RequestCompressorOptions['zstd']) => Promise<Buffer>;
}
/**
 * Cache for available compressors to avoid redundant dynamic imports and checks.
 * @internal
 */
export declare let compressorsCache: Promise<CompressorsMap> | undefined;
/**
 * Supported compression algorithms.
 * @remarks
 * - `gzip` is widely supported.
 * - `brotli` is supported by modern servers and can offer better compression rates, but may be slower.
 * - `deflate` is similar to `gzip` but less commonly used.
 * - `zstd` is experimental, requires Node.js v22.15.0 or higher, and can provide higher compression ratios and speed.
 */
export type RequestCompressionAlgorithm = 'gzip' | 'brotli' | 'deflate' | 'zstd';
/**
 * Options for different request compressors to configure their behavior (e.g., compression level).
 */
export interface RequestCompressorOptions {
    /** Options to control gzip compression. */
    gzip: zlibType.ZlibOptions;
    /** Options to control brotli compression. */
    brotli: zlibType.BrotliOptions;
    /** Options to control deflate compression. */
    deflate: zlibType.ZlibOptions;
    /**
     * Options to control zstd compression.
     * @remarks
     * Zstd options will become available once Node.js v22.15.0 is the minimum supported version.
     */
    zstd: Record<string, any>;
}
/**
 * Configuration for the request compression middleware.
 */
export interface RequestCompressionMiddlewareOptions<C extends RequestCompressionAlgorithm = 'gzip'> {
    /**
     * The algorithm to compress the payload with.
     * Please note that not all servers support all algorithms.
     * @defaultValue 'gzip'
     */
    algorithm?: C;
    /**
     * Options for the chosen compression algorithm, e.g. to control the compression effort.
     */
    compressOptions?: RequestCompressorOptions[C];
    /**
     * Compression mode.
     * - 'auto' - The payload is compressed based on the `autoCompressMinSize` threshold.
     * - 'header-only' - It is assumed that the payload is already compressed. The middleware will only set the appropriate Content-Encoding header without modifying the payload.
     * - 'always' - The payload will always be compressed.
     * - never' - The payload will never be compressed.
     * @defaultValue 'auto'
     */
    mode?: 'auto' | 'header-only' | 'always' | 'never';
    /**
     * Minimum size in bytes a payload must have to be compressed in 'auto' mode.
     * @defaultValue 1024
     */
    autoCompressMinSize?: number;
}
/**
 * Middleware to compress HTTP request payloads.
 * @param options - Configuration options for request compression.
 * @remarks
 * **Middleware Ordering**: Place compression middleware early in your middleware array,
 * typically after logging/csrf but before resilience middleware (retry, timeout, circuit breaker).
 * This ensures the payload is compressed once and reused across retry attempts.
 * @returns An HTTP middleware that compresses request payloads based on the provided options.
 */
export declare function compress<C extends RequestCompressionAlgorithm = 'gzip'>(options?: RequestCompressionMiddlewareOptions<C>): HttpMiddleware;
export {};