@pawells/typescript-common 1.0.1 → 1.1.1

package/build/asserts/internal-utils.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Internal utilities for the asserts package.
+ * These utilities are copied from @jtv/common to make @jtv/asserts standalone.
+ */
+/**
+ * A constructor function type for creating objects of type O.
+ * @template O The object type to construct.
+ */
+export type TConstructableObject<O extends object = object> = new (...args: any[]) => O;
+/**
+ * Performs a deep comparison between two values to determine if they are equivalent.
+ * Handles primitives, objects, arrays, dates, regular expressions, and special values like NaN.
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns True if the values are equivalent, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Primitive values
+ * ObjectEquals(42, 42); // true
+ * ObjectEquals('hello', 'hello'); // true
+ * ObjectEquals(true, false); // false
+ *
+ * // Objects
+ * ObjectEquals({ a: 1, b: 2 }, { a: 1, b: 2 }); // true
+ * ObjectEquals({ a: 1, b: 2 }, { a: 1, b: 3 }); // false
+ *
+ * // Nested objects
+ * const obj1 = { user: { name: 'John', age: 30 }, active: true };
+ * const obj2 = { user: { name: 'John', age: 30 }, active: true };
+ * ObjectEquals(obj1, obj2); // true
+ *
+ * // Arrays
+ * ObjectEquals([1, 2, 3], [1, 2, 3]); // true
+ * ObjectEquals([1, [2, 3]], [1, [2, 3]]); // true
+ *
+ * // Date objects
+ * const date1 = new Date('2023-01-01');
+ * const date2 = new Date('2023-01-01');
+ * ObjectEquals(date1, date2); // true
+ *
+ * // Regular expressions
+ * ObjectEquals(/abc/g, /abc/g); // true
+ * ObjectEquals(/abc/g, /abc/i); // false
+ *
+ * // Special cases
+ * ObjectEquals(NaN, NaN); // true (unlike === comparison)
+ * ObjectEquals(null, undefined); // false
+ * ```
+ */
+export declare function ObjectEquals(a: any, b: any): boolean;
+//# sourceMappingURL=internal-utils.d.ts.map

package/build/asserts/internal-utils.d.ts.map

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

package/build/asserts/internal-utils.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Internal utilities for the asserts package.
+ * These utilities are copied from @jtv/common to make @jtv/asserts standalone.
+ */
+/**
+ * Performs a deep comparison between two values to determine if they are equivalent.
+ * Handles primitives, objects, arrays, dates, regular expressions, and special values like NaN.
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns True if the values are equivalent, false otherwise
+ *
+ * @example
+ * ```typescript
+ * // Primitive values
+ * ObjectEquals(42, 42); // true
+ * ObjectEquals('hello', 'hello'); // true
+ * ObjectEquals(true, false); // false
+ *
+ * // Objects
+ * ObjectEquals({ a: 1, b: 2 }, { a: 1, b: 2 }); // true
+ * ObjectEquals({ a: 1, b: 2 }, { a: 1, b: 3 }); // false
+ *
+ * // Nested objects
+ * const obj1 = { user: { name: 'John', age: 30 }, active: true };
+ * const obj2 = { user: { name: 'John', age: 30 }, active: true };
+ * ObjectEquals(obj1, obj2); // true
+ *
+ * // Arrays
+ * ObjectEquals([1, 2, 3], [1, 2, 3]); // true
+ * ObjectEquals([1, [2, 3]], [1, [2, 3]]); // true
+ *
+ * // Date objects
+ * const date1 = new Date('2023-01-01');
+ * const date2 = new Date('2023-01-01');
+ * ObjectEquals(date1, date2); // true
+ *
+ * // Regular expressions
+ * ObjectEquals(/abc/g, /abc/g); // true
+ * ObjectEquals(/abc/g, /abc/i); // false
+ *
+ * // Special cases
+ * ObjectEquals(NaN, NaN); // true (unlike === comparison)
+ * ObjectEquals(null, undefined); // false
+ * ```
+ */
+export function ObjectEquals(a, b) {
+    // If the values are strictly equal, return true
+    if (a === b)
+        return true;
+    // Handle NaN special case - NaN should equal NaN for assertion purposes
+    if (typeof a === 'number' && typeof b === 'number' && isNaN(a) && isNaN(b)) {
+        return true;
+    }
+    // If either value is null, undefined, or not an object, they can't be equivalent
+    if (a === null || b === null || a === undefined || b === undefined)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object')
+        return false;
+    // Handle Date objects
+    if (a instanceof Date && b instanceof Date) {
+        return a.getTime() === b.getTime();
+    }
+    // Handle RegExp objects
+    if (a instanceof RegExp && b instanceof RegExp) {
+        return a.toString() === b.toString();
+    }
+    // Handle arrays
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        // Compare each element in the arrays
+        for (let i = 0; i < a.length; i++) {
+            if (!ObjectEquals(a[i], b[i]))
+                return false;
+        }
+        return true;
+    }
+    // If one is array and the other isn't, they're not equal
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    // Compare object properties
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    // Also compare symbol properties
+    const symbolsA = Object.getOwnPropertySymbols(a);
+    const symbolsB = Object.getOwnPropertySymbols(b);
+    if (symbolsA.length !== symbolsB.length)
+        return false;
+    for (const key of keysA) {
+        if (!Object.hasOwn(b, key))
+            return false;
+        if (!ObjectEquals(a[key], b[key]))
+            return false;
+    }
+    for (const symbol of symbolsA) {
+        if (!Object.getOwnPropertySymbols(b).includes(symbol))
+            return false;
+        if (!ObjectEquals(a[symbol], b[symbol]))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=internal-utils.js.map

package/build/asserts/internal-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-utils.js","sourceRoot":"","sources":["../../src/asserts/internal-utils.ts"],"names":[],"mappings":"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"}

package/build/asserts/types.d.ts

@@ -0,0 +1,180 @@
+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;
+/**
+ * Configuration interface for assertion exception handling.
+ *
+ * This interface allows comprehensive customization of error behavior when assertions fail.
+ * It provides flexibility to override both the error class and message used when throwing
+ * assertion failures, enabling consistent error handling patterns across different assertion
+ * types. This design supports both simple message overrides and complex error type hierarchies.
+ *
+ * The exception configuration follows an opt-in pattern where all properties are optional,
+ * allowing users to customize only the aspects they need while falling back to sensible
+ * defaults for unconfigured options.
+ *
+ * @interface IAssertException
+ * @since 1.0.0
+ *
+ * @example
+ * Basic usage with custom messages:
+ * ```typescript
+ * // Custom error class with custom message
+ * const config: IAssertException = {
+ *   class: ValidationError,
+ *   message: "Custom validation failed"
+ * };
+ *
+ * // Custom message only (uses default error class from assertion)
+ * const config2: IAssertException = {
+ *   message: "Value must be positive"
+ * };
+ *
+ * // Custom error class only (uses default message from assertion)
+ * const config3: IAssertException = {
+ *   class: TypeError
+ * };
+ * ```
+ *
+ * @example
+ * Advanced usage in assertion functions:
+ * ```typescript
+ * import { AssertString } from './string.js';
+ *
+ * // Using with built-in assertions
+ * try {
+ *   AssertString(123, {
+ *     class: TypeError,
+ *     message: "Username must be a string"
+ *   });
+ * } catch (error) {
+ *   console.log(error instanceof TypeError); // true
+ *   console.log(error.message); // "Username must be a string"
+ * }
+ *
+ * // Reusable error configurations
+ * const validationConfig: IAssertException = {
+ *   class: ValidationError,
+ *   message: "Input validation failed"
+ * };
+ *
+ * AssertString(value, validationConfig);
+ * AssertNumber(otherValue, validationConfig);
+ * ```
+ */
+export interface IAssertException {
+    /**
+     * Custom error class constructor to use when the assertion fails.
+     *
+     * This property allows specifying a custom error class that will be instantiated
+     * and thrown when the assertion fails. The class must be constructable with a
+     * message parameter. If not provided, the assertion function will use its default
+     * error class (e.g., StringError for string assertions, NumberError for number assertions).
+     *
+     * @default - Uses the default error class specific to each assertion function
+     *
+     * @example
+     * ```typescript
+     * // Using built-in error types
+     * const config1: IAssertException = { class: TypeError };
+     * const config2: IAssertException = { class: RangeError };
+     *
+     * // Using custom error classes
+     * class ValidationError extends Error {
+     *   constructor(message: string) {
+     *     super(message);
+     *     this.name = 'ValidationError';
+     *   }
+     * }
+     *
+     * const config3: IAssertException = { class: ValidationError };
+     * ```
+     */
+    class?: TConstructableObject;
+    /**
+     * Custom error message to use when the assertion fails.
+     *
+     * This property allows specifying a custom error message that will be used
+     * when creating the error instance. If not provided, the assertion function
+     * will generate a default descriptive message based on the specific validation
+     * that failed and the values involved.
+     *
+     * @default - Uses auto-generated descriptive message based on the failed assertion
+     *
+     * @example
+     * ```typescript
+     * // Custom messages for different contexts
+     * const userValidation: IAssertException = {
+     *   message: "User ID must be a positive integer"
+     * };
+     *
+     * const apiValidation: IAssertException = {
+     *   message: "API response format is invalid"
+     * };
+     *
+     * // Context-specific error messages
+     * const configValidation: IAssertException = {
+     *   class: ValidationError,
+     *   message: "Invalid configuration: expected string value"
+     * };
+     * ```
+     */
+    message?: string;
+}
+/**
+ * Type guard predicate function
+ * @template T - The type being guarded
+ * @param value - The value to check
+ * @returns true if value is of type T, false otherwise
+ */
+export type TGuard<T> = (value: unknown) => value is T;
+/**
+ * Validation predicate function
+ * @template T - The type of value being validated
+ * @param value - The value to validate
+ * @returns true if valid, false otherwise
+ */
+export type TValidationPredicate<T = unknown> = (value: T) => boolean;
+/**
+ * Array type guard predicate
+ * @template T - The element type
+ * @param value - The value to check
+ * @returns true if value is an array of type T[], false otherwise
+ */
+export type TArrayTypeGuard<T> = (value: unknown) => value is T[];
+/**
+ * Object type guard predicate
+ * @template T - The object type
+ * @param value - The value to check
+ * @returns true if value is of object type T, false otherwise
+ */
+export type TObjectTypeGuard<T extends object> = (value: unknown) => value is T;
+/**
+ * Nullable type guard predicate
+ * @template T - The non-null type
+ * @param value - The value to check
+ * @returns true if value is not null or undefined, false otherwise
+ */
+export type TNonNullableGuard<T> = (value: T | null | undefined) => value is T;
+/**
+ * Custom assertion function type
+ * @template T - The type being asserted
+ * @param value - The value to assert
+ * @param message - Optional error message
+ * @throws IAssertException if assertion fails
+ */
+export type TAssertFunction<T = unknown> = (value: unknown, message?: string) => asserts value is T;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/asserts/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAE5E;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;AAE5E;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,GAAG,KAAK,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,EAAE,CAAC;AAElE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,KAAK,KAAK,IAAI,CAAC,CAAC;AAE/E;;;;;;GAMG;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/build/asserts/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/asserts/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/asserts/types.ts"],"names":[],"mappings":""}

package/build/asserts/utils.d.ts

@@ -0,0 +1,92 @@
+import { TConstructableObject } from './internal-utils.js';
+import { IAssertException } from './types.js';
+/**
+ * Throws an exception using the configured error class and message.
+ *
+ * This function is the central point for throwing assertion errors throughout the library.
+ * It respects the exception configuration provided, using either a custom error class
+ * or falling back to the standard Error class. The function ensures that all assertion
+ * failures are thrown consistently with appropriate error types and messages.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * // Throw with custom error class
+ * ThrowException({
+ *   class: TypeError,
+ *   message: "Expected string but got number"
+ * });
+ *
+ * // Throw with default Error class
+ * ThrowException({
+ *   message: "Validation failed"
+ * });
+ *
+ * // Throw with minimal configuration
+ * ThrowException({}); // Throws generic "An assertion error occurred"
+ * ```
+ */
+export declare function ThrowException(exception: IAssertException): void;
+/**
+ * Sets the error class for an exception configuration if not already specified.
+ *
+ * This utility function is used to configure the default error class that should be
+ * thrown when an assertion fails. It respects existing configuration unless forced,
+ * allowing assertion functions to set sensible defaults while still permitting
+ * user customization.
+ *
+ * @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)
+ *
+ * @example
+ * ```typescript
+ * const config: IAssertException = {};
+ *
+ * // Set default error class (won't override if already set)
+ * SetExceptionClass(config, TypeError);
+ * console.log(config.class === TypeError); // true
+ *
+ * // Won't override existing class unless forced
+ * SetExceptionClass(config, RangeError);
+ * console.log(config.class === TypeError); // still true
+ *
+ * // Force override existing class
+ * SetExceptionClass(config, RangeError, true);
+ * console.log(config.class === RangeError); // true
+ * ```
+ */
+export declare function SetExceptionClass(exception: IAssertException, errorClass: TConstructableObject, force?: boolean): void;
+/**
+ * Sets the error message for an exception configuration if not already specified.
+ *
+ * This utility function is used to configure the default error message that should be
+ * used when an assertion fails. It respects existing configuration unless forced,
+ * allowing assertion functions to set descriptive defaults while still permitting
+ * user customization of error messages.
+ *
+ * @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)
+ *
+ * @example
+ * ```typescript
+ * const config: IAssertException = {};
+ *
+ * // Set default error message (won't override if already set)
+ * SetExceptionMessage(config, "Value must be positive");
+ * console.log(config.message); // "Value must be positive"
+ *
+ * // Won't override existing message unless forced
+ * SetExceptionMessage(config, "Different message");
+ * console.log(config.message); // still "Value must be positive"
+ *
+ * // Force override existing message
+ * SetExceptionMessage(config, "Forced message", true);
+ * console.log(config.message); // "Forced message"
+ * ```
+ */
+export declare function SetExceptionMessage(exception: IAssertException, message: string, force?: boolean): void;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/asserts/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI,CAKhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,EAAE,UAAU,EAAE,oBAAoB,EAAE,KAAK,GAAE,OAAe,GAAG,IAAI,CAG7H;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,OAAe,GAAG,IAAI,CAG9G"}

package/build/asserts/utils.js

@@ -0,0 +1,103 @@
+/**
+ * Throws an exception using the configured error class and message.
+ *
+ * This function is the central point for throwing assertion errors throughout the library.
+ * It respects the exception configuration provided, using either a custom error class
+ * or falling back to the standard Error class. The function ensures that all assertion
+ * failures are thrown consistently with appropriate error types and messages.
+ *
+ * @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
+ *
+ * @example
+ * ```typescript
+ * // Throw with custom error class
+ * ThrowException({
+ *   class: TypeError,
+ *   message: "Expected string but got number"
+ * });
+ *
+ * // Throw with default Error class
+ * ThrowException({
+ *   message: "Validation failed"
+ * });
+ *
+ * // Throw with minimal configuration
+ * ThrowException({}); // Throws generic "An assertion error occurred"
+ * ```
+ */
+export function ThrowException(exception) {
+    if (!exception.class) {
+        throw new Error(exception.message ?? 'An assertion error occurred');
+    }
+    throw new exception.class(exception.message ?? 'An assertion error occurred');
+}
+/**
+ * Sets the error class for an exception configuration if not already specified.
+ *
+ * This utility function is used to configure the default error class that should be
+ * thrown when an assertion fails. It respects existing configuration unless forced,
+ * allowing assertion functions to set sensible defaults while still permitting
+ * user customization.
+ *
+ * @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)
+ *
+ * @example
+ * ```typescript
+ * const config: IAssertException = {};
+ *
+ * // Set default error class (won't override if already set)
+ * SetExceptionClass(config, TypeError);
+ * console.log(config.class === TypeError); // true
+ *
+ * // Won't override existing class unless forced
+ * SetExceptionClass(config, RangeError);
+ * console.log(config.class === TypeError); // still true
+ *
+ * // Force override existing class
+ * SetExceptionClass(config, RangeError, true);
+ * console.log(config.class === RangeError); // true
+ * ```
+ */
+export function SetExceptionClass(exception, errorClass, force = false) {
+    if (!force && exception.class !== undefined)
+        return;
+    exception.class = errorClass;
+}
+/**
+ * Sets the error message for an exception configuration if not already specified.
+ *
+ * This utility function is used to configure the default error message that should be
+ * used when an assertion fails. It respects existing configuration unless forced,
+ * allowing assertion functions to set descriptive defaults while still permitting
+ * user customization of error messages.
+ *
+ * @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)
+ *
+ * @example
+ * ```typescript
+ * const config: IAssertException = {};
+ *
+ * // Set default error message (won't override if already set)
+ * SetExceptionMessage(config, "Value must be positive");
+ * console.log(config.message); // "Value must be positive"
+ *
+ * // Won't override existing message unless forced
+ * SetExceptionMessage(config, "Different message");
+ * console.log(config.message); // still "Value must be positive"
+ *
+ * // Force override existing message
+ * SetExceptionMessage(config, "Forced message", true);
+ * console.log(config.message); // "Forced message"
+ * ```
+ */
+export function SetExceptionMessage(exception, message, force = false) {
+    if (!force && exception.message !== undefined)
+        return;
+    exception.message = message;
+}
+//# sourceMappingURL=utils.js.map

package/build/asserts/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/asserts/utils.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,cAAc,CAAC,SAA2B;IACzD,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,OAAO,IAAI,6BAA6B,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,IAAI,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,IAAI,6BAA6B,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAA2B,EAAE,UAAgC,EAAE,QAAiB,KAAK;IACtH,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO;IACpD,SAAS,CAAC,KAAK,GAAG,UAAU,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAA2B,EAAE,OAAe,EAAE,QAAiB,KAAK;IACvG,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO;IACtD,SAAS,CAAC,OAAO,GAAG,OAAO,CAAC;AAC7B,CAAC"}

package/build/boolean/assert.d.ts

@@ -0,0 +1,66 @@
+import type { IAssertException } from '../asserts/types.js';
+/**
+ * Error thrown when a value is not a valid boolean or fails a boolean assertion.
+ *
+ * @example
+ * throw new BooleanError('Value is not a valid boolean');
+ */
+export declare class BooleanError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Asserts that a value is a boolean primitive type.
+ *
+ * This function performs a strict type assertion that validates the provided value
+ * is of type 'boolean', ensuring it's either `true` or `false`. The assertion will
+ * reject truthy/falsy values that are not actual boolean primitives, making it
+ * ideal for type narrowing in TypeScript and runtime type validation.
+ *
+ * If the assertion fails, the function throws an exception and never returns.
+ * If the assertion passes, TypeScript will narrow the type to `boolean` for
+ * subsequent code execution.
+ *
+ * @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.
+ *
+ * @example
+ * Basic usage with valid boolean values:
+ * ```typescript
+ * AssertBoolean(true);       // ✓ Passes - value is boolean true
+ * AssertBoolean(false);      // ✓ Passes - value is boolean false
+ * ```
+ *
+ * @example
+ * Assertion failures with non-boolean values:
+ * ```typescript
+ * AssertBoolean(1);          // ✗ Throws - truthy number, not boolean
+ * AssertBoolean(0);          // ✗ Throws - falsy number, not boolean
+ * AssertBoolean("true");     // ✗ Throws - string, not boolean
+ * AssertBoolean("false");    // ✗ Throws - string, not boolean
+ * AssertBoolean(null);       // ✗ Throws - null, not boolean
+ * AssertBoolean(undefined);  // ✗ Throws - undefined, not boolean
+ * AssertBoolean([]);         // ✗ Throws - array, not boolean
+ * AssertBoolean({});         // ✗ Throws - object, not boolean
+ * ```
+ *
+ * @example
+ * Using with custom exception handling:
+ * ```typescript
+ * import { AssertBoolean } from './boolean.js';
+ *
+ * // Custom error message
+ * AssertBoolean(value, { message: 'Expected a boolean value' });
+ *
+ * // Type narrowing after successful assertion
+ * function processValue(input: unknown) {
+ *   AssertBoolean(input);
+ *   // TypeScript now knows 'input' is boolean
+ *   return input ? 'yes' : 'no';
+ * }
+ * ```
+ */
+export declare function AssertBoolean(value: unknown, exception?: IAssertException): asserts value is boolean;
+//# sourceMappingURL=assert.d.ts.map

package/build/boolean/assert.d.ts.map

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