Skip to content

mikbry/anzip

Repository files navigation

Anzip

Build Status codecov NPM version License

Anzip is a library to unzip file archive for Node using only one async function.

Purpose

  • Simple to use
  • Modern ES6+ syntax (import instead of require, await/async, ...)
  • Unzip by Yauzl
  • Follows Node best practices

Requirements

  • Node >= 12

Install

yarn add anzip

Or using npm

npm add anzip

Usage

Now that ESM support is widely common, require should be forgotten.

import anzip from 'anzip';

Extract file.zip to current path

await anzip('file.zip');

Extract file.zip to the current path and get output

const output = await anzip('file.zip');
console.log('duration=', output.duration);
console.log('number of files=', output.files.length);

Extract only README.md from file.zip to current path

const output = await anzip('file.zip', { pattern: 'README.md', });
console.log('duration=', output.duration);
console.log('number of files=', output.files.length); // Should be one

Extract only README.md from file.zip to output content variable

const output = await anzip('file.zip', { pattern: 'README.md', outputContent: true });
console.log('duration=', output.duration);
console.log('content=', output.files[0].content);

Extract only README.md from file.zip to output content variable and currentpath

const output = await anzip('file.zip', { pattern: 'README.md', outputPath: './', outputContent: true });
console.log('duration=', output.duration);
console.log('content=', output.files[0].content);

Extract with an entryHandler to fliter entry

const outputPath = './path';
const entryHandler = async entry => {
  let resp = true;
  const fn = entry.name;
  if (fn.endsWith('dummy.pdf')) {
    try {
      await entry.saveTo(outputPath);
      resp = false;
    } catch (e) {
      //
    }
  }
  return resp;
};
const output = await anzip('file.zip',
    outputPath,
    { pattern: /(^(?!\.))(.+(.png|.jpeg|.jpg|.svg|.pdf|.json))$/i,, outputPath: './', entryHandler, outputContent: true });
console.log('duration=', output.duration);
// ./path/dummy.pdf should be saved

Extract using 2 rules and an entryHandler in one to fliter entry

const outputPath = './path';
const entryHandler = async entry => {
  let resp = true;
  const fn = entry.name;
  if (fn.endsWith('dummy.pdf')) {
    try {
      await entry.saveTo(outputPath);
      resp = false;
    } catch (e) {
      //
    }
  }
  return resp;
};
const output = await anzip('file.zip',
    outputPath,
    pattern: /(^(?!\.))(.+(.png|.jpeg|.jpg|.svg|.pdf|.json))$/i,
    flattenPath: true,
    disableSave: true,
    disableOutput: true,
    rules: [
      { pattern: /(^(?!\.))(test.json)$/i, outputContent: true },
      { pattern: /(^(?!\.))(.+(.png|.jpeg|.jpg|.svg|.pdf))$/i, entryHandler },
    ],
  });
console.log('duration=', output.duration);
// ./path/dummy.pdf should be saved

Documentation

One function to rule them all.

output = await anzip(filename, {opts})

Function properties

parameters type description
filename mandatory string containing zip path to + file
opts optional object containing optional parameters
opts.outputPath optional string the directory where to to save extracted files
opts.outputContent optional boolean if set to true, return file.content a Buffer containing file's content
opts.disableSave optional boolean if set to true, don't save files
opts.pattern optional regex if set only extract/proceed matching filenames
opts.flattenPath optional boolean if set don't recreate zip's directories, all file are saved in outputPath
opts.disableOutput optional boolean if set don't write files to output
opts.entryHandler optional promise use it to add some extra processing to an entry, return true if stream is consumed otherwise false
opts.rules optional array use it to add some fine tuned control how to handle each files
opts.rules.pattern mandatory regex if it match entry will use rule's parameters instead of global's one

Returned output is an object containing:

parameters type description
duration number how long it took to extract in seconds
files array all files extracted or handled, otherwise empty
files[x].name string the filename
files[x].directory string the directory in archive (even if opts.flattenPath=true)
files[x].saved boolean true if the file was saved to outputPath
files[x].content Buffer the content of the file available if opts.outputContent=true or rule.outputContent=true
files[x].error Error if an error occured

Contribution

Read Contributing Guide for development setup instructions.