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 is closer to 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 closer to application-level orchestration. 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: a small model for async workflows, typed errors, and value-level dependencies — without a custom 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 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 } from 'awaitly';
import { run } from 'awaitly/run';

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 (flow, 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 module-by-module.

Closest Equivalent to Effect.gen: flow()

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

See the dedicated guide: flow().

awaitly/flow

import { flow } from 'awaitly/flow';
import { 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 flow({ getUser, getPosts }, async (d) => {
  const user = await d.getUser('1');
  const posts = await d.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));

Optional: per-call escape hatch (c)

When you need a custom step id (e.g. calling the same dep twice) or a named parallel scope, flow() passes an optional second argument — the flow context — with c.key(id, fn), c.all(name, ops), and c.raw (the un-wrapped original deps). For richer control (per-call retry/timeout/cache, step.map, step.race, resume) drop down to run() / createWorkflow().

const result = await flow({ getUser, getPosts }, async (d, c) => {
  const user = await c.key('user:primary', () => c.raw.getUser('1'));

  const { posts, profile } = await c.all('fetchProfileBundle', {
    posts: () => c.raw.getPosts(user.id),
    profile: () => c.raw.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/ratelimit	RateLimiter
Circuit breaker	awaitly/circuit-breaker	Not a dedicated first-class module in Effect core; typically built from primitives or handled by external infrastructure
Saga / compensation	awaitly/saga	Not a dedicated first-class module in Effect core; typically built from primitives or handled by external infrastructure
Durable execution	awaitly/durable	Not a dedicated first-class module in Effect core; typically built from primitives or handled by external infrastructure
Human-in-the-loop	awaitly/hitl	Not a dedicated first-class module in Effect core; typically built from primitives or handled by external infrastructure
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

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 { 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, withDeps(workflow, overrides), and run(fn, { deps }) overrides. Effect provides different Layers at runtime.

Error Handling

Error Type Inference

awaitly (run)

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

// 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/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('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 { 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 (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 } = Awaitly.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 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 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 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, 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/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 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.

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 →