modern-tar 0.4.1 → 0.4.2

package/README.md

@@ -197,7 +197,7 @@ await pipeline(sourceStream, extractStream);
 #### Archive Creation
 
 ```typescript
-import { packTarSources, type TarSource } from 'modern-tar/fs';
+import { packTar, type TarSource } from 'modern-tar/fs';
 import { createWriteStream } from 'node:fs';
 import { pipeline } from 'node:stream/promises';
 
@@ -209,7 +209,7 @@ const sources: TarSource[] = [
   { type: 'content', content: '#!/bin/bash\necho "Executable"', target: 'bin/script.sh', mode: 0o755 }
 ];
 
-const archiveStream = packTarSources(sources);
+const archiveStream = packTar(sources);
 await pipeline(archiveStream, createWriteStream('project.tar'));
 ```
 

package/dist/fs/index.d.ts

@@ -1,6 +1,6 @@
 import { TarEntryData, TarHeader, UnpackOptions } from "../types-D-xPQp4Z.js";
-import { Stats } from "node:fs";
 import { Readable, Writable } from "node:stream";
+import { Stats } from "node:fs";
 
 //#region src/fs/types.d.ts
 
@@ -19,6 +19,11 @@ interface PackOptionsFS {
   map?: (header: TarHeader) => TarHeader;
   /** Base directory for symlink security validation, when `dereference` is set to true. */
   baseDir?: string;
+  /**
+   * Maximum number of concurrent filesystem operations during packing.
+   * @default os.cpus().length || 8
+   */
+  concurrency?: number;
 }
 /**
  * Filesystem-specific configuration options for extracting tar archives to the filesystem.
@@ -76,34 +81,15 @@ type TarSource = FileSource | DirectorySource | ContentSource;
 //#endregion
 //#region src/fs/pack.d.ts
 /**
- * Packs multiple sources into a tar archive as a Node.js Readable stream from an
- * array of sources (files, directories, or raw content).
- *
- * @param sources - An array of {@link TarSource} objects describing what to include.
- * @param options - Optional packing configuration using {@link PackOptionsFS}.
- * @returns A Node.js [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable)
- * stream that outputs the tar archive bytes.
- *
- * @example
- * ```typescript
- * import { packTarSources, TarSource } from 'modern-tar/fs';
- *
- * const sources: TarSource[] = [
- * { type: 'file', source: './package.json', target: 'project/package.json' },
- * { type: 'directory', source: './src', target: 'project/src' },
- * { type: 'content', content: 'hello world', target: 'project/hello.txt' }
- * ];
- *
- * const archiveStream = packTarSources(sources);
- * await pipeline(archiveStream, createWriteStream('project.tar'));
- * ```
+ * @deprecated Use `packTar` instead. This function is now an alias for `packTar`.
  */
-declare function packTarSources(sources: TarSource[], options?: PackOptionsFS): Readable;
+declare const packTarSources: typeof packTar;
 /**
- * Pack a directory into a Node.js `Readable` stream. This is a convenience
- * wrapper around `packTarSources` that reads the contents of the specified directory.
+ * Pack a directory or multiple sources into a Node.js `Readable` stream containing
+ * tar archive bytes. Can pack either a single directory or an array of sources
+ * (files, directories, or raw content).
  *
- * @param directoryPath - Path to directory to pack.
+ * @param sources - Either a directory path string or an array of {@link TarSource} objects.
  * @param options - Optional packing configuration using {@link PackOptionsFS}.
  * @returns Node.js [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) stream of tar archive bytes
  *
@@ -117,6 +103,15 @@ declare function packTarSources(sources: TarSource[], options?: PackOptionsFS):
  * const tarStream = packTar('/home/user/project');
  * await pipeline(tarStream, createWriteStream('project.tar'));
  *
+ * // Pack multiple sources
+ * const sources = [
+ *   { type: 'file', source: './package.json', target: 'project/package.json' },
+ *   { type: 'directory', source: './src', target: 'project/src' },
+ *   { type: 'content', content: 'hello world', target: 'project/hello.txt' }
+ * ];
+ * const archiveStream = packTar(sources);
+ * await pipeline(archiveStream, createWriteStream('project.tar'));
+ *
  * // With filtering and transformation
  * const filteredStream = packTar('/my/project', {
  *   filter: (path, stats) => !path.includes('node_modules'),
@@ -125,7 +120,7 @@ declare function packTarSources(sources: TarSource[], options?: PackOptionsFS):
  * });
  * ```
  */
-declare function packTar(directoryPath: string, options?: PackOptionsFS): Readable;
+declare function packTar(sources: TarSource[] | string, options?: PackOptionsFS): Readable;
 //#endregion
 //#region src/fs/unpack.d.ts
 /**

package/dist/fs/index.js

@@ -1,149 +1,184 @@
 import { createTarPacker, createTarUnpacker, normalizeBody, transformHeader } from "../unpacker-DBTDVhe4.js";
-import { createReadStream, createWriteStream } from "node:fs";
 import * as fs from "node:fs/promises";
+import { cpus } from "node:os";
 import * as path from "node:path";
 import { PassThrough, Readable, Writable } from "node:stream";
-import { cpus } from "node:os";
+import { createWriteStream } from "node:fs";
 import { pipeline } from "node:stream/promises";
 
 //#region src/fs/pack.ts
-function packTarSources(sources, options = {}) {
-	const { dereference = false, filter, map, baseDir } = options;
+const packTarSources = packTar;
+function packTar(sources, options = {}) {
 	const stream = new Readable({ read() {} });
-	const packer = createTarPacker((chunk) => stream.push(Buffer.from(chunk)), (error) => stream.destroy(error), () => stream.push(null));
 	(async () => {
-		try {
-			const stack = [...sources].reverse();
-			const seenInodes = /* @__PURE__ */ new Map();
-			const getStat = dereference ? fs.stat : fs.lstat;
-			while (stack.length > 0) {
-				const source = stack.pop();
-				const target = source.target.replace(/\\/g, "/");
-				switch (source.type) {
-					case "file": {
-						if (dereference && baseDir && await isSymlinkUnsafe(source.source, baseDir)) break;
-						const stat = await getStat(source.source);
-						if (filter && !filter(source.source, stat)) break;
-						let header = {
-							name: target,
-							size: 0,
-							mode: stat.mode,
-							mtime: stat.mtime,
-							uid: stat.uid,
-							gid: stat.gid,
-							type: "file"
-						};
-						if (stat.isFile()) {
-							header.size = stat.size;
-							if (stat.nlink > 1) {
-								const linkTarget = seenInodes.get(stat.ino);
-								if (linkTarget) {
-									header.type = "link";
-									header.linkname = linkTarget;
-									header.size = 0;
-								} else seenInodes.set(stat.ino, header.name);
-							}
-						} else if (stat.isSymbolicLink()) {
-							header.type = "symlink";
-							header.linkname = await fs.readlink(source.source);
-							header.size = 0;
-						} else break;
-						if (map) header = map(header);
-						packer.add(header);
-						if (header.type === "file" && header.size > 0) for await (const chunk of createReadStream(source.source)) packer.write(chunk);
-						packer.endEntry();
-						break;
-					}
-					case "directory": {
-						if (dereference && baseDir && await isSymlinkUnsafe(source.source, baseDir)) break;
-						const stat = await getStat(source.source);
-						if (filter && !filter(source.source, stat)) break;
-						let header = {
-							name: target.endsWith("/") ? target : `${target}/`,
-							size: 0,
-							mode: stat.mode,
-							mtime: stat.mtime,
-							uid: stat.uid,
-							gid: stat.gid,
-							type: "directory"
-						};
-						if (map) header = map(header);
-						packer.add(header);
-						packer.endEntry();
-						const dirents = await fs.readdir(source.source, { withFileTypes: true });
-						for (let i = dirents.length - 1; i >= 0; i--) {
-							const dirent = dirents[i];
-							const childSourcePath = path.join(source.source, dirent.name);
-							const childTargetPath = `${target.replace(/\/$/, "")}/${dirent.name}`;
-							if (baseDir && dereference && await isSymlinkUnsafe(childSourcePath, baseDir)) continue;
-							stack.push({
-								type: dirent.isDirectory() ? "directory" : "file",
-								source: childSourcePath,
-								target: childTargetPath
-							});
+		const packer = createTarPacker((chunk) => stream.push(Buffer.from(chunk)), stream.destroy.bind(stream), () => stream.push(null));
+		const { dereference = false, filter, map, baseDir, concurrency = cpus().length || 8 } = options;
+		const isDir = typeof sources === "string";
+		const directoryPath = isDir ? path.resolve(sources) : null;
+		const jobs = isDir ? (await fs.readdir(directoryPath, { withFileTypes: true })).map((entry) => ({
+			type: entry.isDirectory() ? "directory" : "file",
+			source: path.join(directoryPath, entry.name),
+			target: entry.name
+		})) : sources;
+		const results = /* @__PURE__ */ new Map();
+		const resolvers = /* @__PURE__ */ new Map();
+		const seenInodes = /* @__PURE__ */ new Map();
+		let jobIndex = 0;
+		let writeIndex = 0;
+		let activeWorkers = 0;
+		let allJobsQueued = false;
+		const writer = async () => {
+			const readBuffer = Buffer.alloc(64 * 1024);
+			while (true) {
+				if (stream.destroyed) return;
+				if (allJobsQueued && writeIndex >= jobs.length) break;
+				if (!results.has(writeIndex)) {
+					await new Promise((resolve) => resolvers.set(writeIndex, resolve));
+					continue;
+				}
+				const result = results.get(writeIndex);
+				results.delete(writeIndex);
+				resolvers.delete(writeIndex);
+				if (!result) {
+					writeIndex++;
+					continue;
+				}
+				packer.add(result.header);
+				if (result.body) if (result.body instanceof Uint8Array) {
+					if (result.body.length > 0) packer.write(result.body);
+				} else {
+					const { handle, size } = result.body;
+					try {
+						let bytesLeft = size;
+						while (bytesLeft > 0 && !stream.destroyed) {
+							const toRead = Math.min(bytesLeft, readBuffer.length);
+							const { bytesRead } = await handle.read(readBuffer, 0, toRead, null);
+							if (bytesRead === 0) break;
+							packer.write(readBuffer.subarray(0, bytesRead));
+							bytesLeft -= bytesRead;
 						}
-						break;
+					} catch (error) {
+						stream.destroy(error);
+						return;
+					} finally {
+						await handle.close();
 					}
-					case "content": {
-						const data = await normalizeBody(source.content);
-						let header = {
-							name: target,
-							size: data.length,
-							mode: source.mode ?? 420,
-							type: "file"
+				}
+				packer.endEntry();
+				writeIndex++;
+			}
+		};
+		const controller = () => {
+			if (stream.destroyed || allJobsQueued) return;
+			while (activeWorkers < concurrency && jobIndex < jobs.length) {
+				activeWorkers++;
+				const currentIndex = jobIndex++;
+				processJob(jobs[currentIndex], currentIndex).catch(stream.destroy.bind(stream)).finally(() => {
+					activeWorkers--;
+					controller();
+				});
+			}
+			if (activeWorkers === 0 && jobIndex >= jobs.length) {
+				allJobsQueued = true;
+				resolvers.get(writeIndex)?.();
+			}
+		};
+		const processJob = async (job, index) => {
+			let jobResult = null;
+			const target = job.target.replace(/\\/g, "/");
+			try {
+				if (job.type === "content") {
+					const data = await normalizeBody(job.content);
+					const stat$1 = {
+						size: data.length,
+						isFile: () => true,
+						isDirectory: () => false,
+						isSymbolicLink: () => false,
+						mode: job.mode ?? 420,
+						mtime: /* @__PURE__ */ new Date(),
+						uid: process.getuid?.() ?? 0,
+						gid: process.getgid?.() ?? 0
+					};
+					if (filter && !filter(target, stat$1)) return;
+					let header$1 = {
+						name: target,
+						type: "file",
+						size: stat$1.size,
+						mode: stat$1.mode,
+						mtime: stat$1.mtime,
+						uid: stat$1.uid,
+						gid: stat$1.gid
+					};
+					if (map) header$1 = map(header$1);
+					jobResult = {
+						header: header$1,
+						body: data
+					};
+					return;
+				}
+				let stat = await fs.lstat(job.source, { bigint: true });
+				if (dereference && stat.isSymbolicLink()) {
+					const linkTarget = await fs.readlink(job.source);
+					const resolved = path.resolve(path.dirname(job.source), linkTarget);
+					const resolvedBase = baseDir ?? directoryPath ?? process.cwd();
+					if (!resolved.startsWith(resolvedBase + path.sep) && resolved !== resolvedBase) return;
+					stat = await fs.stat(job.source, { bigint: true });
+				}
+				if (filter && !filter(target, stat)) return;
+				let header = {
+					name: target,
+					size: 0,
+					mode: Number(stat.mode),
+					mtime: stat.mtime,
+					uid: Number(stat.uid),
+					gid: Number(stat.gid),
+					type: "file"
+				};
+				let body;
+				if (stat.isDirectory()) {
+					header.type = "directory";
+					header.name = target.endsWith("/") ? target : `${target}/`;
+					try {
+						for (const d of await fs.readdir(job.source, { withFileTypes: true })) jobs.push({
+							type: d.isDirectory() ? "directory" : "file",
+							source: path.join(job.source, d.name),
+							target: `${header.name}${d.name}`
+						});
+					} catch {}
+				} else if (stat.isSymbolicLink()) {
+					header.type = "symlink";
+					header.linkname = await fs.readlink(job.source);
+				} else if (stat.isFile()) {
+					header.size = Number(stat.size);
+					if (stat.nlink > 1 && seenInodes.has(stat.ino)) {
+						header.type = "link";
+						header.linkname = seenInodes.get(stat.ino);
+						header.size = 0;
+					} else {
+						if (stat.nlink > 1) seenInodes.set(stat.ino, target);
+						if (header.size > 0) if (header.size < 32 * 1024) body = await fs.readFile(job.source);
+						else body = {
+							handle: await fs.open(job.source, "r"),
+							size: header.size
 						};
-						if (map) header = map(header);
-						packer.add(header);
-						if (data.length > 0) packer.write(data);
-						packer.endEntry();
-						break;
 					}
-				}
+				} else return;
+				if (map) header = map(header);
+				jobResult = {
+					header,
+					body
+				};
+			} finally {
+				results.set(index, jobResult);
+				resolvers.get(index)?.();
 			}
-			packer.finalize();
-		} catch (error) {
-			stream.destroy(error);
-		}
-	})();
+		};
+		controller();
+		await writer();
+		if (!stream.destroyed) packer.finalize();
+	})().catch((error) => stream.destroy(error));
 	return stream;
 }
-function packTar(directoryPath, options = {}) {
-	const stream = new Readable({ read() {} });
-	(async () => {
-		try {
-			const resolvedPath = path.resolve(directoryPath);
-			const allSources = (await fs.readdir(resolvedPath, { withFileTypes: true })).map((dirent) => ({
-				type: dirent.isDirectory() ? "directory" : "file",
-				source: path.join(resolvedPath, dirent.name),
-				target: dirent.name
-			}));
-			const sources = [];
-			for (const source of allSources) if (source.type === "content" || !options.dereference || !await isSymlinkUnsafe(source.source, resolvedPath)) sources.push(source);
-			const sourceStream = packTarSources(sources, {
-				...options,
-				baseDir: resolvedPath
-			});
-			sourceStream.on("data", (chunk) => stream.push(chunk));
-			sourceStream.on("end", () => stream.push(null));
-			sourceStream.on("error", (err) => stream.destroy(err));
-		} catch (error) {
-			stream.destroy(error);
-		}
-	})();
-	return stream;
-}
-async function isSymlinkUnsafe(sourcePath, baseDir) {
-	try {
-		if ((await fs.lstat(sourcePath)).isSymbolicLink()) {
-			const linkTarget = await fs.readlink(sourcePath);
-			const resolvedTarget = path.resolve(path.dirname(sourcePath), linkTarget);
-			return !(resolvedTarget === baseDir || resolvedTarget.startsWith(baseDir + path.sep));
-		}
-	} catch {
-		return true;
-	}
-	return false;
-}
 
 //#endregion
 //#region src/fs/path.ts
@@ -337,7 +372,7 @@ function createFSHandler(directoryPath, options) {
 		handler: {
 			onHeader(header) {
 				if (signal.aborted) return;
-				activeEntryStream = new PassThrough();
+				activeEntryStream = new PassThrough({ highWaterMark: header.size > 1048576 ? 524288 : void 0 });
 				const entryStream = activeEntryStream;
 				const startOperation = () => {
 					let opPromise;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "modern-tar",
-	"version": "0.4.1",
+	"version": "0.4.2",
 	"description": "Zero dependency streaming tar parser and writer for JavaScript.",
 	"author": "Ayuhito <hello@ayuhito.com>",
 	"license": "MIT",
@@ -16,7 +16,7 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.2.5",
-		"@types/node": "^24.6.2",
+		"@types/node": "^24.7.1",
 		"@vitest/coverage-v8": "^3.2.4",
 		"tsdown": "^0.15.6",
 		"typescript": "^5.9.3",