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 +1 -1
- package/{readme.md → README.md} +23 -19
- package/lib/bestzip.js +43 -56
- package/package.json +1 -1
package/LICENSE
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
MIT License
|
|
2
2
|
|
|
3
|
-
Copyright (c)
|
|
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 → README.md}
RENAMED
|
@@ -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
|
-
|
|
19
|
-
|
|
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
|
-
|
|
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
|
|
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 {
|
|
50
|
-
// const {
|
|
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
|
|
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
|
|
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
|
|
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
|
|
155
|
-
`To keep
|
|
156
|
-
`To
|
|
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:
|
|
171
|
-
// (unset or
|
|
172
|
-
const followSymLinks = options.followSymLinks
|
|
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:
|
|
241
|
-
//
|
|
242
|
-
const followSymLinks = options.followSymLinks
|
|
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
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
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
|
-
|
|
302
|
-
|
|
303
|
-
|
|
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
|
-
//
|
|
342
|
-
//
|
|
343
|
-
//
|
|
344
|
-
// but the native zip can't do it, fall back to the node
|
|
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
|
|
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 {
|
|
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
|
+
"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",
|