@tmlmobilidade/files 20251202.1817.5

package/dist/files.d.ts

@@ -0,0 +1,64 @@
+import JSZip from 'jszip';
+import { ParseConfig } from 'papaparse';
+interface UpdateCsvFieldParams {
+    column: string;
+    csvString: string;
+    rowIndex: number;
+    value: string;
+}
+export declare class Files {
+    /**
+     * Blob to JS File
+     */
+    static blobToFile(blob: Blob, fileName: string): File;
+    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;
+    static getMimeTypeFromFileExtension(fileName: string): 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[]>;
+    /**
+     * 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>;
+    /**
+     * 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,153 @@
+/* eslint-disable @typescript-eslint/no-extraneous-class */
+/* * */
+import { fetchZipFromUrl, isBrowser, normalizeFileContent, readZipFromFile } from './utils.js';
+import { mimeTypes } from '@tmlmobilidade/consts';
+import JSZip from 'jszip';
+import papaparse from 'papaparse';
+/* * */
+export class Files {
+    //
+    /**
+     * Blob to JS File
+     */
+    static blobToFile(blob, fileName) {
+        return new File([blob], fileName);
+    }
+    static getFileExtension(fileName) {
+        const extension = fileName.split('.').pop();
+        if (!extension) {
+            throw new Error('File has no extension');
+        }
+        const mimeType = mimeTypes[extension];
+        if (!mimeType) {
+            throw new Error(`Unsupported file extension: ${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;
+    }
+    static getMimeTypeFromFileExtension(fileName) {
+        const extension = Files.getFileExtension(fileName);
+        return mimeTypes[extension];
+    }
+    /**
+     * 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;
+    }
+    /**
+     * 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 ZIP`);
+        }
+        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');
+            }
+            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 { column, rowIndex, value } = param;
+            const data = await this.parseCsv(csv, { header: true });
+            const updatedData = data.map((row, index) => (index === rowIndex ? { ...row, [column]: value } : row));
+            csv = papaparse.unparse(updatedData, { header: true });
+        }
+        return csv;
+    }
+    /**
+     * 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}`);
+        }
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/utils.d.ts

@@ -0,0 +1,20 @@
+export declare const isBrowser: boolean;
+/**
+ * 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 {Error} If the HTTP request fails or returns a non-200 status code
+ */
+export declare function fetchZipFromUrl(url: string): Promise<ArrayBuffer>;
+/**
+ * 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 {Error} If there is an error reading the file
+ */
+export declare function readZipFromFile(path: string): Promise<ArrayBuffer>;
+/**
+ * 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/utils.js

@@ -0,0 +1,47 @@
+export const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+/**
+ * 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 {Error} 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();
+}
+/**
+ * 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 {Error} If there is an error reading the file
+ */
+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 (err) {
+        throw new Error(`Failed to read ZIP file: ${err.message}`);
+    }
+}
+/**
+ * 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/package.json

@@ -0,0 +1,50 @@
+{
+	"name": "@tmlmobilidade/files",
+	"version": "20251202.1817.5",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://github.com/tmlmobilidade/go#readme",
+	"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": "*",
+		"jszip": "3.10.1",
+		"papaparse": "5.5.3"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/tsconfig": "*",
+		"@types/node": "24.10.1",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.0",
+		"typescript": "5.9.3"
+	}
+}