feat(javascript): Implement gzip compression (#6052)

MarioAlexandruDan · claude · web-flow · commit 2d6c9b272746 · 2026-03-11T15:08:30.000+01:00
Co-authored-by: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/clients/algoliasearch-client-javascript/packages/client-common/package.json b/clients/algoliasearch-client-javascript/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",
diff --git a/clients/algoliasearch-client-javascript/packages/client-common/src/__tests__/transporter/compression.test.ts b/clients/algoliasearch-client-javascript/packages/client-common/src/__tests__/transporter/compression.test.ts
@@ -0,0 +1,123 @@
+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();
+  });
+});
diff --git a/clients/algoliasearch-client-javascript/packages/client-common/src/transporter/compress.ts b/clients/algoliasearch-client-javascript/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));
+}
diff --git a/clients/algoliasearch-client-javascript/packages/client-common/src/transporter/createTransporter.ts b/clients/algoliasearch-client-javascript/packages/client-common/src/transporter/createTransporter.ts
@@ -11,6 +11,7 @@ import type {
 } from '../types';
 import { createStatefulHost } from './createStatefulHost';
 import { RetryError } from './errors';
+import { compress, COMPRESSION_THRESHOLD } from './compress';
 import { deserializeFailure, deserializeSuccess, serializeData, serializeHeaders, serializeUrl } from './helpers';
 import { isRetryable, isSuccess } from './responses';
 import { stackFrameWithoutCredentials, stackTraceWithoutCredentials } from './stackTrace';
@@ -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'
diff --git a/clients/algoliasearch-client-javascript/packages/client-common/src/transporter/index.ts b/clients/algoliasearch-client-javascript/packages/client-common/src/transporter/index.ts
@@ -1,3 +1,4 @@
+export * from './compress';
 export * from './createStatefulHost';
 export * from './createTransporter';
 export * from './errors';
diff --git a/clients/algoliasearch-client-javascript/packages/client-common/src/types/requester.ts b/clients/algoliasearch-client-javascript/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 = {
diff --git a/clients/algoliasearch-client-javascript/packages/client-common/src/types/transporter.ts b/clients/algoliasearch-client-javascript/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 & {
diff --git a/clients/algoliasearch-client-javascript/packages/client-common/vitest.config.ts b/clients/algoliasearch-client-javascript/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',
diff --git a/clients/algoliasearch-client-javascript/packages/requester-browser-xhr/src/createXhrRequester.ts b/clients/algoliasearch-client-javascript/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);
     });
   }
 
diff --git a/clients/algoliasearch-client-javascript/packages/requester-fetch/src/createFetchRequester.ts b/clients/algoliasearch-client-javascript/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,
diff --git a/clients/algoliasearch-client-javascript/packages/requester-testing/src/createEchoRequester.ts b/clients/algoliasearch-client-javascript/packages/requester-testing/src/createEchoRequester.ts
@@ -63,7 +63,7 @@ export function createEchoRequester({ getURL, status = 200 }: EchoRequesterParam
 
     const content: EchoResponse = {
       ...request,
-      data: request.data ? JSON.parse(request.data) : undefined,
+      data: request.data ? JSON.parse(request.data as string) : undefined,
       path,
       host,
       algoliaAgent,
diff --git a/clients/algoliasearch-client-javascript/yarn.lock b/clients/algoliasearch-client-javascript/yarn.lock
@@ -86,6 +86,7 @@ __metadata:
   dependencies:
     "@arethetypeswrong/cli": "npm:0.18.2"
     "@types/node": "npm:24.12.0"
+    fflate: "npm:0.8.2"
     jsdom: "npm:27.4.0"
     publint: "npm:0.3.18"
     ts-node: "npm:10.9.2"
@@ -4524,7 +4525,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"fflate@npm:^0.8.2":
+"fflate@npm:0.8.2, fflate@npm:^0.8.2":
   version: 0.8.2
   resolution: "fflate@npm:0.8.2"
   checksum: 10/2bd26ba6d235d428de793c6a0cd1aaa96a06269ebd4e21b46c8fd1bd136abc631acf27e188d47c3936db090bf3e1ede11d15ce9eae9bffdc4bfe1b9dc66ca9cb
diff --git a/generators/src/main/java/com/algolia/codegen/cts/tests/TestsClient.java b/generators/src/main/java/com/algolia/codegen/cts/tests/TestsClient.java
@@ -104,7 +104,7 @@ public void run(Map<String, CodegenModel> models, Map<String, CodegenOperation>
 
               boolean gzipEncoding = step.parameters != null && step.parameters.getOrDefault("gzip", false).equals(true);
               // many languages don't support gzip yet
-              if (gzipEncoding && (language.equals("javascript") || language.equals("dart"))) {
+              if (gzipEncoding && language.equals("dart")) {
                 continue skipTest;
               }
               stepOut.put("gzipEncoding", gzipEncoding);
diff --git a/templates/javascript/tests/client/createClient.mustache b/templates/javascript/tests/client/createClient.mustache
@@ -18,7 +18,10 @@
     },
     {{/customHosts}}
     ],
-    {{/hasCustomHosts}} 
+    {{/hasCustomHosts}}
+    {{#gzipEncoding}}
+    compression: 'gzip',
+    {{/gzipEncoding}}
     {{#hasTransformationRegion}}
     transformation: { region : "{{{transformationRegion}}}" },
     {{/hasTransformationRegion}} 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+export * from './compress';`
`1`	`2`	`export * from './createStatefulHost';`
`2`	`3`	`export * from './createTransporter';`
`3`	`4`	`export * from './errors';`
Original file line number	Diff line number	Diff line change
`@@ -59,7 +59,7 @@ export function createXhrRequester(): Requester {`
`59`	`59`	`});`
`60`	`60`	`};`
`61`	`61`
`62`		`- baseRequester.send(request.data);`
	`62`	`+ baseRequester.send(request.data as XMLHttpRequestBodyInit \| null \| undefined);`
`63`	`63`	`});`
`64`	`64`	`}`
`65`	`65`