ts-code-contracts/index.d.ts

Design by contract with TypeScript.

/**
 * An error thrown by a code contract.
 */
export declare abstract class ContractError extends Error {
}
/**
 * An error thrown, if a precondition for a function or method is not met.
 */
export declare class PreconditionError extends ContractError {
    constructor(message?: string);
}
/**
 * An error thrown, if an object is an illegal state.
 */
export declare class IllegalStateError extends ContractError {
    constructor(message?: string);
}
/**
 * An error thrown, if a function or method could not fulfil a postcondition.
 */
export declare class PostconditionError extends ContractError {
    constructor(message?: string);
}
/**
 * An error thrown, if an assertion has failed.
 */
export declare class AssertionError extends ContractError {
    constructor(message?: string);
}
/**
 * Throws a `PreconditionError` if the `condition` is `false`.
 * @param condition the precondition that should be `true`
 * @param message an optional message for the error
 * @throws PreconditionError if the condition is `false`
 * @see PreconditionError
 * @example
 * function myFun(name: string) {
 *   requires(name.length > 10, 'Name must be longer than 10 chars');
 * }
 */
export declare function requires(condition: boolean, message?: string): asserts condition;
/**
 * Returns the given value unchanged if it is not `null` or `undefined`.
 * Throws a `PreconditionError` otherwise.
 * @param value the value that should not be `null` or `undefined`
 * @param message an optional message for the error
 * @throws PreconditionError if the value is `null` or `undefined`
 * @see requires
 * @example
 * function myFun(name: string | null) {
 *   const nameNonNull = requiresNonNullish(name, 'Name must be defined');
 *   nameNonNull.toUpperCase(); // no compiler error!
 * }
 */
export declare function requiresNonNullish<T>(value: T, message?: string): NonNullable<T>;
/**
 * Throws a `IllegalStateError` if the `condition` is `false`.
 * @param condition the condition that should be `true`
 * @param message an optional message for the error
 * @throws IllegalStateError if the condition is `false`
 * @see IllegalStateError
 * @example
 * class Socket {
 *   private isOpen = false;
 *   send(data: Data) {
 *     check(this.isOpen, 'Socket must be open');
 *   }
 *   open() {
 *     this.isOpen = true;
 *   }
 * }
 */
export declare function checks(condition: boolean, message?: string): asserts condition;
/**
 * Returns the given value unchanged if it is not `null` or `undefined`.
 * Throws a `IllegalStateError` otherwise.
 * @param value the value that should not be `null` or `undefined`
 * @param message an optional message for the error
 * @throws IllegalStateError if the value is `null` or `undefined`
 * @see checks
 * @example
 * class Socket {
 *   data: Data | null = null;
 *   send() {
 *     const validData = checksNonNullish(this.data, 'Data must be available');
 *     validData.send(); // no compiler error!
 *   }
 * }
 */
export declare function checksNonNullish<T>(value: T, message?: string): NonNullable<T>;
/**
 * Throws a `PostconditionError` if the `condition` is `false`.
 * @param condition the condition that should be `true`
 * @param message an optional message for the error
 * @throws PostconditionError if the condition is `false`
 * @see PostconditionError
 * @example
 * function myFun() {
 *   createPerson({ id: 0, name: 'John' });
 *   const entity = findById(0); // returns null if not present
 *   return ensures(isDefined(entity), 'Failed to persist entity');
 * }
 */
export declare function ensures(condition: boolean, message?: string): asserts condition;
/**
 * Returns the given value unchanged if it is not `null` or `undefined`.
 * Throws a `PostconditionError` otherwise.
 * @param value the value that must not be `null` or `undefined`
 * @param message an optional message for the error
 * @throws PostconditionError if the value is `null` or `undefined`
 * @see ensures
 * @example
 * function myFun(): Person {
 *   createPerson({ id: 0, name: 'John' });
 *   const entity = findById(0); // returns null if not present
 *   return ensuresNonNullish(entity, 'Failed to persist entity');
 * }
 */
export declare function ensuresNonNullish<T>(value: T, message?: string): NonNullable<T>;
/**
 * Throws a `AssertionError` if the `condition` is `false`.
 * @param condition the condition that must be `true`
 * @param message an optional message for the error
 * @throws AssertionError if the condition is `false`
 * @see AssertionError
 */
export declare function asserts(condition: boolean, message?: string): asserts condition;
/**
 * Returns `true` if the value is not `null` or `undefined`.
 * @param value the value to test
 * @example
 * const x: string | null = 'Hello';
 * if (isDefined(x)) {
 *   x.toLowerCase(); // no compiler error!
 * }
 */
export declare function isDefined<T>(value: T): value is NonNullable<T>;
/**
 * Always throws an `IllegalStateError` with the given message.
 * @param message the message for the `IllegalStateError`
 * @throws IllegalStateError in any case
 * @see IllegalStateError
 * @example
 * function myFun(foo: string | null) {
 *   const bar = foo ?? error(PreconditionError, 'Argument may not be null');
 *   const result = bar.length > 0 ? 'OK' : error('Something went wrong!');
 * }
 */
export declare function error(message?: string): never;
/**
 * Always throws an error of the given type with the given message.
 * @param errorType an error class
 * @param message the error message
 * @throws errorType in any case
 * @see IllegalStateError
 * @example
 * function myFun(foo: string | null) {
 *   const bar = foo ?? error(PreconditionError, 'Argument may not be null');
 *   const result = bar.length > 0 ? 'OK' : error('Something went wrong!');
 * }
 */
export declare function error(errorType: new (...args: any[]) => Error, message?: string): never;
/**
 * Asserts that a code branch is unreachable. If it is, the compiler will throw a type error.
 * If this function is reached at runtime, an error will be thrown.
 * @param value a value
 * @param message an optional message for the error
 * @throws AssertionError in any case
 * @example
 * function myFun(foo: MyEnum): string {
 *   switch(foo) {
 *     case MyEnum.A: return 'a';
 *     case MyEnum.B: return 'b';
 *     // no compiler error if MyEnum only has A and B
 *     default: unreachable(foo);
 *   }
 * }
 */
export declare function unreachable(value: never, message?: string): never;