bestzip 3.1.0 → 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
@@ -15,12 +15,16 @@ The native `zip` command on GNU/Linux and macOS is significantly faster and crea
15
15
 
16
16
  ## Global command line usage
17
17
 
18
- npm install -g bestzip
19
- bestzip --no-follow-sym-links destination.zip source/ [other sources...]
18
+ ```bash
19
+ npm install -g bestzip
20
+ bestzip --no-follow-sym-links destination.zip source/ [other sources...]
21
+ ```
20
22
 
21
23
  ## Command line usage within `package.json` scripts
22
24
 
23
- npm install --save-dev bestzip
25
+ ```bash
26
+ npm install --save-dev bestzip
27
+ ```
24
28
 
25
29
  package.json:
26
30
 
@@ -38,7 +42,7 @@ package.json:
38
42
 
39
43
  ## Command line options
40
44
 
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.
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.
42
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.
43
47
  * `--force node|native`: Force the Node.js implementation or the native `zip` command instead of letting bestzip pick automatically.
44
48
 
@@ -46,18 +50,18 @@ package.json:
46
50
  ## Programmatic usage from within Node.js
47
51
 
48
52
  ```javascript
49
- import { zip } from 'bestzip';
50
- // const { zip } = require('bestzip'); // for CJS (requires node.js v22 or newer
53
+ import { bestZip } from 'bestzip';
54
+ // const { bestZip } = require('bestzip'); // for CJS (requires node.js v22 or newer
51
55
 
52
56
  // zip a single source
53
- await zip({
57
+ await bestZip({
54
58
  source: 'build/*',
55
59
  destination: './destination.zip',
56
60
  followSymLinks: false,
57
61
  })
58
62
 
59
63
  // zip multiple sources, starting in a different CWD (current working directory)
60
- await zip({
64
+ await bestZip({
61
65
  source: ['img1.jpg', 'img2.jpg', 'imgn.jpg'],
62
66
  destination: '../images.zip',
63
67
  cwd: './images/', // optional, defaults to process.cwd()
@@ -74,17 +78,7 @@ await zip({
74
78
  * `destination`: Path to generated .zip file.
75
79
  * `cwd`: Set the Current Working Directory that source and destination paths are relative to. Defaults to `process.cwd()`
76
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.
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.
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)).
88
82
 
89
83
  ## How to control the directory structure
90
84
 
@@ -111,3 +105,13 @@ Wildcards (`*`) ignore dotfiles.
111
105
  * To include a dotfile, either include the directory it's in (`folder/`) or include it by name (`folder/.dotfile`)
112
106
  * To omit dotfiles, either use a wildcard (`folder/*`) or explicitly list the desired files (`folder/file1.txt folder/file2.txt`)
113
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/lib/bestzip.js CHANGED
@@ -151,11 +151,9 @@ function maybeWarnAboutSymlinks(options, symlinks, cwd) {
151
151
  lines.push(`...and ${symlinks.length - 3} more`);
152
152
  }
153
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" +
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` +
159
157
  "Detected symlinks:\n" +
160
158
  lines.join("\n")
161
159
  );
@@ -167,9 +165,9 @@ const nativeZip = async (options) => {
167
165
  const sources = await expandSources(cwd, options.source);
168
166
  const destination = path.resolve(cwd, options.destination);
169
167
  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;
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;
173
171
 
174
172
  if (!followSymLinks && !nativeZipSupportsSymlinks()) {
175
173
  // The native zip command cannot store symlinks as links on this platform
@@ -237,9 +235,10 @@ const nativeZip = async (options) => {
237
235
  const nodeZip = async (options) => {
238
236
  const cwd = options.cwd || process.cwd();
239
237
  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;
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";
243
242
  const symlinks = [];
244
243
  const outputFile = await fsp.open(
245
244
  path.resolve(cwd, options.destination),
@@ -270,49 +269,29 @@ const nodeZip = async (options) => {
270
269
  const fullPath = path.resolve(cwd, source);
271
270
  const destPath = source;
272
271
 
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);
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);
299
277
  for (const entry of entries) {
300
278
  const archiveName = destPath + entry.path.substring(fullPath.length);
301
- archive.file(entry.path, {
302
- name: archiveName,
303
- stats: entry.stats,
304
- });
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()) {
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) {
314
283
  symlinks.push(entry.path);
315
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,
294
+ });
316
295
  }
317
296
  }
318
297
  }
@@ -338,13 +317,14 @@ function zip(options) {
338
317
  };
339
318
  }
340
319
 
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.
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.
345
325
  const useNative =
346
326
  hasNativeZip() &&
347
- (options.followSymLinks !== false || nativeZipSupportsSymlinks());
327
+ (options.followSymLinks === true || nativeZipSupportsSymlinks());
348
328
 
349
329
  let promise;
350
330
  if (useNative) {
@@ -362,4 +342,11 @@ function zip(options) {
362
342
 
363
343
  export default zip;
364
344
 
365
- export { zip, nodeZip, nativeZip, hasNativeZip, nativeZipSupportsSymlinks };
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.1.0",
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",