@catbee/utils 2.0.5 → 2.1.1

package/README.md

@@ -111,6 +111,7 @@ server.enableGracefulShutdown();
 | Module                                                                      | Description                                             |
 | --------------------------------------------------------------------------- | ------------------------------------------------------- |
 | [Express Server](https://catbee.in/docs/@catbee/utils/server)               | Fast, secure, and scalable server setup                 |
+| [Healthz Server](https://catbee.in/docs/@catbee/utils/healthz-server)       | Healthz Server              |
 | [Array Utilities](https://catbee.in/docs/@catbee/utils/array)               | Advanced array manipulation                             |
 | [Async Utilities](https://catbee.in/docs/@catbee/utils/async)               | Promise helpers, concurrency, timing                    |
 | [Cache Utilities](https://catbee.in/docs/@catbee/utils/cache)               | In-memory caching with TTL                              |

package/context-store/index.cjs

@@ -28,23 +28,94 @@ var async_hooks = require('async_hooks');
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var TypedContextKey = class {
+  static {
+    __name(this, "TypedContextKey");
+  }
+  symbol;
+  defaultValue;
+  /**
+  * Creates a new typed context key.
+  * @param symbol - The unique symbol for this key
+  * @param defaultValue - Optional default value if key is not found
+  */
+  constructor(symbol, defaultValue) {
+    this.symbol = symbol;
+    this.defaultValue = defaultValue;
+  }
+  /**
+  * Gets the current value for this key.
+  * @returns The value or defaultValue if not found
+  */
+  get() {
+    return ContextStore.get(this.symbol) ?? this.defaultValue;
+  }
+  /**
+  * Sets the value for this key.
+  * @param value The value to set
+  */
+  set(value) {
+    ContextStore.set(this.symbol, value);
+  }
+  /**
+  * Checks if this key exists in the context.
+  * @returns True if the key exists
+  */
+  exists() {
+    return ContextStore.has(this.symbol);
+  }
+  /**
+  * Deletes this key from the context.
+  * @returns True if the key was deleted
+  */
+  delete() {
+    return ContextStore.delete(this.symbol);
+  }
+  /**
+  * Gets the symbol for this key.
+  * @returns Symbol for this key
+  */
+  getSymbol() {
+    return this.symbol;
+  }
+};
 var StoreKeys = {
   LOGGER: Symbol("LOGGER"),
   REQUEST_ID: Symbol("REQUEST_ID"),
-  USER: Symbol("USER"),
-  SESSION: Symbol("SESSION"),
-  TRANSACTION_ID: Symbol("TRANSACTION_ID"),
+  CORRELATION_ID: Symbol("CORRELATION_ID"),
   USER_ID: Symbol("USER_ID"),
+  TRANSACTION_ID: Symbol("TRANSACTION_ID"),
   TENANT_ID: Symbol("TENANT_ID"),
   TRACE_ID: Symbol("TRACE_ID"),
-  CORRELATION_ID: Symbol("CORRELATION_ID")
+  SPAN_ID: Symbol("SPAN_ID"),
+  MESSAGE_ID: Symbol("MESSAGE_ID"),
+  MESSAGE_TYPE: Symbol("MESSAGE_TYPE"),
+  QUEUE_NAME: Symbol("QUEUE_NAME")
+};
+var TypedStoreKeys = {
+  LOGGER: new TypedContextKey(StoreKeys.LOGGER),
+  REQUEST_ID: new TypedContextKey(StoreKeys.REQUEST_ID),
+  CORRELATION_ID: new TypedContextKey(StoreKeys.CORRELATION_ID),
+  USER_ID: new TypedContextKey(StoreKeys.USER_ID),
+  TRANSACTION_ID: new TypedContextKey(StoreKeys.TRANSACTION_ID),
+  TENANT_ID: new TypedContextKey(StoreKeys.TENANT_ID),
+  TRACE_ID: new TypedContextKey(StoreKeys.TRACE_ID),
+  SPAN_ID: new TypedContextKey(StoreKeys.SPAN_ID),
+  MESSAGE_ID: new TypedContextKey(StoreKeys.MESSAGE_ID),
+  MESSAGE_TYPE: new TypedContextKey(StoreKeys.MESSAGE_TYPE),
+  QUEUE_NAME: new TypedContextKey(StoreKeys.QUEUE_NAME)
 };
 function getRequestId() {
-  return ContextStore.get(StoreKeys.REQUEST_ID);
+  return TypedStoreKeys.REQUEST_ID.get();
 }
 __name(getRequestId, "getRequestId");
+function resolveKey(key) {
+  return key instanceof TypedContextKey ? key.getSymbol() : key;
+}
+__name(resolveKey, "resolveKey");
 function getFromContext(key) {
-  return ContextStore.get(key);
+  const symbol = resolveKey(key);
+  return ContextStore.get(symbol);
 }
 __name(getFromContext, "getFromContext");
 var ContextStore = class _ContextStore {
@@ -72,8 +143,9 @@ var ContextStore = class _ContextStore {
   * @returns {T | undefined} The value found (typed) or undefined if not present.
   */
   static get(key) {
+    const symbol = resolveKey(key);
     const store = this.storage.getStore();
-    return store?.[key];
+    return store?.[symbol];
   }
   /**
   * Sets a value in the current context store by symbol key.
@@ -84,11 +156,12 @@ var ContextStore = class _ContextStore {
   * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).
   */
   static set(key, value) {
+    const symbol = resolveKey(key);
     const store = this.storage.getStore();
     if (!store) {
-      throw new Error(`Failed to set ${String(key)}: AsyncLocalStorage store is not initialized.`);
+      throw new Error(`Failed to set ${String(symbol)}: AsyncLocalStorage store is not initialized.`);
     }
-    store[key] = value;
+    store[symbol] = value;
   }
   /**
   * Retrieves the entire context store object for the current async context.
@@ -117,8 +190,9 @@ var ContextStore = class _ContextStore {
   * @returns {boolean} True if the key exists, false otherwise.
   */
   static has(key) {
+    const symbol = resolveKey(key);
     const store = this.storage.getStore();
-    return store !== void 0 && key in store;
+    return store !== void 0 && symbol in store;
   }
   /**
   * Removes a value from the current context store by symbol key.
@@ -128,11 +202,12 @@ var ContextStore = class _ContextStore {
   * @throws {Error} If called outside an active context.
   */
   static delete(key) {
+    const symbol = resolveKey(key);
     const store = this.storage.getStore();
     if (!store) {
-      throw new Error(`Failed to delete ${String(key)}: AsyncLocalStorage store is not initialized.`);
+      throw new Error(`Failed to delete ${String(symbol)}: AsyncLocalStorage store is not initialized.`);
     }
-    return delete store[key];
+    return delete store[symbol];
   }
   /**
   * Updates multiple values in the current context store at once.
@@ -161,22 +236,16 @@ var ContextStore = class _ContextStore {
   * @throws {Error} If called outside an active context.
   */
   static withValue(key, value, callback) {
-    const store = this.storage.getStore();
-    if (!store) {
-      throw new Error(`Failed to set temporary value: AsyncLocalStorage store is not initialized.`);
-    }
-    const hasOriginal = key in store;
-    const originalValue = store[key];
-    store[key] = value;
-    try {
-      return callback();
-    } finally {
-      if (hasOriginal) {
-        store[key] = originalValue;
-      } else {
-        delete store[key];
-      }
+    const symbol = resolveKey(key);
+    const currentStore = this.storage.getStore();
+    if (!currentStore) {
+      throw new Error("Failed to set temporary value: AsyncLocalStorage store is not initialized.");
     }
+    const newStore = {
+      ...currentStore,
+      [symbol]: value
+    };
+    return this.storage.run(newStore, callback);
   }
   /**
   * Creates a new context that inherits values from the current context.
@@ -209,58 +278,10 @@ var ContextStore = class _ContextStore {
     };
   }
 };
-var TypedContextKey = class {
-  static {
-    __name(this, "TypedContextKey");
-  }
-  symbol;
-  defaultValue;
-  /**
-  * Creates a new typed context key.
-  *
-  * @param symbol - The unique symbol for this key
-  * @param defaultValue - Optional default value if key is not found
-  */
-  constructor(symbol, defaultValue) {
-    this.symbol = symbol;
-    this.defaultValue = defaultValue;
-  }
-  /**
-  * Gets the current value for this key.
-  *
-  * @returns The value or defaultValue if not found
-  */
-  get() {
-    return ContextStore.get(this.symbol) ?? this.defaultValue;
-  }
-  /**
-  * Sets the value for this key.
-  *
-  * @param value The value to set
-  */
-  set(value) {
-    ContextStore.set(this.symbol, value);
-  }
-  /**
-  * Checks if this key exists in the context.
-  *
-  * @returns True if the key exists
-  */
-  exists() {
-    return ContextStore.has(this.symbol);
-  }
-  /**
-  * Deletes this key from the context.
-  *
-  * @returns True if the key was deleted
-  */
-  delete() {
-    return ContextStore.delete(this.symbol);
-  }
-};
 
 exports.ContextStore = ContextStore;
 exports.StoreKeys = StoreKeys;
 exports.TypedContextKey = TypedContextKey;
+exports.TypedStoreKeys = TypedStoreKeys;
 exports.getFromContext = getFromContext;
 exports.getRequestId = getRequestId;

package/context-store/index.d.ts

@@ -23,6 +23,7 @@
  */
 
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { Logger } from 'pino';
 
 /**
  * Type representing the store object used in AsyncLocalStorage.
@@ -31,20 +32,76 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 interface Store {
     [key: symbol]: unknown;
 }
+/**
+ * Type-safe wrapper for accessing and modifying context values with specific types.
+ *
+ * @typeParam T - The value type.
+ */
+declare class TypedContextKey<T> {
+    private readonly symbol;
+    private readonly defaultValue?;
+    /**
+     * Creates a new typed context key.
+     * @param symbol - The unique symbol for this key
+     * @param defaultValue - Optional default value if key is not found
+     */
+    constructor(symbol: symbol, defaultValue?: T | undefined);
+    /**
+     * Gets the current value for this key.
+     * @returns The value or defaultValue if not found
+     */
+    get(): T | undefined;
+    /**
+     * Sets the value for this key.
+     * @param value The value to set
+     */
+    set(value: T): void;
+    /**
+     * Checks if this key exists in the context.
+     * @returns True if the key exists
+     */
+    exists(): boolean;
+    /**
+     * Deletes this key from the context.
+     * @returns True if the key was deleted
+     */
+    delete(): boolean;
+    /**
+     * Gets the symbol for this key.
+     * @returns Symbol for this key
+     */
+    getSymbol(): symbol;
+}
+type ContextKey<T = unknown> = symbol | TypedContextKey<T>;
 /**
  * Predefined symbols used as keys in AsyncLocalStorage.
  * Add new symbols here to avoid duplication.
  */
 declare const StoreKeys: {
-    LOGGER: symbol;
-    REQUEST_ID: symbol;
-    USER: symbol;
-    SESSION: symbol;
-    TRANSACTION_ID: symbol;
-    USER_ID: symbol;
-    TENANT_ID: symbol;
-    TRACE_ID: symbol;
-    CORRELATION_ID: symbol;
+    readonly LOGGER: symbol;
+    readonly REQUEST_ID: symbol;
+    readonly CORRELATION_ID: symbol;
+    readonly USER_ID: symbol;
+    readonly TRANSACTION_ID: symbol;
+    readonly TENANT_ID: symbol;
+    readonly TRACE_ID: symbol;
+    readonly SPAN_ID: symbol;
+    readonly MESSAGE_ID: symbol;
+    readonly MESSAGE_TYPE: symbol;
+    readonly QUEUE_NAME: symbol;
+};
+declare const TypedStoreKeys: {
+    readonly LOGGER: TypedContextKey<Logger>;
+    readonly REQUEST_ID: TypedContextKey<string>;
+    readonly CORRELATION_ID: TypedContextKey<string>;
+    readonly USER_ID: TypedContextKey<string>;
+    readonly TRANSACTION_ID: TypedContextKey<string>;
+    readonly TENANT_ID: TypedContextKey<string>;
+    readonly TRACE_ID: TypedContextKey<string>;
+    readonly SPAN_ID: TypedContextKey<string>;
+    readonly MESSAGE_ID: TypedContextKey<string>;
+    readonly MESSAGE_TYPE: TypedContextKey<string>;
+    readonly QUEUE_NAME: TypedContextKey<string>;
 };
 /**
  * Retrieves the current request ID from the async context, if available.
@@ -58,7 +115,7 @@ declare function getRequestId(): string | undefined;
  * @param key The store key symbol
  * @returns The typed value from the store
  */
-declare function getFromContext<T>(key: symbol): T | undefined;
+declare function getFromContext<T>(key: ContextKey<T>): T | undefined;
 /**
  * ContextStore manages per-request scoped context using AsyncLocalStorage.
  * It allows storing and retrieving data across async calls (e.g., request ID, logger).
@@ -94,7 +151,7 @@ declare class ContextStore {
      * @param {symbol} key - Unique symbol used as the store key.
      * @returns {T | undefined} The value found (typed) or undefined if not present.
      */
-    static get<T>(key: symbol): T | undefined;
+    static get<T>(key: ContextKey<T>): T | undefined;
     /**
      * Sets a value in the current context store by symbol key.
      *
@@ -103,7 +160,7 @@ declare class ContextStore {
      * @param {T} value - Value to set in context.
      * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).
      */
-    static set<T>(key: symbol, value: T): void;
+    static set<T>(key: ContextKey<T>, value: T): void;
     /**
      * Retrieves the entire context store object for the current async context.
      *
@@ -126,7 +183,7 @@ declare class ContextStore {
      * @param {symbol} key - The symbol key to check.
      * @returns {boolean} True if the key exists, false otherwise.
      */
-    static has(key: symbol): boolean;
+    static has(key: ContextKey): boolean;
     /**
      * Removes a value from the current context store by symbol key.
      *
@@ -134,7 +191,7 @@ declare class ContextStore {
      * @returns {boolean} True if the key was deleted, false if the key wasn't found or no active context.
      * @throws {Error} If called outside an active context.
      */
-    static delete(key: symbol): boolean;
+    static delete(key: ContextKey): boolean;
     /**
      * Updates multiple values in the current context store at once.
      *
@@ -153,7 +210,7 @@ declare class ContextStore {
      * @returns {T} The result of the callback function.
      * @throws {Error} If called outside an active context.
      */
-    static withValue<T>(key: symbol, value: unknown, callback: () => T): T;
+    static withValue<T, V>(key: ContextKey<V>, value: V, callback: () => T): T;
     /**
      * Creates a new context that inherits values from the current context.
      *
@@ -171,46 +228,6 @@ declare class ContextStore {
      */
     static createExpressMiddleware(initialValuesFactory?: (req: any) => Partial<Record<symbol, unknown>>): (req: any, _res: any, next: any) => void;
 }
-/**
- * Type-safe wrapper for accessing and modifying context values with specific types.
- *
- * @typeParam T - The value type.
- */
-declare class TypedContextKey<T> {
-    private readonly symbol;
-    private readonly defaultValue?;
-    /**
-     * Creates a new typed context key.
-     *
-     * @param symbol - The unique symbol for this key
-     * @param defaultValue - Optional default value if key is not found
-     */
-    constructor(symbol: symbol, defaultValue?: T | undefined);
-    /**
-     * Gets the current value for this key.
-     *
-     * @returns The value or defaultValue if not found
-     */
-    get(): T | undefined;
-    /**
-     * Sets the value for this key.
-     *
-     * @param value The value to set
-     */
-    set(value: T): void;
-    /**
-     * Checks if this key exists in the context.
-     *
-     * @returns True if the key exists
-     */
-    exists(): boolean;
-    /**
-     * Deletes this key from the context.
-     *
-     * @returns True if the key was deleted
-     */
-    delete(): boolean;
-}
 
-export { ContextStore, StoreKeys, TypedContextKey, getFromContext, getRequestId };
-export type { Store };
+export { ContextStore, StoreKeys, TypedContextKey, TypedStoreKeys, getFromContext, getRequestId };
+export type { ContextKey, Store };

package/context-store/index.mjs

@@ -26,23 +26,94 @@ import { AsyncLocalStorage } from 'async_hooks';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var TypedContextKey = class {
+  static {
+    __name(this, "TypedContextKey");
+  }
+  symbol;
+  defaultValue;
+  /**
+  * Creates a new typed context key.
+  * @param symbol - The unique symbol for this key
+  * @param defaultValue - Optional default value if key is not found
+  */
+  constructor(symbol, defaultValue) {
+    this.symbol = symbol;
+    this.defaultValue = defaultValue;
+  }
+  /**
+  * Gets the current value for this key.
+  * @returns The value or defaultValue if not found
+  */
+  get() {
+    return ContextStore.get(this.symbol) ?? this.defaultValue;
+  }
+  /**
+  * Sets the value for this key.
+  * @param value The value to set
+  */
+  set(value) {
+    ContextStore.set(this.symbol, value);
+  }
+  /**
+  * Checks if this key exists in the context.
+  * @returns True if the key exists
+  */
+  exists() {
+    return ContextStore.has(this.symbol);
+  }
+  /**
+  * Deletes this key from the context.
+  * @returns True if the key was deleted
+  */
+  delete() {
+    return ContextStore.delete(this.symbol);
+  }
+  /**
+  * Gets the symbol for this key.
+  * @returns Symbol for this key
+  */
+  getSymbol() {
+    return this.symbol;
+  }
+};
 var StoreKeys = {
   LOGGER: Symbol("LOGGER"),
   REQUEST_ID: Symbol("REQUEST_ID"),
-  USER: Symbol("USER"),
-  SESSION: Symbol("SESSION"),
-  TRANSACTION_ID: Symbol("TRANSACTION_ID"),
+  CORRELATION_ID: Symbol("CORRELATION_ID"),
   USER_ID: Symbol("USER_ID"),
+  TRANSACTION_ID: Symbol("TRANSACTION_ID"),
   TENANT_ID: Symbol("TENANT_ID"),
   TRACE_ID: Symbol("TRACE_ID"),
-  CORRELATION_ID: Symbol("CORRELATION_ID")
+  SPAN_ID: Symbol("SPAN_ID"),
+  MESSAGE_ID: Symbol("MESSAGE_ID"),
+  MESSAGE_TYPE: Symbol("MESSAGE_TYPE"),
+  QUEUE_NAME: Symbol("QUEUE_NAME")
+};
+var TypedStoreKeys = {
+  LOGGER: new TypedContextKey(StoreKeys.LOGGER),
+  REQUEST_ID: new TypedContextKey(StoreKeys.REQUEST_ID),
+  CORRELATION_ID: new TypedContextKey(StoreKeys.CORRELATION_ID),
+  USER_ID: new TypedContextKey(StoreKeys.USER_ID),
+  TRANSACTION_ID: new TypedContextKey(StoreKeys.TRANSACTION_ID),
+  TENANT_ID: new TypedContextKey(StoreKeys.TENANT_ID),
+  TRACE_ID: new TypedContextKey(StoreKeys.TRACE_ID),
+  SPAN_ID: new TypedContextKey(StoreKeys.SPAN_ID),
+  MESSAGE_ID: new TypedContextKey(StoreKeys.MESSAGE_ID),
+  MESSAGE_TYPE: new TypedContextKey(StoreKeys.MESSAGE_TYPE),
+  QUEUE_NAME: new TypedContextKey(StoreKeys.QUEUE_NAME)
 };
 function getRequestId() {
-  return ContextStore.get(StoreKeys.REQUEST_ID);
+  return TypedStoreKeys.REQUEST_ID.get();
 }
 __name(getRequestId, "getRequestId");
+function resolveKey(key) {
+  return key instanceof TypedContextKey ? key.getSymbol() : key;
+}
+__name(resolveKey, "resolveKey");
 function getFromContext(key) {
-  return ContextStore.get(key);
+  const symbol = resolveKey(key);
+  return ContextStore.get(symbol);
 }
 __name(getFromContext, "getFromContext");
 var ContextStore = class _ContextStore {
@@ -70,8 +141,9 @@ var ContextStore = class _ContextStore {
   * @returns {T | undefined} The value found (typed) or undefined if not present.
   */
   static get(key) {
+    const symbol = resolveKey(key);
     const store = this.storage.getStore();
-    return store?.[key];
+    return store?.[symbol];
   }
   /**
   * Sets a value in the current context store by symbol key.
@@ -82,11 +154,12 @@ var ContextStore = class _ContextStore {
   * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).
   */
   static set(key, value) {
+    const symbol = resolveKey(key);
     const store = this.storage.getStore();
     if (!store) {
-      throw new Error(`Failed to set ${String(key)}: AsyncLocalStorage store is not initialized.`);
+      throw new Error(`Failed to set ${String(symbol)}: AsyncLocalStorage store is not initialized.`);
     }
-    store[key] = value;
+    store[symbol] = value;
   }
   /**
   * Retrieves the entire context store object for the current async context.
@@ -115,8 +188,9 @@ var ContextStore = class _ContextStore {
   * @returns {boolean} True if the key exists, false otherwise.
   */
   static has(key) {
+    const symbol = resolveKey(key);
     const store = this.storage.getStore();
-    return store !== void 0 && key in store;
+    return store !== void 0 && symbol in store;
   }
   /**
   * Removes a value from the current context store by symbol key.
@@ -126,11 +200,12 @@ var ContextStore = class _ContextStore {
   * @throws {Error} If called outside an active context.
   */
   static delete(key) {
+    const symbol = resolveKey(key);
     const store = this.storage.getStore();
     if (!store) {
-      throw new Error(`Failed to delete ${String(key)}: AsyncLocalStorage store is not initialized.`);
+      throw new Error(`Failed to delete ${String(symbol)}: AsyncLocalStorage store is not initialized.`);
     }
-    return delete store[key];
+    return delete store[symbol];
   }
   /**
   * Updates multiple values in the current context store at once.
@@ -159,22 +234,16 @@ var ContextStore = class _ContextStore {
   * @throws {Error} If called outside an active context.
   */
   static withValue(key, value, callback) {
-    const store = this.storage.getStore();
-    if (!store) {
-      throw new Error(`Failed to set temporary value: AsyncLocalStorage store is not initialized.`);
-    }
-    const hasOriginal = key in store;
-    const originalValue = store[key];
-    store[key] = value;
-    try {
-      return callback();
-    } finally {
-      if (hasOriginal) {
-        store[key] = originalValue;
-      } else {
-        delete store[key];
-      }
+    const symbol = resolveKey(key);
+    const currentStore = this.storage.getStore();
+    if (!currentStore) {
+      throw new Error("Failed to set temporary value: AsyncLocalStorage store is not initialized.");
     }
+    const newStore = {
+      ...currentStore,
+      [symbol]: value
+    };
+    return this.storage.run(newStore, callback);
   }
   /**
   * Creates a new context that inherits values from the current context.
@@ -207,54 +276,5 @@ var ContextStore = class _ContextStore {
     };
   }
 };
-var TypedContextKey = class {
-  static {
-    __name(this, "TypedContextKey");
-  }
-  symbol;
-  defaultValue;
-  /**
-  * Creates a new typed context key.
-  *
-  * @param symbol - The unique symbol for this key
-  * @param defaultValue - Optional default value if key is not found
-  */
-  constructor(symbol, defaultValue) {
-    this.symbol = symbol;
-    this.defaultValue = defaultValue;
-  }
-  /**
-  * Gets the current value for this key.
-  *
-  * @returns The value or defaultValue if not found
-  */
-  get() {
-    return ContextStore.get(this.symbol) ?? this.defaultValue;
-  }
-  /**
-  * Sets the value for this key.
-  *
-  * @param value The value to set
-  */
-  set(value) {
-    ContextStore.set(this.symbol, value);
-  }
-  /**
-  * Checks if this key exists in the context.
-  *
-  * @returns True if the key exists
-  */
-  exists() {
-    return ContextStore.has(this.symbol);
-  }
-  /**
-  * Deletes this key from the context.
-  *
-  * @returns True if the key was deleted
-  */
-  delete() {
-    return ContextStore.delete(this.symbol);
-  }
-};
 
-export { ContextStore, StoreKeys, TypedContextKey, getFromContext, getRequestId };
+export { ContextStore, StoreKeys, TypedContextKey, TypedStoreKeys, getFromContext, getRequestId };