core-services-sdk 1.3.28 → 1.3.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.28",
+  "version": "1.3.30",
   "main": "src/index.js",
   "type": "module",
   "types": "types/index.d.ts",

package/src/util/context.js

@@ -0,0 +1,81 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+const als = new AsyncLocalStorage()
+
+/**
+ * Context utility built on top of Node.js AsyncLocalStorage.
+ * Provides a per-request (or per-async-chain) storage mechanism that
+ * allows passing metadata (like correlation IDs, user info, tenant ID, etc.)
+ * without explicitly threading it through every function call.
+ */
+
+export const Context = {
+  /**
+   * Run a callback within a given context store.
+   * Everything `await`ed or invoked inside this callback will have access
+   * to the provided store via {@link Context.get}, {@link Context.set}, or {@link Context.all}.
+   *
+   * @template T
+   * @param {Record<string, any>} store
+   * @param {() => T} callback - Function to execute inside the context.
+   * @returns {T} The return value of the callback (sync or async).
+   *
+   * @example
+   * Context.run(
+   *   { correlationId: 'abc123' },
+   *   async () => {
+   *     console.log(Context.get('correlationId')) // "abc123"
+   *   }
+   * )
+   */
+  run(store, callback) {
+    return als.run(store, callback)
+  },
+
+  /**
+   * Retrieve a single value from the current async context store.
+   *
+   * @template T
+   * @param {string} key - The key of the value to retrieve.
+   * @returns {T|undefined} The stored value, or `undefined` if no store exists or key not found.
+   *
+   * @example
+   * const userId = Context.get('userId')
+   */
+  get(key) {
+    const store = als.getStore()
+    return store?.[key]
+  },
+
+  /**
+   * Set a single key-value pair in the current async context store.
+   * If there is no active store (i.e. outside of a {@link Context.run}),
+   * this function does nothing.
+   *
+   * @param {string} key - The key under which to store the value.
+   * @param {any} value - The value to store.
+   *
+   * @example
+   * Context.set('tenantId', 'tnt_1234')
+   */
+  set(key, value) {
+    const store = als.getStore()
+    if (store) {
+      store[key] = value
+    }
+  },
+
+  /**
+   * Get the entire store object for the current async context.
+   *
+   * @returns {Record<string, any>} The current store object,
+   * or an empty object if no store exists.
+   *
+   * @example
+   * const all = Context.all()
+   * console.log(all) // { correlationId: 'abc123', userId: 'usr_789' }
+   */
+  all() {
+    return als.getStore() || {}
+  },
+}

package/src/util/mask-sensitive.js

@@ -1,18 +1,18 @@
 /**
  * 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 {string} [fill='.']
+ * @param {number} [maskLen=2]
  * @param {number} [left=4]
  * @param {number} [right=4]
  * @returns {string}
  */
 export const maskSingle = (
   value,
-  fill = '•',
-  maskLen = 3,
-  left = 4,
-  right = 4,
+  fill = '.',
+  maskLen = null,
+  left = 2,
+  right = 2,
 ) => {
   if (value == null) {
     return ''
@@ -21,14 +21,19 @@ export const maskSingle = (
   if (str.length === 0) {
     return ''
   }
-  const m = Math.max(1, maskLen)
+
+  if (typeof value === 'boolean') {
+    return str
+  }
+  const m =
+    null === maskLen ? Math.max(1, str.length - (right + left)) : 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[0] + fill.repeat(1) // "ab" -> "a.."
     }
     return str.slice(0, 1) + fill.repeat(m) + str.slice(-1)
   }
@@ -39,13 +44,19 @@ export const maskSingle = (
 /**
  * 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 {string} [fill='.']
+ * @param {number} [maskLen=2]
  * @param {number} [left=4]
  * @param {number} [right=4]
  * @returns {string|Array|Object}
  */
-export const mask = (value, fill = '•', maskLen = 3, left = 4, right = 4) => {
+export const mask = (
+  value,
+  fill = '.',
+  maskLen = null,
+  left = 2,
+  right = 2,
+) => {
   const type = typeof value
 
   if (value instanceof Date) {

package/tests/util/context.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest'
+import { Context } from '../../src/util/context.js'
+
+describe('Context utility', () => {
+  it('should return empty object and undefined outside run()', () => {
+    expect(Context.all()).toEqual({})
+    expect(Context.get('foo')).toBeUndefined()
+  })
+
+  it('should provide store values inside run()', () => {
+    Context.run({ correlationId: 'abc123', userId: 'usr_1' }, () => {
+      expect(Context.get('correlationId')).toBe('abc123')
+      expect(Context.get('userId')).toBe('usr_1')
+      expect(Context.all()).toEqual({
+        correlationId: 'abc123',
+        userId: 'usr_1',
+      })
+    })
+  })
+
+  it('should allow setting new values inside run()', () => {
+    Context.run({ initial: true }, () => {
+      expect(Context.get('initial')).toBe(true)
+      Context.set('added', 42)
+      expect(Context.get('added')).toBe(42)
+      expect(Context.all()).toEqual({ initial: true, added: 42 })
+    })
+  })
+
+  it('should isolate different runs()', () => {
+    Context.run({ value: 'first' }, () => {
+      expect(Context.get('value')).toBe('first')
+    })
+    Context.run({ value: 'second' }, () => {
+      expect(Context.get('value')).toBe('second')
+    })
+  })
+
+  it('should preserve context across async/await', async () => {
+    await Context.run({ requestId: 'req-1' }, async () => {
+      expect(Context.get('requestId')).toBe('req-1')
+
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      expect(Context.get('requestId')).toBe('req-1')
+
+      await Promise.resolve().then(() => {
+        expect(Context.get('requestId')).toBe('req-1')
+      })
+    })
+  })
+
+  it('should not leak context between async runs', async () => {
+    const results = await Promise.all([
+      Context.run({ user: 'alice' }, async () => {
+        await new Promise((resolve) => setTimeout(resolve, 5))
+        return Context.get('user')
+      }),
+      Context.run({ user: 'bob' }, async () => {
+        await new Promise((resolve) => setTimeout(resolve, 1))
+        return Context.get('user')
+      }),
+    ])
+
+    expect(results).toContain('alice')
+    expect(results).toContain('bob')
+  })
+})

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

@@ -4,30 +4,37 @@ 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')
+    const value = maskSingle('abcdefgh')
+    expect(value).toBe('ab....gh')
   })
 
   it('masks numbers with default settings', () => {
-    expect(maskSingle(12345678)).toBe('1•••8')
+    expect(maskSingle(12345678)).toBe('12....78')
   })
 
   it('masks booleans', () => {
-    expect(maskSingle(true)).toBe('t•••e')
-    expect(maskSingle(false)).toBe('f•••e')
+    const trueValue = maskSingle(true)
+    expect(trueValue).toBe('true')
+    const falseValue = maskSingle(false)
+    expect(falseValue).toBe('false')
   })
 
   it('masks very short strings correctly', () => {
-    expect(maskSingle('ab')).toBe('a••b'.slice(0, 3)) // will produce 'a••'
-    expect(maskSingle('a')).toBe('•')
+    const value1 = maskSingle('ab')
+    expect(value1).toBe('a.') // will produce 'a.'
+    const value2 = maskSingle('a')
+    expect(value2).toBe('.')
     expect(maskSingle('')).toBe('')
   })
 
   it('respects custom fill and mask length', () => {
-    expect(maskSingle('abcdefgh', '*', 5)).toBe('a*****h')
+    const value = maskSingle('abcdefgh', '*', 5)
+    expect(value).toBe('ab*****gh')
   })
 
   it('ensures maskLen is at least 1', () => {
-    expect(maskSingle('abcdefgh', '*', 0)).toBe('a*h')
+    const value = maskSingle('abcdefgh', '*', 1, 1, 1)
+    expect(value).toBe('a*h')
   })
 
   it('returns empty string for null/undefined', () => {
@@ -38,9 +45,10 @@ describe('maskSingle', () => {
 
 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('abcdefgh')).toBe('ab....gh')
+    expect(mask(12345678)).toBe('12....78')
+    const trueValue = mask(true)
+    expect(trueValue).toBe('true')
     expect(mask(false)).toBe('false')
   })
 
@@ -50,20 +58,22 @@ describe('mask', () => {
   })
 
   it('masks arrays recursively', () => {
-    expect(mask(['abcdefgh', 12345678])).toEqual(['a•••h', '1•••8'])
+    const value = mask(['abcdefgh', 12345678])
+    expect(value).toEqual(['ab....gh', '12....78'])
   })
 
   it('masks objects recursively', () => {
     expect(mask({ a: 'abcdefgh', b: 12345678 })).toEqual({
-      a: 'a•••h',
-      b: '1•••8',
+      a: 'ab....gh',
+      b: '12....78',
     })
   })
 
   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)
+    const expected = { arr: ['ab....gh', { num: '12....78' }] }
+    const value = mask(input)
+    expect(value).toEqual(expected)
   })
 
   it('handles Date instances by returning full ISO string', () => {
@@ -73,7 +83,8 @@ describe('mask', () => {
 
   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)
+    const expected = { val: 'ab*****gh' }
+    const value = mask(input, '*', 5)
+    expect(value).toEqual(expected)
   })
 })