Either

Either 数据类型表示两个互斥的值：Either<R, L> 可以是 Right 值或 Left 值，其中 R 是 Right 值的类型，L 是 Left 值的类型。

理解 Either 和 Exit

Either 主要用作简单的判别联合，不建议作为需要详细错误信息的操作的主要结果类型。

Exit 是 Effect 中首选的结果类型，用于捕获有关失败的全面详细信息。 它封装了有效计算的结果，区分成功和各种失败模式，例如错误、缺陷和中断。

创建 Eithers

您可以使用 Either.right 和 Either.left 构造函数创建 Either。

使用 Either.right 创建类型为 R 的 Right 值。

示例（创建 Right 值）

import { Either } from "effect"

const rightValue = Either.right(42)

console.log(rightValue)
/*
输出:
{ _id: 'Either', _tag: 'Right', right: 42 }
*/

使用 Either.left 创建类型为 L 的 Left 值。

示例（创建 Left 值）

import { Either } from "effect"

const leftValue = Either.left("not a number")

console.log(leftValue)
/*
输出:
{ _id: 'Either', _tag: 'Left', left: 'not a number' }
*/

守卫

使用 Either.isLeft 和 Either.isRight 检查 Either 是 Left 还是 Right 值。

示例（使用守卫检查 Either 的类型）

import { Either } from "effect"

const foo = Either.right(42)

if (Either.isLeft(foo)) {
  console.log(`Left 值是: ${foo.left}`)
} else {
  console.log(`Right 值是: ${foo.right}`)
}
// 输出: "Right 值是: 42"

模式匹配

使用 Either.match 通过为 Left 和 Right 指定单独的回调来处理 Either 的两种情况。

示例（使用 Either 进行模式匹配）

import { Either } from "effect"

const foo = Either.right(42)

const message = Either.match(foo, {
  onLeft: (left) => `Left 值是: ${left}`,
  onRight: (right) => `Right 值是: ${right}`
})

console.log(message)
// 输出: "Right 值是: 42"

映射

映射 Right 值

使用 Either.map 转换 Either 的 Right 值。您提供的函数只会应用于 Right 值，保持任何 Left 值不变。

示例（转换 Right 值）

import { Either } from "effect"

// 通过加 1 转换 Right 值
const rightResult = Either.map(Either.right(1), (n) => n + 1)
console.log(rightResult)
/*
输出:
{ _id: 'Either', _tag: 'Right', right: 2 }
*/

// 对于 Left 值，转换被忽略
const leftResult = Either.map(Either.left("not a number"), (n) => n + 1)
console.log(leftResult)
/*
输出:
{ _id: 'Either', _tag: 'Left', left: 'not a number' }
*/

映射 Left 值

使用 Either.mapLeft 转换 Either 的 Left 值。提供的函数只应用于 Left 值，保持任何 Right 值不变。

示例（转换 Left 值）

import { Either } from "effect"

// 对于 Right 值，转换被忽略
const rightResult = Either.mapLeft(Either.right(1), (s) => s + "!")
console.log(rightResult)
/*
输出:
{ _id: 'Either', _tag: 'Right', right: 1 }
*/

// 通过追加 "!" 转换 Left 值
const leftResult = Either.mapLeft(
  Either.left("not a number"),
  (s) => s + "!"
)
console.log(leftResult)
/*
输出:
{ _id: 'Either', _tag: 'Left', left: 'not a number!' }
*/

映射两个值

使用 Either.mapBoth 转换 Either 的 Left 和 Right 值。此函数接受两个单独的转换函数：一个用于 Left 值，另一个用于 Right 值。

示例（转换 Left 和 Right 值）

import { Either } from "effect"

const transformedRight = Either.mapBoth(Either.right(1), {
  onLeft: (s) => s + "!",
  onRight: (n) => n + 1
})
console.log(transformedRight)
/*
输出:
{ _id: 'Either', _tag: 'Right', right: 2 }
*/

const transformedLeft = Either.mapBoth(Either.left("not a number"), {
  onLeft: (s) => s + "!",
  onRight: (n) => n + 1
})
console.log(transformedLeft)
/*
输出:
{ _id: 'Either', _tag: 'Left', left: 'not a number!' }
*/

与 Effect 的互操作

Either 类型作为 Effect 类型的子类型工作，允许您将其与 Effect 模块中的函数一起使用。虽然这些函数是为处理 Effect 值而构建的，但它们也可以正确管理 Either 值。

Either 如何映射到 Effect

Either 变体	映射到 Effect	描述
Left<L>	Effect<never, L>	表示失败
Right<R>	Effect<R>	表示成功

示例（将 Either 与 Effect 结合）

import { Effect, Either } from "effect"

// 获取数组头部的函数，返回 Either
const head = <A>(array: ReadonlyArray<A>): Either.Either<A, string> =>
  array.length > 0 ? Either.right(array[0]) : Either.left("empty array")

// 返回 Effect 的模拟获取函数
const fetchData = (): Effect.Effect<string, string> => {
  const success = Math.random() > 0.5
  return success
    ? Effect.succeed("some data")
    : Effect.fail("Failed to fetch data")
}

// 混合 Either 和 Effect
const program = Effect.all([head([1, 2, 3]), fetchData()])

Effect.runPromise(program).then(console.log)
/*
示例输出:
[ 1, 'some data' ]
*/

组合两个或多个 Eithers

zipWith

Either.zipWith 函数允许您使用提供的函数组合两个 Either 值。它创建一个新的 Either，保存两个原始 Either 值的组合值。

示例（将两个 Eithers 组合成一个对象）

import { Either } from "effect"

const maybeName: Either.Either<string, string> = Either.right("John")
const maybeAge: Either.Either<number, string> = Either.right(25)

// 将姓名和年龄组合成一个人员对象
const person = Either.zipWith(maybeName, maybeAge, (name, age) => ({
  name: name.toUpperCase(),
  age
}))

console.log(person)
/*
输出:
{ _id: 'Either', _tag: 'Right', right: { name: 'JOHN', age: 25 } }
*/

如果任一 Either 值是 Left，结果将是 Left，保存第一个遇到的 Left 值：

示例（组合带有 Left 值的 Eithers）

import { Either } from "effect"

const maybeName: Either.Either<string, string> = Either.right("John")
const maybeAge: Either.Either<number, string> = Either.left("Oh no!")

// 由于 maybeAge 是 Left，结果也将是 Left
const person = Either.zipWith(maybeName, maybeAge, (name, age) => ({
  name: name.toUpperCase(),
  age
}))

console.log(person)
/*
输出:
{ _id: 'Either', _tag: 'Left', left: 'Oh no!' }
*/

all

要在不转换内容的情况下组合多个 Either 值，您可以使用 Either.all。此函数返回一个结构与输入匹配的 Either：

• 如果您传递一个元组，结果将是相同长度的元组。
• 如果您传递一个结构体，结果将是具有相同键的结构体。
• 如果您传递一个 Iterable，结果将是一个数组。

示例（将多个 Eithers 组合成元组和结构体）

import { Either } from "effect"

const maybeName: Either.Either<string, string> = Either.right("John")
const maybeAge: Either.Either<number, string> = Either.right(25)

//      ┌─── Either<[string, number], string>
//      ▼
const tuple = Either.all([maybeName, maybeAge])
console.log(tuple)
/*
输出:
{ _id: 'Either', _tag: 'Right', right: [ 'John', 25 ] }
*/

//      ┌─── Either<{ name: string; age: number; }, string>
//      ▼
const struct = Either.all({ name: maybeName, age: maybeAge })
console.log(struct)
/*
输出:
{ _id: 'Either', _tag: 'Right', right: { name: 'John', age: 25 } }
*/

如果一个或多个 Either 值是 Left，则返回遇到的第一个 Left：

示例（处理多个 Left 值）

import { Either } from "effect"

const maybeName: Either.Either<string, string> =
  Either.left("name not found")
const maybeAge: Either.Either<number, string> =
  Either.left("age not found")

// 将返回第一个 Left 值
console.log(Either.all([maybeName, maybeAge]))
/*
输出:
{ _id: 'Either', _tag: 'Left', left: 'name not found' }
*/

gen

类似于 Effect.gen，Either.gen 提供了一种更可读的、基于生成器的语法来处理 Either 值，使涉及 Either 的代码更易于编写和理解。这种方法类似于使用 async/await，但专为 Either 量身定制。

示例（使用 Either.gen 创建组合值）

import { Either } from "effect"

const maybeName: Either.Either<string, string> = Either.right("John")
const maybeAge: Either.Either<number, string> = Either.right(25)

const program = Either.gen(function* () {
  const name = (yield* maybeName).toUpperCase()
  const age = yield* maybeAge
  return { name, age }
})

console.log(program)
/*
输出:
{ _id: 'Either', _tag: 'Right', right: { name: 'JOHN', age: 25 } }
*/

当序列中的任何 Either 值是 Left 时，生成器立即返回 Left 值，跳过进一步的操作：

示例（使用 Either.gen 处理 Left 值）

在此示例中，Either.gen 一旦遇到 Left 值就会停止执行，有效地传播错误而不执行进一步的操作。

import { Either } from "effect"

const maybeName: Either.Either<string, string> = Either.left("Oh no!")
const maybeAge: Either.Either<number, string> = Either.right(25)

const program = Either.gen(function* () {
  console.log("正在获取姓名...")
  const name = (yield* maybeName).toUpperCase()
  console.log("正在获取年龄...")
  const age = yield* maybeAge
  return { name, age }
})

console.log(program)
/*
输出:
正在获取姓名...
{ _id: 'Either', _tag: 'Left', left: 'Oh no!' }
*/

在这些示例中使用 console.log 仅用于演示目的。使用 Either.gen 时，避免在生成器函数中包含副作用，因为 Either 应该保持为纯数据结构。