typia/lib/AssertionGuard.d.ts

Superfast runtime validators with only one line

/**
 * Type definition for assertion guard functions in `typia`.
 *
 * An assertion guard is a function that asserts an input value's type at runtime
 * and performs a TypeScript type assertion if validation passes. Unlike regular
 * assertion functions that return the validated value, assertion guards return
 * nothing but automatically cast the input parameter to the expected type `T`.
 *
 * This type is used by `typia.createAssertGuard<T>()` and `typia.createAssertGuardEquals<T>()`
 * to generate reusable assertion guard functions.
 *
 * @template T - The expected type to validate and assert against
 * @param input - The value to validate (type unknown)
 * @throws {TypeGuardError} When the input value doesn't match the expected type T
 * @returns void - Returns nothing, but asserts that input is type T
 *
 * @example
 * ```typescript
 * interface IMember {
 *   name: string;
 *   age: number;
 * }
 *
 * // Create reusable assertion guard
 * const assertMember: AssertionGuard<IMember> = typia.createAssertGuard<IMember>();
 *
 * // Usage - input will be automatically cast to IMember if validation passes
 * const unknownData: unknown = { name: "John", age: 25 };
 *
 * assertMember(unknownData);
 * // After this line, unknownData is automatically treated as IMember type
 * console.log(unknownData.name); // TypeScript knows this is safe
 * ```
 *
 * @see {@link https://github.com/samchon/typia#assertguard-functions} Typia assertion guards documentation
 * @see {@link TypeGuardError} Error thrown when assertion fails
 * @author Jeongho Nam - https://github.com/samchon
 */
export type AssertionGuard<T> = (input: unknown) => asserts input is T;