@catbee/utils 2.0.0-next.1 → 2.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 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/README.md

@@ -1,18 +1,12 @@
 # @catbee/utils
 
-<!-- <div style="width: 100%; display: flex; align-items: center; justify-content: space-between;">
-  <b style="font-size: 24px; text-decoration: none;">@catbee/utils</b>
-  <a href="https://sonarcloud.io/summary/new_code?id=catbee-technologies_catbee-utils">
-    <img src="https://sonarcloud.io/images/project_badges/sonarcloud-dark.svg" alt="SonarQube Cloud" width="200"/>
-  </a>
-</div> -->
 
 ## 🧰 Utility Modules for Node.js
 
 A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications. All utilities are tree-shakable and can be imported independently.
 
 <div style="display: flex; flex-wrap: wrap; gap: 0.5rem; margin: 1rem 0;">
-  <img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build Status" />
+  <img src="https://github.com/catbee-technologies/catbee-utils/actions/workflows/ci.yml/badge.svg?label=Build" alt="Build Status" />
   <img src="https://codecov.io/gh/catbee-technologies/catbee-utils/graph/badge.svg?token=XAJHK6R1OQ" alt="Coverage" />
   <img src="https://img.shields.io/node/v/@catbee/utils" alt="Node Version" />
   <img src="https://img.shields.io/npm/v/@catbee/utils" alt="NPM Version" />
@@ -20,7 +14,7 @@ A modular, production-grade utility toolkit for Node.js and TypeScript, designed
   <img src="https://img.shields.io/npm/v/@catbee/utils/next" alt="NPM Next Version" /> -->
   <img src="https://img.shields.io/npm/dt/@catbee/utils" alt="NPM Downloads" />
   <img src="https://img.shields.io/npm/types/@catbee/utils" alt="TypeScript Types" />
-  <img src="https://img.shields.io/maintenance/yes/2025" alt="Maintenance" />
+  <img src="https://img.shields.io/maintenance/yes/2050" alt="Maintenance" />
   <img src="https://snyk.io/test/github/catbee-technologies/catbee-utils/badge.svg" alt="Snyk Vulnerabilities" />
   <img src="https://sonarcloud.io/api/project_badges/measure?project=catbee-technologies_catbee-utils&metric=alert_status&token=93da835f2d48d37b41fa628cc7fc764c873bd700" alt="Quality Gate Status" />
   <img src="https://sonarcloud.io/api/project_badges/measure?project=catbee-technologies_catbee-utils&metric=ncloc&token=93da835f2d48d37b41fa628cc7fc764c873bd700" alt="Lines of Code" />
@@ -71,7 +65,10 @@ const config = new ServerConfigBuilder()
 
 const server = new ExpressServer(config, {
   beforeInit: srv => console.log('Initializing server...'),
+  beforeRoutes: app => console.log('Setting up routes...'),
+  afterRoutes: app => console.log('Routes initialized.'),
   afterInit: srv => console.log('Server initialized'),
+  onServerCreated: srv => console.log('HTTP/HTTPS server instance created.'),
   beforeStart: app => console.log('Starting server...'),
   afterStart: srv => console.log('Server started!'),
   beforeStop: srv => console.log('Stopping server...'),
@@ -111,44 +108,64 @@ server.enableGracefulShutdown();
 
 ## 📚 Modules Overview
 
-| Module | Description |
-| ------ | ----------- |
-| [Express Server](https://catbee.in/docs/@catbee/utils/express-server) | Fast, secure, and scalable server setup |
-| [Array Utilities](https://catbee.in/docs/@catbee/utils/modules/array) | Advanced array manipulation |
-| [Async Utilities](https://catbee.in/docs/@catbee/utils/modules/async) | Promise helpers, concurrency, timing |
-| [Cache Utilities](https://catbee.in/docs/@catbee/utils/modules/cache) | In-memory caching with TTL |
-| [Context Store](https://catbee.in/docs/@catbee/utils/modules/context-store) | Per-request context via AsyncLocalStorage |
-| [Crypto Utilities](https://catbee.in/docs/@catbee/utils/modules/crypto) | Hashing, encryption, tokens |
-| [Date Utilities](https://catbee.in/docs/@catbee/utils/modules/date) | Date/time manipulation |
-| [Decorators Utilities](https://catbee.in/docs/@catbee/utils/modules/decorators) | TypeScript decorators for Express |
-| [Directory Utilities](https://catbee.in/docs/@catbee/utils/modules/directory) | Directory and file system helpers |
-| [Environment Utilities](https://catbee.in/docs/@catbee/utils/modules/environment) | Env variable management |
-| [Exception Utilities](https://catbee.in/docs/@catbee/utils/modules/exception) | HTTP and error handling |
-| [File System Utilities](https://catbee.in/docs/@catbee/utils/modules/file-system) | File operations |
-| [HTTP Status Codes](https://catbee.in/docs/@catbee/utils/modules/http-status-codes) | Typed status codes |
-| [ID Utilities](https://catbee.in/docs/@catbee/utils/modules/id) | UUID and ID generation |
-| [Logger Utilities](https://catbee.in/docs/@catbee/utils/modules/logger) | Structured logging with Pino |
-| [Middleware Utilities](https://catbee.in/docs/@catbee/utils/modules/middleware) | Express middleware collection |
-| [Object Utilities](https://catbee.in/docs/@catbee/utils/modules/object) | Deep merge, flatten, pick/omit, etc. |
-| [Performance Utilities](https://catbee.in/docs/@catbee/utils/modules/performance) | Timing, memoization, memory tracking |
-| [Request Utilities](https://catbee.in/docs/@catbee/utils/modules/request) | HTTP request parameter parsing/validation |
-| [Response Utilities](https://catbee.in/docs/@catbee/utils/modules/response) | Standardized API response formatting |
-| [Stream Utilities](https://catbee.in/docs/@catbee/utils/modules/stream) | Stream conversion, batching, throttling, line splitting |
-| [String Utilities](https://catbee.in/docs/@catbee/utils/modules/string) | Casing, masking, slugifying, formatting |
-| [Type Utilities](https://catbee.in/docs/@catbee/utils/modules/type) | Type checking, conversion, guards |
-| [URL Utilities](https://catbee.in/docs/@catbee/utils/modules/url) | URL parsing, query manipulation, normalization |
-| [Validate Utilities](https://catbee.in/docs/@catbee/utils/modules/validation) | Input validation functions |
+| Module                                                                      | Description                                             |
+| --------------------------------------------------------------------------- | ------------------------------------------------------- |
+| [Express Server](https://catbee.in/docs/@catbee/utils/server)               | Fast, secure, and scalable server setup                 |
+| [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                              |
+| [Context Store](https://catbee.in/docs/@catbee/utils/context-store)         | Per-request context via AsyncLocalStorage               |
+| [Crypto Utilities](https://catbee.in/docs/@catbee/utils/crypto)             | Hashing, encryption, tokens                             |
+| [Date Utilities](https://catbee.in/docs/@catbee/utils/date)                 | Date/time manipulation                                  |
+| [Decorators Utilities](https://catbee.in/docs/@catbee/utils/decorator)      | TypeScript decorators for Express                       |
+| [Directory Utilities](https://catbee.in/docs/@catbee/utils/directory)       | Directory and file system helpers                       |
+| [Environment Utilities](https://catbee.in/docs/@catbee/utils/environment)   | Env variable management                                 |
+| [Exception Utilities](https://catbee.in/docs/@catbee/utils/exception)       | HTTP and error handling                                 |
+| [File System Utilities](https://catbee.in/docs/@catbee/utils/fs)            | File operations                                         |
+| [HTTP Status Codes](https://catbee.in/docs/@catbee/utils/http-status-codes) | Typed status codes                                      |
+| [ID Utilities](https://catbee.in/docs/@catbee/utils/id)                     | UUID and ID generation                                  |
+| [Logger Utilities](https://catbee.in/docs/@catbee/utils/logger)             | Structured logging with Pino                            |
+| [Middleware Utilities](https://catbee.in/docs/@catbee/utils/middleware)     | Express middleware collection                           |
+| [Object Utilities](https://catbee.in/docs/@catbee/utils/object)             | Deep merge, flatten, pick/omit, etc.                    |
+| [Performance Utilities](https://catbee.in/docs/@catbee/utils/performance)   | Timing, memoization, memory tracking                    |
+| [Request Utilities](https://catbee.in/docs/@catbee/utils/request)           | HTTP request parameter parsing/validation               |
+| [Response Utilities](https://catbee.in/docs/@catbee/utils/response)         | Standardized API response formatting                    |
+| [Stream Utilities](https://catbee.in/docs/@catbee/utils/stream)             | Stream conversion, batching, throttling, line splitting |
+| [String Utilities](https://catbee.in/docs/@catbee/utils/string)             | Casing, masking, slugifying, formatting                 |
+| [Type Utilities](https://catbee.in/docs/@catbee/utils/type)                 | Type checking, conversion, guards                       |
+| [Types Utilities](https://catbee.in/docs/@catbee/utils/types)               | Common TypeScript types and interfaces                  |
+| [URL Utilities](https://catbee.in/docs/@catbee/utils/url)                   | URL parsing, query manipulation, normalization          |
+| [Validate Utilities](https://catbee.in/docs/@catbee/utils/validation)       | Input validation functions                              |
 
 ---
 
 ## 🏁 Usage
 
-Import only what you need:
+This library supports flexible import patterns to suit your needs:
+
+### Root-level imports (everything available)
+Import any utility directly from the root package:
 
 ```ts
-import { chunk, sleep, TTLCache, getLogger } from "@catbee/utils";
+import { chunk, sleep, TTLCache, getLogger, ServerConfigBuilder } from '@catbee/utils';
 ```
 
+### Module-level imports (scoped imports)
+Import only from specific modules for better organization and smaller bundles:
+
+```ts
+// Import only server-related exports
+import { ServerConfigBuilder, ExpressServer } from '@catbee/utils/server';
+
+// Import only date utilities
+import { formatDate, addDays, DateBuilder } from '@catbee/utils/date';
+
+// Import only crypto utilities
+import { hashPassword, verifyPassword } from '@catbee/utils/crypto';
+```
+
+Both import styles are fully supported and tree-shakable. Use whichever fits your project structure best!
+
 ---
 
 ## 📖 Documentation
@@ -159,4 +176,4 @@ import { chunk, sleep, TTLCache, getLogger } from "@catbee/utils";
 
 ## 📜 License
 
-MIT © Catbee Technologies (see the [LICENSE](https://catbee.in/license/) file for the full text)
+MIT © Catbee Technologies (see the [LICENSE](https://catbee.in/license) file for the full text)

package/array/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
@@ -24,7 +24,7 @@
 
 'use strict';
 
-var obj = require('@catbee/utils/obj');
+var object = require('@catbee/utils/object');
 var crypto = require('crypto');
 
 var __defProp = Object.defineProperty;
@@ -79,11 +79,11 @@ function random(array) {
 __name(random, "random");
 function groupBy(array, keyOrFn) {
   if (!Array.isArray(array) || array.length === 0) return {};
-  const keyFn = typeof keyOrFn === "function" ? keyOrFn : (item) => String(obj.getValueByPath(item, keyOrFn));
+  const keyFn = typeof keyOrFn === "function" ? keyOrFn : (item) => String(object.getValueByPath(item, keyOrFn));
   const result = {};
   for (const item of array) {
     const key = String(keyFn(item));
-    if (Object.hasOwn?.(result, key) ?? Object.prototype.hasOwnProperty.call(result, key)) {
+    if (Object.hasOwn(result, key)) {
       result[key].push(item);
     } else {
       result[key] = [
@@ -131,7 +131,7 @@ function mergeSort(array, key, direction = "asc", compareFn) {
   if (!Array.isArray(array)) throw new TypeError("Expected array");
   const arr = array.slice();
   if (arr.length <= 1) return arr;
-  const keyFn = typeof key === "function" ? key : (item) => obj.getValueByPath(item, key);
+  const keyFn = typeof key === "function" ? key : (item) => object.getValueByPath(item, key);
   const collator = new Intl.Collator("en", {
     numeric: true
   });
@@ -325,12 +325,42 @@ function lastOfArr(array) {
   return Array.isArray(array) && array.length > 0 ? array.at(-1) : void 0;
 }
 __name(lastOfArr, "lastOfArr");
+function drop(array, n) {
+  if (!Array.isArray(array) || n <= 0) return [
+    ...array
+  ];
+  return array.slice(n);
+}
+__name(drop, "drop");
+function dropWhile(array, predicate) {
+  if (!Array.isArray(array)) return [];
+  let i = 0;
+  while (i < array.length && predicate(array[i], i)) {
+    i++;
+  }
+  return array.slice(i);
+}
+__name(dropWhile, "dropWhile");
+function maxBy(array, keyOrFn) {
+  if (!Array.isArray(array) || array.length === 0) return void 0;
+  const fn = typeof keyOrFn === "function" ? keyOrFn : (item) => item[keyOrFn];
+  return array.reduce((max, item) => fn(item) > fn(max) ? item : max, array[0]);
+}
+__name(maxBy, "maxBy");
+function minBy(array, keyOrFn) {
+  if (!Array.isArray(array) || array.length === 0) return void 0;
+  const fn = typeof keyOrFn === "function" ? keyOrFn : (item) => item[keyOrFn];
+  return array.reduce((min, item) => fn(item) < fn(min) ? item : min, array[0]);
+}
+__name(minBy, "minBy");
 
 exports.chunk = chunk;
 exports.chunkBy = chunkBy;
 exports.compact = compact;
 exports.countBy = countBy;
 exports.difference = difference;
+exports.drop = drop;
+exports.dropWhile = dropWhile;
 exports.findLast = findLast;
 exports.findLastIndex = findLastIndex;
 exports.flattenDeep = flattenDeep;
@@ -339,7 +369,9 @@ exports.headOfArr = headOfArr;
 exports.intersect = intersect;
 exports.isSorted = isSorted;
 exports.lastOfArr = lastOfArr;
+exports.maxBy = maxBy;
 exports.mergeSort = mergeSort;
+exports.minBy = minBy;
 exports.partition = partition;
 exports.pluck = pluck;
 exports.random = random;

package/array/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
@@ -64,6 +64,7 @@ declare function flattenDeep<T>(array: readonly unknown[]): T[];
  * ```
  */
 declare function random<T>(array: readonly T[]): T | undefined;
+type StrNumSym = string | number | symbol;
 /**
  * Groups items in an array by a nested key or key function.
  *
@@ -74,14 +75,14 @@ declare function random<T>(array: readonly T[]): T | undefined;
  * @returns {Record<string, readonly T[]>}
  * @overload
  * @param {T[]} array - The array to group.
- * @param {(item: T) => string | number | symbol} keyFn - Function to generate group key from item.
+ * @param {(item: T) => StrNumSym} keyFn - Function to generate group key from item.
  * @returns {Record<K, readonly T[]>}
  * @param {T[]} array - The array to group.
- * @param {keyof T | ((item: T) => string | number | symbol)} keyOrFn - Nested property key or key selector.
- * @returns {Record<string | number | symbol, readonly T[]>} Grouped result object.
+ * @param {keyof T | ((item: T) => StrNumSym)} keyOrFn - Nested property key or key selector.
+ * @returns {Record<StrNumSym, readonly T[]>} Grouped result object.
  */
 declare function groupBy<T>(array: T[], key: keyof T): Record<string, readonly T[]>;
-declare function groupBy<T, K extends string | number | symbol>(array: T[], keyFn: (item: T) => K): Record<K, readonly T[]>;
+declare function groupBy<T, K extends StrNumSym>(array: T[], keyFn: (item: T) => K): Record<K, readonly T[]>;
 /**
  * Shuffles an array using the Fisher-Yates algorithm. Uses crypto-secure randomness.
  *
@@ -209,10 +210,10 @@ declare function compact<T>(array: readonly T[]): NonNullable<T>[];
  *
  * @template T The type of array elements.
  * @param {T[]} array - The input array.
- * @param {(item: T) => string | number | symbol} keyFn - Function to generate count key.
+ * @param {(item: T) => StrNumSym} keyFn - Function to generate count key.
  * @returns {Record<string, number>} Object with counts by key.
  */
-declare function countBy<T>(array: readonly T[], keyFn: (item: T) => string | number | symbol): Record<string, number>;
+declare function countBy<T>(array: readonly T[], keyFn: (item: T) => StrNumSym): Record<string, number>;
 /**
  * Toggles an item in array (adds if not present, removes if present).
  *
@@ -313,5 +314,55 @@ declare function headOfArr<T>(array: readonly T[]): T | undefined;
  * @returns {T | undefined}
  */
 declare function lastOfArr<T>(array: readonly T[]): T | undefined;
+/**
+ * Drops the first n elements from an array.
+ *
+ * @template T
+ * @param {readonly T[]} array - The source array.
+ * @param {number} n - Number of elements to drop.
+ * @returns {T[]} Array with first n elements removed.
+ *
+ * @example
+ * drop([1, 2, 3, 4, 5], 2); // [3, 4, 5]
+ */
+declare function drop<T>(array: readonly T[], n: number): T[];
+/**
+ * Drops elements from the start of an array while predicate returns true.
+ *
+ * @template T
+ * @param {readonly T[]} array - The source array.
+ * @param {(item: T, index: number) => boolean} predicate - Condition function.
+ * @returns {T[]} Array with elements dropped.
+ *
+ * @example
+ * dropWhile([1, 2, 3, 4, 1], x => x < 3); // [3, 4, 1]
+ */
+declare function dropWhile<T>(array: readonly T[], predicate: (item: T, index: number) => boolean): T[];
+/**
+ * Finds the element with the maximum value for a given key or function.
+ *
+ * @template T
+ * @param {readonly T[]} array - The source array.
+ * @param {keyof T | ((item: T) => number)} keyOrFn - Property key or function.
+ * @returns {T | undefined} Element with maximum value.
+ *
+ * @example
+ * maxBy([{a: 1}, {a: 5}, {a: 3}], 'a'); // {a: 5}
+ * maxBy([{a: 1}, {a: 5}, {a: 3}], x => x.a); // {a: 5}
+ */
+declare function maxBy<T>(array: readonly T[], keyOrFn: keyof T | ((item: T) => number)): T | undefined;
+/**
+ * Finds the element with the minimum value for a given key or function.
+ *
+ * @template T
+ * @param {readonly T[]} array - The source array.
+ * @param {keyof T | ((item: T) => number)} keyOrFn - Property key or function.
+ * @returns {T | undefined} Element with minimum value.
+ *
+ * @example
+ * minBy([{a: 1}, {a: 5}, {a: 3}], 'a'); // {a: 1}
+ * minBy([{a: 1}, {a: 5}, {a: 3}], x => x.a); // {a: 1}
+ */
+declare function minBy<T>(array: readonly T[], keyOrFn: keyof T | ((item: T) => number)): T | undefined;
 
-export { chunk, chunkBy, compact, countBy, difference, findLast, findLastIndex, flattenDeep, groupBy, headOfArr, intersect, isSorted, lastOfArr, mergeSort, partition, pluck, random, range, remove, secureIndex, secureRandom, shuffle, take, takeWhile, toggle, unique, zip };
+export { chunk, chunkBy, compact, countBy, difference, drop, dropWhile, findLast, findLastIndex, flattenDeep, groupBy, headOfArr, intersect, isSorted, lastOfArr, maxBy, mergeSort, minBy, partition, pluck, random, range, remove, secureIndex, secureRandom, shuffle, take, takeWhile, toggle, unique, zip };

package/array/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
@@ -22,7 +22,7 @@
  * SOFTWARE.
  */
 
-import { getValueByPath } from '@catbee/utils/obj';
+import { getValueByPath } from '@catbee/utils/object';
 import { randomBytes } from 'crypto';
 
 var __defProp = Object.defineProperty;
@@ -81,7 +81,7 @@ function groupBy(array, keyOrFn) {
   const result = {};
   for (const item of array) {
     const key = String(keyFn(item));
-    if (Object.hasOwn?.(result, key) ?? Object.prototype.hasOwnProperty.call(result, key)) {
+    if (Object.hasOwn(result, key)) {
       result[key].push(item);
     } else {
       result[key] = [
@@ -323,5 +323,33 @@ function lastOfArr(array) {
   return Array.isArray(array) && array.length > 0 ? array.at(-1) : void 0;
 }
 __name(lastOfArr, "lastOfArr");
+function drop(array, n) {
+  if (!Array.isArray(array) || n <= 0) return [
+    ...array
+  ];
+  return array.slice(n);
+}
+__name(drop, "drop");
+function dropWhile(array, predicate) {
+  if (!Array.isArray(array)) return [];
+  let i = 0;
+  while (i < array.length && predicate(array[i], i)) {
+    i++;
+  }
+  return array.slice(i);
+}
+__name(dropWhile, "dropWhile");
+function maxBy(array, keyOrFn) {
+  if (!Array.isArray(array) || array.length === 0) return void 0;
+  const fn = typeof keyOrFn === "function" ? keyOrFn : (item) => item[keyOrFn];
+  return array.reduce((max, item) => fn(item) > fn(max) ? item : max, array[0]);
+}
+__name(maxBy, "maxBy");
+function minBy(array, keyOrFn) {
+  if (!Array.isArray(array) || array.length === 0) return void 0;
+  const fn = typeof keyOrFn === "function" ? keyOrFn : (item) => item[keyOrFn];
+  return array.reduce((min, item) => fn(item) < fn(min) ? item : min, array[0]);
+}
+__name(minBy, "minBy");
 
-export { chunk, chunkBy, compact, countBy, difference, findLast, findLastIndex, flattenDeep, groupBy, headOfArr, intersect, isSorted, lastOfArr, mergeSort, partition, pluck, random, range, remove, secureIndex, secureRandom, shuffle, take, takeWhile, toggle, unique, zip };
+export { chunk, chunkBy, compact, countBy, difference, drop, dropWhile, findLast, findLastIndex, flattenDeep, groupBy, headOfArr, intersect, isSorted, lastOfArr, maxBy, mergeSort, minBy, partition, pluck, random, range, remove, secureIndex, secureRandom, shuffle, take, takeWhile, toggle, unique, zip };

package/async/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
@@ -78,10 +78,11 @@ function debounce(fn, delay) {
   return debounced;
 }
 __name(debounce, "debounce");
-function throttle(fn, limit, opts = {
+var DEFAULT_THROTTLE_OPTS = {
   leading: true,
   trailing: false
-}) {
+};
+function throttle(fn, limit, opts = DEFAULT_THROTTLE_OPTS) {
   let lastCall = 0;
   let timer = null;
   let savedArgs = null;
@@ -461,6 +462,25 @@ function optionalRequire(name) {
   }
 }
 __name(optionalRequire, "optionalRequire");
+async function raceWithValue(promises) {
+  return new Promise((resolve, reject) => {
+    let rejectedCount = 0;
+    let lastError;
+    promises.forEach((p, index) => {
+      p.then((value) => resolve({
+        value,
+        index
+      })).catch((err) => {
+        rejectedCount++;
+        lastError = err;
+        if (rejectedCount === promises.length) {
+          reject(lastError);
+        }
+      });
+    });
+  });
+}
+__name(raceWithValue, "raceWithValue");
 
 exports.CircuitBreakerOpenError = CircuitBreakerOpenError;
 exports.CircuitBreakerState = CircuitBreakerState;
@@ -471,6 +491,7 @@ exports.createTaskQueue = createTaskQueue;
 exports.debounce = debounce;
 exports.memoizeAsync = memoizeAsync;
 exports.optionalRequire = optionalRequire;
+exports.raceWithValue = raceWithValue;
 exports.rateLimit = rateLimit;
 exports.retry = retry;
 exports.runInBatches = runInBatches;

package/async/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
@@ -294,6 +294,22 @@ declare function runWithConcurrency<T>(tasks: Array<() => Promise<T>>, options?:
  * @returns {T | null} The required module or null if not found.
  */
 declare function optionalRequire<T = any>(name: string): T | null;
+/**
+ * Races promises and returns the first fulfilled value with its index.
+ * If all promises reject, the last rejection is thrown.
+ *
+ * @template T
+ * @param {Promise<T>[]} promises - Array of promises.
+ * @returns {Promise<{ value: T; index: number }>} First fulfilled value with index.
+ *
+ * @example
+ * const result = await raceWithValue([fetchA(), fetchB(), fetchC()]);
+ * console.log(result.value, result.index); // First fulfilled promise result
+ */
+declare function raceWithValue<T>(promises: Promise<T>[]): Promise<{
+    value: T;
+    index: number;
+}>;
 
-export { CircuitBreakerOpenError, CircuitBreakerState, abortable, circuitBreaker, createDeferred, createTaskQueue, debounce, memoizeAsync, optionalRequire, rateLimit, retry, runInBatches, runInSeries, runWithConcurrency, settleAll, singletonAsync, sleep, throttle, waterfall, withTimeout };
+export { CircuitBreakerOpenError, CircuitBreakerState, abortable, circuitBreaker, createDeferred, createTaskQueue, debounce, memoizeAsync, optionalRequire, raceWithValue, rateLimit, retry, runInBatches, runInSeries, runWithConcurrency, settleAll, singletonAsync, sleep, throttle, waterfall, withTimeout };
 export type { CircuitBreakerOptions, TaskQueue };

package/async/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
@@ -76,10 +76,11 @@ function debounce(fn, delay) {
   return debounced;
 }
 __name(debounce, "debounce");
-function throttle(fn, limit, opts = {
+var DEFAULT_THROTTLE_OPTS = {
   leading: true,
   trailing: false
-}) {
+};
+function throttle(fn, limit, opts = DEFAULT_THROTTLE_OPTS) {
   let lastCall = 0;
   let timer = null;
   let savedArgs = null;
@@ -459,5 +460,24 @@ function optionalRequire(name) {
   }
 }
 __name(optionalRequire, "optionalRequire");
+async function raceWithValue(promises) {
+  return new Promise((resolve, reject) => {
+    let rejectedCount = 0;
+    let lastError;
+    promises.forEach((p, index) => {
+      p.then((value) => resolve({
+        value,
+        index
+      })).catch((err) => {
+        rejectedCount++;
+        lastError = err;
+        if (rejectedCount === promises.length) {
+          reject(lastError);
+        }
+      });
+    });
+  });
+}
+__name(raceWithValue, "raceWithValue");
 
-export { CircuitBreakerOpenError, CircuitBreakerState, abortable, circuitBreaker, createDeferred, createTaskQueue, debounce, memoizeAsync, optionalRequire, rateLimit, retry, runInBatches, runInSeries, runWithConcurrency, settleAll, singletonAsync, sleep, throttle, waterfall, withTimeout };
+export { CircuitBreakerOpenError, CircuitBreakerState, abortable, circuitBreaker, createDeferred, createTaskQueue, debounce, memoizeAsync, optionalRequire, raceWithValue, rateLimit, retry, runInBatches, runInSeries, runWithConcurrency, settleAll, singletonAsync, sleep, throttle, waterfall, withTimeout };

package/cache/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/cache/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/cache/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/config/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
@@ -26,7 +26,7 @@
 
 var env = require('@catbee/utils/env');
 var id = require('@catbee/utils/id');
-var obj = require('@catbee/utils/obj');
+var object = require('@catbee/utils/object');
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -102,9 +102,9 @@ var defaultServerConfig = {
   serviceVersion: {
     enable: env.Env.getBoolean("SERVER_SERVICE_VERSION_ENABLE", false),
     headerName: env.Env.get("SERVER_SERVICE_VERSION_HEADER_NAME", "x-service-version"),
-    version: env.Env.get("SERVER_SERVICE_VERSION", "0.0.0")
+    version: env.Env.get("${npm_package_version}", "0.0.0")
   },
-  skipHealthz: env.Env.getBoolean("SERVER_SKIP_HEALTHZ", false)
+  skipHealthzChecksValidation: env.Env.getBoolean("SERVER_SKIP_HEALTHZ_CHECKS_VALIDATION", false)
 };
 var defaultCatbeeConfig = {
   logger: {
@@ -122,19 +122,19 @@ var defaultCatbeeConfig = {
   },
   server: defaultServerConfig
 };
-var _config = obj.deepClone(defaultCatbeeConfig);
+var _config = object.deepClone(defaultCatbeeConfig);
 function getCatbeeGlobalConfig() {
-  return obj.deepClone(_config);
+  return object.deepClone(_config);
 }
 __name(getCatbeeGlobalConfig, "getCatbeeGlobalConfig");
 var getConfig = getCatbeeGlobalConfig;
 function setCatbeeGlobalConfig(value) {
-  _config = obj.deepObjMerge(_config, value);
+  _config = object.deepObjMerge(_config, value);
 }
 __name(setCatbeeGlobalConfig, "setCatbeeGlobalConfig");
 var setConfig = setCatbeeGlobalConfig;
 function setCatbeeServerGlobalConfig(value) {
-  _config.server = obj.deepObjMerge(_config.server, value);
+  _config.server = object.deepObjMerge(_config.server, value);
 }
 __name(setCatbeeServerGlobalConfig, "setCatbeeServerGlobalConfig");
 function getCatbeeServerGlobalConfig() {

package/config/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