awaitly vs Effect

Effect is a comprehensive FP runtime and ecosystem for TypeScript. It targets full application architecture (concurrency, resource safety, dependency management, and a large stdlib). awaitly focuses on typed async workflows and orchestration, staying on native async/await (no Effect runtime or generator DSL).

TL;DR

• Choose awaitly if you want async/await-native workflows with typed errors and orchestration features (sagas, durable execution, circuit breakers, HITL).
• Choose Effect if you want a full runtime with fibers, Layers, Scope, Schedule, Stream, and a larger FP ecosystem.

The sections below go into detail.

The Abstraction-Level Difference

Effect works at the infrastructure level. It’s a full effect runtime with a capability-tracking type system: fibers, Scope, Layers, Schedule algebra. The runtime manages effects (concurrency, interruption, resource lifecycles), and the type system encodes that architecture.

awaitly works at the application-orchestration level. It’s a minimal effect abstraction layered directly on JavaScript: async/await, Result types, and a step engine. No custom runtime. Architecture lives in values (deps, config, store), not in a capability graph.

These sit at different layers of the stack. awaitly is a deliberately minimal computation model for TypeScript apps: async workflows, typed errors, and value-level dependencies, with no custom runtime. Effect is the tool when you want that runtime and the full type-level encoding of capabilities.

Philosophy Comparison

Effect                              awaitly
┌─────────────────────────┐         ┌───────────────────────────┐
│  FP runtime & ecosystem │         │  async/await + Result<T,E>│
│  ────────────────────── │         │  ──────────────────────── │
│  • Fibers & concurrency │         │  • Native Promises        │
│  • Layer-based DI       │         │  • Workflow orchestration │
│  • Schedule combinators │         │  • Retry/timeout/limits   │
│  • Scope & resources    │         │  • Automatic error union  │
│  • Comprehensive stdlib │         │  • Circuit breaker, saga  │
│                         │         │  • Durable execution      │
│                         │         │  • Human-in-the-loop      │
└─────────────────────────┘         └───────────────────────────┘

Different tools, overlapping problems

Both libraries can give you typed errors, retries, resource cleanup, and composition. Effect does it through a functional runtime with fibers and generators. awaitly does it through async/await with a step engine. The trade-off is learning curve and bundle size vs. Effect’s richer concurrency model.

First impressions: the same code you’d write today

If you can write async/await, you already know awaitly. There is no generator DSL or custom runtime to adopt. You write code that looks like the code you wrote yesterday, and you get typed errors and step-level observability by default, with retries available through the step engine when you need them.

awaitly

import { ok, err, type AsyncResult, run } from 'awaitly';

const fetchUser = async (id: string): AsyncResult<User, 'NOT_FOUND'> =>
  id === '1' ? ok({ id, name: 'Ada' }) : err('NOT_FOUND');

const result = await run(async ({ step }) => {
  const user = await step('fetchUser', () => fetchUser(id));
  return user.name;
});

// result.ok ? result.value : result.error  — error is "NOT_FOUND" | UnexpectedError

Effect

import { Effect, Data } from 'effect';

class NotFound extends Data.TaggedError('NotFound')<{}> {}

const fetchUser = (id: string) =>
  id === '1' ? Effect.succeed({ id, name: 'Ada' }) : Effect.fail(new NotFound());

const program = Effect.gen(function* () {
  const user = yield* fetchUser(id);
  return user.name;
});

const result = await Effect.runPromise(Effect.either(program));
// result._tag === 'Right' ? result.right : result.left

awaitly stays in async/await. In workflow-style APIs (run, createWorkflow), errors are inferred from your dependency object, no manual annotations, no Effect<A, E, R> to thread through. When you’re ready for more (retries, sagas, durable execution, dependency injection), you opt in as needed.

Closest Equivalent to Effect.gen: run() deps-first

The deps-first form run(deps, fn) gives you Effect-like sequential composition while staying in native async/await. The body is async/await; each dep call on the bound steps object is automatically a tracked step using its property name as the id, and errors are inferred from the deps’ return types.

awaitly

import { run, ok, err, type AsyncResult } from 'awaitly';

type User = { id: string; name: string };
type Post = { id: string; userId: string };

const getUser = async (id: string): AsyncResult<User, 'NOT_FOUND'> =>
  id === '1' ? ok({ id, name: 'Ada' }) : err('NOT_FOUND');

const getPosts = async (userId: string): AsyncResult<Post[], 'POSTS_FAILED'> =>
  ok([{ id: 'p1', userId }]);

const result = await run({ getUser, getPosts }, async (s) => {
  const user = await s.getUser('1');
  const posts = await s.getPosts(user.id);
  return { user, posts };
});

// result.error: 'NOT_FOUND' | 'POSTS_FAILED' | UnexpectedError

Effect

import { Effect, Data } from 'effect';

class NotFound extends Data.TaggedError('NotFound')<{}> {}
class PostsFailed extends Data.TaggedError('PostsFailed')<{}> {}

const getUser = (id: string) =>
  id === '1' ? Effect.succeed({ id, name: 'Ada' }) : Effect.fail(new NotFound());

const getPosts = (userId: string) =>
  Effect.succeed([{ id: 'p1', userId }]).pipe(
    Effect.mapError(() => new PostsFailed())
  );

const program = Effect.gen(function* () {
  const user = yield* getUser('1');
  const posts = yield* getPosts(user.id);
  return { user, posts };
});

const result = await Effect.runPromise(Effect.either(program));

More control: explicit steps and parallel scopes

When you need a custom step id (e.g. calling the same dep twice), parallel execution, or per-call retry/timeout/cache, use the explicit step API the callback also receives. step.all runs a named parallel scope; step.map / step.race and retry/timeout options are all available here. For dependency injection, testing overrides, and resume, graduate to createWorkflow().

const result = await run({ getUser, getPosts }, async (s, { step }) => {
  const user = await step('user:primary', () => getUser('1'));

  const { posts, profile } = await step.all('fetchProfileBundle', {
    posts: () => getPosts(user.id),
    profile: () => getUser(user.id),
  });

  return { user, posts, profile };
});

Quick Comparison

This table compares Effect core/stdlib with awaitly core plus optional awaitly modules (ratelimit, durable, saga, etc.). Effect can implement many of these patterns via primitives or ecosystem packages; awaitly provides some as ready-made modules.

Feature	awaitly	Effect
Learning curve	Low (async/await mental model)	Higher (runtime model + Effect.gen/Layers)
Bundle footprint	Small; grows with modules used	Larger baseline; grows with modules used
Result type	Result<T, E>	Effect<A, E, R>
Error typing	Inferred from workflow deps + usage	Tracked in E; generally inferred through composition (flatMap, gen, etc.)
Async model	Native Promises	Effect runtime with fibers
Dependency injection	createWorkflow('name', deps), withDeps(workflow, overrides), and override per run via workflow.run(fn, { deps })	Layers (Context-based DI)
Retry / scheduling	Config objects	Schedule combinators
Concurrency	step.all / step.map / step.race (inside workflows)	Fibers
Interruption / cancellation	Cooperative via AbortSignal	Structured fiber interruption
Rate limiting	awaitly (createRateLimiter)	RateLimiter
Circuit breaker	awaitly (createCircuitBreaker)	Not a dedicated first-class module in Effect core; typically built from primitives or handled by external infrastructure
Saga / compensation	awaitly/durable (createSagaWorkflow)	Not a dedicated first-class module in Effect core; typically built from primitives or handled by external infrastructure
Durable execution	awaitly/durable (durable)	Not a dedicated first-class module in Effect core; typically built from primitives or handled by external infrastructure
Human-in-the-loop	awaitly (approvals/hooks)	Not a dedicated first-class module in Effect core; typically built from primitives or handled by external infrastructure
Resource management	awaitly (step.withResource, scoped cleanup)	Scope (runtime-integrated)
Observability	onEvent workflow event stream → OTel at step boundaries	Runtime-integrated spans/tracing APIs (OTel export requires SDK setup)
Tagged errors	TaggedError with type + matching	Data.TaggedEnum / _tag

Step helpers

awaitly’s step helpers are deliberately small. The core helpers cover the 80%. Every other concern lives as an option on step itself.

awaitly	Effect equivalent
step('id', () => fetchUser(id))	yield* fetchUser(id) (unwrap + chain)
step('id', () => fn(value))	yield* fn(value) (chain)
if (!result.ok) ... at workflow boundary	Effect.match(program, { onSuccess, onFailure })
step.try('id', fn, { onError })	Effect.tryPromise({ try, catch })
step.all('name', { a, b })	Effect.all({ a, b })
step.map('id', items, mapper)	Effect.forEach(items, mapper)
step.race('name', op)	Effect.race(op)
step.sleep('id', ms)	Effect.sleep(ms)

Parallel named (all)

awaitly

// step.all(id, shape, opts?): named results, step tracking
const { user, posts } = await step.all('fetchAll', {
  user: () => fetchUser('1'),
  posts: () => fetchPosts('1'),
});

Effect

const { user, posts } = yield* Effect.all({
  user: fetchUser('1'),
  posts: fetchPosts('1'),
});

Map over array (map)

awaitly

// step.map(id, items, mapper, opts?): parallel, step tracking
const users = await step.map('fetchUsers', ['1', '2', '3'], (id) => fetchUser(id));

Effect

const users = yield* Effect.all(
  ['1', '2', '3'].map((id) => fetchUser(id))
);

Full step engine

These helpers are not thin wrappers: they emit step events, support retry/timeout options, and in createWorkflow use the cache and onAfterStep when you pass a key. See Steps: Effect-style ergonomics.

Result Types

Creating Results

awaitly

import { ok, err, type Result } from 'awaitly';

const divide = (a: number, b: number): Result<number, 'DIVIDE_BY_ZERO'> =>
  b === 0 ? err('DIVIDE_BY_ZERO') : ok(a / b);

const result = divide(10, 2);
if (result.ok) {
  console.log(result.value);
}
/*
Output:
5
*/

Effect

import { Effect } from 'effect';

const divide = (a: number, b: number) =>
  b === 0
    ? Effect.fail('DIVIDE_BY_ZERO' as const)
    : Effect.succeed(a / b);

// Must run through Effect runtime
const program = divide(10, 2);
Effect.runSync(program); // 5

Type Structure

awaitly Result:
         ┌─── Success value type
         │       ┌─── Error type
         ▼       ▼
Result<number, 'DIVIDE_BY_ZERO'>

Effect:
         ┌─── Success value
         │     ┌─── Error type
         │     │     ┌─── Requirements (dependencies)
         ▼     ▼     ▼
Effect<number, 'DIVIDE_BY_ZERO', never>

Note

Effect has a third type parameter for dependencies (Requirements). awaitly handles dependencies through createWorkflow, withDeps(workflow, overrides), and run(fn, { deps }) overrides. Effect provides different Layers at runtime.

Error Handling

Error Type Inference

awaitly (run)

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

const fetchUser = async (id: string): AsyncResult<User, 'NOT_FOUND'> => { /* ... */ };
const sendEmail = async (to: string): AsyncResult<void, 'EMAIL_FAILED'> => { /* ... */ };

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

const result = await run<User, Errors>(async ({ step }) => {
  const user = await step('fetchUser', () => fetchUser('1'));
  await step('sendEmail', () => sendEmail(user.email));
  return user;
});

// TypeScript knows: result.error is 'NOT_FOUND' | 'EMAIL_FAILED' | UnexpectedError

awaitly (workflow)

import { createWorkflow } from 'awaitly';

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

const result = await workflow.run(async ({ step, deps }) => {
  const user = await step('fetchUser', () => deps.fetchUser('1'));
  await step('sendEmail', () => deps.sendEmail(user.email));
  return user;
});

Effect

import { Effect, pipe } from 'effect';

const fetchUser = (id: string) =>
  id === '1'
    ? Effect.succeed({ id, email: 'user@example.com' })
    : Effect.fail('NOT_FOUND' as const);

const sendEmail = (to: string) =>
  to.includes('@')
    ? Effect.succeed(undefined)
    : Effect.fail('EMAIL_FAILED' as const);

// Must compose effects explicitly
const program = pipe(
  fetchUser('1'),
  Effect.flatMap(user =>
    pipe(
      sendEmail(user.email),
      Effect.map(() => user)
    )
  )
);

// TypeScript knows: E = 'NOT_FOUND' | 'EMAIL_FAILED'

Catching Errors

awaitly

const result = await workflow.run(async ({ step, deps }) => {
  const user = await step('fetchUser', () => deps.fetchUser('1'));
  return user;
});

if (!result.ok) {
  switch (result.error) {
    case 'NOT_FOUND':
      console.log('User not found');
      break;
    case 'EMAIL_FAILED':
      console.log('Email failed');
      break;
  }
}

Effect

import { Effect } from 'effect';

const handled = program.pipe(
  Effect.catchTag('NOT_FOUND', () =>
    Effect.succeed({ fallback: true })
  ),
  Effect.catchTag('EMAIL_FAILED', () =>
    Effect.succeed({ emailSkipped: true })
  )
);

Retry and Scheduling

awaitly uses retry policies while Effect uses Schedule combinators. Both achieve similar outcomes with different approaches.

Basic Retry

awaitly

const result = await workflow.run(async ({ step, deps }) => {
  const data = await step.retry(
    'fetchData',
    () => deps.fetchData(),
    {
      attempts: 3,
      backoff: 'exponential',
      initialDelay: 100,
    }
  );
  return data;
});
/*
Retry timeline (exponential, initialDelay 100ms):
Attempt 1:   immediate
Retry delay #1: 100ms  → Attempt 2
Retry delay #2: 200ms  → Attempt 3
*/

Effect

import { Effect, Schedule } from 'effect';

const policy = Schedule.exponential('100 millis').pipe(
  Schedule.compose(Schedule.recurs(3))
);

const program = fetchData.pipe(
  Effect.retry(policy)
);

Effect.runPromise(program);

Backoff Visualization

awaitly Exponential Retry Delays (initialDelay: 100)
────────────────────────────────────────────
Retry delay #1: 100ms   ████
Retry delay #2: 200ms   ████████
Retry delay #3: 400ms   ████████████████
Retry delay #4: 800ms   ████████████████████████████████

(Attempt 1 runs immediately; delays apply *before* each retry.)

With Timeout

awaitly

const result = await workflow.run(async ({ step, deps }) => {
  const data = await step.retry(
    'fetchData',
    () => step.withTimeout(
      'fetchData',
      () => deps.fetchData(),
      { ms: 5000 }
    ),
    { attempts: 3, backoff: 'exponential', initialDelay: 100 }
  );
  return data;
});

Effect

import { Effect, Schedule, Duration } from 'effect';

const policy = Schedule.exponential('100 millis').pipe(
  Schedule.compose(Schedule.recurs(3))
);

const program = fetchData.pipe(
  Effect.timeout(Duration.seconds(5)),
  Effect.retry(policy)
);

With Jitter

awaitly

const result = await step.retry(
  'fetchData',
  () => deps.fetchData(),
  {
    attempts: 5,
    backoff: 'exponential',
    initialDelay: 100,
    jitter: true, // Adds random variation
  }
);

Effect

const policy = Schedule.exponential('100 millis').pipe(
  Schedule.jittered,
  Schedule.compose(Schedule.recurs(5))
);

Rate Limiting

awaitly

import { createRateLimiter } from 'awaitly';

const limiter = createRateLimiter('api', {
  maxPerSecond: 2,
  burstCapacity: 5,
});

const result = await workflow.run(async ({ step, deps }) => {
  // Rate limit *when the step starts*
  const data = await limiter.execute(() => step('fetchData', () => deps.fetchData()));
  return data;
});

Effect

import { Effect, RateLimiter } from 'effect';

// fetchData: Effect<Data, Error, never>
const program = Effect.scoped(
  Effect.gen(function* (_) {
    const rateLimit = yield* _(
      RateLimiter.make({ limit: 2, interval: '1 seconds' })
    );
    return yield* _(rateLimit(fetchData));
  })
);

Note

Both libraries can rate limit by start-time. awaitly also includes a separate concurrency limiter (max in-flight + optional queue) via createConcurrencyLimiter.

Workflow Orchestration

Multi-step Workflows

awaitly

import { createWorkflow } from 'awaitly';

const workflow = createWorkflow('checkout', {
  fetchUser,
  validateOrder,
  chargeCard,
  sendConfirmation,
});

const result = await workflow.run(async ({ step, deps }) => {
  const user = await step('fetchUser', () => deps.fetchUser(userId));
  const order = await step('validateOrder', () => deps.validateOrder(orderData));
  const receipt = await step('chargeCard', () => deps.chargeCard(order.total));
  await step('sendConfirmation', () => deps.sendConfirmation(user.email, receipt));
  return { user, order, receipt };
});

Effect

import { Effect, pipe } from 'effect';

const program = pipe(
  fetchUser(userId),
  Effect.flatMap(user =>
    pipe(
      validateOrder(orderData),
      Effect.flatMap(order =>
        pipe(
          chargeCard(order.total),
          Effect.flatMap(receipt =>
            pipe(
              sendConfirmation(user.email, receipt),
              Effect.map(() => ({ user, order, receipt }))
            )
          )
        )
      )
    )
  )
);

// Or with Effect.gen (generator syntax)
const programGen = Effect.gen(function* () {
  const user = yield* fetchUser(userId);
  const order = yield* validateOrder(orderData);
  const receipt = yield* chargeCard(order.total);
  yield* sendConfirmation(user.email, receipt);
  return { user, order, receipt };
});

Parallel Operations

awaitly

// Effect-style: step.all, named results, step tracking
const result = await workflow.run(async ({ step, deps }) => {
  const { user, posts, comments } = await step.all('fetchAll', {
    user: () => deps.fetchUser('1'),
    posts: () => deps.fetchPosts('1'),
    comments: () => deps.fetchComments('1'),
  });
  return { user, posts, comments };
});

// Array form: step.all(name, () => allAsync([...]))

Effect

import { Effect } from 'effect';

const program = Effect.all({
  user: fetchUser('1'),
  posts: fetchPosts('1'),
  comments: fetchComments('1'),
});

Caching and Persistence

awaitly

// Option 1: In-memory (simple)
const workflow = createWorkflow('workflow', deps, {
  cache: new Map(),
  resumeState: savedState, // Resume from previous run
});

// Option 2: Store (awaitly-mongo or awaitly-postgres) — runWithState + save/loadResumeState
import { mongo } from 'awaitly-mongo';
// or: import { postgres } from 'awaitly-postgres';

const store = mongo(process.env.MONGODB_URI!);

const { result, resumeState } = await workflow.runWithState(async ({ step, deps }) => {
  const user = await step('fetchUser', () => deps.fetchUser('1'), { key: 'user:1' });
  return user;
});
await store.save('wf-1', resumeState);

// Restore: loadResumeState then run with resumeState
const loaded = await store.loadResumeState('wf-1');
if (loaded) {
  await workflow.run(async ({ step, deps }) => { /* same fn */ }, { resumeState: loaded });
}

Effect

import { Effect, Cache, Duration } from 'effect';

const cache = Cache.make({
  capacity: 100,
  timeToLive: Duration.minutes(5),
  lookup: (key: string) => fetchUser(key),
});

const program = Effect.gen(function* () {
  const c = yield* cache;
  return yield* c.get('1');
});

Combining Results

Both libraries provide ways to combine multiple Results/Effects.

All (Fail-Fast)

awaitly

import { allAsync } from 'awaitly';

// In a workflow: step.all (named) or step.map (array)
const { u1, u2, u3 } = await step.all('fetchUsers', {
  u1: () => fetchUser('1'),
  u2: () => fetchUser('2'),
  u3: () => fetchUser('3'),
});

// Standalone: allAsync
const users = await allAsync([
  fetchUser('1'),
  fetchUser('2'),
  fetchUser('3'),
]);
// { ok: true, value: [user1, user2, user3] } or first error

Effect

import { Effect } from 'effect';

const program = Effect.all([
  fetchUser('1'),
  fetchUser('2'),
  fetchUser('3'),
], { concurrency: 'unbounded' });
const result = await Effect.runPromise(program);

AllSettled (Collect All Errors)

awaitly

import { ok, err, allSettled, partition } from 'awaitly';

const results = [ok(1), err('A'), ok(3), err('B')];
const settled = allSettled(results);
/*
Output (any Err present → Err with all errors collected):
{
  ok: false,
  error: [{ error: 'A' }, { error: 'B' }]
}

If every Result is Ok, the success values are returned as an array:
{ ok: true, value: [1, 3] }

To keep both successes and failures, use `partition` instead.
*/

// Keep both successes and failures with partition:
const { values, errors } = partition(results);
// values: [1, 3], errors: ['A', 'B']

Effect

import { Effect } from 'effect';

// Use Effect.allSettled or partition
const program = Effect.forEach(
  [fetchUser('1'), fetchUser('2')],
  (effect) => Effect.either(effect)
);

// Returns array of Either<E, A>

Resource Management

Both libraries provide scoped resource management with automatic cleanup in LIFO order. Effect’s Scope is integrated into the runtime; awaitly’s withScope is explicit and library-level.

awaitly

import { withScope, createResource } from 'awaitly';

const dbResource = await createResource(
  () => new DatabaseClient().connect(),  // acquire
  (client) => client.disconnect()         // release
);

const result = await withScope(async (scope) => {
  const db = scope.add(dbResource);    // scope.add returns the value directly
  const cache = scope.add(
    await createResource(
      () => createCacheClient(db),
      (c) => c.disconnect()
    )
  );

  const users = await db.query('SELECT * FROM users');
  return ok(users);
});
// cleanup runs automatically: cache closed first, then db (LIFO)

// Cleanup errors are collected, not swallowed
if (!result.ok && isResourceCleanupError(result.error)) {
  console.log(result.error.errors);          // all cleanup failures
  console.log(result.error.originalResult);  // the actual result before cleanup failed
}

Effect

import { Effect, Scope } from 'effect';

const program = Effect.scoped(
  Effect.gen(function* () {
    const conn = yield* openConnection;
    const data = yield* query(conn, 'SELECT * FROM users');
    return data;
  }) // conn automatically closed when scope exits
);

Note

Both handle LIFO cleanup and nested scopes. Effect’s Scope is part of the runtime type system (R parameter). awaitly’s withScope is a standalone function that works with any async code; no runtime needed.

Streaming

Both libraries support streaming data processing.

awaitly

import { createWorkflow } from 'awaitly';
import { createMemoryStreamStore, getStreamReader, toAsyncIterable, collect } from 'awaitly/durable';

const streamStore = createMemoryStreamStore();
const workflow = createWorkflow('enrich', deps, { streamStore });

const result = await workflow.run(async ({ step }) => {
  const writer = step.getWritable<User>({ namespace: 'users' });

  for (const user of users) {
    const enriched = await step('enrich', () => enrichUser(user));
    await writer.write(enriched);
  }
  await writer.close();
});

// Consume the stream externally (outside the workflow)
const reader = getStreamReader<User>({
  store: streamStore,
  workflowId: 'enrich',
  namespace: 'users',
});

// Collect all items
const allUsers = await collect(reader);

// Or process one at a time
for await (const user of toAsyncIterable(reader)) {
  await processUser(user);
}

Effect

import { Stream, Effect } from 'effect';

// Effect has a full Stream module
const stream = Stream.fromIterable(fetchPaginatedUsers()).pipe(
  Stream.mapEffect((user) => enrichUser(user)),
  Stream.catchAll((e) => {
    console.error('Stream error:', e);
    return Stream.empty;
  })
);

// Run the stream
const result = await Effect.runPromise(
  Stream.runCollect(stream)
);

Tip

Effect’s Stream is more comprehensive (backpressure, chunking, advanced combinators). awaitly’s streaming is store-based with transformers (map, filter, chunk, collect) and works through step.getWritable / step.getReadable in workflows. Choose based on your complexity needs.

Functional Composition

Effect leans on pipe/flow to thread a value through combinators. awaitly deliberately has no pipe/flow: you compose Results with the plain combinator functions (map, andThen, mapError) or, more often, stay in async/await.

awaitly

import { ok, err, map, andThen, mapError, type Result } from 'awaitly';

// Compose with the Result combinators — plain function calls, no pipe()
const doubled = map(ok(5), (n) => n * 2);
const checked = andThen(doubled, (n) => (n > 5 ? ok(n) : err('TOO_SMALL')));
const result = mapError(checked, (e) => ({ code: e }));

// Wrap the sequence in a reusable function
const processNumber = (input: Result<number, never>) =>
  mapError(
    andThen(
      map(input, (n: number) => n * 2),
      (n) => (n > 5 ? ok(n) : err('TOO_SMALL')),
    ),
    (e) => ({ code: e }),
  );

const out = processNumber(ok(5));

Effect

import { pipe, flow, Effect } from 'effect';

// pipe: Apply functions left-to-right to a value
const result = pipe(
  Effect.succeed(5),
  Effect.map(n => n * 2),
  Effect.flatMap(n => n > 5 ? Effect.succeed(n) : Effect.fail('TOO_SMALL')),
  Effect.mapError(e => ({ code: e }))
);

// flow: Create a new function from composed functions
const processNumber = flow(
  Effect.map((n: number) => n * 2),
  Effect.flatMap(n => n > 5 ? Effect.succeed(n) : Effect.fail('TOO_SMALL')),
  Effect.mapError(e => ({ code: e }))
);

const result = processNumber(Effect.succeed(5));

Note

Effect’s functional toolkit is far more extensive (pipe, flow, identity, constVoid, absurd, etc.). awaitly intentionally ships none of them. It keeps a small set of Result combinators and leans on async/await + run() for sequencing, so there’s no combinator vocabulary to learn.

Tagged Errors

awaitly dispatches on .type; Effect uses _tag.

awaitly

import { TaggedError } from 'awaitly';

class NotFoundError extends TaggedError("NotFoundError")<{
  id: string;
  resource: string;
}> {}

class ValidationError extends TaggedError("ValidationError", {
  message: (p: { field: string }) => `Invalid ${p.field}`
}) {}

// Instances are real Error objects with instanceof support
const err = new NotFoundError({ id: '123', resource: 'User' });
err.type;            // "NotFoundError"
err instanceof Error; // true

// Exhaustive matching: compiler errors if you miss a case
type AppError = NotFoundError | ValidationError;
const msg = TaggedError.match(error as AppError, {
  NotFoundError: (e) => `Missing ${e.resource}: ${e.id}`,
  ValidationError: (e) => e.message,
});

Effect

import { Data, Effect, Match } from 'effect';

class NotFoundError extends Data.TaggedError("NotFoundError")<{
  id: string;
  resource: string;
}> {}

class ValidationError extends Data.TaggedError("ValidationError")<{
  field: string;
}> {}

// Pattern matching via catchTag in pipe
const handled = program.pipe(
  Effect.catchTag("NotFoundError", (e) =>
    Effect.succeed(`Missing ${e.resource}: ${e.id}`)
  ),
  Effect.catchTag("ValidationError", (e) =>
    Effect.succeed(`Invalid ${e.field}`)
  )
);

Note

awaitly’s TaggedError uses .type as the canonical discriminant (._tag is a deprecated alias). Effect uses _tag. awaitly adds instanceof support and a standalone match function that works outside of pipes.

Circuit Breaker

awaitly includes a circuit breaker. Effect doesn’t ship one as a core feature; you’d typically build it from primitives (Ref, Schedule) or use an ecosystem package.

awaitly

import { createCircuitBreaker } from 'awaitly';

const apiBreaker = createCircuitBreaker('external-api', {
  failureThreshold: 5,    // open after 5 failures
  resetTimeout: 30_000,   // try again after 30s
  halfOpenMax: 3,          // allow 3 test requests in half-open
});

const result = await workflow.run(async ({ step, deps }) => {
  const data = await apiBreaker.executeResult(
    () => step('fetchData', () => deps.fetchData())
  );
  return data;
});

// Check state programmatically
apiBreaker.getState();  // "CLOSED" | "OPEN" | "HALF_OPEN"
apiBreaker.getStats();  // { failures, successes, state, ... }

Effect

// No circuit breaker in core; typically built with Ref + Schedule:
import { Effect, Ref, Schedule } from 'effect';

// You'd need to build state tracking, threshold logic,
// half-open probing, and timeout reset manually using
// Effect primitives.

Circuit Breaker States
──────────────────────────────────────────────────────
  CLOSED ──(failures hit threshold)──► OPEN
     ▲                                   │
     │                          (resetTimeout expires)
     │                                   ▼
     └────(test requests pass)──── HALF_OPEN

Saga / Compensation

When a multi-step operation fails partway through, you need to undo the steps that already succeeded. awaitly ships a saga pattern that runs compensations in reverse order automatically. Effect doesn’t ship saga/compensation as a core feature; you’d compose it manually with acquireRelease or catchAll.

awaitly

import { createSagaWorkflow } from 'awaitly/durable';

const checkout = createSagaWorkflow('checkout', {
  reserveInventory, releaseInventory,
  chargeCard, refundPayment,
  sendEmail,
});

const result = await checkout.run(async ({ step, deps }) => {
  const reservation = await step(
    'reserve',
    () => deps.reserveInventory(items),
    { compensate: (res) => deps.releaseInventory(res.id) }
  );

  const payment = await step(
    'charge',
    () => deps.chargeCard(amount),
    { compensate: (p) => deps.refundPayment(p.txId) }
  );

  await step('notify', () => deps.sendEmail(userId));
  return { reservation, payment };
});

// If chargeCard fails:
//   1. releaseInventory runs automatically (reverse order)
//   2. result.ok === false
// If a compensation itself fails, errors are collected:
if (!result.ok && isSagaCompensationError(result.error)) {
  result.error.originalError;       // what triggered the rollback
  result.error.compensationErrors;  // which cleanups failed
}

Effect

import { Effect } from 'effect';

// No saga in core; compose manually with acquireRelease or catchAll:
const program = Effect.gen(function* () {
  const reservation = yield* reserveInventory(items);

  const payment = yield* chargeCard(amount).pipe(
    Effect.catchAll((e) =>
      releaseInventory(reservation.id).pipe(
        Effect.flatMap(() => Effect.fail(e))
      )
    )
  );

  yield* sendEmail(userId).pipe(
    Effect.catchAll((e) =>
      refundPayment(payment.txId).pipe(
        Effect.flatMap(() => releaseInventory(reservation.id)),
        Effect.flatMap(() => Effect.fail(e))
      )
    )
  );

  return { reservation, payment };
});

Note

Manual compensation can become verbose as steps grow. Each new step needs to undo all previous ones. awaitly’s saga helper tracks compensations and runs them in reverse automatically.

Durable Execution

awaitly can checkpoint workflow state after each keyed step, so if the process crashes, the workflow resumes from the last completed step instead of re-running everything.

awaitly

import { durable } from 'awaitly/durable';

const result = await durable.run(
  { fetchUser, createOrder, sendEmail },
  async ({ step, deps }) => {
    // Each keyed step is checkpointed; if the process crashes
    // after 'createOrder', it won't re-run 'fetchUser' on resume
    const user = await step('fetchUser', () => deps.fetchUser('123'), { key: 'user' });
    const order = await step('createOrder', () => deps.createOrder(user), { key: 'order' });
    await step('sendEmail', () => deps.sendEmail(order), { key: 'email' });
    return order;
  },
  {
    id: 'checkout-123',
    store,           // awaitly-postgres or awaitly-mongo
    version: 1,      // bump when workflow logic changes
  }
);

// Query pending workflows
const pending = await durable.listPending(store);
// Clean up old state
await durable.deleteState(store, 'checkout-123');

Effect

// Effect doesn't ship durable execution as a core feature; you'd typically
// pair it with an external orchestrator (Temporal, Inngest, etc.) or
// build persistence around your programs.

Note

Durable execution also handles version mismatches (when you deploy new workflow logic) and concurrent execution guards (prevents two processes from running the same workflow ID simultaneously).

Human-in-the-Loop

awaitly can pause a workflow mid-execution to wait for a human approval, then resume from where it left off.

awaitly

import { createHITLOrchestrator, createMemoryApprovalStore, createMemoryWorkflowStateStore } from 'awaitly/durable';

const orchestrator = createHITLOrchestrator({
  approvalStore: createMemoryApprovalStore(),
  workflowStateStore: createMemoryWorkflowStateStore(),
  notificationChannel: slackNotifier, // optional: notify reviewers
});

// Start workflow: it pauses when it hits an approval gate
const execution = await orchestrator.execute(
  'large-refund',
  workflowFactory,
  async ({ step, deps, args }) => {
    const refund = await step('calculate', () => deps.calculateRefund(args.orderId));
    // Workflow pauses here until approved
    await step('approve', () => deps.requireApproval(refund), { key: `refund:${refund.id}` });
    await step('process', () => deps.processRefund(refund));
    return refund;
  },
  { orderId: '456' }
);

// `runId` only exists on the paused/resumed arms, so narrow before using it.
if (execution.status === 'paused') {
  console.log('Waiting for:', execution.pendingApprovals);

  // Later: manager approves via API/webhook
  await orchestrator.grantApproval('refund:789', { approvedBy: 'manager@co.com' });
  const resumed = await orchestrator.resume(execution.runId, workflowFactory, fn);
}

Effect

// Effect doesn't ship human-in-the-loop as a core feature; you'd typically
// build it with Effect + an external queue (SQS, Redis, database polling)
// and manual state persistence.

Observability

awaitly

import { init } from 'autotel';
import { createWorkflow } from 'awaitly';

init({ service: 'checkout-api' });

const workflow = createWorkflow('checkout', deps);

const result = await workflow.run(async ({ step, deps }) => {
  const user = await step('fetch-user', () => deps.fetchUser('1'));
  return step('charge', () => deps.charge(user));
});

// awaitly creates run, step, retry, scope, and compensation spans.

Effect

import * as NodeSdk from '@effect/opentelemetry/NodeSdk';
import { Effect } from 'effect';

const program = Effect.gen(function* () {
  const user = yield* fetchUser('1');
  return user;
}).pipe(
  Effect.withSpan('fetchUser')
);

// Provide the OpenTelemetry layer, then run the Effect program.
const OtelLive = NodeSdk.layer(() => sdkConfig);
const runnable = program.pipe(Effect.provide(OtelLive));
await Effect.runPromise(runnable);

Note

Effect lets any Effect become a span and propagates context through fibers. Its OpenTelemetry package bridges the Effect tracer, metrics, and logger through a Layer. awaitly instruments its orchestration boundaries automatically through the global OpenTelemetry API. A configured provider and a registered ContextManager are enough; there is no awaitly adapter or alternate runner. Custom metrics and logs still use onEvent, which keeps the small run bundle free of metric and log SDK code.

When to Choose Each

The migration question

If you rely heavily on scoped resources and structured concurrency: Effect remains the better tool. Fibers, Scope, and interruption are built in; awaitly doesn’t model that level of lifecycle.

If your team finds the runtime and abstraction surface too heavy. awaitly offers a simpler mental model: same async/await, typed errors in the return type, deps passed as values. No generators, no Layer graph.

Both get you typed errors and composition. The trade-off is runtime power and type-level architecture (Effect) against application-level simplicity (awaitly).

Choose awaitly when:

• Your team knows async/await and you want typed errors without learning a new paradigm
• You need workflow features like sagas, durable execution, circuit breakers, or human-in-the-loop
• You want automatic error type inference from your dependencies
• Bundle footprint matters (awaitly has a smaller baseline; both grow depending on which modules you use)
• You want to adopt incrementally: start with ok/err in one function, add workflows later

Choose Effect when:

• You want a full functional programming system with fibers and structured concurrency
• You need the Layer system for complex dependency injection graphs
• You want composable Schedule types for advanced retry/repeat logic
• Your team is comfortable with generators and functional composition
• You want Effect’s extensive standard library (Schema, Stream, STM, etc.)

What Effect has that awaitly doesn’t

• Fibers: Lightweight threads with structured concurrency, interruption, and forking. awaitly uses native Promises.
• Layer system: Compile-time verified dependency graphs. awaitly’s DI is simpler: deps are passed to createWorkflow.
• Schedule combinators: Composable scheduling algebra. awaitly uses config objects ({ attempts: 3, backoff: 'exponential' }).
• STM: Software transactional memory. awaitly doesn’t have an equivalent.
• Schema: Runtime validation library. awaitly doesn’t include one (use Zod, Valibot, etc.).

What awaitly provides as first-class modules

• Circuit breaker: CLOSED/OPEN/HALF_OPEN states, presets.
• Saga / compensation: Reverse-order rollback on failure.
• Durable execution: Checkpoint and resume across restarts.
• Human-in-the-loop: Pause and resume via approval store.
• Automatic error inference: Inferred union from deps; no manual wiring.

Effect encodes architecture in types; awaitly keeps it in values.

Next Steps

• Getting Started with awaitly →
• Workflows in depth →
• Retries & Timeouts →
• Resource Management →
• Durable Execution →
• Human-in-the-Loop →