@catbee/utils 2.0.5 → 2.2.0

package/context-store/index.mjs

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

package/healthz-server/index.cjs

@@ -0,0 +1,393 @@
+/*
+ * The MIT License
+ * 
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
+ * 
+ * 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.
+ */
+
+'use strict';
+
+var http = require('http');
+var env = require('@catbee/utils/env');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function getDefaultHealthzConfig() {
+  return {
+    host: env.Env.get("HEALTHZ_HOST", "") || env.Env.get("SERVER_HEALTHZ_HOST", "") || env.Env.get("SERVER_HOST", "") || env.Env.get("HOST", "0.0.0.0"),
+    port: env.Env.getPort("HEALTHZ_PORT", env.Env.getPort("SERVER_HEALTHZ_PORT", 8282)),
+    healthzPath: env.Env.get("HEALTHZ_PATH", "") || env.Env.get("SERVER_HEALTHZ_PATH", "") || env.Env.get("SERVER_HEALTH_CHECK_PATH", "/healthz"),
+    readyzPath: env.Env.get("HEALTHZ_READYZ_PATH", "") || env.Env.get("SERVER_READYZ_PATH", "/readyz"),
+    startupzPath: env.Env.get("HEALTHZ_STARTUPZ_PATH", "") || env.Env.get("SERVER_STARTUPZ_PATH", "/startupz"),
+    detailed: env.Env.getBoolean("HEALTHZ_DETAILED", env.Env.getBoolean("SERVER_HEALTHZ_DETAILED", env.Env.getBoolean("SERVER_HEALTH_CHECK_DETAILED_OUTPUT", true))),
+    checks: [],
+    checkTimeoutMs: env.Env.getDuration("HEALTHZ_CHECK_TIMEOUT_MS", env.Env.getDuration("SERVER_HEALTHZ_CHECK_TIMEOUT_MS", 5e3)),
+    shutdownDelayMs: env.Env.getDuration("HEALTHZ_SHUTDOWN_DELAY_MS", env.Env.getDuration("SERVER_HEALTHZ_SHUTDOWN_DELAY_MS", 5e3)),
+    handleSignals: true
+  };
+}
+__name(getDefaultHealthzConfig, "getDefaultHealthzConfig");
+function resolveConfig(userConfig) {
+  const defaults = getDefaultHealthzConfig();
+  if (!userConfig) return {
+    ...defaults
+  };
+  const cleaned = Object.fromEntries(Object.entries(userConfig).filter(([, v]) => v !== void 0));
+  return {
+    ...defaults,
+    ...cleaned
+  };
+}
+__name(resolveConfig, "resolveConfig");
+
+// src/healthz-server/healthz-server.ts
+var SINGLETON_KEY = Symbol.for("CatbeeHealthzServer");
+var _global = globalThis;
+var HealthzServer = class _HealthzServer {
+  static {
+    __name(this, "HealthzServer");
+  }
+  server;
+  config;
+  startedAt = Date.now();
+  /** Whether the health server has successfully started listening (for `/startupz`) */
+  started = false;
+  /** Whether the service is ready to receive traffic (for `/readyz`) */
+  ready = false;
+  shuttingDown = false;
+  onSigterm = /* @__PURE__ */ __name(() => this.initiateShutdown(), "onSigterm");
+  onSigint = /* @__PURE__ */ __name(() => this.initiateShutdown(), "onSigint");
+  constructor(config) {
+    this.config = config;
+    this.server = http.createServer((req, res) => this.handleRequest(req, res));
+    if (this.config.handleSignals !== false) {
+      process.once("SIGTERM", this.onSigterm);
+      process.once("SIGINT", this.onSigint);
+    }
+  }
+  /**
+  * Returns default Healthz server configuration resolved from environment variables.
+  */
+  static getDefaultConfig() {
+    return getDefaultHealthzConfig();
+  }
+  /**
+  * Boot the health-check server.
+  * Returns `null` if a server is already running in this process.
+  */
+  static async start(opts) {
+    if (_global[SINGLETON_KEY]) return null;
+    const config = resolveConfig(opts);
+    const instance = new _HealthzServer(config);
+    _global[SINGLETON_KEY] = instance;
+    return new Promise((resolve, reject) => {
+      const onError = /* @__PURE__ */ __name((err) => {
+        instance.cleanup();
+        delete _global[SINGLETON_KEY];
+        reject(err);
+      }, "onError");
+      instance.server.once("error", onError);
+      instance.server.listen({
+        host: config.host,
+        port: config.port
+      }, () => {
+        instance.server.off("error", onError);
+        instance.started = true;
+        const addr = instance.server.address();
+        if (!addr || typeof addr === "string") {
+          instance.cleanup();
+          delete _global[SINGLETON_KEY];
+          reject(new Error("Failed to resolve health server address"));
+          return;
+        }
+        resolve({
+          address: addr.address,
+          family: addr.family,
+          port: addr.port
+        });
+      });
+    });
+  }
+  /** Whether the health-check server is currently running and started. */
+  static isStarted() {
+    return _global[SINGLETON_KEY]?.started ?? false;
+  }
+  /** Mark the service as ready / not-ready for traffic. */
+  static setReady(ready) {
+    const instance = _global[SINGLETON_KEY];
+    if (!instance) return;
+    instance.ready = ready;
+  }
+  /** Whether the service is currently marked as ready. */
+  static isReady() {
+    return _global[SINGLETON_KEY]?.ready ?? false;
+  }
+  /** Gracefully stop the health-check server. */
+  static async stop() {
+    const instance = _global[SINGLETON_KEY];
+    if (!instance) return;
+    instance.cleanup();
+    return new Promise((resolve) => {
+      if (typeof instance.server.closeIdleConnections === "function") {
+        instance.server.closeIdleConnections();
+      }
+      instance.server.close(() => {
+        delete _global[SINGLETON_KEY];
+        resolve();
+      });
+    });
+  }
+  static getInstance() {
+    return _global[SINGLETON_KEY];
+  }
+  /**
+  * Register a named check on this HealthzServer instance dynamically.
+  *
+  * @param check - The named check to register
+  * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
+  * @returns This instance for chaining
+  */
+  registerCheck(check, type = "readiness") {
+    if (type === "liveness" || type === "both") {
+      this.config.checks.push(check);
+    }
+    if (type === "readiness" || type === "both") {
+      this.config.readinessChecks ??= [
+        ...this.config.checks
+      ];
+      this.config.readinessChecks.push(check);
+    }
+    return this;
+  }
+  /**
+  * Register a named check on the active singleton HealthzServer instance (if started).
+  *
+  * @param check - The named check to register
+  * @param type - Which probe to attach this check to ('readiness', 'liveness', or 'both')
+  */
+  static registerCheck(check, type = "readiness") {
+    _global[SINGLETON_KEY]?.registerCheck(check, type);
+  }
+  async handleRequest(req, res) {
+    const isHead = req.method === "HEAD";
+    if (req.method !== "GET" && !isHead) {
+      this.sendJson(res, 405, {
+        error: "Method Not Allowed"
+      }, isHead);
+      return;
+    }
+    const url = req.url ?? "/";
+    try {
+      if (url === this.config.healthzPath) {
+        await this.handleLiveness(res, isHead);
+      } else if (url === this.config.readyzPath) {
+        await this.handleReadiness(res, isHead);
+      } else if (url === this.config.startupzPath) {
+        this.handleStartup(res, isHead);
+      } else {
+        this.sendJson(res, 404, {
+          error: "Not Found"
+        }, isHead);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Internal Server Error";
+      this.sendJson(res, 500, {
+        error: message
+      }, isHead);
+    }
+  }
+  /** `/healthz` — Liveness probe */
+  async handleLiveness(res, isHead = false) {
+    const results = await this.runChecks(this.config.checks);
+    if (this.config.onHealthCheck) {
+      const start = Date.now();
+      try {
+        const ok = await this.executeCheck(this.config.onHealthCheck, this.config.checkTimeoutMs);
+        results.push({
+          name: "custom",
+          ok: !!ok,
+          durationMs: Date.now() - start,
+          ...!ok ? {
+            error: "Health check returned false"
+          } : {}
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        results.push({
+          name: "custom",
+          ok: false,
+          durationMs: Date.now() - start,
+          error: message
+        });
+      }
+    }
+    const allOk = results.every((r) => r.ok);
+    const status = allOk ? "ok" : "unhealthy";
+    const httpStatus = allOk ? 200 : 503;
+    this.sendProbe(res, httpStatus, status, results, isHead);
+  }
+  /** `/readyz` — Readiness probe */
+  async handleReadiness(res, isHead = false) {
+    if (this.shuttingDown || !this.ready) {
+      const status2 = "unhealthy";
+      this.sendProbe(res, 503, status2, [
+        {
+          name: "readiness",
+          ok: false,
+          durationMs: 0,
+          error: this.shuttingDown ? "Shutting down" : "Not ready"
+        }
+      ], isHead);
+      return;
+    }
+    const checksToRun = this.config.readinessChecks ?? this.config.checks;
+    const results = await this.runChecks(checksToRun);
+    if (this.config.onReadinessCheck) {
+      const start = Date.now();
+      try {
+        const ready = await this.executeCheck(this.config.onReadinessCheck, this.config.checkTimeoutMs);
+        results.push({
+          name: "custom-readiness",
+          ok: !!ready,
+          durationMs: Date.now() - start,
+          ...!ready ? {
+            error: "Readiness check returned false"
+          } : {}
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        results.push({
+          name: "custom-readiness",
+          ok: false,
+          durationMs: Date.now() - start,
+          error: message
+        });
+      }
+    }
+    const allOk = results.every((r) => r.ok);
+    const status = allOk ? "ok" : "unhealthy";
+    const httpStatus = allOk ? 200 : 503;
+    this.sendProbe(res, httpStatus, status, results, isHead);
+  }
+  /** `/startupz` — Startup probe */
+  handleStartup(res, isHead = false) {
+    if (this.started) {
+      this.sendProbe(res, 200, "ok", [], isHead);
+    } else {
+      this.sendProbe(res, 503, "unhealthy", [
+        {
+          name: "startup",
+          ok: false,
+          durationMs: 0,
+          error: "Service has not started yet"
+        }
+      ], isHead);
+    }
+  }
+  async runChecks(checks) {
+    if (checks.length === 0) return [];
+    return Promise.all(checks.map(async ({ name, check }) => {
+      const start = Date.now();
+      try {
+        const result = await this.executeCheck(check, this.config.checkTimeoutMs);
+        return {
+          name,
+          ok: !!result,
+          durationMs: Date.now() - start
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return {
+          name,
+          ok: false,
+          durationMs: Date.now() - start,
+          error: message
+        };
+      }
+    }));
+  }
+  sendProbe(res, httpStatus, status, checks, isHead = false) {
+    const body = {
+      status,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      uptimeSeconds: Math.floor((Date.now() - this.startedAt) / 1e3)
+    };
+    if (this.config.detailed && checks.length > 0) {
+      body.checks = checks;
+    }
+    this.sendJson(res, httpStatus, body, isHead);
+  }
+  sendJson(res, status, body, isHead = false) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+      "Content-Type": "application/json; charset=utf-8",
+      "Content-Length": Buffer.byteLength(payload),
+      "Cache-Control": "no-cache, no-store, must-revalidate",
+      "X-Content-Type-Options": "nosniff"
+    });
+    if (isHead) {
+      res.end();
+    } else {
+      res.end(payload);
+    }
+  }
+  async executeCheck(fn, ms) {
+    const controller = new AbortController();
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        const error = new Error(`Check timed out after ${ms}ms`);
+        controller.abort(error);
+        reject(error);
+      }, ms);
+    });
+    try {
+      const checkPromise = Promise.resolve().then(() => fn(controller.signal));
+      checkPromise.catch(() => {
+      });
+      return await Promise.race([
+        checkPromise,
+        timeoutPromise
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  async initiateShutdown() {
+    if (this.shuttingDown) return;
+    this.shuttingDown = true;
+    this.ready = false;
+    if (this.config.shutdownDelayMs > 0) {
+      await new Promise((r) => setTimeout(r, this.config.shutdownDelayMs));
+    }
+    await _HealthzServer.stop();
+  }
+  cleanup() {
+    process.off("SIGTERM", this.onSigterm);
+    process.off("SIGINT", this.onSigint);
+    this.ready = false;
+    this.started = false;
+    this.shuttingDown = false;
+  }
+};
+
+exports.HealthzServer = HealthzServer;
+exports.getDefaultHealthzConfig = getDefaultHealthzConfig;
+exports.resolveConfig = resolveConfig;