modern-tar 0.0.0 → 0.2.0

package/README.md

@@ -173,6 +173,25 @@ const extractStream = unpackTar('./output', {
 await pipeline(sourceStream, extractStream);
 ```
 
+#### Archive Creation
+
+```typescript
+import { packTarSources, type TarSource } from 'modern-tar/fs';
+import { createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+
+// Pack multiple sources
+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' },
+  { type: 'content', content: '#!/bin/bash\necho "Executable"', target: 'bin/script.sh', mode: 0o755 }
+];
+
+const archiveStream = packTarSources(sources);
+await pipeline(archiveStream, createWriteStream('project.tar'));
+```
+
 ## API Reference
 
 ### Core API (`modern-tar`)
@@ -339,6 +358,31 @@ const extractStream = unpackTar('/restore/location', {
 await pipeline(tarStream, extractStream);
 ```
 
+#### `packTarSources(sources: TarSource[]): Readable`
+
+Pack multiple sources (files, directories, or raw content) into a tar archive stream.
+
+- **`sources`**: Array of `TarSource` objects describing what to include in the archive.
+- **Returns**: Node.js `Readable` stream of tar archive bytes.
+
+**Example:**
+
+```typescript
+import { packTarSources, type TarSource } from 'modern-tar/fs';
+import { createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+
+const sources: TarSource[] = [
+  { type: 'file', source: './README.md', target: 'docs/readme.txt' },
+  { type: 'directory', source: './src', target: 'app/src' },
+  { type: 'content', content: '{"version": "1.0.0"}', target: 'app/config.json' },
+  { type: 'content', content: Buffer.from('binary data'), target: 'data/binary.dat' }
+];
+
+const archiveStream = packTarSources(sources);
+await pipeline(archiveStream, createWriteStream('app.tar'));
+```
+
 ## Types
 
 ### Core Types
@@ -400,6 +444,35 @@ interface PackOptionsFS {
   map?: (header: TarHeader) => TarHeader;
 }
 
+// Source types for packTarSources function
+interface FileSource {
+  type: "file";
+  /** Path to the source file on the local filesystem */
+  source: string;
+  /** Destination path inside the tar archive */
+  target: string;
+}
+
+interface DirectorySource {
+  type: "directory";
+  /** Path to the source directory on the local filesystem */
+  source: string;
+  /** Destination path inside the tar archive */
+  target: string;
+}
+
+interface ContentSource {
+  type: "content";
+  /** Raw content to add. Supports string, Uint8Array, ArrayBuffer, ReadableStream, Blob, or null. */
+	content: TarEntryData;
+  /** Destination path inside the tar archive */
+  target: string;
+  /** Optional Unix file permissions (e.g., 0o644, 0o755) */
+  mode?: number;
+}
+
+type TarSource = FileSource | DirectorySource | ContentSource;
+
 interface UnpackOptionsFS extends UnpackOptions {
   // Inherited from UnpackOptions (platform-neutral):
   /** Number of leading path components to strip from entry names */

package/dist/fs/index.d.ts

@@ -1,8 +1,8 @@
-import { TarHeader, UnpackOptions } from "../index-BLp7i3zL.js";
+import { TarEntryData, TarHeader, UnpackOptions } from "../index-Dx4tbuJh.js";
 import { Stats } from "node:fs";
 import { Readable, Writable } from "node:stream";
 
-//#region src/fs/pack.d.ts
+//#region src/fs/types.d.ts
 
 /**
  * Filesystem-specific configuration options for packing directories into tar archives.
@@ -18,6 +18,78 @@ interface PackOptionsFS {
   /** Transform function to modify tar headers before packing */
   map?: (header: TarHeader) => TarHeader;
 }
+/**
+ * Filesystem-specific configuration options for extracting tar archives to the filesystem.
+ *
+ * Extends the core {@link UnpackOptions} with Node.js filesystem-specific settings
+ * for controlling file permissions and other filesystem behaviors.
+ */
+interface UnpackOptionsFS extends UnpackOptions {
+  /** Default mode for created directories (e.g., 0o755). If not specified, uses mode from tar header or system default */
+  dmode?: number;
+  /** Default mode for created files (e.g., 0o644). If not specified, uses mode from tar header or system default */
+  fmode?: number;
+  /**
+   * Prevent symlinks from pointing outside the extraction directory.
+   * @default true
+   */
+  validateSymlinks?: boolean;
+}
+/** Describes a file on the local filesystem to be added to the archive. */
+interface FileSource {
+  type: "file";
+  /** Path to the source file on the local filesystem. */
+  source: string;
+  /** Destination path for the file inside the tar archive. */
+  target: string;
+}
+/** Describes a directory on the local filesystem to be added to the archive. */
+interface DirectorySource {
+  type: "directory";
+  /** Path to the source directory on the local filesystem. */
+  source: string;
+  /** Destination path for the directory inside the tar archive. */
+  target: string;
+}
+/** Describes raw content to be added to the archive. Supports all TarEntryData types including strings, buffers, streams, blobs, and null. */
+interface ContentSource {
+  type: "content";
+  /** Raw content to add. Supports string, Uint8Array, ArrayBuffer, ReadableStream, Blob, or null. */
+  content: TarEntryData;
+  /** Destination path for the content inside the tar archive. */
+  target: string;
+  /** Optional Unix file permissions for the entry (e.g., 0o644). */
+  mode?: number;
+}
+/** A union of all possible source types for creating a tar archive. */
+type TarSource = FileSource | DirectorySource | ContentSource;
+//#endregion
+//#region src/fs/archive.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.
+ * @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'));
+ * ```
+ */
+declare function packTarSources(sources: TarSource[]): Readable;
+//#endregion
+//#region src/fs/pack.d.ts
 /**
  * Pack a directory into a Node.js [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) stream containing tar archive bytes.
  *
@@ -49,23 +121,6 @@ interface PackOptionsFS {
 declare function packTar(directoryPath: string, options?: PackOptionsFS): Readable;
 //#endregion
 //#region src/fs/unpack.d.ts
-/**
- * Filesystem-specific configuration options for extracting tar archives to the filesystem.
- *
- * Extends the core {@link UnpackOptions} with Node.js filesystem-specific settings
- * for controlling file permissions and other filesystem behaviors.
- */
-interface UnpackOptionsFS extends UnpackOptions {
-  /** Default mode for created directories (e.g., 0o755). If not specified, uses mode from tar header or system default */
-  dmode?: number;
-  /** Default mode for created files (e.g., 0o644). If not specified, uses mode from tar header or system default */
-  fmode?: number;
-  /**
-   * Prevent symlinks from pointing outside the extraction directory.
-   * @default true
-   */
-  validateSymlinks?: boolean;
-}
 /**
  * Extract a tar archive to a directory.
  *
@@ -99,4 +154,4 @@ interface UnpackOptionsFS extends UnpackOptions {
  */
 declare function unpackTar(directoryPath: string, options?: UnpackOptionsFS): Writable;
 //#endregion
-export { type PackOptionsFS, type UnpackOptionsFS, packTar, unpackTar };
+export { type ContentSource, type DirectorySource, type FileSource, type PackOptionsFS, type TarSource, type UnpackOptionsFS, packTar, packTarSources, unpackTar };

package/dist/fs/index.js

@@ -1,10 +1,121 @@
-import { BLOCK_SIZE, createTarDecoder, createTarHeader, createTarOptionsTransformer } from "../web-BsjPG7md.js";
+import { BLOCK_SIZE, createTarDecoder, createTarHeader, createTarOptionsTransformer, createTarPacker } from "../web-C1b5fAZt.js";
 import { createReadStream, createWriteStream } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { PassThrough, Readable, Writable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
+//#region src/fs/archive.ts
+async function addFileToPacker(controller, sourcePath, targetPath) {
+	const stat = await fs.stat(sourcePath);
+	const entryStream = controller.add({
+		name: targetPath,
+		size: stat.size,
+		mode: stat.mode,
+		mtime: stat.mtime,
+		type: "file"
+	});
+	await pipeline(createReadStream(sourcePath), Writable.fromWeb(entryStream));
+}
+async function addDirectoryToPacker(controller, sourcePath, targetPathInArchive) {
+	const sourceStat = await fs.stat(sourcePath);
+	controller.add({
+		name: `${targetPathInArchive}/`,
+		type: "directory",
+		mode: sourceStat.mode,
+		mtime: sourceStat.mtime,
+		size: 0
+	}).close();
+	const dirents = await fs.readdir(sourcePath, { withFileTypes: true });
+	for (const dirent of dirents) {
+		const fullSourcePath = path.join(sourcePath, dirent.name);
+		const archiveEntryPath = path.join(targetPathInArchive, dirent.name).replace(/\\/g, "/");
+		if (dirent.isDirectory()) await addDirectoryToPacker(controller, fullSourcePath, archiveEntryPath);
+		else if (dirent.isFile()) await addFileToPacker(controller, fullSourcePath, archiveEntryPath);
+	}
+}
+/**
+* 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.
+* @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'));
+* ```
+*/
+function packTarSources(sources) {
+	const { readable, controller } = createTarPacker();
+	(async () => {
+		for (const source of sources) {
+			const targetPath = source.target.replace(/\\/g, "/");
+			switch (source.type) {
+				case "file":
+					await addFileToPacker(controller, source.source, targetPath);
+					break;
+				case "directory":
+					await addDirectoryToPacker(controller, source.source, targetPath);
+					break;
+				case "content": {
+					const { content, mode } = source;
+					if (content instanceof Blob) {
+						const entryStream = controller.add({
+							name: targetPath,
+							size: content.size,
+							mode,
+							type: "file"
+						});
+						await content.stream().pipeTo(entryStream);
+						break;
+					}
+					if (content instanceof ReadableStream) {
+						const chunks = [];
+						for await (const chunk of Readable.fromWeb(content)) chunks.push(chunk);
+						const buffer = Buffer.concat(chunks);
+						const writer$1 = controller.add({
+							name: targetPath,
+							size: buffer.length,
+							mode,
+							type: "file"
+						}).getWriter();
+						await writer$1.write(buffer);
+						await writer$1.close();
+						break;
+					}
+					let data;
+					if (content === null || content === void 0) data = new Uint8Array(0);
+					else if (typeof content === "string") data = Buffer.from(content);
+					else if (content instanceof ArrayBuffer) data = new Uint8Array(content);
+					else data = content;
+					const writer = controller.add({
+						name: targetPath,
+						size: data.length,
+						mode,
+						type: "file"
+					}).getWriter();
+					await writer.write(data);
+					await writer.close();
+					break;
+				}
+			}
+		}
+	})().then(() => controller.finalize()).catch((err) => controller.error(err));
+	return Readable.fromWeb(readable);
+}
+
+//#endregion
 //#region src/fs/pack.ts
 /**
 * Pack a directory into a Node.js [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) stream containing tar archive bytes.
@@ -119,58 +230,17 @@ function packTar(directoryPath, options = {}) {
 */
 function unpackTar(directoryPath, options = {}) {
 	const bridge = new PassThrough();
-	const webReadable = Readable.toWeb(bridge);
-	const processingPromise = (async () => {
-		const { validateSymlinks = true } = options;
-		const resolvedDestDir = path.resolve(directoryPath);
-		const createdDirs = /* @__PURE__ */ new Set();
-		await fs.mkdir(resolvedDestDir, { recursive: true });
-		createdDirs.add(resolvedDestDir);
-		const entryStream = webReadable.pipeThrough(createTarDecoder()).pipeThrough(createTarOptionsTransformer(options));
-		for await (const entry of entryStream) {
-			const header = entry.header;
-			const outPath = path.join(directoryPath, header.name);
-			const parentDir = path.dirname(outPath);
-			if (!createdDirs.has(parentDir)) {
-				await fs.mkdir(parentDir, { recursive: true });
-				createdDirs.add(parentDir);
-			}
-			switch (header.type) {
-				case "directory": {
-					const mode = options.dmode ?? header.mode;
-					if (createdDirs.has(outPath) && mode) await fs.chmod(outPath, mode);
-					else {
-						await fs.mkdir(outPath, {
-							recursive: true,
-							mode
-						});
-						createdDirs.add(outPath);
-					}
-					break;
-				}
-				case "file":
-					await pipeline(Readable.fromWeb(entry.body), createWriteStream(outPath, { mode: options.fmode ?? header.mode }));
-					break;
-				case "symlink":
-					if (header.linkname) {
-						if (validateSymlinks) {
-							const symlinkDir = path.dirname(outPath);
-							const resolvedTarget = path.resolve(symlinkDir, header.linkname);
-							if (!resolvedTarget.startsWith(resolvedDestDir + path.sep) && resolvedTarget !== resolvedDestDir) throw new Error(`Symlink target "${header.linkname}" points outside of the extraction directory.`);
-						}
-						await fs.symlink(header.linkname, outPath);
-					}
-					break;
-				case "link":
-					if (header.linkname) await fs.link(path.join(directoryPath, header.linkname), outPath);
-					break;
-			}
-			if (header.mtime) try {
-				await (header.type === "symlink" ? fs.lutimes : fs.utimes)(outPath, header.mtime, header.mtime);
-			} catch {}
+	const readable = new ReadableStream({
+		start(controller) {
+			bridge.on("data", (chunk) => controller.enqueue(chunk));
+			bridge.on("end", () => controller.close());
+			bridge.on("error", (err) => controller.error(err));
+		},
+		cancel(reason) {
+			bridge.destroy(reason instanceof Error ? reason : new Error(String(reason)));
 		}
-	})();
-	return new Writable({
+	});
+	const writable = new Writable({
 		write(chunk, encoding, callback) {
 			if (!bridge.write(chunk, encoding)) {
 				bridge.once("drain", callback);
@@ -187,7 +257,70 @@ function unpackTar(directoryPath, options = {}) {
 			callback(err);
 		}
 	});
+	const processingPromise = (async () => {
+		const resolvedDestDir = path.resolve(directoryPath);
+		const createdDirs = /* @__PURE__ */ new Set();
+		await fs.mkdir(resolvedDestDir, { recursive: true });
+		createdDirs.add(resolvedDestDir);
+		const reader = readable.pipeThrough(createTarDecoder()).pipeThrough(createTarOptionsTransformer(options)).getReader();
+		try {
+			while (true) {
+				const { done, value: entry } = await reader.read();
+				if (done) break;
+				const { header } = entry;
+				if (path.isAbsolute(header.name)) throw new Error(`Path traversal attempt detected for entry "${header.name}".`);
+				const outPath = path.join(resolvedDestDir, header.name);
+				if (!outPath.startsWith(resolvedDestDir)) throw new Error(`Path traversal attempt detected for entry "${header.name}".`);
+				const parentDir = path.dirname(outPath);
+				if (!createdDirs.has(parentDir)) {
+					await fs.mkdir(parentDir, { recursive: true });
+					createdDirs.add(parentDir);
+				}
+				switch (header.type) {
+					case "directory": {
+						const mode = options.dmode ?? header.mode;
+						if (createdDirs.has(outPath) && mode) await fs.chmod(outPath, mode);
+						else {
+							await fs.mkdir(outPath, {
+								recursive: true,
+								mode
+							});
+							createdDirs.add(outPath);
+						}
+						break;
+					}
+					case "file":
+						await pipeline(Readable.fromWeb(entry.body), createWriteStream(outPath, { mode: options.fmode ?? header.mode }));
+						break;
+					case "symlink":
+						if (!header.linkname) break;
+						if (options.validateSymlinks ?? true) {
+							const symlinkDir = path.dirname(outPath);
+							if (!path.resolve(symlinkDir, header.linkname).startsWith(resolvedDestDir)) throw new Error(`Symlink target "${header.linkname}" points outside the extraction directory.`);
+						}
+						await fs.symlink(header.linkname, outPath);
+						break;
+					case "link": {
+						if (!header.linkname) break;
+						const resolvedLinkTarget = path.resolve(resolvedDestDir, header.linkname);
+						if (!resolvedLinkTarget.startsWith(resolvedDestDir)) throw new Error(`Hardlink target "${header.linkname}" points outside the extraction directory.`);
+						await fs.link(resolvedLinkTarget, outPath);
+						break;
+					}
+				}
+				if (header.mtime) try {
+					await (header.type === "symlink" ? fs.lutimes : fs.utimes)(outPath, header.mtime, header.mtime);
+				} catch {}
+			}
+		} finally {
+			reader.releaseLock();
+		}
+	})();
+	processingPromise.catch((err) => {
+		writable.destroy(err);
+	});
+	return writable;
 }
 
 //#endregion
-export { packTar, unpackTar };
+export { packTar, packTarSources, unpackTar };

package/dist/{index-BLp7i3zL.d.ts → index-Dx4tbuJh.d.ts}

@@ -1,3 +1,73 @@
+//#region src/web/compression.d.ts
+/**
+ * Creates a gzip compression stream using the native
+ * [`CompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) API.
+ *
+ * @returns A [`CompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) configured for gzip compression
+ * @example
+ * ```typescript
+ * import { createGzipEncoder, createTarPacker } from '@modern-tar/core';
+ *
+ * // Create and compress a tar archive
+ * const { readable, controller } = createTarPacker();
+ * const compressedStream = readable.pipeThrough(createGzipEncoder());
+ *
+ * // Add entries...
+ * const fileStream = controller.add({ name: "file.txt", size: 5, type: "file" });
+ * const writer = fileStream.getWriter();
+ * await writer.write(new TextEncoder().encode("hello"));
+ * await writer.close();
+ * controller.finalize();
+ *
+ * // Upload compressed .tar.gz
+ * await fetch('/api/upload', {
+ *   method: 'POST',
+ *   body: compressedStream,
+ *   headers: { 'Content-Type': 'application/gzip' }
+ * });
+ * ```
+ */
+declare function createGzipEncoder(): CompressionStream;
+/**
+ * Creates a gzip decompression stream using the native
+ * [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream) API.
+ *
+ * @returns A [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream) configured for gzip decompression
+ * @example
+ * ```typescript
+ * import { createGzipDecoder, createTarDecoder } from '@modern-tar/core';
+ *
+ * // Download and process a .tar.gz file
+ * const response = await fetch('https://api.example.com/archive.tar.gz');
+ * if (!response.body) throw new Error('No response body');
+ *
+ * // Chain decompression and tar parsing
+ * const entries = response.body
+ *   .pipeThrough(createGzipDecoder())
+ *   .pipeThrough(createTarDecoder());
+ *
+ * for await (const entry of entries) {
+ *   console.log(`Extracted: ${entry.header.name}`);
+ *   // Process entry.body ReadableStream as needed
+ * }
+ * ```
+ * @example
+ * ```typescript
+ * // Decompress local .tar.gz data
+ * const gzippedData = new Uint8Array([...]); // your gzipped tar data
+ * const stream = new ReadableStream({
+ *   start(controller) {
+ *     controller.enqueue(gzippedData);
+ *     controller.close();
+ *   }
+ * });
+ *
+ * const tarStream = stream.pipeThrough(createGzipDecoder());
+ * // Now process tarStream with createTarDecoder()...
+ * ```
+ */
+declare function createGzipDecoder(): DecompressionStream;
+//#endregion
 //#region src/web/types.d.ts
 /**
  * Header information for a tar entry in USTAR format.
@@ -78,76 +148,6 @@ interface UnpackOptions {
   map?: (header: TarHeader) => TarHeader;
 }
 //#endregion
-//#region src/web/compression.d.ts
-/**
- * Creates a gzip compression stream using the native
- * [`CompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) API.
- *
- * @returns A [`CompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) configured for gzip compression
- * @example
- * ```typescript
- * import { createGzipEncoder, createTarPacker } from '@modern-tar/core';
- *
- * // Create and compress a tar archive
- * const { readable, controller } = createTarPacker();
- * const compressedStream = readable.pipeThrough(createGzipEncoder());
- *
- * // Add entries...
- * const fileStream = controller.add({ name: "file.txt", size: 5, type: "file" });
- * const writer = fileStream.getWriter();
- * await writer.write(new TextEncoder().encode("hello"));
- * await writer.close();
- * controller.finalize();
- *
- * // Upload compressed .tar.gz
- * await fetch('/api/upload', {
- *   method: 'POST',
- *   body: compressedStream,
- *   headers: { 'Content-Type': 'application/gzip' }
- * });
- * ```
- */
-declare function createGzipEncoder(): CompressionStream;
-/**
- * Creates a gzip decompression stream using the native
- * [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream) API.
- *
- * @returns A [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream) configured for gzip decompression
- * @example
- * ```typescript
- * import { createGzipDecoder, createTarDecoder } from '@modern-tar/core';
- *
- * // Download and process a .tar.gz file
- * const response = await fetch('https://api.example.com/archive.tar.gz');
- * if (!response.body) throw new Error('No response body');
- *
- * // Chain decompression and tar parsing
- * const entries = response.body
- *   .pipeThrough(createGzipDecoder())
- *   .pipeThrough(createTarDecoder());
- *
- * for await (const entry of entries) {
- *   console.log(`Extracted: ${entry.header.name}`);
- *   // Process entry.body ReadableStream as needed
- * }
- * ```
- * @example
- * ```typescript
- * // Decompress local .tar.gz data
- * const gzippedData = new Uint8Array([...]); // your gzipped tar data
- * const stream = new ReadableStream({
- *   start(controller) {
- *     controller.enqueue(gzippedData);
- *     controller.close();
- *   }
- * });
- *
- * const tarStream = stream.pipeThrough(createGzipDecoder());
- * // Now process tarStream with createTarDecoder()...
- * ```
- */
-declare function createGzipDecoder(): DecompressionStream;
-//#endregion
 //#region src/web/helpers.d.ts
 /**
  * Packs an array of tar entries into a single `Uint8Array` buffer.

package/dist/web/index.d.ts

@@ -1,2 +1,2 @@
-import { ParsedTarEntry, ParsedTarEntryWithData, TarEntry, TarEntryData, TarHeader, TarPackController, UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../index-BLp7i3zL.js";
+import { ParsedTarEntry, ParsedTarEntryWithData, TarEntry, TarEntryData, TarHeader, TarPackController, UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../index-Dx4tbuJh.js";
 export { ParsedTarEntry, ParsedTarEntryWithData, TarEntry, TarEntryData, TarHeader, TarPackController, UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar };

package/dist/web/index.js

@@ -1,3 +1,3 @@
-import { createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../web-BsjPG7md.js";
+import { createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../web-C1b5fAZt.js";
 
 export { createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar };

package/dist/{web-BsjPG7md.js → web-C1b5fAZt.js}

@@ -1,3 +1,154 @@
+//#region src/web/compression.ts
+/**
+* Creates a gzip compression stream using the native
+* [`CompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) API.
+*
+* @returns A [`CompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) configured for gzip compression
+* @example
+* ```typescript
+* import { createGzipEncoder, createTarPacker } from '@modern-tar/core';
+*
+* // Create and compress a tar archive
+* const { readable, controller } = createTarPacker();
+* const compressedStream = readable.pipeThrough(createGzipEncoder());
+*
+* // Add entries...
+* const fileStream = controller.add({ name: "file.txt", size: 5, type: "file" });
+* const writer = fileStream.getWriter();
+* await writer.write(new TextEncoder().encode("hello"));
+* await writer.close();
+* controller.finalize();
+*
+* // Upload compressed .tar.gz
+* await fetch('/api/upload', {
+*   method: 'POST',
+*   body: compressedStream,
+*   headers: { 'Content-Type': 'application/gzip' }
+* });
+* ```
+*/
+function createGzipEncoder() {
+	return new CompressionStream("gzip");
+}
+/**
+* Creates a gzip decompression stream using the native
+* [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream) API.
+*
+* @returns A [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream) configured for gzip decompression
+* @example
+* ```typescript
+* import { createGzipDecoder, createTarDecoder } from '@modern-tar/core';
+*
+* // Download and process a .tar.gz file
+* const response = await fetch('https://api.example.com/archive.tar.gz');
+* if (!response.body) throw new Error('No response body');
+*
+* // Chain decompression and tar parsing
+* const entries = response.body
+*   .pipeThrough(createGzipDecoder())
+*   .pipeThrough(createTarDecoder());
+*
+* for await (const entry of entries) {
+*   console.log(`Extracted: ${entry.header.name}`);
+*   // Process entry.body ReadableStream as needed
+* }
+* ```
+* @example
+* ```typescript
+* // Decompress local .tar.gz data
+* const gzippedData = new Uint8Array([...]); // your gzipped tar data
+* const stream = new ReadableStream({
+*   start(controller) {
+*     controller.enqueue(gzippedData);
+*     controller.close();
+*   }
+* });
+*
+* const tarStream = stream.pipeThrough(createGzipDecoder());
+* // Now process tarStream with createTarDecoder()...
+* ```
+*/
+function createGzipDecoder() {
+	return new DecompressionStream("gzip");
+}
+
+//#endregion
+//#region src/web/options.ts
+/**
+* Creates a transform stream that applies {@link UnpackOptions} to tar entries.
+*
+* @param options - The unpacking options to apply
+* @returns A TransformStream that processes {@link ParsedTarEntry} objects
+*
+* @example
+* ```typescript
+* import { createTarDecoder, createTarOptionsTransformer } from '@modern-tar/core';
+*
+* const transformedStream = sourceStream
+*   .pipeThrough(createTarDecoder())
+*   .pipeThrough(createTarOptionsTransformer({
+*     strip: 1,
+*     filter: (header) => header.name.endsWith('.txt'),
+*     map: (header) => ({ ...header, mode: 0o644 })
+*   }));
+* ```
+*/
+function createTarOptionsTransformer(options = {}) {
+	return new TransformStream({ async transform(entry, controller) {
+		let header = entry.header;
+		if (options.strip !== void 0) {
+			if (options.strip < 0) {
+				drainStream(entry.body);
+				throw new Error(`Invalid strip value: ${options.strip}. Must be non-negative.`);
+			}
+			if (options.strip > 0) {
+				const strippedComponents = header.name.split("/").filter((component) => component.length > 0).slice(options.strip);
+				if (strippedComponents.length === 0) {
+					drainStream(entry.body);
+					return;
+				}
+				const strippedName = strippedComponents.join("/");
+				if (header.type === "directory" && !strippedName.endsWith("/")) header = {
+					...header,
+					name: `${strippedName}/`
+				};
+				else header = {
+					...header,
+					name: strippedName
+				};
+			}
+		}
+		if (options.filter && options.filter(header) === false) {
+			drainStream(entry.body);
+			return;
+		}
+		if (options.map) header = options.map(header);
+		controller.enqueue({
+			header,
+			body: entry.body
+		});
+	} });
+}
+/**
+* Drains the stream asynchronously without blocking the transform stream.
+*/
+function drainStream(stream) {
+	(async () => {
+		const reader = stream.getReader();
+		try {
+			while (true) {
+				const { done } = await reader.read();
+				if (done) break;
+			}
+		} catch (error) {
+			console.debug("Stream drain error (non-critical):", error);
+		} finally {
+			reader.releaseLock();
+		}
+	})();
+}
+
+//#endregion
 //#region src/web/constants.ts
 /** Size of a TAR block in bytes. */
 const BLOCK_SIZE = 512;
@@ -227,6 +378,32 @@ function createTarPacker() {
 		controller: {
 			add(header) {
 				const size = header.type === "directory" || header.type === "symlink" || header.type === "link" ? 0 : header.size ?? 0;
+				if (header.pax) {
+					let paxRecords = "";
+					for (const [key, value] of Object.entries(header.pax)) {
+						const record = `${key}=${value}\n`;
+						let length = record.length + 1;
+						const lengthStr = String(length);
+						length += lengthStr.length;
+						const finalLengthStr = String(length);
+						if (finalLengthStr.length !== lengthStr.length) length += finalLengthStr.length - lengthStr.length;
+						paxRecords += `${length} ${record}`;
+					}
+					if (paxRecords) {
+						const paxBytes = encoder.encode(paxRecords);
+						const paxHeader = createTarHeader({
+							name: `PaxHeader/${header.name}`,
+							size: paxBytes.length,
+							type: "pax-header",
+							mode: 420,
+							mtime: header.mtime
+						});
+						streamController.enqueue(paxHeader);
+						streamController.enqueue(paxBytes);
+						const paxPadding = (BLOCK_SIZE - paxBytes.length % BLOCK_SIZE) % BLOCK_SIZE;
+						if (paxPadding > 0) streamController.enqueue(new Uint8Array(paxPadding));
+					}
+				}
 				const headerBlock = createTarHeader({
 					...header,
 					size
@@ -268,157 +445,6 @@ function createTarPacker() {
 	};
 }
 
-//#endregion
-//#region src/web/compression.ts
-/**
-* Creates a gzip compression stream using the native
-* [`CompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) API.
-*
-* @returns A [`CompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream) configured for gzip compression
-* @example
-* ```typescript
-* import { createGzipEncoder, createTarPacker } from '@modern-tar/core';
-*
-* // Create and compress a tar archive
-* const { readable, controller } = createTarPacker();
-* const compressedStream = readable.pipeThrough(createGzipEncoder());
-*
-* // Add entries...
-* const fileStream = controller.add({ name: "file.txt", size: 5, type: "file" });
-* const writer = fileStream.getWriter();
-* await writer.write(new TextEncoder().encode("hello"));
-* await writer.close();
-* controller.finalize();
-*
-* // Upload compressed .tar.gz
-* await fetch('/api/upload', {
-*   method: 'POST',
-*   body: compressedStream,
-*   headers: { 'Content-Type': 'application/gzip' }
-* });
-* ```
-*/
-function createGzipEncoder() {
-	return new CompressionStream("gzip");
-}
-/**
-* Creates a gzip decompression stream using the native
-* [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream) API.
-*
-* @returns A [`DecompressionStream`](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream) configured for gzip decompression
-* @example
-* ```typescript
-* import { createGzipDecoder, createTarDecoder } from '@modern-tar/core';
-*
-* // Download and process a .tar.gz file
-* const response = await fetch('https://api.example.com/archive.tar.gz');
-* if (!response.body) throw new Error('No response body');
-*
-* // Chain decompression and tar parsing
-* const entries = response.body
-*   .pipeThrough(createGzipDecoder())
-*   .pipeThrough(createTarDecoder());
-*
-* for await (const entry of entries) {
-*   console.log(`Extracted: ${entry.header.name}`);
-*   // Process entry.body ReadableStream as needed
-* }
-* ```
-* @example
-* ```typescript
-* // Decompress local .tar.gz data
-* const gzippedData = new Uint8Array([...]); // your gzipped tar data
-* const stream = new ReadableStream({
-*   start(controller) {
-*     controller.enqueue(gzippedData);
-*     controller.close();
-*   }
-* });
-*
-* const tarStream = stream.pipeThrough(createGzipDecoder());
-* // Now process tarStream with createTarDecoder()...
-* ```
-*/
-function createGzipDecoder() {
-	return new DecompressionStream("gzip");
-}
-
-//#endregion
-//#region src/web/options.ts
-/**
-* Creates a transform stream that applies {@link UnpackOptions} to tar entries.
-*
-* @param options - The unpacking options to apply
-* @returns A TransformStream that processes {@link ParsedTarEntry} objects
-*
-* @example
-* ```typescript
-* import { createTarDecoder, createTarOptionsTransformer } from '@modern-tar/core';
-*
-* const transformedStream = sourceStream
-*   .pipeThrough(createTarDecoder())
-*   .pipeThrough(createTarOptionsTransformer({
-*     strip: 1,
-*     filter: (header) => header.name.endsWith('.txt'),
-*     map: (header) => ({ ...header, mode: 0o644 })
-*   }));
-* ```
-*/
-function createTarOptionsTransformer(options = {}) {
-	return new TransformStream({ async transform(entry, controller) {
-		let header = entry.header;
-		if (options.strip !== void 0) {
-			if (options.strip < 0) {
-				drainStream(entry.body);
-				throw new Error(`Invalid strip value: ${options.strip}. Must be non-negative.`);
-			}
-			if (options.strip > 0) {
-				const strippedComponents = header.name.split("/").filter((component) => component.length > 0).slice(options.strip);
-				if (strippedComponents.length === 0) {
-					drainStream(entry.body);
-					return;
-				}
-				const strippedName = strippedComponents.join("/");
-				if (header.type === "directory" && !strippedName.endsWith("/")) header = {
-					...header,
-					name: `${strippedName}/`
-				};
-				else header = {
-					...header,
-					name: strippedName
-				};
-			}
-		}
-		if (options.filter && options.filter(header) === false) {
-			drainStream(entry.body);
-			return;
-		}
-		if (options.map) header = options.map(header);
-		controller.enqueue({
-			header,
-			body: entry.body
-		});
-	} });
-}
-/**
-* Drains the stream asynchronously without blocking the transform stream.
-*/
-function drainStream(stream) {
-	(async () => {
-		const reader = stream.getReader();
-		try {
-			while (true) {
-				const { done } = await reader.read();
-				if (done) break;
-			}
-		} catch (error) {
-			console.debug("Stream drain error (non-critical):", error);
-		} finally {
-			reader.releaseLock();
-		}
-	})();
-}
-
 //#endregion
 //#region src/web/stream.ts
 function parseHeader(block) {
@@ -551,7 +577,11 @@ function createTarDecoder() {
 			buffer = combined.subarray(offset);
 		},
 		flush(controller) {
-			if (currentEntry) controller.error(/* @__PURE__ */ new Error("Tar archive is truncated."));
+			if (currentEntry) {
+				const error = /* @__PURE__ */ new Error("Tar archive is truncated.");
+				currentEntry.controller.error(error);
+				controller.error(error);
+			}
 			if (buffer.some((b) => b !== 0)) controller.error(/* @__PURE__ */ new Error("Unexpected data at end of archive."));
 		}
 	});

package/package.json

@@ -1,10 +1,13 @@
 {
 	"name": "modern-tar",
-	"version": "0.0.0",
+	"version": "0.2.0",
 	"description": "Zero dependency streaming tar parser and writer for JavaScript.",
 	"license": "MIT",
 	"type": "module",
 	"sideEffects": false,
+	"main": "./dist/web/index.js",
+	"module": "./dist/web/index.js",
+	"types": "./dist/web/index.d.ts",
 	"exports": {
 		"./package.json": "./package.json",
 		".": {