@catbee/utils 2.2.1 → 2.3.0

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 };

package/types/index.d.ts

@@ -161,28 +161,42 @@ type Without<T, U> = {
  * A health check function that can be synchronous or asynchronous.
  * Receives an AbortSignal that is triggered when `checkTimeoutMs` is exceeded.
  *
- * > **Cancellation Note**: Cancellation is cooperative. The check function must listen to
- * > `signal.aborted` or pass `signal` to underlying asynchronous APIs (e.g. database drivers, `fetch`).
- * > Synchronous CPU-bound loops or operations that ignore `signal` cannot be forcibly stopped by JavaScript.
+ * > **Cancellation & Timeout Semantics**:
+ * > When `checkTimeoutMs` expires, the HTTP probe response immediately fast-fails with 503
+ * > and aborts the supplied `AbortSignal`.
+ * >
+ * > However, runtime cancellation in JavaScript is **strictly cooperative**. The probe server cannot
+ * > preemptively interrupt executing JavaScript or force-cancel asynchronous work that does not listen
+ * > to the signal. If a check executes asynchronous tasks without passing `signal`
+ * > (e.g., `await db.query(...)` without `{ signal }`), that task will continue running in the background.
+ * > To prevent background resource leaks, always pass `signal` to underlying drivers/clients
+ * > (e.g. `fetch(url, { signal })`, database clients, HTTP clients) or check `signal?.aborted`.
  *
- * - Return `true` (or resolve to true) to signal healthy.
+ * - Return `true` (or resolve to true, or resolve void without error) to signal healthy.
  * - Return `false` (or resolve to false) to signal unhealthy.
  * - Throw an error (or reject) to signal unhealthy with an error message.
  */
-type HealthCheckFn = (signal?: AbortSignal) => boolean | Promise<boolean>;
+type HealthCheckFn = (signal?: AbortSignal) => boolean | void | Promise<boolean | void>;
 /**
  * A readiness check function.
  * Receives an AbortSignal that is triggered when `checkTimeoutMs` is exceeded.
  *
- * > **Cancellation Note**: Cancellation is cooperative. The check function must listen to
- * > `signal.aborted` or pass `signal` to underlying asynchronous APIs (e.g. database drivers, `fetch`).
- * > Synchronous CPU-bound loops or operations that ignore `signal` cannot be forcibly stopped by JavaScript.
+ * > **Cancellation & Timeout Semantics**:
+ * > When `checkTimeoutMs` expires, the HTTP probe response immediately fast-fails with 503
+ * > and aborts the supplied `AbortSignal`.
+ * >
+ * > However, runtime cancellation in JavaScript is **strictly cooperative**. The probe server cannot
+ * > preemptively interrupt executing JavaScript or force-cancel asynchronous work that does not listen
+ * > to the signal. If a check executes asynchronous tasks without passing `signal`
+ * > (e.g., `await db.query(...)` without `{ signal }`), that task will continue running in the background.
+ * > To prevent background resource leaks, always pass `signal` to underlying drivers/clients
+ * > (e.g. `fetch(url, { signal })`, database clients, HTTP clients) or check `signal?.aborted`.
  *
- * - Return `true` (or resolve to true) to signal ready.
+ * - Return `true` (or resolve to true, or resolve void without error) to signal ready.
  * - Return `false` (or resolve to false) to signal not ready.
  * - Throw an error (or reject) to signal not ready with an error.
  */
-type ReadinessCheckFn = (signal?: AbortSignal) => boolean | Promise<boolean>;
+type ReadinessCheckFn = (signal?: AbortSignal) => boolean | void | Promise<boolean | void>;
 /**
  * A named health check with an associated check function.
  */
@@ -191,10 +205,11 @@ interface NamedCheck {
     name: string;
     /**
      * Check function — return false or throw to indicate failure.
+     * Resolving void without throwing is considered healthy/ready.
      * Receives an AbortSignal that is triggered when the check times out.
-     * Cancellation via the signal is cooperative.
+     * Cancellation via the signal is cooperative; pass `signal` to underlying operations.
      */
-    check: (signal?: AbortSignal) => boolean | Promise<boolean>;
+    check: (signal?: AbortSignal) => boolean | void | Promise<boolean | void>;
 }
 /**
  * Configuration for the standalone healthz HTTP server.
@@ -255,14 +270,27 @@ interface CatbeeHealthzServerConfig {
     /**
      * Custom liveness check function. Runs *in addition to* `checks`.
      * Return `false` or throw to indicate unhealthy.
+     * Can also be provided via `onLivenessCheck`.
      */
     onHealthCheck?: HealthCheckFn;
+    /**
+     * Symmetrical alias for `onHealthCheck` — custom liveness check function.
+     * Runs *in addition to* `checks` on `/healthz`.
+     * Return `false` or throw to indicate unhealthy.
+     */
+    onLivenessCheck?: HealthCheckFn;
     /**
      * Custom readiness check function. Runs *in addition to* `readinessChecks`.
      * Return `false` or throw to indicate not ready.
      */
     onReadinessCheck?: ReadinessCheckFn;
-    /** Timeout (ms) per individual check before it's considered failed
+    /**
+     * Timeout (ms) per individual check before it's considered failed.
+     *
+     * When exceeded, the probe immediately fast-fails with status 503 and triggers
+     * `abort()` on the check's `AbortSignal`. Note that cancellation is cooperative;
+     * checks should forward `signal` to downstream clients (e.g. database drivers, fetch)
+     * to avoid orphaned background execution.
      *  - **default**: `5000`
      *  - **env**: `HEALTHZ_CHECK_TIMEOUT_MS`
      */
@@ -657,9 +685,9 @@ interface CatbeeServerHooks {
     /** Called before server starts listening */
     beforeStart?: (app: Express) => Promise<void> | void;
     /** Called after server is ready */
-    afterStart?: (server: http.Server) => Promise<void> | void;
+    afterStart?: (server: http.Server | https.Server) => Promise<void> | void;
     /** Called before graceful shutdown */
-    beforeStop?: (server: http.Server) => Promise<void> | void;
+    beforeStop?: (server: http.Server | https.Server) => Promise<void> | void;
     /** Called after server stops */
     afterStop?: () => Promise<void> | void;
     /** Custom error handler (overrides Catbee default if provided) */

package/url/index.cjs

@@ -25,6 +25,7 @@
 'use strict';
 
 var url = require('url');
+var string = require('@catbee/utils/string');
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -81,8 +82,8 @@ function getDomain(url$1, removeSubdomains = false) {
 __name(getDomain, "getDomain");
 function joinPaths(...segments) {
   let result = segments.filter((s) => s !== void 0 && s !== null).map((segment, index) => {
-    if (index === 0) return segment.replace(/\/+$/, "");
-    return segment.replace(/^\/+|\/+$/g, "");
+    if (index === 0) return string.trimTrailingChars(segment, "/");
+    return string.trimChars(segment, "/");
   }).filter(Boolean).join("/");
   if (segments[0] === "" && !result.startsWith("/")) result = "/" + result;
   return result;
@@ -92,8 +93,8 @@ function normalizeUrl(url$1, base) {
   try {
     let normalized = url$1.startsWith("//") ? `https:${url$1}` : url$1;
     const parsedUrl = base ? new url.URL(normalized, base) : new url.URL(normalized);
-    parsedUrl.pathname = parsedUrl.pathname.replace(/\/+/g, "/");
-    parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, "");
+    const collapsed = parsedUrl.pathname.replace(/\/+/g, "/");
+    parsedUrl.pathname = string.trimTrailingChars(collapsed, "/");
     parsedUrl.hostname = parsedUrl.hostname.toLowerCase();
     return parsedUrl.toString();
   } catch {

package/url/index.mjs

@@ -23,6 +23,7 @@
  */
 
 import { URL, URLSearchParams } from 'url';
+import { trimTrailingChars, trimChars } from '@catbee/utils/string';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -79,8 +80,8 @@ function getDomain(url, removeSubdomains = false) {
 __name(getDomain, "getDomain");
 function joinPaths(...segments) {
   let result = segments.filter((s) => s !== void 0 && s !== null).map((segment, index) => {
-    if (index === 0) return segment.replace(/\/+$/, "");
-    return segment.replace(/^\/+|\/+$/g, "");
+    if (index === 0) return trimTrailingChars(segment, "/");
+    return trimChars(segment, "/");
   }).filter(Boolean).join("/");
   if (segments[0] === "" && !result.startsWith("/")) result = "/" + result;
   return result;
@@ -90,8 +91,8 @@ function normalizeUrl(url, base) {
   try {
     let normalized = url.startsWith("//") ? `https:${url}` : url;
     const parsedUrl = base ? new URL(normalized, base) : new URL(normalized);
-    parsedUrl.pathname = parsedUrl.pathname.replace(/\/+/g, "/");
-    parsedUrl.pathname = parsedUrl.pathname.replace(/\/+$/, "");
+    const collapsed = parsedUrl.pathname.replace(/\/+/g, "/");
+    parsedUrl.pathname = trimTrailingChars(collapsed, "/");
     parsedUrl.hostname = parsedUrl.hostname.toLowerCase();
     return parsedUrl.toString();
   } catch {