bestzip 3.0.3 → 4.0.0

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.
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2018 Nathan Friedly - http://nfriedly.com/
3
+ Copyright (c) 2026 Nathan Friedly - http://nfriedly.com/
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md ADDED
@@ -0,0 +1,117 @@
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
+ ```bash
19
+ npm install -g bestzip
20
+ bestzip --no-follow-sym-links destination.zip source/ [other sources...]
21
+ ```
22
+
23
+ ## Command line usage within `package.json` scripts
24
+
25
+ ```bash
26
+ npm install --save-dev bestzip
27
+ ```
28
+
29
+ package.json:
30
+
31
+ ```javascript
32
+ {
33
+ //...
34
+ "scripts": {
35
+ "build": "...",
36
+ "zip": "bestzip --no-follow-sym-links bundle.zip build/*",
37
+ "upload": "....",
38
+ "deploy": "npm run build && npm run zip && npm run upload"
39
+ }
40
+ }
41
+ ```
42
+
43
+ ## Command line options
44
+
45
+ * `--follow-sym-links` / `--no-follow-sym-links`: Follow symbolic links and include their target contents in the archive, or don't follow and instead include the link itself (the default). If symlinks are encountered when the flag is not set, a warning will be logged.
46
+ * `--level N` / `-N`: Level of compression, as with the native `zip` command. `N` must be an integer from 0 (store, no compression) to 9 (maximum compression). Defaults to each implementation's own default when unset.
47
+ * `--force node|native`: Force the Node.js implementation or the native `zip` command instead of letting bestzip pick automatically.
48
+
49
+
50
+ ## Programmatic usage from within Node.js
51
+
52
+ ```javascript
53
+ import { bestZip } from 'bestzip';
54
+ // const { bestZip } = require('bestzip'); // for CJS (requires node.js v22 or newer
55
+
56
+ // zip a single source
57
+ await bestZip({
58
+ source: 'build/*',
59
+ destination: './destination.zip',
60
+ followSymLinks: false,
61
+ })
62
+
63
+ // zip multiple sources, starting in a different CWD (current working directory)
64
+ await bestZip({
65
+ source: ['img1.jpg', 'img2.jpg', 'imgn.jpg'],
66
+ destination: '../images.zip',
67
+ cwd: './images/', // optional, defaults to process.cwd()
68
+ followSymLinks: false,
69
+ })
70
+
71
+ // Promises also work: zip({source, destination}).then(...).catch(...)
72
+ // Callbacks also work: zip(destination, sources, callback)
73
+ ```
74
+
75
+ ### API Options
76
+
77
+ * `source`: Path or paths to files and folders to include in the zip file. String or Array of Strings.
78
+ * `destination`: Path to generated .zip file.
79
+ * `cwd`: Set the Current Working Directory that source and destination paths are relative to. Defaults to `process.cwd()`
80
+ * `level`: Level of compression, as with the native `zip` command. An integer from 0 (store, no compression) to 9 (maximum compression). Defaults to each implementation's own default when unset.
81
+ * `followSymLinks`: Follow symbolic links and include the contents of their targets in the zip file. When set to `true` or `false` the preference is honored and no warning is printed. When left unset, symbolic links are **not** followed and a warning is printed whenever symlinks are detected (see [Symbolic links](#symbolic-links)).
82
+
83
+ ## How to control the directory structure
84
+
85
+ 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:
86
+
87
+ `bestzip build.zip build/*`
88
+
89
+ This includes the build/ folder inside of the .zip
90
+
91
+ Alternatively:
92
+
93
+ `cd build/ && bestzip ../build.zip *`
94
+
95
+ This will not include the build/ folder, it's contents will be top-level.
96
+
97
+ *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.*
98
+
99
+ When using the programmatic API, the same effect may be achieved by passing in the `cwd` option.
100
+
101
+ ## .dotfiles
102
+
103
+ Wildcards (`*`) ignore dotfiles.
104
+
105
+ * To include a dotfile, either include the directory it's in (`folder/`) or include it by name (`folder/.dotfile`)
106
+ * To omit dotfiles, either use a wildcard (`folder/*`) or explicitly list the desired files (`folder/file1.txt folder/file2.txt`)
107
+
108
+ ## Symbolic links
109
+
110
+ Starting in v4, bestzip does **not** follow symbolic links by default. Symlinks are stored in the archive as link entries rather than as the contents of their targets. This prevents an archive from accidentally (or maliciously) capturing files from anywhere else on the filesystem that only happen to be reachable through a symlink inside the directory being archived.
111
+
112
+ When symlinks are present and the `followSymLinks` option has not been set explicitly, bestzip prints a warning to stderr listing the symlinked paths and how to opt in to following them.
113
+
114
+ To follow symlinks, set `followSymLinks: true` (programmatic API) or pass `--follow-sym-links` on the command line. To keep the link entries (the default behavior) while suppressing the warning, set `followSymLinks: false` or pass `--no-follow-sym-links` on the command line.
115
+
116
+ When archiving symlinks without following them, bestzip uses the native `zip` command when available. Some native `zip` builds (notably the Windows build of Info-ZIP) cannot store symlinks as link entries at all, so bestzip falls back to its built-in Node.js implementation in that case.
117
+ Note that calling `nativeZip()` directly with `followSymLinks` unset/false on such a platform throws an error; use the `bestZip()` entry point, which routes to the Node.js implementation automatically. Use `nativeZipSupportsSymlinks()` to check whether the available native `zip` can store symlinks as links; it returns `true`/`false` and caches its result after the first call. `bestzip.hasNativeZip()` checks whether a native `zip` is installed at all.
package/bin/cli.js CHANGED
@@ -5,7 +5,13 @@ import * as bestzip from "../lib/bestzip.js";
5
5
  import yargs from "yargs";
6
6
  import { hideBin } from "yargs/helpers";
7
7
 
8
- const argv = yargs(hideBin(process.argv))
8
+ // Rewrite -0 … -9 into --level 0 … --level 9 before yargs parses them
9
+ const preprocessed = hideBin(process.argv).flatMap((arg) => {
10
+ const match = /^-([0-9])$/.exec(arg);
11
+ return match ? ["--level", match[1]] : [arg];
12
+ });
13
+
14
+ const argv = yargs(preprocessed)
9
15
  .usage("\nUsage: bestzip destination.zip sources/")
10
16
  .option("force", {
11
17
  describe: "Force use of node.js or native zip methods",
@@ -14,18 +20,17 @@ const argv = yargs(hideBin(process.argv))
14
20
  .option("level", {
15
21
  describe: "Level of compression",
16
22
  type: "number",
17
- default: -1,
23
+ })
24
+ .option("follow-sym-links", {
25
+ describe:
26
+ "Follow symbolic links and include their target contents in the archive",
27
+ type: "boolean",
18
28
  })
19
29
  .demand(2).argv;
20
30
 
21
31
  const destination = argv._.shift();
22
32
  const source = argv._;
23
33
 
24
- if (argv.level < -1 || argv.level > 9) {
25
- console.error("Invalid compression level, must be >= 0 and <= 9");
26
- process.exit(1);
27
- }
28
-
29
34
  console.log("Writing %s to %s...", source.join(", "), destination);
30
35
 
31
36
  let zip;
@@ -43,6 +48,8 @@ zip({
43
48
  destination,
44
49
  verbose: !!argv.verbose,
45
50
  level: argv.level,
51
+ followSymLinks: argv.followSymLinks,
52
+ viaCli: true,
46
53
  })
47
54
  .then(function () {
48
55
  console.log("zipped!");
package/lib/bestzip.js CHANGED
@@ -1,9 +1,11 @@
1
1
  // creates a zip file using either the native `zip` command if available,
2
2
  // or a node.js zip implementation otherwise.
3
3
 
4
- import cp from "node:child_process";
4
+ import cp, { spawnSync } from "node:child_process";
5
5
  import fs from "node:fs";
6
+ import fsp from "node:fs/promises";
6
7
  import path from "node:path";
8
+ import os from "node:os";
7
9
 
8
10
  import { ZipArchive } from "archiver";
9
11
  import { glob, hasMagic } from "glob";
@@ -13,6 +15,44 @@ function hasNativeZip() {
13
15
  return Boolean(which.sync("zip", { nothrow: true }));
14
16
  }
15
17
 
18
+ let nativeSymlinkCapability;
19
+
20
+ // The native zip command needs the --symlinks flag to store symlinks as links
21
+ // rather than following them. Not every build supports it (notably the
22
+ // Windows build of Info-ZIP). This probes the installed zip for support, since
23
+ // the version string isn't a reliable indicator.
24
+ function nativeZipSupportsSymlinks() {
25
+ if (nativeSymlinkCapability !== undefined) {
26
+ return nativeSymlinkCapability;
27
+ }
28
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bestzip-symlink-check"));
29
+ try {
30
+ const file = path.join(dir, "file");
31
+ const link = path.join(dir, "link");
32
+ fs.writeFileSync(file, "bestzip symlink check");
33
+ try {
34
+ fs.symlinkSync("file", link);
35
+ } catch (e) {
36
+ nativeSymlinkCapability = false;
37
+ return nativeSymlinkCapability;
38
+ }
39
+ const res = spawnSync(
40
+ "zip",
41
+ ["-q", "--symlinks", "check.zip", "file", "link"],
42
+ {
43
+ cwd: dir,
44
+ encoding: "utf8",
45
+ }
46
+ );
47
+ nativeSymlinkCapability = res.status === 0;
48
+ } catch (e) {
49
+ nativeSymlinkCapability = false;
50
+ } finally {
51
+ fs.rmSync(dir, { recursive: true, force: true });
52
+ }
53
+ return nativeSymlinkCapability;
54
+ }
55
+
16
56
  async function expandSources(cwd, source) {
17
57
  // options to behave more like the native zip's glob support
18
58
  const globOpts = {
@@ -46,16 +86,77 @@ async function expandSources(cwd, source) {
46
86
  }
47
87
  }
48
88
 
49
- function walkDir(fullPath) {
50
- const files = fs.readdirSync(fullPath).map((f) => {
51
- const filePath = path.join(fullPath, f);
52
- const stats = fs.statSync(filePath);
53
- if (stats.isDirectory()) {
54
- return walkDir(filePath);
55
- }
56
- return filePath;
57
- });
58
- return files.reduce((acc, cur) => acc.concat(cur), []);
89
+ async function walkTree(fullPath, followSymLinks) {
90
+ let stats;
91
+ if (followSymLinks) {
92
+ stats = await fsp.stat(fullPath);
93
+ } else {
94
+ stats = await fsp.lstat(fullPath);
95
+ }
96
+ if (stats.isSymbolicLink() || !stats.isDirectory()) {
97
+ return [{ path: fullPath, stats }];
98
+ }
99
+ const entries = await fsp.readdir(fullPath);
100
+ const children = await Promise.all(
101
+ entries.map((entry) => walkTree(path.join(fullPath, entry), followSymLinks))
102
+ );
103
+ return children.flat();
104
+ }
105
+
106
+ // Validates the compression level. A level of exactly 0-9 (an integer) is
107
+ // accepted; anything else that is set causes an error. An unset level is
108
+ // allowed and left to each implementation's default.
109
+ function validateLevel(level) {
110
+ if (typeof level === "undefined") {
111
+ return;
112
+ }
113
+ if (
114
+ typeof level !== "number" ||
115
+ !Number.isInteger(level) ||
116
+ level < 0 ||
117
+ level > 9
118
+ ) {
119
+ const typehint = typeof level === "number" ? "" : ` (${typeof level})`;
120
+ throw new Error(
121
+ `bestzip: level should be an integer from 0 to 9, got ${level}${typehint}`
122
+ );
123
+ }
124
+ }
125
+
126
+ async function detectSymlinks(cwd, sources) {
127
+ const results = await Promise.all(
128
+ sources.map(async (source) => {
129
+ const fullPath = path.resolve(cwd, source);
130
+ const entries = await walkTree(fullPath, false);
131
+ return entries
132
+ .filter((entry) => entry.stats.isSymbolicLink())
133
+ .map((entry) => entry.path);
134
+ })
135
+ );
136
+ return results.flat();
137
+ }
138
+
139
+ function maybeWarnAboutSymlinks(options, symlinks, cwd) {
140
+ if (options.followSymLinks !== undefined || symlinks.length === 0) {
141
+ return;
142
+ }
143
+ const cli = options.viaCli;
144
+ const optIn = cli ? "pass --follow-sym-links" : "set followSymLinks: true";
145
+ const optOut = cli
146
+ ? "pass --no-follow-sym-links"
147
+ : "set followSymLinks: false";
148
+ let lines = symlinks.map((p) => path.relative(cwd, p));
149
+ if (lines.length > 4) {
150
+ lines = lines.slice(0, 3);
151
+ lines.push(`...and ${symlinks.length - 3} more`);
152
+ }
153
+ console.warn(
154
+ "Warning: Symbolic links are stored as the link itself rather than the destination by default.\n" +
155
+ `To keep the default behavior and prevent this warning, ${optOut}.\n` +
156
+ `To follow symlinks and include their target contents, ${optIn}.\n` +
157
+ "Detected symlinks:\n" +
158
+ lines.join("\n")
159
+ );
59
160
  }
60
161
 
61
162
  const nativeZip = async (options) => {
@@ -63,20 +164,49 @@ const nativeZip = async (options) => {
63
164
  const command = "zip";
64
165
  const sources = await expandSources(cwd, options.source);
65
166
  const destination = path.resolve(cwd, options.destination);
167
+ validateLevel(options.level);
168
+ // followSymLinks: true opts into following symlinks (archiving their target
169
+ // contents); the default (unset or false) stores symlinks as links.
170
+ const followSymLinks = options.followSymLinks === true;
66
171
 
67
- const args = ["--quiet", "--recurse-paths", destination, "--"].concat(
68
- sources
69
- );
70
- if (
71
- typeof options.level == "number" &&
72
- !isNaN(options.level) &&
73
- options.level >= 0 &&
74
- options.level <= 9
75
- ) {
76
- args.splice(0, 0, "-" + options.level.toString());
172
+ if (!followSymLinks && !nativeZipSupportsSymlinks()) {
173
+ // The native zip command cannot store symlinks as links on this platform
174
+ // (e.g. the Windows build of Info-ZIP). nodeZip can, so the bestzip()
175
+ // entry point routes accordingly — but a direct nativeZip() call can't
176
+ // fulfill this request.
177
+ throw new Error(
178
+ "The native zip command on this platform cannot store symlinks as links. Use the bestzip() entry point, which will select the node implementation, or set followSymLinks to true to follow symlinks instead."
179
+ );
180
+ }
181
+
182
+ const args = ["--quiet", "--recurse-paths"];
183
+ if (typeof options.level === "number") {
184
+ args.push("-" + options.level.toString());
185
+ }
186
+ if (!followSymLinks) {
187
+ args.push("--symlinks");
77
188
  }
189
+ args.push(destination, "--", ...sources);
78
190
 
79
- return new Promise((resolve, reject) => {
191
+ // Scan for symlinks to warn about in parallel with the zip command. The
192
+ // scan is best-effort: if it fails (e.g. it races the zip command touching
193
+ // the same paths), log and fall back to no warning rather than aborting the
194
+ // zip, and never let it reject before the zip process has completed.
195
+ const warnScan = (async () => {
196
+ if (options.followSymLinks !== undefined) {
197
+ return [];
198
+ }
199
+ try {
200
+ return await detectSymlinks(cwd, sources);
201
+ } catch (err) {
202
+ console.warn(
203
+ `bestzip: failed to scan for symlinks to warn about: ${err.message}`
204
+ );
205
+ return [];
206
+ }
207
+ })();
208
+
209
+ const zipPromise = new Promise((resolve, reject) => {
80
210
  const zipProcess = cp.spawn(command, args, {
81
211
  stdio: "inherit",
82
212
  cwd,
@@ -96,18 +226,35 @@ const nativeZip = async (options) => {
96
226
  }
97
227
  });
98
228
  });
229
+
230
+ const [symlinks] = await Promise.all([warnScan, zipPromise]);
231
+ maybeWarnAboutSymlinks(options, symlinks, cwd);
99
232
  };
100
233
 
101
234
  // based on http://stackoverflow.com/questions/15641243/need-to-zip-an-entire-directory-using-node-js/18775083#18775083
102
235
  const nodeZip = async (options) => {
103
236
  const cwd = options.cwd || process.cwd();
104
- const output = fs.createWriteStream(path.resolve(cwd, options.destination));
237
+ validateLevel(options.level);
238
+ // followSymLinks: true follows symlinks and archives their target contents;
239
+ // the default (unset or false) stores symlinks as links.
240
+ const followSymLinks = options.followSymLinks === true;
241
+ const trackSymLinks = typeof options.followSymLinks === "undefined";
242
+ const symlinks = [];
243
+ const outputFile = await fsp.open(
244
+ path.resolve(cwd, options.destination),
245
+ "w"
246
+ );
247
+ const output = outputFile.createWriteStream();
105
248
  const archive = new ZipArchive({
106
249
  zlib: { level: options.level },
107
250
  });
108
251
 
109
- output.on("close", () => resolvePromise());
252
+ output.on("close", async () => {
253
+ await outputFile.close();
254
+ resolvePromise();
255
+ });
110
256
  archive.on("error", (err) => rejectPromise(err));
257
+ archive.on("warning", (err) => console.warn(err && err.message));
111
258
 
112
259
  archive.pipe(output);
113
260
 
@@ -122,26 +269,37 @@ const nodeZip = async (options) => {
122
269
  const fullPath = path.resolve(cwd, source);
123
270
  const destPath = source;
124
271
 
125
- const stats = await fs.promises.stat(fullPath);
126
- if (stats.isDirectory()) {
127
- // Walk directory. Works on directories and directory symlinks.
128
- const files = walkDir(fullPath);
129
- files.forEach((f) => {
130
- const subPath = f.substring(fullPath.length);
131
- archive.file(f, {
132
- name: destPath + subPath,
272
+ // Walk the source once in the requested mode: an lstat walk when storing
273
+ // links (symlinks are emitted as their own entries and stored as links),
274
+ // or a stat walk when following (symlinks are dereferenced and their
275
+ // target contents archived, matching the native zip implementation).
276
+ const entries = await walkTree(fullPath, followSymLinks);
277
+ for (const entry of entries) {
278
+ const archiveName = destPath + entry.path.substring(fullPath.length);
279
+ if (entry.stats.isSymbolicLink()) {
280
+ // Storing a link: keep the raw link target and record it for the
281
+ // default warning (an explicit followSymLinks setting suppresses it).
282
+ if (trackSymLinks) {
283
+ symlinks.push(entry.path);
284
+ }
285
+ archive.symlink(
286
+ archiveName,
287
+ await fsp.readlink(entry.path),
288
+ entry.stats.mode
289
+ );
290
+ } else {
291
+ archive.file(entry.path, {
292
+ name: archiveName,
293
+ stats: entry.stats,
133
294
  });
134
- });
135
- } else if (stats.isFile()) {
136
- archive.file(fullPath, { stats: stats, name: destPath });
295
+ }
137
296
  }
138
297
  }
139
298
 
140
299
  try {
141
300
  const expandedSources = await expandSources(cwd, options.source);
142
- for (const source of expandedSources) {
143
- await addSource(source);
144
- }
301
+ await Promise.all(expandedSources.map(addSource));
302
+ maybeWarnAboutSymlinks(options, symlinks, cwd);
145
303
  archive.finalize();
146
304
  } catch (err) {
147
305
  rejectPromise(err);
@@ -159,8 +317,17 @@ function zip(options) {
159
317
  };
160
318
  }
161
319
 
320
+ // By default symlinks are stored as links, not followed. The native zip
321
+ // command can always follow symlinks (followSymLinks: true), but can only
322
+ // store them as links when it supports --symlinks. When storing links is
323
+ // requested but the native zip can't do it, fall back to the node
324
+ // implementation, which can store links regardless.
325
+ const useNative =
326
+ hasNativeZip() &&
327
+ (options.followSymLinks === true || nativeZipSupportsSymlinks());
328
+
162
329
  let promise;
163
- if (hasNativeZip()) {
330
+ if (useNative) {
164
331
  promise = nativeZip(options);
165
332
  } else {
166
333
  promise = nodeZip(options);
@@ -175,4 +342,11 @@ function zip(options) {
175
342
 
176
343
  export default zip;
177
344
 
178
- export { zip, nodeZip, nativeZip, hasNativeZip };
345
+ export {
346
+ zip,
347
+ zip as bestZip,
348
+ nodeZip,
349
+ nativeZip,
350
+ hasNativeZip,
351
+ nativeZipSupportsSymlinks,
352
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bestzip",
3
- "version": "3.0.3",
3
+ "version": "4.0.0",
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
5
  "type": "module",
6
6
  "exports": "./lib/bestzip.js",
package/readme.md DELETED
@@ -1,100 +0,0 @@
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
- import zip from 'bestzip';
43
- // use version 2.x for require()
44
-
45
- // zip a single source
46
- await zip({
47
- source: 'build/*',
48
- destination: './destination.zip'
49
- })
50
-
51
- // zip multiple sources, starting in a different CWD (current working directory)
52
- await zip({
53
- source: ['img1.jpg', 'img2.jpg', 'imgn.jpg'],
54
- destination: '../images.zip',
55
- cwd: './images/' // optional, defaults to process.cwd()
56
- })
57
-
58
- // Promises also work: zip({source, destination}).then(...).catch(...)
59
- // Callbacks also work: zip(destination, sources, callback)
60
- ```
61
-
62
- ### Options
63
-
64
- * `source`: Path or paths to files and folders to include in the zip file. String or Array of Strings.
65
- * `destination`: Path to generated .zip file.
66
- * `cwd`: Set the Current Working Directory that source and destination paths are relative to. Defaults to `process.cwd()`
67
-
68
- ## How to control the directory structure
69
-
70
- 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:
71
-
72
- `bestzip build.zip build/*`
73
-
74
- This includes the build/ folder inside of the .zip
75
-
76
- Alternatively:
77
-
78
- `cd build/ && bestzip ../build.zip *`
79
-
80
- This will not include the build/ folder, it's contents will be top-level.
81
-
82
- *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.*
83
-
84
- When using the programmatic API, the same effect may be achieved by passing in the `cwd` option.
85
-
86
- ## .dotfiles
87
-
88
- Wildcards (`*`) ignore dotfiles.
89
-
90
- * To include a dotfile, either include the directory it's in (`folder/`) or include it by name (`folder/.dotfile`)
91
- * To omit dotfiles, either use a wildcard (`folder/*`) or explicitly list the desired files (`folder/file1.txt folder/file2.txt`)
92
-
93
- ## Breaking changes for v2
94
-
95
- * `bestzip output.zip foo/bar/file.txt` now includes the foo/bar/ folders, previously it would place file.txt at the top-level
96
- * This was done to more closely align with the native zip command
97
-
98
- ## Breaking changes for v3
99
-
100
- * Switched from CJS to ESM