bestzip 2.2.4 → 2.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +21 -21
  2. package/bin/cli.js +48 -48
  3. package/lib/bestzip.js +182 -182
  4. package/package.json +47 -48
  5. package/readme.md +92 -92
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2018 Nathan Friedly - http://nfriedly.com/
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in
13
- all copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
- THE SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2018 Nathan Friedly - http://nfriedly.com/
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
package/bin/cli.js CHANGED
@@ -1,48 +1,48 @@
1
- #!/usr/bin/env node
2
-
3
- "use strict";
4
-
5
- var zip = require("../lib/bestzip.js");
6
-
7
- var argv = require("yargs")
8
- .usage("\nUsage: bestzip destination.zip sources/")
9
- .option("force", {
10
- describe: "Force use of node.js or native zip methods",
11
- choices: ["node", "native"],
12
- })
13
- .option("level", {
14
- describe: "Level of compression",
15
- type: "number",
16
- default: -1,
17
- })
18
- .demand(2).argv;
19
-
20
- var destination = argv._.shift();
21
- var source = argv._;
22
-
23
- if (argv.level < -1 || argv.level > 9) {
24
- console.error("Invalid compression level, must be >= 0 and <= 9");
25
- process.exit(1);
26
- }
27
-
28
- console.log("Writing %s to %s...", source.join(", "), destination);
29
-
30
- if (argv.force === "node") {
31
- zip = zip.nodeZip;
32
- } else if (argv.force === "native") {
33
- zip = zip.nativeZip;
34
- }
35
-
36
- zip({
37
- source: source,
38
- destination: destination,
39
- verbose: !!argv.verbose,
40
- level: argv.level,
41
- })
42
- .then(function () {
43
- console.log("zipped!");
44
- })
45
- .catch(function (err) {
46
- console.error(err);
47
- process.exit(1);
48
- });
1
+ #!/usr/bin/env node
2
+
3
+ "use strict";
4
+
5
+ var zip = require("../lib/bestzip.js");
6
+
7
+ var argv = require("yargs")
8
+ .usage("\nUsage: bestzip destination.zip sources/")
9
+ .option("force", {
10
+ describe: "Force use of node.js or native zip methods",
11
+ choices: ["node", "native"],
12
+ })
13
+ .option("level", {
14
+ describe: "Level of compression",
15
+ type: "number",
16
+ default: -1,
17
+ })
18
+ .demand(2).argv;
19
+
20
+ var destination = argv._.shift();
21
+ var source = argv._;
22
+
23
+ if (argv.level < -1 || argv.level > 9) {
24
+ console.error("Invalid compression level, must be >= 0 and <= 9");
25
+ process.exit(1);
26
+ }
27
+
28
+ console.log("Writing %s to %s...", source.join(", "), destination);
29
+
30
+ if (argv.force === "node") {
31
+ zip = zip.nodeZip;
32
+ } else if (argv.force === "native") {
33
+ zip = zip.nativeZip;
34
+ }
35
+
36
+ zip({
37
+ source: source,
38
+ destination: destination,
39
+ verbose: !!argv.verbose,
40
+ level: argv.level,
41
+ })
42
+ .then(function () {
43
+ console.log("zipped!");
44
+ })
45
+ .catch(function (err) {
46
+ console.error(err);
47
+ process.exit(1);
48
+ });
package/lib/bestzip.js CHANGED
@@ -1,182 +1,182 @@
1
- // creates a zip file using either the native `zip` command if available,
2
- // or a node.js zip implementation otherwise.
3
-
4
- "use strict";
5
-
6
- const cp = require("child_process");
7
- const fs = require("fs");
8
- const path = require("path");
9
-
10
- const archiver = require("archiver");
11
- const { glob, hasMagic } = require("glob");
12
- const which = require("which");
13
-
14
- function hasNativeZip() {
15
- return Boolean(which.sync("zip", { nothrow: true }));
16
- }
17
-
18
- async function expandSources(cwd, source) {
19
- // options to behave more like the native zip's glob support
20
- const globOpts = {
21
- cwd,
22
- dot: false, // ignore .dotfiles
23
- noglobstar: true, // treat ** as *
24
- noext: true, // no (a|b)
25
- nobrace: true, // no {a,b}
26
- };
27
-
28
- // first handle arrays
29
- if (Array.isArray(source)) {
30
- const results = await Promise.all(source.map((s) => expandSources(cwd, s)));
31
- return results.flat();
32
- }
33
-
34
- // then expand magic
35
- if (typeof source !== "string") {
36
- throw new Error(`source is (${typeof source}) `);
37
- }
38
-
39
- if (hasMagic(source, globOpts)) {
40
- // archiver uses this library but somehow ends up with different results on windows:
41
- // archiver.glob('*') will include subdirectories, but omit their contents on windows
42
- // so we'll use glob directly, and add all of the files it finds
43
- return await glob(source, globOpts);
44
- } else {
45
- // or just trigger the callback with the source string if there is no magic
46
- // always return an array
47
- return [source];
48
- }
49
- }
50
-
51
- function walkDir(fullPath) {
52
- const files = fs.readdirSync(fullPath).map((f) => {
53
- const filePath = path.join(fullPath, f);
54
- const stats = fs.statSync(filePath);
55
- if (stats.isDirectory()) {
56
- return walkDir(filePath);
57
- }
58
- return filePath;
59
- });
60
- return files.reduce((acc, cur) => acc.concat(cur), []);
61
- }
62
-
63
- const nativeZip = async (options) => {
64
- const cwd = options.cwd || process.cwd();
65
- const command = "zip";
66
- const sources = await expandSources(cwd, options.source);
67
-
68
- const args = ["--quiet", "--recurse-paths", options.destination].concat(
69
- sources
70
- );
71
- if (
72
- typeof options.level == "number" &&
73
- !isNaN(options.level) &&
74
- options.level >= 0 &&
75
- options.level <= 9
76
- ) {
77
- args.splice(0, 0, "-" + options.level.toString());
78
- }
79
-
80
- return new Promise((resolve, reject) => {
81
- const zipProcess = cp.spawn(command, args, {
82
- stdio: "inherit",
83
- cwd,
84
- });
85
- zipProcess.on("error", reject);
86
- zipProcess.on("close", (exitCode) => {
87
- if (exitCode === 0) {
88
- resolve();
89
- } else {
90
- reject(
91
- new Error(
92
- `Unexpected exit code from native zip: ${exitCode}\n executed command '${command} ${args.join(
93
- " "
94
- )}'\n executed in directory '${cwd}'`
95
- )
96
- );
97
- }
98
- });
99
- });
100
- };
101
-
102
- // based on http://stackoverflow.com/questions/15641243/need-to-zip-an-entire-directory-using-node-js/18775083#18775083
103
- const nodeZip = async (options) => {
104
- const cwd = options.cwd || process.cwd();
105
- const output = fs.createWriteStream(path.resolve(cwd, options.destination));
106
- const archive = archiver("zip", {
107
- zlib: { level: options.level },
108
- });
109
-
110
- output.on("close", () => resolvePromise());
111
- archive.on("error", (err) => rejectPromise(err));
112
-
113
- archive.pipe(output);
114
-
115
- let resolvePromise;
116
- let rejectPromise;
117
- const promise = new Promise((resolve, reject) => {
118
- resolvePromise = resolve;
119
- rejectPromise = reject;
120
- });
121
-
122
- async function addSource(source) {
123
- const fullPath = path.resolve(cwd, source);
124
- const destPath = source;
125
-
126
- const stats = await fs.promises.stat(fullPath);
127
- if (stats.isDirectory()) {
128
- // Walk directory. Works on directories and directory symlinks.
129
- const files = walkDir(fullPath);
130
- files.forEach((f) => {
131
- const subPath = f.substring(fullPath.length);
132
- archive.file(f, {
133
- name: destPath + subPath,
134
- });
135
- });
136
- } else if (stats.isFile()) {
137
- archive.file(fullPath, { stats: stats, name: destPath });
138
- }
139
- }
140
-
141
- try {
142
- const expandedSources = await expandSources(cwd, options.source);
143
- for (const source of expandedSources) {
144
- await addSource(source);
145
- }
146
- archive.finalize();
147
- } catch (err) {
148
- rejectPromise(err);
149
- }
150
-
151
- return promise;
152
- };
153
-
154
- function zip(options) {
155
- const compatMode = typeof options === "string";
156
- if (compatMode) {
157
- options = {
158
- source: arguments[1],
159
- destination: arguments[0],
160
- };
161
- }
162
-
163
- let promise;
164
- if (hasNativeZip()) {
165
- promise = nativeZip(options);
166
- } else {
167
- promise = nodeZip(options);
168
- }
169
-
170
- if (compatMode) {
171
- promise.then(arguments[2]).catch(arguments[2]);
172
- } else {
173
- return promise;
174
- }
175
- }
176
-
177
- module.exports = zip;
178
- module.exports.zip = zip;
179
- module.exports.nodeZip = nodeZip;
180
- module.exports.nativeZip = nativeZip;
181
- module.exports.bestzip = zip;
182
- module.exports.hasNativeZip = hasNativeZip;
1
+ // creates a zip file using either the native `zip` command if available,
2
+ // or a node.js zip implementation otherwise.
3
+
4
+ "use strict";
5
+
6
+ const cp = require("child_process");
7
+ const fs = require("fs");
8
+ const path = require("path");
9
+
10
+ const archiver = require("archiver");
11
+ const { glob, hasMagic } = require("glob");
12
+ const which = require("which");
13
+
14
+ function hasNativeZip() {
15
+ return Boolean(which.sync("zip", { nothrow: true }));
16
+ }
17
+
18
+ async function expandSources(cwd, source) {
19
+ // options to behave more like the native zip's glob support
20
+ const globOpts = {
21
+ cwd,
22
+ dot: false, // ignore .dotfiles
23
+ noglobstar: true, // treat ** as *
24
+ noext: true, // no (a|b)
25
+ nobrace: true, // no {a,b}
26
+ };
27
+
28
+ // first handle arrays
29
+ if (Array.isArray(source)) {
30
+ const results = await Promise.all(source.map((s) => expandSources(cwd, s)));
31
+ return results.flat();
32
+ }
33
+
34
+ // then expand magic
35
+ if (typeof source !== "string") {
36
+ throw new Error(`source is (${typeof source}) `);
37
+ }
38
+
39
+ if (hasMagic(source, globOpts)) {
40
+ // archiver uses this library but somehow ends up with different results on windows:
41
+ // archiver.glob('*') will include subdirectories, but omit their contents on windows
42
+ // so we'll use glob directly, and add all of the files it finds
43
+ return await glob(source, globOpts);
44
+ } else {
45
+ // or just trigger the callback with the source string if there is no magic
46
+ // always return an array
47
+ return [source];
48
+ }
49
+ }
50
+
51
+ function walkDir(fullPath) {
52
+ const files = fs.readdirSync(fullPath).map((f) => {
53
+ const filePath = path.join(fullPath, f);
54
+ const stats = fs.statSync(filePath);
55
+ if (stats.isDirectory()) {
56
+ return walkDir(filePath);
57
+ }
58
+ return filePath;
59
+ });
60
+ return files.reduce((acc, cur) => acc.concat(cur), []);
61
+ }
62
+
63
+ const nativeZip = async (options) => {
64
+ const cwd = options.cwd || process.cwd();
65
+ const command = "zip";
66
+ const sources = await expandSources(cwd, options.source);
67
+
68
+ const args = ["--quiet", "--recurse-paths", options.destination, "--"].concat(
69
+ sources
70
+ );
71
+ if (
72
+ typeof options.level == "number" &&
73
+ !isNaN(options.level) &&
74
+ options.level >= 0 &&
75
+ options.level <= 9
76
+ ) {
77
+ args.splice(0, 0, "-" + options.level.toString());
78
+ }
79
+
80
+ return new Promise((resolve, reject) => {
81
+ const zipProcess = cp.spawn(command, args, {
82
+ stdio: "inherit",
83
+ cwd,
84
+ });
85
+ zipProcess.on("error", reject);
86
+ zipProcess.on("close", (exitCode) => {
87
+ if (exitCode === 0) {
88
+ resolve();
89
+ } else {
90
+ reject(
91
+ new Error(
92
+ `Unexpected exit code from native zip: ${exitCode}\n executed command '${command} ${args.join(
93
+ " "
94
+ )}'\n executed in directory '${cwd}'`
95
+ )
96
+ );
97
+ }
98
+ });
99
+ });
100
+ };
101
+
102
+ // based on http://stackoverflow.com/questions/15641243/need-to-zip-an-entire-directory-using-node-js/18775083#18775083
103
+ const nodeZip = async (options) => {
104
+ const cwd = options.cwd || process.cwd();
105
+ const output = fs.createWriteStream(path.resolve(cwd, options.destination));
106
+ const archive = archiver("zip", {
107
+ zlib: { level: options.level },
108
+ });
109
+
110
+ output.on("close", () => resolvePromise());
111
+ archive.on("error", (err) => rejectPromise(err));
112
+
113
+ archive.pipe(output);
114
+
115
+ let resolvePromise;
116
+ let rejectPromise;
117
+ const promise = new Promise((resolve, reject) => {
118
+ resolvePromise = resolve;
119
+ rejectPromise = reject;
120
+ });
121
+
122
+ async function addSource(source) {
123
+ const fullPath = path.resolve(cwd, source);
124
+ const destPath = source;
125
+
126
+ const stats = await fs.promises.stat(fullPath);
127
+ if (stats.isDirectory()) {
128
+ // Walk directory. Works on directories and directory symlinks.
129
+ const files = walkDir(fullPath);
130
+ files.forEach((f) => {
131
+ const subPath = f.substring(fullPath.length);
132
+ archive.file(f, {
133
+ name: destPath + subPath,
134
+ });
135
+ });
136
+ } else if (stats.isFile()) {
137
+ archive.file(fullPath, { stats: stats, name: destPath });
138
+ }
139
+ }
140
+
141
+ try {
142
+ const expandedSources = await expandSources(cwd, options.source);
143
+ for (const source of expandedSources) {
144
+ await addSource(source);
145
+ }
146
+ archive.finalize();
147
+ } catch (err) {
148
+ rejectPromise(err);
149
+ }
150
+
151
+ return promise;
152
+ };
153
+
154
+ function zip(options) {
155
+ const compatMode = typeof options === "string";
156
+ if (compatMode) {
157
+ options = {
158
+ source: arguments[1],
159
+ destination: arguments[0],
160
+ };
161
+ }
162
+
163
+ let promise;
164
+ if (hasNativeZip()) {
165
+ promise = nativeZip(options);
166
+ } else {
167
+ promise = nodeZip(options);
168
+ }
169
+
170
+ if (compatMode) {
171
+ promise.then(arguments[2]).catch(arguments[2]);
172
+ } else {
173
+ return promise;
174
+ }
175
+ }
176
+
177
+ module.exports = zip;
178
+ module.exports.zip = zip;
179
+ module.exports.nodeZip = nodeZip;
180
+ module.exports.nativeZip = nativeZip;
181
+ module.exports.bestzip = zip;
182
+ module.exports.hasNativeZip = hasNativeZip;
package/package.json CHANGED
@@ -1,48 +1,47 @@
1
- {
2
- "name": "bestzip",
3
- "version": "2.2.4",
4
- "description": "Uses OS zip command if available (for better performance and speed) or node.js version if there is no system command available. Can be called via node or command line.",
5
- "main": "lib/bestzip.js",
6
- "bin": {
7
- "bestzip": "bin/cli.js"
8
- },
9
- "engines": {
10
- "node": ">=20"
11
- },
12
- "scripts": {
13
- "lint": "eslint .",
14
- "lint-fix": "eslint --fix .",
15
- "unit-test": "jest",
16
- "test": "npm run lint && npm run unit-test"
17
- },
18
- "author": "Nathan Friedly - http://nfriedly.com/",
19
- "license": "MIT",
20
- "repository": {
21
- "type": "git",
22
- "url": "git+ssh://git@github.com/nfriedly/node-bestzip.git"
23
- },
24
- "homepage": "https://github.com/nfriedly/node-bestzip",
25
- "files": [
26
- "bin/cli.js",
27
- "lib/"
28
- ],
29
- "dependencies": {
30
- "archiver": "^7.0.1",
31
- "glob": "^13.0.6",
32
- "which": "^6.0.1",
33
- "yargs": "^16.2.0"
34
- },
35
- "devDependencies": {
36
- "chai": "^4.3.4",
37
- "command-line-test": "^1.0.10",
38
- "eslint": "^8.57.1",
39
- "eslint-config-prettier": "^8.1.0",
40
- "eslint-plugin-prettier": "^3.3.1",
41
- "jest": "^29.7.0",
42
- "klaw-sync": "^6.0.0",
43
- "prettier": "^2.2.1",
44
- "regenerator-runtime": "^0.13.7",
45
- "rimraf": "^3.0.2",
46
- "unzip-stream": "^0.3.1"
47
- }
48
- }
1
+ {
2
+ "name": "bestzip",
3
+ "version": "2.2.6",
4
+ "description": "Uses OS zip command if available (for better performance and speed) or node.js version if there is no system command available. Can be called via node or command line.",
5
+ "main": "lib/bestzip.js",
6
+ "bin": {
7
+ "bestzip": "bin/cli.js"
8
+ },
9
+ "engines": {
10
+ "node": ">=20"
11
+ },
12
+ "scripts": {
13
+ "lint": "eslint .",
14
+ "lint-fix": "eslint --fix .",
15
+ "unit-test": "jest",
16
+ "test": "npm run lint && npm run unit-test"
17
+ },
18
+ "author": "Nathan Friedly - http://nfriedly.com/",
19
+ "license": "MIT",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+ssh://git@github.com/nfriedly/node-bestzip.git"
23
+ },
24
+ "homepage": "https://github.com/nfriedly/node-bestzip",
25
+ "files": [
26
+ "bin/cli.js",
27
+ "lib/"
28
+ ],
29
+ "dependencies": {
30
+ "archiver": "^7.0.1",
31
+ "glob": "^13.0.6",
32
+ "which": "^6.0.1",
33
+ "yargs": "^16.2.0"
34
+ },
35
+ "devDependencies": {
36
+ "chai": "^4.3.4",
37
+ "command-line-test": "^1.0.10",
38
+ "eslint": "^8.57.1",
39
+ "eslint-config-prettier": "^8.1.0",
40
+ "eslint-plugin-prettier": "^3.3.1",
41
+ "jest": "^29.7.0",
42
+ "klaw-sync": "^6.0.0",
43
+ "prettier": "^2.2.1",
44
+ "rimraf": "^3.0.2",
45
+ "unzip-stream": "^0.3.1"
46
+ }
47
+ }
package/readme.md CHANGED
@@ -1,92 +1,92 @@
1
- # bestzip
2
-
3
- [![tests](https://github.com/nfriedly/node-bestzip/actions/workflows/ci.yml/badge.svg)](https://github.com/nfriedly/node-bestzip/actions/workflows/ci.yml)
4
- [![npm version](https://badge.fury.io/js/bestzip.svg)](https://www.npmjs.com/package/bestzip)
5
- [![npm downloads](https://img.shields.io/npm/dm/bestzip)](https://www.npmjs.com/package/bestzip)
6
-
7
- This module provides a `bestzip` command that calls the native `zip` command if available and otherwise falls back to a
8
- Node.js implementation.
9
-
10
- The `--recurse-directories` (`-r`) option is automatically enabled.
11
-
12
- ## Why?
13
-
14
- The native `zip` command on GNU/Linux and macOS is significantly faster and creates moderately smaller .zip files than the Node.js version included here, but Windows has no built-in `zip` command. This module provides the best of both worlds, and allows for easier cross-platform scripting.
15
-
16
- ## Global command line usage
17
-
18
- npm install -g bestzip
19
- bestzip destination.zip source/ [other sources...]
20
-
21
- ## Command line usage within `package.json` scripts
22
-
23
- npm install --save-dev bestzip
24
-
25
- package.json:
26
-
27
- ```javascript
28
- {
29
- //...
30
- "scripts": {
31
- "build" "...",
32
- "zip": "bestzip bundle.zip build/*",
33
- "upload": "....",
34
- "deploy": "npm run build && npm run zip && npm run upload"
35
- }
36
- }
37
- ```
38
-
39
- ## Programmatic usage from within Node.js
40
-
41
- ```javascript
42
- var zip = require('bestzip');
43
-
44
- zip({
45
- source: 'build/*',
46
- destination: './destination.zip'
47
- }).then(function() {
48
- console.log('all done!');
49
- }).catch(function(err) {
50
- console.error(err.stack);
51
- process.exit(1);
52
- });
53
-
54
- // v1.x API also works for backwards compatibility: zip(destination, sources, callback)
55
- ```
56
-
57
- ### Options
58
-
59
- * `source`: Path or paths to files and folders to include in the zip file. String or Array of Strings.
60
- * `destination`: Path to generated .zip file.
61
- * `cwd`: Set the Current Working Directory that source and destination paths are relative to. Defaults to `process.cwd()`
62
- * `level`: Set the level of compression. (Number 0-9, with 0 being no compression and 9 being the most compressed.)
63
-
64
- ## How to control the directory structure
65
-
66
- The directory structure in the .zip is going to match your input files, but the exact details depend on how the command is called. For example:
67
-
68
- `bestzip build.zip build/*`
69
-
70
- This includes the build/ folder inside of the .zip
71
-
72
- Alternatively:
73
-
74
- `cd build/ && bestzip ../build.zip *`
75
-
76
- This will not include the build/ folder, it's contents will be top-level.
77
-
78
- *Note: some tools, including the Archive Utility built into macOS, will automatically create a top-level folder to group everything together when extracting a .zip archive that contains multiple top-level files.*
79
-
80
- When using the programmatic API, the same effect may be achieved by passing in the `cwd` option.
81
-
82
- ## .dotfiles
83
-
84
- Wildcards (`*`) ignore dotfiles.
85
-
86
- * To include a dotfile, either include the directory it's in (`folder/`) or include it by name (`folder/.dotfile`)
87
- * To omit dotfiles, either use a wildcard (`folder/*`) or explicitly list the desired files (`folder/file1.txt folder/file2.txt`)
88
-
89
- ## Breaking changes for v2
90
-
91
- * `bestzip output.zip foo/bar/file.txt` now includes the foo/bar/ folders, previously it would place file.txt at the top-level
92
- * This was done to more closely align with the native zip command
1
+ # bestzip
2
+
3
+ [![tests](https://github.com/nfriedly/node-bestzip/actions/workflows/ci.yml/badge.svg)](https://github.com/nfriedly/node-bestzip/actions/workflows/ci.yml)
4
+ [![npm version](https://badge.fury.io/js/bestzip.svg)](https://www.npmjs.com/package/bestzip)
5
+ [![npm downloads](https://img.shields.io/npm/dm/bestzip)](https://www.npmjs.com/package/bestzip)
6
+
7
+ This module provides a `bestzip` command that calls the native `zip` command if available and otherwise falls back to a
8
+ Node.js implementation.
9
+
10
+ The `--recurse-directories` (`-r`) option is automatically enabled.
11
+
12
+ ## Why?
13
+
14
+ The native `zip` command on GNU/Linux and macOS is significantly faster and creates moderately smaller .zip files than the Node.js version included here, but Windows has no built-in `zip` command. This module provides the best of both worlds, and allows for easier cross-platform scripting.
15
+
16
+ ## Global command line usage
17
+
18
+ npm install -g bestzip
19
+ bestzip destination.zip source/ [other sources...]
20
+
21
+ ## Command line usage within `package.json` scripts
22
+
23
+ npm install --save-dev bestzip
24
+
25
+ package.json:
26
+
27
+ ```javascript
28
+ {
29
+ //...
30
+ "scripts": {
31
+ "build" "...",
32
+ "zip": "bestzip bundle.zip build/*",
33
+ "upload": "....",
34
+ "deploy": "npm run build && npm run zip && npm run upload"
35
+ }
36
+ }
37
+ ```
38
+
39
+ ## Programmatic usage from within Node.js
40
+
41
+ ```javascript
42
+ var zip = require('bestzip');
43
+
44
+ zip({
45
+ source: 'build/*',
46
+ destination: './destination.zip'
47
+ }).then(function() {
48
+ console.log('all done!');
49
+ }).catch(function(err) {
50
+ console.error(err.stack);
51
+ process.exit(1);
52
+ });
53
+
54
+ // v1.x API also works for backwards compatibility: zip(destination, sources, callback)
55
+ ```
56
+
57
+ ### Options
58
+
59
+ * `source`: Path or paths to files and folders to include in the zip file. String or Array of Strings.
60
+ * `destination`: Path to generated .zip file.
61
+ * `cwd`: Set the Current Working Directory that source and destination paths are relative to. Defaults to `process.cwd()`
62
+ * `level`: Set the level of compression. (Number 0-9, with 0 being no compression and 9 being the most compressed.)
63
+
64
+ ## How to control the directory structure
65
+
66
+ The directory structure in the .zip is going to match your input files, but the exact details depend on how the command is called. For example:
67
+
68
+ `bestzip build.zip build/*`
69
+
70
+ This includes the build/ folder inside of the .zip
71
+
72
+ Alternatively:
73
+
74
+ `cd build/ && bestzip ../build.zip *`
75
+
76
+ This will not include the build/ folder, it's contents will be top-level.
77
+
78
+ *Note: some tools, including the Archive Utility built into macOS, will automatically create a top-level folder to group everything together when extracting a .zip archive that contains multiple top-level files.*
79
+
80
+ When using the programmatic API, the same effect may be achieved by passing in the `cwd` option.
81
+
82
+ ## .dotfiles
83
+
84
+ Wildcards (`*`) ignore dotfiles.
85
+
86
+ * To include a dotfile, either include the directory it's in (`folder/`) or include it by name (`folder/.dotfile`)
87
+ * To omit dotfiles, either use a wildcard (`folder/*`) or explicitly list the desired files (`folder/file1.txt folder/file2.txt`)
88
+
89
+ ## Breaking changes for v2
90
+
91
+ * `bestzip output.zip foo/bar/file.txt` now includes the foo/bar/ folders, previously it would place file.txt at the top-level
92
+ * This was done to more closely align with the native zip command