zlib.js: JavaScript Compression Library

Common errors

• TypeError: Zlib.Deflate is not a constructor

  cause The Zlib object was not correctly imported or is not available in the current scope. This typically happens if the CommonJS `require` path is wrong or if using ESM `import` syntax.
  fix Ensure you are using `const Zlib = require('zlibjs/bin/node-zlib.js');` for Node.js environments. For browsers, ensure `zlib_and_gzip.min.js` or similar files are loaded globally before usage.

• ReferenceError: Zlib is not defined

  cause The Zlib object was not imported or included in the environment.
  fix In Node.js, ensure `require('zlibjs/bin/node-zlib.js')` is called and assigned to a `Zlib` variable. In browsers, verify that the appropriate `zlib.js` distribution file is included via a `<script>` tag before your application code.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax in a CommonJS-only Node.js environment or without proper bundler configuration.
  fix This package does not officially support ESM. Use CommonJS `require()` syntax instead: `const Zlib = require('zlibjs/bin/node-zlib.js');`.

Warnings

• breaking This package is no longer actively maintained, with the last release in July 2017. It may contain unpatched security vulnerabilities, compatibility issues with newer Node.js versions or browser environments, and lacks modern features or performance optimizations.
  Fix: Consider migrating to actively maintained libraries like `pako` for browser/universal use or Node.js's built-in `zlib` module for server-side applications, which offer better performance, security, and modern APIs.
• gotcha The GZIP implementation in zlib.js is explicitly stated as 'incomplete' in the README, though it claims to be sufficient for 'usual use'. Developers should test thoroughly for edge cases or specific GZIP features they require.
  Fix: Always validate GZIP compressed output with other tools and consider alternatives if full GZIP specification compliance is critical.
• gotcha The package primarily targets CommonJS for Node.js via a specific path ('zlibjs/bin/node-zlib.js') and global 'Zlib' for browsers. It does not provide official ESM exports, requiring manual adaptation for modern module bundlers or native ESM environments.
  Fix: Use CommonJS `require()` syntax directly. For browser environments, ensure the correct minified script is loaded globally. Modern bundlers might require specific configurations (e.g., aliasing or CJS compatibility loaders) to integrate it.
• deprecated The `lazy` matching parameter in `Zlib.Deflate` options is explicitly marked as deprecated in the README documentation.
  Fix: Avoid using the `lazy` option and rely on default or other configuration parameters for compression settings.
• gotcha zlib.js uses `Array.<number>` or `Uint8Array` for all input and output data. Incorrectly passing JavaScript strings or other data types will lead to runtime errors or corrupted compression.
  Fix: Always convert string data to `Uint8Array` before passing it to compression functions, and convert decompressed `Uint8Array` back to strings as needed. Helper functions like `stringToByteArray` are often necessary.

Install

• npm install zlibjs npm
• yarn add zlibjs yarn
• pnpm add zlibjs pnpm

Imports

• Zlib
  wrong:

  import Zlib from 'zlibjs';

  correct:

  const Zlib = require('zlibjs/bin/node-zlib.js');

  For Node.js, the 'node-zlib.js' entry point is required, and it exports a single 'Zlib' object containing all compression/decompression classes. Browser usage typically involves loading a .min.js file which exposes 'Zlib' globally.
• Deflate
  wrong:

  import { Deflate } from 'zlibjs';

  correct:

  const Zlib = require('zlibjs/bin/node-zlib.js'); const compressor = new Zlib.Deflate(plainData);

  The 'Deflate' class is accessed as a property of the main 'Zlib' object loaded via CommonJS, not as a direct named export from the package.
• Inflate
  wrong:

  import { Inflate } from 'zlibjs/bin/node-zlib.js';

  correct:

  const Zlib = require('zlibjs/bin/node-zlib.js'); const decompressor = new Zlib.Inflate(compressedData);

  Similar to 'Deflate', the 'Inflate' class is a property of the 'Zlib' object and not directly importable via ESM syntax, which is not supported by this package anyway.

Quickstart

This quickstart demonstrates ZLIB compression and decompression, along with a basic GZIP compression example, using the Node.js entry point of zlib.js. It highlights how to initialize Deflate, Inflate, Gzip, and Gunzip classes, handle data as Uint8Array, and convert between strings and byte arrays.

import { Buffer } from 'buffer';

const Zlib = require('zlibjs/bin/node-zlib.js');

function stringToByteArray(str: string): Uint8Array {
    const array = new Uint8Array(str.length);
    for (let i = 0; i < str.length; ++i) {
        array[i] = str.charCodeAt(i) & 0xff;
    }
    return array;
}

const originalString = 'Hello, zlib.js! This is a test string to demonstrate compression and decompression capabilities.';
const plainData = stringToByteArray(originalString);

console.log('Original data length:', plainData.length);

// Compress using ZLIB Deflate
const deflate = new Zlib.Deflate(plainData, {
  compressionType: Zlib.Deflate.CompressionType.DYNAMIC
});
const compressed = deflate.compress();

console.log('Compressed data length (Deflate):', compressed.length);

// Decompress using ZLIB Inflate
const inflate = new Zlib.Inflate(compressed);
const decompressed = inflate.decompress();

console.log('Decompressed data length (Inflate):', decompressed.length);

const decompressedString = Buffer.from(decompressed).toString('utf8');
console.log('Decompressed string:', decompressedString);

if (originalString === decompressedString) {
  console.log('Compression and decompression successful!');
} else {
  console.error('Data mismatch after compression/decompression.');
}

// GZIP Compression example
const gzip = new Zlib.Gzip(plainData, {
    flags: { fname: true, comment: false, fhcrc: false },
    filename: stringToByteArray('test.txt')
});
const gzipped = gzip.compress();
console.log('GZIP compressed data length:', gzipped.length);

// GZIP Decompression example
const gunzip = new Zlib.Gunzip(gzipped);
const gunzipped = gunzip.decompress();
console.log('GZIP decompressed data length:', gunzipped.length);
const gunzippedString = Buffer.from(gunzipped).toString('utf8');
console.log('GZIP decompressed string:', gunzippedString);