Zipster

Zipster aims to enable developers to rapidly and easily create password-protected ZIP files. With various handy functions available to satisfy different use-cases, this promise-based library is built using TypeScript and uses native Node functionality and leverages two primary libraries.

Although the fundamental principle behind Zipster is password-protected ZIP files, you can also create unprotected ZIP files and pass in a number of different options to configure how your ZIP files are created.

This project is still in development. Please report any bugs or feature requests as an issue.

Contents

• Getting Started
• Installation
• Usage
  • Create a ZIP with a single file
  • Create a ZIP with multiple files
  • Create a ZIP from a directory
  • Create a ZIP with a pattern
  • Options
  • Password Example
  • Supported Formats
• Tests
• Issues
• Contributions
• License

Getting Started

You can get started with cloning the Zipster repository by using the following command:

$ git clone git@github.com:ToeFungi/zipster.git
$ cd zipster
$ npm i

Installation

Use the following command to install the Zipster package:

npm i zipster

Usage

There are various ways in which you can create your ZIP file and even more options on how you want it configured. You can set a password or not, compress or not, specify patterns to match for zipping files, etc.

Here are some examples of how to use the functionality provided by this package:

.fromPath(path: string, options: Options)

Create an unprotected ZIP file containing a single specified file

const path = '/some/path/to/my/file.txt'
const options: Options = {
  format: Formats.ZIP
}

Zipster.fromPath(path, options)
  .then((outputPath: string) => console.log({ outputPath }, 'Successfully created ZIP'))

.fromPaths(paths: string[], options: Options)

Create an unprotected ZIP file containing multiple specified files

const paths = [
  '/some/path/to/my/file.txt',
  '/some/path/to/my/file.csv'
]
const options: Options = {
  format: Formats.ZIP
}

Zipster.fromPaths(paths, options)
  .then((outputPath: string) => console.log({ outputPath }, 'Successfully created ZIP'))

.fromDirectory(path: string, options: Options)

Create an unprotected ZIP file containing all the sub-directories at a given path, retaining the folder structure of the sub-directories

const path = '/some/path/to/my/directory'
const options: Options = {
  format: Formats.ZIP
}

Zipster.fromDirectory(path, options)
  .then((outputPath: string) => console.log({ outputPath }, 'Successfully created ZIP'))

.fromPattern(path: string, pattern: string, options: Options)

Create an unprotected ZIP file containing all the files matching the given pattern at the given path

const path = '/some/path/to/my/directory'
const pattern = 'foo*.txt'
const options: Options = {
  format: Formats.ZIP
}

Zipster.fromPattern(path, pattern, options)
  .then((outputPath: string) => console.log({ outputPath }, 'Successfully created ZIP'))

Options

Option	Default	Description
format	null	Whether the ZIP should be password protected or not
password	null	The password for the ZIP if applicable format is specified
output name	UUID V4	The name of the ZIP file to be created
output path	OS Specific	The path to where the ZIP file should be created

Password Example

Create a password-protected ZIP file containing the specified file

const path = '/some/path/to/my/file.txt'
const options: Options = {
  format: Formats.ZIP_ENCRYPTABLE,
  password: 'super-sensitive-password'
}

Zipster.fromPath(path, options)
  .then((outputPath: string) => console.log({ outputPath }, 'Successfully created ZIP'))

Supported Formats

There are currently only two formats that are supported, the .zip and .tar formats. The zip format is the only format which supports password protection. The password format is specifically available through the Formats enum.

Tests

To run tests, you should be able to simply run be able to run the following.

$ npm run test
$ npm run coverage

The testing framework used is Mocha. Chai, Chai-as-promised and nyc are used for assertions and coverage reporting respectively. Ensure that any new changes are covered by an accompanying test suite.

Issues

If you find any problems while working with this library, please log an issue here so that development can begin to rectify the error.

Contributions

This project is completely open source and as such, you are invited to make contributions. Fork the project, make some changes and make the pull request. If you have any feedback regarding the functionality, please don't hesitate to open an issue so this can be resolved. Please ensure that any pull requests have unit tests that cover any additional functionality.

License

MIT License

Copyright (c) 2021 Alex Pickering