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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@zip.js/zip.js

Name: tessl/npm-zip-js--zip-js
Author: tessl

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;
}