b2b-platform-utils 1.1.6 → 1.1.7

package/fileSystem.js

@@ -1,40 +1,298 @@
 'use strict';
 
-// Purpose: Simple sync file helpers that resolve relative paths from the service root (process.cwd()).
+/**
+ * @module fileSystem
+ * @description
+ * Synchronous file and media-related helpers.
+ *
+ * Responsibilities:
+ * - Safe read/write/remove operations on local filesystem.
+ * - Basic MIME / extension resolution.
+ * - Utility to build absolute media URLs based on service context.
+ *
+ * Notes:
+ * - All filesystem paths are resolved against process.cwd() unless already absolute.
+ * - Synchronous I/O will block the Node.js event loop. This is acceptable for:
+ *   - service bootstrap
+ *   - low-frequency admin/debug tasks
+ *   - cron/workers with low concurrency
+ *   It is NOT recommended in hot request/response paths.
+ */
 
 const fs = require('fs');
 const path = require('path');
+const { warningNote } = require('./logger');
+const { getValue } = require('./localCache');
 
-/** Resolve absolute path; if relative, resolve from process.cwd(). */
+// -----------------------------------------------------------------------------
+// Internal helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Resolve an absolute filesystem path. If the provided path is relative,
+ * it will be resolved against process.cwd().
+ *
+ * @param {string} fileName - Absolute or relative path.
+ * @returns {string} Absolute path.
+ */
 function resolvePath(fileName) {
-    return path.isAbsolute(fileName) ? fileName : path.resolve(process.cwd(), fileName);
+    return path.isAbsolute(fileName)
+        ? fileName
+        : path.resolve(process.cwd(), fileName);
 }
 
-module.exports = {
-    /**
-     * Save data as JSON into a file (overwrites if exists).
-     * Ensures parent directory exists.
-     */
-    saveFile: (fileName, data) => {
-        const p = resolvePath(fileName);
-        fs.mkdirSync(path.dirname(p), { recursive: true });
-        fs.writeFileSync(p, JSON.stringify(data));
-    },
-
-    /**
-     * Read text content from a file using UTF-8.
-     * Relative paths are resolved from process.cwd().
-     */
-    readFile: (fileName) => {
-        const p = resolvePath(fileName);
-        return fs.readFileSync(p, 'utf-8');
-    },
-
-    /**
-     * Remove a file from the filesystem.
-     */
-    removeFile: (fileName) => {
-        const p = resolvePath(fileName);
-        fs.unlinkSync(p);
+/**
+ * Ensure the parent directory for a given absolute file path exists.
+ *
+ * @param {string} absolutePath
+ */
+function ensureDirForFile(absolutePath) {
+    fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
+}
+
+/**
+ * Normalize file extension:
+ * - strips query string / hash fragments
+ * - lowercases the extension
+ *
+ * @param {string} filename
+ * @returns {string} extension without dot, e.g. "png"
+ */
+function extractCleanExtension(filename) {
+    // remove query/hash if passed like "avatar.png?ts=123" or "file.pdf#v2"
+    const cleanName = filename.split('?')[0].split('#')[0];
+    const parts = cleanName.split('.');
+    if (parts.length < 2) return '';
+    return parts.pop().toLowerCase();
+}
+
+// -----------------------------------------------------------------------------
+// Public API: Filesystem I/O
+// -----------------------------------------------------------------------------
+
+/**
+ * Save a plain JS value as JSON into a file (overwrites if it already exists).
+ * Ensures parent directory exists.
+ *
+ * @param {string} fileName - Target file path (absolute or relative).
+ * @param {any} data - Serializable data.
+ * @param {Object} [options]
+ * @param {number} [options.spaces=0] - JSON indentation level, e.g. 2 for pretty debug output.
+ */
+function saveFile(fileName, data, options = {}) {
+    const absPath = resolvePath(fileName);
+    ensureDirForFile(absPath);
+
+    const spaces = Number.isInteger(options.spaces) ? options.spaces : 0;
+    const json = JSON.stringify(data, null, spaces);
+
+    fs.writeFileSync(absPath, json, { encoding: 'utf-8' });
+}
+
+/**
+ * Read file content as UTF-8 text.
+ * This will throw if the file is missing or unreadable.
+ *
+ * @param {string} fileName
+ * @returns {string} File contents.
+ */
+function readFile(fileName) {
+    const absPath = resolvePath(fileName);
+    return fs.readFileSync(absPath, 'utf-8');
+}
+
+/**
+ * Read JSON file and parse it.
+ * Returns null if the file does not exist.
+ * Will throw if file exists but content is not valid JSON.
+ *
+ * @param {string} fileName
+ * @returns {any|null}
+ */
+function readJsonFile(fileName) {
+    const absPath = resolvePath(fileName);
+
+    if (!fs.existsSync(absPath)) {
+        return null;
+    }
+
+    const raw = fs.readFileSync(absPath, 'utf-8');
+    return JSON.parse(raw);
+}
+
+/**
+ * Remove a file from the filesystem if it exists.
+ * Safe no-op if file is already missing.
+ *
+ * @param {string} fileName
+ */
+function removeFile(fileName) {
+    const absPath = resolvePath(fileName);
+
+    if (!fs.existsSync(absPath)) {
+        return;
+    }
+
+    fs.unlinkSync(absPath);
+}
+
+// -----------------------------------------------------------------------------
+// Public API: MIME / extension helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Map known MIME types to file extensions.
+ * Unknown types return extension = null and also return an error message.
+ * A warning is logged for visibility.
+ *
+ * @param {string} mimetype - e.g. "image/png", "application/pdf".
+ * @returns {{ extension: string|null, error: string }}
+ */
+function getImageExtension(mimetype) {
+    let extension = null;
+    let error = '';
+
+    switch (mimetype) {
+        case 'image/png':
+            extension = 'png';
+            break;
+        case 'image/jpeg':
+            extension = 'jpeg';
+            break;
+        case 'image/jpg':
+            extension = 'jpg';
+            break;
+        case 'image/svg+xml':
+            extension = 'svg';
+            break;
+        case 'image/webp':
+            extension = 'webp';
+            break;
+        case 'image/gif':
+            extension = 'gif';
+            break;
+        case 'image/vnd.microsoft.icon':
+            extension = 'ico';
+            break;
+        case 'font/ttf':
+            extension = 'ttf';
+            break;
+        case 'text/plain':
+            extension = 'txt';
+            break;
+        case 'text/csv':
+            extension = 'csv';
+            break;
+        case 'application/pdf':
+            extension = 'pdf';
+            break;
+        case 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':
+            extension = 'xlsx';
+            break;
+        default:
+            error = `Undefined file mimetype: ${mimetype}`;
+            extension = null;
+
+            // Emit a non-fatal warning. Service can still decide what to do.
+            if (typeof warningNote === 'function') {
+                warningNote(error);
+            }
+            break;
+    }
+
+    return { extension, error };
+}
+
+/**
+ * Infer MIME type from file extension.
+ * If extension is not recognized, returns an empty string.
+ *
+ * @param {string} filename - Full filename, may contain query/hash.
+ * @returns {string} MIME type string or "" if unknown.
+ */
+function getMimeTypeByFileExtension(filename) {
+    const ext = extractCleanExtension(filename);
+
+    switch (ext) {
+        case 'png':
+            return 'image/png';
+        case 'gif':
+            return 'image/gif';
+        case 'jpeg':
+        case 'jpg':
+            return 'image/jpeg';
+        case 'webp':
+            return 'image/webp';
+        case 'ico':
+            return 'image/vnd.microsoft.icon';
+        case 'svg':
+            return 'image/svg+xml';
+        case 'csv':
+            return 'text/csv';
+        case 'txt':
+            return 'text/plain';
+        case 'xml':
+            return 'application/xml';
+        case 'pdf':
+            return 'application/pdf';
+        case 'xls':
+            return 'application/vnd.ms-excel';
+        case 'xlsx':
+            return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+        case 'doc':
+            return 'application/msword';
+        case 'docx':
+            return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+        case 'mp4':
+            return 'video/mp4';
+        default:
+            return '';
     }
+}
+
+// -----------------------------------------------------------------------------
+// Public API: URL builders
+// -----------------------------------------------------------------------------
+
+/**
+ * Build absolute URL for static/media resource exposed by the platform.
+ * Uses runtime config from localCache.
+ *
+ * Example:
+ * baseApiURL = "https://cdn.example.com"
+ * service = "avatar"
+ * instance = "user123"
+ * fileName = "profile.png"
+ *
+ * Result:
+ * "https://cdn.example.com/file/avatar/user123/profile.png"
+ *
+ * @param {string} service - Logical service name, e.g. "avatar", "cms", "game".
+ * @param {string} instance - Instance or tenant identifier.
+ * @param {string} fileName - File name including extension.
+ * @returns {string} Absolute URL.
+ */
+function getAbsoluteMediaResourceUrl(service, instance, fileName) {
+    const baseUrl = getValue('baseApiURL') || '';
+    return `${baseUrl}/file/${service}/${instance}/${fileName}`;
+}
+
+// -----------------------------------------------------------------------------
+// Exports
+// -----------------------------------------------------------------------------
+
+module.exports = {
+    // Filesystem I/O
+    resolvePath,
+    saveFile,
+    readFile,
+    readJsonFile,
+    removeFile,
+
+    // MIME helpers
+    getImageExtension,
+    getMimeTypeByFileExtension,
+
+    // URL helpers
+    getAbsoluteMediaResourceUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "b2b-platform-utils",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Shared utilities for Node.js microservices: errors map, local cache, logger, numbers, dates, filesystem, media optimization, paginator, slugger, crypto wrapper, sanitize HTML, sorting.",
   "type": "commonjs",
   "license": "KingSizer",