TypeScript Async Patterns

Type async/await, Promise chains, and concurrent patterns correctly in TypeScript

When to Use

• Typing async functions and their return values
• Handling errors in async code with proper types
• Running concurrent operations with Promise.all, Promise.allSettled, Promise.race
• Creating typed async utilities and middleware

Instructions

1. Async function return types — always return

   Promise<T>

   :

async function getUser(id: string): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

2. Type Promise.all — preserves tuple types:

const [user, posts, settings] = await Promise.all([
  getUser(userId), // Promise<User>
  getUserPosts(userId), // Promise<Post[]>
  getSettings(), // Promise<Settings>
]);
// Types: [User, Post[], Settings]

3. Promise.allSettled — returns settled results with status:

const results = await Promise.allSettled([fetchUser(), fetchPosts()]);

for (const result of results) {
  if (result.status === 'fulfilled') {
    console.log(result.value); // Type: User | Post[] (union of all types)
  } else {
    console.log(result.reason); // Type: any
  }
}

4. Promise.race — returns the type of the first resolved:

const result = await Promise.race([
  fetchData(), // Promise<Data>
  timeout(5000), // Promise<never>
]);
// Type: Data (never is absorbed)

5. Typed error handling — catch blocks receive

   unknown

   :

async function fetchUser(id: string): Promise<User> {
  try {
    const res = await fetch(`/api/users/${id}`);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  } catch (error) {
    if (error instanceof Error) {
      throw new Error(`Failed to fetch user: ${error.message}`);
    }
    throw error;
  }
}

6. Result type pattern — avoid exceptions for expected failures:

type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

async function safeFetch<T>(url: string): Promise<Result<T>> {
  try {
    const res = await fetch(url);
    if (!res.ok) return { ok: false, error: new Error(`HTTP ${res.status}`) };
    return { ok: true, value: await res.json() };
  } catch (error) {
    return { ok: false, error: error instanceof Error ? error : new Error(String(error)) };
  }
}

7. Typed retry logic:

async function retry<T>(
  fn: () => Promise<T>,
  options: { retries: number; delay: number }
): Promise<T> {
  for (let i = 0; i <= options.retries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === options.retries) throw error;
      await new Promise((r) => setTimeout(r, options.delay * (i + 1)));
    }
  }
  throw new Error('Unreachable');
}

8. Concurrent execution with concurrency limit:

async function mapConcurrent<T, R>(
  items: T[],
  fn: (item: T) => Promise<R>,
  concurrency: number
): Promise<R[]> {
  const results: R[] = [];
  const executing = new Set<Promise<void>>();

  for (const item of items) {
    const p = fn(item).then((result) => {
      results.push(result);
    });
    executing.add(p);
    p.finally(() => executing.delete(p));

    if (executing.size >= concurrency) {
      await Promise.race(executing);
    }
  }

  await Promise.all(executing);
  return results;
}

9. AsyncIterable for streaming data:

async function* paginate<T>(
  fetchPage: (cursor?: string) => Promise<{ data: T[]; nextCursor?: string }>
): AsyncGenerator<T> {
  let cursor: string | undefined;
  do {
    const page = await fetchPage(cursor);
    yield* page.data;
    cursor = page.nextCursor;
  } while (cursor);
}

for await (const user of paginate(fetchUsers)) {
  console.log(user);
}

Details

TypeScript types async code through the

Promise<T>

await

Promise<T>

T

async

Promise<T>

Awaited<T>

Awaited<Promise<Promise<string>>>

string

Promise.all

Error typing limitations:

catch

.catch()

unknown

useUnknownInCatchVariables

void

undefined

Promise<void>

Promise<undefined>

void

undefined

Unhandled rejection risks: Forgetting to

await

@typescript-eslint/no-floating-promises

Trade-offs:

• Promise.all

  fails fast — if one promise rejects, the entire result rejects. Use

  Promise.allSettled

  when partial success is acceptable
• Async generators are powerful but hard to debug and have poor error propagation
• The Result pattern avoids exceptions but adds verbosity — use it for expected failures (API errors), not unexpected ones (null references)

Source

https://typescriptlang.org/docs/handbook/release-notes/typescript-4-7.html

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.