or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mddata-io.mdfilesystem.mdindex.mdreading.mdstreaming.mdwriting.md
tile.json

tessl/npm-zip-js--zip-js

JavaScript library for compressing and decompressing ZIP files in browsers, Node.js, and Deno with support for encryption, ZIP64, and web workers

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@zip.js/zip.js@2.7.x

To install, run

npx @tessl/cli install tessl/npm-zip-js--zip-js@2.7.0

index.mddocs/

@zip.js/zip.js

Package Information

  • Package Name: @zip.js/zip.js
  • Type: Library
  • Language: JavaScript/TypeScript
  • Installation: npm install @zip.js/zip.js

Overview

zip.js is a powerful JavaScript library for creating and reading ZIP files in browsers, Deno, and Node.js environments. It provides a comprehensive set of APIs for ZIP file manipulation with support for advanced features and optimal performance across different JavaScript runtime environments.

Key Features

  • Multi-core compression via web workers for improved performance
  • Large file support with Zip64 format (files > 4GB)
  • Data encryption using AES-256, AES-192, AES-128, and ZipCrypto algorithms
  • Split ZIP files for handling size-constrained storage
  • Streaming operations for memory-efficient processing of large archives
  • Multiple data sources including Blob, ArrayBuffer, ReadableStream, HTTP ranges
  • Filesystem-like API for complex ZIP manipulation scenarios
  • Native compression streams support for optimal performance
  • Cross-platform compatibility (browsers, Node.js, Deno, Bun)

Core Imports

ESM (Recommended)

import {
  ZipReader,
  ZipWriter,
  BlobReader,
  BlobWriter,
  TextReader,
  TextWriter,
  configure
} from "@zip.js/zip.js";

CommonJS

const {
  ZipReader,
  ZipWriter,
  BlobReader,
  BlobWriter,
  TextReader,
  TextWriter,
  configure
} = require("@zip.js/zip.js");

Alternative Entry Points

// Full API with embedded codecs
import * as zip from "@zip.js/zip.js/lib/zip-full.js";

// Filesystem API
import { fs } from "@zip.js/zip.js/lib/zip-fs.js";

// No web workers
import * as zip from "@zip.js/zip.js/lib/zip-no-worker.js";

Basic Usage

import {
  ZipReader,
  ZipWriter,
  BlobReader,
  BlobWriter,
  TextReader,
  TextWriter
} from "@zip.js/zip.js";

// Create a ZIP file
const zipWriter = new ZipWriter(new BlobWriter("application/zip"));
await zipWriter.add("hello.txt", new TextReader("Hello World!"));
const zipBlob = await zipWriter.close();

// Read a ZIP file
const zipReader = new ZipReader(new BlobReader(zipBlob));
const entries = await zipReader.getEntries();
const text = await entries[0].getData(new TextWriter());
await zipReader.close();
console.log(text); // "Hello World!"

Architecture

zip.js is designed with a modular architecture supporting different use cases and environments while maintaining optimal performance and memory efficiency.

Core Components

Core API (@zip.js/zip.js)

  • ZipReader/ZipWriter - Primary classes for ZIP operations
  • Reader/Writer abstraction for different data sources/destinations
  • Configurable web worker support for non-blocking operations

Streaming API

  • ZipReaderStream/ZipWriterStream - Stream-based processing
  • Memory-efficient handling of large files
  • Pipeline-compatible with web streams

Filesystem API (@zip.js/zip.js/lib/zip-fs.js)

  • FS class providing filesystem-like operations
  • ZipDirectoryEntry/ZipFileEntry for hierarchical manipulation
  • Import/export capabilities with multiple data formats

Build Variants

  • Default build: Web workers + compression streams
  • Full build (zip-full.js): Embedded codecs, no external dependencies
  • No-worker builds: Synchronous operation variants
  • Filesystem build (zip-fs.js): High-level filesystem API

Web Worker Architecture

zip.js uses web workers for non-blocking compression/decompression:

  • Automatic worker management and load balancing
  • Configurable worker count and termination timeout
  • Fallback to main thread when workers unavailable

Configuration

Global library configuration for web workers, compression, and codecs.

function configure(configuration: Configuration): void;

interface Configuration extends WorkerConfiguration {
  maxWorkers?: number;
  terminateWorkerTimeout?: number;
  workerScripts?: {
    deflate?: string[];
    inflate?: string[];
  };
  chunkSize?: number;
  Deflate?: typeof ZipDeflate;
  Inflate?: typeof ZipInflate;
  CompressionStream?: typeof TransformStream;
  DecompressionStream?: typeof TransformStream;
}

interface WorkerConfiguration {
  useWebWorkers?: boolean;
  useCompressionStream?: boolean;
}

Configuration Details

Data Input/Output

Classes for reading from and writing to different data sources and destinations.

Reader Classes

class Reader<Type> {
  constructor(value: Type);
  readonly readable: ReadableStream;
  readonly size: number;
  init?(): Promise<void>;
  readUint8Array(index: number, length: number): Promise<Uint8Array>;
}

class TextReader extends Reader<string> {}
class BlobReader extends Reader<Blob> {}
class Data64URIReader extends Reader<string> {}
class Uint8ArrayReader extends Reader<Uint8Array> {}
class HttpReader extends Reader<string> {
  constructor(url: string | URL, options?: HttpOptions);
}
class HttpRangeReader extends HttpReader {
  constructor(url: string | URL, options?: HttpRangeOptions);
}
class SplitDataReader extends Reader<(Reader<unknown> | ReadableReader | ReadableStream)[]> {}

Writer Classes

class Writer<Type> {
  readonly writable: WritableStream;
  init?(size?: number): Promise<void>;
  writeUint8Array(array: Uint8Array): Promise<void>;
  getData(): Promise<Type>;
}

class TextWriter extends Writer<string> {
  constructor(encoding?: string);
}
class BlobWriter {
  constructor(mimeString?: string);
  readonly writable: WritableStream;
  init(): Promise<void>;
  getData(): Promise<Blob>;
}
class Data64URIWriter extends Writer<string> {
  constructor(mimeString?: string);
}
class Uint8ArrayWriter extends Writer<Uint8Array> {}
class SplitDataWriter {
  constructor(
    writerGenerator: AsyncGenerator<Writer<unknown> | WritableWriter | WritableStream, boolean>,
    maxSize?: number
  );
  readonly writable: WritableStream;
  init(): Promise<void>;
}

Data Input/Output Details

ZIP Reading

Reading and extracting from ZIP files.

class ZipReader<Type> {
  constructor(
    reader: Reader<Type> | ReadableReader | ReadableStream | (Reader<unknown> | ReadableReader | ReadableStream)[],
    options?: ZipReaderConstructorOptions
  );
  
  readonly comment: Uint8Array;
  readonly prependedData?: Uint8Array;
  readonly appendedData?: Uint8Array;
  
  getEntries(options?: ZipReaderGetEntriesOptions): Promise<Entry[]>;
  getEntriesGenerator(options?: ZipReaderGetEntriesOptions): AsyncGenerator<Entry, boolean>;
  close(): Promise<void>;
}

type Entry = DirectoryEntry | FileEntry;

interface DirectoryEntry extends EntryMetaData {
  directory: true;
  getData?: undefined;
}

interface FileEntry extends EntryMetaData {
  directory: false;
  getData<Type>(
    writer: Writer<Type> | WritableWriter | WritableStream | AsyncGenerator<Writer<unknown> | WritableWriter | WritableStream, boolean>,
    options?: EntryGetDataOptions
  ): Promise<Type>;
  arrayBuffer(options?: EntryGetDataOptions): Promise<ArrayBuffer>;
}

ZIP Reading Details

ZIP Writing

Creating and modifying ZIP files.

class ZipWriter<Type> {
  constructor(
    writer: Writer<Type> | WritableWriter | WritableStream | AsyncGenerator<Writer<unknown> | WritableWriter | WritableStream, boolean>,
    options?: ZipWriterConstructorOptions
  );
  
  readonly hasCorruptedEntries?: boolean;
  
  prependZip<ReaderType>(
    reader: Reader<ReaderType> | ReadableReader | ReadableStream | (Reader<unknown> | ReadableReader | ReadableStream)[]
  ): Promise<void>;
  
  add<ReaderType>(
    filename: string,
    reader?: Reader<ReaderType> | ReadableReader | ReadableStream | (Reader<unknown> | ReadableReader | ReadableStream)[],
    options?: ZipWriterAddDataOptions
  ): Promise<EntryMetaData>;
  
  remove(entry: Entry | string): boolean;
  close(comment?: Uint8Array, options?: ZipWriterCloseOptions): Promise<Type>;
}

ZIP Writing Details

Streaming API

Stream-based ZIP operations for efficient processing of large files.

class ZipReaderStream<T> {
  constructor(options?: ZipReaderConstructorOptions);
  
  readonly readable: ReadableStream<Omit<Entry, "getData"> & { readable?: ReadableStream<Uint8Array> }>;
  readonly writable: WritableStream<T>;
}

class ZipWriterStream {
  constructor(options?: ZipWriterConstructorOptions);
  
  readonly readable: ReadableStream<Uint8Array>;
  readonly zipWriter: ZipWriter<unknown>;
  
  transform<T>(path: string): { readable: ReadableStream<T>; writable: WritableStream<T> };
  writable<T>(path: string): WritableStream<T>;
  close(comment?: Uint8Array, options?: ZipWriterCloseOptions): Promise<unknown>;
}

Streaming API Details

Filesystem API

High-level filesystem-like operations for complex ZIP manipulation.

const fs: {
  FS: typeof FS;
  ZipDirectoryEntry: typeof ZipDirectoryEntry;
  ZipFileEntry: typeof ZipFileEntry;
};

class FS extends ZipDirectoryEntry {
  readonly root: ZipDirectoryEntry;
  
  remove(entry: ZipEntry): void;
  move(entry: ZipEntry, destination: ZipDirectoryEntry): void;
  find(fullname: string): ZipEntry | undefined;
  getById(id: number): ZipEntry | undefined;
}

Filesystem API Details

Utilities

function getMimeType(fileExtension: string): string;
function terminateWorkers(): Promise<void>;
function initShimAsyncCodec(
  library: EventBasedZipLibrary,
  constructorOptions: unknown | null,
  registerDataHandler: registerDataHandler
): ZipLibrary;

Error Constants

const ERR_HTTP_RANGE: string;
const ERR_BAD_FORMAT: string;
const ERR_EOCDR_NOT_FOUND: string;
const ERR_EOCDR_LOCATOR_ZIP64_NOT_FOUND: string;
const ERR_CENTRAL_DIRECTORY_NOT_FOUND: string;
const ERR_LOCAL_FILE_HEADER_NOT_FOUND: string;
const ERR_EXTRAFIELD_ZIP64_NOT_FOUND: string;
const ERR_ENCRYPTED: string;
const ERR_UNSUPPORTED_ENCRYPTION: string;
const ERR_UNSUPPORTED_COMPRESSION: string;
const ERR_INVALID_SIGNATURE: string;
const ERR_INVALID_UNCOMPRESSED_SIZE: string;
const ERR_INVALID_PASSWORD: string;
const ERR_DUPLICATED_NAME: string;
const ERR_INVALID_COMMENT: string;
const ERR_INVALID_ENTRY_NAME: string;
const ERR_INVALID_ENTRY_COMMENT: string;
const ERR_INVALID_VERSION: string;
const ERR_INVALID_EXTRAFIELD_TYPE: string;
const ERR_INVALID_EXTRAFIELD_DATA: string;
const ERR_INVALID_ENCRYPTION_STRENGTH: string;
const ERR_UNSUPPORTED_FORMAT: string;
const ERR_SPLIT_ZIP_FILE: string;
const ERR_OVERLAPPING_ENTRY: string;
const ERR_ITERATOR_COMPLETED_TOO_SOON: string;
const ERR_UNDEFINED_UNCOMPRESSED_SIZE: string;
const ERR_WRITER_NOT_INITIALIZED: string;
const ERR_ZIP_NOT_EMPTY: string;

Types

EntryMetaData

interface EntryMetaData {
  offset: number;
  filename: string;
  rawFilename: Uint8Array;
  filenameUTF8: boolean;
  directory: boolean;
  executable: boolean;
  encrypted: boolean;
  zipCrypto: boolean;
  compressedSize: number;
  uncompressedSize: number;
  lastModDate: Date;
  lastAccessDate?: Date;
  creationDate?: Date;
  rawLastModDate: number | bigint;
  rawLastAccessDate?: number | bigint;
  rawCreationDate?: number | bigint;
  comment: string;
  rawComment: Uint8Array;
  commentUTF8: boolean;
  signature: number;
  extraField?: Map<number, { type: number; data: Uint8Array }>;
  rawExtraField: Uint8Array;
  zip64: boolean;
  version: number;
  versionMadeBy: number;
  msDosCompatible: boolean;
  internalFileAttributes: number;
  externalFileAttributes: number;
  diskNumberStart: number;
  compressionMethod: number;
}

HTTP Options

interface HttpOptions extends HttpRangeOptions {
  useRangeHeader?: boolean;
  forceRangeRequests?: boolean;
  preventHeadRequest?: boolean;
  combineSizeEocd?: boolean;
}

interface HttpRangeOptions {
  useXHR?: boolean;
  headers?: Iterable<[string, string]> | Map<string, string>;
}

Reader/Writer Interfaces

interface Initializable {
  init?(): Promise<void>;
}

interface ReadableReader {
  readable: ReadableStream;
}

interface WritableWriter {
  writable: WritableStream;
  maxSize?: number;
}

Event-based Codec Interfaces

interface EventBasedZipLibrary {
  Deflate: typeof EventBasedCodec;
  Inflate: typeof EventBasedCodec;
}

interface ZipLibrary {
  Deflate: typeof ZipDeflate;
  Inflate: typeof ZipInflate;
}

interface registerDataHandler {
  (codec: EventBasedCodec, onData: dataHandler): void;
}

interface dataHandler {
  (data: Uint8Array): void;
}

Option Interfaces

interface ZipReaderConstructorOptions extends ZipReaderOptions, GetEntriesOptions, WorkerConfiguration {
  extractPrependedData?: boolean;
  extractAppendedData?: boolean;
}

interface ZipReaderGetEntriesOptions extends GetEntriesOptions, EntryOnprogressOptions {}

interface GetEntriesOptions {
  filenameEncoding?: string;
  commentEncoding?: string;
  decodeText?(value: Uint8Array, encoding: string): string | undefined;
}

interface ZipReaderOptions {
  checkPasswordOnly?: boolean;
  checkSignature?: boolean;
  checkOverlappingEntry?: boolean;
  checkOverlappingEntryOnly?: boolean;
  password?: string;
  passThrough?: boolean;
  rawPassword?: Uint8Array;
  signal?: AbortSignal;
  preventClose?: boolean;
  transferStreams?: boolean;
}

interface EntryGetDataOptions extends EntryDataOnprogressOptions, ZipReaderOptions, WorkerConfiguration {}

interface ZipWriterConstructorOptions {
  zip64?: boolean;
  preventClose?: boolean;
  level?: number;
  bufferedWrite?: boolean;
  keepOrder?: boolean;
  password?: string;
  rawPassword?: Uint8Array;
  encryptionStrength?: 1 | 2 | 3;
  signal?: AbortSignal;
  lastModDate?: Date;
  lastAccessDate?: Date;
  creationDate?: Date;
  extendedTimestamp?: boolean;
  zipCrypto?: boolean;
  version?: number;
  versionMadeBy?: number;
  useUnicodeFileNames?: boolean;
  dataDescriptor?: boolean;
  dataDescriptorSignature?: boolean;
  msDosCompatible?: boolean;
  externalFileAttributes?: number;
  internalFileAttributes?: number;
  supportZip64SplitFile?: boolean;
  usdz?: boolean;
  passThrough?: boolean;
  encrypted?: boolean;
  offset?: number;
  compressionMethod?: number;
  encodeText?(text: string): Uint8Array | undefined;
}

interface ZipWriterAddDataOptions extends ZipWriterConstructorOptions, EntryDataOnprogressOptions, WorkerConfiguration {
  directory?: boolean;
  executable?: boolean;
  comment?: string;
  extraField?: Map<number, Uint8Array>;
  uncompressedSize?: number;
  signature?: number;
}

interface ZipWriterCloseOptions extends EntryOnprogressOptions {
  zip64?: boolean;
  preventClose?: boolean;
}

interface EntryDataOnprogressOptions {
  onstart?(total: number): Promise<void> | undefined;
  onprogress?(progress: number, total: number): Promise<void> | undefined;
  onend?(computedSize: number): Promise<void> | undefined;
}

interface EntryOnprogressOptions {
  onprogress?(progress: number, total: number, entry: EntryMetaData): Promise<void> | undefined;
}

declare class SyncCodec {
  append(data: Uint8Array): Uint8Array;
}

declare class ZipDeflate extends SyncCodec {
  flush(): Uint8Array;
}

declare class ZipInflate extends SyncCodec {
  flush(): void;
}

declare class EventBasedCodec {
  push(data: Uint8Array): void;
  ondata(data?: Uint8Array): void;
}