Option

Option 数据类型表示可选值。Option<A> 可以是 Some<A>（包含类型为 A 的值）或 None（表示值的缺失）。

您可以在以下场景中使用 Option：

• 用于初始值
• 从并非对所有可能输入都有定义的函数中返回值（称为”偏函数”）
• 管理数据结构中的可选字段
• 处理可选的函数参数

创建 Options

some

使用 Option.some 构造函数创建一个保存类型为 A 的值的 Option。

示例（创建带有值的 Option）

import { Option } from "effect"

// 一个保存数字 1 的 Option
const value = Option.some(1)

console.log(value)
// 输出: { _id: 'Option', _tag: 'Some', value: 1 }

none

使用 Option.none 构造函数创建一个表示值缺失的 Option。

示例（创建没有值的 Option）

import { Option } from "effect"

// 一个不保存任何值的 Option
const noValue = Option.none()

console.log(noValue)
// 输出: { _id: 'Option', _tag: 'None' }

liftPredicate

您可以基于谓词创建 Option，例如，检查值是否为正数。

示例（使用显式 Option 创建）

以下是使用 Option.none 和 Option.some 实现此功能的方法：

import { Option } from "effect"

const isPositive = (n: number) => n > 0

const parsePositive = (n: number): Option.Option<number> =>
  isPositive(n) ? Option.some(n) : Option.none()

示例（使用 Option.liftPredicate 简化）

或者，您可以使用 Option.liftPredicate 简化上述逻辑：

import { Option } from "effect"

const isPositive = (n: number) => n > 0

//      ┌─── (b: number) => Option<number>
//      ▼
const parsePositive = Option.liftPredicate(isPositive)

建模可选属性

考虑一个 User 模型，其中 "email" 属性是可选的，可以保存 string 值。我们使用 Option<string> 类型来表示这个可选属性：

import { Option } from "effect"

interface User {
  readonly id: number
  readonly username: string
  readonly email: Option.Option<string>
}

属性键始终存在

可选性仅适用于属性的值。键 "email" 将始终存在于对象中，无论它是否有值。

以下是如何创建有和没有电子邮件的 User 实例的示例：

示例（创建有和没有电子邮件的用户）

import { Option } from "effect"

interface User {
  readonly id: number
  readonly username: string
  readonly email: Option.Option<string>
}

const withEmail: User = {
  id: 1,
  username: "john_doe",
  email: Option.some("john.doe@example.com")
}

const withoutEmail: User = {
  id: 2,
  username: "jane_doe",
  email: Option.none()
}

守卫

您可以使用 Option.isSome 和 Option.isNone 守卫检查 Option 是 Some 还是 None。

示例（使用守卫检查 Option 值）

import { Option } from "effect"

const foo = Option.some(1)

console.log(Option.isSome(foo))
// 输出: true

if (Option.isNone(foo)) {
  console.log("Option 为空")
} else {
  console.log(`Option 有一个值: ${foo.value}`)
}
// 输出: "Option 有一个值: 1"

模式匹配

使用 Option.match 通过为 None 和 Some 指定单独的回调来处理 Option 的两种情况。

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

import { Option } from "effect"

const foo = Option.some(1)

const message = Option.match(foo, {
  onNone: () => "Option 为空",
  onSome: (value) => `Option 有一个值: ${value}`
})

console.log(message)
// 输出: "Option 有一个值: 1"

使用 Option

map

Option.map 函数允许您转换 Option 内部的值，而无需手动解包和重新包装。如果 Option 保存一个值（Some），则应用转换函数。如果 Option 是 None，则忽略该函数，Option 保持不变。

示例（映射 Some 中的值）

import { Option } from "effect"

// 转换 Some 内部的值
console.log(Option.map(Option.some(1), (n) => n + 1))
// 输出: { _id: 'Option', _tag: 'Some', value: 2 }

当处理 None 时，映射函数不会执行，Option 保持为 None：

示例（映射 None）

import { Option } from "effect"

// 映射 None 结果仍为 None
console.log(Option.map(Option.none(), (n) => n + 1))
// 输出: { _id: 'Option', _tag: 'None' }

flatMap

Option.flatMap 函数类似于 Option.map，但它专为处理转换可能返回另一个 Option 的情况而设计。这允许我们链接依赖于 Option 中是否存在值的计算。

考虑一个包含嵌套可选 Address 的 User 模型，该 Address 本身包含一个可选的 street 属性：

import { Option } from "effect"

interface User {
  readonly id: number
  readonly username: string
  readonly email: Option.Option<string>
  readonly address: Option.Option<Address>
}

interface Address {
  readonly city: string
  readonly street: Option.Option<string>
}

在此模型中，address 字段是 Option<Address>，Address 内的 street 字段是 Option<string>。

我们可以使用 Option.flatMap 从 address 中提取 street 属性：

示例（提取嵌套的可选属性）

import { Option } from "effect"

interface Address {
  readonly city: string
  readonly street: Option.Option<string>
}

interface User {
  readonly id: number
  readonly username: string
  readonly email: Option.Option<string>
  readonly address: Option.Option<Address>
}

const user: User = {
  id: 1,
  username: "john_doe",
  email: Option.some("john.doe@example.com"),
  address: Option.some({
    city: "New York",
    street: Option.some("123 Main St")
  })
}

// 使用 flatMap 提取街道值
const street = user.address.pipe(
  Option.flatMap((address) => address.street)
)

console.log(street)
// 输出: { _id: 'Option', _tag: 'Some', value: '123 Main St' }

如果 user.address 是 Some，Option.flatMap 应用函数 (address) => address.street 来检索 street 值。

如果 user.address 是 None，则不执行该函数，street 保持为 None。

这种方法让我们能够简洁地处理嵌套的可选值，避免手动检查，使代码更清洁、更易读。

filter

Option.filter 函数允许您基于给定的谓词过滤 Option。如果不满足谓词或 Option 是 None，结果将是 None。

示例（过滤 Option 值）

以下是如何使用 Option.filter 简化一些代码以获得更惯用的方法：

原始代码

import { Option } from "effect"

// 从 Option 中删除空字符串的函数
const removeEmptyString = (input: Option.Option<string>) => {
  if (Option.isSome(input) && input.value === "") {
    return Option.none() // 如果值是空字符串则返回 None
  }
  return input // 否则，返回原始 Option
}

console.log(removeEmptyString(Option.none()))
// 输出: { _id: 'Option', _tag: 'None' }

console.log(removeEmptyString(Option.some("")))
// 输出: { _id: 'Option', _tag: 'None' }

console.log(removeEmptyString(Option.some("a")))
// 输出: { _id: 'Option', _tag: 'Some', value: 'a' }

重构的惯用代码

使用 Option.filter，我们可以更简洁地编写相同的逻辑：

import { Option } from "effect"

const removeEmptyString = (input: Option.Option<string>) =>
  Option.filter(input, (value) => value !== "")

console.log(removeEmptyString(Option.none()))
// 输出: { _id: 'Option', _tag: 'None' }

console.log(removeEmptyString(Option.some("")))
// 输出: { _id: 'Option', _tag: 'None' }

console.log(removeEmptyString(Option.some("a")))
// 输出: { _id: 'Option', _tag: 'Some', value: 'a' }

从 Option 获取值

要检索存储在 Option 内部的值，您可以使用 Option 模块提供的几个辅助函数。以下是可用方法的概述：

getOrThrow

此函数从 Some 中提取值。如果 Option 是 None，它会抛出错误。

示例（检索值或抛出错误）

import { Option } from "effect"

console.log(Option.getOrThrow(Option.some(10)))
// 输出: 10

console.log(Option.getOrThrow(Option.none()))
// 抛出: Error: getOrThrow called on a None

getOrNull / getOrUndefined

这些函数将 None 转换为 null 或 undefined，这在使用非基于 Option 的代码时很有用。

示例（将 None 转换为 null 或 undefined）

import { Option } from "effect"

console.log(Option.getOrNull(Option.some(5)))
// 输出: 5

console.log(Option.getOrNull(Option.none()))
// 输出: null

console.log(Option.getOrUndefined(Option.some(5)))
// 输出: 5

console.log(Option.getOrUndefined(Option.none()))
// 输出: undefined

getOrElse

此函数允许您指定当 Option 是 None 时要返回的默认值。

示例（当 None 时提供默认值）

import { Option } from "effect"

console.log(Option.getOrElse(Option.some(5), () => 0))
// 输出: 5

console.log(Option.getOrElse(Option.none(), () => 0))
// 输出: 0

回退

orElse

当计算返回 None 时，您可能想要尝试产生 Option 的替代计算。Option.orElse 函数在这种情况下很有用。它让您链接多个计算，如果当前计算结果为 None，则继续下一个。这种方法通常用于重试逻辑，尝试计算直到一个成功或所有可能性都用尽。

示例（尝试替代计算）

import { Option } from "effect"

// 模拟可能产生或不产生结果的计算
const computation = (): Option.Option<number> =>
  Math.random() < 0.5 ? Option.some(10) : Option.none()

// 模拟替代计算
const alternativeComputation = (): Option.Option<number> =>
  Math.random() < 0.5 ? Option.some(20) : Option.none()

// 尝试第一个计算，如果需要则尝试替代方案
const program = computation().pipe(
  Option.orElse(() => alternativeComputation())
)

const result = Option.match(program, {
  onNone: () => "两个计算都导致 None",
  // 至少有一个计算成功
  onSome: (value) => `计算值: ${value}`
})

console.log(result)
// 输出: 计算值: 10

firstSomeOf

您还可以使用 Option.firstSomeOf 从 Option 值的可迭代对象中获取第一个 Some 值：

示例（检索第一个 Some 值）

import { Option } from "effect"

const first = Option.firstSomeOf([
  Option.none(),
  Option.some(2),
  Option.none(),
  Option.some(3)
])

console.log(first)
// 输出: { _id: 'Option', _tag: 'Some', value: 2 }

与可空类型的互操作

在处理 Option 数据类型时，您可能会遇到使用 undefined 或 null 来表示可选值的代码。Option 模块提供了几个 API 来简化与这些可空类型的交互。

fromNullable

Option.fromNullable 将可空值（null 或 undefined）转换为 Option。如果值是 null 或 undefined，它返回 Option.none()。否则，它将值包装在 Option.some() 中。

示例（从可空值创建 Option）

import { Option } from "effect"

console.log(Option.fromNullable(null))
// 输出: { _id: 'Option', _tag: 'None' }

console.log(Option.fromNullable(undefined))
// 输出: { _id: 'Option', _tag: 'None' }

console.log(Option.fromNullable(1))
// 输出: { _id: 'Option', _tag: 'Some', value: 1 }

如果您需要将 Option 转换回可空值，有两个辅助方法：

• Option.getOrNull：将 None 转换为 null。
• Option.getOrUndefined：将 None 转换为 undefined。

与 Effect 的互操作

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

Option 如何映射到 Effect

Option 变体	映射到 Effect	描述
None	Effect<never, NoSuchElementException>	表示值的缺失
Some<A>	Effect<A>	表示值的存在

示例（将 Option 与 Effect 结合）

import { Effect, Option } from "effect"

// 获取数组头部的函数，返回 Option
const head = <A>(array: ReadonlyArray<A>): Option.Option<A> =>
  array.length > 0 ? Option.some(array[0]) : Option.none()

// 返回 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")
}

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

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

组合两个或多个 Options

zipWith

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

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

import { Option } from "effect"

const maybeName: Option.Option<string> = Option.some("John")
const maybeAge: Option.Option<number> = Option.some(25)

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

console.log(person)
/*
输出:
{ _id: 'Option', _tag: 'Some', value: { name: 'JOHN', age: 25 } }
*/

如果任一 Option 值是 None，结果将是 None：

示例（处理 None 值）

import { Option } from "effect"

const maybeName: Option.Option<string> = Option.some("John")
const maybeAge: Option.Option<number> = Option.none()

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

console.log(person)
// 输出: { _id: 'Option', _tag: 'None' }

all

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

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

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

import { Option } from "effect"

const maybeName: Option.Option<string> = Option.some("John")
const maybeAge: Option.Option<number> = Option.some(25)

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

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

如果任何 Option 值是 None，结果将是 None：

示例

import { Option } from "effect"

const maybeName: Option.Option<string> = Option.some("John")
const maybeAge: Option.Option<number> = Option.none()

console.log(Option.all([maybeName, maybeAge]))
// 输出: { _id: 'Option', _tag: 'None' }

gen

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

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

import { Option } from "effect"

const maybeName: Option.Option<string> = Option.some("John")
const maybeAge: Option.Option<number> = Option.some(25)

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

console.log(person)
/*
输出:
{ _id: 'Option', _tag: 'Some', value: { name: 'JOHN', age: 25 } }
*/

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

示例（使用 Option.gen 处理 None 值）

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

import { Option } from "effect"

const maybeName: Option.Option<string> = Option.none()
const maybeAge: Option.Option<number> = Option.some(25)

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

console.log(program)
/*
输出:
正在获取姓名...
{ _id: 'Option', _tag: 'None' }
*/

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

等价性

您可以使用 Option.getEquivalence 函数比较 Option 值。此函数允许您通过为它们可能包含的值类型提供 Equivalence 来指定如何比较 Option 类型的内容。

示例（比较可选数字的等价性）

假设您有可选数字并想要检查它们是否等价。以下是如何使用 Option.getEquivalence：

import { Option, Equivalence } from "effect"

const myEquivalence = Option.getEquivalence(Equivalence.number)

console.log(myEquivalence(Option.some(1), Option.some(1)))
// 输出: true，两个选项都包含数字 1

console.log(myEquivalence(Option.some(1), Option.some(2)))
// 输出: false，数字不同

console.log(myEquivalence(Option.some(1), Option.none()))
// 输出: false，一个是数字，另一个为空

排序

您可以使用 Option.getOrder 函数对 Option 值的集合进行排序。此函数有助于为 Option 中包含的值类型指定自定义排序规则。

示例（排序可选数字）

假设您有一个可选数字列表，并希望按升序排序，将空值（Option.none()）视为最低值：

import { Option, Array, Order } from "effect"

const items = [Option.some(1), Option.none(), Option.some(2)]

// 创建用于排序包含数字的 Option 值的顺序
const myOrder = Option.getOrder(Order.number)

console.log(Array.sort(myOrder)(items))
/*
输出:
[
  { _id: 'Option', _tag: 'None' },           // None 首先出现，因为它被认为是最低的
  { _id: 'Option', _tag: 'Some', value: 1 }, // 按升序排序
  { _id: 'Option', _tag: 'Some', value: 2 }
]
*/

示例（按逆序排序可选日期）

考虑一个更复杂的情况，您有一个包含可选日期的对象列表，并希望按降序排序，将 Option.none() 值放在末尾：

import { Option, Array, Order } from "effect"

const items = [
  { data: Option.some(new Date(10)) },
  { data: Option.some(new Date(20)) },
  { data: Option.none() }
]

// 定义在 Option 值内按逆序排序日期的顺序
const sorted = Array.sortWith(
  items,
  (item) => item.data,
  Order.reverse(Option.getOrder(Order.Date))
)

console.log(sorted)
/*
输出:
[
  { data: { _id: 'Option', _tag: 'Some', value: '1970-01-01T00:00:00.020Z' } },
  { data: { _id: 'Option', _tag: 'Some', value: '1970-01-01T00:00:00.010Z' } },
  { data: { _id: 'Option', _tag: 'None' } } // None 放在最后
]
*/