@pawells/typescript-common 1.4.1 → 2.1.5

package/{build → dist}/array/array-sample.js

@@ -1,23 +1,14 @@
 export function ArraySample(array, n, random) {
-    // Handle overload where second argument is RNG function
-    let sampleCount;
-    let rng = random ?? Math.random;
-    if (typeof n === 'function') {
-        rng = n;
-        sampleCount = undefined;
-    }
-    else {
-        sampleCount = n;
-    }
+    const rng = random ?? Math.random;
     if (!array || array.length === 0) {
-        return sampleCount !== undefined ? [] : undefined;
+        return n !== undefined ? [] : undefined;
     }
-    if (sampleCount === undefined) {
+    if (n === undefined) {
         return array[Math.floor(rng() * array.length)];
     }
     // Fisher-Yates partial shuffle for O(n) sampling
     const copy = [...array];
-    const count = Math.min(sampleCount, copy.length);
+    const count = Math.min(n, copy.length);
     for (let i = 0; i < count; i++) {
         const j = i + Math.floor(rng() * (copy.length - i));
         const tmp = copy[j];
@@ -26,4 +17,3 @@ export function ArraySample(array, n, random) {
     }
     return copy.slice(0, count);
 }
-//# sourceMappingURL=array-sample.js.map

package/{build → dist}/array/array-shuffle.d.ts

@@ -4,7 +4,7 @@
  * @template T - The type of array elements
  * @param array - The array to shuffle
  * @param random - Optional custom RNG function (returns number between 0 and 1). Defaults to `Math.random`.
- * @returns A new shuffled array (original is not mutated)
+ * @returns A new shuffled array (original is not mutated). Returns `[]` if `array` is `null` or `undefined`.
  *
  * @remarks Uses `Math.random()` by default — not cryptographically secure. Do not use for
  * security-sensitive operations.

package/{build → dist}/array/array-shuffle.js

@@ -4,7 +4,7 @@
  * @template T - The type of array elements
  * @param array - The array to shuffle
  * @param random - Optional custom RNG function (returns number between 0 and 1). Defaults to `Math.random`.
- * @returns A new shuffled array (original is not mutated)
+ * @returns A new shuffled array (original is not mutated). Returns `[]` if `array` is `null` or `undefined`.
  *
  * @remarks Uses `Math.random()` by default — not cryptographically secure. Do not use for
  * security-sensitive operations.
@@ -28,4 +28,3 @@ export function ArrayShuffle(array, random) {
     }
     return result;
 }
-//# sourceMappingURL=array-shuffle.js.map

package/{build → dist}/array/array-sort-by.d.ts

@@ -6,7 +6,7 @@ import type { TTransform } from './types.js';
  * @param array - The array to sort
  * @param keyFn - Function that extracts the sort key from each element
  * @param direction - Sort direction: `'asc'` (default) or `'desc'`
- * @returns A sorted copy of the array
+ * @returns A sorted copy of the array. Returns `[]` if `array` is `null` or `undefined`.
  *
  * @example
  * ```typescript

package/{build → dist}/array/array-sort-by.js

@@ -5,7 +5,7 @@
  * @param array - The array to sort
  * @param keyFn - Function that extracts the sort key from each element
  * @param direction - Sort direction: `'asc'` (default) or `'desc'`
- * @returns A sorted copy of the array
+ * @returns A sorted copy of the array. Returns `[]` if `array` is `null` or `undefined`.
  *
  * @example
  * ```typescript
@@ -28,4 +28,3 @@ export function ArraySortBy(array, keyFn, direction = 'asc') {
         return 0;
     });
 }
-//# sourceMappingURL=array-sort-by.js.map

package/{build → dist}/array/array-zip.d.ts

@@ -3,7 +3,7 @@
  * The result length is capped at the shortest input array.
  *
  * @param arrays - Two or more arrays to zip
- * @returns Array of tuples — one tuple per index position
+ * @returns Array of tuples — one tuple per index position. Returns `[]` if `arrays` is empty or if any input array is `null` or `undefined`.
  *
  * @example
  * ```typescript

package/{build → dist}/array/array-zip.js

@@ -3,7 +3,7 @@
  * The result length is capped at the shortest input array.
  *
  * @param arrays - Two or more arrays to zip
- * @returns Array of tuples — one tuple per index position
+ * @returns Array of tuples — one tuple per index position. Returns `[]` if `arrays` is empty or if any input array is `null` or `undefined`.
  *
  * @example
  * ```typescript
@@ -22,4 +22,3 @@ export function ArrayZip(...arrays) {
     const minLen = Math.min(...arrays.map((a) => a.length));
     return Array.from({ length: minLen }, (_, i) => arrays.map((a) => a[i]));
 }
-//# sourceMappingURL=array-zip.js.map

package/{build → dist}/array/assert.d.ts

@@ -15,10 +15,6 @@ export interface IAssertArrayArgs {
     /** Maximum number of elements the array must contain (inclusive) */
     maxSize?: number;
 }
-/**
- * Alias for {@link IAssertArrayArgs}. Kept for backwards compatibility.
- */
-export type TSizeConstraint = IAssertArrayArgs;
 /**
  * Type alias for 2D dimension constraint properties.
  * Represents constraints that can be applied to matrix dimensions.
@@ -63,45 +59,53 @@ export interface IAssertArray2DArgs {
 }
 /**
  * Asserts that a value is an array, optionally validating its size.
- * @template T The type of array elements.
- * @param value The value to validate.
- * @param args Optional size constraints.
- * @param exception Optional custom exception to throw.
+ * @template T - The type of array elements.
+ * @param value - The value to validate.
+ * @param args - Optional size constraints.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If the value is not an array or fails size validation.
  */
 export declare function AssertArray<T = unknown>(value: unknown, args?: IAssertArrayArgs, exception?: IAssertException): asserts value is T[];
 /**
  * Asserts that a value is a 2D array, optionally validating its dimensions.
- * @template T The type of array elements.
- * @param value The value to validate.
- * @param args Optional dimension constraints.
- * @param exception Optional custom exception to throw.
+ * @template T - The type of array elements.
+ * @param value - The value to validate.
+ * @param args - Optional dimension constraints.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If the value is not a 2D array or fails dimension validation.
  */
 export declare function AssertArray2D<T = unknown>(value: unknown, args?: IAssertArray2DArgs, exception?: IAssertException): asserts value is T[][];
 /**
  * Asserts that an array is not empty.
- * @template T The type of array elements.
- * @param value The array to validate.
- * @param exception Optional custom exception to throw.
+ * @template T - The type of array elements.
+ * @param value - The array to validate.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If the array is empty.
  */
 export declare function AssertArrayNotEmpty<T>(value: T[] | unknown, exception?: IAssertException): asserts value is T[];
 /**
  * Asserts that all elements in an array satisfy a predicate.
- * @template T The type of array elements.
- * @param array The array to validate.
- * @param predicate A function to test each element.
- * @param exception Optional custom exception to throw.
+ *
+ * Uses `array.every()` to check if all elements satisfy the predicate condition.
+ * Throws an error if any element fails the test.
+ *
+ * @template T - The type of array elements.
+ * @param array - The array to validate.
+ * @param predicate - A function to test each element.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If any element fails the predicate test.
  */
 export declare function AssertArrayAll<T>(array: T[], predicate: (el: T, idx: number, arr: T[]) => boolean, exception?: IAssertException): void;
 /**
  * Asserts that at least one element in an array satisfies a predicate.
- * @template T The type of array elements.
- * @param array The array to validate.
- * @param predicate A function to test each element.
- * @param exception Optional custom exception to throw.
+ *
+ * Uses `array.some()` to check if any element satisfies the predicate condition.
+ * Throws an error if no elements pass the test.
+ *
+ * @template T - The type of array elements.
+ * @param array - The array to validate.
+ * @param predicate - A function to test each element.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If no elements pass the predicate test.
  */
 export declare function AssertArrayAny<T>(array: T[], predicate: (el: T, idx: number, arr: T[]) => boolean, exception?: IAssertException): void;

package/dist/array/assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/array/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,WAAW;gBAC9B,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,gBAAgB,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CA2BxI;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,kBAAuB,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,EAAE,CAqElJ;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,EAAE,CAYnH;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,IAAI,CAO1I;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,IAAI,CAO1I"}

package/{build → dist}/array/assert.js

@@ -1,4 +1,4 @@
-import { SetExceptionClass, SetExceptionMessage, ThrowException } from '../asserts/utils.js';
+import { SetExceptionClass, SetExceptionMessage, ThrowException, AssertValueType } from '../asserts/utils.js';
 import { SimpleError } from '../asserts/errors.js';
 /**
  * Error thrown when a value is not a valid array or fails an array assertion.
@@ -13,20 +13,17 @@ export class ArrayError extends SimpleError {
 }
 /**
  * Asserts that a value is an array, optionally validating its size.
- * @template T The type of array elements.
- * @param value The value to validate.
- * @param args Optional size constraints.
- * @param exception Optional custom exception to throw.
+ * @template T - The type of array elements.
+ * @param value - The value to validate.
+ * @param args - Optional size constraints.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If the value is not an array or fails size validation.
  */
 export function AssertArray(value, args, exception = {}) {
     // Initialize exception configuration with defaults
     SetExceptionClass(exception, ArrayError);
     // Validate that the value is an array
-    if (!Array.isArray(value)) {
-        SetExceptionMessage(exception, `Expected array but received ${typeof value}: ${String(value)}`);
-        ThrowException(exception);
-    }
+    AssertValueType(value, 'array', exception);
     // Type cast is safe after array validation
     const array = value;
     // Validate exact size constraint if specified
@@ -47,30 +44,27 @@ export function AssertArray(value, args, exception = {}) {
 }
 /**
  * Asserts that a value is a 2D array, optionally validating its dimensions.
- * @template T The type of array elements.
- * @param value The value to validate.
- * @param args Optional dimension constraints.
- * @param exception Optional custom exception to throw.
+ * @template T - The type of array elements.
+ * @param value - The value to validate.
+ * @param args - Optional dimension constraints.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If the value is not a 2D array or fails dimension validation.
  */
 export function AssertArray2D(value, args = {}, exception = {}) {
     // Initialize exception configuration with defaults
     SetExceptionClass(exception, ArrayError);
     // Validate that the value is an array
-    if (!Array.isArray(value)) {
-        SetExceptionMessage(exception, `Expected array but received ${typeof value}: ${String(value)}`);
-        ThrowException(exception);
-    }
+    AssertValueType(value, 'array', exception);
     // Type cast is safe after array validation
     const array = value;
-    // Validate that all elements are arrays (making it 2D)
-    if (!array.every((row) => Array.isArray(row))) {
-        let invalidPositions = array.map((row, idx) => {
-            if (!Array.isArray(row))
-                return idx;
-            return null;
-        });
-        invalidPositions = invalidPositions.filter((idx) => idx !== null);
+    // Validate that all elements are arrays (making it 2D) with single-pass collection of invalid positions
+    const invalidPositions = [];
+    for (let i = 0; i < array.length; i++) {
+        if (!Array.isArray(array[i])) {
+            invalidPositions.push(i);
+        }
+    }
+    if (invalidPositions.length > 0) {
         SetExceptionMessage(exception, `Expected 2D array but found non-array elements at positions: ${invalidPositions.join(', ')}`);
         ThrowException(exception);
     }
@@ -117,9 +111,9 @@ export function AssertArray2D(value, args = {}, exception = {}) {
 }
 /**
  * Asserts that an array is not empty.
- * @template T The type of array elements.
- * @param value The array to validate.
- * @param exception Optional custom exception to throw.
+ * @template T - The type of array elements.
+ * @param value - The array to validate.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If the array is empty.
  */
 export function AssertArrayNotEmpty(value, exception = {}) {
@@ -143,13 +137,18 @@ function assertIsArray(array, exception) {
 }
 /**
  * Asserts that all elements in an array satisfy a predicate.
- * @template T The type of array elements.
- * @param array The array to validate.
- * @param predicate A function to test each element.
- * @param exception Optional custom exception to throw.
+ *
+ * Uses `array.every()` to check if all elements satisfy the predicate condition.
+ * Throws an error if any element fails the test.
+ *
+ * @template T - The type of array elements.
+ * @param array - The array to validate.
+ * @param predicate - A function to test each element.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If any element fails the predicate test.
  */
 export function AssertArrayAll(array, predicate, exception = {}) {
+    // Predicate functions use array.some() / array.every() for consistency
     assertIsArray(array, exception);
     if (!array.every(predicate)) {
         SetExceptionMessage(exception, 'Not all elements satisfy the predicate condition');
@@ -158,17 +157,21 @@ export function AssertArrayAll(array, predicate, exception = {}) {
 }
 /**
  * Asserts that at least one element in an array satisfies a predicate.
- * @template T The type of array elements.
- * @param array The array to validate.
- * @param predicate A function to test each element.
- * @param exception Optional custom exception to throw.
+ *
+ * Uses `array.some()` to check if any element satisfies the predicate condition.
+ * Throws an error if no elements pass the test.
+ *
+ * @template T - The type of array elements.
+ * @param array - The array to validate.
+ * @param predicate - A function to test each element.
+ * @param exception - Optional custom exception to throw.
  * @throws {ArrayError} If no elements pass the predicate test.
  */
 export function AssertArrayAny(array, predicate, exception = {}) {
+    // Predicate functions use array.some() / array.every() for consistency
     assertIsArray(array, exception);
     if (!array.some(predicate)) {
         SetExceptionMessage(exception, 'No elements satisfy the predicate condition');
         ThrowException(exception);
     }
 }
-//# sourceMappingURL=assert.js.map

package/{build → dist}/array/index.js

@@ -23,4 +23,3 @@ export * from './array-sort-by.js';
 export * from './array-count-by.js';
 export * from './array-sample.js';
 export * from './assert.js';
-//# sourceMappingURL=index.js.map

package/{build → dist}/array/types.d.ts

@@ -29,4 +29,33 @@ export type TComparator<T> = (a: T, b: T) => number;
  * @returns true if values are equal, false otherwise
  */
 export type TEqualityComparator<T> = (a: T, b: T) => boolean;
+/**
+ * Options for comparing array elements.
+ * Supports both custom comparator functions and deep equality checking.
+ *
+ * @template T - The type of array elements
+ */
+/**
+ * Comparison options for array operations.
+ *
+ * Provides a discriminated union where callers must choose exactly one strategy:
+ * - `comparator`: Custom equality function for specialized comparison logic
+ * - `useDeepEqual`: Deep structural equality checking
+ * - `keyFn`: Function to extract a primitive key for O(n+m) Set-based lookup
+ *
+ * Mutually exclusive at compile time via `never` literals.
+ */
+export type TArrayComparisonOptions<T> = {
+    comparator: TEqualityComparator<T>;
+    useDeepEqual?: never;
+    keyFn?: never;
+} | {
+    useDeepEqual: true;
+    comparator?: never;
+    keyFn?: never;
+} | {
+    keyFn: (item: T) => unknown;
+    comparator?: never;
+    useDeepEqual?: never;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/array/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/array/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CAAC,MAAM,EAAE,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;AAE7D;;;;;GAKG;AACH;;;;;;;;;GASG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAClC;IAAE,UAAU,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAAC,YAAY,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAC3E;IAAE,YAAY,EAAE,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GACzD;IAAE,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,YAAY,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC"}

package/dist/array/types.js

@@ -0,0 +1 @@
+export {};

package/{build → dist}/array/unique.d.ts

@@ -1,9 +1,11 @@
 /**
  * Returns a new array with duplicate values removed.
  *
+ * Returns empty array if input is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @param array - The input array
- * @returns A new array containing only unique values (preserves first occurrence order)
+ * @returns A new array containing only unique values (preserves first occurrence order). Returns `[]` if `array` is `null`, `undefined`, or empty.
  *
  * @remarks Uses reference equality for objects. Two distinct objects with
  * identical property values are **not** considered equal and will both be kept.

package/{build → dist}/array/unique.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unique.d.ts","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAMlD"}
+{"version":3,"file":"unique.d.ts","sourceRoot":"","sources":["../../src/array/unique.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAOlD"}

package/{build → dist}/array/unique.js

@@ -1,9 +1,11 @@
 /**
  * Returns a new array with duplicate values removed.
  *
+ * Returns empty array if input is null, undefined, or empty.
+ *
  * @template T - The type of array elements
  * @param array - The input array
- * @returns A new array containing only unique values (preserves first occurrence order)
+ * @returns A new array containing only unique values (preserves first occurrence order). Returns `[]` if `array` is `null`, `undefined`, or empty.
  *
  * @remarks Uses reference equality for objects. Two distinct objects with
  * identical property values are **not** considered equal and will both be kept.
@@ -15,9 +17,9 @@
  * ```
  */
 export function Unique(array) {
-    if (array === null || array === undefined) {
+    // Consistent null-check: early return for null/undefined/empty arrays
+    if (!array || array.length === 0) {
         return [];
     }
     return [...new Set(array)];
 }
-//# sourceMappingURL=unique.js.map

package/dist/asserts/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/asserts/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAY,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAM3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,SAAgB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAE7D;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAkB5E;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC7C;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D;AAED;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC5C;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;IAClD;;;;OAIG;gBACS,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGnF;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;IAC/C;;;OAGG;gBACS,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGhE;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC3C;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG3D;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;IACjD;;;OAGG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9D"}

package/{build → dist}/asserts/errors.js

@@ -55,9 +55,12 @@ export class BaseError extends Error {
         this.name = this.constructor.name;
         this.Code = code;
         this.Context = context;
-        if (typeof Error.captureStackTrace === 'function') {
-            Error.captureStackTrace(this, this.constructor);
+        /* eslint-disable @typescript-eslint/no-explicit-any */
+        const ErrorWithCapture = Error;
+        if (typeof ErrorWithCapture.captureStackTrace === 'function') {
+            ErrorWithCapture.captureStackTrace(this, this.constructor);
         }
+        /* eslint-enable @typescript-eslint/no-explicit-any */
     }
 }
 /**
@@ -173,4 +176,3 @@ export class BufferOverflowError extends BaseError {
         super(`Buffer overflow: maximum size ${maxSize} exceeded`, 'BUFFER_OVERFLOW', context);
     }
 }
-//# sourceMappingURL=errors.js.map

package/{build → dist}/asserts/generic.d.ts

@@ -1,10 +1,39 @@
 import type { IAssertException, TGuard, TValidationPredicate } from './types.js';
 import { SimpleError } from './errors.js';
+/**
+ * Serializes a value to a human-readable string, safe for any value type.
+ *
+ * Prevents sensitive data exposure in error messages by:
+ * - Masking object contents (shows type name only, not property values)
+ * - Truncating long strings with a clear indication
+ * - Handling non-serializable values gracefully
+ *
+ * @param value - The value to serialize for display
+ * @param maxLength - Maximum characters to display for primitives (default: 50, capped at 10,000)
+ * @returns A safe string representation (at most maxLength chars plus "[truncated]" suffix)
+ *
+ * @example
+ * safeDisplay({ apiKey: 'secret123', username: 'john' }); // '[Object]'
+ * safeDisplay('x'.repeat(100)); // 'xxx....[truncated]'
+ * safeDisplay(circularRef); // '[non-serializable]'
+ *
+ * @internal Used internally by assertion functions to safely display values in error messages
+ */
+export declare function safeDisplay(value: unknown, maxLength?: number): string;
+/**
+ * Gets the display type of a value including null and undefined.
+ * Used for error messages in null/undefined assertions and type checking.
+ *
+ * @param value - The value to get the type of
+ * @returns A string representation of the value's type ('null', 'undefined', 'array', 'object', or typeof)
+ * @internal Used internally by assertion functions for consistent type messages
+ */
+export declare function GetValueType(value: unknown): string;
 /**
  * Type alias for constructor functions.
  * Represents any class constructor that can be instantiated.
  */
-export type TConstructorFunction<T = any> = new (...args: any[]) => T;
+export type TConstructorFunction<T = unknown> = new (...args: any[]) => T;
 /**
  * Error thrown when a nullish assertion fails — the value is not null or undefined
  * but was expected to be. Used by {@link AssertNull} when the provided value is a
@@ -394,7 +423,7 @@ export declare function AssertInstanceOf<T>(value: unknown, constructor: TConstr
  * AssertFunction(123); // ✗ Throws FunctionError
  * AssertFunction(null); // ✗ Throws FunctionError
  */
-export declare function AssertFunction(value: unknown, exception?: IAssertException): asserts value is (...args: any[]) => any;
+export declare function AssertFunction(value: unknown, exception?: IAssertException): asserts value is (...args: unknown[]) => unknown;
 /**
  * Asserts that a value is a symbol.
  *
@@ -431,5 +460,5 @@ export declare function AssertSymbol(value: unknown, exception?: IAssertExceptio
  * AssertExtends(Derived, Base); // ✓ Valid
  * AssertExtends(Base, Derived); // ✗ Throws ExtendsError
  */
-export declare function AssertExtends(derived: abstract new (...args: any[]) => any, base: abstract new (...args: any[]) => any, exception?: IAssertException): void;
+export declare function AssertExtends(derived: abstract new (...args: any[]) => unknown, base: abstract new (...args: any[]) => unknown, exception?: IAssertException): void;
 //# sourceMappingURL=generic.d.ts.map

package/dist/asserts/generic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic.d.ts","sourceRoot":"","sources":["../../src/asserts/generic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjF,OAAO,EAAkB,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,SAAK,GAAG,MAAM,CAiBlE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOnD;AAED;;;GAGG;AAEH,MAAM,MAAM,oBAAoB,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAE1E;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,WAAW;gBAC7B,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;;GAOG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAChC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,WAAW;gBAClC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,WAAW;gBAClC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBACnC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,WAAW;gBACjC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,WAAW;gBAC/B,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAChC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,IAAI,CAM7F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,IAAI,CAMhG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,SAAS,CAAC,CAOjH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC,CAAC,CAAC,CAO5G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,IAAI,CAMvH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAO1H;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAU9I;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAOjI;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAOtG;AAED;;;;;;;;;;;;;;;;;GAiBG;AAEH,wBAAgB,aAAa,CAAC,OAAO,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,IAAI,EAAE,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,IAAI,CAqBvK"}