Data

Data 模块简化了在 TypeScript 中创建和处理数据结构。它提供了定义数据类型、确保对象之间相等性以及哈希数据以进行高效比较的工具。

值相等性

Data 模块提供了用于创建数据类型的构造函数，内置支持相等性和哈希，无需自定义实现。

这意味着使用这些构造函数创建的两个值如果具有相同的结构和值，则被认为是相等的。

struct

在普通 JavaScript 中，只有当对象引用完全相同的实例时，才被认为是相等的。

示例（在普通 JavaScript 中比较两个对象）

const alice = { name: "Alice", age: 30 }

// 此比较为 false，因为它们是不同的实例
console.log(alice === { name: "Alice", age: 30 }) // 输出: false
Error ts(2839)  ― This condition will always return 'false' since JavaScript compares objects by reference, not value.

然而，Data.struct 构造函数允许您基于结构和内容比较值。

示例（创建和检查结构体的相等性）

import { Data, Equal } from "effect"

//      ┌─── { readonly name: string; readonly age: number; }
//      ▼
const alice = Data.struct({ name: "Alice", age: 30 })

// 检查 Alice 是否等于具有相同结构和值的新对象
console.log(Equal.equals(alice, Data.struct({ name: "Alice", age: 30 })))
// 输出: true

// 检查 Alice 是否等于具有相同内容的普通 JavaScript 对象
console.log(Equal.equals(alice, { name: "Alice", age: 30 }))
// 输出: false

由 Equal.equals 执行的比较是浅层的，意味着嵌套对象不会递归比较，除非它们也使用 Data.struct 创建。

示例（嵌套对象的浅层比较）

import { Data, Equal } from "effect"

const nested = Data.struct({ name: "Alice", nested_field: { value: 42 } })

// 这将为 false，因为嵌套对象是通过引用比较的
console.log(
  Equal.equals(
    nested,
    Data.struct({ name: "Alice", nested_field: { value: 42 } })
  )
)
// 输出: false

要确保嵌套对象按结构比较，也要对它们使用 Data.struct。

示例（正确比较嵌套对象）

import { Data, Equal } from "effect"

const nested = Data.struct({
  name: "Alice",
  nested_field: Data.struct({ value: 42 })
})

// 现在，比较返回 true
console.log(
  Equal.equals(
    nested,
    Data.struct({
      name: "Alice",
      nested_field: Data.struct({ value: 42 })
    })
  )
)
// 输出: true

tuple

要使用元组表示数据，您可以使用 Data.tuple 构造函数。这确保您的元组可以进行结构比较。

示例（创建和检查元组的相等性）

import { Data, Equal } from "effect"

//      ┌─── readonly [string, number]
//      ▼
const alice = Data.tuple("Alice", 30)

// 检查 Alice 是否等于具有相同结构和值的新元组
console.log(Equal.equals(alice, Data.tuple("Alice", 30)))
// 输出: true

// 检查 Alice 是否等于具有相同内容的普通 JavaScript 元组
console.log(Equal.equals(alice, ["Alice", 30]))
// 输出: false

浅层比较

Equal.equals 只检查顶层结构。如果需要深度比较，请对嵌套对象使用 Data 构造函数。

array

您可以使用 Data.array 创建支持结构相等性的类数组数据结构。

示例（创建和检查数组的相等性）

import { Data, Equal } from "effect"

//      ┌─── readonly number[]
//      ▼
const numbers = Data.array([1, 2, 3, 4, 5])

// 检查数组是否等于具有相同值的新数组
console.log(Equal.equals(numbers, Data.array([1, 2, 3, 4, 5])))
// 输出: true

// 检查数组是否等于具有相同内容的普通 JavaScript 数组
console.log(Equal.equals(numbers, [1, 2, 3, 4, 5]))
// 输出: false

浅层比较

Equal.equals 只检查顶层结构。如果需要深度比较，请对嵌套对象使用 Data 构造函数。

构造函数

该模块引入了一个称为”Case 类”的概念，它在定义数据类型时自动化各种基本操作。 这些操作包括生成构造函数、处理相等性检查和管理哈希。

Case 类可以通过两种主要方式定义：

• 使用 case 或 tagged 作为普通对象
• 使用 Class 或 TaggedClass 作为 TypeScript 类

case

Data.case 助手为您的数据类型生成构造函数和内置的相等性检查和哈希支持。

示例（定义 Case 类并检查相等性）

在此示例中，Data.case 用于为 Person 创建构造函数。生成的实例具有内置的相等性检查支持，允许您使用 Equal.equals 直接比较它们。

import { Data, Equal } from "effect"

interface Person {
  readonly name: string
}

// 为 `Person` 创建构造函数
//
//      ┌─── (args: { readonly name: string; }) => Person
//      ▼
const make = Data.case<Person>()

const alice = make({ name: "Alice" })

console.log(Equal.equals(alice, make({ name: "Alice" })))
// 输出: true

console.log(Equal.equals(alice, make({ name: "John" })))
// 输出: false

示例（定义和比较嵌套 Case 类）

此示例演示了使用 Data.case 创建嵌套数据结构，例如包含 Address 的 Person 类型。Person 和 Address 构造函数都支持相等性检查。

import { Data, Equal } from "effect"

interface Address {
  readonly street: string
  readonly city: string
}

// 为 `Address` 创建构造函数
const Address = Data.case<Address>()

interface Person {
  readonly name: string
  readonly address: Address
}

// 为 `Person` 创建构造函数
const Person = Data.case<Person>()

const alice = Person({
  name: "Alice",
  address: Address({ street: "123 Main St", city: "Wonderland" })
})

const anotherAlice = Person({
  name: "Alice",
  address: Address({ street: "123 Main St", city: "Wonderland" })
})

console.log(Equal.equals(alice, anotherAlice))
// 输出: true

或者，您可以使用 Data.struct 创建嵌套数据结构，而无需定义单独的 Address 构造函数。

示例（对嵌套对象使用 Data.struct）

import { Data, Equal } from "effect"

interface Person {
  readonly name: string
  readonly address: {
    readonly street: string
    readonly city: string
  }
}

// 为 `Person` 创建构造函数
const Person = Data.case<Person>()

const alice = Person({
  name: "Alice",
  address: Data.struct({ street: "123 Main St", city: "Wonderland" })
})

const anotherAlice = Person({
  name: "Alice",
  address: Data.struct({ street: "123 Main St", city: "Wonderland" })
})

console.log(Equal.equals(alice, anotherAlice))
// 输出: true

示例（定义和比较递归 Case 类）

此示例演示了使用 Data.case 定义二叉树的递归结构，其中每个节点可以包含其他节点。

import { Data, Equal } from "effect"

interface BinaryTree<T> {
  readonly value: T
  readonly left: BinaryTree<T> | null
  readonly right: BinaryTree<T> | null
}

// 为 `BinaryTree` 创建构造函数
const BinaryTree = Data.case<BinaryTree<number>>()

const tree1 = BinaryTree({
  value: 0,
  left: BinaryTree({ value: 1, left: null, right: null }),
  right: null
})

const tree2 = BinaryTree({
  value: 0,
  left: BinaryTree({ value: 1, left: null, right: null }),
  right: null
})

console.log(Equal.equals(tree1, tree2))
// 输出: true

tagged

当您使用包含标签字段的数据类型时，如在不相交联合类型中，为每个实例手动定义标签可能会变得重复。使用 case 方法需要您每次都指定标签字段，这可能很麻烦。

示例（手动定义标记 Case 类）

在这里，我们使用 Data.case 创建带有 _tag 字段的 Person 类型。请注意，每个新实例都需要指定 _tag。

import { Data } from "effect"

interface Person {
  readonly _tag: "Person" // the tag
  readonly name: string
}

const Person = Data.case<Person>()

// 为每个实例重复 `_tag: 'Person'`
const alice = Person({ _tag: "Person", name: "Alice" })
const bob = Person({ _tag: "Person", name: "Bob" })

为了简化此过程，Data.tagged 助手会自动添加标签。它遵循 Effect 生态系统中将标签字段命名为 "_tag" 的约定。

示例（使用 Data.tagged 简化标记）

Data.tagged 助手允许您只定义一次标签，使实例创建更简单。

import { Data } from "effect"

interface Person {
  readonly _tag: "Person" // the tag
  readonly name: string
}

const Person = Data.tagged<Person>("Person")

// `_tag` 字段会自动添加
const alice = Person({ name: "Alice" })
const bob = Person({ name: "Bob" })

console.log(alice)
// 输出: { name: 'Alice', _tag: 'Person' }

Class

如果您更喜欢使用类而不是普通对象，可以使用 Data.Class 作为 Data.case 的替代方案。在您想要面向类的结构，包含方法和自定义逻辑的场景中，这种方法可能感觉更自然。

示例（使用 Data.Class 实现面向类的结构）

以下是使用 Data.Class 定义 Person 类的方法：

import { Data, Equal } from "effect"

// 定义扩展 Data.Class 的 Person 类
class Person extends Data.Class<{ name: string }> {}

// 创建 Person 实例
const alice = new Person({ name: "Alice" })

// 检查两个实例之间的相等性
console.log(Equal.equals(alice, new Person({ name: "Alice" })))
// 输出: true

使用类的好处之一是您可以轻松添加自定义方法和 getter。这允许您扩展数据类型的功能。

示例（向类添加自定义 Getters）

在此示例中，我们向 Person 类添加 upperName getter 以返回大写的名称：

import { Data } from "effect"

// 使用自定义 getter 扩展 Person 类
class Person extends Data.Class<{ name: string }> {
  get upperName() {
    return this.name.toUpperCase()
  }
}

// 创建实例并使用自定义 getter
const alice = new Person({ name: "Alice" })

console.log(alice.upperName)
// 输出: ALICE

TaggedClass

如果您更喜欢基于类的方法，但也希望获得不相交联合标记的好处，Data.TaggedClass 可能是一个有用的选择。它的工作方式类似于 tagged，但专为类定义而定制。

示例（定义具有内置标记的标记类）

以下是使用 Data.TaggedClass 定义 Person 类的方法。请注意，标签 "Person" 会自动添加：

import { Data, Equal } from "effect"

// 定义带有 _tag "Person" 的标记类 Person
class Person extends Data.TaggedClass("Person")<{ name: string }> {}

// 创建 Person 实例
const alice = new Person({ name: "Alice" })

console.log(alice)
// 输出: Person { name: 'Alice', _tag: 'Person' }

// 检查两个实例之间的相等性
console.log(Equal.equals(alice, new Person({ name: "Alice" })))
// 输出: true

使用标记类的好处之一是能够轻松添加自定义方法和 getter，根据需要扩展类的功能。

示例（向标记类添加自定义 Getters）

在此示例中，我们向 Person 类添加 upperName getter，它返回大写的名称：

import { Data } from "effect"

// 使用自定义 getter 扩展 Person 类
class Person extends Data.TaggedClass("Person")<{ name: string }> {
  get upperName() {
    return this.name.toUpperCase()
  }
}

// 创建实例并使用自定义 getter
const alice = new Person({ name: "Alice" })

console.log(alice.upperName)
// 输出: ALICE

标记结构体的联合

要创建标记结构体的不相交联合，您可以使用 Data.TaggedEnum 和 Data.taggedEnum。这些实用程序使定义和使用普通对象的联合变得简单。

定义

传递给 Data.TaggedEnum 的类型必须是一个对象，其中键表示标签， 值定义相应数据类型的结构。

示例（定义标记联合并检查相等性）

import { Data, Equal } from "effect"

// 使用 TaggedEnum 定义联合类型
type RemoteData = Data.TaggedEnum<{
  Loading: {}
  Success: { readonly data: string }
  Failure: { readonly reason: string }
}>

// 为联合中的每种情况创建构造函数
const { Loading, Success, Failure } = Data.taggedEnum<RemoteData>()

// 实例化不同状态
const state1 = Loading()
const state2 = Success({ data: "test" })
const state3 = Success({ data: "test" })
const state4 = Failure({ reason: "not found" })

// 检查状态之间的相等性
console.log(Equal.equals(state2, state3)) // 输出: true
console.log(Equal.equals(state2, state4)) // 输出: false

// 显示状态
console.log(state1) // 输出: { _tag: 'Loading' }
console.log(state2) // 输出: { data: 'test', _tag: 'Success' }
console.log(state4) // 输出: { reason: 'not found', _tag: 'Failure' }

标签字段命名约定

标签字段 "_tag" 用于识别每个状态的类型， 遵循 Effect 的命名约定。

$is 和 $match

Data.taggedEnum 提供 $is 和 $match 函数，用于方便的类型守卫和模式匹配。

示例（使用类型守卫和模式匹配）

import { Data } from "effect"

type RemoteData = Data.TaggedEnum<{
  Loading: {}
  Success: { readonly data: string }
  Failure: { readonly reason: string }
}>

const { $is, $match, Loading, Success } = Data.taggedEnum<RemoteData>()

// 使用 `$is` 为 "Loading" 创建类型守卫
const isLoading = $is("Loading")

console.log(isLoading(Loading()))
// 输出: true
console.log(isLoading(Success({ data: "test" })))
// 输出: false

// 使用 `$match` 进行模式匹配
const matcher = $match({
  Loading: () => "this is a Loading",
  Success: ({ data }) => `this is a Success: ${data}`,
  Failure: ({ reason }) => `this is a Failure: ${reason}`
})

console.log(matcher(Success({ data: "test" })))
// 输出: "this is a Success: test"

添加泛型

您可以通过使用 TaggedEnum.WithGenerics 创建更灵活和可重用的标记联合。这种方法允许您定义可以动态处理不同类型的标记联合。

示例（在 TaggedEnum 中使用泛型）

import { Data } from "effect"

// 为 RemoteData 定义泛型 TaggedEnum
type RemoteData<Success, Failure> = Data.TaggedEnum<{
  Loading: {}
  Success: { data: Success }
  Failure: { reason: Failure }
}>

// 扩展 TaggedEnum.WithGenerics 以添加泛型
interface RemoteDataDefinition extends Data.TaggedEnum.WithGenerics<2> {
  readonly taggedEnum: RemoteData<this["A"], this["B"]>
}

// 为泛型 RemoteData 创建构造函数
const { Loading, Failure, Success } =
  Data.taggedEnum<RemoteDataDefinition>()

// 使用特定类型实例化每种情况
const loading = Loading()
const failure = Failure({ reason: "not found" })
const success = Success({ data: 1 })

错误

在 Effect 中，使用专门的构造函数简化了错误处理：

• Error
• TaggedError

这些构造函数使定义自定义错误类型变得简单，同时还提供有用的集成，如相等性检查和结构化错误处理。

Error

Data.Error 允许您创建具有超出典型 message 属性的额外字段的 Error 类型。

示例（创建具有附加字段的自定义错误）

import { Data } from "effect"

// 定义具有附加字段的自定义错误
class NotFound extends Data.Error<{ message: string; file: string }> {}

// 创建自定义错误的实例
const err = new NotFound({
  message: "Cannot find this file",
  file: "foo.txt"
})

console.log(err instanceof Error)
// 输出: true

console.log(err.file)
// 输出: foo.txt
console.log(err)
/*
输出:
NotFound [Error]: Cannot find this file
  file: 'foo.txt'
  ... stack trace ...
*/

您可以直接在 Effect.gen 中 yield NotFound 的实例，而无需使用 Effect.fail。

示例（在 Effect.gen 中 Yield 自定义错误）

import { Data, Effect } from "effect"

class NotFound extends Data.Error<{ message: string; file: string }> {}

const program = Effect.gen(function* () {
  yield* new NotFound({
    message: "Cannot find this file",
    file: "foo.txt"
  })
})

Effect.runPromise(program)
/*
抛出:
Error: Cannot find this file
    at ... {
  name: '(FiberFailure) Error',
  [Symbol(effect/Runtime/FiberFailure/Cause)]: {
    _tag: 'Fail',
    error: NotFound [Error]: Cannot find this file
        at ...stack trace...
      file: 'foo.txt'
    }
  }
}
*/

TaggedError

Effect 提供了 TaggedError API 来自动向您的自定义错误添加 _tag 字段。这简化了使用 Effect.catchTag 或 Effect.catchTags 等 API 的错误处理。

import { Data, Effect, Console } from "effect"

// 定义自定义标记错误
class NotFound extends Data.TaggedError("NotFound")<{
  message: string
  file: string
}> {}

const program = Effect.gen(function* () {
  yield* new NotFound({
    message: "Cannot find this file",
    file: "foo.txt"
  })
}).pipe(
  // 捕获并处理标记错误
  Effect.catchTag("NotFound", (err) =>
    Console.error(`${err.message} (${err.file})`)
  )
)

Effect.runPromise(program)
// 输出: Cannot find this file (foo.txt)

原生 Cause 支持

使用 Data.Error 或 Data.TaggedError 创建的错误可以包含 cause 属性，与 JavaScript Error 的原生 cause 功能集成，以进行更详细的错误跟踪。

示例（使用 cause 属性）

import { Data, Effect } from "effect"

// 定义具有 cause 属性的错误
class MyError extends Data.Error<{ cause: Error }> {}

const program = Effect.gen(function* () {
  yield* new MyError({
    cause: new Error("Something went wrong")
  })
})

Effect.runPromise(program)
/*
抛出:
Error: An error has occurred
    at ... {
  name: '(FiberFailure) Error',
  [Symbol(effect/Runtime/FiberFailure/Cause)]: {
    _tag: 'Fail',
    error: MyError
        at ...
      [cause]: Error: Something went wrong
          at ...
*/