@ls-stack/utils 3.40.0 → 3.42.0

package/dist/assertions.d.cts

@@ -5,177 +5,188 @@ type StrictNonUndefined<T, N = unknown> = undefined extends T ? NotUndefined<T>
 /**
  * Ensures a value is not undefined and returns it with the correct type.
  *
- * Throws an error if the value is undefined. Use it instead of `!` operator for better type safety.
+ * Throws an error if the value is undefined. Use it instead of `!` operator for
+ * better type safety.
+ *
+ * @example
+ *   ```typescript
+ *   const maybeString: string | undefined = getValue();
+ *   const definiteString = notUndefined(maybeString); // Type: string
+ *
+ *   // With custom error message
+ *   const value = notUndefined(maybeValue, 'Value must be defined');
+ *
+ *   // With custom error function
+ *   const value = notUndefined(maybeValue, () => new ValidationError('Required field'));
+ *   ```;
  *
  * @template T - The type of the input value
  * @param value - The value to check for undefined
- * @param error - Error message string or function that returns an Error to throw if value is undefined
+ * @param error - Error message string or function that returns an Error to
+ *   throw if value is undefined
  * @returns The input value with undefined excluded from its type
  * @throws {Error} When the value is undefined
- *
- * @example
- * ```typescript
- * const maybeString: string | undefined = getValue();
- * const definiteString = notUndefined(maybeString); // Type: string
- *
- * // With custom error message
- * const value = notUndefined(maybeValue, 'Value must be defined');
- *
- * // With custom error function
- * const value = notUndefined(maybeValue, () => new ValidationError('Required field'));
- * ```
  */
 declare function notUndefined<T>(value: T, error?: string | (() => Error)): StrictNonUndefined<T>;
 type StrictNonNullable<T, N = unknown> = undefined extends T ? NonNullable<T> : null extends T ? NonNullable<T> : N;
 /**
- * Ensures a value is not null or undefined and returns it with the correct type.
+ * Ensures a value is not null or undefined and returns it with the correct
+ * type.
+ *
+ * Throws an error if the value is null or undefined. Use it instead of `!`
+ * operator for better type safety.
+ *
+ * @example
+ *   ```typescript
+ *   const maybeString: string | null | undefined = getValue();
+ *   const definiteString = notNullish(maybeString); // Type: string
+ *
+ *   // With custom error message
+ *   const value = notNullish(maybeValue, 'Value cannot be null or undefined');
  *
- * Throws an error if the value is null or undefined. Use it instead of `!` operator for better type safety.
+ *   // With custom error function
+ *   const value = notNullish(maybeValue, () => new ValidationError('Required field'));
+ *   ```;
  *
  * @template T - The type of the input value
  * @param value - The value to check for null or undefined
- * @param error - Error message string or function that returns an Error to throw if value is nullish
+ * @param error - Error message string or function that returns an Error to
+ *   throw if value is nullish
  * @returns The input value with null and undefined excluded from its type
  * @throws {Error} When the value is null or undefined
- *
- * @example
- * ```typescript
- * const maybeString: string | null | undefined = getValue();
- * const definiteString = notNullish(maybeString); // Type: string
- *
- * // With custom error message
- * const value = notNullish(maybeValue, 'Value cannot be null or undefined');
- *
- * // With custom error function
- * const value = notNullish(maybeValue, () => new ValidationError('Required field'));
- * ```
  */
 declare function notNullish<T>(value: T, error?: string | (() => Error)): StrictNonNullable<T>;
 /**
- * Asserts that a value is not null or undefined using TypeScript's assertion signature.
+ * Asserts that a value is not null or undefined using TypeScript's assertion
+ * signature.
  *
- * Throws an error if the value is null or undefined. Use it instead of `!` operator for better type safety.
+ * Throws an error if the value is null or undefined. Use it instead of `!`
+ * operator for better type safety.
+ *
+ * @example
+ *   ```typescript
+ *   function processValue(input: string | null | undefined) {
+ *     assertIsNotNullish(input);
+ *     // TypeScript now knows input is string
+ *     console.log(input.toUpperCase());
+ *   }
+ *
+ *   // With custom error
+ *   assertIsNotNullish(value, 'Value is required for processing');
+ *   ```;
  *
  * @template T - The type of the input value
  * @param value - The value to assert is not null or undefined
- * @param error - Error message string or function that returns an Error to throw if value is nullish
+ * @param error - Error message string or function that returns an Error to
+ *   throw if value is nullish
  * @throws {Error} When the value is null or undefined
- *
- * @example
- * ```typescript
- * function processValue(input: string | null | undefined) {
- *   assertIsNotNullish(input);
- *   // TypeScript now knows input is string
- *   console.log(input.toUpperCase());
- * }
- *
- * // With custom error
- * assertIsNotNullish(value, 'Value is required for processing');
- * ```
  */
 declare function assertIsNotNullish<T>(value: T, error?: string | (() => Error)): asserts value is StrictNonNullable<T, never>;
 /**
  * Asserts that a value is not undefined using TypeScript's assertion signature.
  *
- * Throws an error if the value is undefined. Use it instead of `!` operator for better type safety.
+ * Throws an error if the value is undefined. Use it instead of `!` operator for
+ * better type safety.
+ *
+ * @example
+ *   ```typescript
+ *   function processValue(input: string | undefined) {
+ *     assertIsNotUndefined(input);
+ *     // TypeScript now knows input is string
+ *     console.log(input.toUpperCase());
+ *   }
+ *
+ *   // With custom error
+ *   assertIsNotUndefined(value, 'Value must be defined');
+ *   ```;
  *
  * @template T - The type of the input value
  * @param value - The value to assert is not undefined
- * @param error - Error message string or function that returns an Error to throw if value is undefined
+ * @param error - Error message string or function that returns an Error to
+ *   throw if value is undefined
  * @throws {Error} When the value is undefined
- *
- * @example
- * ```typescript
- * function processValue(input: string | undefined) {
- *   assertIsNotUndefined(input);
- *   // TypeScript now knows input is string
- *   console.log(input.toUpperCase());
- * }
- *
- * // With custom error
- * assertIsNotUndefined(value, 'Value must be defined');
- * ```
  */
 declare function assertIsNotUndefined<T>(value: T, error?: string | (() => Error)): asserts value is StrictNonUndefined<T, never>;
 /**
  * Asserts that a condition is always true, throwing an error if it's falsy.
  *
- * This function is useful for enforcing invariants in your code - conditions that
- * should always be true. It uses TypeScript's assertion signature to narrow types
- * based on the condition.
+ * This function is useful for enforcing invariants in your code - conditions
+ * that should always be true. It uses TypeScript's assertion signature to
+ * narrow types based on the condition.
+ *
+ * @example
+ *   ```typescript
+ *   function divide(a: number, b: number) {
+ *     invariant(b !== 0, 'Division by zero is not allowed');
+ *     return a / b;
+ *   }
+ *
+ *   // Type narrowing example
+ *   function processUser(user: User | null) {
+ *     invariant(user, 'User must be logged in');
+ *     // TypeScript now knows user is User, not null
+ *     console.log(user.name);
+ *   }
+ *
+ *   // With custom error function
+ *   invariant(isValid, () => new ValidationError('Invalid state detected'));
+ *   ```;
  *
  * @param condition - The condition to check (any truthy/falsy value)
- * @param error - Error message string or function that returns an Error to throw if condition is falsy
+ * @param error - Error message string or function that returns an Error to
+ *   throw if condition is falsy
  * @throws {Error} When the condition is falsy
- *
- * @example
- * ```typescript
- * function divide(a: number, b: number) {
- *   invariant(b !== 0, 'Division by zero is not allowed');
- *   return a / b;
- * }
- *
- * // Type narrowing example
- * function processUser(user: User | null) {
- *   invariant(user, 'User must be logged in');
- *   // TypeScript now knows user is User, not null
- *   console.log(user.name);
- * }
- *
- * // With custom error function
- * invariant(isValid, () => new ValidationError('Invalid state detected'));
- * ```
  */
 declare function invariant(condition: any, error?: string | (() => Error)): asserts condition;
 /**
  * Ensures exhaustive type checking in switch statements or conditional logic.
  *
- * This function should be used in the default case of switch statements or
- * the final else branch of conditional logic to ensure all possible cases
- * are handled. It helps catch missing cases at compile time when new union
- * members are added.
- *
- * @template Except - The type that should never be reached
- * @param narrowedType - The value that should never exist at runtime
- * @returns An Error object (this function should never actually execute)
+ * This function should be used in the default case of switch statements or the
+ * final else branch of conditional logic to ensure all possible cases are
+ * handled. It helps catch missing cases at compile time when new union members
+ * are added.
  *
  * @example
- * ```typescript
- * type Status = 'pending' | 'success' | 'error';
- *
- * function handleStatus(status: Status) {
- *   switch (status) {
- *     case 'pending':
- *       return 'Loading...';
- *     case 'success':
- *       return 'Done!';
- *     case 'error':
- *       return 'Failed!';
- *     default:
- *       throw exhaustiveCheck(status); // TypeScript error if Status gains new members
+ *   ```typescript
+ *   type Status = 'pending' | 'success' | 'error';
+ *
+ *   function handleStatus(status: Status) {
+ *     switch (status) {
+ *       case 'pending':
+ *         return 'Loading...';
+ *       case 'success':
+ *         return 'Done!';
+ *       case 'error':
+ *         return 'Failed!';
+ *       default:
+ *         throw exhaustiveCheck(status); // TypeScript error if Status gains new members
+ *     }
  *   }
- * }
- *
- * // In conditional logic
- * function processValue(value: string | number) {
- *   if (typeof value === 'string') {
- *     return value.toUpperCase();
- *   } else if (typeof value === 'number') {
- *     return value.toString();
- *   } else {
- *     throw exhaustiveCheck(value); // Ensures all cases are covered
+ *
+ *   // In conditional logic
+ *   function processValue(value: string | number) {
+ *     if (typeof value === 'string') {
+ *       return value.toUpperCase();
+ *     } else if (typeof value === 'number') {
+ *       return value.toString();
+ *     } else {
+ *       throw exhaustiveCheck(value); // Ensures all cases are covered
+ *     }
  *   }
- * }
- * ```
+ *   ```;
+ *
+ * @template Except - The type that should never be reached
+ * @param narrowedType - The value that should never exist at runtime
+ * @returns An Error object (this function should never actually execute)
  */
 declare function exhaustiveCheck<Except = never>(narrowedType: NoInfer<Except>): Error;
-/** @deprecated use import from `@ls-stack/typeGuards` instead */
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
 declare const isFunction: typeof isFunction$1;
-/** @deprecated use import from `@ls-stack/typeGuards` instead */
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
 declare const isObject: typeof isObject$1;
-/** @deprecated use import from `@ls-stack/typeGuards` instead */
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
 declare const isPlainObject: typeof isPlainObject$1;
-/** @deprecated use import from `@ls-stack/typeGuards` instead */
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
 declare const isPromise: typeof isPromise$1;
 
 export { assertIsNotNullish, assertIsNotUndefined, exhaustiveCheck, invariant, isFunction, isObject, isPlainObject, isPromise, notNullish, notUndefined };

package/dist/assertions.d.ts

@@ -5,177 +5,188 @@ type StrictNonUndefined<T, N = unknown> = undefined extends T ? NotUndefined<T>
 /**
  * Ensures a value is not undefined and returns it with the correct type.
  *
- * Throws an error if the value is undefined. Use it instead of `!` operator for better type safety.
+ * Throws an error if the value is undefined. Use it instead of `!` operator for
+ * better type safety.
+ *
+ * @example
+ *   ```typescript
+ *   const maybeString: string | undefined = getValue();
+ *   const definiteString = notUndefined(maybeString); // Type: string
+ *
+ *   // With custom error message
+ *   const value = notUndefined(maybeValue, 'Value must be defined');
+ *
+ *   // With custom error function
+ *   const value = notUndefined(maybeValue, () => new ValidationError('Required field'));
+ *   ```;
  *
  * @template T - The type of the input value
  * @param value - The value to check for undefined
- * @param error - Error message string or function that returns an Error to throw if value is undefined
+ * @param error - Error message string or function that returns an Error to
+ *   throw if value is undefined
  * @returns The input value with undefined excluded from its type
  * @throws {Error} When the value is undefined
- *
- * @example
- * ```typescript
- * const maybeString: string | undefined = getValue();
- * const definiteString = notUndefined(maybeString); // Type: string
- *
- * // With custom error message
- * const value = notUndefined(maybeValue, 'Value must be defined');
- *
- * // With custom error function
- * const value = notUndefined(maybeValue, () => new ValidationError('Required field'));
- * ```
  */
 declare function notUndefined<T>(value: T, error?: string | (() => Error)): StrictNonUndefined<T>;
 type StrictNonNullable<T, N = unknown> = undefined extends T ? NonNullable<T> : null extends T ? NonNullable<T> : N;
 /**
- * Ensures a value is not null or undefined and returns it with the correct type.
+ * Ensures a value is not null or undefined and returns it with the correct
+ * type.
+ *
+ * Throws an error if the value is null or undefined. Use it instead of `!`
+ * operator for better type safety.
+ *
+ * @example
+ *   ```typescript
+ *   const maybeString: string | null | undefined = getValue();
+ *   const definiteString = notNullish(maybeString); // Type: string
+ *
+ *   // With custom error message
+ *   const value = notNullish(maybeValue, 'Value cannot be null or undefined');
  *
- * Throws an error if the value is null or undefined. Use it instead of `!` operator for better type safety.
+ *   // With custom error function
+ *   const value = notNullish(maybeValue, () => new ValidationError('Required field'));
+ *   ```;
  *
  * @template T - The type of the input value
  * @param value - The value to check for null or undefined
- * @param error - Error message string or function that returns an Error to throw if value is nullish
+ * @param error - Error message string or function that returns an Error to
+ *   throw if value is nullish
  * @returns The input value with null and undefined excluded from its type
  * @throws {Error} When the value is null or undefined
- *
- * @example
- * ```typescript
- * const maybeString: string | null | undefined = getValue();
- * const definiteString = notNullish(maybeString); // Type: string
- *
- * // With custom error message
- * const value = notNullish(maybeValue, 'Value cannot be null or undefined');
- *
- * // With custom error function
- * const value = notNullish(maybeValue, () => new ValidationError('Required field'));
- * ```
  */
 declare function notNullish<T>(value: T, error?: string | (() => Error)): StrictNonNullable<T>;
 /**
- * Asserts that a value is not null or undefined using TypeScript's assertion signature.
+ * Asserts that a value is not null or undefined using TypeScript's assertion
+ * signature.
  *
- * Throws an error if the value is null or undefined. Use it instead of `!` operator for better type safety.
+ * Throws an error if the value is null or undefined. Use it instead of `!`
+ * operator for better type safety.
+ *
+ * @example
+ *   ```typescript
+ *   function processValue(input: string | null | undefined) {
+ *     assertIsNotNullish(input);
+ *     // TypeScript now knows input is string
+ *     console.log(input.toUpperCase());
+ *   }
+ *
+ *   // With custom error
+ *   assertIsNotNullish(value, 'Value is required for processing');
+ *   ```;
  *
  * @template T - The type of the input value
  * @param value - The value to assert is not null or undefined
- * @param error - Error message string or function that returns an Error to throw if value is nullish
+ * @param error - Error message string or function that returns an Error to
+ *   throw if value is nullish
  * @throws {Error} When the value is null or undefined
- *
- * @example
- * ```typescript
- * function processValue(input: string | null | undefined) {
- *   assertIsNotNullish(input);
- *   // TypeScript now knows input is string
- *   console.log(input.toUpperCase());
- * }
- *
- * // With custom error
- * assertIsNotNullish(value, 'Value is required for processing');
- * ```
  */
 declare function assertIsNotNullish<T>(value: T, error?: string | (() => Error)): asserts value is StrictNonNullable<T, never>;
 /**
  * Asserts that a value is not undefined using TypeScript's assertion signature.
  *
- * Throws an error if the value is undefined. Use it instead of `!` operator for better type safety.
+ * Throws an error if the value is undefined. Use it instead of `!` operator for
+ * better type safety.
+ *
+ * @example
+ *   ```typescript
+ *   function processValue(input: string | undefined) {
+ *     assertIsNotUndefined(input);
+ *     // TypeScript now knows input is string
+ *     console.log(input.toUpperCase());
+ *   }
+ *
+ *   // With custom error
+ *   assertIsNotUndefined(value, 'Value must be defined');
+ *   ```;
  *
  * @template T - The type of the input value
  * @param value - The value to assert is not undefined
- * @param error - Error message string or function that returns an Error to throw if value is undefined
+ * @param error - Error message string or function that returns an Error to
+ *   throw if value is undefined
  * @throws {Error} When the value is undefined
- *
- * @example
- * ```typescript
- * function processValue(input: string | undefined) {
- *   assertIsNotUndefined(input);
- *   // TypeScript now knows input is string
- *   console.log(input.toUpperCase());
- * }
- *
- * // With custom error
- * assertIsNotUndefined(value, 'Value must be defined');
- * ```
  */
 declare function assertIsNotUndefined<T>(value: T, error?: string | (() => Error)): asserts value is StrictNonUndefined<T, never>;
 /**
  * Asserts that a condition is always true, throwing an error if it's falsy.
  *
- * This function is useful for enforcing invariants in your code - conditions that
- * should always be true. It uses TypeScript's assertion signature to narrow types
- * based on the condition.
+ * This function is useful for enforcing invariants in your code - conditions
+ * that should always be true. It uses TypeScript's assertion signature to
+ * narrow types based on the condition.
+ *
+ * @example
+ *   ```typescript
+ *   function divide(a: number, b: number) {
+ *     invariant(b !== 0, 'Division by zero is not allowed');
+ *     return a / b;
+ *   }
+ *
+ *   // Type narrowing example
+ *   function processUser(user: User | null) {
+ *     invariant(user, 'User must be logged in');
+ *     // TypeScript now knows user is User, not null
+ *     console.log(user.name);
+ *   }
+ *
+ *   // With custom error function
+ *   invariant(isValid, () => new ValidationError('Invalid state detected'));
+ *   ```;
  *
  * @param condition - The condition to check (any truthy/falsy value)
- * @param error - Error message string or function that returns an Error to throw if condition is falsy
+ * @param error - Error message string or function that returns an Error to
+ *   throw if condition is falsy
  * @throws {Error} When the condition is falsy
- *
- * @example
- * ```typescript
- * function divide(a: number, b: number) {
- *   invariant(b !== 0, 'Division by zero is not allowed');
- *   return a / b;
- * }
- *
- * // Type narrowing example
- * function processUser(user: User | null) {
- *   invariant(user, 'User must be logged in');
- *   // TypeScript now knows user is User, not null
- *   console.log(user.name);
- * }
- *
- * // With custom error function
- * invariant(isValid, () => new ValidationError('Invalid state detected'));
- * ```
  */
 declare function invariant(condition: any, error?: string | (() => Error)): asserts condition;
 /**
  * Ensures exhaustive type checking in switch statements or conditional logic.
  *
- * This function should be used in the default case of switch statements or
- * the final else branch of conditional logic to ensure all possible cases
- * are handled. It helps catch missing cases at compile time when new union
- * members are added.
- *
- * @template Except - The type that should never be reached
- * @param narrowedType - The value that should never exist at runtime
- * @returns An Error object (this function should never actually execute)
+ * This function should be used in the default case of switch statements or the
+ * final else branch of conditional logic to ensure all possible cases are
+ * handled. It helps catch missing cases at compile time when new union members
+ * are added.
  *
  * @example
- * ```typescript
- * type Status = 'pending' | 'success' | 'error';
- *
- * function handleStatus(status: Status) {
- *   switch (status) {
- *     case 'pending':
- *       return 'Loading...';
- *     case 'success':
- *       return 'Done!';
- *     case 'error':
- *       return 'Failed!';
- *     default:
- *       throw exhaustiveCheck(status); // TypeScript error if Status gains new members
+ *   ```typescript
+ *   type Status = 'pending' | 'success' | 'error';
+ *
+ *   function handleStatus(status: Status) {
+ *     switch (status) {
+ *       case 'pending':
+ *         return 'Loading...';
+ *       case 'success':
+ *         return 'Done!';
+ *       case 'error':
+ *         return 'Failed!';
+ *       default:
+ *         throw exhaustiveCheck(status); // TypeScript error if Status gains new members
+ *     }
  *   }
- * }
- *
- * // In conditional logic
- * function processValue(value: string | number) {
- *   if (typeof value === 'string') {
- *     return value.toUpperCase();
- *   } else if (typeof value === 'number') {
- *     return value.toString();
- *   } else {
- *     throw exhaustiveCheck(value); // Ensures all cases are covered
+ *
+ *   // In conditional logic
+ *   function processValue(value: string | number) {
+ *     if (typeof value === 'string') {
+ *       return value.toUpperCase();
+ *     } else if (typeof value === 'number') {
+ *       return value.toString();
+ *     } else {
+ *       throw exhaustiveCheck(value); // Ensures all cases are covered
+ *     }
  *   }
- * }
- * ```
+ *   ```;
+ *
+ * @template Except - The type that should never be reached
+ * @param narrowedType - The value that should never exist at runtime
+ * @returns An Error object (this function should never actually execute)
  */
 declare function exhaustiveCheck<Except = never>(narrowedType: NoInfer<Except>): Error;
-/** @deprecated use import from `@ls-stack/typeGuards` instead */
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
 declare const isFunction: typeof isFunction$1;
-/** @deprecated use import from `@ls-stack/typeGuards` instead */
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
 declare const isObject: typeof isObject$1;
-/** @deprecated use import from `@ls-stack/typeGuards` instead */
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
 declare const isPlainObject: typeof isPlainObject$1;
-/** @deprecated use import from `@ls-stack/typeGuards` instead */
+/** @deprecated Use import from `@ls-stack/typeGuards` instead */
 declare const isPromise: typeof isPromise$1;
 
 export { assertIsNotNullish, assertIsNotUndefined, exhaustiveCheck, invariant, isFunction, isObject, isPlainObject, isPromise, notNullish, notUndefined };