Pako - JavaScript Zlib Compression

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES module environment (e.g., Node.js with `"type": "module"` in `package.json`, or a browser without a bundler that transpiles CJS).
  fix For Pako v2.x, ensure your environment supports CommonJS or use a bundler (like Webpack or Rollup) configured for CJS interop. For Pako v3.x, switch to ES module imports: `import { deflate } from 'pako';`

• TypeError: pako.deflate is not a function

  cause This typically occurs when using `import pako from 'pako'` with Pako v3, or when mixing CJS/ESM import styles. In v3, `deflate` (and other core functions) are named exports, not properties of a default `pako` object.
  fix For Pako v3, change your import to `import { deflate, inflate } from 'pako';` and call them directly as `deflate(...)`, `inflate(...)`. If using v2 with a bundler that mishandles default exports, try `import * as pako from 'pako';` or stick to `const pako = require('pako');`.

• Error: incorrect header check

  cause The input data provided to `pako.inflate` (or `Inflate` class) is corrupted, incomplete, or was compressed with a different format than expected (e.g., raw deflate data passed to `inflate` expecting gzip, or vice versa).
  fix Verify the integrity and completeness of your compressed data. Ensure that the `format` option for `inflate` (e.g., `windowBits`) matches the format used during compression. For example, use `pako.inflate(data, { raw: true })` for raw deflate data, or `pako.inflate(data, { to: 'string' })` if expecting UTF-8 output from a compatible `deflate` operation.

Warnings

• breaking Starting with v3.0.0, Pako transitioned to an ESM-first package. While bundlers may handle CJS interop, direct `require('pako')` for the main entry point will lead to issues, and `import pako from 'pako'` will behave differently or require specific build configurations compared to v2.x.
  Fix: For CommonJS environments, explicitly import from `pako/index.cjs` or `pako/dist/pako.cjs.js`. For ESM, use named imports like `import { deflate, inflate } from 'pako';` and adjust code to new top-level exports.
• breaking In Pako v3.x, methods like `deflate`, `inflate`, `deflateRaw`, and `inflateRaw` are now direct named exports from the top-level `pako` module, rather than properties of a default `pako` object (e.g., `pako.deflate`). This changes the way these functions are accessed.
  Fix: Update imports from `const pako = require('pako'); pako.deflate(...)` to `import { deflate } from 'pako'; deflate(...)` (for ESM) or `const { deflate } = require('pako/index.cjs'); deflate(...)` (for CJS).
• gotcha When using the streaming `Deflate` or `Inflate` classes, errors are not thrown as exceptions directly but are instead indicated by the `err` property on the instance after `push` operations. Failing to check `deflator.err` or `inflator.err` can lead to silent data corruption or incomplete results.
  Fix: Always check `if (deflator.err)` or `if (inflator.err)` after pushing chunks or at the end of the stream processing to ensure data integrity and proper error handling.

Install

• npm install pako npm
• yarn add pako yarn
• pnpm add pako pnpm

Imports

• pako
  wrong:

  import pako from 'pako';

  correct:

  const pako = require('pako');

  For pako v2.x, the main export is a CommonJS module. Direct ES module imports may behave unexpectedly or require bundler configuration for CJS interop. Pako v3.x transitioned to ESM-first.
• Deflate class
  wrong:

  import { Deflate } from 'pako';

  correct:

  const { Deflate } = require('pako');

  In pako v2.x, `Deflate` is a named property of the main CommonJS export. For pako v3.x, `Deflate` is a top-level named ES module export.
• inflate function
  wrong:

  import { inflate } from 'pako';

  correct:

  const { inflate } = require('pako');

  In pako v2.x, `inflate` is a named property of the main CommonJS export. For pako v3.x, `inflate` is a top-level named ES module export.

Quickstart

Demonstrates basic string compression/decompression using `deflate` and `inflate` with string conversion, including an example of the streaming API for larger data handling.

const pako = require('pako');

const data = { message: 'Hello, pako!', timestamp: Date.now(), items: ['a', 'b', 'c'] };
const stringifiedData = JSON.stringify(data);

console.log('Original size (bytes):', Buffer.byteLength(stringifiedData, 'utf8'));

// Compress stringified data
const compressed = pako.deflate(stringifiedData, { level: 9 }); // Use highest compression level
console.log('Compressed size (bytes):', compressed.length);

// Decompress back to string
const restoredString = pako.inflate(compressed, { to: 'string' });
console.log('Decompressed string matches original:', restoredString === stringifiedData);

const restoredData = JSON.parse(restoredString);
console.log('Restored data:', restoredData);

// Demonstrating stream interface for larger data
const deflator = new pako.Deflate();
deflator.push(new TextEncoder().encode('First chunk of data. '), false);
deflator.push(new TextEncoder().encode('Second chunk, and this is the end.'), true);

if (deflator.err) {
  console.error('Deflate error:', deflator.msg);
} else {
  console.log('Stream compressed data length:', deflator.result.length);
}