@tmlmobilidade/go-utils-files 20260904.1059.6

package/dist/files.d.ts

@@ -0,0 +1,78 @@
+import JSZip from 'jszip';
+import { type ParseConfig } from 'papaparse';
+interface UpdateCsvFieldParams {
+    column: string;
+    csvString: string;
+    rowIndex: number;
+    value: string;
+}
+export declare class Files {
+    /**
+     * Converts a Blob to a File.
+     * @param blob The Blob object to convert.
+     * @param fileName The name of the resulting File.
+     * @returns The resulting File.
+     */
+    static blobToFile(blob: Blob, fileName: string): File;
+    /**
+     * Returns the file extension from a file name.
+     * @param fileName The name of the file.
+     * @returns The file extension.
+     * @throws Error if the file has no extension or if the extension is not supported.
+     */
+    static getFileExtension(fileName: string): string;
+    /**
+     * Gets the file extension from a MIME type.
+     * @param mimeType The MIME type to get the file extension for.
+     * @returns The file extension, or an empty string if not found.
+     */
+    static getFileExtensionFromMimeType(mimeType: string): string;
+    /**
+     * Gets the MIME type from a file extension.
+     * @param fileName The name of the file to get the MIME type for.
+     * @returns The MIME type.
+     */
+    static getMimeTypeFromFileExtension(fileName: string): string;
+    /**
+     * Reads and extracts a single file from a ZIP archive.
+     * @param zipFilePath The zip file to read from, can be a File object (browser), string path (Node.js), or URL
+     * @param fileName The name of the file to extract from the ZIP
+     * @param encoding The encoding to use when reading the file. See JSZip documentation for supported formats.
+     * @returns A Promise resolving to the file contents in the specified encoding
+     * @throws Error if the file is not found in the ZIP
+     */
+    static readFileFromZip<T extends Parameters<JSZip.JSZipObject['async']>[0]>(zipFilePath: File | string | URL, fileName: string, encoding: T): Promise<ReturnType<JSZip.JSZipObject['async']> extends Promise<infer R> ? R : never>;
+    /**
+     * Unzips a ZIP file from a File (browser), string path (Node.js), or URL.
+     * @param zipFilePath The path, URL, or File object representing the ZIP file to extract.
+     * @returns A Promise that resolves to a JSZip instance representing the unzipped contents.
+     */
+    static unzip(zipFilePath: File | string | URL): Promise<JSZip>;
+    /**
+     * Updates a CSV string with an object.
+     * @param csvString The CSV string to update
+     * @param column The column name to update
+     * @param row The row index to update
+     * @param value The value to update the column with
+     * @returns A Promise resolving to the updated CSV string
+     */
+    static updateCsvField<T>(params: UpdateCsvFieldParams[]): Promise<string>;
+    /**
+     * Parses a CSV string into an array of objects using PapaParse.
+     * @param csvString The CSV string to parse
+     * @param options Parse configuration options
+     * @param options.header Whether to interpret first row as field names. Defaults to true.
+     * @param options.skipEmptyLines Whether to skip empty lines in the CSV. Defaults to true.
+     * @param options.rest Additional PapaParse configuration options
+     * @returns Promise resolving to array of parsed objects
+     * @throws Error if parsing fails with details of parsing errors
+     */
+    static parseCsv<T>(csvString: string, { header, skipEmptyLines, ...options }: ParseConfig<T>): Promise<T[]>;
+    /**
+     * Zips multiple files into a ZIP archive.
+     * @param files An object where keys are filenames and values are either File (browser) or Buffer/Uint8Array (Node.js).
+     * @returns A Promise resolving to a Uint8Array representing the ZIP file content.
+     */
+    static zip(files: Record<string, Buffer | File | Uint8Array>): Promise<Uint8Array>;
+}
+export {};

package/dist/files.js

@@ -0,0 +1,171 @@
+/* * */
+import { mimeTypes } from '@tmlmobilidade/consts';
+import JSZip from 'jszip';
+import papaparse from 'papaparse';
+import { fetchZipFromUrl } from './helpers/fetch-zip-from-url.js';
+import { isBrowser } from './helpers/is-browser.js';
+import { normalizeFileContent } from './helpers/normalize-file-content.js';
+import { readZipFromFile } from './helpers/read-zip-from-file.js';
+/* * */
+export class Files {
+    //
+    /**
+     * Converts a Blob to a File.
+     * @param blob The Blob object to convert.
+     * @param fileName The name of the resulting File.
+     * @returns The resulting File.
+     */
+    static blobToFile(blob, fileName) {
+        return new File([blob], fileName);
+    }
+    /**
+     * Returns the file extension from a file name.
+     * @param fileName The name of the file.
+     * @returns The file extension.
+     * @throws Error if the file has no extension or if the extension is not supported.
+     */
+    static getFileExtension(fileName) {
+        // Extract the file extension from the file name.
+        const extension = fileName.split('.').pop()?.toLowerCase();
+        // Throw an error if the file has no extension
+        // or if the extension is not supported.
+        if (!extension)
+            throw new Error('File has no extension');
+        // Get the MIME type for the extension.
+        const mimeType = mimeTypes[extension];
+        // Throw an error if the extension is not supported.
+        if (!mimeType)
+            throw new Error(`Unsupported file extension: ${extension}`);
+        // Return the file extension.
+        return extension;
+    }
+    /**
+     * Gets the file extension from a MIME type.
+     * @param mimeType The MIME type to get the file extension for.
+     * @returns The file extension, or an empty string if not found.
+     */
+    static getFileExtensionFromMimeType(mimeType) {
+        if (!mimeType)
+            return '';
+        const extension = Object.keys(mimeTypes).find(key => mimeTypes[key] === mimeType);
+        if (!extension)
+            return '';
+        return extension;
+    }
+    /**
+     * Gets the MIME type from a file extension.
+     * @param fileName The name of the file to get the MIME type for.
+     * @returns The MIME type.
+     */
+    static getMimeTypeFromFileExtension(fileName) {
+        const extension = Files.getFileExtension(fileName);
+        return mimeTypes[extension];
+    }
+    /**
+     * Reads and extracts a single file from a ZIP archive.
+     * @param zipFilePath The zip file to read from, can be a File object (browser), string path (Node.js), or URL
+     * @param fileName The name of the file to extract from the ZIP
+     * @param encoding The encoding to use when reading the file. See JSZip documentation for supported formats.
+     * @returns A Promise resolving to the file contents in the specified encoding
+     * @throws Error if the file is not found in the ZIP
+     */
+    static async readFileFromZip(zipFilePath, fileName, encoding) {
+        const zip = await Files.unzip(zipFilePath);
+        const file = zip.file(fileName);
+        if (!file)
+            throw new Error(`File ${fileName} not found in the zip archive.`);
+        return await file.async(encoding);
+    }
+    /**
+     * Unzips a ZIP file from a File (browser), string path (Node.js), or URL.
+     * @param zipFilePath The path, URL, or File object representing the ZIP file to extract.
+     * @returns A Promise that resolves to a JSZip instance representing the unzipped contents.
+     */
+    static async unzip(zipFilePath) {
+        try {
+            let data = null;
+            if (isBrowser && zipFilePath instanceof File) {
+                data = await zipFilePath.arrayBuffer();
+            }
+            if (typeof zipFilePath === 'string' || zipFilePath instanceof URL) {
+                const pathOrUrl = zipFilePath.toString();
+                if (isBrowser || pathOrUrl.startsWith('http')) {
+                    data = await fetchZipFromUrl(pathOrUrl);
+                }
+                else {
+                    data = await readZipFromFile(pathOrUrl);
+                }
+            }
+            if (!data || data.byteLength === 0) {
+                throw new Error('ZIP file is empty');
+            }
+            const zip = await JSZip.loadAsync(data);
+            if (Object.keys(zip.files).length === 0) {
+                throw new Error('ZIP file contains no files');
+            }
+            return zip;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('Central Directory')) {
+                throw new Error('Invalid or corrupted ZIP file', error);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Updates a CSV string with an object.
+     * @param csvString The CSV string to update
+     * @param column The column name to update
+     * @param row The row index to update
+     * @param value The value to update the column with
+     * @returns A Promise resolving to the updated CSV string
+     */
+    static async updateCsvField(params) {
+        let csv = params[0].csvString;
+        for (const param of params) {
+            const data = await this.parseCsv(csv, { header: true });
+            const updatedData = data.map((row, index) => (index === param.rowIndex ? { ...row, [param.column]: param.value } : row));
+            csv = papaparse.unparse(updatedData, { header: true });
+        }
+        return csv;
+    }
+    /**
+     * Parses a CSV string into an array of objects using PapaParse.
+     * @param csvString The CSV string to parse
+     * @param options Parse configuration options
+     * @param options.header Whether to interpret first row as field names. Defaults to true.
+     * @param options.skipEmptyLines Whether to skip empty lines in the CSV. Defaults to true.
+     * @param options.rest Additional PapaParse configuration options
+     * @returns Promise resolving to array of parsed objects
+     * @throws Error if parsing fails with details of parsing errors
+     */
+    static async parseCsv(csvString, { header = true, skipEmptyLines = true, ...options }) {
+        const parse = papaparse.parse(csvString, { header, skipEmptyLines, ...options });
+        if (parse.errors.length > 0) {
+            throw new Error(`Failed to parse CSV: ${parse.errors.map(error => `${error.message} [${error.code}]`).join(', ')}`);
+        }
+        return parse.data;
+    }
+    /**
+     * Zips multiple files into a ZIP archive.
+     * @param files An object where keys are filenames and values are either File (browser) or Buffer/Uint8Array (Node.js).
+     * @returns A Promise resolving to a Uint8Array representing the ZIP file content.
+     */
+    static async zip(files) {
+        try {
+            const zip = new JSZip();
+            await Promise.all(Object.entries(files).map(async ([filename, content]) => {
+                const fileData = await normalizeFileContent(content);
+                zip.file(filename, fileData);
+            }));
+            const zipContent = await zip.generateAsync({ type: 'uint8array' });
+            if (!zipContent || zipContent.length === 0) {
+                throw new Error('Failed to generate ZIP: output is empty');
+            }
+            return zipContent;
+        }
+        catch (error) {
+            throw new Error(`Failed to create ZIP archive: ${error.message}`, error);
+        }
+    }
+}

package/dist/helpers/fetch-zip-from-url.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Fetches a ZIP file from a URL and returns it as an ArrayBuffer.
+ * @param url The URL of the ZIP file to fetch.
+ * @returns A Promise that resolves to an ArrayBuffer containing the ZIP file data.
+ * @throws If the HTTP request fails or returns a non-200 status code.
+ */
+export declare function fetchZipFromUrl(url: string): Promise<ArrayBuffer>;

package/dist/helpers/fetch-zip-from-url.js

@@ -0,0 +1,13 @@
+/* * */
+/**
+ * Fetches a ZIP file from a URL and returns it as an ArrayBuffer.
+ * @param url The URL of the ZIP file to fetch.
+ * @returns A Promise that resolves to an ArrayBuffer containing the ZIP file data.
+ * @throws If the HTTP request fails or returns a non-200 status code.
+ */
+export async function fetchZipFromUrl(url) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`Failed to fetch ZIP file: HTTP ${response.status} - ${response.statusText}`);
+    return await response.arrayBuffer();
+}

package/dist/helpers/get-tmp-workdir-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Gets the temporary working directory path for a given ID.
+ * @param id The ID to get the temporary working directory path for.
+ * @returns The temporary working directory path.
+ */
+export declare function getTmpWorkdirPath(id?: string, createIfNotExists?: boolean): string;

package/dist/helpers/get-tmp-workdir-path.js

@@ -0,0 +1,33 @@
+/* * */
+import { generateRandomString } from '@tmlmobilidade/strings';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isBrowser } from './is-browser.js';
+/**
+ * Gets the temporary working directory path for a given ID.
+ * @param id The ID to get the temporary working directory path for.
+ * @returns The temporary working directory path.
+ */
+export function getTmpWorkdirPath(id, createIfNotExists) {
+    //
+    if (isBrowser) {
+        throw new Error('getTmpWorkdirPath is not supported in the browser');
+    }
+    //
+    // Use the system temporary directory and create
+    // a subdirectory based on the ID, if any was provided.
+    // Otherwise, use a random ID for the subdirectory.
+    const osTmpDir = tmpdir();
+    const workdirName = id ? id : generateRandomString();
+    const workdirPath = join(osTmpDir, encodeURIComponent(workdirName));
+    //
+    // If the createIfNotExists flag is set to true,
+    // create the directory if it doesn't exist.
+    if (createIfNotExists && !fs.existsSync(workdirPath)) {
+        fs.mkdirSync(workdirPath, { recursive: true });
+    }
+    //
+    // Return the temporary working directory path.
+    return workdirPath;
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,5 @@
+export * from './fetch-zip-from-url.js';
+export * from './get-tmp-workdir-path.js';
+export * from './is-browser.js';
+export * from './normalize-file-content.js';
+export * from './read-zip-from-file.js';

package/dist/helpers/index.js

@@ -0,0 +1,5 @@
+export * from './fetch-zip-from-url.js';
+export * from './get-tmp-workdir-path.js';
+export * from './is-browser.js';
+export * from './normalize-file-content.js';
+export * from './read-zip-from-file.js';

package/dist/helpers/is-browser.d.ts

@@ -0,0 +1 @@
+export declare const isBrowser: boolean;

package/dist/helpers/is-browser.js

@@ -0,0 +1,2 @@
+/* * */
+export const isBrowser = typeof globalThis === 'object' && 'window' in globalThis;

package/dist/helpers/normalize-file-content.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Converts the input file data into an ArrayBuffer or Uint8Array suitable for JSZip.
+ * @param content A File (browser) or Buffer/Uint8Array (Node.js)
+ */
+export declare function normalizeFileContent(content: Buffer | File | Uint8Array): Promise<ArrayBuffer | Uint8Array>;

package/dist/helpers/normalize-file-content.js

@@ -0,0 +1,15 @@
+/* * */
+import { isBrowser } from './is-browser.js';
+/**
+ * Converts the input file data into an ArrayBuffer or Uint8Array suitable for JSZip.
+ * @param content A File (browser) or Buffer/Uint8Array (Node.js)
+ */
+export async function normalizeFileContent(content) {
+    if (isBrowser && content instanceof File) {
+        return await content.arrayBuffer();
+    }
+    if (content instanceof Buffer || content instanceof Uint8Array) {
+        return content;
+    }
+    throw new TypeError('Unsupported file content type for zipping.');
+}

package/dist/helpers/read-zip-from-file.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reads a ZIP file from the local filesystem and returns it as an ArrayBuffer.
+ * @param path The file system path to the ZIP file.
+ * @returns A Promise that resolves to an ArrayBuffer containing the ZIP file data.
+ * @throws If there is an error reading the file or if the function is called in a browser environment.
+ */
+export declare function readZipFromFile(path: string): Promise<ArrayBuffer>;

package/dist/helpers/read-zip-from-file.js

@@ -0,0 +1,24 @@
+/* * */
+import { isBrowser } from './is-browser.js';
+/**
+ * Reads a ZIP file from the local filesystem and returns it as an ArrayBuffer.
+ * @param path The file system path to the ZIP file.
+ * @returns A Promise that resolves to an ArrayBuffer containing the ZIP file data.
+ * @throws If there is an error reading the file or if the function is called in a browser environment.
+ */
+export async function readZipFromFile(path) {
+    //
+    if (isBrowser) {
+        throw new Error('readZipFromFile is not supported in the browser');
+    }
+    //
+    // Only require fs/promises in Node.js
+    const { readFile } = await (Function('return import("fs/promises")')());
+    try {
+        const buffer = await readFile(path);
+        return buffer.buffer;
+    }
+    catch (error) {
+        throw new Error(`Failed to read ZIP file: ${error.message}`, error);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './files.js';
+export * from './helpers/index.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './files.js';
+export * from './helpers/index.js';

package/package.json

@@ -0,0 +1,51 @@
+{
+	"name": "@tmlmobilidade/go-utils-files",
+	"version": "20260904.1059.6",
+	"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/consts": "*",
+		"@tmlmobilidade/strings": "*",
+		"jszip": "3.10.1",
+		"papaparse": "5.7.0"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/go-utils-tsconfig": "*",
+		"@types/node": "26.4.0",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"typescript": "6.0.3"
+	}
+}