feat: added options to tar generator

Author: aryanjassal

src/Generator.ts

@@ -1,31 +1,62 @@
-import type { TarType, DirectoryContent } from './types';
+import type {
+  EntryType,
+  DirectoryContent,
+  HeaderOptions,
+  ReadFileOptions,
+  WalkDirectoryOptions,
+  TarOptions,
+} from './types';
 import fs from 'fs';
 import path from 'path';
-import { TarTypes } from './types';
+import { EntryTypes } from './types';
 import * as errors from './errors';
 
-/**
- * The size for each tar block. This is usually 512 bytes.
- */
-const BLOCK_SIZE = 512;
+// Set defaults to the options used by the generators
+const defaultHeaderOptions: HeaderOptions = {
+  fileNameEncoding: 'utf8',
+  blockSize: 512,
+};
+const defaultReadFileOptions: ReadFileOptions = {
+  fs: fs.promises,
+  blockSize: 512,
+};
+const defaultWalkDirectoryOptions: WalkDirectoryOptions = {
+  fs: fs.promises,
+  blockSize: 512,
+};
+const defaultTarOptions: TarOptions = {
+  fs: fs.promises,
+  blockSize: 512,
+  fileNameEncoding: 'utf8',
+};
 
 function computeChecksum(header: Buffer): number {
-  let sum = 0;
-  for (let i = 0; i < BLOCK_SIZE; i++) {
-    sum += i >= 148 && i < 156 ? 32 : header[i]; // Fill checksum with spaces
+  if (!header.subarray(148, 156).every((byte) => byte === 32)) {
+    throw new errors.ErrorVirtualTarInvalidHeader(
+      'Checksum field is not properly initialized with spaces',
+    );
   }
-  return sum;
+  return header.reduce((sum, byte) => sum + byte, 0);
 }
 
-function createHeader(filePath: string, stat: fs.Stats, type: TarType): Buffer {
+function createHeader(
+  filePath: string,
+  stat: fs.Stats,
+  type: EntryType,
+  options: Partial<HeaderOptions> = defaultHeaderOptions,
+): Buffer {
   if (filePath.length < 1 || filePath.length > 255) {
     throw new errors.ErrorVirtualTarInvalidFileName(
       'The file name must be longer than 1 character and shorter than 255 characters',
     );
   }
 
-  const size = type === TarTypes.FILE ? stat.size : 0;
-  const header = Buffer.alloc(BLOCK_SIZE, 0);
+  // Merge the defaults with the provided options
+  const opts: HeaderOptions = { ...defaultHeaderOptions, ...options };
+
+  const size = type === EntryTypes.FILE ? stat.size : 0;
+  const time = parseInt((stat.mtime.getTime() / 1000).toFixed(0)); // Unix time
+  const header = Buffer.alloc(opts.blockSize, 0);
 
   // The TAR headers follow this structure
   // Start    Size    Description
@@ -48,12 +79,17 @@ function createHeader(filePath: string, stat: fs.Stats, type: TarType): Buffer {
   // 345      155     File name (last 155 bytes, total 255 bytes, null-padded)
   // 500      12      '\0' (unused)
 
-  header.write(filePath.slice(0, 99).padEnd(100, '\0'), 0, 100, 'utf8');
+  header.write(
+    filePath.slice(0, 99).padEnd(100, '\0'),
+    0,
+    100,
+    opts.fileNameEncoding,
+  );
   header.write(stat.mode.toString(8).padStart(7, '0') + '\0', 100, 12, 'ascii');
   header.write(stat.uid.toString(8).padStart(7, '0') + '\0', 108, 12, 'ascii');
   header.write(stat.gid.toString(8).padStart(7, '0') + '\0', 116, 12, 'ascii');
   header.write(size.toString(8).padStart(7, '0') + '\0', 124, 12, 'ascii');
-  // Mtime will be null
+  header.write(time.toString(8).padStart(7, '0') + '\0', 136, 12, 'ascii');
   header.write('        ', 148, 8, 'ascii'); // Placeholder for checksum
   header.write(type, 156, 1, 'ascii');
   // File owner name will be null
@@ -63,7 +99,12 @@ function createHeader(filePath: string, stat: fs.Stats, type: TarType): Buffer {
   // Owner group name will be null
   // Device major will be null
   // Device minor will be null
-  header.write(filePath.slice(100).padEnd(155, '\0'), 345, 155, 'utf8');
+  header.write(
+    filePath.slice(100).padEnd(155, '\0'),
+    345,
+    155,
+    opts.fileNameEncoding,
+  );
 
   // Updating with the new checksum
   const checksum = computeChecksum(header);
@@ -72,19 +113,23 @@ function createHeader(filePath: string, stat: fs.Stats, type: TarType): Buffer {
   return header;
 }
 
-async function* readFile(filePath: string): AsyncGenerator<Buffer, void, void> {
-  const fileHandle = await fs.promises.open(filePath, 'r');
-  const buffer = Buffer.alloc(BLOCK_SIZE);
+async function* readFile(
+  filePath: string,
+  options: Partial<ReadFileOptions> = defaultReadFileOptions,
+): AsyncGenerator<Buffer, void, void> {
+  const opts: ReadFileOptions = { ...defaultReadFileOptions, ...options };
+  const fileHandle = await opts.fs.open(filePath, 'r');
+  const buffer = Buffer.alloc(opts.blockSize);
   let bytesRead = -1; // Initialisation value
 
   try {
     while (bytesRead !== 0) {
       buffer.fill(0);
-      const result = await fileHandle.read(buffer, 0, BLOCK_SIZE, null);
+      const result = await fileHandle.read(buffer, 0, opts.blockSize, null);
       bytesRead = result.bytesRead;
 
       if (bytesRead === 0) break; // EOF reached
-      if (bytesRead < 512) buffer.fill(0, bytesRead, BLOCK_SIZE);
+      if (bytesRead < 512) buffer.fill(0, bytesRead, opts.blockSize);
 
       yield buffer;
     }
@@ -99,38 +144,53 @@ async function* readFile(filePath: string): AsyncGenerator<Buffer, void, void> {
 async function* walkDirectory(
   baseDir: string,
   relativePath: string = '',
+  options: Partial<WalkDirectoryOptions> = defaultWalkDirectoryOptions,
 ): AsyncGenerator<DirectoryContent> {
-  const entries = await fs.promises.readdir(path.join(baseDir, relativePath));
+  const opts: WalkDirectoryOptions = {
+    ...defaultWalkDirectoryOptions,
+    ...options,
+  };
+  const entries = await opts.fs.readdir(path.join(baseDir, relativePath));
 
   // Sort the entries lexicographically
   for (const entry of entries.sort()) {
     const fullPath = path.join(baseDir, relativePath, entry);
-    const stat = await fs.promises.stat(fullPath);
+    const stat = await opts.fs.stat(fullPath);
     const tarPath = path.join(relativePath, entry);
 
     if (stat.isDirectory()) {
-      yield { path: tarPath + '/', stat: stat, type: TarTypes.DIRECTORY };
+      yield { path: tarPath + '/', stat: stat, type: EntryTypes.DIRECTORY };
       yield* walkDirectory(baseDir, path.join(relativePath, entry));
     } else if (stat.isFile()) {
-      yield { path: tarPath, stat: stat, type: TarTypes.FILE };
+      yield { path: tarPath, stat: stat, type: EntryTypes.FILE };
     }
   }
 }
 
-async function* createTar(baseDir: string): AsyncGenerator<Buffer, void, void> {
-  for await (const entry of walkDirectory(baseDir)) {
-    // Create header
+async function* createTar(
+  baseDir: string,
+  options: Partial<TarOptions> = defaultTarOptions,
+): AsyncGenerator<Buffer, void, void> {
+  const opts = { ...defaultTarOptions, ...options };
+  const entryGen = walkDirectory(baseDir, '', {
+    fs: opts.fs,
+    blockSize: opts.blockSize,
+  });
+
+  for await (const entry of entryGen) {
     yield createHeader(entry.path, entry.stat, entry.type);
 
-    if (entry.type === TarTypes.FILE) {
-      // Get file contents
-      yield* readFile(path.join(baseDir, entry.path));
+    if (entry.type === EntryTypes.FILE) {
+      yield* readFile(path.join(baseDir, entry.path), {
+        fs: opts.fs,
+        blockSize: opts.blockSize,
+      });
     }
   }
 
   // End-of-archive marker - two 512-byte null blocks
-  yield Buffer.alloc(BLOCK_SIZE, 0);
-  yield Buffer.alloc(BLOCK_SIZE, 0);
+  yield Buffer.alloc(opts.blockSize, 0);
+  yield Buffer.alloc(opts.blockSize, 0);
 }
 
 export { createHeader, readFile, createTar };

src/errors.ts

@@ -12,8 +12,13 @@ class ErrorVirtualTarInvalidFileName<T> extends ErrorVirtualTar<T> {
   static description = 'The provided file name is invalid';
 }
 
+class ErrorVirtualTarInvalidHeader<T> extends ErrorVirtualTar<T> {
+  static description = 'The header has invalid data';
+}
+
 export {
   ErrorVirtualTar,
   ErrorVirtualTarUndefinedBehaviour,
   ErrorVirtualTarInvalidFileName,
+  ErrorVirtualTarInvalidHeader,
 };

src/types.ts

@@ -1,17 +1,49 @@
 import type { Stats } from 'fs';
 
-const TarTypes = {
+const EntryTypes = {
   FILE: '0',
   DIRECTORY: '5',
 } as const;
 
-type TarType = (typeof TarTypes)[keyof typeof TarTypes];
+type EntryType = (typeof EntryTypes)[keyof typeof EntryTypes];
 
 type DirectoryContent = {
   path: string;
   stat: Stats;
-  type: TarType;
+  type: EntryType;
 };
 
-export type { TarType, DirectoryContent };
-export { TarTypes };
+type HeaderOptions = {
+  fileNameEncoding: 'ascii' | 'utf8';
+  blockSize: number;
+};
+
+// An actual type for `fs` doesn't exist
+type ReadFileOptions = {
+  fs: any;
+  blockSize: number;
+};
+
+// An actual type for `fs` doesn't exist
+type WalkDirectoryOptions = {
+  fs: any;
+  blockSize: number;
+};
+
+// An actual type for `fs` doesn't exist
+type TarOptions = {
+  fs: any;
+  blockSize: number;
+  fileNameEncoding: 'ascii' | 'utf8';
+};
+
+export type {
+  EntryType,
+  DirectoryContent,
+  HeaderOptions,
+  ReadFileOptions,
+  WalkDirectoryOptions,
+  TarOptions,
+};
+
+export { EntryTypes };