constructor-sync-async.mdx

title	Creating from Synchronous and Callback Code
id	constructor-sync-async
skillLevel	beginner
applicationPatternId	core-concepts
summary	Use sync and async to lift synchronous or callback-based computations into Effect, enabling safe and composable interop with legacy code.
tags	sync async constructor effect interop callback legacy
rule	description Use sync and async to create Effects from synchronous or callback-based computations, making them composable and type-safe.
related	constructor-try-trypromise constructor-succeed-some-right
author	PaulJPhilp
lessonOrder	10

Creating from Synchronous and Callback Code

Guideline

Use the sync and async constructors to lift synchronous or callback-based computations into the Effect world.
This enables safe, composable interop with legacy or third-party code that doesn't use Promises or Effects.

Rationale

Many APIs are synchronous or use callbacks instead of Promises.
By lifting them into Effects, you gain access to all of Effect's combinators, error handling, and resource safety.

Good Example

import { Effect } from "effect";

// Synchronous: Wrap a computation that is guaranteed not to throw
const effectSync = Effect.sync(() => Math.random()); // Effect<never, number, never>

// Callback-based: Wrap a Node.js-style callback API
function legacyReadFile(
  path: string,
  cb: (err: Error | null, data?: string) => void
) {
  setTimeout(() => cb(null, "file contents"), 10);
}

const effectAsync = Effect.async<string, Error>((resume) => {
  legacyReadFile("file.txt", (err, data) => {
    if (err) resume(Effect.fail(err));
    else resume(Effect.succeed(data!));
  });
}); // Effect<string, Error, never>

Explanation:

• Effect.sync is for synchronous computations that are guaranteed not to throw.
• Effect.async is for integrating callback-based APIs, converting them into Effects.

Anti-Pattern

Directly calling synchronous or callback-based APIs inside Effects without lifting them, which can break composability and error handling.