@pawells/typescript-common 1.4.1 → 2.1.5

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

@@ -1,17 +1,61 @@
 import { ObjectEquals } from './internal-utils.js';
 import { SetExceptionClass, SetExceptionMessage, ThrowException } from './utils.js';
 import { AssertionError, SimpleError } from './errors.js';
-/** Maximum number of characters to include from a value in an error message. */
-const MAX_VALUE_DISPLAY_LENGTH = 100;
-/** Serialises a value to a human-readable string, safe for any value type. */
-function safeDisplay(value) {
+/**
+ * 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 function safeDisplay(value, maxLength = 50) {
+    // Cap maxLength to prevent memory exhaustion from extremely large values
+    const effectiveMaxLength = Math.min(maxLength, 10_000);
+    // For objects, use type name instead of full serialization to avoid leaking structure
+    if (typeof value === 'object' && value !== null) {
+        return `[${Object.getPrototypeOf(value)?.constructor?.name ?? 'Object'}]`;
+    }
+    // For primitives, truncate with clear indication
     try {
-        return (JSON.stringify(value) ?? String(value)).slice(0, MAX_VALUE_DISPLAY_LENGTH);
+        const serialized = JSON.stringify(value) ?? String(value);
+        return serialized.length > effectiveMaxLength
+            ? serialized.slice(0, effectiveMaxLength) + '...[truncated]'
+            : serialized;
     }
     catch {
-        return String(value).slice(0, MAX_VALUE_DISPLAY_LENGTH);
+        return '[non-serializable]';
     }
 }
+/**
+ * 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 function GetValueType(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'object') {
+        return Array.isArray(value) ? 'array' : 'object';
+    }
+    return typeof value;
+}
 /**
  * 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
@@ -270,7 +314,8 @@ export function AssertNotEquals(value, expected, exception = {}) {
 export function AssertNull(value, exception = {}) {
     SetExceptionClass(exception, NullError);
     if (value !== null && value !== undefined) {
-        SetExceptionMessage(exception, `Expected null or undefined but received ${typeof value}: ${JSON.stringify(value)}`);
+        const actualType = GetValueType(value);
+        SetExceptionMessage(exception, `Expected null or undefined but received ${actualType}: ${safeDisplay(value)}`);
         ThrowException(exception);
     }
 }
@@ -309,8 +354,8 @@ export function AssertNull(value, exception = {}) {
 export function AssertNotNull(value, exception = {}) {
     SetExceptionClass(exception, NotNullError);
     if (value === null || value === undefined) {
-        const actualValue = value === null ? 'null' : 'undefined';
-        SetExceptionMessage(exception, `Expected non-null/non-undefined value but received ${actualValue}`);
+        const actualType = GetValueType(value);
+        SetExceptionMessage(exception, `Expected non-null/non-undefined value but received ${actualType}`);
         ThrowException(exception);
     }
 }
@@ -398,8 +443,8 @@ export function AssertPredicate(value, predicate, exception = {}) {
 export function AssertIsType(value, typeGuard, exception = {}) {
     SetExceptionClass(exception, TypeGuardError);
     if (!typeGuard(value)) {
-        const actualType = value === null ? 'null' : value === undefined ? 'undefined' : typeof value;
-        SetExceptionMessage(exception, `Expected value to conform to required type but received ${actualType}: ${JSON.stringify(value).slice(0, MAX_VALUE_DISPLAY_LENGTH)}`);
+        const actualType = GetValueType(value);
+        SetExceptionMessage(exception, `Expected value to conform to required type but received ${actualType}: ${safeDisplay(value)}`);
         ThrowException(exception);
     }
 }
@@ -440,7 +485,10 @@ export function AssertIsType(value, typeGuard, exception = {}) {
 export function AssertInstanceOf(value, constructor, exception = {}) {
     SetExceptionClass(exception, InstanceOfError);
     if (!(value instanceof constructor)) {
-        const actualType = value === null ? 'null' : value === undefined ? 'undefined' : value.constructor?.name || typeof value;
+        let actualType = GetValueType(value);
+        if (actualType === 'object' && value !== null && typeof value === 'object') {
+            actualType = value.constructor?.name ?? 'object';
+        }
         SetExceptionMessage(exception, `Expected instance of ${constructor.name} but received ${actualType}`);
         ThrowException(exception);
     }
@@ -465,7 +513,7 @@ export function AssertInstanceOf(value, constructor, exception = {}) {
 export function AssertFunction(value, exception = {}) {
     SetExceptionClass(exception, FunctionError);
     if (typeof value !== 'function') {
-        const actualType = value === null ? 'null' : value === undefined ? 'undefined' : typeof value;
+        const actualType = GetValueType(value);
         SetExceptionMessage(exception, `Expected function but received ${actualType}`);
         ThrowException(exception);
     }
@@ -490,7 +538,7 @@ export function AssertFunction(value, exception = {}) {
 export function AssertSymbol(value, exception = {}) {
     SetExceptionClass(exception, SymbolError);
     if (typeof value !== 'symbol') {
-        const actualType = value === null ? 'null' : value === undefined ? 'undefined' : typeof value;
+        const actualType = GetValueType(value);
         SetExceptionMessage(exception, `Expected symbol but received ${actualType}`);
         ThrowException(exception);
     }
@@ -513,6 +561,7 @@ export function AssertSymbol(value, exception = {}) {
  * AssertExtends(Derived, Base); // ✓ Valid
  * AssertExtends(Base, Derived); // ✗ Throws ExtendsError
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function AssertExtends(derived, base, exception = {}) {
     SetExceptionClass(exception, ExtendsError);
     if (typeof derived !== 'function' || typeof base !== 'function') {
@@ -534,4 +583,3 @@ export function AssertExtends(derived, base, exception = {}) {
         ThrowException(exception);
     }
 }
-//# sourceMappingURL=generic.js.map

package/dist/asserts/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module asserts
+ * @description Aggregation barrel for all assertion functions.
+ * Exports both generic assertion primitives (like AssertNull, AssertNotNull, AssertEquals, etc.)
+ * and domain-specific validators (AssertArray, AssertBoolean, AssertNumber, AssertObject, AssertString).
+ *
+ * Domain-specific assertions are re-exported here as a convenience so callers can import
+ * all assertion functions from a single entry point. They originate from their respective
+ * domain modules (array/, boolean/, number/, object/, string/).
+ *
+ * Note: Internal utility functions (SetExceptionClass, SetExceptionMessage, ThrowException,
+ * AssertValueType, safeDisplay, GetValueType) are NOT exported from this barrel as they are
+ * part of the internal assertion implementation contract and should not be relied upon by external code.
+ */
+/**
+ * Export all array assertion functions and types
+ */
+export * from '../array/assert.js';
+/**
+ * Export all boolean assertion functions and types
+ */
+export * from '../boolean/assert.js';
+/**
+ * Export generic assertion functions (but not internal utilities)
+ */
+export { AssertEquals, AssertNotEquals, AssertNull, AssertNotNull, AssertPredicate, AssertIsType, AssertInstanceOf, AssertFunction, AssertSymbol, AssertExtends, NullError, NotNullError, PredicateError, TypeGuardError, InstanceOfError, FunctionError, SymbolError, ExtendsError, type TConstructorFunction, } from './generic.js';
+/**
+ * Export all number assertion functions and types
+ */
+export * from '../number/assert.js';
+/**
+ * Export all object assertion functions and types
+ */
+export * from '../object/assert.js';
+/**
+ * Export all string assertion functions and types
+ */
+export * from '../string/assert.js';
+/**
+ * Export type definitions and interfaces
+ */
+export * from './types.js';
+/**
+ * Export error classes for standardized error handling
+ */
+export * from './errors.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/asserts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,cAAc,oBAAoB,CAAC;AAEnC;;GAEG;AACH,cAAc,sBAAsB,CAAC;AAErC;;GAEG;AACH,OAAO,EACN,YAAY,EACZ,eAAe,EACf,UAAU,EACV,aAAa,EACb,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,SAAS,EACT,YAAY,EACZ,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,EACb,WAAW,EACX,YAAY,EACZ,KAAK,oBAAoB,GACzB,MAAM,cAAc,CAAC;AAEtB;;GAEG;AACH,cAAc,qBAAqB,CAAC;AAEpC;;GAEG;AACH,cAAc,qBAAqB,CAAC;AAEpC;;GAEG;AACH,cAAc,qBAAqB,CAAC;AAEpC;;GAEG;AACH,cAAc,YAAY,CAAC;AAE3B;;GAEG;AACH,cAAc,aAAa,CAAC"}

package/dist/asserts/index.js

@@ -0,0 +1,46 @@
+/**
+ * @module asserts
+ * @description Aggregation barrel for all assertion functions.
+ * Exports both generic assertion primitives (like AssertNull, AssertNotNull, AssertEquals, etc.)
+ * and domain-specific validators (AssertArray, AssertBoolean, AssertNumber, AssertObject, AssertString).
+ *
+ * Domain-specific assertions are re-exported here as a convenience so callers can import
+ * all assertion functions from a single entry point. They originate from their respective
+ * domain modules (array/, boolean/, number/, object/, string/).
+ *
+ * Note: Internal utility functions (SetExceptionClass, SetExceptionMessage, ThrowException,
+ * AssertValueType, safeDisplay, GetValueType) are NOT exported from this barrel as they are
+ * part of the internal assertion implementation contract and should not be relied upon by external code.
+ */
+/**
+ * Export all array assertion functions and types
+ */
+export * from '../array/assert.js';
+/**
+ * Export all boolean assertion functions and types
+ */
+export * from '../boolean/assert.js';
+/**
+ * Export generic assertion functions (but not internal utilities)
+ */
+export { AssertEquals, AssertNotEquals, AssertNull, AssertNotNull, AssertPredicate, AssertIsType, AssertInstanceOf, AssertFunction, AssertSymbol, AssertExtends, NullError, NotNullError, PredicateError, TypeGuardError, InstanceOfError, FunctionError, SymbolError, ExtendsError, } from './generic.js';
+/**
+ * Export all number assertion functions and types
+ */
+export * from '../number/assert.js';
+/**
+ * Export all object assertion functions and types
+ */
+export * from '../object/assert.js';
+/**
+ * Export all string assertion functions and types
+ */
+export * from '../string/assert.js';
+/**
+ * Export type definitions and interfaces
+ */
+export * from './types.js';
+/**
+ * Export error classes for standardized error handling
+ */
+export * from './errors.js';

package/{build → dist}/asserts/internal-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal-utils.d.ts","sourceRoot":"","sources":["../../src/asserts/internal-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAGxF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"internal-utils.d.ts","sourceRoot":"","sources":["../../src/asserts/internal-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AAEH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAGxF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/{build → dist}/asserts/internal-utils.js

@@ -3,4 +3,3 @@
  */
 // Single source of truth — the canonical implementation lives in the object module.
 export { ObjectEquals } from '../object/equals.js';
-//# sourceMappingURL=internal-utils.js.map

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

@@ -1,19 +1,4 @@
-import { TConstructableObject } from './internal-utils.js';
-/**
- * Type alias for constraint union patterns.
- * Represents common constraint combinations used across assertion modules.
- */
-export type TConstraintValue = string | number | boolean | null | undefined;
-/**
- * Type alias for comparison operators.
- * Represents the various comparison operations available in constraint validation.
- */
-export type TComparisonOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
-/**
- * Type alias for validation result patterns.
- * Represents the union of possible validation outcomes.
- */
-export type TValidationResult = true | Error;
+import type { TConstructableObject } from './internal-utils.js';
 /**
  * Configuration interface for assertion exception handling.
  *
@@ -27,7 +12,6 @@ export type TValidationResult = true | Error;
  * defaults for unconfigured options.
  *
  * @interface IAssertException
- * @since 1.0.0
  *
  * @example
  * Basic usage with custom messages:
@@ -139,6 +123,14 @@ export interface IAssertException {
  * @template T - The type being guarded
  * @param value - The value to check
  * @returns true if value is of type T, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isString: TGuard<string> = (value): value is string => typeof value === 'string';
+ * if (isString(input)) {
+ *   // input is now typed as string
+ * }
+ * ```
  */
 export type TGuard<T> = (value: unknown) => value is T;
 /**
@@ -146,6 +138,14 @@ export type TGuard<T> = (value: unknown) => value is T;
  * @template T - The type of value being validated
  * @param value - The value to validate
  * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isPositive: TValidationPredicate<number> = (value) => value > 0;
+ * if (isPositive(count)) {
+ *   // count is valid
+ * }
+ * ```
  */
 export type TValidationPredicate<T = unknown> = (value: T) => boolean;
 /**
@@ -153,6 +153,15 @@ export type TValidationPredicate<T = unknown> = (value: T) => boolean;
  * @template T - The element type
  * @param value - The value to check
  * @returns true if value is an array of type T[], false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isStringArray: TArrayTypeGuard<string> = (value): value is string[] =>
+ *   Array.isArray(value) && value.every(item => typeof item === 'string');
+ * if (isStringArray(items)) {
+ *   // items is now typed as string[]
+ * }
+ * ```
  */
 export type TArrayTypeGuard<T> = (value: unknown) => value is T[];
 /**
@@ -160,6 +169,16 @@ export type TArrayTypeGuard<T> = (value: unknown) => value is T[];
  * @template T - The object type
  * @param value - The value to check
  * @returns true if value is of object type T, false otherwise
+ *
+ * @example
+ * ```typescript
+ * interface User { id: number; name: string; }
+ * const isUser: TObjectTypeGuard<User> = (value): value is User =>
+ *   typeof value === 'object' && value !== null && 'id' in value && 'name' in value;
+ * if (isUser(data)) {
+ *   // data is now typed as User
+ * }
+ * ```
  */
 export type TObjectTypeGuard<T extends object> = (value: unknown) => value is T;
 /**
@@ -167,6 +186,15 @@ export type TObjectTypeGuard<T extends object> = (value: unknown) => value is T;
  * @template T - The non-null type
  * @param value - The value to check
  * @returns true if value is not null or undefined, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const isDefined: TNonNullableGuard<string> = (value): value is string =>
+ *   value !== null && value !== undefined;
+ * if (isDefined(maybeString)) {
+ *   // maybeString is now typed as string
+ * }
+ * ```
  */
 export type TNonNullableGuard<T> = (value: T | null | undefined) => value is T;
 /**
@@ -175,6 +203,17 @@ export type TNonNullableGuard<T> = (value: T | null | undefined) => value is T;
  * @param value - The value to assert
  * @param message - Optional error message
  * @throws IAssertException if assertion fails
+ *
+ * @example
+ * ```typescript
+ * const AssertNumber: TAssertFunction<number> = (value, message) => {
+ *   if (typeof value !== 'number') {
+ *     throw new Error(message || 'Expected a number');
+ *   }
+ * };
+ * AssertNumber(input);
+ * // input is now typed as number
+ * ```
  */
 export type TAssertFunction<T = unknown> = (value: unknown, message?: string) => asserts value is T;
 //# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/asserts/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,EAAE,CAAC;AAElE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;AAEhF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,KAAK,KAAK,IAAI,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC"}

package/dist/asserts/types.js

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

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

@@ -1,5 +1,5 @@
-import { TConstructableObject } from './internal-utils.js';
-import { IAssertException } from './types.js';
+import type { TConstructableObject } from './internal-utils.js';
+import type { IAssertException } from './types.js';
 /**
  * Throws an exception using the configured error class and message.
  *
@@ -10,6 +10,7 @@ import { IAssertException } from './types.js';
  *
  * @param exception - Exception configuration containing error class and/or message
  * @throws {Error} The configured error class with the specified message, or generic Error if no class specified
+ * @internal
  *
  * @example
  * ```typescript
@@ -40,6 +41,7 @@ export declare function ThrowException(exception: IAssertException): void;
  * @param exception - Exception configuration object to modify
  * @param errorClass - The error class constructor to set as default
  * @param force - Whether to override existing error class configuration (default: false)
+ * @internal
  *
  * @example
  * ```typescript
@@ -70,6 +72,7 @@ export declare function SetExceptionClass(exception: IAssertException, errorClas
  * @param exception - Exception configuration object to modify
  * @param message - The error message to set as default
  * @param force - Whether to override existing error message configuration (default: false)
+ * @internal
  *
  * @example
  * ```typescript
@@ -89,4 +92,17 @@ export declare function SetExceptionClass(exception: IAssertException, errorClas
  * ```
  */
 export declare function SetExceptionMessage(exception: IAssertException, message: string, force?: boolean): void;
+/**
+ * Assert that a value matches an expected type, throwing if it doesn't.
+ * Handles primitives (string, number, boolean), arrays, and objects.
+ * Delegates type checking logic to a single source of truth for consistent
+ * error messages and behavior across all type assertion functions.
+ *
+ * @param value - The value to check
+ * @param expectedType - Expected type string ('string', 'number', 'boolean', 'array', 'object')
+ * @param exception - Exception object to populate on failure
+ * @throws Throws the exception if type check fails
+ * @internal Used internally by type-specific assertion functions
+ */
+export declare function AssertValueType(value: unknown, expectedType: 'string' | 'number' | 'boolean' | 'array' | 'object', exception: IAssertException): asserts value;
 //# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/asserts/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAKhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,oBAAoB,EAAE,KAAK,UAAQ,GAAG,IAAI,CAGpH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,UAAQ,GAAG,IAAI,CAGrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC9B,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,EAClE,SAAS,EAAE,gBAAgB,GACzB,OAAO,CAAC,KAAK,CAuCf"}

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

@@ -1,3 +1,4 @@
+import { safeDisplay, GetValueType } from './generic.js';
 /**
  * Throws an exception using the configured error class and message.
  *
@@ -8,6 +9,7 @@
  *
  * @param exception - Exception configuration containing error class and/or message
  * @throws {Error} The configured error class with the specified message, or generic Error if no class specified
+ * @internal
  *
  * @example
  * ```typescript
@@ -43,6 +45,7 @@ export function ThrowException(exception) {
  * @param exception - Exception configuration object to modify
  * @param errorClass - The error class constructor to set as default
  * @param force - Whether to override existing error class configuration (default: false)
+ * @internal
  *
  * @example
  * ```typescript
@@ -77,6 +80,7 @@ export function SetExceptionClass(exception, errorClass, force = false) {
  * @param exception - Exception configuration object to modify
  * @param message - The error message to set as default
  * @param force - Whether to override existing error message configuration (default: false)
+ * @internal
  *
  * @example
  * ```typescript
@@ -100,4 +104,55 @@ export function SetExceptionMessage(exception, message, force = false) {
         return;
     exception.message = message;
 }
-//# sourceMappingURL=utils.js.map
+/**
+ * Assert that a value matches an expected type, throwing if it doesn't.
+ * Handles primitives (string, number, boolean), arrays, and objects.
+ * Delegates type checking logic to a single source of truth for consistent
+ * error messages and behavior across all type assertion functions.
+ *
+ * @param value - The value to check
+ * @param expectedType - Expected type string ('string', 'number', 'boolean', 'array', 'object')
+ * @param exception - Exception object to populate on failure
+ * @throws Throws the exception if type check fails
+ * @internal Used internally by type-specific assertion functions
+ */
+export function AssertValueType(value, expectedType, exception) {
+    if (value === null) {
+        SetExceptionMessage(exception, `Expected ${expectedType} but received null`);
+        ThrowException(exception);
+    }
+    if (value === undefined) {
+        SetExceptionMessage(exception, `Expected ${expectedType} but received undefined`);
+        ThrowException(exception);
+    }
+    if (expectedType === 'array') {
+        if (!Array.isArray(value)) {
+            const actualType = GetValueType(value);
+            SetExceptionMessage(exception, `Expected array but received ${actualType}: ${safeDisplay(value)}`);
+            ThrowException(exception);
+        }
+        return;
+    }
+    if (expectedType === 'object') {
+        if (typeof value !== 'object') {
+            const actualType = GetValueType(value);
+            SetExceptionMessage(exception, `Expected object but received ${actualType}: ${safeDisplay(value)}`);
+            ThrowException(exception);
+        }
+        return;
+    }
+    if (expectedType === 'number') {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            const actualType = typeof value === 'number' ? 'NaN' : GetValueType(value);
+            SetExceptionMessage(exception, `Expected number but received ${actualType}: ${safeDisplay(value)}`);
+            ThrowException(exception);
+        }
+        return;
+    }
+    // For string and boolean
+    const actualType = GetValueType(value);
+    if (actualType !== expectedType) {
+        SetExceptionMessage(exception, `Expected ${expectedType} but received ${actualType}: ${safeDisplay(value)}`);
+        ThrowException(exception);
+    }
+}

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

@@ -24,8 +24,7 @@ export declare class BooleanError extends SimpleError {
  * @param value - The value to validate and assert as a boolean primitive
  * @param exception - Optional exception configuration for custom error handling.
  *                   Can include custom error message, error type, or other metadata.
- * @throws {Error} When value is not a boolean primitive. The specific error type
- *                 depends on the exception configuration provided.
+ * @throws {BooleanError} When value is not a boolean primitive
  *
  * @example
  * Basic usage with valid boolean values:

package/{build → dist}/boolean/assert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/boolean/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAChC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAMxG"}
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/boolean/assert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,WAAW;gBAChC,OAAO,CAAC,EAAE,MAAM;CAG5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,gBAAqB,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAGxG"}

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

@@ -1,4 +1,4 @@
-import { SetExceptionClass, SetExceptionMessage, ThrowException } from '../asserts/utils.js';
+import { SetExceptionClass, AssertValueType } from '../asserts/utils.js';
 import { SimpleError } from '../asserts/errors.js';
 /**
  * Error thrown when a value is not a valid boolean or fails a boolean assertion.
@@ -26,8 +26,7 @@ export class BooleanError extends SimpleError {
  * @param value - The value to validate and assert as a boolean primitive
  * @param exception - Optional exception configuration for custom error handling.
  *                   Can include custom error message, error type, or other metadata.
- * @throws {Error} When value is not a boolean primitive. The specific error type
- *                 depends on the exception configuration provided.
+ * @throws {BooleanError} When value is not a boolean primitive
  *
  * @example
  * Basic usage with valid boolean values:
@@ -67,9 +66,5 @@ export class BooleanError extends SimpleError {
  */
 export function AssertBoolean(value, exception = {}) {
     SetExceptionClass(exception, BooleanError);
-    if (typeof value !== 'boolean') {
-        SetExceptionMessage(exception, `Expected boolean but received ${typeof value}: ${String(value)}`);
-        ThrowException(exception);
-    }
+    AssertValueType(value, 'boolean', exception);
 }
-//# sourceMappingURL=assert.js.map

package/dist/boolean/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Boolean assertion functions and types.
+ *
+ * Provides assertion helpers for validating boolean values at runtime.
+ *
+ * Currently contains only assertion utilities. This module structure is designed
+ * to accommodate additional boolean utilities in the future (e.g., conversion,
+ * parsing functions).
+ *
+ * @module boolean
+ */
+export * from './assert.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/boolean/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/boolean/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,aAAa,CAAC"}

package/dist/boolean/index.js

@@ -0,0 +1,12 @@
+/**
+ * Boolean assertion functions and types.
+ *
+ * Provides assertion helpers for validating boolean values at runtime.
+ *
+ * Currently contains only assertion utilities. This module structure is designed
+ * to accommodate additional boolean utilities in the future (e.g., conversion,
+ * parsing functions).
+ *
+ * @module boolean
+ */
+export * from './assert.js';

package/{build → dist}/enum/enum-entries.d.ts

@@ -1,4 +1,4 @@
-import { TEnumType, TEnumValue } from './types.js';
+import type { TEnumType, TEnumValue } from './types.js';
 /**
  * Returns non-numeric key-value pairs from an enum.
  *

package/dist/enum/enum-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum-entries.d.ts","sourceRoot":"","sources":["../../src/enum/enum-entries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,CAIzF"}

package/{build → dist}/enum/enum-entries.js

@@ -16,4 +16,3 @@ export function EnumEntries(e) {
         return [];
     return Object.entries(e).filter(([key]) => Number.isNaN(Number(key)));
 }
-//# sourceMappingURL=enum-entries.js.map

package/{build → dist}/enum/enum-key-by-value.d.ts

@@ -1,4 +1,4 @@
-import { TEnumType, TEnumValue } from './types.js';
+import type { TEnumType, TEnumValue } from './types.js';
 /**
  * Gets the enum key for a given value.
  *

package/dist/enum/enum-key-by-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum-key-by-value.d.ts","sourceRoot":"","sources":["../../src/enum/enum-key-by-value.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAQ3G"}

package/{build → dist}/enum/enum-key-by-value.js

@@ -23,4 +23,3 @@ export function EnumKeyByValue(e, value) {
         return found[0];
     return undefined;
 }
-//# sourceMappingURL=enum-key-by-value.js.map

package/{build → dist}/enum/enum-keys.js

@@ -20,4 +20,3 @@ export function EnumKeys(obj) {
         return [];
     return Object.keys(obj).filter((k) => Number.isNaN(Number(k)));
 }
-//# sourceMappingURL=enum-keys.js.map

package/{build → dist}/enum/enum-safe-value.d.ts

@@ -1,4 +1,4 @@
-import { TEnumType, TEnumValue } from './types.js';
+import type { TEnumType, TEnumValue } from './types.js';
 /**
  * Gets an enum value safely, returning a fallback if the value is not a valid enum member.
  *

package/dist/enum/enum-safe-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enum-safe-value.d.ts","sourceRoot":"","sources":["../../src/enum/enum-safe-value.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,GAAG,UAAU,CAExH"}

package/{build → dist}/enum/enum-safe-value.js

@@ -18,4 +18,3 @@ import { ValidateEnumValue } from './validate-enum-value.js';
 export function EnumSafeValue(e, value, fallback) {
     return ValidateEnumValue(e, value) ? value : fallback;
 }
-//# sourceMappingURL=enum-safe-value.js.map