modern-tar 0.3.0 → 0.3.2

package/README.md

@@ -246,7 +246,7 @@ const entries = [
 const tarBuffer = await packTar(entries);
 ```
 
-#### `unpackTar(archive: ArrayBuffer | Uint8Array, options?: UnpackOptions): Promise<ParsedTarEntryWithData[]>`
+#### `unpackTar(archive: ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, options?: UnpackOptions): Promise<ParsedTarEntryWithData[]>`
 
 Extract all entries from a tar archive buffer with optional filtering and transformation.
 
@@ -287,7 +287,7 @@ const stream2 = controller.add({ name: "file2.txt", size: 4 });
 controller.finalize();
 ```
 
-#### `createTarDecoder(): TransformStream<Uint8Array, ParsedTarEntry>`
+#### `createTarDecoder(options?: DecoderOptions): TransformStream<Uint8Array, ParsedTarEntry>`
 
 Create a transform stream that parses tar bytes into entries.
 
@@ -387,6 +387,7 @@ const tarStream = createReadStream('backup.tar');
 const extractStream = unpackTar('/restore/location', {
   strip: 1,
   fmode: 0o644, // Set consistent file permissions
+  strict: true, // Enable strict validation
 });
 await pipeline(tarStream, extractStream);
 ```
@@ -455,8 +456,13 @@ interface ParsedTarEntryWithData {
 }
 
 // Platform-neutral configuration for unpacking
-interface UnpackOptions {
-  /** Number of leading path components to strip from entry names (e.g., strip: 1 removes first directory) */
+interface DecoderOptions {
+  /** Enable strict validation (e.g., throw on invalid checksums) */
+  strict?: boolean;
+}
+
+interface UnpackOptions extends DecoderOptions {
+	/** Number of leading path components to strip from entry names (e.g., strip: 1 removes first directory) */
   strip?: number;
   /** Filter function to include/exclude entries (return false to skip) */
   filter?: (header: TarHeader) => boolean;

package/dist/fs/index.d.ts

@@ -1,4 +1,4 @@
-import { TarEntryData, TarHeader, UnpackOptions } from "../index-C8X7IkYR.js";
+import { TarEntryData, TarHeader, UnpackOptions } from "../index-1Ec89lu7.js";
 import { Stats } from "node:fs";
 import { Readable, Writable } from "node:stream";
 

package/dist/fs/index.js

@@ -1,4 +1,4 @@
-import { BLOCK_SIZE, createTarDecoder, createTarHeader, createTarOptionsTransformer, createTarPacker, encoder, generatePax } from "../web-LcCN87Qy.js";
+import { BLOCK_SIZE, createTarDecoder, createTarHeader, createTarOptionsTransformer, createTarPacker, encoder, generatePax } from "../web-Daso6SHn.js";
 import { createReadStream, createWriteStream } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
@@ -269,7 +269,7 @@ function unpackTar(directoryPath, options = {}) {
 		const resolvedDestDir = normalizePath(path.resolve(directoryPath));
 		const validatedDirs = new Set([resolvedDestDir]);
 		await fs.mkdir(resolvedDestDir, { recursive: true });
-		const reader = readable.pipeThrough(createTarDecoder()).pipeThrough(createTarOptionsTransformer(options)).getReader();
+		const reader = readable.pipeThrough(createTarDecoder(options)).pipeThrough(createTarOptionsTransformer(options)).getReader();
 		try {
 			const maxDepth = options.maxDepth ?? 1024;
 			while (true) {

package/dist/{index-C8X7IkYR.d.ts → index-1Ec89lu7.d.ts}

@@ -142,13 +142,26 @@ interface ParsedTarEntryWithData {
   header: TarHeader;
   data: Uint8Array;
 }
+/**
+ * Configuration options for creating a tar decoder stream.
+ */
+interface DecoderOptions {
+  /**
+   * Enable strict validation of the tar archive.
+   * When true, the decoder will throw errors for data corruption issues:
+   * - Invalid checksums (indicates header corruption)
+   * - Invalid USTAR magic string (format violation)
+   * @default false
+   */
+  strict?: boolean;
+}
 /**
  * Platform-neutral configuration options for extracting tar archives.
  *
  * These options work with any tar extraction implementation and are not tied
  * to specific platforms like Node.js filesystem APIs.
  */
-interface UnpackOptions {
+interface UnpackOptions extends DecoderOptions {
   /** Number of leading path components to strip from entry names (e.g., strip: 1 removes first directory) */
   strip?: number;
   /** Filter function to include/exclude entries (return false to skip) */
@@ -372,6 +385,7 @@ declare function createTarPacker(): {
 /**
  * Create a transform stream that parses tar bytes into entries.
  *
+ * @param options - Optional configuration for the decoder using {@link DecoderOptions}.
  * @returns `TransformStream` that converts tar archive bytes to {@link ParsedTarEntry} objects.
  * @example
  * ```typescript
@@ -385,6 +399,6 @@ declare function createTarPacker(): {
  *  // Process entry.body stream as needed
  * }
  */
-declare function createTarDecoder(): TransformStream<Uint8Array, ParsedTarEntry>;
+declare function createTarDecoder(options?: DecoderOptions): TransformStream<Uint8Array, ParsedTarEntry>;
 //#endregion
-export { type ParsedTarEntry, type ParsedTarEntryWithData, type TarEntry, type TarEntryData, type TarHeader, type TarPackController, type UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar };
+export { type DecoderOptions, type ParsedTarEntry, type ParsedTarEntryWithData, type TarEntry, type TarEntryData, type TarHeader, type TarPackController, type UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar };

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-C8X7IkYR.js";
-export { ParsedTarEntry, ParsedTarEntryWithData, TarEntry, TarEntryData, TarHeader, TarPackController, UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar };
+import { DecoderOptions, ParsedTarEntry, ParsedTarEntryWithData, TarEntry, TarEntryData, TarHeader, TarPackController, UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../index-1Ec89lu7.js";
+export { DecoderOptions, 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-LcCN87Qy.js";
+import { createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../web-Daso6SHn.js";
 
 export { createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar };

package/dist/{web-LcCN87Qy.js → web-Daso6SHn.js}

@@ -291,7 +291,7 @@ function readString(view, offset, size) {
 */
 function readOctal(view, offset, size) {
 	const octalString = readString(view, offset, size).trim();
-	return octalString ? Number.parseInt(octalString, 8) : 0;
+	return octalString ? parseInt(octalString, 8) : 0;
 }
 /**
 * Reads a numeric field that can be octal or POSIX base-256.
@@ -557,6 +557,7 @@ const metaEntryParsers = {
 /**
 * Create a transform stream that parses tar bytes into entries.
 *
+* @param options - Optional configuration for the decoder using {@link DecoderOptions}.
 * @returns `TransformStream` that converts tar archive bytes to {@link ParsedTarEntry} objects.
 * @example
 * ```typescript
@@ -570,7 +571,8 @@ const metaEntryParsers = {
 *  // Process entry.body stream as needed
 * }
 */
-function createTarDecoder() {
+function createTarDecoder(options = {}) {
+	const strict = options.strict ?? false;
 	let buffer = new Uint8Array(0);
 	let currentEntry = null;
 	let paxGlobals = {};
@@ -607,7 +609,7 @@ function createTarDecoder() {
 						return;
 					}
 				}
-				const header = parseUstarHeader(headerBlock);
+				const header = parseUstarHeader(headerBlock, strict);
 				const metaParser = metaEntryParsers[header.type];
 				if (metaParser) {
 					const dataSize = header.size;
@@ -650,18 +652,22 @@ function createTarDecoder() {
 			if (offset > 0) buffer = buffer.slice(offset);
 		},
 		flush(controller) {
-			if (currentEntry) {
-				const error = /* @__PURE__ */ new Error("Tar archive is truncated.");
+			if (currentEntry) if (strict) {
+				const error = /* @__PURE__ */ new Error(`Tar archive is truncated. Expected ${currentEntry.header.size} bytes but received ${currentEntry.header.size - currentEntry.bytesLeft}.`);
 				currentEntry.controller.error(error);
 				controller.error(error);
-			}
-			if (buffer.some((b) => b !== 0)) controller.error(/* @__PURE__ */ new Error("Unexpected data at end of archive."));
+			} else try {
+				currentEntry.controller.close();
+			} catch {}
+			if (strict && buffer.some((b) => b !== 0)) controller.error(/* @__PURE__ */ new Error("Unexpected data at end of archive."));
 		}
 	});
 }
-function parseUstarHeader(block) {
-	if (!validateChecksum(block)) throw new Error("Invalid tar header checksum.");
+function parseUstarHeader(block, strict) {
+	if (strict && !validateChecksum(block)) throw new Error("Invalid tar header checksum.");
 	const typeflag = readString(block, USTAR.typeflag.offset, USTAR.typeflag.size);
+	const magic = readString(block, USTAR.magic.offset, USTAR.magic.size);
+	if (strict && magic !== "ustar") throw new Error(`Invalid USTAR magic: expected "ustar", got "${magic}"`);
 	return {
 		name: readString(block, USTAR.name.offset, USTAR.name.size),
 		mode: readOctal(block, USTAR.mode.offset, USTAR.mode.size),
@@ -672,7 +678,7 @@ function parseUstarHeader(block) {
 		checksum: readOctal(block, USTAR.checksum.offset, USTAR.checksum.size),
 		type: FLAGTYPE[typeflag] || "file",
 		linkname: readString(block, USTAR.linkname.offset, USTAR.linkname.size),
-		magic: readString(block, USTAR.magic.offset, USTAR.magic.size),
+		magic,
 		uname: readString(block, USTAR.uname.offset, USTAR.uname.size),
 		gname: readString(block, USTAR.gname.offset, USTAR.gname.size),
 		prefix: readString(block, USTAR.prefix.offset, USTAR.prefix.size)
@@ -685,7 +691,7 @@ function parsePax(buffer) {
 	while (offset < buffer.length) {
 		const spaceIndex = buffer.indexOf(32, offset);
 		if (spaceIndex === -1) break;
-		const length = Number.parseInt(decoder.decode(buffer.subarray(offset, spaceIndex)), 10);
+		const length = parseInt(decoder.decode(buffer.subarray(offset, spaceIndex)), 10);
 		if (Number.isNaN(length) || length === 0) break;
 		const recordEnd = offset + length;
 		const [key, value] = decoder.decode(buffer.subarray(spaceIndex + 1, recordEnd - 1)).split("=", 2);
@@ -699,16 +705,16 @@ function parsePax(buffer) {
 					overrides.linkname = value;
 					break;
 				case "size":
-					overrides.size = Number.parseInt(value, 10);
+					overrides.size = parseInt(value, 10);
 					break;
 				case "mtime":
-					overrides.mtime = Number.parseFloat(value);
+					overrides.mtime = parseFloat(value);
 					break;
 				case "uid":
-					overrides.uid = Number.parseInt(value, 10);
+					overrides.uid = parseInt(value, 10);
 					break;
 				case "gid":
-					overrides.gid = Number.parseInt(value, 10);
+					overrides.gid = parseInt(value, 10);
 					break;
 				case "uname":
 					overrides.uname = value;
@@ -853,7 +859,7 @@ async function unpackTar(archive, options = {}) {
 		controller.close();
 	} });
 	const results = [];
-	const reader = sourceStream.pipeThrough(createTarDecoder()).pipeThrough(createTarOptionsTransformer(options)).getReader();
+	const reader = sourceStream.pipeThrough(createTarDecoder(options)).pipeThrough(createTarOptionsTransformer(options)).getReader();
 	try {
 		while (true) {
 			const { done, value: entry } = await reader.read();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "modern-tar",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Zero dependency streaming tar parser and writer for JavaScript.",
 	"author": "Ayuhito <hello@ayuhito.com>",
 	"license": "MIT",