@tokenizer/inflate

@tokenizer/inflate is a package designed for handling and extracting data from ZIP files efficiently using a tokenizer-based approach. The library provides a customizable way to parse ZIP archives and extract compressed data while minimizing memory usage.

Features

• Efficient Decompression: Handles streams compressed with DEFLATE and related formats (e.g., gzip).
• Tokenizer Compatibility: Seamlessly integrates with strtok3. For example, use @tokenizer/s3 for efficient partial extraction of a Zip stored on AWS S3 cloud file storage.
• Streamlined Interface: Provides an intuitive API for working with compressed data in streaming and random-access scenarios.
• Chunked Data Access: Leverages the underlying media's capabilities to offer chunked or random access to data, unlike traditional streams.
• Plug-and-Play: Easily integrate with existing tokenizer-based workflows for parsing file metadata or binary structures.
• Interrupt the extraction process conditionally.

Installation

1npm install @tokenizer/inflate

Usage

Example: Extracting Specific Files

The following example demonstrates how to use the library to extract .txt files and stop processing when encountering a .stop file.

1import { ZipHandler } from '@tokenizer/inflate';
2import { fromFile } from 'strtok3';
3
4const fileFilter = (file) => {
5  console.log(`Processing file: ${file.filename}`);
6
7  if (file.filename?.endsWith(".stop")) {
8    console.log(`Stopping processing due to file: ${file.filename}`);
9    return { handler: false, stop: true }; // Stop the unzip process
10  }
11
12  if (file.filename?.endsWith(".txt")) {
13    return {
14      handler: async (data) => {
15        console.log(`Extracted text file: ${file.filename}`);
16        console.log(new TextDecoder().decode(data));
17      },
18    };
19  }
20
21  return { handler: false }; // Ignore other files
22};
23
24async function extractFiles(zipFilePath) {
25  const tokenizer = await fromFile(zipFilePath);
26  const zipHandler = new ZipHandler(tokenizer);
27  await zipHandler.unzip(fileFilter);
28}
29
30extractFiles('example.zip').catch(console.error);

API

ZipHandler

A class for handling ZIP file parsing and extraction.

Constructor

1new ZipHandler(tokenizer: ITokenizer)

• tokenizer: An instance of ITokenizer to read the ZIP archive.

Methods

• isZip(): Promise<boolean>

  Determines whether the input file is a ZIP archive.

• unzip(fileCb: InflateFileFilter): Promise<void>

  Extracts files from the ZIP archive, applying the provided InflateFileFilter callback to each file.

InflatedDataHandler

Types

InflateFileFilter

1type InflateFileFilter = (file: IFullZipHeader) => InflateFileFilterResult;

Callback function to determine whether a file should be handled or ignored.

InflateFileFilterResult

1type InflateFileFilterResult = {
2  handler: InflatedDataHandler | false; // Handle file data or ignore
3  stop?: boolean; // Stop processing further files
4};
5

Returned from InflateFileFilter to control file handling and extraction flow.

InflatedDataHandler

1type InflatedDataHandler = (fileData: Uint8Array) => Promise<void>;

Handler for processing uncompressed file data.

Compatibility

This module is a pure ECMAScript Module (ESM). The distributed JavaScript codebase is compliant with the ECMAScript 2020 (11th Edition) standard. If used with Node.js, it requires version ≥ 18.

License

This project is licensed under the MIT License. See the LICENSE file for details.