core-services-sdk 1.3.22 → 1.3.24

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.22",
+  "version": "1.3.24",
   "main": "src/index.js",
   "type": "module",
+  "types": "types/index.d.ts",
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "test": "vitest run --coverage",
     "format": "prettier --write .",
-    "bump": "node ./scripts/bump-version.js"
+    "bump": "node ./scripts/bump-version.js",
+    "build:types": "tsc --declaration --allowJs --emitDeclarationOnly --outDir types ./src/index.js"
   },
   "repository": {
     "type": "git",
@@ -45,6 +47,7 @@
     "eslint-plugin-prettier": "^5.5.1",
     "path": "^0.12.7",
     "prettier": "^3.6.2",
+    "typescript": "^5.9.2",
     "url": "^0.11.4",
     "vitest": "^3.2.4"
   }

package/src/core/index.js

@@ -5,3 +5,4 @@ export * from './normalize-min-max.js'
 export * from './normalize-to-array.js'
 export * from './combine-unique-arrays.js'
 export * from './normalize-phone-number.js'
+export * from './normalize-premitives-types-or-default.js'

package/src/core/normalize-premitives-types-or-default.js

@@ -0,0 +1,215 @@
+/**
+ * Normalize Utilities
+ *
+ * Small helpers to guarantee stable, predictable values from user/config inputs.
+ * When an incoming value is missing, malformed, or in a different-but-supported
+ * representation (e.g., number/boolean as string), these utilities either accept
+ * it (after safe normalization) or return a default you control.
+ *
+ * Design highlights:
+ * - Keep call sites compact and intention-revealing.
+ * - Be strict for strings (no implicit type coercion).
+ * - Be permissive for number/boolean when the input is a string in an accepted form.
+ * - Fast, side-effect free, no deep cloning — values are returned by reference when valid.
+ */
+
+/**
+ * Generic predicate-based normalization.
+ *
+ * Purpose:
+ *  Ensure a value conforms to a caller-provided predicate; otherwise return a provided default.
+ *  Useful when you need a single reusable pattern for custom shapes or policies
+ *  (e.g., "must be a non-empty array of strings", "must be a plain object", etc.).
+ *
+ * Behavior:
+ *  - Calls `isValid(value)`.
+ *  - If the predicate returns true → returns `value` (as-is).
+ *  - Otherwise → returns `defaultValue` (as-is).
+ *
+ * Performance & Safety:
+ *  - O(1) aside from your predicate cost.
+ *  - No cloning or sanitization is performed.
+ *  - Ensure `isValid` is pure and fast; avoid throwing inside it.
+ *
+ * @template T
+ * @param {any} value
+ *   Candidate input to validate.
+ * @param {(v:any)=>boolean} isValid
+ *   Validation predicate. Return true iff the input is acceptable.
+ * @param {T} defaultValue
+ *   Fallback to return when `value` fails validation.
+ * @returns {T}
+ *   The original `value` when valid; otherwise `defaultValue`.
+ *
+ * @example
+ * // Ensure a finite number
+ * normalizeOrDefault(5, v => typeof v === 'number' && Number.isFinite(v), 0) // → 5
+ * normalizeOrDefault('x', v => typeof v === 'number', 0)                     // → 0
+ *
+ * @example
+ * // Ensure an object (non-null, non-array)
+ * const cfg = normalizeOrDefault(
+ *   maybeCfg,
+ *   v => v && typeof v === 'object' && !Array.isArray(v),
+ *   {}
+ * )
+ */
+export function normalizeOrDefault(value, isValid, defaultValue) {
+  return isValid(value) ? value : defaultValue
+}
+
+/**
+ * Normalize a value to a non-empty, trimmed string; otherwise return a default (also trimmed).
+ *
+ * Purpose:
+ *  Guarantee that downstream code receives a usable, non-empty string
+ *  without performing implicit type coercion.
+ *
+ * Acceptance Criteria:
+ *  - Accept only actual strings whose `trim()` length is > 0.
+ *  - Return `value.trim()` when valid.
+ *  - Otherwise return `defaultValue.trim()`.
+ *
+ * Why strict for strings?
+ *  - Silent coercion from non-strings to string can hide bugs.
+ *  - If you need to stringify other types, do it explicitly at the call site.
+ *
+ * Edge Cases:
+ *  - If `defaultValue` is empty or whitespace-only, the function returns an empty string.
+ *    Prefer providing a meaningful, non-empty default for clarity.
+ *
+ * @param {any} value
+ *   Candidate to normalize (must be a string to be accepted).
+ * @param {string} defaultValue
+ *   Fallback used when `value` is not a non-empty string. Will be `trim()`ed.
+ * @returns {string}
+ *   A trimmed non-empty string when `value` is valid; otherwise `defaultValue.trim()`.
+ *
+ * @example
+ * normalizeStringOrDefault('  user-roles-management:edit  ', 'fallback')
+ * // → 'user-roles-management:edit'
+ *
+ * @example
+ * normalizeStringOrDefault('', 'user-roles-management:edit')
+ * // → 'user-roles-management:edit'
+ *
+ * @example
+ * normalizeStringOrDefault(42, 'user-roles-management:edit')
+ * // → 'user-roles-management:edit'
+ */
+export function normalizeStringOrDefault(value, defaultValue) {
+  const def = typeof defaultValue === 'string' ? defaultValue.trim() : ''
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (trimmed.length > 0) {
+      return trimmed
+    }
+  }
+  return def
+}
+
+/**
+ * Normalize a value to a valid number (with safe string coercion); otherwise return a default.
+ *
+ * Purpose:
+ *  Accept numeric inputs that may arrive as strings (e.g., from env vars or config files)
+ *  while keeping semantics explicit and predictable.
+ *
+ * Acceptance Criteria:
+ *  - Accepts finite numbers (`typeof value === 'number' && Number.isFinite(value)`).
+ *  - Accepts strings that become a finite number via `Number(trimmed)`.
+ *    Examples: "42", "  3.14 ", "1e3", "-7", "0x10" (JS Number semantics).
+ *  - Rejects non-numeric strings (e.g., "", "   ", "abc") and non-number types.
+ *  - Returns `defaultValue` when not acceptable.
+ *
+ * Parsing Semantics:
+ *  - Uses `Number(s)` which requires the whole trimmed string to be numeric.
+ *  - Honors JavaScript numeric literal rules (including hex and scientific notation).
+ *  - If you want base-10 only or looser parsing, do it explicitly before calling.
+ *
+ * @param {any} value
+ *   Candidate to normalize (number or numeric string).
+ * @param {number} defaultValue
+ *   Fallback used when `value` is neither a finite number nor a numeric string.
+ * @returns {number}
+ *   A finite number derived from `value`, or `defaultValue`.
+ *
+ * @example
+ * normalizeNumberOrDefault(42, 0)       // → 42
+ * normalizeNumberOrDefault(' 3.14 ', 0) // → 3.14
+ * normalizeNumberOrDefault('1e3', 0)    // → 1000
+ * normalizeNumberOrDefault('-7', 0)     // → -7
+ *
+ * @example
+ * normalizeNumberOrDefault('abc', 7)    // → 7
+ * normalizeNumberOrDefault(NaN, 7)      // → 7
+ * normalizeNumberOrDefault({}, 7)       // → 7
+ */
+export function normalizeNumberOrDefault(value, defaultValue) {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value
+  }
+  if (typeof value === 'string') {
+    const s = value.trim()
+    if (s.length > 0) {
+      const n = Number(s)
+      if (Number.isFinite(n)) {
+        return n
+      }
+    }
+  }
+  return defaultValue
+}
+
+/**
+ * Normalize a value to a boolean (with "true"/"false" string support); otherwise return a default.
+ *
+ * Purpose:
+ *  Stabilize feature flags and binary config values that might be provided as either booleans
+ *  or as canonical strings.
+ *
+ * Acceptance Criteria:
+ *  - Accepts actual booleans (`true` / `false`) → returned as-is.
+ *  - Accepts strings equal to "true" or "false" (case-insensitive, trimmed).
+ *    "true"  → true
+ *    "false" → false
+ *  - Rejects other strings ("yes", "1", "0", etc.) and other types → returns `defaultValue`.
+ *
+ * Rationale:
+ *  - Limiting string forms to the canonical words avoids accidental truthiness/falseyness.
+ *  - If you need to accept "1"/"0" or other variants, coerce at the call site so intent is explicit.
+ *
+ * @param {any} value
+ *   Candidate to normalize (boolean or "true"/"false" string).
+ * @param {boolean} defaultValue
+ *   Fallback used when `value` is neither a boolean nor an accepted string form.
+ * @returns {boolean}
+ *   A boolean derived from `value`, or `defaultValue`.
+ *
+ * @example
+ * normalizeBooleanOrDefault(true,  false) // → true
+ * normalizeBooleanOrDefault(false, true)  // → false
+ *
+ * @example
+ * normalizeBooleanOrDefault('true',  false) // → true
+ * normalizeBooleanOrDefault(' FALSE ', true) // → false
+ *
+ * @example
+ * normalizeBooleanOrDefault('yes',  false) // → false  (rejected → default)
+ * normalizeBooleanOrDefault(1,      true)  // → true   (rejected → default)
+ */
+export function normalizeBooleanOrDefault(value, defaultValue) {
+  if (typeof value === 'boolean') {
+    return value
+  }
+  if (typeof value === 'string') {
+    const s = value.trim().toLowerCase()
+    if (s === 'true') {
+      return true
+    }
+    if (s === 'false') {
+      return false
+    }
+  }
+  return defaultValue
+}

package/src/index.js

@@ -8,3 +8,4 @@ export * from './logger/index.js'
 export * from './mailer/index.js'
 export * from './rabbit-mq/index.js'
 export * from './templates/index.js'
+export * from './util/index.js'

package/src/util/index.js

@@ -0,0 +1,12 @@
+import { mask, maskSingle } from './mask-sensitive.js'
+
+/**
+ * @namespace util
+ * Common utility functions.
+ */
+export const util = {
+  mask,
+  maskSingle,
+}
+
+export { mask, maskSingle }

package/src/util/mask-sensitive.js

@@ -0,0 +1,78 @@
+/**
+ * Mask middle of a primitive value while keeping left/right edges.
+ * @param {string|number|boolean|null|undefined} value
+ * @param {string} [fill='•']
+ * @param {number} [maskLen=3]
+ * @param {number} [left=4]
+ * @param {number} [right=4]
+ * @returns {string}
+ */
+export const maskSingle = (
+  value,
+  fill = '•',
+  maskLen = 3,
+  left = 4,
+  right = 4,
+) => {
+  if (value == null) {
+    return ''
+  }
+  const str = String(value)
+  if (str.length === 0) {
+    return ''
+  }
+  const m = Math.max(1, maskLen)
+
+  if (str.length <= left + right) {
+    if (str.length === 1) {
+      return fill
+    }
+    if (str.length === 2) {
+      return str[0] + fill.repeat(2) // "ab" -> "a••"
+    }
+    return str.slice(0, 1) + fill.repeat(m) + str.slice(-1)
+  }
+
+  return str.slice(0, left) + fill.repeat(m) + str.slice(-right)
+}
+
+/**
+ * Recursively mask values in strings, numbers, booleans, arrays, and objects.
+ * @param {string|number|boolean|Array|Object|null|undefined} value
+ * @param {string} [fill='•']
+ * @param {number} [maskLen=3]
+ * @param {number} [left=4]
+ * @param {number} [right=4]
+ * @returns {string|Array|Object}
+ */
+export const mask = (value, fill = '•', maskLen = 3, left = 4, right = 4) => {
+  const type = typeof value
+
+  if (value instanceof Date) {
+    const isoDate = value.toISOString()
+    return maskSingle(isoDate, '', isoDate.length, 0, 0)
+  }
+
+  if (value == null || (value && ['string', 'number'].includes(type))) {
+    return maskSingle(value, fill, maskLen, left, right)
+  }
+
+  if (type === 'boolean') {
+    return maskSingle(value, '', 0, 0, 0)
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((aValue) => mask(aValue, fill, maskLen, left, right))
+  }
+
+  if (typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([prop, propValue]) => [
+        prop,
+        mask(propValue, fill, maskLen, left, right),
+      ]),
+    )
+  }
+
+  return value
+}

package/tests/core/normalize-premitives-types-or-default.unit.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  normalizeOrDefault,
+  normalizeStringOrDefault,
+  normalizeNumberOrDefault,
+  normalizeBooleanOrDefault,
+} from '../../src/core/normalize-premitives-types-or-default.js'
+
+describe('normalizeOrDefault (generic)', () => {
+  it('returns value if predicate is true', () => {
+    const out = normalizeOrDefault(5, (v) => typeof v === 'number', 0)
+    expect(out).toBe(5)
+  })
+  it('returns default if predicate is false', () => {
+    const out = normalizeOrDefault('x', (v) => typeof v === 'number', 0)
+    expect(out).toBe(0)
+  })
+})
+
+describe('normalizeStringOrDefault (strict, no coercion)', () => {
+  it('keeps a non-empty trimmed string', () => {
+    expect(normalizeStringOrDefault('  hello  ', 'fallback')).toBe('hello')
+  })
+  it('returns default for empty / whitespace-only', () => {
+    expect(normalizeStringOrDefault('', 'fallback')).toBe('fallback')
+    expect(normalizeStringOrDefault('   ', 'fallback')).toBe('fallback')
+  })
+  it('returns default for non-strings', () => {
+    expect(normalizeStringOrDefault(123, 'fallback')).toBe('fallback')
+    expect(normalizeStringOrDefault(null, 'fallback')).toBe('fallback')
+  })
+  it('trims default defensively', () => {
+    expect(normalizeStringOrDefault('', '  fallback  ')).toBe('fallback')
+  })
+})
+
+describe('normalizeNumberOrDefault (coercive for strings)', () => {
+  it('keeps valid number', () => {
+    expect(normalizeNumberOrDefault(42, 0)).toBe(42)
+  })
+  it('coerces valid numeric string', () => {
+    expect(normalizeNumberOrDefault('42', 0)).toBe(42)
+    expect(normalizeNumberOrDefault('  3.14 ', 0)).toBe(3.14)
+    expect(normalizeNumberOrDefault('1e3', 0)).toBe(1000)
+    expect(normalizeNumberOrDefault('-7', 0)).toBe(-7)
+  })
+  it('returns default for invalid number inputs', () => {
+    expect(normalizeNumberOrDefault(NaN, 7)).toBe(7)
+    expect(normalizeNumberOrDefault('   ', 7)).toBe(7)
+    expect(normalizeNumberOrDefault('abc', 7)).toBe(7)
+    expect(normalizeNumberOrDefault({}, 7)).toBe(7)
+  })
+})
+
+describe('normalizeBooleanOrDefault (coercive for "true"/"false" strings)', () => {
+  it('keeps actual booleans', () => {
+    expect(normalizeBooleanOrDefault(true, false)).toBe(true)
+    expect(normalizeBooleanOrDefault(false, true)).toBe(false)
+  })
+  it('coerces "true"/"false" strings (case-insensitive)', () => {
+    expect(normalizeBooleanOrDefault('true', false)).toBe(true)
+    expect(normalizeBooleanOrDefault('FALSE', true)).toBe(false)
+    expect(normalizeBooleanOrDefault('  TrUe  ', false)).toBe(true)
+  })
+  it('returns default for other strings / types', () => {
+    expect(normalizeBooleanOrDefault('yes', false)).toBe(false)
+    expect(normalizeBooleanOrDefault('0', true)).toBe(true)
+    expect(normalizeBooleanOrDefault(1, false)).toBe(false)
+    expect(normalizeBooleanOrDefault(null, true)).toBe(true)
+  })
+})

package/tests/rabbit-mq/rabbit-mq.test.js

@@ -22,6 +22,7 @@ describe('RabbitMQ SDK', () => {
   let received = null
 
   beforeAll(async () => {
+    // @ts-ignore
     sdk = await initializeQueue({ host, log: testLog })
 
     await sdk.subscribe({

package/tests/util/mask-sensitive.unit.test.js

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest'
+
+import { mask, maskSingle } from '../../src/util/index.js'
+
+describe('maskSingle', () => {
+  it('masks middle of a regular string (length == left+right)', () => {
+    expect(maskSingle('abcdefgh')).toBe('a•••h')
+  })
+
+  it('masks numbers with default settings', () => {
+    expect(maskSingle(12345678)).toBe('1•••8')
+  })
+
+  it('masks booleans', () => {
+    expect(maskSingle(true)).toBe('t•••e')
+    expect(maskSingle(false)).toBe('f•••e')
+  })
+
+  it('masks very short strings correctly', () => {
+    expect(maskSingle('ab')).toBe('a••b'.slice(0, 3)) // will produce 'a••'
+    expect(maskSingle('a')).toBe('•')
+    expect(maskSingle('')).toBe('')
+  })
+
+  it('respects custom fill and mask length', () => {
+    expect(maskSingle('abcdefgh', '*', 5)).toBe('a*****h')
+  })
+
+  it('ensures maskLen is at least 1', () => {
+    expect(maskSingle('abcdefgh', '*', 0)).toBe('a*h')
+  })
+
+  it('returns empty string for null/undefined', () => {
+    expect(maskSingle(null)).toBe('')
+    expect(maskSingle(undefined)).toBe('')
+  })
+})
+
+describe('mask', () => {
+  it('masks primitives (string, number, boolean)', () => {
+    expect(mask('abcdefgh')).toBe('a•••h')
+    expect(mask(12345678)).toBe('1•••8')
+    expect(mask(true)).toBe('true')
+    expect(mask(false)).toBe('false')
+  })
+
+  it('returns empty string for null/undefined', () => {
+    expect(mask(null)).toBe('')
+    expect(mask(undefined)).toBe('')
+  })
+
+  it('masks arrays recursively', () => {
+    expect(mask(['abcdefgh', 12345678])).toEqual(['a•••h', '1•••8'])
+  })
+
+  it('masks objects recursively', () => {
+    expect(mask({ a: 'abcdefgh', b: 12345678 })).toEqual({
+      a: 'a•••h',
+      b: '1•••8',
+    })
+  })
+
+  it('masks nested objects/arrays recursively', () => {
+    const input = { arr: ['abcdefgh', { num: 12345678 }] }
+    const expected = { arr: ['a•••h', { num: '1•••8' }] }
+    expect(mask(input)).toEqual(expected)
+  })
+
+  it('handles Date instances by returning full ISO string', () => {
+    const d = new Date('2025-08-15T12:34:56.789Z')
+    expect(mask(d)).toBe(d.toISOString())
+  })
+
+  it('respects custom fill and mask length in recursive calls', () => {
+    const input = { val: 'abcdefgh' }
+    const expected = { val: 'a*****h' }
+    expect(mask(input, '*', 5)).toEqual(expected)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "allowJs": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types"
+  },
+  "include": ["src"]
+}

package/types/core/combine-unique-arrays.d.ts

@@ -0,0 +1 @@
+export function combineUniqueArrays(...lists: Array<any>[]): Array<any>;

package/types/core/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./regex-utils.js";
+export * from "./otp-generators.js";
+export * from "./sanitize-objects.js";
+export * from "./normalize-min-max.js";
+export * from "./normalize-to-array.js";
+export * from "./combine-unique-arrays.js";
+export * from "./normalize-phone-number.js";
+export * from "./normalize-premitives-types-or-default.js";

package/types/core/normalize-min-max.d.ts

@@ -0,0 +1,10 @@
+export function normalizeMinMax(defaultMinMax: {
+    min: number;
+    max: number;
+}, valuesMinMax: {
+    min?: number;
+    max?: number;
+} | null | undefined): {
+    min: number;
+    max: number;
+};

package/types/core/normalize-phone-number.d.ts

@@ -0,0 +1,48 @@
+/** Resolve libphonenumber regardless of interop shape */
+export function getLib(): any;
+export function phoneUtil(): any;
+/**
+ * Parse & validate an international number (must start with '+').
+ * @param {string} input
+ * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
+ * @throws {Error} If the number is invalid
+ */
+export function normalizePhoneOrThrowIntl(input: string): {
+    e164: string;
+    national: string;
+    international: string;
+    regionCode: string | undefined;
+    type: number;
+};
+/**
+ * Parse & validate a national number using a region hint.
+ * @param {string} input
+ * @param {string} defaultRegion
+ * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
+ * @throws {Error} If the number is invalid
+ */
+export function normalizePhoneOrThrowWithRegion(input: string, defaultRegion: string): {
+    e164: string;
+    national: string;
+    international: string;
+    regionCode: string | undefined;
+    type: number;
+};
+/**
+ * Smart normalization:
+ * - If input starts with '+', parse as international.
+ * - Otherwise require a defaultRegion and parse as national.
+ * @param {string} input
+ * @param {{ defaultRegion?: string }} [opts]
+ * @returns {{e164:string,national:string,international:string,regionCode:string|undefined,type:number}}
+ * @throws {Error} If invalid or defaultRegion is missing for non-international input
+ */
+export function normalizePhoneOrThrow(input: string, opts?: {
+    defaultRegion?: string;
+}): {
+    e164: string;
+    national: string;
+    international: string;
+    regionCode: string | undefined;
+    type: number;
+};