b2b-platform-utils 1.1.6 → 1.1.8

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

@@ -4,17 +4,24 @@
  * @module inMemoryConfig
  * @description
  * 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.
+ *
+ * Highlights:
+ * - Safe in-memory KV for runtime config/state.
+ * - "common" bag is the canonical place for cross-service shared config
+ *   (locale, currency, GEO, etc.).
+ * - Optional ENV fallback for BaseCurrency.
+ * - Includes service-level tuning constants like bufferChunkSize,
+ *   defaultLimit, and RPC wait thresholds.
  *
  * Design goals:
- * 1) No side effects on import (ENV is read lazily, only if enabled).
- * 2) "Common" bag is the single source of truth for cross-cutting config.
- * 3) Services that do NOT use base currency remain unaffected by ENV.
+ * 1) No side effects on import. ENV is only read lazily and only if enabled.
+ * 2) Service can identify itself at runtime via setService().
+ * 3) Callers can safely read sane defaults (e.g. en-US, USD, WW).
  */
 
-// ---- Internal state ---------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Internal state
+// -----------------------------------------------------------------------------
 
 /** @type {Record<string, any>} */
 let cacheData = {};
@@ -23,7 +30,13 @@ let cacheData = {};
 let serviceKey = 'not_set_service';
 
 /** @type {number} */
-let bufferChunkSize = 512000;
+const bufferChunkSize = 512000;
+
+/** @type {number} */
+const defaultLimit = 30;
+
+/** @type {number} */
+const RPC_WAIT_FOR_READY = 2000;
 
 /** @type {string} */
 const GEO_DEFAULT = 'WW';
@@ -34,10 +47,17 @@ const LOCALE_DEFAULT = 'en-US';
 /** @type {boolean} */
 let envBaseCurrencyFallbackEnabled = false; // opt-in per process
 
-// ---- Utilities --------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Internal utilities
+// -----------------------------------------------------------------------------
 
 /**
  * Ensure the "common" bag exists and return it by reference.
+ * This is the shared namespace for cross-cutting runtime config such as:
+ * - GEODefault
+ * - LocaleDefault
+ * - BaseCurrency
+ *
  * @returns {Record<string, any>}
  */
 function ensureCommonBag() {
@@ -49,7 +69,7 @@ function ensureCommonBag() {
 
 /**
  * Normalize to a 3-letter uppercase currency code.
- * Returns null if invalid.
+ * Returns null if the code is missing or invalid.
  *
  * @param {unknown} value
  * @returns {string|null}
@@ -60,7 +80,9 @@ function normalizeCurrencyCode(value) {
     return /^[A-Z]{3}$/.test(code) ? code : null;
 }
 
-// ---- Public API: KV ---------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Public API: KV
+// -----------------------------------------------------------------------------
 
 /**
  * Set a top-level key in the cache.
@@ -74,6 +96,7 @@ function setValue(key, value) {
 
 /**
  * Get a top-level value from the cache.
+ * Returns null if the key is not present.
  *
  * @param {string} key
  * @returns {any|null}
@@ -86,6 +109,7 @@ function getValue(key) {
 
 /**
  * Shallow-merge a config object into the cache.
+ * Keys in `data` override current values.
  *
  * @param {Record<string, any>} data
  */
@@ -99,6 +123,7 @@ function applyConfig(data) {
 
 /**
  * Return a direct reference to the whole cache (mutable).
+ * This is useful for diagnostics, admin endpoints, etc.
  *
  * @returns {Record<string, any>}
  */
@@ -106,10 +131,13 @@ function getData() {
     return cacheData;
 }
 
-// ---- Public API: service/meta ----------------------------------------------
+// -----------------------------------------------------------------------------
+// Public API: service/meta
+// -----------------------------------------------------------------------------
 
 /**
- * Return current microservice key.
+ * Return the current microservice key.
+ * Example: "gateway", "cms", "analytics".
  *
  * @returns {string}
  */
@@ -118,7 +146,8 @@ function getService() {
 }
 
 /**
- * Override microservice key at runtime.
+ * Set the current microservice key at runtime.
+ * Should typically be called once during bootstrap of each service.
  *
  * @param {string} key
  */
@@ -130,6 +159,7 @@ function setService(key) {
 
 /**
  * Get configured buffer chunk size.
+ * Used in streaming / chunked payload logic.
  *
  * @returns {number}
  */
@@ -138,8 +168,28 @@ function getBufferChunkSize() {
 }
 
 /**
- * Initialize environment/customer from process params.
- * Kept for compatibility with existing bootstrap flows.
+ * Get default "limit" value for list/pagination endpoints.
+ *
+ * @returns {number}
+ */
+function getDefaultLimit() {
+    return defaultLimit;
+}
+
+/**
+ * Get default gRPC "wait for ready" timeout in milliseconds.
+ * Used by clients before marking remote service as unavailable.
+ *
+ * @returns {number}
+ */
+function getRPCWaitForReady() {
+    return RPC_WAIT_FOR_READY;
+}
+
+/**
+ * Initialize environment/customer from process startup params.
+ * Kept for compatibility with legacy bootstrap flows where
+ * process.argv-like arrays are passed in.
  *
  * @param {string[]} params
  */
@@ -151,7 +201,8 @@ function parseInitConfig(params) {
 }
 
 /**
- * Return the "common" bag snapshot ({} if missing).
+ * Return a plain snapshot of the "common" bag,
+ * or {} if it is not yet defined.
  *
  * @returns {Record<string, any>}
  */
@@ -161,10 +212,13 @@ function getCommonValue() {
         : {};
 }
 
-// ---- Public API: domain helpers --------------------------------------------
+// -----------------------------------------------------------------------------
+// Public API: domain helpers (locale / geo / currency)
+// -----------------------------------------------------------------------------
 
 /**
  * Read GEODefault from "common" or return fallback.
+ * GEO codes usually look like "WW", "EU", "US", etc.
  *
  * @returns {string}
  */
@@ -174,7 +228,7 @@ function getDefaultGEO() {
 
 /**
  * Read LocaleDefault from "common" or return fallback.
- * Locale codes must follow the pattern: en-US, de-DE, pt-BR etc.
+ * Locale codes must follow the pattern en-US, de-DE, pt-BR, etc.
  *
  * @returns {string}
  */
@@ -184,8 +238,12 @@ function getDefaultLocale() {
 
 /**
  * Enable or disable ENV fallback for BaseCurrency.
- * When enabled and "common.BaseCurrency" is not set,
- * getBaseCurrency() will use process.env.BASE_CURRENCY.
+ * When enabled AND "common.BaseCurrency" is not set,
+ * getBaseCurrency() will try process.env.BASE_CURRENCY.
+ *
+ * This allows a service to say:
+ *  - "I understand base currency matters to me"
+ *  - "If config is missing, read from ENV"
  *
  * @param {boolean} enabled
  */
@@ -194,8 +252,10 @@ function enableEnvBaseCurrencyFallback(enabled = true) {
 }
 
 /**
- * Get BaseCurrency from "common", otherwise (optionally) from ENV.
- * Returns null if nothing is set or valid.
+ * Get BaseCurrency from "common", or (optionally) from ENV.
+ * Returns null if nothing valid is provided.
+ *
+ * Expected values: "USD", "EUR", "GBP", "JPY", etc.
  *
  * @returns {string|null}
  */
@@ -216,9 +276,10 @@ function getBaseCurrency() {
 }
 
 /**
- * Explicitly set BaseCurrency into the "common" bag.
+ * Set BaseCurrency into the "common" bag explicitly.
+ * Will throw if code is not a valid 3-letter currency code.
  *
- * @param {string} code - 3-letter code, e.g., "USD", "EUR", "GBP".
+ * @param {string} code - 3-letter code, e.g. "USD", "EUR", "GBP".
  * @throws {Error} If code is invalid.
  */
 function setBaseCurrency(code) {
@@ -232,10 +293,12 @@ function setBaseCurrency(code) {
     common.BaseCurrency = normalized;
 }
 
-// ---- Exports ---------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Exports
+// -----------------------------------------------------------------------------
 
 module.exports = {
-    // KV
+    // KV helpers
     setValue,
     getValue,
     applyConfig,
@@ -245,6 +308,8 @@ module.exports = {
     getService,
     setService,
     getBufferChunkSize,
+    getDefaultLimit,
+    getRPCWaitForReady,
     parseInitConfig,
     getCommonValue,
 

package/package.json

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