类 API

在使用模式时，除了Schema.Struct构造器之外，您还有其他选择。 您可以通过Schema.Class实用程序利用类的强大功能，它具有针对常见用例量身定制的一系列优势：

类提供了几个简化模式创建过程的功能：

• 一体化定义：使用类，您可以同时定义模式和不透明类型。
• 共享功能：您可以使用类方法或getter合并共享功能。
• 值哈希和等值：利用内置功能检查值等值和应用哈希（感谢Class实现了Data.Class）。

Class Schemas Are Transformations

Classes defined with Schema.Class act as transformations. See Class Schemas are Transformations for details.

定义

要使用Schema.Class定义类，您需要指定：

• 正在创建的类的类型。
• 类的唯一标识符。
• 所需的字段。

示例（定义模式类）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

在此示例中，Person既是模式又是TypeScript类。Person的实例使用定义的模式创建，确保符合指定的字段。

示例（创建实例）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

console.log(new Person({ id: 1, name: "John" }))
/*
Output:
Person { id: 1, name: 'John' }
*/

// 使用工厂函数
console.log(Person.make({ id: 1, name: "John" }))
/*
Output:
Person { id: 1, name: 'John' }
*/

Why Use Identifiers?

You need to specify an identifier to make the class global. This ensures that two classes with the same identifier refer to the same instance, avoiding reliance on instanceof checks.

This behavior is similar to how we handle other class-based APIs like Context.Tag.

Using a unique identifier is particularly useful in scenarios where live reloads can occur, as it helps preserve the instance across reloads. It ensures there is no duplication of instances (although it shouldn’t happen, some bundlers and frameworks can behave unpredictably).

类模式是转换

类模式将结构模式转换为表示类类型的声明模式。

• 解码时，普通对象被转换为类的实例。
• 编码时，类实例被转换回普通对象。

示例（解码和编码类）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

const person = Person.make({ id: 1, name: "John" })

// 从普通对象解码为类实例
const decoded = Schema.decodeUnknownSync(Person)({ id: 1, name: "John" })
console.log(decoded)
// Output: Person { id: 1, name: 'John' }

// 将类实例编码回普通对象
const encoded = Schema.encodeUnknownSync(Person)(person)
console.log(encoded)
// Output: { id: 1, name: 'John' }

定义无字段的类

当您的模式不需要任何字段时，您可以使用空对象定义类。

示例（定义和使用无参数的类）

import { Schema } from "effect"

// 定义无字段的类
class NoArgs extends Schema.Class<NoArgs>("NoArgs")({}) {}

// 使用默认构造器创建实例
const noargs1 = new NoArgs()

// 或者，通过显式传递空对象创建实例
const noargs2 = new NoArgs({})

定义带过滤器的类

过滤器允许您在解码、编码或创建实例时验证输入。您可以传递应用了过滤器的Schema.Struct，而不是指定原始字段。

示例（对模式类应用过滤器）

import { Schema } from "effect"

class WithFilter extends Schema.Class<WithFilter>("WithFilter")(
  Schema.Struct({
    a: Schema.NumberFromString,
    b: Schema.NumberFromString
  }).pipe(
    Schema.filter(({ a, b }) => a >= b || "a must be greater than b")
  )
) {}

// 构造器
console.log(new WithFilter({ a: 1, b: 2 }))
/*
throws:
ParseError: WithFilter (Constructor)
└─ Predicate refinement failure
   └─ a must be greater than b
*/

// 解码
console.log(Schema.decodeUnknownSync(WithFilter)({ a: "1", b: "2" }))
/*
throws:
ParseError: (WithFilter (Encoded side) <-> WithFilter)
└─ Encoded side transformation failure
   └─ WithFilter (Encoded side)
      └─ Predicate refinement failure
         └─ a must be greater than b
*/

通过类构造器验证属性

当您使用Schema.Class定义类时，构造器会自动检查提供的属性是否符合模式的规则。

定义和实例化有效的类实例

构造器确保每个属性（如id和name）都符合模式。例如，id必须是数字，name必须是非空字符串。

示例（创建有效实例）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

// 使用有效属性创建实例
const john = new Person({ id: 1, name: "John" })

处理无效属性

如果在实例化期间提供了无效属性，构造器会抛出错误，解释验证失败的原因。

示例（使用无效属性创建实例）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

// 尝试使用无效的`name`创建实例
new Person({ id: 1, name: "" })
/*
throws:
ParseError: Person (Constructor)
└─ ["name"]
   └─ NonEmptyString
      └─ Predicate refinement failure
         └─ Expected NonEmptyString, actual ""
*/

错误清楚地指出name字段未能满足NonEmptyString要求。

绕过验证

在某些情况下，您可能希望绕过验证逻辑。虽然通常不建议这样做，但库提供了这样做的选项。

示例（绕过验证）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

// 在实例化期间绕过验证
const john = new Person({ id: 1, name: "" }, true)

// 或显式使用`disableValidation`选项
new Person({ id: 1, name: "" }, { disableValidation: true })

类中的自动哈希和等值

使用Schema.Class创建的类实例通过与Data.Class的集成支持Equal特征。这使得即使在不同实例之间也能进行直接的值比较。

基本等值检查

如果两个类实例的属性具有相同的值，则认为它们相等。

示例（比较具有相等属性的实例）

import { Schema } from "effect"
import { Equal } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

const john1 = new Person({ id: 1, name: "John" })
const john2 = new Person({ id: 1, name: "John" })

// 比较实例
console.log(Equal.equals(john1, john2))
// Output: true

嵌套或复杂属性

Equal特征在第一级执行比较。如果属性是更复杂的结构（如数组），即使数组本身具有相同的值，实例也可能不被认为相等。

示例（数组的浅等值）

import { Schema } from "effect"
import { Equal } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString,
  hobbies: Schema.Array(Schema.String) // 标准数组模式
}) {}

const john1 = new Person({
  id: 1,
  name: "John",
  hobbies: ["reading", "coding"]
})
const john2 = new Person({
  id: 1,
  name: "John",
  hobbies: ["reading", "coding"]
})

// 等值失败，因为`hobbies`没有进行深度比较
console.log(Equal.equals(john1, john2))
// Output: false

要为数组等嵌套结构实现深度等值，请结合使用Schema.Data和Data.array。这使库能够比较数组的每个元素，而不是将其视为单个实体。

示例（使用Schema.Data进行深度等值）

import { Schema } from "effect"
import { Data, Equal } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString,
  hobbies: Schema.Data(Schema.Array(Schema.String)) // 启用深度等值
}) {}

const john1 = new Person({
  id: 1,
  name: "John",
  hobbies: Data.array(["reading", "coding"])
})
const john2 = new Person({
  id: 1,
  name: "John",
  hobbies: Data.array(["reading", "coding"])
})

// 等值成功，因为`hobbies`进行了深度比较
console.log(Equal.equals(john1, john2))
// Output: true

使用自定义逻辑扩展类

模式类提供了包含自定义getter和方法的灵活性，允许您将其功能扩展到定义字段之外。

添加自定义Getter

getter可用于从类的字段派生计算值。例如，Person类可以包含一个getter来返回大写的name属性。

示例（为大写名称添加Getter）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {
  // 返回大写名称的自定义getter
  get upperName() {
    return this.name.toUpperCase()
  }
}

const john = new Person({ id: 1, name: "John" })

// 使用自定义getter
console.log(john.upperName)
// Output: "JOHN"

添加自定义方法

除了getter之外，您还可以定义方法来封装涉及类字段的更复杂逻辑或操作。

示例（添加方法）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {
  // 返回问候语的自定义方法
  greet() {
    return `Hello, my name is ${this.name}.`
  }
}

const john = new Person({ id: 1, name: "John" })

// 使用自定义方法
console.log(john.greet())
// Output: "Hello, my name is John."

将类用作模式定义

当您使用Schema.Class定义类时，它既作为模式又作为类。这种双重功能允许在需要模式的任何地方使用该类。

示例（在数组模式中使用类）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

// 在数组模式中使用Person类
const Persons = Schema.Array(Person)

//     ┌─── readonly Person[]
//     ▼
type Type = typeof Persons.Type

暴露的值

类还包含一个fields静态属性，它概述了在类创建期间定义的字段。

示例（访问fields属性）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

//       ┌─── {
//       |      readonly id: typeof Schema.Number;
//       |      readonly name: typeof Schema.NonEmptyString;
//       |    }
//       ▼
Person.fields

添加注解

使用Schema.Class定义类类似于创建转换模式，该模式将结构模式转换为表示类类型的声明模式。

例如，考虑以下类定义：

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

在底层，此定义创建了一个转换模式，该模式映射：

Schema.Struct({
  id: Schema.Number,
  name: Schema.NonEmptyString
})

到表示Person类的模式：

Schema.declare((input) => input instanceof Person)

因此，使用Schema.Class定义模式涉及三个模式：

• “from”模式（结构）
• “to”模式（类）
• “transformation”模式（结构 -> 类）

您可以通过将元组作为第二个参数传递给Schema.Class API来注解这些模式中的每一个。

示例（注解类模式的不同部分）

import { Schema, SchemaAST } from "effect"

class Person extends Schema.Class<Person>("Person")(
  {
    id: Schema.Number,
    name: Schema.NonEmptyString
  },
  [
    // "to"模式的注解
    { description: `"to" description` },

    // "transformation"模式的注解
    { description: `"transformation" description` },

    // "from"模式的注解
    { description: `"from" description` }
  ]
) {}

console.log(SchemaAST.getDescriptionAnnotation(Person.ast.to))
// Output: { _id: 'Option', _tag: 'Some', value: '"to" description' }

console.log(SchemaAST.getDescriptionAnnotation(Person.ast))
// Output: { _id: 'Option', _tag: 'Some', value: '"transformation" description' }

console.log(SchemaAST.getDescriptionAnnotation(Person.ast.from))
// Output: { _id: 'Option', _tag: 'Some', value: '"from" description' }

如果您不想注解所有三个模式，可以为希望跳过的模式传递undefined。

示例（跳过注解）

import { Schema, SchemaAST } from "effect"

class Person extends Schema.Class<Person>("Person")(
  {
    id: Schema.Number,
    name: Schema.NonEmptyString
  },
  [
    // "to"模式无注解
    undefined,

    // "transformation"模式的注解
    { description: `"transformation" description` }
  ]
) {}

console.log(SchemaAST.getDescriptionAnnotation(Person.ast.to))
// Output: { _id: 'Option', _tag: 'None' }

console.log(SchemaAST.getDescriptionAnnotation(Person.ast))
// Output: { _id: 'Option', _tag: 'Some', value: '"transformation" description' }

console.log(SchemaAST.getDescriptionAnnotation(Person.ast.from))
// Output: { _id: 'Option', _tag: 'None' }

默认情况下，用于定义类的唯一标识符也作为类模式的默认identifier注解应用。

示例（默认标识符注解）

import { Schema, SchemaAST } from "effect"

// 用作默认标识符注解 ────┐
//                                           |
//                                           ▼
class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {}

console.log(SchemaAST.getIdentifierAnnotation(Person.ast.to))
// Output: { _id: 'Option', _tag: 'Some', value: 'Person' }

递归模式

当您需要定义依赖于自身的模式时，Schema.suspend组合器很有用，就像递归数据结构的情况一样。 在此示例中，Category模式依赖于自身，因为它有一个subcategories字段，该字段是Category对象的数组。

示例（自引用模式）

import { Schema } from "effect"

// 定义具有递归子类别字段的Category模式
class Category extends Schema.Class<Category>("Category")({
  name: Schema.String,
  subcategories: Schema.Array(
    Schema.suspend((): Schema.Schema<Category> => Category)
  )
}) {}

Correct Inference

It is necessary to add an explicit type annotation because otherwise TypeScript would struggle to infer types correctly. Without this annotation, you might encounter this error message:

示例（缺少类型注解错误）

import { Schema } from "effect"

class Category extends Schema.Class<Category>("Category")({
Error ts(2506)  ― 'Category' is referenced directly or indirectly in its own base expression.
  name: Schema.String,
  subcategories: Schema.Array(Schema.suspend(() => Category))
Error ts(7024)  ― Function implicitly has return type 'any' because it does not have a return type annotation and is referenced directly or indirectly in one of its return expressions.
}) {}

互相递归模式

有时，模式以互相递归的方式相互依赖。例如，算术表达式树可能包括Expression节点，这些节点可以是数字或Operation节点，而Operation节点又引用Expression节点。

示例（算术表达式树）

import { Schema } from "effect"

class Expression extends Schema.Class<Expression>("Expression")({
  type: Schema.Literal("expression"),
  value: Schema.Union(
    Schema.Number,
    Schema.suspend((): Schema.Schema<Operation> => Operation)
  )
}) {}

class Operation extends Schema.Class<Operation>("Operation")({
  type: Schema.Literal("operation"),
  operator: Schema.Literal("+", "-"),
  left: Expression,
  right: Expression
}) {}

具有不同编码和类型的递归类型

定义Encoded类型与Type类型不同的递归模式会引入额外的复杂性。例如，如果模式包含转换数据的字段（例如NumberFromString），则Encoded和Type类型可能不对齐。

在这种情况下，我们需要为Encoded类型定义接口。

让我们考虑一个示例：假设我们想要向Category模式添加一个id字段，其中id的模式是NumberFromString。 重要的是要注意NumberFromString是一个将字符串转换为数字的模式，因此NumberFromString的Type和Encoded类型不同，分别为number和string。 当我们将此字段添加到Category模式时，TypeScript会引发错误：

import { Schema } from "effect"

class Category extends Schema.Class<Category>("Category")({
  id: Schema.NumberFromString,
  name: Schema.String,
  subcategories: Schema.Array(
    Schema.suspend((): Schema.Schema<Category> => Category)
Error ts(2322)  ― Type 'typeof Category' is not assignable to type 'Schema<Category, Category, never>'.
  The types of 'Encoded.id' are incompatible between these types.
    Type 'string' is not assignable to type 'number'.
  )
}) {}

此错误发生是因为显式注解S.suspend((): S.Schema<Category> => Category不再足够，需要通过显式添加Encoded类型来调整：

示例（使用显式Encoded类型调整模式）

import { Schema } from "effect"

interface CategoryEncoded {
  readonly id: string
  readonly name: string
  readonly subcategories: ReadonlyArray<CategoryEncoded>
}

class Category extends Schema.Class<Category>("Category")({
  id: Schema.NumberFromString,
  name: Schema.String,
  subcategories: Schema.Array(
    Schema.suspend(
      (): Schema.Schema<Category, CategoryEncoded> => Category
    )
  )
}) {}

正如我们所观察到的，有必要为模式的Encoded定义接口以启用递归模式定义，这可能会使事情复杂化并且相当繁琐。 缓解这种情况的一种模式是将负责递归的字段与所有其他字段分离。

示例（分离递归字段）

import { Schema } from "effect"

const fields = {
  id: Schema.NumberFromString,
  name: Schema.String
  // ...可能的其他字段
}

interface CategoryEncoded extends Schema.Struct.Encoded<typeof fields> {
  // 使用递归定义`subcategories`
  readonly subcategories: ReadonlyArray<CategoryEncoded>
}

class Category extends Schema.Class<Category>("Category")({
  ...fields, // 包含字段
  subcategories: Schema.Array(
    // 使用递归定义`subcategories`
    Schema.suspend(
      (): Schema.Schema<Category, CategoryEncoded> => Category
    )
  )
}) {}

标记类变体

您还可以创建扩展effect/Data模块中的TaggedClass和TaggedError的类。

示例（创建标记类和错误）

import { Schema } from "effect"

// 定义具有"name"字段的标记类
class TaggedPerson extends Schema.TaggedClass<TaggedPerson>()(
  "TaggedPerson",
  {
    name: Schema.String
  }
) {}

// 定义具有"status"字段的标记错误
class HttpError extends Schema.TaggedError<HttpError>()("HttpError", {
  status: Schema.Number
}) {}

const joe = new TaggedPerson({ name: "Joe" })
console.log(joe._tag)
// Output: "TaggedPerson"

const error = new HttpError({ status: 404 })
console.log(error._tag)
// Output: "HttpError"

console.log(error.stack) // 访问堆栈跟踪

扩展现有类

extend静态实用程序允许您通过添加额外字段和功能来增强现有的模式类。这种方法有助于在现有模式的基础上构建，而无需从头重新定义它们。

示例（扩展模式类）

import { Schema } from "effect"

// 定义基类
class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {
  // 将名称转换为大写的自定义getter
  get upperName() {
    return this.name.toUpperCase()
  }
}

// 扩展基类以包含"age"字段
class PersonWithAge extends Person.extend<PersonWithAge>("PersonWithAge")(
  {
    age: Schema.Number
  }
) {
  // 检查人员是否为成年人的自定义getter
  get isAdult() {
    return this.age >= 18
  }
}

// 用法
const john = new PersonWithAge({ id: 1, name: "John", age: 25 })
console.log(john.upperName) // Output: "JOHN"
console.log(john.isAdult) // Output: true

请注意，扩展类时只能添加额外字段。

示例（尝试覆盖现有字段）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.NonEmptyString
}) {
  get upperName() {
    return this.name.toUpperCase()
  }
}

class BadExtension extends Person.extend<BadExtension>("BadExtension")({
  name: Schema.Number
}) {}
/*
throws:
Error: Duplicate property signature
details: Duplicate key "name"
*/

此错误发生是因为允许覆盖字段是不安全的。它可能会干扰类上定义的任何依赖于原始定义的getter或方法。例如，在这种情况下，如果name字段更改为数字，upperName getter将会中断。

转换

您可以使用有效转换来增强模式类，以丰富或验证实体，特别是在处理来自数据库或API等外部系统的数据时。

示例（有效转换）

以下示例演示了向Person类添加age字段。age值基于id字段异步派生。

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

// 基类定义
class Person extends Schema.Class<Person>("Person")({
  id: Schema.Number,
  name: Schema.String
}) {}

console.log(Schema.decodeUnknownSync(Person)({ id: 1, name: "name" }))
/*
Output:
Person { id: 1, name: 'name' }
*/

// 模拟基于id异步获取年龄
function getAge(id: number): Effect.Effect<number, Error> {
  return Effect.succeed(id + 2)
}

// 具有转换的扩展类
class PersonWithTransform extends Person.transformOrFail<PersonWithTransform>(
  "PersonWithTransform"
)(
  {
    age: Schema.optionalWith(Schema.Number, { exact: true, as: "Option" })
  },
  {
    // 新字段的解码逻辑
    decode: (input) =>
      Effect.mapBoth(getAge(input.id), {
        onFailure: (e) =>
          new ParseResult.Type(Schema.String.ast, input.id, e.message),
        // 必须返回{ age: Option<number> }
        onSuccess: (age) => ({ ...input, age: Option.some(age) })
      }),
    encode: ParseResult.succeed
  }
) {}

Schema.decodeUnknownPromise(PersonWithTransform)({
  id: 1,
  name: "name"
}).then(console.log)
/*
Output:
PersonWithTransform {
  id: 1,
  name: 'name',
  age: { _id: 'Option', _tag: 'Some', value: 3 }
}
*/

// 具有条件转换的扩展类
class PersonWithTransformFrom extends Person.transformOrFailFrom<PersonWithTransformFrom>(
  "PersonWithTransformFrom"
)(
  {
    age: Schema.optionalWith(Schema.Number, { exact: true, as: "Option" })
  },
  {
    decode: (input) =>
      Effect.mapBoth(getAge(input.id), {
        onFailure: (e) =>
          new ParseResult.Type(Schema.String.ast, input, e.message),
        // 必须返回{ age?: number }
        onSuccess: (age) => (age > 18 ? { ...input, age } : { ...input })
      }),
    encode: ParseResult.succeed
  }
) {}

Schema.decodeUnknownPromise(PersonWithTransformFrom)({
  id: 1,
  name: "name"
}).then(console.log)
/*
Output:
PersonWithTransformFrom {
  id: 1,
  name: 'name',
  age: { _id: 'Option', _tag: 'None' }
}
*/

使用哪个API（transformOrFail或transformOrFailFrom）的决定取决于您希望何时执行转换：

1. 使用transformOrFail：

   • 转换在过程结束时发生。
   • 它期望您提供类型为{ age: Option<number> }的值。
   • 在处理初始输入后，新的转换开始发挥作用，您需要确保最终输出符合指定的结构。

2. 使用transformOrFailFrom：

   • 一旦处理初始输入，新的转换就开始。
   • 您应该提供值{ age?: number }。
   • 基于这个新输入，后续转换Schema.optionalWith(Schema.Number, { exact: true, as: "Option" })被执行。
   • 这种方法允许立即处理输入，可能影响后续转换。