Skip to content
Badlands

Assert

The assert utility is a TypeScript function used to validate conditions at runtime. It throws an error with a custom message if the condition is not met and helps TypeScript narrow types by asserting the condition to be true after the check.

assert(condition: unknown, message: string): asserts condition

This function checks the given condition and throws an error with the provided message if the condition evaluates to false. The assert function also tells TypeScript that the condition is asserted to be true after the check if no error is thrown. This is useful for narrowing types in TypeScript.

Parameters:

  • condition (unknown): The condition to check. This could be any expression, and if it evaluates to false, an error will be thrown.
  • message (string): The message that will be included in the error if the condition is not met.

Return Type:

  • asserts condition: This type assertion tells TypeScript that the type of condition is guaranteed to be true after this function call if no error is thrown.

Example Usage:

function someFunction(data: unknown) {
  // Assert that `data` is of type string.
  assert(typeof data === "string", "Data must be a string");


  // After the assertion, TypeScript knows `data` is a string.
  console.log(data.toUpperCase());
}


// Usage:
someFunction("hello"); // This works fine.
someFunction(123); // This will throw an error: "Data must be a string"

How It Works:

  • The function checks if the condition evaluates to false.
    • If false, it throws an error with the provided message.
    • If true, the function proceeds without interruption.
  • The asserts condition return type tells TypeScript’s type system that the condition is now considered true after this assertion if no error is thrown. This allows TypeScript to narrow down types in the following code, making the type system more useful and preventing errors.

Example Scenario:

Let’s say you are writing a function that only accepts positive numbers. You could use this assert function to ensure that the value meets the condition before proceeding with further logic:

function calculateSquareRoot(num: number) {
  // Ensure the number is non-negative.
  assert(num >= 0, "Number must be non-negative");


  return Math.sqrt(num);
}


calculateSquareRoot(4); // Returns 2
calculateSquareRoot(-4); // Throws Error: "Number must be non-negative"

In this example, if the assert condition fails, the error is thrown, and TypeScript will know that after the assertion, it can safely assume the number is non-negative. This ensures better code safety and less chance of runtime errors.

Notes:

  • This function is typically used in development or debugging scenarios to enforce conditions and validate inputs.
  • It can also be used for validating conditions before performing type-dependent operations in TypeScript, such as narrowing a union type.
  • Be cautious about using assertions in production code, as they can add overhead due to runtime checks. Consider using them primarily in development or testing environments.