feat(javascript): Implement gzip compression (generated)

algolia/api-clients-automation#6052

Co-authored-by: algolia-bot <accounts+algolia-api-client-bot@algolia.com>
Co-authored-by: Mario-Alexandru Dan <marioalexandrudan@gmail.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

packages/client-common/package.json

@@ -34,6 +34,9 @@
     "test": "tsc --noEmit && vitest --run",
     "test:bundle": "publint . && attw --pack ."
   },
+  "dependencies": {
+    "fflate": "0.8.2"
+  },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.2",
     "@types/node": "24.12.0",

packages/client-common/src/__tests__/transporter/compression.test.ts

@@ -0,0 +1,135 @@
+import { gunzipSync } from 'fflate';
+import { beforeEach, describe, expect, test } from 'vitest';
+import { createMemoryCache, createNullCache } from '../../cache';
+import { createNullLogger } from '../../logger';
+import { createTransporter } from '../../transporter';
+import { COMPRESSION_THRESHOLD } from '../../transporter/compress';
+import type { AlgoliaAgent, EndRequest } from '../../types';
+
+// A payload large enough to exceed COMPRESSION_THRESHOLD
+const largePayload = { data: 'x'.repeat(COMPRESSION_THRESHOLD + 1) };
+
+const algoliaAgent: AlgoliaAgent = {
+  value: 'test',
+  add: () => algoliaAgent,
+};
+
+function makeTransporter(compression?: 'gzip', onRequest?: (req: EndRequest) => void) {
+  return createTransporter({
+    hosts: [{ url: 'localhost', accept: 'readWrite', protocol: 'https' }],
+    hostsCache: createNullCache(),
+    baseHeaders: {},
+    baseQueryParameters: {},
+    algoliaAgent,
+    logger: createNullLogger(),
+    timeouts: { connect: 1000, read: 2000, write: 3000 },
+    ...(compression ? { compression } : {}),
+    requester: {
+      send: async (req) => {
+        onRequest?.(req);
+        return { status: 200, content: '{}', isTimedOut: false };
+      },
+    },
+    requestsCache: createMemoryCache(),
+    responsesCache: createMemoryCache(),
+  });
+}
+
+describe('compression', () => {
+  let captured: EndRequest | undefined;
+
+  beforeEach(() => {
+    captured = undefined;
+  });
+
+  test('does not compress when compression is not configured', async () => {
+    const transporter = makeTransporter(undefined, (req) => {
+      captured = req;
+    });
+
+    await transporter.request({
+      method: 'POST',
+      path: '/test',
+      queryParameters: {},
+      headers: {},
+      data: { foo: 'bar' },
+    });
+
+    expect(captured).toBeDefined();
+    expect(captured!.headers['content-encoding']).toBeUndefined();
+    expect(typeof captured!.data).toBe('string');
+    expect(captured!.data).toBe('{"foo":"bar"}');
+  });
+
+  test('compresses POST body when compression is gzip', async () => {
+    const transporter = makeTransporter('gzip', (req) => {
+      captured = req;
+    });
+
+    await transporter.request({ method: 'POST', path: '/test', queryParameters: {}, headers: {}, data: largePayload });
+
+    expect(captured).toBeDefined();
+    expect(captured!.headers['content-encoding']).toBe('gzip');
+    expect(captured!.data).toBeInstanceOf(Uint8Array);
+
+    const decompressed = new TextDecoder().decode(gunzipSync(captured!.data as Uint8Array));
+    expect(decompressed).toBe(JSON.stringify(largePayload));
+  });
+
+  test('compresses PUT body when compression is gzip', async () => {
+    const transporter = makeTransporter('gzip', (req) => {
+      captured = req;
+    });
+
+    await transporter.request({ method: 'PUT', path: '/test', queryParameters: {}, headers: {}, data: largePayload });
+
+    expect(captured).toBeDefined();
+    expect(captured!.headers['content-encoding']).toBe('gzip');
+    expect(captured!.data).toBeInstanceOf(Uint8Array);
+
+    const decompressed = new TextDecoder().decode(gunzipSync(captured!.data as Uint8Array));
+    expect(decompressed).toBe(JSON.stringify(largePayload));
+  });
+
+  test('does not compress POST when body is below threshold', async () => {
+    const transporter = makeTransporter('gzip', (req) => {
+      captured = req;
+    });
+
+    await transporter.request({
+      method: 'POST',
+      path: '/test',
+      queryParameters: {},
+      headers: {},
+      data: { foo: 'bar' },
+    });
+
+    expect(captured).toBeDefined();
+    expect(captured!.headers['content-encoding']).toBeUndefined();
+    expect(typeof captured!.data).toBe('string');
+  });
+
+  test('does not compress GET requests', async () => {
+    const transporter = makeTransporter('gzip', (req) => {
+      captured = req;
+    });
+
+    await transporter.request({ method: 'GET', path: '/test', queryParameters: {}, headers: {} });
+
+    expect(captured).toBeDefined();
+    expect(captured!.headers['content-encoding']).toBeUndefined();
+    expect(captured!.data).toBeUndefined();
+  });
+
+  test('does not compress POST when body is empty', async () => {
+    const transporter = makeTransporter('gzip', (req) => {
+      captured = req;
+    });
+
+    await transporter.request({ method: 'POST', path: '/test', queryParameters: {}, headers: {} });
+
+    expect(captured).toBeDefined();
+    expect(captured!.headers['content-encoding']).toBeUndefined();
+    expect(captured!.data).toBeUndefined();
+  });
+});

packages/client-common/src/transporter/compress.ts

@@ -0,0 +1,11 @@
+import { gzipSync } from 'fflate';
+
+export const COMPRESSION_THRESHOLD = 750;
+
+/**
+ * Compresses a string using gzip via fflate.
+ * Works in both Node.js and browsers with no platform-specific code.
+ */
+export function compress(data: string): Uint8Array {
+  return gzipSync(new TextEncoder().encode(data));
+}

packages/client-common/src/transporter/createTransporter.ts

@@ -9,6 +9,7 @@ import type {
   Transporter,
   TransporterOptions,
 } from '../types';
+import { compress, COMPRESSION_THRESHOLD } from './compress';
 import { createStatefulHost } from './createStatefulHost';
 import { RetryError } from './errors';
 import { deserializeFailure, deserializeSuccess, serializeData, serializeHeaders, serializeUrl } from './helpers';
@@ -31,6 +32,7 @@ export function createTransporter({
   requester,
   requestsCache,
   responsesCache,
+  compression,
 }: TransporterOptions): Transporter {
   async function createRetryableOptions(compatibleHosts: Host[]): Promise<RetryableOptions> {
     const statefulHosts = await Promise.all(
@@ -79,9 +81,20 @@ export function createTransporter({
     /**
      * First we prepare the payload that do not depend from hosts.
      */
-    const data = serializeData(request, requestOptions);
+    const serializedData = serializeData(request, requestOptions);
     const headers = serializeHeaders(baseHeaders, request.headers, requestOptions.headers);
 
+    const shouldCompress =
+      compression === 'gzip' &&
+      serializedData !== undefined &&
+      serializedData.length > COMPRESSION_THRESHOLD &&
+      (request.method === 'POST' || request.method === 'PUT');
+
+    const data = shouldCompress ? compress(serializedData) : serializedData;
+    if (shouldCompress) {
+      headers['content-encoding'] = 'gzip';
+    }
+
     // On `GET`, the data is proxied to query parameters.
     const dataQueryParameters: QueryParameters =
       request.method === 'GET'

packages/client-common/src/transporter/index.ts

@@ -1,3 +1,4 @@
+export * from './compress';
 export * from './createStatefulHost';
 export * from './createTransporter';
 export * from './errors';

packages/client-common/src/types/requester.ts

@@ -41,7 +41,7 @@ export type EndRequest = Pick<Request, 'headers' | 'method'> & {
    * The response timeout, in milliseconds.
    */
   responseTimeout: number;
-  data?: string | undefined;
+  data?: string | Uint8Array | undefined;
 };
 
 export type Response = {

packages/client-common/src/types/transporter.ts

@@ -150,6 +150,14 @@ export type TransporterOptions = {
    * The user agent used. Sent on query parameters.
    */
   algoliaAgent: AlgoliaAgent;
+
+  /**
+   * The compression algorithm to use when sending POST/PUT request bodies.
+   * When set to `'gzip'`, request bodies are gzip-compressed and
+   * `Content-Encoding: gzip` is added to the headers.
+   * Works on all Node.js versions and browsers with no native API requirements.
+   */
+  compression?: 'gzip';
 };
 
 export type Transporter = TransporterOptions & {

packages/client-common/vitest.config.ts

@@ -11,6 +11,7 @@ export default defineConfig({
             'src/__tests__/create-iterable-promise.test.ts',
             'src/__tests__/logger/null-logger.test.ts',
             'src/__tests__/transporter/cache.test.ts',
+            'src/__tests__/transporter/compression.test.ts',
           ],
           name: 'node',
           environment: 'node',

packages/requester-browser-xhr/src/createXhrRequester.ts

@@ -59,7 +59,7 @@ export function createXhrRequester(): Requester {
         });
       };
 
-      baseRequester.send(request.data);
+      baseRequester.send(request.data as XMLHttpRequestBodyInit | null | undefined);
     });
   }
 

packages/requester-fetch/src/createFetchRequester.ts

@@ -32,7 +32,7 @@ export function createFetchRequester({ requesterOptions = {} }: FetchRequesterOp
     try {
       fetchRes = await fetch(request.url, {
         method: request.method,
-        body: request.data || null,
+        body: (request.data as BodyInit) || null,
         redirect: 'manual',
         signal,
         ...requesterOptions,