@catbee/utils 0.0.1 → 0.0.3

package/build/src/utils/cache.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.utils.js","sourceRoot":"","sources":["../../../src/utils/cache.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Represents a cached entry with a value and an expiration timestamp.\n */\ntype CacheEntry<T> = {\n  value: T;\n  expiresAt: number;\n};\n\n/**\n * An in-memory cache with time-to-live (TTL) support for each entry.\n *\n * @typeParam K - Type of the key.\n * @typeParam V - Type of the value.\n *\n * @example\n * const cache = new TTLCache<string, number>(1000);\n * cache.set(\"x\", 123);\n * const value = cache.get(\"x\"); // 123\n */\nexport class TTLCache<K, V> {\n  private cache = new Map<K, CacheEntry<V>>();\n\n  /**\n   * @param ttlMs - Default time-to-live in milliseconds for cache entries.\n   */\n  constructor(private ttlMs: number = 5 * 60 * 1000) {}\n\n  /**\n   * Sets a key-value pair in the cache with the default TTL.\n   *\n   * @param key - The key to set.\n   * @param value - The value to associate with the key.\n   */\n  set(key: K, value: V): void {\n    const expiresAt = Date.now() + this.ttlMs;\n    this.cache.set(key, { value, expiresAt });\n  }\n\n  /**\n   * Sets a key-value pair in the cache with a custom TTL.\n   *\n   * @param key - The key to set.\n   * @param value - The value to associate with the key.\n   * @param ttlMs - Time-to-live in milliseconds.\n   */\n  setWithTTL(key: K, value: V, ttlMs: number): void {\n    const expiresAt = Date.now() + ttlMs;\n    this.cache.set(key, { value, expiresAt });\n  }\n\n  /**\n   * Retrieves the value for a given key if it hasn't expired.\n   *\n   * @param key - The key to retrieve.\n   * @returns The cached value, or undefined if not found or expired.\n   */\n  get(key: K): V | undefined {\n    const entry = this.cache.get(key);\n    if (!entry) return undefined;\n    if (Date.now() > entry.expiresAt) {\n      this.cache.delete(key);\n      return undefined;\n    }\n    return entry.value;\n  }\n\n  /**\n   * Checks if the key exists and hasn't expired.\n   *\n   * @param key - The key to check.\n   * @returns `true` if key exists and is valid, otherwise `false`.\n   */\n  has(key: K): boolean {\n    return this.get(key) !== undefined;\n  }\n\n  /**\n   * Deletes a key from the cache.\n   *\n   * @param key - The key to delete.\n   * @returns `true` if the key existed and was removed, `false` otherwise.\n   */\n  delete(key: K): boolean {\n    return this.cache.delete(key);\n  }\n\n  /**\n   * Clears all entries from the cache.\n   */\n  clear(): void {\n    this.cache.clear();\n  }\n\n  /**\n   * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).\n   *\n   * @returns Number of items in the cache (may include expired keys).\n   */\n  size(): number {\n    return this.cache.size;\n  }\n\n  /**\n   * Removes all expired entries from the cache.\n   *\n   * @returns Number of entries removed.\n   */\n  cleanup(): number {\n    let removed = 0;\n    const now = Date.now();\n    for (const [key, entry] of this.cache.entries()) {\n      if (now > entry.expiresAt) {\n        this.cache.delete(key);\n        removed++;\n      }\n    }\n    return removed;\n  }\n\n  /**\n   * Returns an iterator of all current valid [key, value] pairs.\n   *\n   * @returns IterableIterator<[K, V]>\n   */\n  *entries(): IterableIterator<[K, V]> {\n    for (const [key, entry] of this.cache.entries()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield [key, entry.value];\n      }\n    }\n  }\n\n  /**\n   * Returns an iterator of all current valid keys.\n   *\n   * @returns IterableIterator<K>\n   */\n  *keys(): IterableIterator<K> {\n    for (const [key, entry] of this.cache.entries()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield key;\n      }\n    }\n  }\n\n  /**\n   * Returns an iterator of all current valid values.\n   *\n   * @returns IterableIterator<V>\n   */\n  *values(): IterableIterator<V> {\n    for (const entry of this.cache.values()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield entry.value;\n      }\n    }\n  }\n}\n"]}
+{"version":3,"file":"cache.utils.js","sourceRoot":"","sources":["../../../src/utils/cache.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { Config } from '../config';\n\n/**\n * Represents a cached entry with a value and an expiration timestamp.\n */\ntype CacheEntry<T> = {\n  value: T;\n  expiresAt: number;\n  lastAccessed?: number; // Track last access time for LRU functionality\n};\n\n/**\n * Options for configuring a TTLCache instance.\n */\nexport interface TTLCacheOptions {\n  /** Default time-to-live in milliseconds for cache entries */\n  ttlMs?: number;\n  /** Maximum number of entries to keep in cache (uses LRU eviction policy) */\n  maxSize?: number;\n  /** Auto-cleanup interval in milliseconds (disabled if 0 or negative) */\n  autoCleanupMs?: number;\n}\n\n/**\n * An in-memory cache with time-to-live (TTL) support for each entry.\n *\n * @typeParam K - Type of the key.\n * @typeParam V - Type of the value.\n *\n * @example\n * const cache = new TTLCache<string, number>({ ttlMs: 1000 });\n * cache.set(\"x\", 123);\n * const value = cache.get(\"x\"); // 123\n */\nexport class TTLCache<K, V> {\n  private cache = new Map<K, CacheEntry<V>>();\n  private ttlMs: number;\n  private maxSize?: number;\n  private cleanupInterval?: NodeJS.Timeout;\n\n  /**\n   * @param options - Configuration options for the cache\n   */\n  constructor(options: TTLCacheOptions = {}) {\n    this.ttlMs = options.ttlMs ?? Config.Cache.defaultTtl;\n    this.maxSize = options.maxSize;\n\n    // Setup auto-cleanup if enabled\n    const autoCleanupMs = options.autoCleanupMs;\n    if (autoCleanupMs && autoCleanupMs > 0) {\n      this.cleanupInterval = setInterval(() => {\n        this.cleanup();\n      }, autoCleanupMs);\n    }\n  }\n\n  /**\n   * Sets a key-value pair in the cache with the default TTL.\n   *\n   * @param key - The key to set.\n   * @param value - The value to associate with the key.\n   */\n  set(key: K, value: V): void {\n    this.setWithTTL(key, value, this.ttlMs);\n  }\n\n  /**\n   * Sets a key-value pair in the cache with a custom TTL.\n   *\n   * @param key - The key to set.\n   * @param value - The value to associate with the key.\n   * @param ttlMs - Time-to-live in milliseconds.\n   */\n  setWithTTL(key: K, value: V, ttlMs: number): void {\n    const now = Date.now();\n    const expiresAt = now + ttlMs;\n    this.cache.set(key, { value, expiresAt, lastAccessed: now });\n\n    // Enforce max size limit if configured\n    if (this.maxSize && this.cache.size > this.maxSize) {\n      this.evictLRU();\n    }\n  }\n\n  /**\n   * Retrieves the value for a given key if it hasn't expired.\n   *\n   * @param key - The key to retrieve.\n   * @returns The cached value, or undefined if not found or expired.\n   */\n  get(key: K): V | undefined {\n    const entry = this.cache.get(key);\n    if (!entry) return undefined;\n\n    const now = Date.now();\n    if (now > entry.expiresAt) {\n      this.cache.delete(key);\n      return undefined;\n    }\n\n    // Update last access time for LRU tracking\n    entry.lastAccessed = now;\n    return entry.value;\n  }\n\n  /**\n   * Retrieves or computes a value if it's not in the cache or has expired.\n   *\n   * @param key - The key to retrieve\n   * @param producer - Function to generate the value if not cached\n   * @param ttlMs - Optional custom TTL for the computed value\n   * @returns The cached or computed value\n   */\n  async getOrCompute(key: K, producer: () => Promise<V>, ttlMs?: number): Promise<V> {\n    const value = this.get(key);\n    if (value !== undefined) return value;\n\n    const newValue = await producer();\n    this.setWithTTL(key, newValue, ttlMs ?? this.ttlMs);\n    return newValue;\n  }\n\n  /**\n   * Checks if the key exists and hasn't expired.\n   *\n   * @param key - The key to check.\n   * @returns `true` if key exists and is valid, otherwise `false`.\n   */\n  has(key: K): boolean {\n    return this.get(key) !== undefined;\n  }\n\n  /**\n   * Deletes a key from the cache.\n   *\n   * @param key - The key to delete.\n   * @returns `true` if the key existed and was removed, `false` otherwise.\n   */\n  delete(key: K): boolean {\n    return this.cache.delete(key);\n  }\n\n  /**\n   * Clears all entries from the cache.\n   */\n  clear(): void {\n    this.cache.clear();\n  }\n\n  /**\n   * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).\n   *\n   * @returns Number of items in the cache (may include expired keys).\n   */\n  size(): number {\n    return this.cache.size;\n  }\n\n  /**\n   * Set multiple key-value pairs at once with the default TTL.\n   *\n   * @param entries - Array of [key, value] tuples to set\n   */\n  setMany(entries: [K, V][]): void {\n    for (const [key, value] of entries) {\n      this.set(key, value);\n    }\n  }\n\n  /**\n   * Get multiple values at once.\n   *\n   * @param keys - Array of keys to retrieve\n   * @returns Array of values (undefined for keys that don't exist or expired)\n   */\n  getMany(keys: K[]): (V | undefined)[] {\n    return keys.map(key => this.get(key));\n  }\n\n  /**\n   * Removes all expired entries from the cache.\n   *\n   * @returns Number of entries removed.\n   */\n  cleanup(): number {\n    let removed = 0;\n    const now = Date.now();\n    for (const [key, entry] of this.cache.entries()) {\n      if (now > entry.expiresAt) {\n        this.cache.delete(key);\n        removed++;\n      }\n    }\n    return removed;\n  }\n\n  /**\n   * Returns an iterator of all current valid [key, value] pairs.\n   *\n   * @returns IterableIterator<[K, V]>\n   */\n  *entries(): IterableIterator<[K, V]> {\n    for (const [key, entry] of this.cache.entries()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield [key, entry.value];\n      }\n    }\n  }\n\n  /**\n   * Returns an iterator of all current valid keys.\n   *\n   * @returns IterableIterator<K>\n   */\n  *keys(): IterableIterator<K> {\n    for (const [key, entry] of this.cache.entries()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield key;\n      }\n    }\n  }\n\n  /**\n   * Returns an iterator of all current valid values.\n   *\n   * @returns IterableIterator<V>\n   */\n  *values(): IterableIterator<V> {\n    for (const entry of this.cache.values()) {\n      if (Date.now() <= entry.expiresAt) {\n        yield entry.value;\n      }\n    }\n  }\n\n  /**\n   * Extends the expiration of a key by the specified time or default TTL.\n   *\n   * @param key - The key to refresh\n   * @param ttlMs - Optional new TTL in milliseconds (uses default if not specified)\n   * @returns true if the key was found and refreshed, false otherwise\n   */\n  refresh(key: K, ttlMs?: number): boolean {\n    const entry = this.cache.get(key);\n    if (!entry) return false;\n\n    const now = Date.now();\n    if (now > entry.expiresAt) {\n      this.cache.delete(key);\n      return false;\n    }\n\n    entry.expiresAt = now + (ttlMs ?? this.ttlMs);\n    entry.lastAccessed = now;\n    return true;\n  }\n\n  /**\n   * Returns a snapshot of cache stats.\n   *\n   * @returns Object containing cache statistics\n   */\n  stats() {\n    const now = Date.now();\n    let expired = 0;\n    let valid = 0;\n\n    for (const entry of this.cache.values()) {\n      if (now > entry.expiresAt) {\n        expired++;\n      } else {\n        valid++;\n      }\n    }\n\n    return {\n      size: this.cache.size,\n      validEntries: valid,\n      expiredEntries: expired,\n      maxSize: this.maxSize\n    };\n  }\n\n  /**\n   * Stop the auto-cleanup interval if it's running.\n   */\n  destroy() {\n    if (this.cleanupInterval) {\n      clearInterval(this.cleanupInterval);\n      this.cleanupInterval = undefined;\n    }\n  }\n\n  /**\n   * Evict the least recently used entry from the cache.\n   * @private\n   */\n  private evictLRU(): void {\n    let oldestKey: K | undefined;\n    let oldestAccess = Infinity;\n\n    for (const [key, entry] of this.cache.entries()) {\n      // Skip entries that are already expired\n      if (Date.now() > entry.expiresAt) {\n        this.cache.delete(key);\n        return;\n      }\n\n      // Find the oldest accessed entry\n      if (entry.lastAccessed && entry.lastAccessed < oldestAccess) {\n        oldestAccess = entry.lastAccessed;\n        oldestKey = key;\n      }\n    }\n\n    if (oldestKey) {\n      this.cache.delete(oldestKey);\n    }\n  }\n}\n"]}

package/build/src/utils/context-store.utils.d.ts

@@ -1,4 +1,4 @@
-import { AsyncLocalStorage } from "async_hooks";
+import { AsyncLocalStorage } from 'async_hooks';
 /**
  * Type representing the store object used in AsyncLocalStorage.
  * Keys must be unique symbols to ensure isolation and prevent collisions.
@@ -13,6 +13,10 @@ export interface Store {
 export declare const StoreKeys: {
     LOGGER: symbol;
     REQUEST_ID: symbol;
+    USER_ID: symbol;
+    TENANT_ID: symbol;
+    TRACE_ID: symbol;
+    CORRELATION_ID: symbol;
 };
 /**
  * Retrieves the current request ID from the async context, if available.
@@ -20,6 +24,13 @@ export declare const StoreKeys: {
  * @returns {string | undefined} The request ID string or undefined if not present in the current context.
  */
 export declare function getRequestId(): string | undefined;
+/**
+ * Type-safe getter for common context values.
+ *
+ * @param key The store key symbol
+ * @returns The typed value from the store
+ */
+export declare function getFromContext<T>(key: symbol): T | undefined;
 /**
  * ContextStore manages per-request scoped context using AsyncLocalStorage.
  * It allows storing and retrieving data across async calls (e.g., request ID, logger).
@@ -81,5 +92,95 @@ export declare class ContextStore {
      * @returns {T} The result of the callback function.
      */
     static run<T>(store: Store, callback: () => T): T;
+    /**
+     * Checks if a key exists in the current context store.
+     *
+     * @param {symbol} key - The symbol key to check.
+     * @returns {boolean} True if the key exists, false otherwise.
+     */
+    static has(key: symbol): boolean;
+    /**
+     * Removes a value from the current context store by symbol key.
+     *
+     * @param {symbol} key - The symbol key to delete.
+     * @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;
+    /**
+     * Updates multiple values in the current context store at once.
+     *
+     * @param {Partial<Record<symbol, unknown>>} values - Object containing symbol keys and values to update.
+     * @throws {Error} If called outside an active context.
+     */
+    static patch(values: Partial<Record<symbol, unknown>>): void;
+    /**
+     * Executes a callback with a temporary store value that only exists during execution.
+     * Original store is restored after callback completes.
+     *
+     * @typeParam T - The callback's return type.
+     * @param {symbol} key - The symbol key to temporarily set.
+     * @param {unknown} value - The temporary value.
+     * @param {() => T} callback - The function to execute with the temporary value.
+     * @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;
+    /**
+     * Creates a new context that inherits values from the current context.
+     *
+     * @typeParam T - The callback's return type.
+     * @param {Partial<Record<symbol, unknown>>} newValues - New values to add to or override in the context.
+     * @param {() => T} callback - The function to execute in the new context.
+     * @returns {T} The result of the callback function.
+     */
+    static extend<T>(newValues: Partial<Record<symbol, unknown>>, callback: () => T): T;
+    /**
+     * Creates Express middleware that initializes a context for each request.
+     *
+     * @param {(req: any) => Partial<Record<symbol, unknown>>} initialValuesFactory - Function that returns initial context values.
+     * @returns Express middleware function.
+     */
+    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.
+ */
+export declare class TypedContextKey<T> {
+    private symbol;
+    private 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;
 }
 //# sourceMappingURL=context-store.utils.d.ts.map

package/build/src/utils/context-store.utils.js

@@ -1,15 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContextStore = exports.StoreKeys = void 0;
+exports.TypedContextKey = exports.ContextStore = exports.StoreKeys = void 0;
 exports.getRequestId = getRequestId;
+exports.getFromContext = getFromContext;
 const async_hooks_1 = require("async_hooks");
 /**
  * Predefined symbols used as keys in AsyncLocalStorage.
  * Add new symbols here to avoid duplication.
  */
 exports.StoreKeys = {
-    LOGGER: Symbol("logger"),
-    REQUEST_ID: Symbol("requestId"),
+    LOGGER: Symbol('logger'),
+    REQUEST_ID: Symbol('requestId'),
+    USER_ID: Symbol('userId'),
+    TENANT_ID: Symbol('tenantId'),
+    TRACE_ID: Symbol('traceId'),
+    CORRELATION_ID: Symbol('correlationId')
 };
 /**
  * Retrieves the current request ID from the async context, if available.
@@ -19,6 +24,15 @@ exports.StoreKeys = {
 function getRequestId() {
     return ContextStore.get(exports.StoreKeys.REQUEST_ID);
 }
+/**
+ * Type-safe getter for common context values.
+ *
+ * @param key The store key symbol
+ * @returns The typed value from the store
+ */
+function getFromContext(key) {
+    return ContextStore.get(key);
+}
 /**
  * ContextStore manages per-request scoped context using AsyncLocalStorage.
  * It allows storing and retrieving data across async calls (e.g., request ID, logger).
@@ -90,6 +104,111 @@ class ContextStore {
     static run(store, callback) {
         return this.storage.run(store, callback);
     }
+    /**
+     * Checks if a key exists in the current context store.
+     *
+     * @param {symbol} key - The symbol key to check.
+     * @returns {boolean} True if the key exists, false otherwise.
+     */
+    static has(key) {
+        const store = this.storage.getStore();
+        return store !== undefined && key in store;
+    }
+    /**
+     * Removes a value from the current context store by symbol key.
+     *
+     * @param {symbol} key - The symbol key to delete.
+     * @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) {
+        const store = this.storage.getStore();
+        if (!store) {
+            throw new Error(`Failed to delete ${String(key)}: AsyncLocalStorage store is not initialized.`);
+        }
+        return delete store[key];
+    }
+    /**
+     * Updates multiple values in the current context store at once.
+     *
+     * @param {Partial<Record<symbol, unknown>>} values - Object containing symbol keys and values to update.
+     * @throws {Error} If called outside an active context.
+     */
+    static patch(values) {
+        const store = this.storage.getStore();
+        if (!store) {
+            throw new Error('Failed to patch: AsyncLocalStorage store is not initialized.');
+        }
+        Object.getOwnPropertySymbols(values).forEach(key => {
+            store[key] = values[key];
+        });
+    }
+    /**
+     * Executes a callback with a temporary store value that only exists during execution.
+     * Original store is restored after callback completes.
+     *
+     * @typeParam T - The callback's return type.
+     * @param {symbol} key - The symbol key to temporarily set.
+     * @param {unknown} value - The temporary value.
+     * @param {() => T} callback - The function to execute with the temporary value.
+     * @returns {T} The result of the callback function.
+     * @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.`);
+        }
+        // Save original value
+        const hasOriginal = key in store;
+        const originalValue = store[key];
+        // Set temporary value
+        store[key] = value;
+        try {
+            // Run callback
+            return callback();
+        }
+        finally {
+            // Restore original value
+            if (hasOriginal) {
+                store[key] = originalValue;
+            }
+            else {
+                delete store[key];
+            }
+        }
+    }
+    /**
+     * Creates a new context that inherits values from the current context.
+     *
+     * @typeParam T - The callback's return type.
+     * @param {Partial<Record<symbol, unknown>>} newValues - New values to add to or override in the context.
+     * @param {() => T} callback - The function to execute in the new context.
+     * @returns {T} The result of the callback function.
+     */
+    static extend(newValues, callback) {
+        const currentStore = this.storage.getStore() || {};
+        // Create new store with current values plus new ones
+        const newStore = Object.assign({}, currentStore);
+        // Add new values
+        Object.getOwnPropertySymbols(newValues).forEach(key => {
+            newStore[key] = newValues[key];
+        });
+        // Run with extended store
+        return this.storage.run(newStore, callback);
+    }
+    /**
+     * Creates Express middleware that initializes a context for each request.
+     *
+     * @param {(req: any) => Partial<Record<symbol, unknown>>} initialValuesFactory - Function that returns initial context values.
+     * @returns Express middleware function.
+     */
+    static createExpressMiddleware(initialValuesFactory = () => ({})) {
+        return (req, res, next) => {
+            const initialValues = initialValuesFactory(req);
+            ContextStore.run(initialValues, next);
+        };
+    }
 }
 exports.ContextStore = ContextStore;
 /**
@@ -97,4 +216,55 @@ exports.ContextStore = ContextStore;
  * @private
  */
 ContextStore.storage = new async_hooks_1.AsyncLocalStorage();
+/**
+ * Type-safe wrapper for accessing and modifying context values with specific types.
+ *
+ * @typeParam T - The value type.
+ */
+class TypedContextKey {
+    /**
+     * 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() {
+        const value = ContextStore.get(this.symbol);
+        return value !== undefined ? value : 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.TypedContextKey = TypedContextKey;
 //# sourceMappingURL=context-store.utils.js.map

package/build/src/utils/context-store.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-store.utils.js","sourceRoot":"","sources":["../../../src/utils/context-store.utils.ts"],"names":[],"mappings":";;;AAwBA,oCAEC;AA1BD,6CAAgD;AAUhD;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC;CAChC,CAAC;AAEF;;;;GAIG;AACH,SAAgB,YAAY;IAC1B,OAAO,YAAY,CAAC,GAAG,CAAS,iBAAS,CAAC,UAAU,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAa,YAAY;IAOvB;;;;OAIG;IACH,MAAM,CAAC,WAAW;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAI,GAAW;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAG,GAAG,CAAkB,CAAC;IACvC,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,iBAAiB,MAAM,CAAC,GAAG,CAAC,+CAA+C,CAC5E,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,GAAG,CAAI,KAAY,EAAE,QAAiB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;;AAlEH,oCAmEC;AAlEC;;;GAGG;AACqB,oBAAO,GAAG,IAAI,+BAAiB,EAAS,CAAC","sourcesContent":["import { AsyncLocalStorage } from \"async_hooks\";\n\n/**\n * Type representing the store object used in AsyncLocalStorage.\n * Keys must be unique symbols to ensure isolation and prevent collisions.\n */\nexport interface Store {\n  [key: symbol]: unknown;\n}\n\n/**\n * Predefined symbols used as keys in AsyncLocalStorage.\n * Add new symbols here to avoid duplication.\n */\nexport const StoreKeys = {\n  LOGGER: Symbol(\"logger\"),\n  REQUEST_ID: Symbol(\"requestId\"),\n};\n\n/**\n * Retrieves the current request ID from the async context, if available.\n *\n * @returns {string | undefined} The request ID string or undefined if not present in the current context.\n */\nexport function getRequestId(): string | undefined {\n  return ContextStore.get<string>(StoreKeys.REQUEST_ID);\n}\n\n/**\n * ContextStore manages per-request scoped context using AsyncLocalStorage.\n * It allows storing and retrieving data across async calls (e.g., request ID, logger).\n *\n * Example (Express middleware):\n * ```\n * // Middleware to initialize context and logger\n * app.use((req, res, next) => {\n *   const requestId = req.headers[\"x-request-id\"]?.toString() || crypto.randomUUID();\n *   ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n *     ContextStore.set(StoreKeys.LOGGER, getLogger().child({ reqId: requestId }));\n *     next();\n *   });\n * });\n * ```\n */\nexport class ContextStore {\n  /**\n   * The underlying AsyncLocalStorage instance for context.\n   * @private\n   */\n  private static readonly storage = new AsyncLocalStorage<Store>();\n\n  /**\n   * Returns the raw AsyncLocalStorage instance for advanced access.\n   *\n   * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.\n   */\n  static getInstance(): AsyncLocalStorage<Store> {\n    return this.storage;\n  }\n\n  /**\n   * Retrieves a value from the async context store by symbol key.\n   *\n   * @typeParam T - The expected return type of the value.\n   * @param {symbol} key - Unique symbol used as the store key.\n   * @returns {T | undefined} The value found (typed) or undefined if not present.\n   */\n  static get<T>(key: symbol): T | undefined {\n    const store = this.storage.getStore();\n    return store?.[key] as T | undefined;\n  }\n\n  /**\n   * Sets a value in the current context store by symbol key.\n   *\n   * @typeParam T - The value type to set.\n   * @param {symbol} key - Unique symbol key.\n   * @param {T} value - Value to set in context.\n   * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).\n   */\n  static set<T>(key: symbol, value: T): void {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error(\n        `Failed to set ${String(key)}: AsyncLocalStorage store is not initialized.`,\n      );\n    }\n    store[key] = value;\n  }\n\n  /**\n   * Retrieves the entire context store object for the current async context.\n   *\n   * @returns {Store | undefined} The current store object or undefined if called outside a context.\n   */\n  static getAll(): Store | undefined {\n    return this.storage.getStore();\n  }\n\n  /**\n   * Initializes a new async context and executes a callback within it.\n   * This must be called at the beginning of a request or logical async flow.\n   *\n   * @typeParam T - The callback's return type.\n   * @param {Store} store - The initial key-value store object.\n   * @param {() => T} callback - The function to run within the new context.\n   * @returns {T} The result of the callback function.\n   */\n  static run<T>(store: Store, callback: () => T): T {\n    return this.storage.run(store, callback);\n  }\n}\n"]}
+{"version":3,"file":"context-store.utils.js","sourceRoot":"","sources":["../../../src/utils/context-store.utils.ts"],"names":[],"mappings":";;;AA4BA,oCAEC;AAQD,wCAEC;AAxCD,6CAAgD;AAUhD;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC,SAAS,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC,eAAe,CAAC;CACxC,CAAC;AAEF;;;;GAIG;AACH,SAAgB,YAAY;IAC1B,OAAO,YAAY,CAAC,GAAG,CAAS,iBAAS,CAAC,UAAU,CAAC,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc,CAAI,GAAW;IAC3C,OAAO,YAAY,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAa,YAAY;IAOvB;;;;OAIG;IACH,MAAM,CAAC,WAAW;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAI,GAAW;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAG,GAAG,CAAkB,CAAC;IACvC,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;QAC/F,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,GAAG,CAAI,KAAY,EAAE,QAAiB;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,GAAW;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,KAAK,SAAS,IAAI,GAAG,IAAI,KAAK,CAAC;IAC7C,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,GAAW;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;QAClG,CAAC;QACD,OAAO,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,KAAK,CAAC,MAAwC;QACnD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;YACjD,KAAK,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IACD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,SAAS,CAAI,GAAW,EAAE,KAAc,EAAE,QAAiB;QAChE,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,4EAA4E,CAAC,CAAC;QAChG,CAAC;QAED,sBAAsB;QACtB,MAAM,WAAW,GAAG,GAAG,IAAI,KAAK,CAAC;QACjC,MAAM,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAEjC,sBAAsB;QACtB,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAEnB,IAAI,CAAC;YACH,eAAe;YACf,OAAO,QAAQ,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,yBAAyB;YACzB,IAAI,WAAW,EAAE,CAAC;gBAChB,KAAK,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC;YAC7B,CAAC;iBAAM,CAAC;gBACN,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAI,SAA2C,EAAE,QAAiB;QAC7E,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;QAEnD,qDAAqD;QACrD,MAAM,QAAQ,qBAAe,YAAY,CAAE,CAAC;QAE5C,iBAAiB;QACjB,MAAM,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;YACpD,QAAQ,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QAEH,0BAA0B;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,uBAAuB,CAAC,uBAAuE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;QAC9G,OAAO,CAAC,GAAQ,EAAE,GAAQ,EAAE,IAAS,EAAE,EAAE;YACvC,MAAM,aAAa,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;YAChD,YAAY,CAAC,GAAG,CAAC,aAAsB,EAAE,IAAI,CAAC,CAAC;QACjD,CAAC,CAAC;IACJ,CAAC;;AAlLH,oCAmLC;AAlLC;;;GAGG;AACqB,oBAAO,GAAG,IAAI,+BAAiB,EAAS,CAAC;AAgLnE;;;;GAIG;AACH,MAAa,eAAe;IAC1B;;;;;OAKG;IACH,YACU,MAAc,EACd,YAAgB;QADhB,WAAM,GAAN,MAAM,CAAQ;QACd,iBAAY,GAAZ,YAAY,CAAI;IACvB,CAAC;IAEJ;;;;OAIG;IACH,GAAG;QACD,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAI,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/C,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;IACzD,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,KAAQ;QACV,YAAY,CAAC,GAAG,CAAI,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;CACF;AAhDD,0CAgDC","sourcesContent":["import { AsyncLocalStorage } from 'async_hooks';\n\n/**\n * Type representing the store object used in AsyncLocalStorage.\n * Keys must be unique symbols to ensure isolation and prevent collisions.\n */\nexport interface Store {\n  [key: symbol]: unknown;\n}\n\n/**\n * Predefined symbols used as keys in AsyncLocalStorage.\n * Add new symbols here to avoid duplication.\n */\nexport const StoreKeys = {\n  LOGGER: Symbol('logger'),\n  REQUEST_ID: Symbol('requestId'),\n  USER_ID: Symbol('userId'),\n  TENANT_ID: Symbol('tenantId'),\n  TRACE_ID: Symbol('traceId'),\n  CORRELATION_ID: Symbol('correlationId')\n};\n\n/**\n * Retrieves the current request ID from the async context, if available.\n *\n * @returns {string | undefined} The request ID string or undefined if not present in the current context.\n */\nexport function getRequestId(): string | undefined {\n  return ContextStore.get<string>(StoreKeys.REQUEST_ID);\n}\n\n/**\n * Type-safe getter for common context values.\n *\n * @param key The store key symbol\n * @returns The typed value from the store\n */\nexport function getFromContext<T>(key: symbol): T | undefined {\n  return ContextStore.get<T>(key);\n}\n\n/**\n * ContextStore manages per-request scoped context using AsyncLocalStorage.\n * It allows storing and retrieving data across async calls (e.g., request ID, logger).\n *\n * Example (Express middleware):\n * ```\n * // Middleware to initialize context and logger\n * app.use((req, res, next) => {\n *   const requestId = req.headers[\"x-request-id\"]?.toString() || crypto.randomUUID();\n *   ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {\n *     ContextStore.set(StoreKeys.LOGGER, getLogger().child({ reqId: requestId }));\n *     next();\n *   });\n * });\n * ```\n */\nexport class ContextStore {\n  /**\n   * The underlying AsyncLocalStorage instance for context.\n   * @private\n   */\n  private static readonly storage = new AsyncLocalStorage<Store>();\n\n  /**\n   * Returns the raw AsyncLocalStorage instance for advanced access.\n   *\n   * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.\n   */\n  static getInstance(): AsyncLocalStorage<Store> {\n    return this.storage;\n  }\n\n  /**\n   * Retrieves a value from the async context store by symbol key.\n   *\n   * @typeParam T - The expected return type of the value.\n   * @param {symbol} key - Unique symbol used as the store key.\n   * @returns {T | undefined} The value found (typed) or undefined if not present.\n   */\n  static get<T>(key: symbol): T | undefined {\n    const store = this.storage.getStore();\n    return store?.[key] as T | undefined;\n  }\n\n  /**\n   * Sets a value in the current context store by symbol key.\n   *\n   * @typeParam T - The value type to set.\n   * @param {symbol} key - Unique symbol key.\n   * @param {T} value - Value to set in context.\n   * @throws {Error} If called outside an active context (not within a .run call or in the wrong async boundaries).\n   */\n  static set<T>(key: symbol, value: T): void {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error(`Failed to set ${String(key)}: AsyncLocalStorage store is not initialized.`);\n    }\n    store[key] = value;\n  }\n\n  /**\n   * Retrieves the entire context store object for the current async context.\n   *\n   * @returns {Store | undefined} The current store object or undefined if called outside a context.\n   */\n  static getAll(): Store | undefined {\n    return this.storage.getStore();\n  }\n\n  /**\n   * Initializes a new async context and executes a callback within it.\n   * This must be called at the beginning of a request or logical async flow.\n   *\n   * @typeParam T - The callback's return type.\n   * @param {Store} store - The initial key-value store object.\n   * @param {() => T} callback - The function to run within the new context.\n   * @returns {T} The result of the callback function.\n   */\n  static run<T>(store: Store, callback: () => T): T {\n    return this.storage.run(store, callback);\n  }\n\n  /**\n   * Checks if a key exists in the current context store.\n   *\n   * @param {symbol} key - The symbol key to check.\n   * @returns {boolean} True if the key exists, false otherwise.\n   */\n  static has(key: symbol): boolean {\n    const store = this.storage.getStore();\n    return store !== undefined && key in store;\n  }\n\n  /**\n   * Removes a value from the current context store by symbol key.\n   *\n   * @param {symbol} key - The symbol key to delete.\n   * @returns {boolean} True if the key was deleted, false if the key wasn't found or no active context.\n   * @throws {Error} If called outside an active context.\n   */\n  static delete(key: symbol): boolean {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error(`Failed to delete ${String(key)}: AsyncLocalStorage store is not initialized.`);\n    }\n    return delete store[key];\n  }\n\n  /**\n   * Updates multiple values in the current context store at once.\n   *\n   * @param {Partial<Record<symbol, unknown>>} values - Object containing symbol keys and values to update.\n   * @throws {Error} If called outside an active context.\n   */\n  static patch(values: Partial<Record<symbol, unknown>>): void {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error('Failed to patch: AsyncLocalStorage store is not initialized.');\n    }\n    Object.getOwnPropertySymbols(values).forEach(key => {\n      store[key] = values[key];\n    });\n  }\n  /**\n   * Executes a callback with a temporary store value that only exists during execution.\n   * Original store is restored after callback completes.\n   *\n   * @typeParam T - The callback's return type.\n   * @param {symbol} key - The symbol key to temporarily set.\n   * @param {unknown} value - The temporary value.\n   * @param {() => T} callback - The function to execute with the temporary value.\n   * @returns {T} The result of the callback function.\n   * @throws {Error} If called outside an active context.\n   */\n  static withValue<T>(key: symbol, value: unknown, callback: () => T): T {\n    const store = this.storage.getStore();\n    if (!store) {\n      throw new Error(`Failed to set temporary value: AsyncLocalStorage store is not initialized.`);\n    }\n\n    // Save original value\n    const hasOriginal = key in store;\n    const originalValue = store[key];\n\n    // Set temporary value\n    store[key] = value;\n\n    try {\n      // Run callback\n      return callback();\n    } finally {\n      // Restore original value\n      if (hasOriginal) {\n        store[key] = originalValue;\n      } else {\n        delete store[key];\n      }\n    }\n  }\n\n  /**\n   * Creates a new context that inherits values from the current context.\n   *\n   * @typeParam T - The callback's return type.\n   * @param {Partial<Record<symbol, unknown>>} newValues - New values to add to or override in the context.\n   * @param {() => T} callback - The function to execute in the new context.\n   * @returns {T} The result of the callback function.\n   */\n  static extend<T>(newValues: Partial<Record<symbol, unknown>>, callback: () => T): T {\n    const currentStore = this.storage.getStore() || {};\n\n    // Create new store with current values plus new ones\n    const newStore: Store = { ...currentStore };\n\n    // Add new values\n    Object.getOwnPropertySymbols(newValues).forEach(key => {\n      newStore[key] = newValues[key];\n    });\n\n    // Run with extended store\n    return this.storage.run(newStore, callback);\n  }\n\n  /**\n   * Creates Express middleware that initializes a context for each request.\n   *\n   * @param {(req: any) => Partial<Record<symbol, unknown>>} initialValuesFactory - Function that returns initial context values.\n   * @returns Express middleware function.\n   */\n  static createExpressMiddleware(initialValuesFactory: (req: any) => Partial<Record<symbol, unknown>> = () => ({})) {\n    return (req: any, res: any, next: any) => {\n      const initialValues = initialValuesFactory(req);\n      ContextStore.run(initialValues as Store, next);\n    };\n  }\n}\n\n/**\n * Type-safe wrapper for accessing and modifying context values with specific types.\n *\n * @typeParam T - The value type.\n */\nexport class TypedContextKey<T> {\n  /**\n   * Creates a new typed context key.\n   *\n   * @param symbol - The unique symbol for this key\n   * @param defaultValue - Optional default value if key is not found\n   */\n  constructor(\n    private symbol: symbol,\n    private defaultValue?: T\n  ) {}\n\n  /**\n   * Gets the current value for this key.\n   *\n   * @returns The value or defaultValue if not found\n   */\n  get(): T | undefined {\n    const value = ContextStore.get<T>(this.symbol);\n    return value !== undefined ? value : this.defaultValue;\n  }\n\n  /**\n   * Sets the value for this key.\n   *\n   * @param value The value to set\n   */\n  set(value: T): void {\n    ContextStore.set<T>(this.symbol, value);\n  }\n\n  /**\n   * Checks if this key exists in the context.\n   *\n   * @returns True if the key exists\n   */\n  exists(): boolean {\n    return ContextStore.has(this.symbol);\n  }\n\n  /**\n   * Deletes this key from the context.\n   *\n   * @returns True if the key was deleted\n   */\n  delete(): boolean {\n    return ContextStore.delete(this.symbol);\n  }\n}\n"]}

package/build/src/utils/crypto.utils.d.ts

@@ -1,4 +1,5 @@
-import { BinaryToTextEncoding } from "crypto";
+import { BinaryToTextEncoding, CipherGCMTypes } from 'crypto';
+export type BufferEncoding = 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'utf-16le' | 'ucs2' | 'ucs-2' | 'base64' | 'base64url' | 'latin1' | 'binary' | 'hex';
 /**
  * Generates an HMAC digest using the specified algorithm and secret key.
  *
@@ -8,7 +9,7 @@ import { BinaryToTextEncoding } from "crypto";
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
  * @returns {string} HMAC digest as a string.
  */
-export declare const hmac: (algorithm: string, input: string, secret: string, encoding?: BinaryToTextEncoding) => string;
+export declare function hmac(algorithm: string, input: string, secret: string, encoding?: BinaryToTextEncoding): string;
 /**
  * Generates a hash digest using the specified algorithm.
  *
@@ -17,7 +18,7 @@ export declare const hmac: (algorithm: string, input: string, secret: string, en
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
  * @returns {string} Hash digest as a string.
  */
-export declare const hash: (algorithm: string, input: string, encoding?: BinaryToTextEncoding) => string;
+export declare function hash(algorithm: string, input: string, encoding?: BinaryToTextEncoding): string;
 /**
  * Generates an HMAC-SHA256 digest.
  *
@@ -25,7 +26,7 @@ export declare const hash: (algorithm: string, input: string, encoding?: BinaryT
  * @param {string} secret - The secret key.
  * @returns {string} SHA-256 HMAC digest as a string.
  */
-export declare const sha256Hmac: (input: string, secret: string) => string;
+export declare function sha256Hmac(input: string, secret: string): string;
 /**
  * Generates a SHA1 hash digest.
  *
@@ -33,7 +34,7 @@ export declare const sha256Hmac: (input: string, secret: string) => string;
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
  * @returns {string} SHA-1 hash as a string.
  */
-export declare const sha1: (input: string, encoding?: BinaryToTextEncoding) => string;
+export declare function sha1(input: string, encoding?: BinaryToTextEncoding): string;
 /**
  * Generates a SHA256 hash digest.
  *
@@ -41,18 +42,119 @@ export declare const sha1: (input: string, encoding?: BinaryToTextEncoding) => s
  * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
  * @returns {string} SHA-256 hash as a string.
  */
-export declare const sha256: (input: string, encoding?: BinaryToTextEncoding) => string;
+export declare function sha256(input: string, encoding?: BinaryToTextEncoding): string;
 /**
  * Generates an MD5 hash digest.
  *
  * @param {string} input - The string to hash.
  * @returns {string} MD5 hash as a string.
  */
-export declare const md5: (input: string) => string;
+export declare function md5(input: string): string;
 /**
  * Generates a cryptographically strong random string by hashing a random UUID with SHA-256.
  *
  * @returns {string} Random string hashed with SHA-256 (hex encoding).
  */
-export declare const randomString: () => string;
+export declare function randomString(): string;
+/**
+ * Generates a secure random buffer of specified byte length.
+ *
+ * @param {number} [byteLength=32] - Number of random bytes to generate.
+ * @returns {Buffer} Buffer containing random bytes.
+ */
+export declare function generateRandomBytes(byteLength?: number): Buffer;
+/**
+ * Generates a secure random string of specified byte length with specified encoding.
+ *
+ * @param {number} [byteLength=32] - Number of random bytes to generate.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
+ * @returns {string} Random string in specified encoding.
+ */
+export declare function generateRandomBytesAsString(byteLength?: number, encoding?: BinaryToTextEncoding): string;
+/**
+ * Generates a secure API key with a specified format.
+ *
+ * @param {string} [prefix=''] - Optional prefix for the key.
+ * @param {number} [byteLength=24] - Number of random bytes to generate.
+ * @returns {string} Formatted API key.
+ */
+export declare function generateApiKey(prefix?: string, byteLength?: number): string;
+/**
+ * Compares two strings, arrays, or buffers in constant time to prevent timing attacks.
+ *
+ * @param {string | Buffer | Uint8Array} a - First value to compare
+ * @param {string | Buffer | Uint8Array} b - Second value to compare
+ * @returns {boolean} True if values are equal
+ */
+export declare function safeCompare(a: string | Buffer | Uint8Array, b: string | Buffer | Uint8Array): boolean;
+/**
+ * Interface for encryption options
+ */
+export interface EncryptionOptions {
+    /** Algorithm to use (default: aes-256-gcm) */
+    algorithm?: CipherGCMTypes;
+    /** Input encoding for plaintext if string (default: utf8) */
+    inputEncoding?: BufferEncoding;
+    /** Output encoding for ciphertext (default: hex) */
+    outputEncoding?: BinaryToTextEncoding;
+}
+/**
+ * Interface for decryption options
+ */
+export interface DecryptionOptions {
+    /** Algorithm to use (default: aes-256-gcm) */
+    algorithm?: CipherGCMTypes;
+    /** Input encoding for ciphertext if string (default: hex) */
+    inputEncoding?: BinaryToTextEncoding;
+    /** Output encoding for plaintext (default: utf8) */
+    outputEncoding?: BufferEncoding;
+}
+/**
+ * Result of encryption operation including all data needed for decryption
+ */
+export interface EncryptionResult {
+    /** Encrypted data (string or Buffer based on options) */
+    ciphertext: string | Buffer;
+    /** Initialization vector */
+    iv: Buffer;
+    /** Authentication tag (for GCM mode) */
+    authTag?: Buffer;
+    /** Algorithm used */
+    algorithm: string;
+}
+/**
+ * Encrypts data using a symmetric key with secure defaults (AES-256-GCM).
+ *
+ * @param {string | Buffer} data - Data to encrypt
+ * @param {string | Buffer} key - Encryption key or passphrase
+ * @param {EncryptionOptions} [options] - Encryption options
+ * @returns {Promise<EncryptionResult>} Encrypted data with metadata
+ */
+export declare function encrypt(data: string | Buffer, key: string | Buffer, options?: EncryptionOptions): Promise<EncryptionResult>;
+/**
+ * Decrypts data that was encrypted with the encrypt function.
+ *
+ * @param {EncryptionResult} encryptedData - The encrypted data and metadata
+ * @param {string | Buffer} key - Decryption key or passphrase
+ * @param {DecryptionOptions} [options] - Decryption options
+ * @returns {Promise<string | Buffer>} Decrypted data
+ */
+export declare function decrypt(encryptedData: EncryptionResult, key: string | Buffer, options?: DecryptionOptions): Promise<string | Buffer>;
+/**
+ * Creates a signed token with an expiration time and payload.
+ *
+ * @param {object} payload - Data to include in the token
+ * @param {string} secret - Secret key for signing
+ * @param {number} [expiresInSeconds=3600] - Token expiration in seconds
+ * @returns {string} Signed token string
+ */
+export declare function createSignedToken(payload: Record<string, any>, secret: string, expiresInSeconds?: number): string;
+/**
+ * Verifies and decodes a signed token.
+ *
+ * @param {string} token - The token to verify
+ * @param {string} secret - Secret key for verification
+ * @returns {object | null} Decoded payload if valid, null if invalid
+ */
+export declare function verifySignedToken(token: string, secret: string): Record<string, any> | null;
 //# sourceMappingURL=crypto.utils.d.ts.map