@tmlmobilidade/go-utils-zip 20260914.1727.46

package/dist/get-zip-file-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 filePath The path to the `.zip` file.
+ * @returns The SHA-256 hash of the `.zip` file contents.
+ */
+export declare function getZipFileHash(filePath: string): Promise<string>;

package/dist/get-zip-file-hash.js

@@ -0,0 +1,67 @@
+/* * */
+import { getDirectoryFiles } from '@tmlmobilidade/go-utils-fs';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { unzipFile } from './unzip-file.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 filePath The path to the `.zip` file.
+ * @returns The SHA-256 hash of the `.zip` file contents.
+ */
+export async function getZipFileHash(filePath) {
+    //
+    //
+    // Initialize a new temporary directory
+    const temporaryDirectory = fs.mkdtempDisposableSync('get-zip-file-hash-');
+    try {
+        //
+        //
+        // Extract the ZIP file into the temporary directory.
+        await unzipFile(filePath, temporaryDirectory.path);
+        //
+        // Find all extracted files.
+        const sortedExtractedFilePaths = 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');
+        //
+    }
+    finally {
+        temporaryDirectory.remove();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './get-zip-file-hash.js';
+export * from './unzip-file.js';
+export * from './zip-directory.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './get-zip-file-hash.js';
+export * from './unzip-file.js';
+export * from './zip-directory.js';

package/dist/unzip-file.d.ts

@@ -0,0 +1,10 @@
+import fs from 'node:fs';
+/**
+ * Unzips a zip file into a directory using Yauzl.
+ * @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?: fs.Mode): Promise<void>;

package/dist/unzip-file.js

@@ -0,0 +1,44 @@
+/* * */
+import { setDirectoryPermissions } from '@tmlmobilidade/go-utils-fs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import yauzl from 'yauzl';
+/**
+ * Unzips a zip file into a directory using Yauzl.
+ * @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) {
+    //
+    //
+    // Create the output directory if it doesn't exist
+    if (fs.existsSync(outputDir))
+        throw new Error(`Output directory ${outputDir} already exists`);
+    fs.mkdirSync(outputDir, { recursive: true });
+    //
+    // Open the zip file
+    const zipfile = await yauzl.openPromise(zipFilePath);
+    //
+    // Iterate over each entry in the zip file
+    for await (const entry of zipfile.eachEntry()) {
+        //
+        //
+        // Directory file names end with '/'.
+        // Note that entries for directories themselves are optional.
+        // An entry's fileName implicitly requires its parent directories to exist.
+        if (entry.fileName.endsWith('/'))
+            continue;
+        //
+        // file entry
+        const readStream = await zipfile.openReadStreamPromise(entry);
+        const filePath = path.join(outputDir, entry.fileName);
+        await pipeline(readStream, fs.createWriteStream(filePath));
+    }
+    //
+    // Set the permissions of the output directory
+    setDirectoryPermissions(outputDir, dirPermissionsMode);
+}

package/dist/zip-directory.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Zips a directory into a zip file using Yazl.
+ * @param inputDir The path to the directory to zip.
+ * @param outputZipFilePath The path to the zip file to create.
+ * @returns A promise that resolves when the directory is zipped.
+ */
+export declare function zipDirectory(inputDir: string, outputZipFilePath: string): Promise<void>;

package/dist/zip-directory.js

@@ -0,0 +1,52 @@
+/* * */
+import fs from 'node:fs';
+import path from 'node:path';
+import { ZipFile } from 'yazl';
+/**
+ * Zips a directory into a zip file using Yazl.
+ * @param inputDir The path to the directory to zip.
+ * @param outputZipFilePath The path to the zip file to create.
+ * @returns A promise that resolves when the directory is zipped.
+ */
+export async function zipDirectory(inputDir, outputZipFilePath) {
+    //
+    //
+    // Check if the input directory exists
+    if (!fs.existsSync(inputDir))
+        throw new Error(`Input directory ${inputDir} does not exist`);
+    //
+    // Setup a new instance of Yazl and include all files in the input directory
+    const outputZip = new ZipFile();
+    await new Promise((resolve, reject) => {
+        try {
+            //
+            //
+            // Read the working directory contents and filter
+            // to keep only files. Throw an error if there are no files,
+            // as it would produce an invalid zip file.
+            const inputDirContents = fs.readdirSync(inputDir, { withFileTypes: true });
+            const inputDirFiles = inputDirContents.filter(file => file.isFile());
+            if (!inputDirFiles.length)
+                throw new Error('No files found in input directory');
+            //
+            // Add each file to the zip
+            for (const inputDirFile of inputDirFiles) {
+                const filePath = path.join(inputDir, inputDirFile.name);
+                outputZip.addFile(filePath, inputDirFile.name, { compress: true });
+            }
+            //
+            // Setup a write stream to the final zip file
+            outputZip.outputStream
+                .pipe(fs.createWriteStream(outputZipFilePath))
+                .on('close', resolve);
+            //
+            // Finalize the zip creation, which triggers
+            // the piping and writing process.
+            outputZip.end();
+            //
+        }
+        catch (error) {
+            reject(error);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@tmlmobilidade/go-utils-zip",
+	"version": "20260914.1727.46",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@tmlmobilidade/go-utils-fs": "*",
+		"yauzl": "3.4.0",
+		"yazl": "3.3.1"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/go-utils-tsconfig": "*",
+		"@types/node": "26.4.0",
+		"@types/yauzl": "3.4.0",
+		"@types/yazl": "3.3.1",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}