@catbee/utils 2.0.4 → 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/cache/index.cjs

@@ -33,6 +33,7 @@ var TTLCache = class {
     __name(this, "TTLCache");
   }
   cache = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
   ttlMs;
   maxSize;
   cleanupInterval;
@@ -90,7 +91,7 @@ var TTLCache = class {
     const entry = this.cache.get(key);
     if (!entry) return void 0;
     const now = Date.now();
-    if (now > entry.expiresAt) {
+    if (now >= entry.expiresAt) {
       this.cache.delete(key);
       return void 0;
     }
@@ -102,17 +103,31 @@ var TTLCache = class {
   /**
   * Retrieves or computes a value if it's not in the cache or has expired.
   *
+  * Concurrent calls for the same key share the same producer promise,
+  * preventing duplicate computations while the value is being generated.
+  *
   * @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 !== void 0) return value;
-    const newValue = await producer();
-    this.setWithTTL(key, newValue, ttlMs ?? this.ttlMs);
-    return newValue;
+    const cached = this.get(key);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const pending = this.pending.get(key);
+    if (pending) {
+      return pending;
+    }
+    const promise = Promise.resolve().then(producer).then((value) => {
+      this.setWithTTL(key, value, ttlMs ?? this.ttlMs);
+      return value;
+    }).finally(() => {
+      this.pending.delete(key);
+    });
+    this.pending.set(key, promise);
+    return promise;
   }
   /**
   * Checks if the key exists and hasn't expired.
@@ -174,7 +189,7 @@ var TTLCache = class {
     let removed = 0;
     const now = Date.now();
     for (const [key, entry] of this.cache.entries()) {
-      if (now > entry.expiresAt) {
+      if (now >= entry.expiresAt) {
         this.cache.delete(key);
         removed++;
       }
@@ -188,7 +203,7 @@ var TTLCache = class {
   */
   *entries() {
     for (const [key, entry] of this.cache.entries()) {
-      if (Date.now() <= entry.expiresAt) {
+      if (Date.now() < entry.expiresAt) {
         yield [
           key,
           entry.value
@@ -203,7 +218,7 @@ var TTLCache = class {
   */
   *keys() {
     for (const [key, entry] of this.cache.entries()) {
-      if (Date.now() <= entry.expiresAt) {
+      if (Date.now() < entry.expiresAt) {
         yield key;
       }
     }
@@ -215,7 +230,7 @@ var TTLCache = class {
   */
   *values() {
     for (const entry of this.cache.values()) {
-      if (Date.now() <= entry.expiresAt) {
+      if (Date.now() < entry.expiresAt) {
         yield entry.value;
       }
     }
@@ -231,12 +246,14 @@ var TTLCache = class {
     const entry = this.cache.get(key);
     if (!entry) return false;
     const now = Date.now();
-    if (now > entry.expiresAt) {
+    if (now >= entry.expiresAt) {
       this.cache.delete(key);
       return false;
     }
     entry.expiresAt = now + (ttlMs ?? this.ttlMs);
     entry.lastAccessed = now;
+    this.cache.delete(key);
+    this.cache.set(key, entry);
     return true;
   }
   /**
@@ -249,7 +266,7 @@ var TTLCache = class {
     let expired = 0;
     let valid = 0;
     for (const entry of this.cache.values()) {
-      if (now > entry.expiresAt) {
+      if (now >= entry.expiresAt) {
         expired++;
       } else {
         valid++;
@@ -277,14 +294,17 @@ var TTLCache = class {
   */
   evictLRU() {
     const now = Date.now();
-    for (const [key, entry] of Array.from(this.cache.entries())) {
-      if (now > entry.expiresAt) {
+    for (const [key, entry] of this.cache.entries()) {
+      if (now >= entry.expiresAt) {
         this.cache.delete(key);
       }
     }
     while (this.maxSize && this.cache.size > this.maxSize) {
-      const oldestKey = this.cache.keys().next().value;
-      this.cache.delete(oldestKey);
+      const next = this.cache.keys().next();
+      if (next.done) {
+        break;
+      }
+      this.cache.delete(next.value);
     }
   }
 };

package/cache/index.d.ts

@@ -41,11 +41,12 @@ interface TTLCacheOptions {
  *
  * @example
  * const cache = new TTLCache<string, number>({ ttlMs: 1000 });
- * cache.set("x", 123);
- * const value = cache.get("x"); // 123
+ * cache.set('x', 123);
+ * const value = cache.get('x'); // 123
  */
 declare class TTLCache<K, V> {
     private readonly cache;
+    private readonly pending;
     private readonly ttlMs;
     private readonly maxSize?;
     private cleanupInterval?;
@@ -78,6 +79,9 @@ declare class TTLCache<K, V> {
     /**
      * Retrieves or computes a value if it's not in the cache or has expired.
      *
+     * Concurrent calls for the same key share the same producer promise,
+     * preventing duplicate computations while the value is being generated.
+     *
      * @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

package/cache/index.mjs

@@ -31,6 +31,7 @@ var TTLCache = class {
     __name(this, "TTLCache");
   }
   cache = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
   ttlMs;
   maxSize;
   cleanupInterval;
@@ -88,7 +89,7 @@ var TTLCache = class {
     const entry = this.cache.get(key);
     if (!entry) return void 0;
     const now = Date.now();
-    if (now > entry.expiresAt) {
+    if (now >= entry.expiresAt) {
       this.cache.delete(key);
       return void 0;
     }
@@ -100,17 +101,31 @@ var TTLCache = class {
   /**
   * Retrieves or computes a value if it's not in the cache or has expired.
   *
+  * Concurrent calls for the same key share the same producer promise,
+  * preventing duplicate computations while the value is being generated.
+  *
   * @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 !== void 0) return value;
-    const newValue = await producer();
-    this.setWithTTL(key, newValue, ttlMs ?? this.ttlMs);
-    return newValue;
+    const cached = this.get(key);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const pending = this.pending.get(key);
+    if (pending) {
+      return pending;
+    }
+    const promise = Promise.resolve().then(producer).then((value) => {
+      this.setWithTTL(key, value, ttlMs ?? this.ttlMs);
+      return value;
+    }).finally(() => {
+      this.pending.delete(key);
+    });
+    this.pending.set(key, promise);
+    return promise;
   }
   /**
   * Checks if the key exists and hasn't expired.
@@ -172,7 +187,7 @@ var TTLCache = class {
     let removed = 0;
     const now = Date.now();
     for (const [key, entry] of this.cache.entries()) {
-      if (now > entry.expiresAt) {
+      if (now >= entry.expiresAt) {
         this.cache.delete(key);
         removed++;
       }
@@ -186,7 +201,7 @@ var TTLCache = class {
   */
   *entries() {
     for (const [key, entry] of this.cache.entries()) {
-      if (Date.now() <= entry.expiresAt) {
+      if (Date.now() < entry.expiresAt) {
         yield [
           key,
           entry.value
@@ -201,7 +216,7 @@ var TTLCache = class {
   */
   *keys() {
     for (const [key, entry] of this.cache.entries()) {
-      if (Date.now() <= entry.expiresAt) {
+      if (Date.now() < entry.expiresAt) {
         yield key;
       }
     }
@@ -213,7 +228,7 @@ var TTLCache = class {
   */
   *values() {
     for (const entry of this.cache.values()) {
-      if (Date.now() <= entry.expiresAt) {
+      if (Date.now() < entry.expiresAt) {
         yield entry.value;
       }
     }
@@ -229,12 +244,14 @@ var TTLCache = class {
     const entry = this.cache.get(key);
     if (!entry) return false;
     const now = Date.now();
-    if (now > entry.expiresAt) {
+    if (now >= entry.expiresAt) {
       this.cache.delete(key);
       return false;
     }
     entry.expiresAt = now + (ttlMs ?? this.ttlMs);
     entry.lastAccessed = now;
+    this.cache.delete(key);
+    this.cache.set(key, entry);
     return true;
   }
   /**
@@ -247,7 +264,7 @@ var TTLCache = class {
     let expired = 0;
     let valid = 0;
     for (const entry of this.cache.values()) {
-      if (now > entry.expiresAt) {
+      if (now >= entry.expiresAt) {
         expired++;
       } else {
         valid++;
@@ -275,14 +292,17 @@ var TTLCache = class {
   */
   evictLRU() {
     const now = Date.now();
-    for (const [key, entry] of Array.from(this.cache.entries())) {
-      if (now > entry.expiresAt) {
+    for (const [key, entry] of this.cache.entries()) {
+      if (now >= entry.expiresAt) {
         this.cache.delete(key);
       }
     }
     while (this.maxSize && this.cache.size > this.maxSize) {
-      const oldestKey = this.cache.keys().next().value;
-      this.cache.delete(oldestKey);
+      const next = this.cache.keys().next();
+      if (next.done) {
+        break;
+      }
+      this.cache.delete(next.value);
     }
   }
 };

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;