b2b-platform-utils 1.1.7 → 1.1.9

package/amountFormat.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * @module amountFormat
+ * @description
+ * Utility for consistent conversion between major (e.g. 17.00 EUR)
+ * and minor units (e.g. 1700 cents).
+ *
+ * All conversions are currency-aware and respect currency exponents:
+ * EUR/USD/GBP → 2 decimals, JPY → 0 decimals, KWD → 3 decimals.
+ */
+
+const { getBaseCurrency } = require('./localCache');
+
+/**
+ * Convert minor units (e.g. 1700) to major amount (e.g. 17.00)
+ *
+ * @param {number|string} amount - Minor amount in integer form.
+ * @param {string} [currency=getBaseCurrency()] - ISO 4217 currency code.
+ * @returns {number} Major amount.
+ * @throws {Error} If amount is not numeric.
+ */
+function toMajorAmount(amount, currency = getBaseCurrency()) {
+    if (amount == null) return 0;
+
+    const exponent = getCurrencyExponent(currency);
+    const num = Number(amount);
+
+    if (!Number.isFinite(num)) {
+        throw new Error('Invalid amount');
+    }
+
+    // Avoid unnecessary floating-point drift.
+    const factor = Math.pow(10, exponent);
+    const major = num / factor;
+
+    return parseFloat(major.toFixed(exponent));
+}
+
+/**
+ * Convert major amount (e.g. 17.00) to minor units (e.g. 1700)
+ *
+ * @param {number|string} amount - Major amount.
+ * @param {string} [currency=getBaseCurrency()] - ISO 4217 currency code.
+ * @returns {number} Minor amount as integer.
+ * @throws {Error} If amount is missing or invalid.
+ */
+function toMinorAmount(amount, currency = getBaseCurrency()) {
+    if (amount == null) {
+        throw new Error('Amount is required');
+    }
+
+    const exponent = getCurrencyExponent(currency);
+    const normalized = String(amount).replace(',', '.'); // support "17,5"
+    const num = Number(normalized);
+
+    if (!Number.isFinite(num)) {
+        throw new Error('Invalid amount');
+    }
+
+    const fixed = num.toFixed(exponent);
+    // Using Math.round avoids string replace for integers like 0 decimals
+    const minor = Math.round(num * Math.pow(10, exponent));
+
+    // fallback to parsed integer if rounding is not safe
+    return Number.isSafeInteger(minor)
+        ? minor
+        : parseInt(fixed.replace('.', ''), 10);
+}
+
+/**
+ * Return decimal exponent for currency.
+ *
+ * @param {string} currency - ISO 4217 currency code.
+ * @returns {number} Number of decimal places (default = 2).
+ */
+function getCurrencyExponent(currency) {
+    const map = {
+        EUR: 2,
+        USD: 2,
+        GBP: 2,
+        CHF: 2,
+        JPY: 0,
+        KWD: 3
+    };
+
+    const code = typeof currency === 'string'
+        ? currency.trim().toUpperCase()
+        : '';
+
+    return map[code] ?? 2;
+}
+
+module.exports = {
+    toMajorAmount,
+    toMinorAmount
+};

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.7",
+  "version": "1.1.9",
   "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",