apify-client 3.0.0-beta.21 → 3.0.0-beta.23

package/dist/http_client.d.ts

@@ -2,6 +2,7 @@ import type http from 'node:http';
 import type https from 'node:https';
 import type { AxiosInstance, AxiosRequestConfig, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
 import type { Log } from '@apify/log';
+import type { HttpCompressor } from './http_compressors/base.js';
 import type { RequestInterceptorFunction } from './interceptors.js';
 import type { Statistics } from './statistics.js';
 import type { Timeout, TimeoutTier } from './timeouts.js';
@@ -11,6 +12,11 @@ export declare class HttpClient {
     maxRetries: number;
     minDelayBetweenRetriesMillis: number;
     userProvidedRequestInterceptors: RequestInterceptorFunction[];
+    /**
+     * Compressor applied to request bodies that are worth compressing. The request interceptor captures it at
+     * construction, so it is fixed for the lifetime of the client.
+     */
+    readonly httpCompressor: HttpCompressor;
     logger: Log;
     /** Duration of each timeout tier, in milliseconds. */
     timeoutMillis: Record<TimeoutTier, number>;
@@ -43,6 +49,7 @@ export interface HttpClientOptions {
     maxRetries: number;
     minDelayBetweenRetriesMillis: number;
     requestInterceptors: RequestInterceptorFunction[];
+    httpCompressor: HttpCompressor;
     timeoutShortSecs: number;
     timeoutMediumSecs: number;
     timeoutLongSecs: number;

package/dist/http_client.js

@@ -3,7 +3,7 @@ import axios, { AxiosHeaders } from 'axios';
 import { APIFY_ENV_VARS } from '@apify/consts';
 import { concatStreamToBuffer } from '@apify/utilities';
 import { ApifyApiError } from './apify_api_error.js';
-import { InvalidResponseBodyError, requestInterceptors, responseInterceptors } from './interceptors.js';
+import { createRequestInterceptors, InvalidResponseBodyError, responseInterceptors } from './interceptors.js';
 import { runtime } from '#runtime';
 import { asArray, cast, getEnv, isStream, version } from './utils.js';
 const RATE_LIMIT_EXCEEDED_STATUS_CODE = 429;
@@ -12,6 +12,11 @@ export class HttpClient {
     maxRetries;
     minDelayBetweenRetriesMillis;
     userProvidedRequestInterceptors;
+    /**
+     * Compressor applied to request bodies that are worth compressing. The request interceptor captures it at
+     * construction, so it is fixed for the lifetime of the client.
+     */
+    httpCompressor;
     logger;
     /** Duration of each timeout tier, in milliseconds. */
     timeoutMillis;
@@ -28,6 +33,7 @@ export class HttpClient {
         this.maxRetries = options.maxRetries;
         this.minDelayBetweenRetriesMillis = options.minDelayBetweenRetriesMillis;
         this.userProvidedRequestInterceptors = options.requestInterceptors;
+        this.httpCompressor = options.httpCompressor;
         this.timeoutMillis = {
             short: options.timeoutShortSecs * 1000,
             medium: options.timeoutMediumSecs * 1000,
@@ -86,7 +92,7 @@ export class HttpClient {
             }
             this.axios.defaults.headers['User-Agent'] = userAgent;
         }
-        requestInterceptors.forEach((i) => this.axios.interceptors.request.use(i));
+        createRequestInterceptors(this.httpCompressor).forEach((i) => this.axios.interceptors.request.use(i));
         this.userProvidedRequestInterceptors.forEach((i) => this.axios.interceptors.request.use(i));
         responseInterceptors.forEach((i) => this.axios.interceptors.response.use(i));
     }

package/dist/http_compressors/base.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+/**
+ * Strategy for compressing HTTP request bodies.
+ *
+ * Implement this interface to create a custom compressor. Set `contentEncoding` to the value that should be sent in
+ * the `Content-Encoding` header and implement `compress()`. The client calls it only for bodies that are large
+ * enough to benefit from compression, whose content type does not already carry its own compression, and which the
+ * caller did not send with a `Content-Encoding` of their own.
+ *
+ * @example
+ * ```javascript
+ * import { ApifyClient } from 'apify-client';
+ *
+ * const identityCompressor = {
+ *     contentEncoding: 'identity',
+ *
+ *     async compress(data) {
+ *         return data;
+ *     },
+ * };
+ *
+ * const client = new ApifyClient({ token: 'my-token', compression: identityCompressor });
+ * ```
+ */
+export interface HttpCompressor {
+    /** Value sent in the `Content-Encoding` header, for example `gzip` or `br`. */
+    readonly contentEncoding: string;
+    /**
+     * Compresses a request body.
+     *
+     * @param data - The raw bytes to compress.
+     * @returns The compressed bytes.
+     */
+    compress(data: Buffer): Promise<Buffer>;
+}
+/**
+ * Schema accepting anything shaped like an {@link HttpCompressor}.
+ * @internal
+ */
+export declare const httpCompressorSchema: z.ZodCustom<HttpCompressor, HttpCompressor>;

package/dist/http_compressors/base.js

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/**
+ * Schema accepting anything shaped like an {@link HttpCompressor}.
+ * @internal
+ */
+export const httpCompressorSchema = z.custom((value) => typeof value === 'object' &&
+    value !== null &&
+    typeof value.contentEncoding === 'string' &&
+    typeof value.compress === 'function', { error: 'Invalid input: expected an HttpCompressor' });

package/dist/http_compressors/brotli.d.ts

@@ -0,0 +1,33 @@
+import type { HttpCompressor } from './base.js';
+/**
+ * Compresses request bodies using brotli.
+ *
+ * Built on the `node:zlib` module, so it works wherever the client runs on Node.js.
+ *
+ * @example
+ * ```javascript
+ * import { ApifyClient, BrotliHttpCompressor } from 'apify-client';
+ *
+ * const client = new ApifyClient({ token: 'my-token', compression: new BrotliHttpCompressor({ quality: 11 }) });
+ * ```
+ */
+export declare class BrotliHttpCompressor implements HttpCompressor {
+    #private;
+    readonly contentEncoding = "br";
+    /**
+     * @param options - Compressor options.
+     * @throws {ArgumentValidationError} If `quality` is out of the valid range.
+     */
+    constructor(options?: BrotliHttpCompressorOptions);
+    compress(data: Buffer): Promise<Buffer>;
+}
+/**
+ * Options for {@link BrotliHttpCompressor}.
+ */
+export interface BrotliHttpCompressorOptions {
+    /**
+     * Compression level, from `0` (the fastest) to `11` (the best compression).
+     * @default 6
+     */
+    quality?: number;
+}

package/dist/http_compressors/brotli.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { runtime } from '#runtime';
+import { parseArgument } from '../utils.js';
+/** Lowest valid brotli quality, the fastest with the least compression. */
+const MIN_QUALITY = 0;
+/** Highest valid brotli quality, the slowest with the best compression. */
+const MAX_QUALITY = 11;
+/** Middle of the range, where brotli already beats gzip at a comparable CPU cost. */
+const DEFAULT_QUALITY = 6;
+const optionsSchema = z.strictObject({
+    quality: z.int().min(MIN_QUALITY).max(MAX_QUALITY).default(DEFAULT_QUALITY),
+});
+/**
+ * Compresses request bodies using brotli.
+ *
+ * Built on the `node:zlib` module, so it works wherever the client runs on Node.js.
+ *
+ * @example
+ * ```javascript
+ * import { ApifyClient, BrotliHttpCompressor } from 'apify-client';
+ *
+ * const client = new ApifyClient({ token: 'my-token', compression: new BrotliHttpCompressor({ quality: 11 }) });
+ * ```
+ */
+export class BrotliHttpCompressor {
+    contentEncoding = 'br';
+    #quality;
+    /**
+     * @param options - Compressor options.
+     * @throws {ArgumentValidationError} If `quality` is out of the valid range.
+     */
+    constructor(options = {}) {
+        const { quality } = parseArgument(options, optionsSchema, 'BrotliHttpCompressorOptions');
+        this.#quality = quality;
+    }
+    async compress(data) {
+        return runtime.compress(data, { algorithm: 'br', quality: this.#quality });
+    }
+}

package/dist/http_compressors/gzip.d.ts

@@ -0,0 +1,33 @@
+import type { HttpCompressor } from './base.js';
+/**
+ * Compresses request bodies using gzip.
+ *
+ * Built on the `node:zlib` module, so it works wherever the client runs on Node.js.
+ *
+ * @example
+ * ```javascript
+ * import { ApifyClient, GzipHttpCompressor } from 'apify-client';
+ *
+ * const client = new ApifyClient({ token: 'my-token', compression: new GzipHttpCompressor({ quality: 1 }) });
+ * ```
+ */
+export declare class GzipHttpCompressor implements HttpCompressor {
+    #private;
+    readonly contentEncoding = "gzip";
+    /**
+     * @param options - Compressor options.
+     * @throws {ArgumentValidationError} If `quality` is out of the valid range.
+     */
+    constructor(options?: GzipHttpCompressorOptions);
+    compress(data: Buffer): Promise<Buffer>;
+}
+/**
+ * Options for {@link GzipHttpCompressor}.
+ */
+export interface GzipHttpCompressorOptions {
+    /**
+     * Compression level, from `1` (the fastest) to `9` (the best compression).
+     * @default 6
+     */
+    quality?: number;
+}

package/dist/http_compressors/gzip.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { runtime } from '#runtime';
+import { parseArgument } from '../utils.js';
+/** Lowest valid gzip quality, the fastest with the least compression. */
+const MIN_QUALITY = 1;
+/** Highest valid gzip quality, the slowest with the best compression. */
+const MAX_QUALITY = 9;
+/** zlib's own default. The levels above it roughly double the CPU cost for about a percent fewer bytes. */
+const DEFAULT_QUALITY = 6;
+const optionsSchema = z.strictObject({
+    quality: z.int().min(MIN_QUALITY).max(MAX_QUALITY).default(DEFAULT_QUALITY),
+});
+/**
+ * Compresses request bodies using gzip.
+ *
+ * Built on the `node:zlib` module, so it works wherever the client runs on Node.js.
+ *
+ * @example
+ * ```javascript
+ * import { ApifyClient, GzipHttpCompressor } from 'apify-client';
+ *
+ * const client = new ApifyClient({ token: 'my-token', compression: new GzipHttpCompressor({ quality: 1 }) });
+ * ```
+ */
+export class GzipHttpCompressor {
+    contentEncoding = 'gzip';
+    #quality;
+    /**
+     * @param options - Compressor options.
+     * @throws {ArgumentValidationError} If `quality` is out of the valid range.
+     */
+    constructor(options = {}) {
+        const { quality } = parseArgument(options, optionsSchema, 'GzipHttpCompressorOptions');
+        this.#quality = quality;
+    }
+    async compress(data) {
+        return runtime.compress(data, { algorithm: 'gzip', quality: this.#quality });
+    }
+}

package/dist/http_compressors/index.d.ts

@@ -0,0 +1,6 @@
+export type { HttpCompressor } from './base.js';
+export { BrotliHttpCompressor } from './brotli.js';
+export type { BrotliHttpCompressorOptions } from './brotli.js';
+export { GzipHttpCompressor } from './gzip.js';
+export type { GzipHttpCompressorOptions } from './gzip.js';
+export type { HttpCompressionAlgorithm } from './resolve.js';

package/dist/http_compressors/index.js

@@ -0,0 +1,2 @@
+export { BrotliHttpCompressor } from './brotli.js';
+export { GzipHttpCompressor } from './gzip.js';

package/dist/http_compressors/resolve.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import type { HttpCompressor } from './base.js';
+/**
+ * Compression algorithms the `compression` option of {@link ApifyClient} accepts by name. Each name selects the
+ * matching built-in compressor with its default quality: `'brotli'` a {@link BrotliHttpCompressor}, `'gzip'` a
+ * {@link GzipHttpCompressor}. The Apify API also accepts `deflate` and `identity`, which a custom
+ * {@link HttpCompressor} covers.
+ */
+export type HttpCompressionAlgorithm = 'brotli' | 'gzip';
+/**
+ * Schema of the `compression` option: an algorithm name or an {@link HttpCompressor}.
+ * @internal
+ */
+export declare const compressionSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    gzip: "gzip";
+    brotli: "brotli";
+}>, z.ZodCustom<HttpCompressor, HttpCompressor>]>;
+/**
+ * Turns the `compression` option into a ready-to-use {@link HttpCompressor}: a name into the matching built-in
+ * compressor with its default quality, a compressor into itself.
+ * @internal
+ */
+export declare function resolveCompressor(compression: HttpCompressionAlgorithm | HttpCompressor): HttpCompressor;

package/dist/http_compressors/resolve.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { httpCompressorSchema } from './base.js';
+import { BrotliHttpCompressor } from './brotli.js';
+import { GzipHttpCompressor } from './gzip.js';
+/**
+ * Schema of the `compression` option: an algorithm name or an {@link HttpCompressor}.
+ * @internal
+ */
+export const compressionSchema = z.union([
+    z.enum(['brotli', 'gzip']),
+    httpCompressorSchema,
+]);
+/**
+ * Turns the `compression` option into a ready-to-use {@link HttpCompressor}: a name into the matching built-in
+ * compressor with its default quality, a compressor into itself.
+ * @internal
+ */
+export function resolveCompressor(compression) {
+    if (typeof compression !== 'string')
+        return compression;
+    switch (compression) {
+        case 'gzip':
+            return new GzipHttpCompressor();
+        case 'brotli':
+            return new BrotliHttpCompressor();
+    }
+}

package/dist/index.d.ts

@@ -30,5 +30,6 @@ export * from './apify_api_error.js';
 export { ArgumentValidationError } from '@apify/validations';
 export * from './response_validation_error.js';
 export { InvalidResponseBodyError } from './interceptors.js';
+export * from './http_compressors/index.js';
 export type { PaginatedList, Dictionary } from './utils.js';
 export type { Timeout, TimeoutOptions, TimeoutTier } from './timeouts.js';

package/dist/index.js

@@ -30,3 +30,4 @@ export * from './apify_api_error.js';
 export { ArgumentValidationError } from '@apify/validations';
 export * from './response_validation_error.js';
 export { InvalidResponseBodyError } from './interceptors.js';
+export * from './http_compressors/index.js';

package/dist/interceptors.d.ts

@@ -1,5 +1,6 @@
 import type { AxiosInterceptorManager, AxiosResponse } from 'axios';
 import type { ApifyRequestConfig, ApifyResponse } from './http_client.js';
+import type { HttpCompressor } from './http_compressors/base.js';
 /**
  * This error exists for the quite common situation, where only a partial JSON response is received and
  * an attempt to parse the JSON throws an error. In most cases this can be resolved by retrying the
@@ -15,5 +16,11 @@ export declare class InvalidResponseBodyError extends Error {
 }
 export type RequestInterceptorFunction = Parameters<AxiosInterceptorManager<ApifyRequestConfig>['use']>[0];
 export type ResponseInterceptorFunction = Parameters<AxiosInterceptorManager<ApifyResponse>['use']>[0];
-export declare const requestInterceptors: RequestInterceptorFunction[];
+/**
+ * The client's own request interceptors, in registration order. Axios runs request interceptors in the reverse
+ * order of registration, so the body is serialized before it is compressed, and interceptors registered later,
+ * such as the user-provided ones, run before both.
+ * @internal
+ */
+export declare function createRequestInterceptors(compressor: HttpCompressor): RequestInterceptorFunction[];
 export declare const responseInterceptors: ResponseInterceptorFunction[];

package/dist/interceptors.js

@@ -1,7 +1,8 @@
 import axios, { AxiosHeaders } from 'axios';
 import contentTypeParser from 'content-type';
 import { maybeParseBody } from './body_parser.js';
-import { isCompressibleContentType, maybeCompressValue } from './utils.js';
+import { runtime } from '#runtime';
+import { isCompressibleContentType, MIN_COMPRESS_BYTES, toBytes } from './utils.js';
 /**
  * This error exists for the quite common situation, where only a partial JSON response is received and
  * an attempt to parse the JSON throws an error. In most cases this can be resolved by retrying the
@@ -30,6 +31,17 @@ function getHeader(config, name) {
     const value = key === undefined ? undefined : config.headers?.[key];
     return typeof value === 'string' ? value : undefined;
 }
+/** Removes a request header regardless of the casing it was set with. */
+function deleteHeader(config, name) {
+    const { headers } = config;
+    if (!headers)
+        return;
+    const wanted = name.toLowerCase();
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === wanted)
+            delete headers[key];
+    }
+}
 function serializeRequest(config) {
     // A string body with an explicit content type is already serialized and goes out as it is. The axios default
     // transform would otherwise parse a JSON one in full just to check that it is valid, which for a body assembled
@@ -79,18 +91,32 @@ function stringifyWithFunctions(obj) {
         return typeof value === 'function' ? value.toString() : value;
     });
 }
-async function maybeCompressRequest(config) {
+/**
+ * Compresses the request body with the client's compressor and labels it with the compressor's `Content-Encoding`.
+ *
+ * Runs after `serializeRequest`, so a JSON body is already a string here. A caller-set `Content-Encoding` is
+ * forwarded verbatim, which is how a pre-encoded body is uploaded, and `Content-Encoding: identity` opts a single
+ * request out of compression. The built-in compressors need `node:zlib`, so a body sent from a browser or an edge
+ * runtime goes out as it is.
+ *
+ * Compressing changes the body length, so any `Content-Length` the caller set describes the wrong body and has to
+ * go. Axios keeps a caller-set one over the size it computes, which would stall the request until it times out.
+ */
+async function maybeCompressRequest(config, compressor) {
+    if (!runtime.isNode)
+        return config;
+    const bytes = toBytes(config.data);
+    if (!bytes || bytes.byteLength < MIN_COMPRESS_BYTES)
+        return config;
     // A caller-supplied encoding means the body is already encoded and the header describes it, so leave both alone.
     if (getHeader(config, 'content-encoding'))
         return config;
     if (!isCompressibleContentType(getHeader(config, 'content-type')))
         return config;
-    const maybeCompressed = await maybeCompressValue(config.data);
-    if (maybeCompressed) {
-        config.headers ??= {};
-        config.headers['content-encoding'] = maybeCompressed.encoding;
-        config.data = maybeCompressed.data;
-    }
+    config.data = await compressor.compress(Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength));
+    config.headers ??= {};
+    config.headers['content-encoding'] = compressor.contentEncoding;
+    deleteHeader(config, 'content-length');
     return config;
 }
 function parseResponseData(response) {
@@ -115,9 +141,13 @@ function parseResponseData(response) {
     }
     return response;
 }
-export const requestInterceptors = [
-    maybeCompressRequest,
-    serializeRequest,
-    ensureHeadersPrototype,
-];
+/**
+ * The client's own request interceptors, in registration order. Axios runs request interceptors in the reverse
+ * order of registration, so the body is serialized before it is compressed, and interceptors registered later,
+ * such as the user-provided ones, run before both.
+ * @internal
+ */
+export function createRequestInterceptors(compressor) {
+    return [async (config) => maybeCompressRequest(config, compressor), serializeRequest, ensureHeadersPrototype];
+}
 export const responseInterceptors = [parseResponseData];

package/dist/resource_clients/dataset.d.ts

@@ -158,13 +158,14 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
     /**
      * Stores one or more items into the dataset.
      *
-     * Items can be objects, strings, or arrays thereof. Each item will be stored as a separate
-     * record in the dataset. Objects are automatically serialized to JSON. If you provide an array,
-     * all items will be stored in order. This method is idempotent - calling it multiple times
-     * with the same data will not create duplicates, but will append items each time.
+     * Each item will be stored as a separate record in the dataset. Objects are automatically
+     * serialized to JSON. If you provide an array, all items will be stored in order. This method
+     * is idempotent - calling it multiple times with the same data will not create duplicates, but
+     * will append items each time.
      *
-     * @param items - A single item (object or string) or an array of items to store.
-     *                Objects are automatically stringified to JSON. Strings are stored as-is.
+     * @param items - A single item, an array of items, or a string that is the JSON serialization of
+     *                either - the API only accepts an object or an array of objects, so a plain string
+     *                is not a valid item on its own.
      * @param options - Request options
      * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @see https://docs.apify.com/api/v2/dataset-items-post
@@ -184,12 +185,9 @@ export declare class DatasetClient<Data extends Record<string | number, any> = R
      *   { url: 'https://test.com', title: 'Test' },
      *   { url: 'https://demo.com', title: 'Demo' }
      * ]);
-     *
-     * // Store string items
-     * await client.dataset('my-dataset').pushItems(['item1', 'item2', 'item3']);
      * ```
      */
-    pushItems(items: Data | Data[] | string | string[], options?: TimeoutOptions): Promise<void>;
+    pushItems(items: Data | Data[] | string, options?: TimeoutOptions): Promise<void>;
     /**
      * Gets statistical information about the dataset.
      *

package/dist/resource_clients/dataset.js

@@ -43,7 +43,7 @@ const downloadItemsOptionsSchema = z.strictObject({
     signature: z.string().optional(),
     ...timeoutOptionsShape,
 });
-const pushItemsSchema = z.union([itemSchema, z.string(), z.array(z.union([itemSchema, z.string()]))]);
+const pushItemsSchema = z.union([itemSchema, z.string(), z.array(itemSchema)]);
 // Apart from `timeoutSecs` and `expiresInSecs`, every option becomes a query parameter of the generated URL, so
 // `chunkSize` (client-side only) and `signature` (which this method produces) are left out. The options type
 // omits both to match.
@@ -255,13 +255,14 @@ export class DatasetClient extends ResourceClient {
     /**
      * Stores one or more items into the dataset.
      *
-     * Items can be objects, strings, or arrays thereof. Each item will be stored as a separate
-     * record in the dataset. Objects are automatically serialized to JSON. If you provide an array,
-     * all items will be stored in order. This method is idempotent - calling it multiple times
-     * with the same data will not create duplicates, but will append items each time.
+     * Each item will be stored as a separate record in the dataset. Objects are automatically
+     * serialized to JSON. If you provide an array, all items will be stored in order. This method
+     * is idempotent - calling it multiple times with the same data will not create duplicates, but
+     * will append items each time.
      *
-     * @param items - A single item (object or string) or an array of items to store.
-     *                Objects are automatically stringified to JSON. Strings are stored as-is.
+     * @param items - A single item, an array of items, or a string that is the JSON serialization of
+     *                either - the API only accepts an object or an array of objects, so a plain string
+     *                is not a valid item on its own.
      * @param options - Request options
      * @param options.timeoutSecs - Timeout for the API request. Default is `'medium'`.
      * @see https://docs.apify.com/api/v2/dataset-items-post
@@ -281,9 +282,6 @@ export class DatasetClient extends ResourceClient {
      *   { url: 'https://test.com', title: 'Test' },
      *   { url: 'https://demo.com', title: 'Demo' }
      * ]);
-     *
-     * // Store string items
-     * await client.dataset('my-dataset').pushItems(['item1', 'item2', 'item3']);
      * ```
      */
     async pushItems(items, options = {}) {

package/dist/runtime/node.js

@@ -1,5 +1,4 @@
 import os from 'node:os';
-import { promisify } from 'node:util';
 import { brotliCompress, constants, gzip } from 'node:zlib';
 /**
  * The Node.js implementation of {@link Runtime}. Deno and Bun resolve the `node` condition too and
@@ -8,24 +7,16 @@ import { brotliCompress, constants, gzip } from 'node:zlib';
 export const runtime = {
     isNode: true,
     platform: `${os.platform()}; Node/${process.version}`,
-    async compress(data) {
-        try {
-            // `promisify()` belongs inside the fallback chain: a partial `node:zlib` can export
-            // `brotliCompress` without implementing it, and `promisify(undefined)` throws. At module scope
-            // that would fail the whole import instead of falling through to gzip.
-            const options = { params: { [constants.BROTLI_PARAM_QUALITY]: 6 } };
-            return { data: await promisify(brotliCompress)(data, options), encoding: 'br' };
-        }
-        catch {
-            // Runtimes that only provide a partial `node:zlib` (Node.js compatibility shims) may not implement
-            // brotli, but usually do implement gzip.
-        }
-        try {
-            return { data: await promisify(gzip)(data), encoding: 'gzip' };
-        }
-        catch {
-            return undefined;
-        }
+    async compress(data, { algorithm, quality }) {
+        return new Promise((resolve, reject) => {
+            const done = (error, result) => (error ? reject(error) : resolve(result));
+            if (algorithm === 'br') {
+                brotliCompress(data, { params: { [constants.BROTLI_PARAM_QUALITY]: quality } }, done);
+            }
+            else {
+                gzip(data, { level: quality }, done);
+            }
+        });
     },
     async createHttpAgents({ timeoutMillis }) {
         // Loaded on the first request rather than with the client: the proxy support pulls in a sizeable

package/dist/runtime/types.d.ts

@@ -1,12 +1,14 @@
 import type http from 'node:http';
 import type https from 'node:https';
 /**
- * A request body compressed for transport, with the `content-encoding` value that declares it.
+ * What to compress a request body with, as the built-in `HttpCompressor` implementations ask for it.
  * @internal
  */
-export interface CompressedValue {
-    data: Uint8Array;
-    encoding: 'br' | 'gzip';
+export interface CompressionOptions {
+    /** Algorithm to compress with, named by the `Content-Encoding` value it produces. */
+    algorithm: 'br' | 'gzip';
+    /** Compression level, in the range the algorithm defines. */
+    quality: number;
 }
 /**
  * The agents axios's Node.js adapter sends requests through.
@@ -25,9 +27,8 @@ export interface HttpAgents {
 export interface Runtime {
     /**
      * Whether the Node.js implementation was selected, which the `node` condition settles when `#runtime` is
-     * resolved - so a Node.js application bundled for a browser or a neutral target reports `false`. The
-     * features that need a Node.js `Readable` response - log streaming and the `stream` record option - are
-     * gated on it.
+     * resolved - so a Node.js application bundled for a browser or a neutral target reports `false`. Log
+     * streaming, the `stream` record option and request body compression are gated on it.
      */
     isNode: boolean;
     /**
@@ -36,10 +37,11 @@ export interface Runtime {
      */
     platform: string | undefined;
     /**
-     * Compresses a request body, or resolves to `undefined` where compression is not available. Compression
-     * is a best-effort optimization, so it never throws.
+     * Compresses a request body. The built-in compressors go through it, so a bundle for a browser or an edge
+     * runtime carries no `node:zlib`. Throws where the runtime has no compression, which the client never
+     * reaches, since it compresses only where {@link isNode} holds.
      */
-    compress(data: Uint8Array): Promise<CompressedValue | undefined>;
+    compress(data: Uint8Array, options: CompressionOptions): Promise<Buffer>;
     /**
      * Creates the agents axios's Node.js adapter sends requests through, or resolves to `undefined` where
      * axios does not use agents.

package/dist/runtime/web.js

@@ -5,10 +5,11 @@ export const runtime = {
     isNode: false,
     // Browsers do not let a page set the `User-Agent` header.
     platform: undefined,
-    // No request compression: brotli has no Web API, and a `content-encoding` request header is not on the
-    // list of headers the Apify API allows in a cross-origin request, so a browser would fail the preflight.
+    // No request compression: brotli and gzip have no Web API, and a `content-encoding` request header is not
+    // on the list of headers the Apify API allows in a cross-origin request, so a browser would fail the
+    // preflight. The client compresses in Node.js alone, so nothing reaches this.
     async compress() {
-        return undefined;
+        throw new Error('Request body compression is only available in Node.js.');
     },
     // The XHR and fetch adapters of axios do not use agents.
     async createHttpAgents() {