cellizip 📦

High-performance, zero-dependency TypeScript & JavaScript library for creating and compressing .zip files in memory.

cellizip is designed to work seamlessly in modern JavaScript runtimes: Browser, Node.js (18+), Deno, Bun, and Cloudflare Workers / Edge Runtimes.

---

✨ Features

• 🚀 Zero External Dependencies: Ultra-lightweight, fast, and footprint-free.
• ⚡ DEFLATE & STORE Compression: Uses native CompressionStream for DEFLATE compression and provides synchronous STORE mode.
• 🔤 Full UTF-8 Support: Filenames with special characters, accents, and emojis (UTF-8 Language Encoding Flag PKZIP).
• 🌐 Cross-Platform: Works identically in Browsers and Server runtimes.
• 📘 TypeScript Ready: Written entirely in TypeScript with .d.ts declarations included out of the box.

---

📦 Installation

npm install cellizip
# or
yarn add cellizip
# or
pnpm add cellizip

Or directly import cellizip.ts / dist/cellizip.js into your project!

---

🚀 Quick Start

1. Basic Usage (cellizip Instance)

import cellizip from 'cellizip';

const zip = new cellizip();

// Add text strings, Uint8Array, ArrayBuffer, or Blob
zip.add('hello.txt', 'Hello World!');
zip.add('data/users.json', JSON.stringify([{ id: 1, name: 'Alice' }]));
zip.add('images/logo.png', logoUint8Array);

// Create an empty folder
zip.add('empty_folder/', '', { isDir: true });

// Generate binary ZIP file (Uint8Array) with DEFLATE compression
const zipBuffer = await zip.generateAsync({ compression: 'DEFLATE' });

---

2. Synchronous Generation (STORE Mode)

For scenarios where instant response time is critical without asynchronous processing:

import cellizip from 'cellizip';

const zip = new cellizip();
zip.add('notes.txt', 'Quick content');

const uint8Array = zip.generateSync(); // Ultra-fast synchronous generation

---

3. One-Line Convenience Helpers

import cellizip from 'cellizip';

// Asynchronous ZIP creation
const zipData = await cellizip.zip({
  'file1.txt': 'Text content 1',
  'config.json': '{"active": true}',
});

// Synchronous ZIP creation
const zipSyncData = cellizip.zipSync({
  'file1.txt': 'Text content 1',
  'config.json': '{"active": true}',
});

---

💻 Practical Examples

Browser: Direct User Download

import cellizip from 'cellizip';

async function downloadZip() {
  const zip = new cellizip();
  zip.add('document.pdf', pdfArrayBuffer);
  zip.add('info.txt', 'Created with cellizip!');

  // Helper to generate a Blob ready for browser download
  const blob = await zip.generateBlob({ compression: 'DEFLATE' });

  const link = document.createElement('a');
  link.href = URL.createObjectURL(blob);
  link.download = 'archive.zip';
  link.click();
  URL.revokeObjectURL(link.href);
}

Node.js: Saving Archive to Disk

import cellizip from 'cellizip';
import * as fs from 'node:fs/promises';

async function saveZip() {
  const zip = new cellizip();
  zip.add('report.txt', 'Report generated at ' + new Date().toISOString());

  const zipBytes = await zip.generateAsync({ compression: 'DEFLATE' });
  await fs.writeFile('report.zip', zipBytes);
}

---

📖 API Reference

Class cellizip

Instance Methods

• add(path: string, content?: ZipInput, options?: AddOptions): this Adds a file or directory entry to the ZIP archive.

  • path: File path inside the archive (e.g. 'folder/file.txt').
  • content: String, Uint8Array, ArrayBuffer, or Blob.
  • options:
    • compression: 'STORE' | 'DEFLATE'
    • date: Modification Date object (default: current date).
    • comment: Entry comment.
    • isDir: boolean (true for directories).

• has(path: string): boolean Checks whether an entry exists in the archive.

• remove(path: string): boolean Removes an entry from the archive.

• clear(): void Removes all entries from the archive.

• generateAsync(options?: GenerateOptions): Promise<Uint8Array> Generates the binary ZIP archive asynchronously.

  • options.compression: 'STORE' | 'DEFLATE' (default: 'STORE')
  • options.comment: Global ZIP archive comment.

• generateSync(options?: GenerateOptions): Uint8Array Generates the binary ZIP archive synchronously (uses 'STORE' mode).

• generateBlob(options?: GenerateOptions, mimeType?: string): Promise<Blob> Browser helper to return a Blob representation of the ZIP archive.

Static Methods

• cellizip.zip(entries: Record<string, ZipInput>, options?: GenerateOptions): Promise<Uint8Array> One-line asynchronous ZIP creation.

• cellizip.zipSync(entries: Record<string, Exclude<ZipInput, Blob>>, options?: GenerateOptions): Uint8Array One-line synchronous ZIP creation.

---

🛠️ Utility Exports

• crc32(data: Uint8Array): number: Calculates the CRC-32 checksum of a byte array.
• toDosDateTime(date: Date): { time: number, date: number }: Converts a JavaScript Date to 16-bit MS-DOS time and date numbers.

---

📜 License

MIT © 2026