@catbee/utils 0.0.6 → 0.0.8-next.0

package/build/esnext/utils/cache.utils.js

@@ -1,293 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-import { config } from '../config';
-/**
- * An in-memory cache with time-to-live (TTL) support for each entry.
- *
- * @typeParam K - Type of the key.
- * @typeParam V - Type of the value.
- *
- * @example
- * const cache = new TTLCache<string, number>({ ttlMs: 1000 });
- * cache.set("x", 123);
- * const value = cache.get("x"); // 123
- */
-export class TTLCache {
-    /**
-     * @param options - Configuration options for the cache
-     */
-    constructor(options = {}) {
-        var _a;
-        this.cache = new Map();
-        this.ttlMs = (_a = options.ttlMs) !== null && _a !== void 0 ? _a : config.cache.defaultTtl;
-        this.maxSize = options.maxSize;
-        // Setup auto-cleanup if enabled
-        const autoCleanupMs = options.autoCleanupMs;
-        if (autoCleanupMs && autoCleanupMs > 0) {
-            this.cleanupInterval = setInterval(() => {
-                this.cleanup();
-            }, autoCleanupMs);
-        }
-    }
-    /**
-     * Sets a key-value pair in the cache with the default TTL.
-     *
-     * @param key - The key to set.
-     * @param value - The value to associate with the key.
-     */
-    set(key, value) {
-        this.setWithTTL(key, value, this.ttlMs);
-    }
-    /**
-     * Sets a key-value pair in the cache with a custom TTL.
-     *
-     * @param key - The key to set.
-     * @param value - The value to associate with the key.
-     * @param ttlMs - Time-to-live in milliseconds.
-     */
-    setWithTTL(key, value, ttlMs) {
-        const now = Date.now();
-        const expiresAt = now + ttlMs;
-        if (this.cache.has(key)) {
-            this.cache.delete(key); // remove old entry to maintain LRU order
-        }
-        this.cache.set(key, { value, expiresAt, lastAccessed: now });
-        if (this.maxSize && this.cache.size > this.maxSize) {
-            this.evictLRU();
-        }
-    }
-    /**
-     * Retrieves the value for a given key if it hasn't expired.
-     *
-     * @param key - The key to retrieve.
-     * @returns The cached value, or undefined if not found or expired.
-     */
-    get(key) {
-        const entry = this.cache.get(key);
-        if (!entry)
-            return undefined;
-        const now = Date.now();
-        if (now > entry.expiresAt) {
-            this.cache.delete(key);
-            return undefined;
-        }
-        // Update lastAccessed and move key to the end (most recently used)
-        entry.lastAccessed = now;
-        // Re-insert to end of Map to maintain LRU order
-        this.cache.delete(key);
-        this.cache.set(key, entry);
-        return entry.value;
-    }
-    /**
-     * Retrieves or computes a value if it's not in the cache or has expired.
-     *
-     * @param key - The key to retrieve
-     * @param producer - Function to generate the value if not cached
-     * @param ttlMs - Optional custom TTL for the computed value
-     * @returns The cached or computed value
-     */
-    async getOrCompute(key, producer, ttlMs) {
-        const value = this.get(key);
-        if (value !== undefined)
-            return value;
-        const newValue = await producer();
-        this.setWithTTL(key, newValue, ttlMs !== null && ttlMs !== void 0 ? ttlMs : this.ttlMs);
-        return newValue;
-    }
-    /**
-     * Checks if the key exists and hasn't expired.
-     *
-     * @param key - The key to check.
-     * @returns `true` if key exists and is valid, otherwise `false`.
-     */
-    has(key) {
-        return this.get(key) !== undefined;
-    }
-    /**
-     * Deletes a key from the cache.
-     *
-     * @param key - The key to delete.
-     * @returns `true` if the key existed and was removed, `false` otherwise.
-     */
-    delete(key) {
-        return this.cache.delete(key);
-    }
-    /**
-     * Clears all entries from the cache.
-     */
-    clear() {
-        this.cache.clear();
-    }
-    /**
-     * Returns the number of entries currently in the cache (includes expired entries until next access/cleanup).
-     *
-     * @returns Number of items in the cache (may include expired keys).
-     */
-    size() {
-        return this.cache.size;
-    }
-    /**
-     * Set multiple key-value pairs at once with the default TTL.
-     *
-     * @param entries - Array of [key, value] tuples to set
-     */
-    setMany(entries) {
-        for (const [key, value] of entries) {
-            this.set(key, value);
-        }
-    }
-    /**
-     * Get multiple values at once.
-     *
-     * @param keys - Array of keys to retrieve
-     * @returns Array of values (undefined for keys that don't exist or expired)
-     */
-    getMany(keys) {
-        return keys.map(key => this.get(key));
-    }
-    /**
-     * Removes all expired entries from the cache.
-     *
-     * @returns Number of entries removed.
-     */
-    cleanup() {
-        let removed = 0;
-        const now = Date.now();
-        for (const [key, entry] of this.cache.entries()) {
-            if (now > entry.expiresAt) {
-                this.cache.delete(key);
-                removed++;
-            }
-        }
-        return removed;
-    }
-    /**
-     * Returns an iterator of all current valid [key, value] pairs.
-     *
-     * @returns IterableIterator<[K, V]>
-     */
-    *entries() {
-        for (const [key, entry] of this.cache.entries()) {
-            if (Date.now() <= entry.expiresAt) {
-                yield [key, entry.value];
-            }
-        }
-    }
-    /**
-     * Returns an iterator of all current valid keys.
-     *
-     * @returns IterableIterator<K>
-     */
-    *keys() {
-        for (const [key, entry] of this.cache.entries()) {
-            if (Date.now() <= entry.expiresAt) {
-                yield key;
-            }
-        }
-    }
-    /**
-     * Returns an iterator of all current valid values.
-     *
-     * @returns IterableIterator<V>
-     */
-    *values() {
-        for (const entry of this.cache.values()) {
-            if (Date.now() <= entry.expiresAt) {
-                yield entry.value;
-            }
-        }
-    }
-    /**
-     * Extends the expiration of a key by the specified time or default TTL.
-     *
-     * @param key - The key to refresh
-     * @param ttlMs - Optional new TTL in milliseconds (uses default if not specified)
-     * @returns true if the key was found and refreshed, false otherwise
-     */
-    refresh(key, ttlMs) {
-        const entry = this.cache.get(key);
-        if (!entry)
-            return false;
-        const now = Date.now();
-        if (now > entry.expiresAt) {
-            this.cache.delete(key);
-            return false;
-        }
-        entry.expiresAt = now + (ttlMs !== null && ttlMs !== void 0 ? ttlMs : this.ttlMs);
-        entry.lastAccessed = now;
-        return true;
-    }
-    /**
-     * Returns a snapshot of cache stats.
-     *
-     * @returns Object containing cache statistics
-     */
-    stats() {
-        const now = Date.now();
-        let expired = 0;
-        let valid = 0;
-        for (const entry of this.cache.values()) {
-            if (now > entry.expiresAt) {
-                expired++;
-            }
-            else {
-                valid++;
-            }
-        }
-        return {
-            size: this.cache.size,
-            validEntries: valid,
-            expiredEntries: expired,
-            maxSize: this.maxSize
-        };
-    }
-    /**
-     * Stop the auto-cleanup interval if it's running.
-     */
-    destroy() {
-        if (this.cleanupInterval) {
-            clearInterval(this.cleanupInterval);
-            this.cleanupInterval = undefined;
-        }
-    }
-    /**
-     * Evict the least recently used entry from the cache.
-     * @private
-     */
-    evictLRU() {
-        const now = Date.now();
-        // Remove all expired items first
-        for (const [key, entry] of Array.from(this.cache.entries())) {
-            if (now > entry.expiresAt) {
-                this.cache.delete(key);
-            }
-        }
-        // Evict oldest entries until within max size
-        while (this.maxSize && this.cache.size > this.maxSize) {
-            const oldestKey = this.cache.keys().next().value;
-            this.cache.delete(oldestKey);
-        }
-    }
-}
-//# sourceMappingURL=cache.utils.js.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"cache.utils.js","sourceRoot":"","sources":["../../../src/utils/cache.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { 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\n    if (this.cache.has(key)) {\n      this.cache.delete(key); // remove old entry to maintain LRU order\n    }\n\n    this.cache.set(key, { value, expiresAt, lastAccessed: now });\n\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 lastAccessed and move key to the end (most recently used)\n    entry.lastAccessed = now;\n    // Re-insert to end of Map to maintain LRU order\n    this.cache.delete(key);\n    this.cache.set(key, entry);\n\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    const now = Date.now();\n\n    // Remove all expired items first\n    for (const [key, entry] of Array.from(this.cache.entries())) {\n      if (now > entry.expiresAt) {\n        this.cache.delete(key);\n      }\n    }\n\n    // Evict oldest entries until within max size\n    while (this.maxSize && this.cache.size > this.maxSize) {\n      const oldestKey = this.cache.keys().next().value;\n      this.cache.delete(oldestKey as K);\n    }\n  }\n}\n"]}

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

@@ -1,186 +0,0 @@
-import { AsyncLocalStorage } from 'async_hooks';
-/**
- * Type representing the store object used in AsyncLocalStorage.
- * Keys must be unique symbols to ensure isolation and prevent collisions.
- */
-export interface Store {
-    [key: symbol]: unknown;
-}
-/**
- * Predefined symbols used as keys in AsyncLocalStorage.
- * Add new symbols here to avoid duplication.
- */
-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.
- *
- * @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).
- *
- * Example (Express middleware):
- * ```
- * // Middleware to initialize context and logger
- * app.use((req, res, next) => {
- *   const requestId = req.headers["x-request-id"]?.toString() || crypto.randomUUID();
- *   ContextStore.run({ [StoreKeys.REQUEST_ID]: requestId }, () => {
- *     ContextStore.set(StoreKeys.LOGGER, getLogger().child({ requestId }));
- *     next();
- *   });
- * });
- * ```
- */
-export declare class ContextStore {
-    /**
-     * The underlying AsyncLocalStorage instance for context.
-     * @private
-     */
-    private static readonly storage;
-    /**
-     * Returns the raw AsyncLocalStorage instance for advanced access.
-     *
-     * @returns {AsyncLocalStorage<Store>} The AsyncLocalStorage instance.
-     */
-    static getInstance(): AsyncLocalStorage<Store>;
-    /**
-     * Retrieves a value from the async context store by symbol key.
-     *
-     * @typeParam T - The expected return type of the value.
-     * @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;
-    /**
-     * Sets a value in the current context store by symbol key.
-     *
-     * @typeParam T - The value type to set.
-     * @param {symbol} key - Unique symbol key.
-     * @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;
-    /**
-     * Retrieves the entire context store object for the current async context.
-     *
-     * @returns {Store | undefined} The current store object or undefined if called outside a context.
-     */
-    static getAll(): Store | undefined;
-    /**
-     * Initializes a new async context and executes a callback within it.
-     * This must be called at the beginning of a request or logical async flow.
-     *
-     * @typeParam T - The callback's return type.
-     * @param {Store} store - The initial key-value store object.
-     * @param {() => T} callback - The function to run within the new context.
-     * @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