@ls-stack/utils 3.65.0 → 3.67.0

package/dist/assertions.d.cts

@@ -1,192 +0,0 @@
-import { isFunction as isFunction$1, isObject as isObject$1, isPlainObject as isPlainObject$1, isPromise as isPromise$1 } from './typeGuards.cjs';
-
-type NotUndefined<T> = T extends undefined ? never : T;
-type StrictNonUndefined<T, N = unknown> = undefined extends T ? NotUndefined<T> : N;
-/**
- * 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.
- *
- * @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
- * @returns The input value with undefined excluded from its type
- * @throws {Error} When the value is undefined
- */
-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.
- *
- * 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');
- *
- *   // 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
- * @returns The input value with null and undefined excluded from its type
- * @throws {Error} When the value is null or undefined
- */
-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.
- *
- * 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
- * @throws {Error} When the value is null or undefined
- */
-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.
- *
- * @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
- * @throws {Error} When the value is undefined
- */
-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.
- *
- * @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
- * @throws {Error} When the condition is falsy
- */
-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.
- *
- * @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
- *     }
- *   }
- *
- *   // 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 */
-declare const isFunction: typeof isFunction$1;
-/** @deprecated Use import from `@ls-stack/typeGuards` instead */
-declare const isObject: typeof isObject$1;
-/** @deprecated Use import from `@ls-stack/typeGuards` instead */
-declare const isPlainObject: typeof isPlainObject$1;
-/** @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.js

@@ -1,25 +0,0 @@
-import {
-  assertIsNotNullish,
-  assertIsNotUndefined,
-  exhaustiveCheck,
-  invariant,
-  isFunction,
-  isObject,
-  isPlainObject,
-  isPromise,
-  notNullish,
-  notUndefined
-} from "./chunk-C2SVCIWE.js";
-import "./chunk-JF2MDHOJ.js";
-export {
-  assertIsNotNullish,
-  assertIsNotUndefined,
-  exhaustiveCheck,
-  invariant,
-  isFunction,
-  isObject,
-  isPlainObject,
-  isPromise,
-  notNullish,
-  notUndefined
-};