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 +1 -1
- package/README.md +117 -0
- package/bin/cli.js +14 -7
- package/lib/bestzip.js +214 -40
- package/package.json +1 -1
- package/readme.md +0 -100
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
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# bestzip
|
|
2
|
+
|
|
3
|
+
[](https://github.com/nfriedly/node-bestzip/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/bestzip)
|
|
5
|
+
[](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
|
-
|
|
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
|
-
|
|
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
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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", () =>
|
|
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
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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
|
-
|
|
143
|
-
|
|
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 (
|
|
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 {
|
|
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",
|
package/readme.md
DELETED
|
@@ -1,100 +0,0 @@
|
|
|
1
|
-
# bestzip
|
|
2
|
-
|
|
3
|
-
[](https://github.com/nfriedly/node-bestzip/actions/workflows/ci.yml)
|
|
4
|
-
[](https://www.npmjs.com/package/bestzip)
|
|
5
|
-
[](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
|