Nearly Perfected Mystique

    @navidjalali/io
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.1 • Public • Published

    🍉 IO

    A small library that makes promises less eager 🥔

    IO<A> is a lightweight wrapper around () => Promise<A> with some useful combinators.

    🔧 Installation

    npm install @navidjalali/io

    ⚡️ How to make an IO

    You can make a new IO using one of the following ways:

    🏋🏻‍♂️ Lifting a pure value into an IO:

    You can make a successful or failed IO out of a pure value.

    IO.succeed(value)
    IO.fail(error)
    IO.fromNull(maybeNull)
    IO.fromUndefined(maybeUndefined)
    👷🏻‍♂️ Using the constructor:

    This is very similar to creating a normal Promise.

    new IO<A>((resolve, reject) => {
        // ...
    })
    🦆 From a thunk that returns a promise

    Any promise can be wrapped into an IO.

    IO.fromThunk(() => fetch('/api/v1/posts'))
    🍩 From a function

    Exceptions thrown by the function will be lifted into failures.

    const unsafeFunction = () => {
        // Unsafe code
    }
    
    IO.fromThunkSync(unsafeFunction)

    🤔 How to evaluate an IO?

    Simply call .run(). This will create a normal Promise.

    Polling

    Any IO that will return some Union type A | InProgress can be polled using IO.poll. This will rerun the IO until it succeeds with a result of type A.

    const checkProgress: IO<Result | InProgress> = IO.fromThunk(
        () => fetch('/api/v1/progress/poll')
    ).flatMap(_ => _.json())
    const result: IO<Result> = IO.poll(checkProgress, 100)

    Scheduling

    You can schedule an IO to run later using the scheduleOnce and scheduleForever combinators. You can also make more complicated scheduling logic yourself using IO.sleep and recursion.

    🔁 Retries

    You can retry an IO using a RetryPolicy. Currently you can only pick between Spaced and ExponentialWithBackoff

    IO.fromThunk(() => fetch('/api/v1/posts'))
        .retry(RetryPolicies.spaced(100, 3))

    Timeout

    You can effectively get a rejection if your effect runs longer than a specified period using the timeout combinator but please keep in mind that this WILL NOT cancel the Promise created from running this effect or interrupt its finalizers. Hopefully I will make this behaviour better soon.

    🌈 More!

    There's more you can do. Feel free to check the code, and contribute if you find a new usecase that can be covered!

    Install

    npm i @navidjalali/io

    DownloadsWeekly Downloads

    3

    Version

    1.1.1

    License

    ISC

    Unpacked Size

    62.5 kB

    Total Files

    18

    Last publish

    Collaborators

    • navidjalali