feat: fix issues and improve tests

Author: cyber-hari

src/array/array.utils.ts

@@ -1,4 +1,4 @@
-import { getValueByPath } from '@catbee/utils/obj';
+import { getValueByPath } from '@catbee/utils/object';
 import { randomBytes } from 'node:crypto';
 
 /**
@@ -85,6 +85,8 @@ export function random<T>(array: readonly T[]): T | undefined {
   return array[secureIndex(array.length)];
 }
 
+type StrNumSym = string | number | symbol;
+
 /* eslint-disable no-redeclare */
 /**
  * Groups items in an array by a nested key or key function.
@@ -96,20 +98,17 @@ export 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.
  */
 export function groupBy<T>(array: T[], key: keyof T): Record<string, readonly T[]>;
-export function groupBy<T, K extends string | number | symbol>(
-  array: T[],
-  keyFn: (item: T) => K
-): Record<K, readonly T[]>;
+export function groupBy<T, K extends StrNumSym>(array: T[], keyFn: (item: T) => K): Record<K, readonly T[]>;
 export function groupBy<T>(
   array: readonly T[],
-  keyOrFn: keyof T | ((item: T) => string | number | symbol)
+  keyOrFn: keyof T | ((item: T) => StrNumSym)
 ): Record<string, readonly T[]> {
   if (!Array.isArray(array) || array.length === 0) return {};
 
@@ -119,7 +118,7 @@ export function groupBy<T>(
   const result: Record<string, T[]> = {};
   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] = [item];
@@ -403,10 +402,10 @@ export 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.
  */
-export function countBy<T>(array: readonly T[], keyFn: (item: T) => string | number | symbol): Record<string, number> {
+export function countBy<T>(array: readonly T[], keyFn: (item: T) => StrNumSym): Record<string, number> {
   if (!Array.isArray(array)) return {};
   const result: Record<string, number> = {};
   for (const item of array) {
@@ -598,3 +597,75 @@ export function headOfArr<T>(array: readonly T[]): T | undefined {
 export function lastOfArr<T>(array: readonly T[]): T | undefined {
   return Array.isArray(array) && array.length > 0 ? array.at(-1) : 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]
+ */
+export function drop<T>(array: readonly T[], n: number): T[] {
+  if (!Array.isArray(array) || n <= 0) return [...array];
+  return array.slice(n);
+}
+
+/**
+ * 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]
+ */
+export function dropWhile<T>(array: readonly T[], predicate: (item: T, index: number) => boolean): T[] {
+  if (!Array.isArray(array)) return [];
+  let i = 0;
+  while (i < array.length && predicate(array[i], i)) {
+    i++;
+  }
+  return array.slice(i);
+}
+
+/**
+ * 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}
+ */
+export function maxBy<T>(array: readonly T[], keyOrFn: keyof T | ((item: T) => number)): T | undefined {
+  if (!Array.isArray(array) || array.length === 0) return undefined;
+  const fn = typeof keyOrFn === 'function' ? keyOrFn : (item: T) => item[keyOrFn] as unknown as number;
+  return array.reduce<T>((max, item) => (fn(item) > fn(max) ? item : max), array[0]);
+}
+
+/**
+ * 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}
+ */
+export function minBy<T>(array: readonly T[], keyOrFn: keyof T | ((item: T) => number)): T | undefined {
+  if (!Array.isArray(array) || array.length === 0) return undefined;
+  const fn = typeof keyOrFn === 'function' ? keyOrFn : (item: T) => item[keyOrFn] as unknown as number;
+  return array.reduce<T>((min, item) => (fn(item) < fn(min) ? item : min), array[0]);
+}

src/async/async.utils.ts

@@ -61,6 +61,11 @@ export function debounce<T extends (...args: any[]) => void>(fn: T, delay: numbe
   };
 }
 
+const DEFAULT_THROTTLE_OPTS = {
+  leading: true,
+  trailing: false
+} as const;
+
 /**
  * Creates a throttled version of a function that limits its execution rate.
  * Allows control over leading/trailing invocation.
@@ -74,10 +79,7 @@ export function debounce<T extends (...args: any[]) => void>(fn: T, delay: numbe
 export function throttle<T extends (...args: any[]) => void>(
   fn: T,
   limit: number,
-  opts: { leading?: boolean; trailing?: boolean } = {
-    leading: true,
-    trailing: false
-  }
+  opts: { leading?: boolean; trailing?: boolean } = DEFAULT_THROTTLE_OPTS
 ): (...args: Parameters<T>) => void {
   let lastCall = 0;
   let timer: NodeJS.Timeout | null = null;
@@ -749,3 +751,32 @@ export function optionalRequire<T = any>(name: string): T | null {
     return 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
+ */
+export async function raceWithValue<T>(promises: Promise<T>[]): Promise<{ value: T; index: number }> {
+  return new Promise((resolve, reject) => {
+    let rejectedCount = 0;
+    let lastError: any;
+
+    promises.forEach((p, index) => {
+      p.then(value => resolve({ value, index })).catch(err => {
+        rejectedCount++;
+        lastError = err;
+        if (rejectedCount === promises.length) {
+          reject(lastError);
+        }
+      });
+    });
+  });
+}

src/config/config.ts

@@ -2,7 +2,7 @@ import type { CatbeeConfig, CatbeeGlobalServerConfig } from '@catbee/utils/types
 import type { Logger, LoggerLevels } from '@catbee/utils/logger';
 import { Env } from '@catbee/utils/env';
 import { uuid } from '@catbee/utils/id';
-import { deepClone, deepObjMerge } from '@catbee/utils/obj';
+import { deepClone, deepObjMerge } from '@catbee/utils/object';
 
 /**
  * Extends Express Request interface to add request ID tracking.
@@ -83,9 +83,9 @@ export const defaultServerConfig: CatbeeGlobalServerConfig = {
   serviceVersion: {
     enable: Env.getBoolean('SERVER_SERVICE_VERSION_ENABLE', false),
     headerName: Env.get('SERVER_SERVICE_VERSION_HEADER_NAME', 'x-service-version'),
-    version: Env.get('SERVER_SERVICE_VERSION', '0.0.0')
+    version: Env.get('${npm_package_version}', '0.0.0')
   },
-  skipHealthz: Env.getBoolean('SERVER_SKIP_HEALTHZ', false)
+  skipHealthzChecksValidation: Env.getBoolean('SERVER_SKIP_HEALTHZ_CHECKS_VALIDATION', false)
 } as const;
 
 /** Default Catbee configuration loaded from environment variables. */

src/context-store/context-store.utils.ts

@@ -263,8 +263,7 @@ export class TypedContextKey<T> {
    * @returns The value or defaultValue if not found
    */
   get(): T | undefined {
-    const value = ContextStore.get<T>(this.symbol);
-    return value !== undefined ? value : this.defaultValue;
+    return ContextStore.get<T>(this.symbol) ?? this.defaultValue;
   }
 
   /**

src/crypto/crypto.utils.ts

@@ -6,12 +6,18 @@ import {
   createCipheriv,
   createDecipheriv,
   scrypt,
-  timingSafeEqual
+  timingSafeEqual,
+  pbkdf2
 } from 'node:crypto';
 import type { CipherGCMTypes } from 'node:crypto';
 import { promisify } from 'node:util';
 import { uuid } from '@catbee/utils/id';
 
+// Promisified version of pbkdf2 for key derivation
+const pbkdf2Async = promisify(pbkdf2);
+// Promisified version of scrypt for key derivation
+const scryptAsync = promisify<string | Buffer, string | Buffer, number, Buffer>(scrypt);
+
 export type BufferEncoding =
   | 'ascii'
   | 'utf8'
@@ -203,11 +209,10 @@ export interface EncryptionResult {
   authTag?: Buffer;
   /** Algorithm used */
   algorithm: string;
+  /** Salt used for key derivation */
+  salt: Buffer;
 }
 
-// Promisified version of scrypt for key derivation
-const scryptAsync = promisify<string | Buffer, string | Buffer, number, Buffer>(scrypt);
-
 /**
  * Encrypts data using a symmetric key with secure defaults (AES-256-GCM).
  *
@@ -229,7 +234,8 @@ export async function encrypt(
   const iv = randomBytes(16);
 
   // Derive key using scrypt if key is a string (passphrase)
-  const derivedKey = typeof key === 'string' ? await scryptAsync(key, iv.slice(0, 8), 32) : key;
+  const salt = randomBytes(8);
+  const derivedKey = typeof key === 'string' ? await scryptAsync(key, salt, 32) : key;
 
   // Create cipher
   const cipher = createCipheriv(algorithm, derivedKey, iv);
@@ -252,7 +258,8 @@ export async function encrypt(
     ciphertext,
     iv,
     authTag,
-    algorithm
+    algorithm,
+    salt
   };
 }
 
@@ -274,7 +281,7 @@ export async function decrypt(
   const outputEncoding = options.outputEncoding || 'utf8';
 
   // Derive key using scrypt if key is a string (passphrase)
-  const derivedKey = typeof key === 'string' ? await scryptAsync(key, encryptedData.iv.slice(0, 8), 32) : key;
+  const derivedKey = typeof key === 'string' ? await scryptAsync(key, encryptedData.salt, 32) : key;
 
   // Create decipher
   const decipher = createDecipheriv(algorithm, derivedKey, encryptedData.iv);
@@ -362,3 +369,109 @@ export function verifySignedToken(token: string, secret: string): Record<string,
     return null;
   }
 }
+
+/**
+ * Derives a cryptographic key using PBKDF2 (SHA-256).
+ *
+ * @param password - Password to derive key from
+ * @param salt - Cryptographic salt (use unique per password)
+ * @param keyLength - Output key length in bytes (default 32)
+ * @param iterations - Number of hashing iterations (default 310000, OWASP recommended)
+ * @returns Derived key as Buffer
+ *
+ * @example
+ * const key = await pbkdf2Hash('myPassword', 'mySalt');
+ */
+export async function pbkdf2Hash(
+  password: string,
+  salt: string | Buffer,
+  keyLength = 32,
+  iterations = 310_000
+): Promise<Buffer> {
+  return pbkdf2Async(password, salt, iterations, keyLength, 'sha256') as Promise<Buffer>;
+}
+
+/**
+ * Generates a cryptographically secure nonce (number used once).
+ *
+ * @param {number} [byteLength=16] - Length of nonce in bytes.
+ * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
+ * @returns {string} Nonce string.
+ *
+ * @example
+ * const nonce = generateNonce(16, 'base64'); // Random nonce
+ */
+export function generateNonce(byteLength: number = 16, encoding: BinaryToTextEncoding = 'hex'): string {
+  return randomBytes(byteLength).toString(encoding);
+}
+
+/**
+ * Generates a cryptographically secure random integer in a range.
+ *
+ * @param {number} min - Minimum value (inclusive).
+ * @param {number} max - Maximum value (inclusive).
+ * @returns {number} Random integer.
+ *
+ * @example
+ * const random = secureRandomInt(1, 100); // Random number 1-100
+ */
+export function secureRandomInt(min: number, max: number): number {
+  if (min > max) throw new Error('min must be less than or equal to max');
+  const range = max - min + 1;
+  const bytesNeeded = Math.ceil(Math.log2(range) / 8);
+  const maxValid = Math.floor(256 ** bytesNeeded / range) * range;
+
+  let randomValue: number;
+  do {
+    const bytes = randomBytes(bytesNeeded);
+    randomValue = bytes.reduce((acc, byte, i) => acc + byte * 256 ** i, 0);
+  } while (randomValue >= maxValid);
+
+  return min + (randomValue % range);
+}
+
+/**
+ * Hashes a password using scrypt (memory-hard function).
+ *
+ * @param {string} password - The password to hash.
+ * @param {number} [saltLength=16] - Length of salt in bytes.
+ * @param {number} [keyLength=32] - Length of derived key.
+ * @returns {Promise<string>} Hash string containing salt and key.
+ *
+ * @example
+ * const hash = await hashPassword('myPassword');
+ * // Returns format: salt:hash (both base64)
+ */
+export async function hashPassword(password: string, saltLength: number = 16, keyLength: number = 32): Promise<string> {
+  const salt = randomBytes(saltLength);
+  const scryptAsync = promisify(scrypt);
+  const derivedKey = (await scryptAsync(password, salt, keyLength)) as Buffer;
+  return `${salt.toString('base64')}:${derivedKey.toString('base64')}`;
+}
+
+/**
+ * Verifies a password against a scrypt hash.
+ *
+ * @param {string} password - The password to verify.
+ * @param {string} hash - The hash to verify against (from hashPassword).
+ * @returns {Promise<boolean>} True if password matches.
+ *
+ * @example
+ * const isValid = await verifyPassword('myPassword', storedHash);
+ */
+export async function verifyPassword(password: string, hash: string): Promise<boolean> {
+  try {
+    const [saltB64, keyB64] = hash.split(':');
+    if (!saltB64 || !keyB64) return false;
+
+    const salt = Buffer.from(saltB64, 'base64');
+    const key = Buffer.from(keyB64, 'base64');
+
+    const scryptAsync = promisify(scrypt);
+    const derivedKey = (await scryptAsync(password, salt, key.length)) as Buffer;
+
+    return timingSafeEqual(key, derivedKey);
+  } catch {
+    return false;
+  }
+}