s3-zip

[![npm version][npm-badge]][npm-url]
[![Build Status][gh-actions-badge]][gh-actions-url]

Download selected files from an Amazon S3 bucket as a zip file.

Install

``
npm install s3-zip
`

AWS Configuration

Refer to the [AWS SDK][aws-sdk-url] for authenticating to AWS prior to using this plugin.

Usage

$3

`javascript

const fs = require('fs')
const join = require('path').join
const s3Zip = require('s3-zip')

const region = 'bucket-region'
const bucket = 'name-of-s3-bucket'
const folder = 'name-of-bucket-folder/'
const file1 = 'Image A.png'
const file2 = 'Image B.png'
const file3 = 'Image C.png'
const file4 = 'Image D.png'

const output = fs.createWriteStream(join(__dirname, 'use-s3-zip.zip'))

s3Zip
.archive({ region: region, bucket: bucket}, folder, [file1, file2, file3, file4])
.pipe(output)

`

You can also pass a custom S3 client. For example if you want to zip files from a S3 compatible storage:

`javascript
const { S3Client } = require('@aws-sdk/client-s3')

const s3Client = new S3Client({
region: 'us-east-1',
endpoint: 'http://localhost:9000',
forcePathStyle: true
})

s3Zip
.archive({ s3: s3Client, bucket: bucket }, folder, [file1, file2])
.pipe(output)
`

Note: When passing a custom S3 client, it must be an AWS SDK v3 client (from @aws-sdk/client-s3). AWS SDK v2 clients are not supported and will result in an error.

$3

Example of s3-zip in combination with AWS Lambda.

$3

`javascript
const fs = require('fs')
const join = require('path').join
const {
S3Client
} = require("@aws-sdk/client-s3")
const s3Zip = require('s3-zip')
const XmlStream = require('xml-stream')

const region = 'bucket-region'
const bucket = 'name-of-s3-bucket'
const folder = 'name-of-bucket-folder/'
const s3 = new S3Client({ region: region })
const params = {
Bucket: bucket,
Prefix: folder
}

const filesArray = []
const files = s3.listObjects(params).createReadStream()
const xml = new XmlStream(files)
xml.collect('Key')
xml.on('endElement: Key', function(item) {
filesArray.push(item['$text'].substring(folder.length))
})

xml
.on('end', function () {
zip(filesArray)
})

function zip(files) {
console.log(files)
const output = fs.createWriteStream(join(__dirname, 'use-s3-zip.zip'))
s3Zip
.archive({ region: region, bucket: bucket, preserveFolderStructure: true }, folder, files)
.pipe(output)
}
`

$3

`javascript
s3Zip
.setFormat('tar')
.archive({ region: region, bucket: bucket }, folder, [file1, file2])
.pipe(output)
`

$3

`javascript
s3Zip
.setRegisterFormatOptions('zip-encrypted', require("archiver-zip-encrypted"))
.setFormat('zip-encryptable')
.setArchiverOptions({zlib: {level: 8}, encryptionMethod: 'aes256', password: '123'})
.archive({ region: region, bucket: bucket }, folder, [file1, file2])
.pipe(output)
`

$3

We use [archiver][archiver-url] to create archives. To pass your options to it, use setArchiverOptions method:

`javascript
s3Zip
.setFormat('tar')
.setArchiverOptions({ gzip: true })
.archive({ region: region, bucket: bucket }, folder, [file1, file2])
`

$3

You can pass an array of objects with type [EntryData][entrydata-url] to organize your archive.

`javascript
const files = ['flower.jpg', 'road.jpg']
const archiveFiles = [
{ name: 'newFolder/flower.jpg' },

/ _rw_______ /
{ name: 'road.jpg', mode: parseInt('0600', 8) }
];
s3Zip.archive({ region: region, bucket: bucket }, folder, files, archiveFiles)
`

$3

s3-zip works with any framework which leverages on NodeJS Streams including ExpressJS.

`javascript
const s3Zip = require('s3-zip')

app.get('/download', (req, res) => {
s3Zip
.archive({ region: region, bucket: bucket }, '', 'abc.jpg')
.pipe(res)
})
`
Above should stream out the file in the response of the request.

$3

Enable debug mode to see the logs:

`javascript
s3Zip.archive({ region: region, bucket: bucket, debug: true }, folder, files)
`

Testing

Tests are written in Node Tap, run them like this:

`
npm t
`

If you would like a more fancy coverage report:

`
npm run coverage
`

Publishing

This package is automatically published to NPM when a new release is created on GitHub. The publishing workflow:

1. Triggers on GitHub releases
2. Runs tests to ensure quality
3. Publishes to NPM using the NPM_TOKEN secret

$3

To enable automatic publishing, the repository requires an NPM_TOKEN secret to be configured in GitHub:

1. Generate an NPM access token with publish permissions
2. Add it as a repository secret named NPM_TOKEN` in GitHub Settings > Secrets and variables > Actions

The workflow can also be triggered manually from the Actions tab for testing purposes.

[aws-sdk-url]: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/configuring-the-jssdk.html
[npm-badge]: https://badge.fury.io/js/s3-zip.svg
[npm-url]: https://badge.fury.io/js/s3-zip
[gh-actions-badge]: https://github.com/orangewise/s3-zip/actions/workflows/test.yml/badge.svg?branch=master
[gh-actions-url]: https://github.com/orangewise/s3-zip/actions/workflows/test.yml
[archiver-url]: https://www.npmjs.com/package/archiver
[entrydata-url]: https://archiverjs.com/docs/global.html#EntryData