typesafe-ts/dist/assert/assert.d.ts

TypeScript utilities for type-safe error handling and optional values

/**
 * Static type assertion function that enforces compile-time type checking.
 *
 * Use this function with Check utilities to assert type relationships at compile time.
 * If the assertion fails, TypeScript will show a compile error with your custom message.
 *
 * @template T - Should be a type that resolves to `true` from Check utilities. If `false`, compilation fails.
 * @template AssertMessage - Optional custom error message displayed when assertion fails
 *
 * @example
 * Basic usage with Check utilities:
 * ```ts
 * import { Assert, type Check } from "typesafe-ts/assert";
 *
 * // ✅ These compile successfully
 * Assert<Check.Equal<string, string>, "Strings should be equal">();
 * Assert<Check.True<true>, "This should be true">();
 * Assert<Check.Extends<"hello", string>, "String literal extends string">();
 *
 * // ❌ These cause compile errors
 * Assert<Check.Equal<string, number>, "Different types">(); // Compile error!
 * Assert<Check.True<false>, "This is false">(); // Compile error!
 *
 * // ⚠️These are undefined behavior and should be avoided
 * // prefer Assert<Check.IsNever<T>, "...">(); for reliable behavior
 * Assert<never, "Behavior is not guaranteed and could flip without a breaking change.">();
 * // prefer Assert<Check.IsAny<T>, "...">(); for reliable behavior
 * Assert<any, "Behavior is not guaranteed and could flip without a breaking change.">();
 * ```
 *
 * @example
 * Testing complex type relationships:
 * ```ts
 * import { Assert, type Check } from "typesafe-ts/assert";
 *
 * type User = { name: string; age: number };
 * type UserWithId = User & { id: string };
 *
 * // Assert that UserWithId extends User
 * Assert<Check.Extends<UserWithId, User>, "UserWithId should extend User">();
 *
 * // Assert that two interface definitions are equivalent
 * type ApiUser = { name: string; age: number };
 * Assert<Check.Equal<User, ApiUser>, "User and ApiUser should be the same">();
 * ```
 *
 * @example
 * Detecting problematic types:
 * ```ts
 * import { Assert, type Check } from "typesafe-ts/assert";
 *
 * // Ensure a type is not 'any' (helps catch type safety issues)
 * function processValue<T>(value: T): T {
 *   Assert<Check.IsAny<T>, "Parameter should not be 'any'">();  // ❌ Compile error if T is any
 *   return value;
 * }
 *
 * // Ensure a type is not 'never' (helps catch impossible type scenarios)
 * type Result<T> = T extends string ? string : never;
 * Assert<Check.IsNever<Result<number>>, "Result<number> creates never type">();
 * ```
 *
 * @returns Void if assertion passes, otherwise causes a compile-time error
 *
 * @see {@link import("./check.ts").Equal} - Test if two types are exactly equal
 * @see {@link import("./check.ts").True} - Test if a type is exactly `true`
 * @see {@link import("./check.ts").False} - Test if a type is exactly `false`
 * @see {@link import("./check.ts").Extends} - Test if one type extends another
 * @see {@link import("./check.ts").IsNever} - Test if a type is `never`
 * @see {@link import("./check.ts").IsAny} - Test if a type is `any`
 * @see {@link import("./check.ts").IsUnknown} - Test if a type is `unknown`
 */
export declare function Assert<T extends true | {
    "Assertion Error": AssertMessage;
    "You provided": T;
    Hint: T extends false ? "The asserted condition is false." : "Assert works best with conditional types that resolves to true or false, such as Check.Equal<A, B>, Check.IsNever<T>, etc.";
}, AssertMessage extends string = "">(): T extends true ? void : AssertionError<T, AssertMessage>;
type AssertionError<T, Message extends string> = {
    "Assertion Error": Message;
    "Check Result": T;
    Hint: "Use Check.Equal<A, B>, Check.True<T>, Check.False<T>, or Check.Extends<Sub, Super>";
};
export {};
//# sourceMappingURL=assert.d.ts.map