@tmlmobilidade/go-utils-exec 20260903.2201.22 → 20260904.1431.46

package/dist/files/calculate-zip-hash.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Calculates a deterministic SHA-256 hash of the contents of a `.zip` file.
+ * The hash is independent of `.zip` file metadata such as file modification timestamps,
+ * compression settings, and `.zip` file entry ordering.
+ * Files are hashed individually in streaming mode, then the filenames and
+ * individual hashes are sorted and combined into the final hash.
+ * @param zipFilePath The path to the `.zip` file.
+ * @returns The SHA-256 hash of the `.zip` file contents.
+ */
+export declare function calculateZipFileHash(filePath: string): Promise<string>;

package/dist/files/calculate-zip-hash.js

@@ -0,0 +1,61 @@
+/* * */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import unzipper from 'unzipper';
+import { getDirectoryFiles } from './get-directory-files.js';
+/**
+ * Calculates a deterministic SHA-256 hash of the contents of a `.zip` file.
+ * The hash is independent of `.zip` file metadata such as file modification timestamps,
+ * compression settings, and `.zip` file entry ordering.
+ * Files are hashed individually in streaming mode, then the filenames and
+ * individual hashes are sorted and combined into the final hash.
+ * @param zipFilePath The path to the `.zip` file.
+ * @returns The SHA-256 hash of the `.zip` file contents.
+ */
+export async function calculateZipFileHash(filePath) {
+    //
+    //
+    // Initialize a new temporary directory and extract the ZIP file into it.
+    const temporaryDirectory = fs.mkdtempDisposableSync('calculate-zip-file-hash');
+    await fs
+        .createReadStream(filePath)
+        .pipe(unzipper.Extract({ path: temporaryDirectory.path }))
+        .promise();
+    //
+    // Find all extracted files.
+    const sortedExtractedFilePaths = await getDirectoryFiles(temporaryDirectory.path);
+    //
+    // Initialize the list of files to hash.
+    const foundFiles = [];
+    for (const absolutePath of sortedExtractedFilePaths) {
+        // Create a new hash for the file
+        const hash = createHash('sha256');
+        // Open a read stream for the file.
+        const stream = fs.createReadStream(absolutePath);
+        // Stream the file contents and calculate the SHA-256 hash.
+        for await (const chunk of stream) {
+            hash.update(chunk);
+        }
+        // Add the file to the list of files to hash.
+        const relativeFilePath = path.relative(temporaryDirectory.path, absolutePath);
+        foundFiles.push({ hash: hash.digest('hex'), path: relativeFilePath });
+    }
+    //
+    // Make the result independent of the order of entries in the zip file.
+    foundFiles.sort((a, b) => a.path.localeCompare(b.path));
+    //
+    // Clean up the temporary directory.
+    temporaryDirectory.remove();
+    //
+    // Calculate the final hash by concatenating the sorted list
+    // of filenames and individual file hashes.
+    const finalHash = createHash('sha256');
+    for (const file of foundFiles) {
+        finalHash.update(file.path);
+        finalHash.update('\0');
+        finalHash.update(file.hash);
+        finalHash.update('\0');
+    }
+    return finalHash.digest('hex');
+}

package/dist/files/get-directory-files.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Gets the files in a directory and its subdirectories recursively.
+ * @param dirPath The path to the directory to get the files from.
+ * @returns A promise that resolves to an array of file paths.
+ */
+export declare function getDirectoryFiles(dirPath: string): Promise<string[]>;

package/dist/files/get-directory-files.js

@@ -0,0 +1,37 @@
+/* * */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Gets the files in a directory and its subdirectories recursively.
+ * @param dirPath The path to the directory to get the files from.
+ * @returns A promise that resolves to an array of file paths.
+ */
+export async function getDirectoryFiles(dirPath) {
+    //
+    //
+    // Read the directory contents.
+    const dirEntries = await fs.readdir(dirPath, { withFileTypes: true });
+    //
+    // Initialize the list of files.
+    const dirFiles = [];
+    for (const entry of dirEntries) {
+        // Get the path to the entry.
+        const entryPath = path.join(dirPath, entry.name);
+        // If the entry is a directory, recursively get
+        // the files in the subdirectory.
+        if (entry.isDirectory()) {
+            const subdirFiles = await getDirectoryFiles(entryPath);
+            dirFiles.push(...subdirFiles);
+            continue;
+        }
+        // Add the path to the list of files.
+        if (entry.isFile()) {
+            dirFiles.push(entryPath);
+        }
+    }
+    //
+    // Sort and return the list of files in the directory
+    // and its subdirectories.
+    const sortedDirFiles = dirFiles.sort((a, b) => a.localeCompare(b));
+    return sortedDirFiles;
+}

package/dist/files/index.d.ts

@@ -0,0 +1,5 @@
+export * from './calculate-zip-hash.js';
+export * from './get-directory-files.js';
+export * from './set-directory-permissions.js';
+export * from './stream-csv-file.js';
+export * from './unzip-file.js';

package/dist/files/index.js

@@ -0,0 +1,5 @@
+export * from './calculate-zip-hash.js';
+export * from './get-directory-files.js';
+export * from './set-directory-permissions.js';
+export * from './stream-csv-file.js';
+export * from './unzip-file.js';

package/dist/files/set-directory-permissions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sets the permissions of a directory and its files.
+ * @param dirPath The path to the directory to set the permissions of.
+ * @param mode The mode to set the permissions of the directory and its files to.
+ */
+export declare function setDirectoryPermissions(dirPath: string, mode: number): void;

package/dist/files/set-directory-permissions.js

@@ -0,0 +1,19 @@
+/* * */
+import fs from 'node:fs';
+/**
+ * Sets the permissions of a directory and its files.
+ * @param dirPath The path to the directory to set the permissions of.
+ * @param mode The mode to set the permissions of the directory and its files to.
+ */
+export function setDirectoryPermissions(dirPath, mode) {
+    const files = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const file of files) {
+        const filePath = `${dirPath}/${file.name}`;
+        if (file.isDirectory()) {
+            setDirectoryPermissions(filePath, mode);
+        }
+        else {
+            fs.chmodSync(filePath, mode);
+        }
+    }
+}

package/dist/files/stream-csv-file.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parses a CSV file into a stream and calls a callback function for each row.
+ * @param filePath The path to the CSV file to parse.
+ * @param rowParser A callback function that will be called for each row.
+ * @returns A promise that resolves when the stream is closed.
+ */
+export declare function streamCsvFile<T>(filePath: string, rowParser: (rowData: T) => Promise<void>): Promise<void>;

package/dist/files/stream-csv-file.js

@@ -0,0 +1,25 @@
+/* * */
+import { parse as csvParser } from 'csv-parse';
+import fs from 'fs';
+/**
+ * Parses a CSV file into a stream and calls a callback function for each row.
+ * @param filePath The path to the CSV file to parse.
+ * @param rowParser A callback function that will be called for each row.
+ * @returns A promise that resolves when the stream is closed.
+ */
+export async function streamCsvFile(filePath, rowParser) {
+    const parser = csvParser({
+        bom: true,
+        cast: value => value === '' ? undefined : value,
+        columns: true,
+        record_delimiter: ['\n', '\r', '\r\n'],
+        skip_empty_lines: true,
+        skipRecordsWithEmptyValues: true,
+        trim: true,
+    });
+    const fileStream = fs.createReadStream(filePath);
+    const stream = fileStream.pipe(parser);
+    for await (const rowData of stream) {
+        await rowParser(rowData);
+    }
+}

package/dist/files/unzip-file.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Unzips a zip file into a directory in stream mode, avoiding memory issues.
+ * This also calls the `setDirectoryPermissions` function to override
+ * the permissions of the unzipped files, if any were preserved in the zip file.
+ * @param zipFilePath The path to the zip file to unzip.
+ * @param outputDir The path to the directory to unzip the file to.
+ * @param dirPermissionsMode The mode to set the permissions of the unzipped directory to. Defaults to `0o666` (read and write for owner, group and others).
+ * @returns A promise that resolves when the file is unzipped.
+ */
+export declare function unzipFile(zipFilePath: string, outputDir: string, dirPermissionsMode?: number): Promise<void>;

package/dist/files/unzip-file.js

@@ -0,0 +1,20 @@
+/* * */
+import fs from 'node:fs';
+import unzipper from 'unzipper';
+import { setDirectoryPermissions } from './set-directory-permissions.js';
+/**
+ * Unzips a zip file into a directory in stream mode, avoiding memory issues.
+ * This also calls the `setDirectoryPermissions` function to override
+ * the permissions of the unzipped files, if any were preserved in the zip file.
+ * @param zipFilePath The path to the zip file to unzip.
+ * @param outputDir The path to the directory to unzip the file to.
+ * @param dirPermissionsMode The mode to set the permissions of the unzipped directory to. Defaults to `0o666` (read and write for owner, group and others).
+ * @returns A promise that resolves when the file is unzipped.
+ */
+export async function unzipFile(zipFilePath, outputDir, dirPermissionsMode = 0o666) {
+    await fs
+        .createReadStream(zipFilePath)
+        .pipe(unzipper.Extract({ path: outputDir }))
+        .promise();
+    setDirectoryPermissions(outputDir, dirPermissionsMode);
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './batch/index.js';
+export * from './files/index.js';
 export * from './lifecycle/index.js';

package/dist/index.js

@@ -1,2 +1,3 @@
 export * from './batch/index.js';
+export * from './files/index.js';
 export * from './lifecycle/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/go-utils-exec",
-	"version": "20260903.2201.22",
+	"version": "20260904.1431.46",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"
@@ -39,11 +39,14 @@
 		"@tmlmobilidade/go-types-geo": "*",
 		"@tmlmobilidade/go-types-shared": "*",
 		"@tmlmobilidade/go-utils-dates": "*",
-		"@tmlmobilidade/timer": "*"
+		"@tmlmobilidade/timer": "*",
+		"csv-parse": "7.0.2",
+		"unzipper": "0.12.5"
 	},
 	"devDependencies": {
 		"@tmlmobilidade/go-utils-tsconfig": "*",
 		"@types/node": "26.4.0",
+		"@types/unzipper": "0.10.11",
 		"resolve-tspaths": "0.8.23",
 		"tsc-watch": "7.2.1",
 		"typescript": "6.0.3"