@pawells/typescript-common 1.0.0 → 1.1.0

package/build/asserts/string.js

@@ -0,0 +1,185 @@
+import { SetExceptionClass, SetExceptionMessage, ThrowException } from './utils.js';
+/**
+ * Cache for compiled regex patterns to improve performance when the same patterns are used repeatedly.
+ * Maps regex source + flags to the compiled RegExp object for efficient reuse.
+ *
+ * @internal
+ */
+const REGEX_PATTERN_CACHE = new Map();
+/**
+ * Maximum number of cached regex patterns to prevent unbounded memory growth.
+ * When this limit is reached, the cache will be cleared to maintain memory efficiency.
+ *
+ * @internal
+ */
+const MAX_CACHE_SIZE = 100;
+/**
+ * Number of oldest cache entries to evict in one batch when the cache is full.
+ *
+ * @internal
+ */
+const CACHE_EVICTION_BATCH_SIZE = 20;
+/**
+ * Gets a cached regex pattern or creates and caches a new one.
+ * This optimization improves performance when the same regex patterns are used repeatedly.
+ *
+ * @param source - The regex pattern source string
+ * @param flags - The regex flags string
+ * @returns The compiled RegExp object
+ * @internal
+ */
+function getCachedRegex(source, flags = '') {
+    const cacheKey = `${source}:::${flags}`;
+    let regex = REGEX_PATTERN_CACHE.get(cacheKey);
+    if (!regex) {
+        // Use LRU eviction: delete oldest entries when cache reaches limit
+        if (REGEX_PATTERN_CACHE.size >= MAX_CACHE_SIZE) {
+            const keysToDelete = Array.from(REGEX_PATTERN_CACHE.keys()).slice(0, CACHE_EVICTION_BATCH_SIZE);
+            keysToDelete.forEach(key => REGEX_PATTERN_CACHE.delete(key));
+        }
+        regex = new RegExp(source, flags);
+        REGEX_PATTERN_CACHE.set(cacheKey, regex);
+    }
+    return regex;
+}
+/**
+ * Error thrown when a value is not a valid string or fails a string assertion.
+ *
+ * @example
+ * throw new StringError('Value is not a valid string');
+ */
+export class StringError extends Error {
+    constructor(message) {
+        super(message ?? 'String Assertion Failed');
+        this.name = 'StringError';
+        Object.setPrototypeOf(this, StringError.prototype);
+    }
+}
+/**
+ * Asserts that a value is a string primitive type.
+ *
+ * This method validates that the provided value is of type 'string'. It accepts
+ * any string including empty strings. This is a strict type check that will
+ * reject string objects created with new String().
+ *
+ * @template TError - Custom error type to throw on failure
+ * @param value - The value to validate as a string
+ * @param exception - Optional exception configuration for custom error handling
+ * @throws {StringError} When value is not a string primitive
+ *
+ * @example
+ * ```typescript
+ * AssertString("hello");             // ✓ Valid
+ * AssertString("");                  // ✓ Valid (empty string is still a string)
+ * AssertString("123");               // ✓ Valid (numeric string)
+ * AssertString(123);                 // ✗ Throws StringError (number)
+ * AssertString(null);                // ✗ Throws StringError
+ * AssertString(new String("hello")); // ✗ Throws StringError (String object)
+ * ```
+ */
+export function AssertString(value, exception = {}) {
+    SetExceptionClass(exception, StringError);
+    if (typeof value !== 'string') {
+        SetExceptionMessage(exception, `Expected string but received ${typeof value}: ${String(value)}`);
+        ThrowException(exception);
+    }
+}
+/**
+ * Asserts that a value is a non-empty string (after trimming whitespace).
+ *
+ * This method validates that the provided value is a string and contains at least
+ * one non-whitespace character after trimming. This is useful for validating user
+ * inputs, form fields, and API parameters where empty or whitespace-only strings
+ * are not acceptable.
+ *
+ * @template TError - Custom error type to throw on failure
+ * @param value - The value to validate as a non-empty string
+ * @param exception - Optional exception configuration for custom error handling
+ * @throws {StringError} When value is not a string or is empty/whitespace-only
+ *
+ * @example
+ * ```typescript
+ * AssertStringNotEmpty("hello");         // ✓ Valid
+ * AssertStringNotEmpty("  a  ");         // ✓ Valid (has non-whitespace content)
+ * AssertStringNotEmpty("x");             // ✓ Valid (single character)
+ * AssertStringNotEmpty("");              // ✗ Throws StringError (empty)
+ * AssertStringNotEmpty("   ");           // ✗ Throws StringError (whitespace only)
+ * AssertStringNotEmpty("\t\n  ");        // ✗ Throws StringError (whitespace only)
+ * AssertStringNotEmpty(123);             // ✗ Throws StringError (not a string)
+ * ```
+ */
+export function AssertStringNotEmpty(value, exception = {}) {
+    SetExceptionClass(exception, StringError);
+    if (typeof value !== 'string') {
+        SetExceptionMessage(exception, `Expected non-empty string but received ${typeof value}: ${String(value)}`);
+        ThrowException(exception);
+    }
+    const str = value;
+    if (str === '') {
+        SetExceptionMessage(exception, 'Expected non-empty string but received empty string');
+        ThrowException(exception);
+    }
+    if (str.trim() === '') {
+        SetExceptionMessage(exception, 'Expected non-empty string but received whitespace-only string');
+        ThrowException(exception);
+    }
+}
+/**
+ * Asserts that a string matches a regular expression pattern.
+ *
+ * This method validates that the provided string matches the specified regular
+ * expression pattern. The string must be a valid string type (use AssertString first
+ * if needed). Useful for validating formats like emails, phone numbers, IDs, and
+ * other structured text data.
+ *
+ * For performance optimization, regex patterns are cached when possible to avoid
+ * recompilation of the same patterns. This provides significant performance benefits
+ * when validating many values against the same pattern.
+ *
+ * @template TError - Custom error type to throw on failure
+ * @param value - The string to test against the pattern
+ * @param regex - The regular expression pattern to match against
+ * @param exception - Optional exception configuration for custom error handling
+ * @throws {StringError} When string does not match the pattern
+ *
+ * @example
+ * ```typescript
+ * // Email validation
+ * AssertStringMatches("hello@example.com", /^[^\s@]+@[^\s@]+\.[^\s@]+$/);  // ✓ Valid
+ *
+ * // Digits only validation
+ * AssertStringMatches("123", /^\d+$/);                                     // ✓ Valid
+ * AssertStringMatches("12a", /^\d+$/);                                     // ✗ Throws StringError
+ *
+ * // Phone number format
+ * AssertStringMatches("(555) 123-4567", /^\(\d{3}\) \d{3}-\d{4}$/);       // ✓ Valid
+ *
+ * // Alphanumeric with length constraint
+ * AssertStringMatches("abc123", /^[a-zA-Z0-9]{3,10}$/);                   // ✓ Valid
+ * AssertStringMatches("ab", /^[a-zA-Z0-9]{3,10}$/);                       // ✗ Throws (too short)
+ *
+ * // Performance benefit with repeated pattern usage
+ * const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+ * AssertStringMatches("user1@example.com", emailPattern); // Cached for future use
+ * AssertStringMatches("user2@example.com", emailPattern); // Uses cached pattern
+ * ```
+ */
+export function AssertStringMatches(value, regex, exception = {}) {
+    SetExceptionClass(exception, StringError);
+    AssertString(value, exception); // Ensure value is a string before matching
+    // Use cached regex for better performance when possible
+    // If the regex has a source and flags, we can cache it for reuse
+    let testRegex;
+    if (regex.source && regex.flags !== undefined) {
+        testRegex = getCachedRegex(regex.source, regex.flags);
+    }
+    else {
+        // Fallback to original regex if caching is not possible
+        testRegex = regex;
+    }
+    if (!testRegex.test(value)) {
+        SetExceptionMessage(exception, `String does not match the required pattern: ${regex.toString()}`);
+        ThrowException(exception);
+    }
+}
+//# sourceMappingURL=string.js.map

package/build/asserts/string.js.map

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