@easrng.net/futures

impl Future for TypeScript {}

I've been learning about how async works in Rust, and I wanted to play with its style of Futures in TypeScript to get a good feel for them and their advantages. It turns out they have lots of really nice properties, like cancellation and the ability to pass metadata down the stack without needing complicated engine support like AsyncLocalStorage, and they can be implemented quite ergonomically with generator functions.

Install

pnpx atpkgs add @easrng.net/futures
# or
pnpm i @easrng.net/futures

Usage

@easrng.net/futures has the core Future types, @easrng.net/futures/executor is an implementation of an executor, @easrng.net/futures/callback-future is an implementation of a future backed by an initialization function, a callback, and a cleanup function, which is useful for wrapping Promises or APIs like setTimeout. It's important to note that while Futures do implement the IterableIterator interface, they can not be used as normal iterables. If you try to loop over them with for or something they will just spin forever. Look at my executor implementation if you want to drive them yourself. Also, you need to make sure that any try/catch that surrounds a yield point eventually rethrows AbortErrors or cancellation will not work properly.

import type { Future } from "@easrng.net/futures";
import { Executor } from "@easrng.net/futures/executor";
import { CallbackFuture } from "@easrng.net/futures/callback-future";

const sleep = (ms: number): Future<void> =>
  CallbackFuture<void>((resolve) => {
    const timeout = setTimeout(resolve, ms);
    return () => {
      clearTimeout(timeout);
    };
  });

function* test(): Future<void> {
  console.log("hello worldZZzzzz...");
  yield* sleep(1000);
  console.log("i'm awake from my nap!");
}

const task = Executor.spawn(test());

// to await:
await task.promise;

// to cancel:
await task.cancel();

For something more in-depth that takes advantage of async cancellation support, see ./examples/test.ts.