@catbee/utils 2.0.0-next.1 → 2.0.1

package/string/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -91,5 +91,34 @@ function toTitleCase(str) {
   return str.split(/(\s+)/).map((part) => part.trim().length === 0 ? part : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()).join("");
 }
 __name(toTitleCase, "toTitleCase");
+function escapeRegex(str) {
+  if (typeof str !== "string") throw new TypeError("Expected a string");
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+__name(escapeRegex, "escapeRegex");
+function unescapeHtml(str) {
+  if (typeof str !== "string") return "";
+  const entities = {
+    "&": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&#39;": "'",
+    "&#x27;": "'"
+  };
+  return str.replace(/&(?:amp|lt|gt|quot|#39|#x27);/g, (match) => entities[match] || match);
+}
+__name(unescapeHtml, "unescapeHtml");
+function isBlank(str) {
+  return typeof str === "string" && str.trim().length === 0;
+}
+__name(isBlank, "isBlank");
+function ellipsis(str, maxLength, suffix = "...") {
+  if (typeof str !== "string" || str.length <= maxLength) return str;
+  const truncated = str.slice(0, maxLength - suffix.length);
+  const lastSpace = truncated.lastIndexOf(" ");
+  return (lastSpace > 0 ? truncated.slice(0, lastSpace) : truncated) + suffix;
+}
+__name(ellipsis, "ellipsis");
 
-export { capitalize, countOccurrences, equalsIgnoreCase, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, truncate };
+export { capitalize, countOccurrences, ellipsis, equalsIgnoreCase, escapeRegex, isBlank, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, truncate, unescapeHtml };

package/type/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -117,12 +117,29 @@ function isEmpty(value) {
   return false;
 }
 __name(isEmpty, "isEmpty");
+function isIterable(value) {
+  return value !== null && value !== void 0 && typeof value[Symbol.iterator] === "function";
+}
+__name(isIterable, "isIterable");
+function isAsyncIterable(value) {
+  return value !== null && value !== void 0 && typeof value[Symbol.asyncIterator] === "function";
+}
+__name(isAsyncIterable, "isAsyncIterable");
+function assertType(value, guard, message) {
+  if (!guard(value)) {
+    throw new TypeError(message || `Type assertion failed`);
+  }
+}
+__name(assertType, "assertType");
 
+exports.assertType = assertType;
 exports.ensureType = ensureType;
 exports.getTypeOf = getTypeOf;
 exports.isArrayOf = isArrayOf;
+exports.isAsyncIterable = isAsyncIterable;
 exports.isDefined = isDefined;
 exports.isEmpty = isEmpty;
+exports.isIterable = isIterable;
 exports.isPrimitiveType = isPrimitiveType;
 exports.toBool = toBool;
 exports.toNum = toNum;

package/type/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -127,5 +127,41 @@ declare function isDefined<T>(value: T | null | undefined): value is T;
  * @returns True when value is considered empty
  */
 declare function isEmpty(value: any): boolean;
+/**
+ * Type guard to check if a value is iterable.
+ *
+ * @param {unknown} value - Value to check.
+ * @returns {boolean} True if value is iterable.
+ *
+ * @example
+ * isIterable([1, 2, 3]); // true
+ * isIterable('hello'); // true
+ * isIterable(new Set([1, 2])); // true
+ */
+declare function isIterable<T = any>(value: unknown): value is Iterable<T>;
+/**
+ * Type guard to check if a value is an async iterable.
+ *
+ * @param {unknown} value - Value to check.
+ * @returns {boolean} True if value is async iterable.
+ *
+ * @example
+ * async function* gen() { yield 1; }
+ * isAsyncIterable(gen()); // true
+ */
+declare function isAsyncIterable<T = any>(value: unknown): value is AsyncIterable<T>;
+/**
+ * Asserts that a value is of a specific type, throwing an error if not.
+ *
+ * @template T
+ * @param {unknown} value - Value to assert.
+ * @param {(value: unknown) => value is T} guard - Type guard function.
+ * @param {string} [message] - Error message if assertion fails.
+ * @returns {asserts value is T}
+ *
+ * @example
+ * assertType(value, (v): v is string => typeof v === 'string', 'Expected string');
+ */
+declare function assertType<T>(value: unknown, guard: (value: unknown) => value is T, message?: string): asserts value is T;
 
-export { ensureType, getTypeOf, isArrayOf, isDefined, isEmpty, isPrimitiveType, toBool, toNum, toStr };
+export { assertType, ensureType, getTypeOf, isArrayOf, isAsyncIterable, isDefined, isEmpty, isIterable, isPrimitiveType, toBool, toNum, toStr };

package/type/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -115,5 +115,19 @@ function isEmpty(value) {
   return false;
 }
 __name(isEmpty, "isEmpty");
+function isIterable(value) {
+  return value !== null && value !== void 0 && typeof value[Symbol.iterator] === "function";
+}
+__name(isIterable, "isIterable");
+function isAsyncIterable(value) {
+  return value !== null && value !== void 0 && typeof value[Symbol.asyncIterator] === "function";
+}
+__name(isAsyncIterable, "isAsyncIterable");
+function assertType(value, guard, message) {
+  if (!guard(value)) {
+    throw new TypeError(message || `Type assertion failed`);
+  }
+}
+__name(assertType, "assertType");
 
-export { ensureType, getTypeOf, isArrayOf, isDefined, isEmpty, isPrimitiveType, toBool, toNum, toStr };
+export { assertType, ensureType, getTypeOf, isArrayOf, isAsyncIterable, isDefined, isEmpty, isIterable, isPrimitiveType, toBool, toNum, toStr };

package/types/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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

package/types/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -24,6 +24,7 @@
 
 import { json, urlencoded, Request, Response, Express, NextFunction } from 'express';
 import http from 'node:http';
+import https from 'node:https';
 import { ExpressServer } from '@catbee/utils/server';
 import { HelmetOptions } from 'helmet';
 import { CompressionOptions } from 'compression';
@@ -554,8 +555,14 @@ interface CatbeeServerConfig {
 interface CatbeeServerHooks {
     /** Called before middleware & routes initialize */
     beforeInit?: (server: ExpressServer) => Promise<void> | void;
+    /** Called before any routes are registered */
+    beforeRoutes?: (app: Express) => Promise<void> | void;
+    /** Called after all routes are registered, before error handling middleware */
+    afterRoutes?: (app: Express) => Promise<void> | void;
     /** Called after middleware & routes initialize */
     afterInit?: (server: ExpressServer) => Promise<void> | void;
+    /** Called when the underlying HTTP/HTTPS server instance is created */
+    onServerCreated?: (server: http.Server | https.Server) => Promise<void> | void;
     /** Called before server starts listening */
     beforeStart?: (app: Express) => Promise<void> | void;
     /** Called after server is ready */
@@ -575,7 +582,7 @@ interface GlobalServerAddons {
     /**
      * Skip healthz endpoint even if health checks are configured
      *  - **default**: `false`
-     *  - **env**: `SERVER_SKIP_HEALTHZ`
+     *  - **env**: `SERVER_SKIP_HEALTHZ_CHECKS_VALIDATION`
      *
      * @additionalInfo
      * Set to true to return `200 OK` for `/healthz` without checks
@@ -586,7 +593,7 @@ interface GlobalServerAddons {
      *       Health checks can still be performed programmatically
      *       or via other endpoints if needed
      */
-    skipHealthz: boolean;
+    skipHealthzChecksValidation: boolean;
 }
 /** Combined global server configuration type */
 type CatbeeGlobalServerConfig = CatbeeServerConfig & GlobalServerAddons;

package/types/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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

package/url/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -101,6 +101,16 @@ function normalizeUrl(url$1, base) {
   }
 }
 __name(normalizeUrl, "normalizeUrl");
+function updateQueryParam(url$1, key, value) {
+  try {
+    const urlObj = new url.URL(url$1);
+    urlObj.searchParams.set(key, String(value));
+    return urlObj.toString();
+  } catch {
+    return url$1;
+  }
+}
+__name(updateQueryParam, "updateQueryParam");
 function createUrlBuilder(baseUrl) {
   return {
     /**
@@ -185,15 +195,65 @@ function parseTypedQueryParams(url$1, converters) {
   }
 }
 __name(parseTypedQueryParams, "parseTypedQueryParams");
+function getSubdomain(url$1) {
+  try {
+    const { hostname } = new url.URL(url$1);
+    const parts = hostname.split(".");
+    if (parts.length <= 2) return "";
+    return parts.slice(0, -2).join(".");
+  } catch {
+    return "";
+  }
+}
+__name(getSubdomain, "getSubdomain");
+function isRelativeUrl(url$1) {
+  if (!url$1 || typeof url$1 !== "string") return false;
+  try {
+    new url.URL(url$1);
+    return false;
+  } catch {
+    return url$1.startsWith("/") || url$1.startsWith("./") || url$1.startsWith("../");
+  }
+}
+__name(isRelativeUrl, "isRelativeUrl");
+function toAbsoluteUrl(relativeUrl, baseUrl) {
+  try {
+    return new url.URL(relativeUrl, baseUrl).toString();
+  } catch {
+    return relativeUrl;
+  }
+}
+__name(toAbsoluteUrl, "toAbsoluteUrl");
+function sanitizeUrl(url$1, allowedProtocols = [
+  "http",
+  "https"
+]) {
+  try {
+    const parsedUrl = new url.URL(url$1);
+    const protocol = parsedUrl.protocol.replace(":", "");
+    if (!allowedProtocols.includes(protocol)) {
+      return null;
+    }
+    return parsedUrl.toString();
+  } catch {
+    return null;
+  }
+}
+__name(sanitizeUrl, "sanitizeUrl");
 
 exports.appendQueryParams = appendQueryParams;
 exports.createUrlBuilder = createUrlBuilder;
 exports.extractQueryParams = extractQueryParams;
 exports.getDomain = getDomain;
 exports.getExtension = getExtension;
+exports.getSubdomain = getSubdomain;
+exports.isRelativeUrl = isRelativeUrl;
 exports.isValidUrl = isValidUrl;
 exports.joinPaths = joinPaths;
 exports.normalizeUrl = normalizeUrl;
 exports.parseQueryString = parseQueryString;
 exports.parseTypedQueryParams = parseTypedQueryParams;
 exports.removeQueryParams = removeQueryParams;
+exports.sanitizeUrl = sanitizeUrl;
+exports.toAbsoluteUrl = toAbsoluteUrl;
+exports.updateQueryParam = updateQueryParam;

package/url/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -91,6 +91,18 @@ declare function joinPaths(...segments: string[]): string;
  * // -> 'http://example.com/bar'
  */
 declare function normalizeUrl(url: string, base?: string): string;
+/**
+ * Updates or sets a single query parameter in a URL.
+ *
+ * @param {string} url - The source URL.
+ * @param {string} key - Parameter key.
+ * @param {string | number} value - Parameter value.
+ * @returns {string} URL with updated parameter.
+ *
+ * @example
+ * updateQueryParam('https://example.com?page=1', 'page', 2); // 'https://example.com?page=2'
+ */
+declare function updateQueryParam(url: string, key: string, value: string | number): string;
 /**
  * Creates a URL builder for constructing URLs with a base URL.
  *
@@ -162,5 +174,50 @@ declare function getExtension(url: string): string;
  * // -> { page: 2, q: 'test' }
  */
 declare function parseTypedQueryParams<T extends Record<string, any>>(url: string, converters?: Record<keyof T, (val: string) => any>): Partial<T>;
+/**
+ * Extracts the subdomain from a URL.
+ *
+ * @param {string} url - The URL.
+ * @returns {string} Subdomain or empty string.
+ *
+ * @example
+ * getSubdomain('https://api.example.com'); // 'api'
+ * getSubdomain('https://www.blog.example.com'); // 'www.blog'
+ */
+declare function getSubdomain(url: string): string;
+/**
+ * Checks if a URL is relative (not absolute).
+ *
+ * @param {string} url - The URL to check.
+ * @returns {boolean} True if relative.
+ *
+ * @example
+ * isRelativeUrl('/path/to/page'); // true
+ * isRelativeUrl('https://example.com/page'); // false
+ */
+declare function isRelativeUrl(url: string): boolean;
+/**
+ * Converts a relative URL to an absolute URL using a base URL.
+ *
+ * @param {string} relativeUrl - The relative URL.
+ * @param {string} baseUrl - The base URL.
+ * @returns {string} Absolute URL.
+ *
+ * @example
+ * toAbsoluteUrl('/api/users', 'https://example.com'); // 'https://example.com/api/users'
+ */
+declare function toAbsoluteUrl(relativeUrl: string, baseUrl: string): string;
+/**
+ * Sanitizes a URL by removing dangerous protocols and normalizing.
+ *
+ * @param {string} url - The URL to sanitize.
+ * @param {string[]} [allowedProtocols=['http', 'https']] - Allowed protocols.
+ * @returns {string | null} Sanitized URL or null if unsafe.
+ *
+ * @example
+ * sanitizeUrl('javascript:alert(1)'); // null
+ * sanitizeUrl('https://example.com'); // 'https://example.com/'
+ */
+declare function sanitizeUrl(url: string, allowedProtocols?: string[]): string | null;
 
-export { appendQueryParams, createUrlBuilder, extractQueryParams, getDomain, getExtension, isValidUrl, joinPaths, normalizeUrl, parseQueryString, parseTypedQueryParams, removeQueryParams };
+export { appendQueryParams, createUrlBuilder, extractQueryParams, getDomain, getExtension, getSubdomain, isRelativeUrl, isValidUrl, joinPaths, normalizeUrl, parseQueryString, parseTypedQueryParams, removeQueryParams, sanitizeUrl, toAbsoluteUrl, updateQueryParam };

package/url/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -99,6 +99,16 @@ function normalizeUrl(url, base) {
   }
 }
 __name(normalizeUrl, "normalizeUrl");
+function updateQueryParam(url, key, value) {
+  try {
+    const urlObj = new URL(url);
+    urlObj.searchParams.set(key, String(value));
+    return urlObj.toString();
+  } catch {
+    return url;
+  }
+}
+__name(updateQueryParam, "updateQueryParam");
 function createUrlBuilder(baseUrl) {
   return {
     /**
@@ -183,5 +193,50 @@ function parseTypedQueryParams(url, converters) {
   }
 }
 __name(parseTypedQueryParams, "parseTypedQueryParams");
+function getSubdomain(url) {
+  try {
+    const { hostname } = new URL(url);
+    const parts = hostname.split(".");
+    if (parts.length <= 2) return "";
+    return parts.slice(0, -2).join(".");
+  } catch {
+    return "";
+  }
+}
+__name(getSubdomain, "getSubdomain");
+function isRelativeUrl(url) {
+  if (!url || typeof url !== "string") return false;
+  try {
+    new URL(url);
+    return false;
+  } catch {
+    return url.startsWith("/") || url.startsWith("./") || url.startsWith("../");
+  }
+}
+__name(isRelativeUrl, "isRelativeUrl");
+function toAbsoluteUrl(relativeUrl, baseUrl) {
+  try {
+    return new URL(relativeUrl, baseUrl).toString();
+  } catch {
+    return relativeUrl;
+  }
+}
+__name(toAbsoluteUrl, "toAbsoluteUrl");
+function sanitizeUrl(url, allowedProtocols = [
+  "http",
+  "https"
+]) {
+  try {
+    const parsedUrl = new URL(url);
+    const protocol = parsedUrl.protocol.replace(":", "");
+    if (!allowedProtocols.includes(protocol)) {
+      return null;
+    }
+    return parsedUrl.toString();
+  } catch {
+    return null;
+  }
+}
+__name(sanitizeUrl, "sanitizeUrl");
 
-export { appendQueryParams, createUrlBuilder, extractQueryParams, getDomain, getExtension, isValidUrl, joinPaths, normalizeUrl, parseQueryString, parseTypedQueryParams, removeQueryParams };
+export { appendQueryParams, createUrlBuilder, extractQueryParams, getDomain, getExtension, getSubdomain, isRelativeUrl, isValidUrl, joinPaths, normalizeUrl, parseQueryString, parseTypedQueryParams, removeQueryParams, sanitizeUrl, toAbsoluteUrl, updateQueryParam };

package/validation/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -68,7 +68,7 @@ function isEmail(str) {
     if (!labelRegex.test(label)) return false;
     if (label.startsWith("-") || label.endsWith("-")) return false;
   }
-  const tld = labels[labels.length - 1];
+  const tld = labels.at(-1) || "";
   if (!TLD_REGEX.test(tld)) return false;
   return true;
 }
@@ -207,7 +207,7 @@ function isBase64(str) {
 __name(isBase64, "isBase64");
 function hasRequiredProps(obj, requiredProps) {
   if (!obj || typeof obj !== "object") return false;
-  return requiredProps.every((prop) => Object.prototype.hasOwnProperty.call(obj, prop) && obj[prop] != null);
+  return requiredProps.every((prop) => Object.hasOwn(obj, prop) && obj[prop] != null);
 }
 __name(hasRequiredProps, "hasRequiredProps");
 function isDateInRange(date, minDate, maxDate) {

package/validation/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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

package/validation/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -62,7 +62,7 @@ function isEmail(str) {
     if (!labelRegex.test(label)) return false;
     if (label.startsWith("-") || label.endsWith("-")) return false;
   }
-  const tld = labels[labels.length - 1];
+  const tld = labels.at(-1) || "";
   if (!TLD_REGEX.test(tld)) return false;
   return true;
 }
@@ -201,7 +201,7 @@ function isBase64(str) {
 __name(isBase64, "isBase64");
 function hasRequiredProps(obj, requiredProps) {
   if (!obj || typeof obj !== "object") return false;
-  return requiredProps.every((prop) => Object.prototype.hasOwnProperty.call(obj, prop) && obj[prop] != null);
+  return requiredProps.every((prop) => Object.hasOwn(obj, prop) && obj[prop] != null);
 }
 __name(hasRequiredProps, "hasRequiredProps");
 function isDateInRange(date, minDate, maxDate) {