@catbee/utils 2.2.0 → 2.3.0

package/server/index.mjs

@@ -37,6 +37,7 @@ import { fileExists, readFile, readFileSync } from '@catbee/utils/fs';
 import { isPort, isHostname } from '@catbee/utils/validation';
 import { optionalRequire } from '@catbee/utils/async';
 import { uuid } from '@catbee/utils/id';
+import { trimChars } from '@catbee/utils/string';
 import { HealthzServer } from '@catbee/utils/healthz-server';
 
 var __defProp = Object.defineProperty;
@@ -730,8 +731,12 @@ var ExpressServer = class {
   app;
   /** Set of active WebSocket connections */
   connections = /* @__PURE__ */ new Set();
-  /** Flag indicating if the server is shutting down */
+  /** Flag indicating if the server is shutting down (rejects traffic with 503) */
   isShuttingDown = false;
+  /** Flag indicating if the server is in graceful drain delay (sets Connection: close while servicing traffic) */
+  isDraining = false;
+  /** Internal readiness state (used when HealthzServer is not enabled) */
+  internalReady = false;
   /** Flag indicating if graceful shutdown handlers are registered */
   gracefulShutdownRegistered = false;
   /** Map of registered signal listeners for clean teardown */
@@ -742,10 +747,14 @@ var ExpressServer = class {
   healthzChecks = [];
   /** Named checks queued for Healthz readiness probe */
   healthzReadinessChecks = [];
+  /** Whether readiness checks were explicitly provided or registered */
+  hasExplicitReadinessChecks = false;
   /** Promise that resolves when initialization (middleware + routes) is complete */
   initPromise;
   /** In-flight start promise to protect against concurrent start() calls */
   startPromise;
+  /** In-flight stop promise to protect against concurrent stop() calls */
+  stopPromise;
   /**
   * Initializes server with intelligent defaults and security best practices.
   * All settings can be customized via config and hooks.
@@ -786,7 +795,8 @@ var ExpressServer = class {
       if (this.config.healthzServer.checks) {
         this.healthzChecks.push(...this.config.healthzServer.checks);
       }
-      if (this.config.healthzServer.readinessChecks) {
+      if (this.config.healthzServer.readinessChecks !== void 0) {
+        this.hasExplicitReadinessChecks = true;
         this.healthzReadinessChecks.push(...this.config.healthzServer.readinessChecks);
       }
     }
@@ -884,6 +894,9 @@ var ExpressServer = class {
         res.status(HttpStatusCodes.SERVICE_UNAVAILABLE).json(new ServiceUnavailableException("Server is shutting down"));
         return;
       }
+      if (this.isDraining) {
+        res.setHeader("Connection", "close");
+      }
       next();
     });
   }
@@ -1197,21 +1210,96 @@ var ExpressServer = class {
       check
     };
     if (probeType === "liveness" || probeType === "both") {
-      this.healthzChecks.push(namedCheck);
+      const idx = this.healthzChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) {
+        this.healthzChecks[idx] = namedCheck;
+      } else {
+        this.healthzChecks.push(namedCheck);
+      }
     }
     if (probeType === "readiness" || probeType === "both") {
-      this.healthzReadinessChecks.push(namedCheck);
+      this.hasExplicitReadinessChecks = true;
+      const idx = this.healthzReadinessChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) {
+        this.healthzReadinessChecks[idx] = namedCheck;
+      } else {
+        this.healthzReadinessChecks.push(namedCheck);
+      }
     }
     HealthzServer.registerCheck(namedCheck, probeType);
     return this;
   }
   /**
+  * Unregister a health check by name.
+  *
+  * @param name Name of the check to remove
+  * @param options Target probe type ('readiness' | 'liveness' | 'both') or options object
+  * @returns This instance for method chaining
+  */
+  unregisterHealthCheck(name, options) {
+    const probeType = typeof options === "string" ? options : options?.type ?? "both";
+    if (probeType === "liveness" || probeType === "both") {
+      const idx = this.healthzChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) this.healthzChecks.splice(idx, 1);
+    }
+    if (probeType === "readiness" || probeType === "both") {
+      const idx = this.healthzReadinessChecks.findIndex((c) => c.name === name);
+      if (idx !== -1) this.healthzReadinessChecks.splice(idx, 1);
+    }
+    HealthzServer.unregisterCheck(name, probeType);
+    return this;
+  }
+  /**
+  * Get all registered Healthz checks queued for this Express server.
+  */
+  getHealthzChecks() {
+    return {
+      liveness: [
+        ...this.healthzChecks
+      ],
+      readiness: [
+        ...this.healthzReadinessChecks
+      ]
+    };
+  }
+  /**
+  * Register a readiness health check.
+  *
+  * @param name Unique identifier for the check (used in detailed responses)
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @returns This instance for method chaining
+  */
+  registerReadinessCheck(name, check) {
+    return this.registerHealthCheck(name, check, "readiness");
+  }
+  /**
+  * Register a liveness health check.
+  *
+  * @param name Unique identifier for the check (used in detailed responses)
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @returns This instance for method chaining
+  */
+  registerLivenessCheck(name, check) {
+    return this.registerHealthCheck(name, check, "liveness");
+  }
+  /**
+  * Register a readiness and liveness health check.
+  *
+  * @param name Unique identifier for the check (used in detailed responses)
+  * @param check Function returning boolean or Promise<boolean> indicating health (supports optional AbortSignal)
+  * @returns This instance for method chaining
+  */
+  registerReadinessAndLivenessChecks(name, check) {
+    return this.registerHealthCheck(name, check, "both");
+  }
+  /**
   * Mark the service as ready / not-ready for traffic on the Healthz probe server.
   *
   * @param ready Whether the service is ready to receive traffic
   * @returns This instance for method chaining
   */
   setReady(ready) {
+    this.internalReady = ready;
     HealthzServer.setReady(ready);
     return this;
   }
@@ -1219,7 +1307,28 @@ var ExpressServer = class {
   * Whether the service is currently marked as ready for traffic on the Healthz probe server.
   */
   isReady() {
-    return HealthzServer.isReady();
+    if (this.isHealthzServerEnabled()) {
+      return HealthzServer.isReady();
+    }
+    return this.internalReady && this.isRunning();
+  }
+  /**
+  * Mark application startup as completed on the Healthz probe server (switches `/startupz` to 200).
+  *
+  * @returns This instance for method chaining
+  */
+  markStartupComplete() {
+    HealthzServer.markStartupComplete();
+    return this;
+  }
+  /**
+  * Whether application startup has completed on the Healthz probe server.
+  */
+  isStartupComplete() {
+    if (this.isHealthzServerEnabled()) {
+      return HealthzServer.isStartupComplete();
+    }
+    return this.isRunning();
   }
   /**
   * Get the running HealthzServer instance (if started).
@@ -1240,7 +1349,7 @@ var ExpressServer = class {
   * @returns `true` when ready, otherwise `false`.
   */
   ready() {
-    return HealthzServer.isReady();
+    return this.isReady();
   }
   /**
   * Get the underlying Express application instance.
@@ -1297,92 +1406,108 @@ var ExpressServer = class {
   */
   async doStart() {
     await this.initPromise;
-    await this.runHook("beforeStart", this.app);
-    const server = this.createServerInstance();
-    this.server = server;
-    return new Promise((resolve, reject) => {
-      let isListening = false;
-      server.on("error", (err) => {
-        if (!isListening) {
-          getLogger().error({
-            err
-          }, "Server failed to start");
-          try {
-            server.removeAllListeners();
-            server.close();
-            if (HealthzServer.isStarted()) {
-              HealthzServer.stop().catch(() => {
-              });
-            }
-          } catch {
-          }
-          this.server = null;
-          this.connections.clear();
-          reject(err);
-        } else {
-          getLogger().error({
-            err
-          }, "Server runtime error");
-        }
-      });
-      this.setupConnectionTracking();
-      Promise.resolve(this.runHook("onServerCreated", server)).then(() => {
-        const onListening = /* @__PURE__ */ __name(async () => {
-          try {
-            if (this.isHealthzServerEnabled()) {
-              const healthzConfig = {
-                ...typeof this.config.healthzServer === "object" ? this.config.healthzServer : {},
-                handleSignals: false,
-                checks: [
-                  ...this.healthzChecks
-                ],
-                readinessChecks: [
-                  ...this.healthzReadinessChecks
-                ]
-              };
-              const addr = await HealthzServer.start(healthzConfig);
-              if (!addr) {
-                throw new Error("Healthz probe server failed to start (already running in this process)");
-              }
-              this.healthzAddress = addr;
-            }
-            this.logServerStartInfo();
-            await this.runHook("afterStart", server);
-            if (this.isHealthzServerEnabled()) {
-              HealthzServer.setReady(true);
-            }
-            isListening = true;
-            resolve(server);
-          } catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
+    if (this.isHealthzServerEnabled()) {
+      const healthzConfig = {
+        ...typeof this.config.healthzServer === "object" ? this.config.healthzServer : {},
+        handleSignals: false,
+        checks: [
+          ...this.healthzChecks
+        ],
+        ...this.hasExplicitReadinessChecks ? {
+          readinessChecks: [
+            ...this.healthzReadinessChecks
+          ]
+        } : {}
+      };
+      const addr = await HealthzServer.start(healthzConfig);
+      if (!addr) {
+        throw new Error("Healthz probe server failed to start (already running in this process)");
+      }
+      this.healthzAddress = addr;
+    }
+    try {
+      await this.runHook("beforeStart", this.app);
+      const server = this.createServerInstance();
+      this.server = server;
+      return await new Promise((resolve, reject) => {
+        let isListening = false;
+        server.on("error", async (err) => {
+          if (!isListening) {
             getLogger().error({
-              err: error
-            }, "Server startup failed");
-            if (HealthzServer.isStarted()) {
-              await HealthzServer.stop().catch(() => {
-              });
-            }
+              err
+            }, "Server failed to start");
             try {
               server.removeAllListeners();
               server.close();
+              if (HealthzServer.isRunning()) {
+                await HealthzServer.stop().catch(() => {
+                });
+              }
             } catch {
             }
             this.server = null;
             this.healthzAddress = null;
             this.connections.clear();
-            reject(error);
+            reject(err);
+          } else {
+            getLogger().error({
+              err
+            }, "Server runtime error");
           }
-        }, "onListening");
-        const listenArgs = [
-          this.config.port,
-          this.config.host,
-          onListening
-        ];
-        server.listen(...listenArgs);
-      }).catch((err) => {
-        server.emit("error", err instanceof Error ? err : new Error(String(err)));
+        });
+        this.setupConnectionTracking();
+        Promise.resolve(this.runHook("onServerCreated", server)).then(() => {
+          const onListening = /* @__PURE__ */ __name(async () => {
+            try {
+              this.logServerStartInfo();
+              await this.runHook("afterStart", server);
+              this.internalReady = true;
+              if (this.isHealthzServerEnabled()) {
+                HealthzServer.markStartupComplete();
+                HealthzServer.setReady(true);
+              }
+              isListening = true;
+              resolve(server);
+            } catch (err) {
+              const error = err instanceof Error ? err : new Error(String(err));
+              getLogger().error({
+                err: error
+              }, "Server startup failed");
+              if (HealthzServer.isRunning()) {
+                await HealthzServer.stop().catch(() => {
+                });
+              }
+              try {
+                server.removeAllListeners();
+                server.close();
+              } catch {
+              }
+              this.server = null;
+              this.healthzAddress = null;
+              this.connections.clear();
+              reject(error);
+            }
+          }, "onListening");
+          const listenArgs = [
+            this.config.port,
+            this.config.host,
+            onListening
+          ];
+          server.listen(...listenArgs);
+        }).catch((err) => {
+          server.emit("error", err instanceof Error ? err : new Error(String(err)));
+        });
       });
-    });
+    } catch (err) {
+      if (HealthzServer.isRunning()) {
+        await HealthzServer.stop().catch(() => {
+        });
+      }
+      this.healthzAddress = null;
+      this.server = null;
+      this.connections.clear();
+      throw err;
+    }
   }
   /**
   * Create HTTP or HTTPS server instance (without listening).
@@ -1423,7 +1548,8 @@ var ExpressServer = class {
     const url = `${protocol}://${host}:${port}`;
     getLogger().info(`Server running on ${url}`);
     if (this.healthzAddress) {
-      getLogger().info(`Healthz probe server running on http://${this.healthzAddress.address}:${this.healthzAddress.port}`);
+      const healthzHost = this.formatHostForUrl(this.healthzAddress.address);
+      getLogger().info(`Healthz server running on http://${healthzHost}:${this.healthzAddress.port}`);
     }
     if (this.config.openApi?.enable) {
       getLogger().info(`API docs available at ${url}${this.normalizePath(this.config.openApi.mountPath, this.config.openApi.withGlobalPrefix)}`);
@@ -1446,16 +1572,26 @@ var ExpressServer = class {
   * - Monitoring systems are notified
   */
   async stop(force = false) {
-    if (!this.server && !HealthzServer.isStarted()) {
+    if (!this.server && !HealthzServer.isRunning()) {
       getLogger().warn("Stop called but server is not running");
       return;
     }
-    if (this.isShuttingDown) {
-      getLogger().warn("Shutdown already in progress");
-      return;
+    if (this.stopPromise) {
+      return this.stopPromise;
+    }
+    this.stopPromise = this.doStop(force);
+    try {
+      await this.stopPromise;
+    } finally {
+      this.stopPromise = void 0;
     }
-    this.isShuttingDown = true;
-    if (HealthzServer.isStarted()) {
+  }
+  /**
+  * Internal implementation of server shutdown.
+  */
+  async doStop(force = false) {
+    this.internalReady = false;
+    if (HealthzServer.isRunning()) {
       HealthzServer.setReady(false);
     }
     if (this.server) {
@@ -1463,19 +1599,23 @@ var ExpressServer = class {
     }
     try {
       const shutdownDelay = this.getHealthzShutdownDelay();
-      if (shutdownDelay > 0 && !force && HealthzServer.isStarted()) {
+      if (shutdownDelay > 0 && !force && HealthzServer.isRunning()) {
         getLogger().info(`Waiting ${shutdownDelay}ms for load balancer to drain traffic...`);
+        this.isDraining = true;
         await new Promise((resolve) => setTimeout(resolve, shutdownDelay));
       }
+      this.isDraining = false;
+      this.isShuttingDown = true;
       if (this.server) {
         await this.gracefulShutdown(force);
       }
     } finally {
-      if (HealthzServer.isStarted()) {
+      if (HealthzServer.isRunning()) {
         await HealthzServer.stop();
         this.healthzAddress = null;
       }
       this.isShuttingDown = false;
+      this.isDraining = false;
     }
   }
   /**
@@ -1562,10 +1702,11 @@ var ExpressServer = class {
         signalHandled = true;
         getLogger().info(`Received ${signal}, initiating graceful shutdown...`);
         try {
-          this.disableGracefulShutdown();
           await this.stop(false);
+          this.disableGracefulShutdown();
           process.exit(0);
         } catch (err) {
+          this.disableGracefulShutdown();
           getLogger().fatal({
             err
           }, "Shutdown failed");
@@ -1923,7 +2064,8 @@ var ExpressServer = class {
   }
   normalizePath(path, withGlobalPrefix = false) {
     const sanitize = /* @__PURE__ */ __name((p) => {
-      return "/" + p.trim().replace(/^\/+/, "").replace(/\/{2,}/g, "/").replace(/\/+$/, "");
+      const inner = trimChars(p.trim(), "/");
+      return inner ? "/" + inner.replace(/\/{2,}/g, "/") : "/";
     }, "sanitize");
     const prefix = withGlobalPrefix && this.globalPrefix ? sanitize(this.globalPrefix) : "";
     if (typeof path !== "string" || !path.trim()) {

package/string/index.cjs

@@ -44,7 +44,8 @@ function toCamelCase(str) {
 }
 __name(toCamelCase, "toCamelCase");
 function slugify(str) {
-  return str.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+  const slug = str.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-");
+  return trimChars(slug, "-");
 }
 __name(slugify, "slugify");
 function truncate(str, len) {
@@ -69,7 +70,13 @@ function mask(str, visibleStart = 0, visibleEnd = 0, maskChar = "*") {
 }
 __name(mask, "mask");
 function stripHtml(str) {
-  return str.replace(/<[^>]*>/g, "");
+  let prev;
+  let result = str;
+  do {
+    prev = result;
+    result = result.replace(/<[^<>]*>/g, "");
+  } while (result !== prev);
+  return result;
 }
 __name(stripHtml, "stripHtml");
 function equalsIgnoreCase(a, b) {
@@ -122,6 +129,38 @@ function ellipsis(str, maxLength, suffix = "...") {
   return (lastSpace > 0 ? truncated.slice(0, lastSpace) : truncated) + suffix;
 }
 __name(ellipsis, "ellipsis");
+function trimChars(str, chars = " ") {
+  if (!str) return "";
+  let start = 0;
+  let end = str.length;
+  while (start < end && chars.includes(str[start])) {
+    start++;
+  }
+  while (end > start && chars.includes(str[end - 1])) {
+    end--;
+  }
+  return str.slice(start, end);
+}
+__name(trimChars, "trimChars");
+function trimLeadingChars(str, chars = " ") {
+  if (!str) return "";
+  let start = 0;
+  const end = str.length;
+  while (start < end && chars.includes(str[start])) {
+    start++;
+  }
+  return str.slice(start, end);
+}
+__name(trimLeadingChars, "trimLeadingChars");
+function trimTrailingChars(str, chars = " ") {
+  if (!str) return "";
+  let end = str.length;
+  while (end > 0 && chars.includes(str[end - 1])) {
+    end--;
+  }
+  return str.slice(0, end);
+}
+__name(trimTrailingChars, "trimTrailingChars");
 
 exports.capitalize = capitalize;
 exports.countOccurrences = countOccurrences;
@@ -138,5 +177,8 @@ exports.toKebabCase = toKebabCase;
 exports.toPascalCase = toPascalCase;
 exports.toSnakeCase = toSnakeCase;
 exports.toTitleCase = toTitleCase;
+exports.trimChars = trimChars;
+exports.trimLeadingChars = trimLeadingChars;
+exports.trimTrailingChars = trimTrailingChars;
 exports.truncate = truncate;
 exports.unescapeHtml = unescapeHtml;

package/string/index.d.ts

@@ -165,5 +165,40 @@ declare function isBlank(str: string): boolean;
  * ellipsis('The quick brown fox', 10); // 'The quick...'
  */
 declare function ellipsis(str: string, maxLength: number, suffix?: string): string;
+/**
+ * Trims leading and trailing occurrences of specified characters in linear O(n) time
+ * without using regular expressions (immune to polynomial ReDoS).
+ *
+ * @param {string} str - The input string.
+ * @param {string} [chars=' '] - Character or set of characters to trim.
+ * @returns {string} The trimmed string.
+ *
+ * @example
+ * trimChars('///api/users///', '/'); // 'api/users'
+ * trimChars('---hello-world---', '-'); // 'hello-world'
+ */
+declare function trimChars(str: string, chars?: string): string;
+/**
+ * Trims leading occurrences of specified characters in linear O(n) time.
+ *
+ * @param {string} str - The input string.
+ * @param {string} [chars=' '] - Character or set of characters to trim from start.
+ * @returns {string} The trimmed string.
+ *
+ * @example
+ * trimLeadingChars('///api/users', '/'); // 'api/users'
+ */
+declare function trimLeadingChars(str: string, chars?: string): string;
+/**
+ * Trims trailing occurrences of specified characters in linear O(n) time.
+ *
+ * @param {string} str - The input string.
+ * @param {string} [chars=' '] - Character or set of characters to trim from end.
+ * @returns {string} The trimmed string.
+ *
+ * @example
+ * trimTrailingChars('https://example.com///', '/'); // 'https://example.com'
+ */
+declare function trimTrailingChars(str: string, chars?: string): string;
 
-export { capitalize, countOccurrences, ellipsis, equalsIgnoreCase, escapeRegex, isBlank, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, truncate, unescapeHtml };
+export { capitalize, countOccurrences, ellipsis, equalsIgnoreCase, escapeRegex, isBlank, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, trimChars, trimLeadingChars, trimTrailingChars, truncate, unescapeHtml };

package/string/index.mjs

@@ -42,7 +42,8 @@ function toCamelCase(str) {
 }
 __name(toCamelCase, "toCamelCase");
 function slugify(str) {
-  return str.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+  const slug = str.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-");
+  return trimChars(slug, "-");
 }
 __name(slugify, "slugify");
 function truncate(str, len) {
@@ -67,7 +68,13 @@ function mask(str, visibleStart = 0, visibleEnd = 0, maskChar = "*") {
 }
 __name(mask, "mask");
 function stripHtml(str) {
-  return str.replace(/<[^>]*>/g, "");
+  let prev;
+  let result = str;
+  do {
+    prev = result;
+    result = result.replace(/<[^<>]*>/g, "");
+  } while (result !== prev);
+  return result;
 }
 __name(stripHtml, "stripHtml");
 function equalsIgnoreCase(a, b) {
@@ -120,5 +127,37 @@ function ellipsis(str, maxLength, suffix = "...") {
   return (lastSpace > 0 ? truncated.slice(0, lastSpace) : truncated) + suffix;
 }
 __name(ellipsis, "ellipsis");
+function trimChars(str, chars = " ") {
+  if (!str) return "";
+  let start = 0;
+  let end = str.length;
+  while (start < end && chars.includes(str[start])) {
+    start++;
+  }
+  while (end > start && chars.includes(str[end - 1])) {
+    end--;
+  }
+  return str.slice(start, end);
+}
+__name(trimChars, "trimChars");
+function trimLeadingChars(str, chars = " ") {
+  if (!str) return "";
+  let start = 0;
+  const end = str.length;
+  while (start < end && chars.includes(str[start])) {
+    start++;
+  }
+  return str.slice(start, end);
+}
+__name(trimLeadingChars, "trimLeadingChars");
+function trimTrailingChars(str, chars = " ") {
+  if (!str) return "";
+  let end = str.length;
+  while (end > 0 && chars.includes(str[end - 1])) {
+    end--;
+  }
+  return str.slice(0, end);
+}
+__name(trimTrailingChars, "trimTrailingChars");
 
-export { capitalize, countOccurrences, ellipsis, equalsIgnoreCase, escapeRegex, isBlank, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, truncate, unescapeHtml };
+export { capitalize, countOccurrences, ellipsis, equalsIgnoreCase, escapeRegex, isBlank, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, trimChars, trimLeadingChars, trimTrailingChars, truncate, unescapeHtml };