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).

The Abstraction-Level Difference

Effect is infrastructure-level. It’s a full effect runtime with a capability-tracking type system: fibers, Scope, Layers, Schedule algebra. You get a runtime that manages effects — concurrency, interruption, resource lifecycles — and the type system encodes that architecture.

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

That’s not “Effect minus runtime” — it’s a different layer of the stack. awaitly is a deliberately minimal computation model for TypeScript applications: one type for async + errors + environment, without a runtime. Effect is the tool when you want the 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 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.

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); override per run via workflow.run(fn, { deps })	Layers (Context-based DI)
Retry / scheduling	Config objects	Schedule combinators
Concurrency	Promise.all / step.all	Fibers
Rate limiting	awaitly/ratelimit	RateLimiter
Circuit breaker	awaitly/circuit-breaker	Not shipped as a core feature; built from primitives or ecosystem packages
Saga / compensation	awaitly/saga	Not shipped as a core feature; built from primitives or ecosystem packages
Durable execution	awaitly/durable	Not shipped as a core feature; built from primitives or ecosystem packages
Human-in-the-loop	awaitly/hitl	Not shipped as a core feature; built from primitives or ecosystem packages
Resource management	awaitly/resource (scoped cleanup)	Scope (runtime-integrated)
Observability	Event-to-OTel adapter at step boundaries	Runtime-integrated spans/tracing APIs (OTel export requires SDK setup)
Tagged errors	TaggedError with _tag + matching	Data.TaggedEnum / _tag

Effect-style step helpers

awaitly’s step helpers are aligned with Effect’s API so the surface feels familiar to Effect users: as close as we can get while still using async/await and not generators. They run through the full step engine (events, retry, timeout, and in createWorkflow: cache and onAfterStep).

Unwrap (run)

awaitly

// step.run(id, result, opts?): unwraps AsyncResult, exits on error
const user = await step.run('fetchUser', () => fetchUser('1'), { key: 'user:1' });

Effect

const user = yield* fetchUser('1');

Chain (flatMap / andThen)

awaitly

// step.andThen(id, value, fn, opts?)
const enriched = await step.andThen('enrich', user, (u) => enrichUser(u));

Effect

const enriched = yield* enrichUser(user);

Pattern match (match)

awaitly

// step.match(id, result, { ok, err }, opts?): step-tracked
const msg = await step.match('handleUser', userResult, {
  ok: (user) => `Hello ${user.name}`,
  err: () => 'Failed',
});

Effect

const msg = yield* Effect.match(userResult, {
  onSuccess: (user) => `Hello ${user.name}`,
  onFailure: () => 'Failed',
});

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 { Awaitly, type Result } from 'awaitly';

const divide = (a: number, b: number): Result<number, 'DIVIDE_BY_ZERO'> =>
  b === 0 ? Awaitly.err('DIVIDE_BY_ZERO') : Awaitly.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; you can override deps per run with run(fn, { deps }). Effect provides different Layers at runtime.

Error Handling

Error Type Inference

awaitly

import { createWorkflow } from 'awaitly/workflow';

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

// Error types automatically inferred from dependencies
const workflow = createWorkflow('workflow', { fetchUser, sendEmail });

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

// TypeScript knows: result.error is 'NOT_FOUND' | 'EMAIL_FAILED' | UnexpectedError
// step.run unwraps AsyncResult; use step('id', fn) or step.run with a getter when caching

Effect

import { Effect, pipe } from 'effect';

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

const sendEmail = (to: string) =>
  Effect.fail('EMAIL_FAILED' as const).pipe(
    Effect.map(() => undefined)
  );

// 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',
      delayMs: 100,
    }
  );
  return data;
});
/*
Retry timeline:
Attempt 1: immediate
Attempt 2: after 100ms
Attempt 3: after 200ms
*/

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 Backoff (delayMs: 100)
────────────────────────────────────────────
#1: 100ms   ████
#2: 200ms   ████████
#3: 400ms   ████████████████
#4: 800ms   ████████████████████████████████

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', delayMs: 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',
    delayMs: 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/ratelimit';

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/workflow';

const workflow = createWorkflow('workflow', { 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 program = 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 };
});

// Or step('id', () => allAsync([...])) for array results

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 { Awaitly } 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 Awaitly.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 { Awaitly } from 'awaitly';

const results = [Awaitly.ok(1), Awaitly.err('A'), Awaitly.ok(3), Awaitly.err('B')];
const settled = Awaitly.allSettled(results);
/*
Output:
{
  ok: false,
  error: ['A', 'B'],
  successes: [1, 3],
  failures: ['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 deeply integrated with the runtime; awaitly’s withScope is explicit and library-level.

awaitly

import { withScope, createResource } from 'awaitly/resource';

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/workflow';
import { createMemoryStreamStore, getStreamReader, toAsyncIterable, collect } from 'awaitly/streaming';

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 powerful (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 Utilities

Both libraries provide functional composition utilities.

awaitly

import { Awaitly } from 'awaitly';

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

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

const result = processNumber(Awaitly.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

Both libraries use similar pipe and flow patterns. Effect’s functional utilities are more extensive (includes identity, constVoid, absurd, etc.). awaitly’s are focused on Result manipulation.

Tagged Errors

Both use a _tag discriminant for pattern matching on error types.

awaitly

import { TaggedError } from 'awaitly/tagged-error';

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._tag;       // "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

Both approaches give you _tag-based discrimination. awaitly’s TaggedError adds instanceof support and a standalone match function that works outside of pipes. Effect’s tagged errors are designed for use within the Effect pipe/generator ecosystem.

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/circuit-breaker';

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/saga';

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

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

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

  await saga.step('notify', () => 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

The manual Effect approach gets unwieldy as steps grow; each new step needs to compensate all previous ones. awaitly’s saga 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/hitl';

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' }
);

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 { createAutotelAdapter } from 'awaitly/otel';
import { createWorkflow } from 'awaitly/workflow';

const otel = createAutotelAdapter({
  serviceName: 'checkout',
  createStepSpans: true,
  recordMetrics: true,
});

const workflow = createWorkflow('checkout', deps, {
  onEvent: otel.handleEvent,  // plug into the event system
});

// After execution, inspect metrics
const metrics = otel.getMetrics();
metrics.stepDurations;   // [{ name, durationMs, success }]
metrics.retryCount;
metrics.errorCount;
metrics.cacheHits;

Effect

import { Effect } from 'effect';

// Effect has built-in tracing via spans
const program = Effect.gen(function* () {
  const user = yield* fetchUser('1');
  return user;
}).pipe(
  Effect.withSpan('fetchUser')
);

// Requires OpenTelemetry SDK setup for export

Note

Effect’s tracing is deeper: spans are part of the runtime and propagate automatically through fibers. awaitly’s approach is event-based: the workflow emits events, and the otel adapter translates them into spans and metrics. Simpler to set up, but you’re instrumenting at the step level rather than at every function call.

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.

Spell it out: both get you typed errors and composition; the trade-off is runtime power and type-level architecture (Effect) vs. 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 stays small; Effect is larger and scales with modules)
• 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.

Bottom line: Effect encodes architecture in types; awaitly keeps architecture in values.

Next Steps

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