Numerous Pulls Merged

    assert-ts
    TypeScript icon, indicating that this package has built-in type declarations

    0.3.4 • Public • Published

    assert-ts

    Invariant and non-null/undefined assertions, both

    • strict, i.e. logs error and throws exception, and
    • soft, i.e. just logs a warning.

    Both strict and soft will narrow type, i.e. eliminate null or undefined.

    Introduction

    The purpose of this library is to make assumptions explicit, rather than just a comment or even worse just a thought while writing your code. This applies both to assumptions about conditions to be met or values not being null/undefined.

    Installation

    To install the library into your project, run yarn or npm:

    yarn add assert-ts

    or

    npm i assert-ts

    Examples

    Assert condition, strict

    import assert from 'assert-ts';
    
    function transfer(fromId: string, toId: string, amount: number) {
      // Throws error if not true
      assert(amount > 0);
      ...
    }

    Assert condition, soft

    import assert from 'assert-ts';
    
    function transfer(fromId: string, toId: string, amount: number) {
      // Logs warning if false
      if (assert.soft(amount > 0)) {
        ...
      }
    }

    Assert condition with more context info

    To make it easier to find the cause of an assertion failure, you can provide more information, i.e. a custom message and any relevant properties.

    import assert from 'assert-ts';
    
    function transfer(fromId: string, toId: string, amount: number) {
      // Custom message and properties will be formatted into error message
      assert(amount > 0, "Cannot transfer 0 or negative amounts", { fromId, toId, ammount });
      ...
    }

    Assert non-null/undefined

    import assert from 'assert-ts';
    
    function findAccount(id): Account | undefined { ... }
    
    function transfer(fromnId: string, toId: string, amount: number) {
      ...
    
      // Throws error if findAccount returns undefined
      const fromAccount = assert(findAccount(fromId), "From account does not exist", { fromId});
    
      // Type restriction: when a non-null/undefined assertion succeeds,
      // type is restricted, e.g. to Account. Hence, no need for further testing of undefined/null
      fromAccount.amount -= amount;
    
      ...
    }

    Assert non-null/undefined, soft

    import assert from 'assert-ts';
    
    
    function notify(person?: Person) {
      ...
      // Logs warning if person is undefined
      if (assert.soft(person, 'Person should be provided')) {
        // person narrowed to Person
        sendSms(person.mobile);
      }
    }

    API

    assert has two signatures

    Assert condition

    Checks that a condition is true. If not, an error is thrown. By default, any message or properties provided will be formatted as part of the error's message. See below for custom configuration.

    function assert(
      condition: boolean,
      message?: string,
      props?: object | (() => object),
    ): asserts condition;

    Assert non-null/undefined

    Checks that a value is not null or undefined. If null or undefined, an error is thrown. When successful, the returned value's type is restricted to the expected type.

    function assert<T>(
      value: T | undefined | null,
      message?: string,
      props?: object | (() => object),
    ): T;

    assert.soft has two signatures

    Check condition

    Checks that a condition is true. If not, logs a warning. By default, any message or properties provided will be formatted as part of the warning message. See below for custom configuration.

    function soft(
      condition: boolean,
      message?: string,
      props?: object | (() => object),
    ): condition is true;

    Check non-null/undefined

    Checks that a value is not null or undefined. If null or undefined, a warning is logged. When successful, the value's type is narrowed to the expected type.

    function soft<T>(
      value: T | undefined | null,
      message?: string,
      props?: object | (() => object),
    ): value is T;

    Configuration

    The default configuration throws an Error with a message saying whether it was a condition or null/undefined check that failed and any custom message or properties formatted as part of the message.

    Use configureAssert to customize this, providing an AssertConfiguration object with any of the following properties:

    Property Description
    formatter To do custom formatting of error message (failureType: FailureType, message?: string, props?: object) => string
    errorCreator To create custom error objects (failureType: FailureType, message?: string, props?: object) => Error
    errorReporter To do custom reporting of assertion failures, e.g. report to backend (failureType: FailureType, error: Error, message?: string, props?: object) => void
    warningReporter To do custom reporting of soft assertion failures, e.g. report to backend (failureType: FailureType, message?: string, props?: object) => void

    Contributors

    Bjørn Egil Hansen (@bjornegil)

    Sponsors

    Fram X - a cross platform app company from Norway.

    Install

    npm i assert-ts

    DownloadsWeekly Downloads

    2,693

    Version

    0.3.4

    License

    ISC

    Unpacked Size

    15.3 kB

    Total Files

    9

    Last publish

    Collaborators

    • bjorn_egil