Effect.sync — safe synchronous work

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<number, never, never>
4
//      ▼
5
const now = Effect.sync(() => Date.now())

Use Effect.sync when the work is synchronous and cannot throw under any input you’ll feed it: reading Date.now(), generating a UUID, computing a derived value, pushing to a local buffer. The E channel stays never because there is no way for the captured function to fail.

Rule of thumb. sync is for local work the JavaScript runtime can’t fail at. The moment a library call is involved, ask: “does its documentation promise no throw under my inputs?” If not, use try.

Your turn wrap the `() => { read++; return 42 }` thunk in `Effect.sync(...)` so the side effect only fires when `runSync` walks the description. The test asserts `read === 0` before the runner and `read === 1` after — proof the constructor captured the work without firing it.

Effect.try — synchronous work that may throw

1
import { Effect, Data } from "effect"
2

3
class ParseError extends Data.TaggedError("ParseError")<{
4
  readonly cause: unknown
5
}> {}
6

7
//      ┌─── Effect<unknown, ParseError, never>
8
//      ▼
9
const parse = (input: string) =>
10
  Effect.try({
11
    try: () => JSON.parse(input),
12
    catch: (cause) => new ParseError({ cause }),
13
  })

Use Effect.try when the synchronous work can throw (JSON.parse, new URL, a third-party library that throws on bad input). The catch callback converts the thrown value — unknown — into a typed error you put in the E channel.

Your turn wrap `JSON.parse` so its `SyntaxError` becomes a typed `ParseError`.

Effect.promise — safe asynchronous work

1
import { Effect } from "effect"
2

3
//      ┌─── Effect<string, never, never>
4
//      ▼
5
const readBody = (response: Response) =>
6
  Effect.promise(() => response.text())

Use Effect.promise when the work returns a Promise that you have a guarantee will not reject — e.g., a stream you know is exhausted, a library call documented as infallible, or a Promise.resolve you produced. The E channel stays never.

Warning: if the promise does reject, the rejection becomes a defect (an unrecoverable failure, see step 48 Cause & Sandbox), not an E error. If you are not certain the promise will resolve, use tryPromise instead.

Your turn lift a known-safe promise into an Effect.

Effect.tryPromise — asynchronous work that may reject

1
import { Effect, Data } from "effect"
2

3
class FetchError extends Data.TaggedError("FetchError")<{
4
  readonly cause: unknown
5
}> {}
6

7
//      ┌─── Effect<Response, FetchError, never>
8
//      ▼
9
const fetchUrl = (url: string) =>
10
  Effect.tryPromise({
11
    try: () => fetch(url),
12
    catch: (cause) => new FetchError({ cause }),
13
  })

Use Effect.tryPromise for the realistic case: an async operation that may reject (network calls, file I/O, database queries). The catch callback converts the rejection — also unknown — into a typed E error.

Your turn wrap a function that returns a rejecting promise and confirm the typed error appears in `E`.

The wrong-constructor mistake

1
// ❌ Bug — sync wraps a function that throws. The throw becomes a defect, not
2
//    an E-channel value. catchTag won't see it.
3
const bad = Effect.sync(() => JSON.parse("{bad json"))
4

5
// ✅ Fix — try captures the throw into the typed E channel.
6
const good = Effect.try({
7
  try: () => JSON.parse("{bad json"),
8
  catch: (cause) => new ParseError({ cause }),
9
})

Effect.sync and Effect.promise declare “this will not fail” — the type system stamps E = never. If the wrapped code does fail, the failure escapes the E channel and becomes a defect, which is much harder to recover from.

The try variants exist to keep that contract honest.

Your turn observe a failed `Effect.sync` producing a defect (the `Exit` reports a `Die`, not a `Fail`), then rewrite it with `Effect.try` and confirm the error surfaces in `E` as a typed `ParseError`.