awaitly vs try/catch

Traditional JavaScript uses try/catch for error handling. awaitly uses Result types that make errors explicit in the type system. This guide shows the same operations in both styles.

The core idea

Start with a normal function signature:

async function fetchUser(id: string): Promise<User>

It promises a User. It says nothing about what happens when the user isn’t found, the network drops, or the server returns a 500. Those failures are real, but the type ignores them. You learn about them by reading the implementation or by hitting them in production.

awaitly moves the failures into the return type:

async function fetchUser(id: string): AsyncResult<User, 'NOT_FOUND' | 'NETWORK_ERROR'>

Now the signature tells you both outcomes: a User if it works, or 'NOT_FOUND' or 'NETWORK_ERROR' if it doesn’t. TypeScript then makes you handle the failure before you can touch the value.

New to this type syntax?

In TypeScript, a specific string like 'NOT_FOUND' can be a type of its own, and | means “one of these”. So 'NOT_FOUND' | 'NETWORK_ERROR' describes a value that is one of those two exact strings. The Result Types page walks through this from the start.

The two approaches side by side:

try/catch                           Result types
─────────────────                   ─────────────────
• Errors are implicit               • Errors are explicit
• Signature hides failure           • Signature is the contract
• Caught at runtime                 • Caught at compile time
• Easy to forget handling           • TypeScript enforces handling

When try/catch is fine: small scripts, internal tools, low-risk apps. Plain async/await with careful error handling works well there.

Where it starts to hurt: once failures are a normal part of what your code does, once several layers have to agree on how errors flow, or once you want the compiler to catch a missed case when you refactor.

Simple Operations

Parsing JSON

awaitly

import { Awaitly } from 'awaitly';

const parseJson = (str: string) => Awaitly.from(() => JSON.parse(str));

const result = parseJson('{"name": "Alice"}');

if (result.ok) {
  console.log(result.value.name);
} else {
  console.log('Parse error:', result.error.message);
}
/*
Output:
Alice
*/

try/catch

const parseJson = (str: string) => {
  try {
    return JSON.parse(str);
  } catch (error) {
    console.log('Parse error:', error.message);
    return null;
  }
};

const result = parseJson('{"name": "Alice"}');

if (result !== null) {
  console.log(result.name);
}
/*
Output:
Alice
*/

The hidden problem

With try/catch, nothing in the type system tells you parseJson can fail. With Result types, the return type Result<T, Error> makes it explicit.

API Calls

awaitly

import { Awaitly, type AsyncResult } from 'awaitly';

type FetchError = 'NETWORK_ERROR' | 'NOT_FOUND' | 'SERVER_ERROR';

const fetchUser = async (id: string): AsyncResult<User, FetchError> => {
  try {
    const res = await fetch(`/api/users/${id}`);
    if (!res.ok) {
      if (res.status === 404) return Awaitly.err('NOT_FOUND');
      return Awaitly.err('SERVER_ERROR');
    }
    return Awaitly.ok(await res.json());
  } catch {
    return Awaitly.err('NETWORK_ERROR');
  }
};

// Caller MUST handle the error - TypeScript enforces it
const result = await fetchUser('123');
if (!result.ok) {
  switch (result.error) {
    case 'NOT_FOUND':
      console.log('User not found');
      break;
    case 'NETWORK_ERROR':
      console.log('Check your connection');
      break;
    case 'SERVER_ERROR':
      console.log('Try again later');
      break;
  }
}
/*
Output (on success):
{ ok: true, value: { id: '123', name: 'Alice' } }

Output (on 404):
{ ok: false, error: 'NOT_FOUND' }
*/

try/catch

const fetchUser = async (id: string): Promise<User> => {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) {
    if (res.status === 404) throw new Error('NOT_FOUND');
    throw new Error('SERVER_ERROR');
  }
  return res.json();
};

// Caller might forget to wrap in try/catch - no TypeScript warning!
try {
  const user = await fetchUser('123');
  console.log(user.name);
} catch (error) {
  // What errors can this throw? TypeScript doesn't know.
  if (error.message === 'NOT_FOUND') {
    console.log('User not found');
  } else {
    console.log('Something went wrong');
  }
}

Error Type Safety

What can go wrong?

awaitly

// The function signature tells you exactly what can fail
const processPayment = async (
  amount: number
): AsyncResult<Receipt, 'INSUFFICIENT_FUNDS' | 'CARD_DECLINED' | 'NETWORK_ERROR'> => {
  // ...
};

// TypeScript knows all possible errors
const result = await processPayment(100);
if (!result.ok) {
  // Autocomplete shows: 'INSUFFICIENT_FUNDS' | 'CARD_DECLINED' | 'NETWORK_ERROR'
  console.log(result.error);
}

try/catch

// No indication in the type what errors can occur
const processPayment = async (amount: number): Promise<Receipt> => {
  // ...
};

// You have to read the implementation or docs to know what can throw
try {
  const receipt = await processPayment(100);
} catch (error) {
  // What type is error? unknown
  // What values can it have? Who knows
}

Documentation in types

With Result types, the possible errors are documented in the function signature. No need to dig through code or hope the docs are up to date.

What Result types don't do

awaitly does not prevent every runtime error, eliminate unexpected failures, or replace your validation logic. It gives you typed error channels and a consistent way to compose failures. You still write your own validation and guard against the unexpected.

Chaining Operations

Sequential operations with early exit

awaitly (run)

import { run } from 'awaitly/run';
import { type ErrorsOf } from 'awaitly';

const deps = { fetchUser, validateAge, createAccount };
type Errors = ErrorsOf<typeof deps>;

const result = await run<Account, Errors>(async ({ step }) => {
  const user = await step('fetchUser', () => fetchUser('123'));
  // If fetchUser fails, we stop here and return the error

  const validated = await step('validateAge', () => validateAge(user));
  // If validateAge fails, we stop here

  const account = await step('createAccount', () => createAccount(validated));
  // If createAccount fails, we stop here

  return account;
});

// Error is: 'NOT_FOUND' | 'UNDERAGE' | 'DUPLICATE_EMAIL' | UnexpectedError

awaitly (workflow)

import { createWorkflow } from 'awaitly/workflow';

// createWorkflow infers errors automatically — no ErrorsOf needed
const workflow = createWorkflow('workflow', { fetchUser, validateAge, createAccount });

const result = await workflow.run(async ({ step, deps }) => {
  const user = await step('fetchUser', () => deps.fetchUser('123'));
  const validated = await step('validateAge', () => deps.validateAge(user));
  const account = await step('createAccount', () => deps.createAccount(validated));
  return account;
});

// Same error type, plus retry/caching/observability when you need it

try/catch

const createUserAccount = async (userId: string) => {
  try {
    const user = await fetchUser(userId);
    // If fetchUser throws, we jump to catch

    const validated = await validateAge(user);
    // If validateAge throws, we jump to catch

    const account = await createAccount(validated);
    // If createAccount throws, we jump to catch

    return account;
  } catch (error) {
    // What type of error is this?
    // Which function threw it?
    // How do we handle each case?
    throw error; // Often just re-throw because we don't know
  }
};

Partial Success

When you want all results, even failures

awaitly

import { Awaitly } from 'awaitly';

const results = await Promise.all([
  fetchUser('1'),
  fetchUser('2'),
  fetchUser('3'),
]);

// Collect all outcomes (successes and failures)
const settled = Awaitly.allSettled(results);
// See [Awaitly.allSettled](/reference/api/) for the exact return shape.

// Partition into successes and failures
const [successes, failures] = Awaitly.partition(results);
console.log(`Found ${successes.length} users`);
console.log(`Failed to find ${failures.length} users`);

try/catch

const results = await Promise.allSettled([
  fetchUser('1'),
  fetchUser('2'),
  fetchUser('3'),
]);

// Have to manually filter and extract values
const successes = results
  .filter(r => r.status === 'fulfilled')
  .map(r => r.value);
const failures = results
  .filter(r => r.status === 'rejected')
  .map(r => r.reason);

console.log(`Found ${successes.length} users`);
console.log(`Failed to find ${failures.length} users`);

Transforming Results

Mapping success values

awaitly

import { Awaitly } from 'awaitly';

const result = Awaitly.ok(5);

// Transform the value
const doubled = Awaitly.map(result, n => n * 2);
// { ok: true, value: 10 }

// Chain operations that might fail
const validated = Awaitly.andThen(result, n =>
  n > 0 ? Awaitly.ok(n) : Awaitly.err('NEGATIVE')
);

try/catch

const result = 5;

// Transform the value - but no error handling built in
const doubled = result * 2;

// Chain operations that might fail - need manual try/catch
try {
  const validated = result > 0 ? result : (() => { throw 'NEGATIVE'; })();
} catch (e) {
  // ...
}

When to Use Each

Use try/catch when:

• Working with legacy code that throws
• Wrapping third-party libraries (then convert to Result)
• Truly exceptional conditions (out of memory, etc.)
• Quick scripts where type safety isn’t critical
• Your app is small, internal, or low-risk — plain async/await with disciplined error handling is perfectly reasonable

Use Result types when:

• Building new APIs or functions
• Errors are part of normal flow (validation, not found, etc.)
• You want TypeScript to track error types
• You need to compose multiple fallible operations
• You want self-documenting error handling

Wrapping Throwing Code

You don’t have to rewrite everything. Wrap existing code:

import { Awaitly } from 'awaitly';

// Sync: Awaitly.from(fn, onError)
const result1 = Awaitly.from(() => JSON.parse(jsonString), () => 'PARSE_ERROR' as const);

// Async (outside workflows): Awaitly.fromPromise(promise, onError)
const result2 = await Awaitly.fromPromise(
  fetch('/api/data').then(r => r.json()),
  () => 'FETCH_ERROR' as const
);

// With error context from the cause
const result3 = Awaitly.from(
  () => JSON.parse(data),
  (cause) => ({ type: 'PARSE_ERROR' as const, message: String(cause) })
);

// Inside workflows: step.try('id', () => …, { error: 'MY_ERROR' })

Gradual adoption

You can adopt Result types gradually. Wrap boundary code (API calls, user input) with Awaitly.from / Awaitly.fromPromise, and use step.try inside workflow callbacks.

Summary

Aspect	try/catch	Result types
Error visibility	Hidden in runtime	Explicit in types
Compiler help	None	Full type checking
Documentation	Separate (if any)	In function signature
Composition	Nested try/catch	Clean chaining
Partial failure	Manual handling	Built-in (allSettled)
Learning curve	Familiar	New pattern

The difference comes down to one thing: try/catch leaves failure out of the type, so you track it in your head. awaitly puts failure in the type, so the compiler tracks it for you.

Next Steps

• Learn about Results →
• Your First Workflow →
• Handling Errors →