bestzip 3.0.3 → 3.1.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/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,79 @@ 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 followed by default — their target contents are included in the archive.\n" +
155
+ `To keep this behavior and prevent this warning, ${optIn}.\n` +
156
+ `To store symlinks as links instead, ${optOut}.\n` +
157
+ "This default will change in v4 to store symlinks as links. " +
158
+ "Set followSymLinks explicitly to opt in to following.\n" +
159
+ "Detected symlinks:\n" +
160
+ lines.join("\n")
161
+ );
59
162
  }
60
163
 
61
164
  const nativeZip = async (options) => {
@@ -63,20 +166,49 @@ const nativeZip = async (options) => {
63
166
  const command = "zip";
64
167
  const sources = await expandSources(cwd, options.source);
65
168
  const destination = path.resolve(cwd, options.destination);
169
+ validateLevel(options.level);
170
+ // followSymLinks: false opts into storing symlinks as links; the default
171
+ // (unset or true) follows symlinks and is unchanged.
172
+ const followSymLinks = options.followSymLinks !== false;
66
173
 
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());
174
+ if (!followSymLinks && !nativeZipSupportsSymlinks()) {
175
+ // The native zip command cannot store symlinks as links on this platform
176
+ // (e.g. the Windows build of Info-ZIP). nodeZip can, so the bestzip()
177
+ // entry point routes accordingly — but a direct nativeZip() call can't
178
+ // fulfill this request.
179
+ throw new Error(
180
+ "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."
181
+ );
182
+ }
183
+
184
+ const args = ["--quiet", "--recurse-paths"];
185
+ if (typeof options.level === "number") {
186
+ args.push("-" + options.level.toString());
77
187
  }
188
+ if (!followSymLinks) {
189
+ args.push("--symlinks");
190
+ }
191
+ args.push(destination, "--", ...sources);
192
+
193
+ // Scan for symlinks to warn about in parallel with the zip command. The
194
+ // scan is best-effort: if it fails (e.g. it races the zip command touching
195
+ // the same paths), log and fall back to no warning rather than aborting the
196
+ // zip, and never let it reject before the zip process has completed.
197
+ const warnScan = (async () => {
198
+ if (options.followSymLinks !== undefined) {
199
+ return [];
200
+ }
201
+ try {
202
+ return await detectSymlinks(cwd, sources);
203
+ } catch (err) {
204
+ console.warn(
205
+ `bestzip: failed to scan for symlinks to warn about: ${err.message}`
206
+ );
207
+ return [];
208
+ }
209
+ })();
78
210
 
79
- return new Promise((resolve, reject) => {
211
+ const zipPromise = new Promise((resolve, reject) => {
80
212
  const zipProcess = cp.spawn(command, args, {
81
213
  stdio: "inherit",
82
214
  cwd,
@@ -96,18 +228,34 @@ const nativeZip = async (options) => {
96
228
  }
97
229
  });
98
230
  });
231
+
232
+ const [symlinks] = await Promise.all([warnScan, zipPromise]);
233
+ maybeWarnAboutSymlinks(options, symlinks, cwd);
99
234
  };
100
235
 
101
236
  // based on http://stackoverflow.com/questions/15641243/need-to-zip-an-entire-directory-using-node-js/18775083#18775083
102
237
  const nodeZip = async (options) => {
103
238
  const cwd = options.cwd || process.cwd();
104
- const output = fs.createWriteStream(path.resolve(cwd, options.destination));
239
+ validateLevel(options.level);
240
+ // followSymLinks: false stores symlinks as links; the default (unset or
241
+ // true) follows symlinks, matching the native zip implementation.
242
+ const followSymLinks = options.followSymLinks !== false;
243
+ const symlinks = [];
244
+ const outputFile = await fsp.open(
245
+ path.resolve(cwd, options.destination),
246
+ "w"
247
+ );
248
+ const output = outputFile.createWriteStream();
105
249
  const archive = new ZipArchive({
106
250
  zlib: { level: options.level },
107
251
  });
108
252
 
109
- output.on("close", () => resolvePromise());
253
+ output.on("close", async () => {
254
+ await outputFile.close();
255
+ resolvePromise();
256
+ });
110
257
  archive.on("error", (err) => rejectPromise(err));
258
+ archive.on("warning", (err) => console.warn(err && err.message));
111
259
 
112
260
  archive.pipe(output);
113
261
 
@@ -122,26 +270,57 @@ const nodeZip = async (options) => {
122
270
  const fullPath = path.resolve(cwd, source);
123
271
  const destPath = source;
124
272
 
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,
133
- });
273
+ if (!followSymLinks) {
274
+ // Store symlinks as link entries (their targets, not their contents).
275
+ const entries = await walkTree(fullPath, false);
276
+ for (const entry of entries) {
277
+ const subPath = entry.path.substring(fullPath.length);
278
+ if (entry.stats.isSymbolicLink()) {
279
+ symlinks.push(entry.path);
280
+ archive.symlink(
281
+ destPath + subPath,
282
+ await fsp.readlink(entry.path),
283
+ entry.stats.mode
284
+ );
285
+ } else {
286
+ archive.file(entry.path, {
287
+ name: destPath + subPath,
288
+ stats: entry.stats,
289
+ });
290
+ }
291
+ }
292
+ return;
293
+ }
294
+
295
+ // Follow symlinks by default. Pass explicit (stat) stats so archiver
296
+ // dereferences symlinks and stores their target contents rather than the
297
+ // link itself, matching the native zip implementation.
298
+ const entries = await walkTree(fullPath, true);
299
+ for (const entry of entries) {
300
+ const archiveName = destPath + entry.path.substring(fullPath.length);
301
+ archive.file(entry.path, {
302
+ name: archiveName,
303
+ stats: entry.stats,
134
304
  });
135
- } else if (stats.isFile()) {
136
- archive.file(fullPath, { stats: stats, name: destPath });
305
+ }
306
+
307
+ // Warn while following by default (followSymLinks unset): detect symlinks
308
+ // via an lstat walk so the deprecation warning still fires even though the
309
+ // archive stores their target contents.
310
+ if (options.followSymLinks === undefined) {
311
+ const detected = await walkTree(fullPath, false);
312
+ for (const entry of detected) {
313
+ if (entry.stats.isSymbolicLink()) {
314
+ symlinks.push(entry.path);
315
+ }
316
+ }
137
317
  }
138
318
  }
139
319
 
140
320
  try {
141
321
  const expandedSources = await expandSources(cwd, options.source);
142
- for (const source of expandedSources) {
143
- await addSource(source);
144
- }
322
+ await Promise.all(expandedSources.map(addSource));
323
+ maybeWarnAboutSymlinks(options, symlinks, cwd);
145
324
  archive.finalize();
146
325
  } catch (err) {
147
326
  rejectPromise(err);
@@ -159,8 +338,16 @@ function zip(options) {
159
338
  };
160
339
  }
161
340
 
341
+ // The native zip command can store symlinks as links only when it supports
342
+ // --symlinks. If followSymLinks is not explicitly false, it just follows
343
+ // symlinks, which every native zip can do. When storing links is requested
344
+ // but the native zip can't do it, fall back to the node implementation.
345
+ const useNative =
346
+ hasNativeZip() &&
347
+ (options.followSymLinks !== false || nativeZipSupportsSymlinks());
348
+
162
349
  let promise;
163
- if (hasNativeZip()) {
350
+ if (useNative) {
164
351
  promise = nativeZip(options);
165
352
  } else {
166
353
  promise = nodeZip(options);
@@ -175,4 +362,4 @@ function zip(options) {
175
362
 
176
363
  export default zip;
177
364
 
178
- export { zip, nodeZip, nativeZip, hasNativeZip };
365
+ export { zip, nodeZip, nativeZip, hasNativeZip, nativeZipSupportsSymlinks };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bestzip",
3
- "version": "3.0.3",
3
+ "version": "3.1.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 CHANGED
@@ -16,7 +16,7 @@ The native `zip` command on GNU/Linux and macOS is significantly faster and crea
16
16
  ## Global command line usage
17
17
 
18
18
  npm install -g bestzip
19
- bestzip destination.zip source/ [other sources...]
19
+ bestzip --no-follow-sym-links destination.zip source/ [other sources...]
20
20
 
21
21
  ## Command line usage within `package.json` scripts
22
22
 
@@ -28,42 +28,63 @@ package.json:
28
28
  {
29
29
  //...
30
30
  "scripts": {
31
- "build" "...",
32
- "zip": "bestzip bundle.zip build/*",
31
+ "build": "...",
32
+ "zip": "bestzip --no-follow-sym-links bundle.zip build/*",
33
33
  "upload": "....",
34
34
  "deploy": "npm run build && npm run zip && npm run upload"
35
35
  }
36
36
  }
37
37
  ```
38
38
 
39
+ ## Command line options
40
+
41
+ * `--follow-sym-links` / `--no-follow-sym-links`: Follow symbolic links and include their target contents in the archive (the default) or don't follow and instead include the link itself. Setting one flag or the other is recommended because the default will change in the next major version (v4.0.0). If symlinks are encountered when the flag is not set, a warning will be logged.
42
+ * `--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.
43
+ * `--force node|native`: Force the Node.js implementation or the native `zip` command instead of letting bestzip pick automatically.
44
+
45
+
39
46
  ## Programmatic usage from within Node.js
40
47
 
41
48
  ```javascript
42
- import zip from 'bestzip';
43
- // use version 2.x for require()
49
+ import { zip } from 'bestzip';
50
+ // const { zip } = require('bestzip'); // for CJS (requires node.js v22 or newer
44
51
 
45
52
  // zip a single source
46
53
  await zip({
47
54
  source: 'build/*',
48
- destination: './destination.zip'
55
+ destination: './destination.zip',
56
+ followSymLinks: false,
49
57
  })
50
58
 
51
59
  // zip multiple sources, starting in a different CWD (current working directory)
52
60
  await zip({
53
61
  source: ['img1.jpg', 'img2.jpg', 'imgn.jpg'],
54
62
  destination: '../images.zip',
55
- cwd: './images/' // optional, defaults to process.cwd()
63
+ cwd: './images/', // optional, defaults to process.cwd()
64
+ followSymLinks: false,
56
65
  })
57
66
 
58
67
  // Promises also work: zip({source, destination}).then(...).catch(...)
59
68
  // Callbacks also work: zip(destination, sources, callback)
60
69
  ```
61
70
 
62
- ### Options
71
+ ### API Options
63
72
 
64
73
  * `source`: Path or paths to files and folders to include in the zip file. String or Array of Strings.
65
74
  * `destination`: Path to generated .zip file.
66
75
  * `cwd`: Set the Current Working Directory that source and destination paths are relative to. Defaults to `process.cwd()`
76
+ * `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.
77
+ * `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 followed (the current default) and a warning is printed whenever symlinks are detected, because this default will change in v4 to store symlinks as links instead (see [Symbolic links](#symbolic-links)).
78
+
79
+ ## Symbolic links
80
+
81
+ By default, bestzip **follows** symbolic links — their target contents are included in the archive. 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 or out.
82
+
83
+ **This default will change in v4** to store symlinks as link entries (not following them), which is the more secure behavior. To prepare for this, set `followSymLinks` explicitly in your code.
84
+
85
+ To follow symlinks (the current default), set `followSymLinks: true` (programmatic API) or pass `--follow-sym-links` on the command line. To suppress the warning while keeping the current default, set `followSymLinks: true` explicitly. To store symlinks as links instead, set `followSymLinks: false` or pass `--no-follow-sym-links` on the command line.
86
+
87
+ When storing symlinks as links, 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. Note that calling `bestzip.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 `bestzip.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.
67
88
 
68
89
  ## How to control the directory structure
69
90
 
@@ -90,11 +111,3 @@ Wildcards (`*`) ignore dotfiles.
90
111
  * To include a dotfile, either include the directory it's in (`folder/`) or include it by name (`folder/.dotfile`)
91
112
  * To omit dotfiles, either use a wildcard (`folder/*`) or explicitly list the desired files (`folder/file1.txt folder/file2.txt`)
92
113
 
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