b2b-platform-utils 1.1.1 → 1.1.2

package/localCache.js

@@ -1,34 +1,115 @@
 'use strict';
 
-// Purpose: Lightweight in-memory key-value store scoped to the running process.
-// Note: Added setService(key) to allow passing microservice key without breaking existing API.
+/**
+ * @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.
+ *
+ * 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.
+ */
 
+// ---- Internal state ---------------------------------------------------------
+
+/** @type {Record<string, any>} */
 let cacheData = {};
+
+/** @type {string} */
 let serviceKey = 'notification';
+
+/** @type {number} */
 let bufferChunkSize = 512000;
+
+/** @type {string} */
 const GEO_DEFAULT = 'WW';
 
+/** @type {boolean} */
+let envBaseCurrencyFallbackEnabled = false; // opt-in per process
+
+// ---- Utilities --------------------------------------------------------------
+
+/**
+ * Ensure the "common" bag exists and return it by reference.
+ * @returns {Record<string, any>}
+ */
+function ensureCommonBag() {
+    if (!cacheData.common || typeof cacheData.common !== 'object') {
+        cacheData.common = {};
+    }
+    return cacheData.common;
+}
+
+/**
+ * Normalize to a 3-letter uppercase currency code.
+ * Returns null if invalid.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+function normalizeCurrencyCode(value) {
+    if (typeof value !== 'string') return null;
+    const code = value.trim().toUpperCase();
+    return /^[A-Z]{3}$/.test(code) ? code : null;
+}
+
+// ---- Public API: KV ---------------------------------------------------------
+
+/**
+ * Set a top-level key in the cache.
+ * @param {string} key
+ * @param {any} value
+ */
 function setValue(key, value) {
     cacheData[key] = value;
 }
 
+/**
+ * Get a top-level value from the cache.
+ * @param {string} key
+ * @returns {any|null}
+ */
 function getValue(key) {
-    return cacheData[key] || null;
+    return Object.prototype.hasOwnProperty.call(cacheData, key)
+        ? cacheData[key]
+        : null;
 }
 
-function getCommonValue() {
-    return cacheData['common'] || {};
+/**
+ * Shallow-merge a config object into the cache.
+ * @param {Record<string, any>} data
+ */
+function applyConfig(data) {
+    for (const k in data) {
+        if (Object.prototype.hasOwnProperty.call(data, k)) {
+            setValue(k, data[k]);
+        }
+    }
+}
+
+/**
+ * Return a direct reference to the whole cache (mutable).
+ * @returns {Record<string, any>}
+ */
+function getData() {
+    return cacheData;
 }
 
+// ---- Public API: service/meta ----------------------------------------------
+
 /**
  * Return current microservice key.
+ * @returns {string}
  */
 function getService() {
     return serviceKey;
 }
 
 /**
- * Allow overriding the microservice key at runtime (non-breaking addition).
+ * Override microservice key at runtime.
+ * @param {string} key
  */
 function setService(key) {
     if (typeof key === 'string' && key.length) {
@@ -36,12 +117,18 @@ function setService(key) {
     }
 }
 
+/**
+ * Get configured buffer chunk size.
+ * @returns {number}
+ */
 function getBufferChunkSize() {
     return bufferChunkSize;
 }
 
 /**
- * Initialize environment/customer from process params (kept as-is).
+ * Initialize environment/customer from process params.
+ * Kept for compatibility with existing bootstrap flows.
+ * @param {string[]} params
  */
 function parseInitConfig(params) {
     const environment = params[2];
@@ -51,37 +138,93 @@ function parseInitConfig(params) {
 }
 
 /**
- * Shallow-apply a config object into the cache.
+ * Return the "common" bag snapshot ({} if missing).
+ * @returns {Record<string, any>}
  */
-function applyConfig(data) {
-    for (const i in data) {
-        setValue(i, data[i]);
-    }
+function getCommonValue() {
+    return cacheData.common && typeof cacheData.common === 'object'
+        ? cacheData.common
+        : {};
 }
 
+// ---- Public API: domain helpers --------------------------------------------
+
 /**
- * Return the whole cache snapshot (by reference).
+ * Read GEODefault from "common" or return fallback.
+ * @returns {string}
  */
-function getData() {
-    return cacheData;
+function getDefaultGEO() {
+    return getValue('common')?.GEODefault || GEO_DEFAULT;
 }
 
 /**
- * Read GEODefault from "common" bag or return fallback.
+ * 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 getDefaultGEO() {
-    return getValue('common')?.GEODefault || GEO_DEFAULT;
+function enableEnvBaseCurrencyFallback(enabled = true) {
+    envBaseCurrencyFallbackEnabled = Boolean(enabled);
+}
+
+/**
+ * Get BaseCurrency from "common", otherwise (optionally) from ENV.
+ * Returns null if nothing is set or valid.
+ * @returns {string|null}
+ */
+function getBaseCurrency() {
+    // 1) Primary source: "common.BaseCurrency"
+    const fromCommon = getValue('common')?.BaseCurrency;
+    const normalizedCommon = normalizeCurrencyCode(fromCommon);
+    if (normalizedCommon) return normalizedCommon;
+
+    // 2) Optional fallback: process.env.BASE_CURRENCY (lazy read)
+    if (envBaseCurrencyFallbackEnabled) {
+        const normalizedEnv = normalizeCurrencyCode(process.env.BASE_CURRENCY);
+        if (normalizedEnv) return normalizedEnv;
+    }
+
+    // 3) Nothing found
+    return null;
+}
+
+/**
+ * Explicitly set BaseCurrency into the "common" bag.
+ * @param {string} code - 3-letter code, e.g., "USD", "EUR", "GBP".
+ * @throws {Error} If code is invalid.
+ */
+function setBaseCurrency(code) {
+    const normalized = normalizeCurrencyCode(code);
+    if (!normalized) {
+        throw new Error(
+            'Invalid currency code. Expected a 3-letter uppercase code like "USD", "EUR", or "GBP".'
+        );
+    }
+    const common = ensureCommonBag();
+    common.BaseCurrency = normalized;
 }
 
+// ---- Exports ---------------------------------------------------------------
+
 module.exports = {
+    // KV
     setValue,
     getValue,
-    parseInitConfig,
     applyConfig,
     getData,
+
+    // Service/meta
     getService,
     setService,
     getBufferChunkSize,
+    parseInitConfig,
+    getCommonValue,
+
+    // Domain helpers
     getDefaultGEO,
-    getCommonValue
+
+    // Currency helpers
+    getBaseCurrency,
+    setBaseCurrency,
+    enableEnvBaseCurrencyFallback
 };

package/package.json

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