Skip to content

awaitly

awaitly

Typed errors in theasync/await you already write.

When a step fails, TypeScript names the error. You keep plain async functions. Retries, timeouts, and resume land on the steps that need them.

npm install awaitly

checkout.tsworkflow graph
Bundled
Result · run() · createWorkflow()
Built in
Retries · Timeouts · Resume · Idempotency
Inferred
Error unions from your deps

Put the failure in the return type.

A function that throws looks like Promise<User> to TypeScript. The NOT_FOUND case hides in the body, and the caller'scatch gets unknown. Return err() instead and the failure sits in the signature, where the compiler checks every caller.

get-user.tsResult
import { ok, err, type AsyncResult } from 'awaitly';

async function getUser(id: string): AsyncResult<User, { type: 'NOT_FOUND' }> {
  const user = await db.find(id);
  return user ? ok(user) : err({ type: 'NOT_FOUND' });
}

const result = await getUser('123');

if (result.ok) result.value;      // User
else result.error.type;    // 'NOT_FOUND', the only option
TypeScript seesAsyncResult<User, { type: 'NOT_FOUND' }>

Rename NOT_FOUND and every caller that checks for it stops compiling. Add a second failure and every match() call stops compiling until it handles the new case.

Hand your functions to run(). Get plain values back.

Checking result.ok after every call gets old by the third call.run() does the check for you. Each call returns the unwrapped value, and the first err stops the function and becomes the result.

order.tsrun()
import { run } from 'awaitly';

const result = await run({ getOrder, getUser, charge }, async (s) => {
  const order = await s.getOrder(orderId);    // Order, not a Result
  const user = await s.getUser(order.userId); // skipped if getOrder failed
  return s.charge(user, order.total);
});

You wrote three function calls and TypeScript built that error union from them. When a step needs retries, a timeout, or resume after a crash, move the same functions into createWorkflow().

Need retries or resume? Same code, one step up.

createWorkflow() takes the same functions as run(). Here the charge retries three times, the shipment carries an idempotency key, and TypeScript still infers the error union.

checkout.tscreateWorkflow()
const checkout = createWorkflow('checkout', { reserve, charge, ship });

const result = await checkout.run(async ({ step, deps }) => {
  const hold = await step('reserve', () => deps.reserve(cart));

  // Retry only what is worth retrying.
  const payment = await step.retry('charge', () => deps.charge(hold), {
    attempts: 3,
    backoff: 'exponential',
  });

  // Keyed, so a resumed run never ships twice.
  return step('ship', () => deps.ship(payment), { key: payment.id });
});

if (!result.ok) handle(result.error);
result.error{ type: 'OUT_OF_STOCK' } | { type: 'CARD_DECLINED' } | { type: 'SHIP_FAILED' } | UnexpectedError

You did not write that union. TypeScript built it from the error types ofreserve, charge, and ship.

  • async/await

    No new control flow

    No generators, no pipe chains. The body is the async function you would have written anyway.

  • step.retry

    Policies land per step

    Only charge retries. Reserve and ship run once.

  • key

    Resume without double-shipping

    A rerun after a crash reads the cached step instead of calling the carrier twice.

  • result.error

    TypeScript writes the union

    Inferred from the three dependencies. Add a fourth and TypeScript widens it for you.

Try it on one handler. Leave the rest on try/catch.

See what a change does to the workflow.

Someone adds a fraud check to checkout. The diff shows three new lines.awaitly-analyze review reads the same change and reports a new step and a new way for checkout to fail.

checkout.ts+3 −1
  const ship = async (payment: Payment) => ...
+ const screen = async (hold): AsyncResult<Hold, { type: 'FRAUD_FLAGGED' }> => ...
- const checkout = createWorkflow('checkout', { reserve, charge, ship });
+ const checkout = createWorkflow('checkout', { reserve, screen, charge, ship });
  
      const hold = await step('reserve', () => deps.reserve(cart));
+     await step('screen', () => deps.screen(hold));
      const payment = await step.retry('charge', ...);
Fig 1. The pull request diff. Nothing in it tells the reviewer that checkout can now fail with FRAUD_FLAGGED.
awaitly-analyze review1 new error type
Steps3 → 4, + screen
Structural regressions✓ nothing removed
New error types⚠ FRAUD_FLAGGED
Complexity✓ within thresholds
Fig 2. The same change as awaitly-analyze review reports it. TypeScript backs it up: everymatch() on checkout's result stops compiling until someone handlesFRAUD_FLAGGED.
awaitly-analyze --format=xstate · autovisualizerinteractive
Fig 3. The same change, drawn from the analyzer's output. screen and its edges are new (green); the old reserve → charge edge is gone (dashed red). Press play to step through it, or click an event.

Run it on any pull request with the GitHub Action, or locally with npx awaitly-analyze review.

Three problems, three primitives.

catch (e) is unknown. You read the function body to learn what failed.

Errors as data

  • Return ok or err
  • Errors live in the type
  • Handle by name at the edge
// failures are typed values
return ok(user);
return err({ type: 'NOT_FOUND' });

You unwrap Results by hand in every async handler.

Composes with await

  • Calls return plain values
  • Happy path reads straight down
  • First error exits the run
const user = await s.getUser(id);
return s.getOrders(user.id);

Retries mean another helper library and another config shape.

Reliability built in

  • step.retry() with backoff
  • Timeouts on any step
  • Resume and idempotency keys
await step.retry('charge',
  () => deps.charge(order),
  { attempts: 3,
    backoff: 'exponential' });

Between try/catch and a full runtime.

awaitly keeps async/await and infers errors from deps. Effect and neverthrow solve adjacent problems; pick the tool that matches how you write TypeScript today.

awaitlythis librarytry / catchJavaScriptneverthrowResult typesEffectfp ecosystem
async / await syntax●●◐methods◐gens / pipe
errors typed from deps●○unknown◐manual unions●
retries / timeouts built in●○○●
pause / resume workflows●○○◐via fibers
learning curveone new fnnonelowruntime + DSL

Questions we hear often

Still stuck? Open an issue on GitHub.

Why not use Effect?

Effect covers fibers, layers, and a full runtime. awaitly targets teams that want typed errors and workflow primitives without leaving async/await. If you already write Effect, see the Effect layers guide. If you want a lighter entry point, start here.

How long does it take to learn?

Two ideas: return ok/err instead of throwing, then call run() or createWorkflow() to unwrap Results inside an async function. Most teams wire up a first workflow in an afternoon.

Can I adopt it in an existing codebase?

Yes. Wrap one handler that returns Results, call it through run(), and leave the rest on try/catch until you touch those files. No rewrite pass required.

What about runtime overhead?

awaitly adds a thin wrapper around your functions. The cost shows up in clearer types and fewer production surprises, not in extra network hops. Profile your hot paths if latency is tight.

How does it compare to neverthrow?

neverthrow gives you Result types; you maintain error unions by hand. awaitly infers the union from your dependency graph and adds retries, resume, and step metadata. See the neverthrow comparison.

Do I need a database for durable workflows?

No. Workflows run in memory by default. Plug in Postgres, Mongo, or a file store when you need crash recovery or human-in-the-loop pauses.

import { run } from "awaitly"

Stop hand-rolling error unions.

Install awaitly, wrap one handler with run(), and let the compiler track what can fail.

npm install awaitly