feat(pack): allow overriding more metadata on tar sources (#78)

* feat(pack): allow overriding more metadata on tar sources

* test(pack): support windows cases

Author: ayuhito

REFERENCE.md

@@ -236,43 +236,49 @@ interface PackOptionsFS {
   map?: (header: TarHeader) => TarHeader;
 }
 
+// Base interface for all source types
+interface BaseSource {
+  /** Destination path for the entry inside the tar archive */
+  target: string;
+  /** Optional modification time. Overrides filesystem values or defaults to current time. */
+  mtime?: Date;
+  /** Optional user ID. Overrides filesystem values or defaults to 0. */
+  uid?: number;
+  /** Optional group ID. Overrides filesystem values or defaults to 0. */
+  gid?: number;
+  /** Optional user name. */
+  uname?: string;
+  /** Optional group name. */
+  gname?: string;
+  /** Optional Unix file permissions for the entry (e.g., 0o644, 0o755). */
+  mode?: number;
+}
+
 // Source types for packTar function
-interface FileSource {
+interface FileSource extends BaseSource {
   type: "file";
   /** Path to the source file on the local filesystem */
   source: string;
-  /** Destination path inside the tar archive */
-  target: string;
 }
 
-interface DirectorySource {
+interface DirectorySource extends BaseSource {
   type: "directory";
   /** Path to the source directory on the local filesystem */
   source: string;
-  /** Destination path inside the tar archive */
-  target: string;
 }
 
-interface ContentSource {
+interface ContentSource extends BaseSource {
   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;
 }
 
-interface StreamSource {
+interface StreamSource extends BaseSource {
   type: "stream";
   /** A Node.js Readable stream or Web ReadableStream. */
   content: Readable | ReadableStream;
-  /** Destination path inside the tar archive */
-  target: string;
   /** The total size of the stream's content in bytes. This is required for streams to prevent hanging. */
   size: number;
-  /** Optional Unix file permissions (e.g., 0o644, 0o755) */
-  mode?: number;
 }
 
 type TarSource = FileSource | DirectorySource | ContentSource | StreamSource;

src/fs/pack.ts

@@ -248,9 +248,9 @@ export function packTar(
 						isDirectory: () => false,
 						isSymbolicLink: () => false,
 						mode: job.mode ?? 0o644,
-						mtime: new Date(),
-						uid: process.getuid?.() ?? 0,
-						gid: process.getgid?.() ?? 0,
+						mtime: job.mtime ?? new Date(),
+						uid: job.uid ?? 0,
+						gid: job.gid ?? 0,
 					} as Stats;
 
 					if (filter && !filter(target, stat)) return;
@@ -263,6 +263,8 @@ export function packTar(
 						mtime: stat.mtime,
 						uid: stat.uid,
 						gid: stat.gid,
+						uname: job.uname,
+						gname: job.gname,
 					};
 
 					if (map) header = map(header);
@@ -297,10 +299,12 @@ export function packTar(
 				let header: TarHeader = {
 					name: target,
 					size: 0,
-					mode: Number(stat.mode),
-					mtime: stat.mtime,
-					uid: Number(stat.uid),
-					gid: Number(stat.gid),
+					mode: job.mode ?? Number(stat.mode),
+					mtime: job.mtime ?? stat.mtime,
+					uid: job.uid ?? Number(stat.uid),
+					gid: job.gid ?? Number(stat.gid),
+					uname: job.uname,
+					gname: job.gname,
 					type: "file", // Default type
 				};
 

src/fs/types.ts

@@ -50,46 +50,52 @@ export interface UnpackOptionsFS extends UnpackOptions {
 	concurrency?: number;
 }
 
+/** Base interface containing common metadata properties for all source types. */
+export interface BaseSource {
+	/** Destination path for the entry inside the tar archive. */
+	target: string;
+	/** Optional modification time. Overrides filesystem values or defaults to current time. */
+	mtime?: Date;
+	/** Optional user ID. Overrides filesystem values or defaults to 0. */
+	uid?: number;
+	/** Optional group ID. Overrides filesystem values or defaults to 0. */
+	gid?: number;
+	/** Optional user name. */
+	uname?: string;
+	/** Optional group name. */
+	gname?: string;
+	/** Optional Unix file permissions for the entry (e.g., 0o644, 0o755). */
+	mode?: number;
+}
+
 /** Describes a file on the local filesystem to be added to the archive. */
-export interface FileSource {
+export interface FileSource extends BaseSource {
 	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. */
-export interface DirectorySource {
+export interface DirectorySource extends BaseSource {
 	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, buffered content to be added to the archive. */
-export interface ContentSource {
+export interface ContentSource extends BaseSource {
 	type: "content";
 	/** Raw content to add. Supports string, Uint8Array, ArrayBuffer, 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;
 }
 
 /** Describes a stream of content to be added to the archive. */
-export interface StreamSource {
+export interface StreamSource extends BaseSource {
 	type: "stream";
 	/** A Readable or ReadableStream. */
 	content: Readable | ReadableStream;
-	/** Destination path for the content inside the tar archive. */
-	target: string;
 	/** The total size of the stream's content in bytes. This is required for streams. */
 	size: number;
-	/** Optional Unix file permissions for the entry (e.g., 0o644). */
-	mode?: number;
 }
 
 /** A union of all possible source types for creating a tar archive. */