Error Management #

import { Effect, Exit } from "effect"

const cases = {
  fail: Effect.fail("user not found"),                                 // Effect<never, string>
  thrown: Effect.sync(() => { throw new TypeError("x is undefined") }), // Effect<never, never>: a bug
  die: Effect.die("unreachable state"),                                // Effect<never, never>: a bug on purpose
  interrupt: Effect.interrupt                                          // Effect<never, never>: cancelled
}

for (const [name, effect] of Object.entries(cases)) {
  const exit = Effect.runSyncExit(effect)
  if (Exit.isFailure(exit)) {
    // Every reason has a _tag: Fail, Die, or Interrupt
    console.log(name, "->", exit.cause.reasons.map((r) => r._tag).join(","))
  }
}

import { Cause, Data, Effect, Exit, Schema } from "effect"

// Preferred: schema-backed. _tag is "NotFound", filled in automatically.
class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
  id: Schema.Number
}) {}

// Lighter: plain fields, no schema.
class Forbidden extends Data.TaggedError("Forbidden")<{
  readonly id: number
  readonly role: string
}> {}

const users = new Map([
  [1, { name: "Ada", role: "admin" }],
  [2, { name: "Lin", role: "guest" }]
])

// Inferred: Effect<string, NotFound | Forbidden>. Both errors are in the type.
const loadName = (id: number) =>
  Effect.gen(function* () {
    const user = users.get(id)
    if (user === undefined) {
      return yield* new NotFound({ id })   // yield* an error instance to fail: a typed throw
    }
    if (user.role !== "admin") {
      return yield* new Forbidden({ id, role: user.role })
    }
    return user.name
  })

for (const id of [1, 2, 3]) {
  const exit = Effect.runSyncExit(loadName(id))
  if (Exit.isSuccess(exit)) {
    console.log(id, "ok", exit.value)
  } else {
    const error = Cause.squash(exit.cause) as NotFound | Forbidden
    // _tag narrows the union, so the right field is available in each branch
    console.log(id, error._tag, error._tag === "NotFound" ? "id " + error.id : "role " + error.role)
  }
}

import { Effect, Schema } from "effect"

class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { id: Schema.Number }) {}
class Forbidden extends Schema.TaggedError<Forbidden>()("Forbidden", { role: Schema.String }) {}
class Timeout extends Schema.TaggedError<Timeout>()("Timeout", { ms: Schema.Number }) {}

const loadName = (id: number): Effect.Effect<string, NotFound | Forbidden | Timeout> =>
  id === 1 ? Effect.succeed("Ada")
  : id === 2 ? Effect.fail(new Forbidden({ role: "guest" }))
  : id === 3 ? Effect.fail(new Timeout({ ms: 500 }))
  : Effect.fail(new NotFound({ id }))

// One tag handled. E shrinks to Forbidden | Timeout.
const step1 = (id: number): Effect.Effect<string, Forbidden | Timeout> =>
  loadName(id).pipe(
    Effect.catchTag("NotFound", (e) => Effect.succeed("nobody #" + e.id))
  )

// The remaining tags, one handler each. E shrinks to never.
const safeName = (id: number): Effect.Effect<string, never> =>
  step1(id).pipe(
    Effect.catchTags({
      Forbidden: (e) => Effect.succeed("hidden (" + e.role + ")"),
      Timeout: (e) => Effect.succeed("slow (" + e.ms + "ms)")
    })
  )

// Array form for a shared handler, then catch for whatever is left (only Timeout here).
const fallback = (id: number): Effect.Effect<string, never> =>
  loadName(id).pipe(
    Effect.catchTag(["NotFound", "Forbidden"], (e) => Effect.succeed("no access: " + e._tag)),
    Effect.catch((e) => Effect.succeed("other: " + e._tag))
  )

for (const id of [1, 2, 3, 4]) {
  console.log(id, Effect.runSync(safeName(id)), "|", Effect.runSync(fallback(id)))
}

import { Cause, Effect, Exit, Filter, Schema } from "effect"

class HttpError extends Schema.TaggedError<HttpError>()("HttpError", { status: Schema.Number }) {}
class ParseError extends Schema.TaggedError<ParseError>()("ParseError", { input: Schema.String }) {}
class AppError extends Schema.TaggedError<AppError>()("AppError", { message: Schema.String }) {}

const request = (status: number): Effect.Effect<string, HttpError | ParseError> =>
  status === 200 ? Effect.succeed("body")
  : status === 0 ? Effect.fail(new ParseError({ input: "<html>" }))
  : Effect.fail(new HttpError({ status }))

const load = (status: number): Effect.Effect<string, AppError> =>
  request(status).pipe(
    // 1. A plain predicate: recover only when the value says so. E does not shrink.
    Effect.catchIf(
      (e) => e._tag === "HttpError" && e.status >= 500,
      () => Effect.succeed("cached copy")
    ),
    // 2. A reusable Filter on the tag. ParseError leaves E here.
    Effect.catchFilter(
      Filter.tagged("ParseError"),
      (e) => Effect.succeed("empty (could not parse " + e.input + ")")
    ),
    // 3. Translate what is left (only HttpError now) into the domain error.
    Effect.mapError((e) => new AppError({ message: "request failed with " + e.status }))
  )

for (const status of [200, 503, 0, 404]) {
  const exit = Effect.runSyncExit(load(status))
  console.log(status, Exit.isSuccess(exit) ? exit.value : "AppError: " + (Cause.squash(exit.cause) as AppError).message)
}

import { Effect, Schema } from "effect"

class TooSmall extends Schema.TaggedError<TooSmall>()("TooSmall", { amount: Schema.Number }) {}
class AppError extends Schema.TaggedError<AppError>()("AppError", { message: Schema.String }) {}

// 1. filterOrFail: keep the value if the test passes, or fail with a typed error.
const checkAmount = (amount: number): Effect.Effect<number, TooSmall> =>
  Effect.succeed(amount).pipe(
    Effect.filterOrFail((n) => n >= 10, (n) => new TooSmall({ amount: n }))
  )

// 2. mapBoth: change both channels in one step. number -> string, TooSmall -> AppError.
const describe = (amount: number): Effect.Effect<string, AppError> =>
  checkAmount(amount).pipe(
    Effect.mapBoth({
      onFailure: (e) => new AppError({ message: "amount " + e.amount + " is too small" }),
      onSuccess: (n) => "accepted " + n
    })
  )

// 3. flip: the error becomes the success value. A test that expects a failure reads it directly.
const expectFailure = (amount: number): Effect.Effect<AppError, string> => Effect.flip(describe(amount))

// 4. firstSuccessOf: try the sources in order. The first success wins, and the rest do not run.
const fromCache = (key: string): Effect.Effect<string, string> =>
  key === "a" ? Effect.succeed("cache:" + key) : Effect.fail("cache miss")
const fromDb = (key: string): Effect.Effect<string, string> =>
  key === "b" ? Effect.succeed("db:" + key) : Effect.fail("db miss")
const lookup = (key: string) => Effect.firstSuccessOf([fromCache(key), fromDb(key), Effect.succeed("default")])

const program = Effect.gen(function* () {
  console.log(yield* describe(25))
  const error = yield* expectFailure(3)
  console.log("expected failure:", error.message)
  for (const key of ["a", "b", "c"]) {
    console.log(key, "->", yield* lookup(key))
  }
})

Effect.runSync(program)

import { Cause, Effect, Exit, Result, Schema } from "effect"

class Invalid extends Schema.TaggedError<Invalid>()("Invalid", { sku: Schema.String }) {}

const check = (sku: string): Effect.Effect<string, Invalid> =>
  sku.startsWith("sku-") ? Effect.succeed(sku.toUpperCase()) : Effect.fail(new Invalid({ sku }))

const skus = ["sku-1", "bad-2", "sku-3", "bad-4"]

const program = Effect.gen(function* () {
  // 1. forEach stops at the first failure. sku-3 and bad-4 never run.
  const first = yield* Effect.result(Effect.forEach(skus, check))
  console.log("forEach:", Result.isFailure(first) ? "stopped at " + first.failure.sku : "all ok")

  // 2. partition runs every element and never fails. Failures on the left, successes on the right.
  const [failed, ok] = yield* Effect.partition(skus, check)
  console.log("partition:", failed.map((e) => e.sku).join(","), "|", ok.join(","))

  // 3. validate runs every element. It fails with every error in a non-empty array.
  const validated = yield* Effect.result(Effect.validate(skus, check))
  console.log("validate:", Result.isFailure(validated) ? validated.failure.length + " errors" : "all ok")

  // 4. all with mode "result": every entry is a Result, with the same keys as the input.
  const results = yield* Effect.all({ a: check("sku-1"), b: check("bad-2") }, { mode: "result" })
  console.log("all result:", results.a._tag, results.b._tag)

  // 5. forEach with Effect.result: one Result per element, in input order, also with concurrency.
  const each = yield* Effect.forEach(skus, (sku) => Effect.result(check(sku)), { concurrency: "unbounded" })
  console.log("forEach+result:", each.map((r) => (Result.isSuccess(r) ? "ok" : "fail")).join(","))

  // 6. all without mode: the first failure wins, also with concurrency. The cause has 1 reason.
  const exit = yield* Effect.exit(Effect.all([check("bad-2"), check("bad-4")], { concurrency: "unbounded" }))
  if (Exit.isFailure(exit)) {
    console.log("all cause:", exit.cause.reasons.length, "reason,", (Cause.squash(exit.cause) as Invalid).sku)
  }
})

Effect.runSync(program)

import { Effect, Option, Result, Schema } from "effect"

class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { key: Schema.String }) {}

const settings = new Map([["theme", "dark"]])
const get = (key: string): Effect.Effect<string, NotFound> => {
  const value = settings.get(key)
  return value === undefined ? Effect.fail(new NotFound({ key })) : Effect.succeed(value)
}

const program = Effect.gen(function* () {
  // A default value. Effect<string, never>
  const lang = yield* get("lang").pipe(Effect.orElseSucceed(() => "en"))
  console.log("lang:", lang)

  // One plain function per outcome
  const theme = yield* get("theme").pipe(Effect.match({
    onFailure: (e) => "missing " + e.key,
    onSuccess: (v) => "theme is " + v
  }))
  console.log(theme)

  // Same shape, but each handler is an Effect
  yield* get("font").pipe(Effect.matchEffect({
    onFailure: (e) => Effect.sync(() => console.log("no", e.key, "setting, using default")),
    onSuccess: (v) => Effect.sync(() => console.log("font is", v))
  }))

  // Both outcomes as data. Effect<Result<string, NotFound>, never>
  const r = yield* Effect.result(get("lang"))
  console.log("result:", Result.isSuccess(r) ? r.success : "failed with " + r.failure._tag)

  // Only "did it work". The error is thrown away. Effect<Option<string>, never>
  const o = yield* Effect.option(get("theme"))
  console.log("option:", Option.isSome(o) ? o.value : "none")

  // Do not care at all. Effect<void, never>
  yield* Effect.ignore(get("lang"))
  console.log("still running")
})

Effect.runSync(program)

import { Cause, Effect, Exit } from "effect"

// Bug: crashes for unknown ids. The thrown TypeError becomes a defect.
const findName = (id: number) =>
  Effect.sync(() => {
    const rows = [{ id: 1, name: "Ada" }]
    return rows.find((r) => r.id === id)!.name
  })

// 1. catch cannot see it. E is never, so this handler never runs.
const naive = findName(2).pipe(Effect.catch(() => Effect.succeed("fallback")))
const exit = Effect.runSyncExit(naive)
console.log("naive:", Exit.isFailure(exit) ? exit.cause.reasons.map((r) => r._tag).join(",") : "recovered")

// 2. catchDefect sees only defects, as unknown.
const guarded = findName(2).pipe(
  Effect.catchDefect((defect) =>
    Effect.succeed(defect instanceof TypeError ? "recovered from a TypeError" : "recovered")
  )
)
console.log("guarded:", Effect.runSync(guarded))

// 3. catchCause sees everything, and Cause.pretty describes it.
const reported = Effect.die(new Error("unreachable: cart already paid")).pipe(
  Effect.catchCause((cause) =>
    Effect.sync(() => {
      console.log("report:", Cause.pretty(cause).split("\n")[0])   // first line; the rest is a stack trace
      return "recovered"
    })
  )
)
console.log("reported:", Effect.runSync(reported))

import { Effect, Schema } from "effect"

class CardDeclined extends Schema.TaggedError<CardDeclined>()("CardDeclined", { code: Schema.String }) {}
class InsufficientFunds extends Schema.TaggedError<InsufficientFunds>()("InsufficientFunds", { missing: Schema.Number }) {}
class GatewayDown extends Schema.TaggedError<GatewayDown>()("GatewayDown", { retryAfter: Schema.Number }) {}

// One error for the payment step. The reason says why.
class PaymentError extends Schema.TaggedError<PaymentError>()("PaymentError", {
  reason: Schema.Union([CardDeclined, InsufficientFunds, GatewayDown])
}) {}

const pay = (amount: number): Effect.Effect<string, PaymentError> =>
  amount <= 50 ? Effect.succeed("paid " + amount)
  : amount <= 100 ? Effect.fail(new PaymentError({ reason: new InsufficientFunds({ missing: amount - 50 }) }))
  : amount <= 500 ? Effect.fail(new PaymentError({ reason: new CardDeclined({ code: "51" }) }))
  : Effect.fail(new PaymentError({ reason: new GatewayDown({ retryAfter: 30 }) }))

// One reason. E is still PaymentError, because the other reasons can happen.
const one = (amount: number): Effect.Effect<string, PaymentError> =>
  pay(amount).pipe(
    Effect.catchReason("PaymentError", "InsufficientFunds", (r) => Effect.succeed("top up " + r.missing))
  )

// Several reasons plus a catch-all for the rest. E is never.
const many = (amount: number): Effect.Effect<string, never> =>
  pay(amount).pipe(
    Effect.catchReasons("PaymentError", {
      InsufficientFunds: (r) => Effect.succeed("top up " + r.missing),
      CardDeclined: (r) => Effect.succeed("declined, code " + r.code)
    }, (r) => Effect.succeed("later: " + r._tag))
  )

// The reasons become the error. E is CardDeclined | InsufficientFunds after catchTag.
const unwrapped = (amount: number): Effect.Effect<string, CardDeclined | InsufficientFunds> =>
  pay(amount).pipe(
    Effect.unwrapReason("PaymentError"),
    Effect.catchTag("GatewayDown", (r) => Effect.succeed("retry in " + r.retryAfter + "s"))
  )

for (const amount of [40, 80, 300, 900]) {
  console.log(amount, "->", Effect.runSync(many(amount)))
}
console.log("one(80):", Effect.runSync(one(80)))
console.log("unwrapped(900):", Effect.runSync(unwrapped(900)))

import { Effect } from "effect"

const program = Effect.fail("boom").pipe(
  Effect.catchAll((e) => Effect.succeed("recovered: " + e))
)

console.log(Effect.runSync(program))

import { Effect, Schema } from "effect"

class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { id: Schema.Number }) {}

const loadUser = (id: number): Effect.Effect<string, NotFound> =>
  id === 1 ? Effect.succeed("Ada") : Effect.fail(new NotFound({ id }))

const program = loadUser(7).pipe(
  Effect.catchTag("UserNotFound", (e) => Effect.succeed("missing user " + e.id))
)

console.log(Effect.runSync(program))

import { Effect, Schema } from "effect"

class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { id: Schema.Number }) {}
class Forbidden extends Schema.TaggedError<Forbidden>()("Forbidden", { role: Schema.String }) {}

const loadName = (id: number): Effect.Effect<string, NotFound | Forbidden> =>
  id === 1 ? Effect.succeed("Ada")
  : id === 2 ? Effect.fail(new Forbidden({ role: "guest" }))
  : Effect.fail(new NotFound({ id }))

const safeName = (id: number): Effect.Effect<string, never> =>
  loadName(id).pipe(
    Effect.catchTag("NotFound", (e) => Effect.succeed("nobody #" + e.id))
  )

console.log(Effect.runSync(safeName(1)))
console.log(Effect.runSync(safeName(3)))

import { Effect } from "effect"

const parseCount = (raw: string) =>
  Effect.sync(() => {
    const n = Number(raw)
    if (Number.isNaN(n)) throw new Error("not a number: " + raw)
    return n
  })

const program = parseCount("abc").pipe(
  Effect.catch(() => Effect.succeed(0)),
  Effect.map((n) => "count: " + n + (n === 0 ? " (fallback)" : ""))
)

console.log(Effect.runSync(program))

import { Effect, Schema } from "effect"

class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { id: Schema.Number }) {}

const users = new Map([[1, "Ada"]])

const loadName = (id: number) =>
  Effect.gen(function* () {
    const name = users.get(id)
    if (name === undefined) throw new NotFound({ id })
    return name
  })

const describe = (id: number) =>
  loadName(id).pipe(
    Effect.catchTag("NotFound", (e) => Effect.succeed("no user with id " + e.id))
  )

console.log(Effect.runSync(describe(1)))
console.log(Effect.runSync(describe(2)))

import { Effect, Schema } from "effect"

class ConfigError extends Schema.TaggedError<ConfigError>()("ConfigError", { message: Schema.String }) {}

// A low-level helper you do not own. It fails with a string.
const readFile = (path: string): Effect.Effect<string, string> =>
  path === "app.json" ? Effect.succeed('{"port":8080}') : Effect.fail("ENOENT " + path)

// The domain function. Callers should only ever see ConfigError.
const loadConfig = (path: string): Effect.Effect<string, ConfigError> =>
  readFile(path)

const program = Effect.gen(function* () {
  const raw = yield* loadConfig("app.json")
  console.log("loaded", raw)
  const fallback = yield* loadConfig("missing.json").pipe(Effect.catch(() => Effect.succeed("{}")))
  console.log("fallback", fallback)
})

Effect.runSync(program)

import { Effect, Schema } from "effect"

class Invalid extends Schema.TaggedError<Invalid>()("Invalid", { field: Schema.String }) {}

const form: Record<string, string> = { name: "", email: "ada@example.com", age: "" }

const check = (field: string): Effect.Effect<string, Invalid> =>
  form[field] === "" ? Effect.fail(new Invalid({ field })) : Effect.succeed(form[field] ?? "")

const report = Effect.forEach(["name", "email", "age"], check).pipe(
  Effect.map(() => "form is valid"),
  Effect.catch((e) => Effect.succeed("invalid: " + e.field))
)

console.log(Effect.runSync(report))

import { Effect, Exit, Schema } from "effect"

class TooSmall extends Schema.TaggedError<TooSmall>()("TooSmall", { amount: Schema.Number }) {}

const checkAmount = (amount: number): Effect.Effect<number, TooSmall> =>
  Effect.succeed(amount).pipe(
    Effect.filterOrFail((n) => n >= 10)
  )

for (const amount of [25, 3]) {
  const exit = Effect.runSyncExit(checkAmount(amount))
  console.log(amount, Exit.isSuccess(exit) ? "accepted" : "rejected")
}

import { Effect, Schema } from "effect"

class RateLimited extends Schema.TaggedError<RateLimited>()("RateLimited", { retryAfter: Schema.Number }) {}
class Unauthorized extends Schema.TaggedError<Unauthorized>()("Unauthorized", { scope: Schema.String }) {}
class ApiError extends Schema.TaggedError<ApiError>()("ApiError", {
  reason: Schema.Union([RateLimited, Unauthorized])
}) {}

const call = (n: number): Effect.Effect<string, ApiError> =>
  n === 1 ? Effect.succeed("200 OK")
  : n === 2 ? Effect.fail(new ApiError({ reason: new RateLimited({ retryAfter: 30 }) }))
  : Effect.fail(new ApiError({ reason: new Unauthorized({ scope: "orders:read" }) }))

const describe = (n: number): Effect.Effect<string, never> =>
  call(n).pipe(
    Effect.catchTags({
      RateLimited: (r) => Effect.succeed("wait " + r.retryAfter + "s"),
      Unauthorized: (r) => Effect.succeed("need scope " + r.scope)
    })
  )

for (const n of [1, 2, 3]) console.log(Effect.runSync(describe(n)))

import { Effect, Option, Schema } from "effect"

class NotFound extends Schema.TaggedError<NotFound>()("NotFound", { key: Schema.String }) {}

const settings = new Map([["theme", "dark"]])
const get = (key: string): Effect.Effect<string, NotFound> => {
  const value = settings.get(key)
  return value === undefined ? Effect.fail(new NotFound({ key })) : Effect.succeed(value)
}

const report = (key: string) =>
  Effect.gen(function* () {
    const outcome = yield* Effect.option(get(key))
    console.log(key + ": " + (Option.isSome(outcome) ? outcome.value : "failed"))
  })

Effect.runSync(report("theme"))
Effect.runSync(report("lang"))