b2b-platform-utils 1.1.5 → 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/localCache.js

@@ -6,6 +6,7 @@
  * Process-scoped in-memory key-value store for configuration.
  * - Backward compatible with existing API surface.
  * - Adds currency helpers with explicit opt-in ENV fallback.
+ * - Provides default GEO and Locale helpers for runtime consumers.
  *
  * Design goals:
  * 1) No side effects on import (ENV is read lazily, only if enabled).
@@ -27,6 +28,9 @@ let bufferChunkSize = 512000;
 /** @type {string} */
 const GEO_DEFAULT = 'WW';
 
+/** @type {string} */
+const LOCALE_DEFAULT = 'en-US';
+
 /** @type {boolean} */
 let envBaseCurrencyFallbackEnabled = false; // opt-in per process
 
@@ -46,6 +50,7 @@ function ensureCommonBag() {
 /**
  * Normalize to a 3-letter uppercase currency code.
  * Returns null if invalid.
+ *
  * @param {unknown} value
  * @returns {string|null}
  */
@@ -59,6 +64,7 @@ function normalizeCurrencyCode(value) {
 
 /**
  * Set a top-level key in the cache.
+ *
  * @param {string} key
  * @param {any} value
  */
@@ -68,6 +74,7 @@ function setValue(key, value) {
 
 /**
  * Get a top-level value from the cache.
+ *
  * @param {string} key
  * @returns {any|null}
  */
@@ -79,6 +86,7 @@ function getValue(key) {
 
 /**
  * Shallow-merge a config object into the cache.
+ *
  * @param {Record<string, any>} data
  */
 function applyConfig(data) {
@@ -91,6 +99,7 @@ function applyConfig(data) {
 
 /**
  * Return a direct reference to the whole cache (mutable).
+ *
  * @returns {Record<string, any>}
  */
 function getData() {
@@ -101,6 +110,7 @@ function getData() {
 
 /**
  * Return current microservice key.
+ *
  * @returns {string}
  */
 function getService() {
@@ -109,6 +119,7 @@ function getService() {
 
 /**
  * Override microservice key at runtime.
+ *
  * @param {string} key
  */
 function setService(key) {
@@ -119,6 +130,7 @@ function setService(key) {
 
 /**
  * Get configured buffer chunk size.
+ *
  * @returns {number}
  */
 function getBufferChunkSize() {
@@ -128,6 +140,7 @@ function getBufferChunkSize() {
 /**
  * Initialize environment/customer from process params.
  * Kept for compatibility with existing bootstrap flows.
+ *
  * @param {string[]} params
  */
 function parseInitConfig(params) {
@@ -139,6 +152,7 @@ function parseInitConfig(params) {
 
 /**
  * Return the "common" bag snapshot ({} if missing).
+ *
  * @returns {Record<string, any>}
  */
 function getCommonValue() {
@@ -151,16 +165,28 @@ function getCommonValue() {
 
 /**
  * Read GEODefault from "common" or return fallback.
+ *
  * @returns {string}
  */
 function getDefaultGEO() {
     return getValue('common')?.GEODefault || GEO_DEFAULT;
 }
 
+/**
+ * Read LocaleDefault from "common" or return fallback.
+ * Locale codes must follow the pattern: en-US, de-DE, pt-BR etc.
+ *
+ * @returns {string}
+ */
+function getDefaultLocale() {
+    return getValue('common')?.LocaleDefault || LOCALE_DEFAULT;
+}
+
 /**
  * Enable or disable ENV fallback for BaseCurrency.
  * When enabled and "common.BaseCurrency" is not set,
  * getBaseCurrency() will use process.env.BASE_CURRENCY.
+ *
  * @param {boolean} enabled
  */
 function enableEnvBaseCurrencyFallback(enabled = true) {
@@ -170,6 +196,7 @@ function enableEnvBaseCurrencyFallback(enabled = true) {
 /**
  * Get BaseCurrency from "common", otherwise (optionally) from ENV.
  * Returns null if nothing is set or valid.
+ *
  * @returns {string|null}
  */
 function getBaseCurrency() {
@@ -190,6 +217,7 @@ function getBaseCurrency() {
 
 /**
  * Explicitly set BaseCurrency into the "common" bag.
+ *
  * @param {string} code - 3-letter code, e.g., "USD", "EUR", "GBP".
  * @throws {Error} If code is invalid.
  */
@@ -222,6 +250,7 @@ module.exports = {
 
     // Domain helpers
     getDefaultGEO,
+    getDefaultLocale,
 
     // Currency helpers
     getBaseCurrency,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "b2b-platform-utils",
-  "version": "1.1.5",
+  "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",