Why compress-kit? 🤔

• 📉 Strong Compression – Achieves size reductions of ~30% to 90% on typical text and JSON data using the Deflate algorithm via pako.
• 🔁 Lossless Algorithms – Ensures perfect reconstruction of the original data.
• 🧪 Strict Validation - Robust input checks and type validation for predictable results.
• 🌐 Cross-Platform – Works seamlessly in Web, Node.js, Deno, Bun and Cloudflare Workers.
• 💡 Typed and Ergonomic - Type-safe API with both throwing and non-throwing (Result) flavors.
• 🍼 Explain Like I'm Five - Newbie-friendly explanations and documentation.

Installation 🔥

npm install compress-kit@latest
# or
yarn add compress-kit@latest
# or
pnpm install compress-kit@latest
# or
bun add compress-kit@latest

Quick Start 🚀

import { compress, compressObj, decompress, decompressObj } from "compress-kit";

const compressed = compress(longString);
const original = decompress(compressed);
console.log(original);

const compressedObj = compressObj(longObject);
const originalObj = decompressObj<typeof longObject>(compressedObj);
console.log(originalObj);

API Reference 📚

The try Prefix (Non-Throwing Result API) 🤔

The try prefix functions return a Result<T> object that indicates success or failure without throwing exceptions.

This is useful in scenarios where you want to handle errors gracefully without using try/catch blocks.

// Throwing version - simpler but requires try/catch
const msg = compress("long message");
console.log(`Compressed message: ${msg}`);
// Non-throwing version - returns a Result<T> object
const msg = tryCompress("long message");

// Either check for success status
if (msg.success) console.log(`Compressed message: ${msg.result}`);
else console.error(`${msg.error.message} - ${msg.error.description}`);

// Or Check that there is no error
if (!msg.error) console.log(`Compressed message: ${msg.result}`);
else console.error(`${msg.error.message} - ${msg.error.description}`);

Compression & Decompression 🤫

Compression is the process of reducing a data's size by removing redundancies, making it faster to transmit and requiring less storage space. Decompression is the reverse process, restoring the original data from its compressed form.

import { compress, compressObj, decompress, decompressObj } from "compress-kit";

const longString = `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.`;

const compressed = compress(longString);
const original = decompress(compressed);
console.log(original);

const longObj = {
  name: "John Doe",
  age: 30,
  city: "New York",
  occupation: "Developer",
  hobbies: ["coding", "gaming", "reading"],
  isActive: true,
  scores: { math: 95, english: 88, science: 92 },
  friends: ["Alice", "Bob", "Charlie"],
};

const compressedObj = compressObj(longObj);
const originalObj = decompressObj<typeof longObj>(compressedObj);
console.log(originalObj);

The compress and decompress functions handle strings, while compressObj and decompressObj work with JavaScript objects, serializing them to JSON for compression. They both accept an optional option parameter to customize the compression process.

export interface CompressOptions {
  // Encoding format for the output compressed data (default: `'base64url'`).
  outputEncoding?: "base64" | "base64url" | "hex";

  // Compression level (1-9; default: 6).
  level?: number;

  // Size of the compression window: 2^windowBits (8-15; default: 15).
  windowBits?: number;

  // Memory usage for compression match finder (1-9; default: 8).
  memLevel?: number;

  // Compression strategy, 95% of cases should use 'default' (default: 'default').
  strategy?: "default" | "filtered" | "huffmanOnly" | "rle" | "fixed";
}

export interface DecompressOptions {
  // Encoding format for the input compressed data (default: `'base64url'`).
  inputEncoding?: "base64" | "base64url" | "hex";

  // Size of the compression window: 2^windowBits (8-15; default: 15).
  windowBits?: number;
}

Credit 💪🏽

Huge credit to pako for the underlying compression and decompression algorithms used in this package.

Contributions 🤝

Want to contribute or suggest a feature or improvement?

• Open an issue or feature request
• Submit a PR to improve the packages or add new ones
• Star ⭐ the repo if you like what you see