core-services-sdk 1.3.29 → 1.3.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "core-services-sdk",
-  "version": "1.3.29",
+  "version": "1.3.31",
   "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/index.js

@@ -10,3 +10,4 @@ export const util = {
 }
 
 export { mask, maskSingle }
+export { Context } from './context.js'

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')
+  })
+})