高级用法

声明新数据类型

原始数据类型

要为原始数据类型（如File）声明模式，您可以使用Schema.declare函数以及类型守卫。

示例（为File声明模式）

import { Schema } from "effect"

// 使用类型守卫为File类型声明模式
const FileFromSelf = Schema.declare(
  (input: unknown): input is File => input instanceof File
)

const decode = Schema.decodeUnknownSync(FileFromSelf)

// 解码有效的File对象
console.log(decode(new File([], "")))
/*
Output:
File { size: 0, type: '', name: '', lastModified: 1724774163056 }
*/

// 解码无效输入
decode(null)
/*
throws
ParseError: Expected <declaration schema>, actual null
*/

添加注解

像identifier和description这样的注解对于改善错误消息和使模式自文档化很有用。

要增强默认错误消息，您可以添加注解，特别是identifier、title和description注解（这些注解都不是必需的，但建议作为良好实践，可以使您的模式”自文档化”）。这些注解将被消息系统利用以返回更有意义的消息。

• 标识符：模式的唯一名称
• 标题：简短的描述性标题
• 描述：模式目的的详细解释

示例（使用注解声明模式）

import { Schema } from "effect"

// 为File类型声明带有附加注解的模式
const FileFromSelf = Schema.declare(
  (input: unknown): input is File => input instanceof File,
  {
    // 模式的唯一标识符
    identifier: "FileFromSelf",
    // 模式的详细描述
    description: "The `File` type in JavaScript"
  }
)

const decode = Schema.decodeUnknownSync(FileFromSelf)

// 解码有效的File对象
console.log(decode(new File([], "")))
/*
Output:
File { size: 0, type: '', name: '', lastModified: 1724774163056 }
*/

// 解码无效输入
decode(null)
/*
throws
ParseError: Expected FileFromSelf, actual null
*/

类型构造器

类型构造器是接受一个或多个类型作为参数并返回新类型的泛型类型。要为类型构造器定义模式，您可以使用Schema.declare函数。

示例（为ReadonlySet<A>声明模式）

import { ParseResult, Schema } from "effect"

export const MyReadonlySet = <A, I, R>(
  // Set元素的模式
  item: Schema.Schema<A, I, R>
): Schema.Schema<ReadonlySet<A>, ReadonlySet<I>, R> =>
  Schema.declare(
    // 存储Set元素的模式
    [item],
    {
      // 解码函数
      decode: (item) => (input, parseOptions, ast) => {
        if (input instanceof Set) {
          // 解码Set中的每个元素
          const elements = ParseResult.decodeUnknown(Schema.Array(item))(
            Array.from(input.values()),
            parseOptions
          )
          // 返回包含解码元素的ReadonlySet
          return ParseResult.map(
            elements,
            (as): ReadonlySet<A> => new Set(as)
          )
        }
        // 处理无效输入
        return ParseResult.fail(new ParseResult.Type(ast, input))
      },
      // 编码函数
      encode: (item) => (input, parseOptions, ast) => {
        if (input instanceof Set) {
          // 编码Set中的每个元素
          const elements = ParseResult.encodeUnknown(Schema.Array(item))(
            Array.from(input.values()),
            parseOptions
          )
          // 返回包含编码元素的ReadonlySet
          return ParseResult.map(
            elements,
            (is): ReadonlySet<I> => new Set(is)
          )
        }
        // 处理无效输入
        return ParseResult.fail(new ParseResult.Type(ast, input))
      }
    },
    {
      description: `ReadonlySet<${Schema.format(item)}>`
    }
  )

// 为数字的ReadonlySet定义模式
const setOfNumbers = MyReadonlySet(Schema.NumberFromString)

const decode = Schema.decodeUnknownSync(setOfNumbers)

console.log(decode(new Set(["1", "2", "3"]))) // Set(3) { 1, 2, 3 }

// 解码无效输入
decode(null)
/*
throws
ParseError: Expected ReadonlySet<NumberFromString>, actual null
*/

// 解码包含无效元素的Set
decode(new Set(["1", null, "3"]))
/*
throws
ParseError: ReadonlyArray<NumberFromString>
└─ [1]
   └─ NumberFromString
      └─ Encoded side transformation failure
         └─ Expected string, actual null
*/

解码/编码限制

解码和编码函数不能依赖上下文（Requirements类型参数）并且不能处理异步效果。 这意味着在这些函数中只支持同步操作。

添加编译器注解

在定义新数据类型时，一些编译器如Arbitrary或Pretty可能不知道如何处理新类型。 这可能导致错误，因为编译器可能缺乏生成实例或产生可读输出的必要信息：

示例（尝试在没有必需注解的情况下生成任意值）

import { Arbitrary, Schema } from "effect"

// 为File类型定义模式
const FileFromSelf = Schema.declare(
  (input: unknown): input is File => input instanceof File,
  {
    identifier: "FileFromSelf"
  }
)

// 尝试为模式创建Arbitrary实例
const arb = Arbitrary.make(FileFromSelf)
/*
throws:
Error: Missing annotation
details: Generating an Arbitrary for this schema requires an "arbitrary" annotation
schema (Declaration): FileFromSelf
*/

在上面的示例中，尝试为FileFromSelf模式生成任意值失败，因为编译器缺乏必要的注解。要解决这个问题，您需要提供用于生成任意数据的注解：

示例（为自定义File模式添加Arbitrary注解）

import { Arbitrary, FastCheck, Pretty, Schema } from "effect"

const FileFromSelf = Schema.declare(
  (input: unknown): input is File => input instanceof File,
  {
    identifier: "FileFromSelf",
    // 提供一个生成随机File实例的函数
    arbitrary: () => (fc) =>
      fc
        .tuple(fc.string(), fc.string())
        .map(([content, path]) => new File([content], path))
  }
)

// 为模式创建Arbitrary实例
const arb = Arbitrary.make(FileFromSelf)

// 使用Arbitrary实例生成示例文件
const files = FastCheck.sample(arb, 2)
console.log(files)
/*
Example Output:
[
  File { size: 5, type: '', name: 'C', lastModified: 1706435571176 },
  File { size: 1, type: '', name: '98Ggmc', lastModified: 1706435571176 }
]
*/

有关如何为Arbitrary编译器添加注解的更多详细信息，请参阅Arbitrary文档。

品牌类型

TypeScript的类型系统是结构化的，这意味着任何两个结构等价的类型都被认为是相同的。 当语义上不同的类型被当作相同类型处理时，这可能会导致问题。

示例（结构化类型问题）

type UserId = string
type Username = string

declare const getUser: (id: UserId) => object

const myUsername: Username = "gcanti"

getUser(myUsername) // 这错误地工作了

在上面的示例中，UserId和Username都是同一类型string的别名。这意味着getUser函数可能错误地接受Username作为有效的UserId，导致错误和问题。

为了防止这种情况，Effect引入了品牌类型。这些类型将唯一标识符（或”品牌”）附加到类型上，允许您区分结构相似但语义不同的类型。

示例（定义品牌类型）

import { Brand } from "effect"

type UserId = string & Brand.Brand<"UserId">
type Username = string

declare const getUser: (id: UserId) => object

const myUsername: Username = "gcanti"

getUser(myUsername)
Error ts(2345)  ― Argument of type 'string' is not assignable to parameter of type 'UserId'.
  Type 'string' is not assignable to type 'Brand<"UserId">'.

通过将UserId定义为品牌类型，getUser函数只能接受UserId类型的值，而不能接受普通字符串或其他与字符串兼容的类型。这有助于防止因意外传递错误类型的值给函数而导致的错误。

有两种方式为品牌类型定义模式，取决于您是否：

• 想要从头开始定义模式
• 已经通过effect/Brand定义了品牌类型并想要重用它来定义模式

从头开始定义品牌模式

要从头开始为品牌类型定义模式，请使用Schema.brand函数。

示例（为品牌类型创建模式）

import { Schema } from "effect"

const UserId = Schema.String.pipe(Schema.brand("UserId"))

// string & Brand<"UserId">
type UserId = typeof UserId.Type

请注意，您可以使用unique symbol作为品牌来确保跨模块/包的唯一性。

示例（使用唯一符号作为品牌）

import { Schema } from "effect"

const UserIdBrand: unique symbol = Symbol.for("UserId")

const UserId = Schema.String.pipe(Schema.brand(UserIdBrand))

// string & Brand<typeof UserIdBrand>
type UserId = typeof UserId.Type

重用现有的品牌构造器

如果您已经使用effect/Brand模块定义了品牌类型，您可以使用Schema.fromBrand函数重用它来定义模式。

示例（重用现有的品牌类型）

import { Schema } from "effect"
import { Brand } from "effect"

// 现有的品牌类型
type UserId = string & Brand.Brand<"UserId">

const UserId = Brand.nominal<UserId>()

// 为品牌类型定义模式
const UserIdSchema = Schema.String.pipe(Schema.fromBrand(UserId))

利用默认构造器

Schema.brand函数包含一个默认构造器来便于创建品牌值。

import { Schema } from "effect"

const UserId = Schema.String.pipe(Schema.brand("UserId"))

const userId = UserId.make("123") // 创建一个品牌UserId

属性签名

PropertySignature表示从”From”字段到”To”字段的转换。这允许您定义传入数据字段与内部模型之间的映射。

基本用法

属性签名可以使用注解定义，以提供关于字段的额外上下文。

示例（为属性签名添加注解）

import { Schema } from "effect"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.propertySignature(Schema.NumberFromString).annotations({
    title: "Age" // 标记age字段的注解
  })
})

A PropertySignature type contains several parameters, each providing details about the transformation between the source field (From) and the target field (To). Let’s take a look at what each of these parameters represents:

age: PropertySignature<
  ToToken,
  ToType,
  FromKey,
  FromToken,
  FromType,
  HasDefault,
  Context
>

Parameter	Description
age	Key of the “To” field
ToToken	Indicates field requirement: "?:" for optional, ":" for required
ToType	Type of the “To” field
FromKey	(Optional, default = never) Indicates the source field key, typically the same as “To” field key unless specified
FromToken	Indicates source field requirement: "?:" for optional, ":" for required
FromType	Type of the “From” field
HasDefault	Indicates if there is a constructor default value (Boolean)

In the example above, the PropertySignature type for age is:

PropertySignature<":", number, never, ":", string, false, never>

This means:

参数	描述
age	”To”字段的键
ToToken	":"表示age字段是必需的
ToType	age字段的类型是number
FromKey	never表示解码发生在同名的age字段
FromToken	":"表示解码发生在必需的age字段
FromType	”From”字段的类型是string
HasDefault	false：表示没有默认值

有时，源字段（“From”字段）可能与内部模型中的字段名称不同。您可以使用Schema.fromKey函数在这些字段之间进行映射。

示例（从不同键映射）

import { Schema } from "effect"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.propertySignature(Schema.NumberFromString).pipe(
    Schema.fromKey("AGE") // 从"AGE"映射到"age"
  )
})

console.log(Schema.decodeUnknownSync(Person)({ name: "name", AGE: "18" }))
// Output: { name: 'name', age: 18 }

当您从"AGE"映射到"age"时，PropertySignature类型变为：

PropertySignature<":", number, never, ":", string, false, never>
PropertySignature<":", number, "AGE", ":", string, false, never>

可选字段

基本可选属性

语法：

Schema.optional(schema: Schema<A, I, R>)

在模式中创建可选属性，允许字段被省略或设置为undefined。

解码

输入	输出
<缺失值>	保持<缺失值>
undefined	保持undefined
i: I	转换为a: A

编码

输入	输出
<缺失值>	保持<缺失值>
undefined	保持undefined
a: A	转换回i: I

示例（定义可选数字字段）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optional(Schema.NumberFromString)
})

//     ┌─── { readonly quantity?: string | undefined; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity?: number | undefined; }
//     ▼
type Type = typeof Product.Type

// 解码示例

console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
// Output: { quantity: 1 }
console.log(Schema.decodeUnknownSync(Product)({}))
// Output: {}
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
// Output: { quantity: undefined }

// 编码示例

console.log(Schema.encodeSync(Product)({ quantity: 1 }))
// Output: { quantity: "1" }
console.log(Schema.encodeSync(Product)({}))
// Output: {}
console.log(Schema.encodeSync(Product)({ quantity: undefined }))
// Output: { quantity: undefined }

暴露的值

您可以使用from属性访问原始模式类型（在标记为可选之前）。

示例（访问原始模式）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optional(Schema.NumberFromString)
})

//      ┌─── typeof Schema.NumberFromString
//      ▼
const from = Product.fields.quantity.from

带空值的可选

语法：

Schema.optionalWith(schema: Schema<A, I, R>, { nullable: true })

在模式中创建可选属性，将null值视为与缺失值相同。

解码

输入	输出
<缺失值>	保持<缺失值>
undefined	保持undefined
null	转换为<缺失值>
i: I	转换为a: A

编码

输入	输出
<缺失值>	保持<缺失值>
undefined	保持undefined
a: A	转换回i: I

示例（将Null处理为缺失值）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    nullable: true
  })
})

//     ┌─── { readonly quantity?: string | null | undefined; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity?: number | undefined; }
//     ▼
type Type = typeof Product.Type

// 解码示例

console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
// Output: { quantity: 1 }
console.log(Schema.decodeUnknownSync(Product)({}))
// Output: {}
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
// Output: { quantity: undefined }
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
// Output: {}

// 编码示例

console.log(Schema.encodeSync(Product)({ quantity: 1 }))
// Output: { quantity: "1" }
console.log(Schema.encodeSync(Product)({}))
// Output: {}
console.log(Schema.encodeSync(Product)({ quantity: undefined }))
// Output: { quantity: undefined }

暴露的值

您可以使用from属性访问原始模式类型（在标记为可选之前）。

示例（访问原始模式）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    nullable: true
  })
})

//      ┌─── typeof Schema.NumberFromString
//      ▼
const from = Product.fields.quantity.from

带精确性的可选

语法：

Schema.optionalWith(schema: Schema<A, I, R>, { exact: true })

创建可选属性的同时强制严格类型。这意味着只接受指定的类型（不包括undefined）。任何尝试解码undefined的操作都会导致错误。

解码

输入	输出
<缺失值>	保持<缺失值>
undefined	ParseError
i: I	转换为a: A

编码

输入	输出
<缺失值>	保持<缺失值>
a: A	转换回i: I

示例（在可选字段中使用精确性）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, { exact: true })
})

//     ┌─── { readonly quantity?: string; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity?: number; }
//     ▼
type Type = typeof Product.Type

// 解码示例

console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
// Output: { quantity: 1 }
console.log(Schema.decodeUnknownSync(Product)({}))
// Output: {}
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
/*
throws:
ParseError: { readonly quantity?: NumberFromString }
└─ ["quantity"]
   └─ NumberFromString
      └─ Encoded side transformation failure
         └─ Expected string, actual undefined
*/

// 编码示例

console.log(Schema.encodeSync(Product)({ quantity: 1 }))
// Output: { quantity: "1" }
console.log(Schema.encodeSync(Product)({}))
// Output: {}

暴露的值

您可以使用from属性访问原始模式类型（在标记为可选之前）。

示例（访问原始模式）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, { exact: true })
})

//      ┌─── typeof Schema.NumberFromString
//      ▼
const from = Product.fields.quantity.from

组合空值和精确性

语法：

Schema.optionalWith(schema: Schema<A, I, R>, { exact: true, nullable: true })

允许您定义一个可选属性，该属性强制严格类型（仅精确类型），同时将null视为等同于缺失值。

解码

输入	输出
<缺失值>	保持<缺失值>
null	转换为<缺失值>
undefined	ParseError
i: I	转换为a: A

编码

输入	输出
<缺失值>	保持<缺失值>
a: A	转换回i: I

示例（在可选字段中使用精确性并将Null处理为缺失值）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    exact: true,
    nullable: true
  })
})

//     ┌─── { readonly quantity?: string | null; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity?: number; }
//     ▼
type Type = typeof Product.Type

// 解码示例

console.log(Schema.decodeUnknownSync(Product)({ quantity: "1" }))
// Output: { quantity: 1 }
console.log(Schema.decodeUnknownSync(Product)({}))
// Output: {}
console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
/*
throws:
ParseError: (Struct (Encoded side) <-> Struct (Type side))
└─ Encoded side transformation failure
   └─ Struct (Encoded side)
      └─ ["quantity"]
         └─ NumberFromString | null
            ├─ NumberFromString
            │  └─ Encoded side transformation failure
            │     └─ Expected string, actual undefined
            └─ Expected null, actual undefined
*/
console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
// Output: {}

// 编码示例

console.log(Schema.encodeSync(Product)({ quantity: 1 }))
// Output: { quantity: "1" }
console.log(Schema.encodeSync(Product)({}))
// Output: {}

暴露的值

您可以使用from属性访问原始模式类型（在标记为可选之前）。

示例（访问原始模式）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    exact: true,
    nullable: true
  })
})

//      ┌─── typeof Schema.NumberFromString
//      ▼
const from = Product.fields.quantity.from

使用never类型表示可选字段

当创建模式来复制包含never类型可选字段的TypeScript类型时，例如：

type MyType = {
  readonly quantity?: never
}

这些字段的处理取决于您的tsconfig.json中的exactOptionalPropertyTypes设置。 此设置影响模式是否应将可选的never类型字段视为简单缺失或允许undefined作为值。

示例（exactOptionalPropertyTypes: false）

当此功能关闭时，您可以使用Schema.optional函数。这种方法允许字段隐式接受undefined作为值。

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optional(Schema.Never)
})

//     ┌─── { readonly quantity?: undefined; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity?: undefined; }
//     ▼
type Type = typeof Product.Type

示例（exactOptionalPropertyTypes: true）

当此功能开启时，建议使用Schema.optionalWith函数。 它确保更严格地强制字段的缺失。

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.Never, { exact: true })
})

//     ┌─── { readonly quantity?: never; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity?: never; }
//     ▼
type Type = typeof Product.Type

默认值

Schema.optionalWith中的default选项允许您设置在解码和对象构造阶段应用的默认值。 此功能确保即使用户未提供某些属性，系统也会自动使用指定的默认值。

Schema.optionalWith函数提供了几种方式来控制在解码和编码期间如何应用默认值。您可以微调是否仅在输入完全缺失时应用默认值，或者甚至在提供null或undefined值时也应用默认值。

基本默认值

这是最简单的用例。如果输入缺失或为undefined，将应用默认值。

语法

Schema.optionalWith(schema: Schema<A, I, R>, { default: () => A })

操作	行为
解码	如果输入缺失或为undefined，则应用默认值
编码	将输入a: A转换回i: I

示例（当字段缺失或为undefined时应用默认值）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    default: () => 1 // Default value for quantity
  })
})

//     ┌─── { readonly quantity?: string | undefined; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity: number; }
//     ▼
type Type = typeof Product.Type

// 应用默认值的解码示例

console.log(Schema.decodeUnknownSync(Product)({}))
// Output: { quantity: 1 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
// Output: { quantity: 1 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
// Output: { quantity: 2 }

// 应用默认值的对象构造示例

console.log(Product.make({}))
// Output: { quantity: 1 }

console.log(Product.make({ quantity: 2 }))
// Output: { quantity: 2 }

暴露的值

您可以使用from属性访问原始模式类型（在标记为可选之前）。

示例（访问原始模式）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    default: () => 1 // Default value for quantity
  })
})

//      ┌─── typeof Schema.NumberFromString
//      ▼
const from = Product.fields.quantity.from

带精确性的默认值

当您希望仅在字段完全缺失时（而不是在为undefined时）应用默认值时，可以使用exact选项。

语法

Schema.optionalWith(schema: Schema<A, I, R>, {
  default: () => A,
  exact: true
})

操作	行为
解码	仅在输入缺失时应用默认值
编码	将输入a: A转换回i: I

示例（仅在字段缺失时应用默认值）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    default: () => 1, // Default value for quantity
    exact: true // Only apply default if quantity is not provided
  })
})

//     ┌─── { readonly quantity?: string; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity: number; }
//     ▼
type Type = typeof Product.Type

console.log(Schema.decodeUnknownSync(Product)({}))
// Output: { quantity: 1 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
// Output: { quantity: 2 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
/*
throws:
ParseError: (Struct (Encoded side) <-> Struct (Type side))
└─ Encoded side transformation failure
   └─ Struct (Encoded side)
      └─ ["quantity"]
         └─ NumberFromString
            └─ Encoded side transformation failure
               └─ Expected string, actual undefined
*/

带空值的默认值

在您希望null值触发默认行为的情况下，可以使用nullable选项。这确保如果字段设置为null，它将被默认值替换。

语法

Schema.optionalWith(schema: Schema<A, I, R>, {
  default: () => A,
  nullable: true
})

操作	行为
解码	如果输入缺失或为undefined或null，则应用默认值
编码	将输入a: A转换回i: I

示例（当字段缺失或为undefined或null时应用默认值）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    default: () => 1, // Default value for quantity
    nullable: true // Apply default if quantity is null
  })
})

//     ┌─── { readonly quantity?: string | null | undefined; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity: number; }
//     ▼
type Type = typeof Product.Type

console.log(Schema.decodeUnknownSync(Product)({}))
// Output: { quantity: 1 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
// Output: { quantity: 1 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
// Output: { quantity: 1 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
// Output: { quantity: 2 }

组合精确性和空值

为了更严格的方法，您可以同时组合exact和nullable选项。这样，默认值仅在字段为null或缺失时应用，而不是在明确设置为undefined时应用。

语法

Schema.optionalWith(schema: Schema<A, I, R>, {
  default: () => A,
  exact: true,
  nullable: true
})

操作	行为
解码	如果输入缺失或为null，则应用默认值
编码	将输入a: A转换回i: I

示例（仅在字段缺失或为null时应用默认值）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    default: () => 1, // Default value for quantity
    exact: true, // Only apply default if quantity is not provided
    nullable: true // Apply default if quantity is null
  })
})

//     ┌─── { readonly quantity?: string | null; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity: number; }
//     ▼
type Type = typeof Product.Type

console.log(Schema.decodeUnknownSync(Product)({}))
// Output: { quantity: 1 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
// Output: { quantity: 1 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
// Output: { quantity: 2 }

console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
/*
throws:
ParseError: (Struct (Encoded side) <-> Struct (Type side))
└─ Encoded side transformation failure
   └─ Struct (Encoded side)
      └─ ["quantity"]
         └─ NumberFromString
            └─ Encoded side transformation failure
               └─ Expected string, actual undefined
*/

可选字段作为Options

在处理可选字段时，您可能希望将它们作为Option类型处理。这种方法允许您明确管理字段的存在或缺失，而不是依赖于undefined或null。

带Option类型的基本可选

您可以配置模式将可选字段视为Option类型，其中缺失或undefined值转换为Option.none()，现有值包装在Option.some()中。

语法

optionalWith(schema: Schema<A, I, R>, { as: "Option" })

解码

输入	输出
<缺失值>	转换为Option.none()
undefined	转换为Option.none()
i: I	转换为Option.some(a: A)

编码

输入	输出
Option.none()	转换为<缺失值>
Option.some(a: A)	转换回i: I

示例（将可选字段作为Option处理）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, { as: "Option" })
})

//     ┌─── { readonly quantity?: string | undefined; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity: Option<number>; }
//     ▼
type Type = typeof Product.Type

console.log(Schema.decodeUnknownSync(Product)({}))
// Output: { quantity: { _id: 'Option', _tag: 'None' } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
// Output: { quantity: { _id: 'Option', _tag: 'None' } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
// Output: { quantity: { _id: 'Option', _tag: 'Some', value: 2 } }

暴露的值

您可以使用from属性访问原始模式类型（在标记为可选之前）。

示例（访问原始模式）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, { as: "Option" })
})

//      ┌─── typeof Schema.NumberFromString
//      ▼
const from = Product.fields.quantity.from

带精确性的可选

exact选项确保可选字段的默认行为仅在字段完全缺失时应用，而不是在为undefined时应用。

语法

optionalWith(schema: Schema<A, I, R>, {
  as: "Option",
  exact: true
})

解码

输入	输出
<缺失值>	转换为Option.none()
undefined	ParseError
i: I	转换为Option.some(a: A)

编码

输入	输出
Option.none()	转换为<缺失值>
Option.some(a: A)	转换回i: I

示例（在可选字段作为Option时使用精确性）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    as: "Option",
    exact: true
  })
})

//     ┌─── { readonly quantity?: string; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity: Option<number>; }
//     ▼
type Type = typeof Product.Type

console.log(Schema.decodeUnknownSync(Product)({}))
// Output: { quantity: { _id: 'Option', _tag: 'None' } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
// Output: { quantity: { _id: 'Option', _tag: 'Some', value: 2 } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
/*
throws:
ParseError: (Struct (Encoded side) <-> Struct (Type side))
└─ Encoded side transformation failure
   └─ Struct (Encoded side)
      └─ ["quantity"]
         └─ NumberFromString
            └─ Encoded side transformation failure
               └─ Expected string, actual undefined
*/

暴露的值

您可以使用from属性访问原始模式类型（在标记为可选之前）。

示例（访问原始模式）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    as: "Option",
    exact: true
  })
})

//      ┌─── typeof Schema.NumberFromString
//      ▼
const from = Product.fields.quantity.from

带空值的可选

nullable选项扩展了默认行为，将null视为等同于Option.none()，与缺失或undefined值一起处理。

语法

optionalWith(schema: Schema<A, I, R>, {
  as: "Option",
  nullable: true
})

解码

输入	输出
<缺失值>	转换为Option.none()
undefined	转换为Option.none()
null	转换为Option.none()
i: I	转换为Option.some(a: A)

编码

输入	输出
Option.none()	转换为<缺失值>
Option.some(a: A)	转换回i: I

示例（在可选字段作为Option时将Null处理为缺失值）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    as: "Option",
    nullable: true
  })
})

//     ┌─── { readonly quantity?: string | null | undefined; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity: Option<number>; }
//     ▼
type Type = typeof Product.Type

console.log(Schema.decodeUnknownSync(Product)({}))
// Output: { quantity: { _id: 'Option', _tag: 'None' } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
// Output: { quantity: { _id: 'Option', _tag: 'None' } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
// Output: { quantity: { _id: 'Option', _tag: 'None' } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
// Output: { quantity: { _id: 'Option', _tag: 'Some', value: 2 } }

暴露的值

您可以使用from属性访问原始模式类型（在标记为可选之前）。

示例（访问原始模式）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    as: "Option",
    nullable: true
  })
})

//      ┌─── typeof Schema.NumberFromString
//      ▼
const from = Product.fields.quantity.from

组合精确性和空值

当同时使用exact和nullable选项时，只有null和缺失字段被视为Option.none()，而undefined被视为无效值。

语法

optionalWith(schema: Schema<A, I, R>, {
  as: "Option",
  exact: true,
  nullable: true
})

解码

输入	输出
<缺失值>	转换为Option.none()
undefined	ParseError
null	转换为Option.none()
i: I	转换为Option.some(a: A)

编码

输入	输出
Option.none()	转换为<缺失值>
Option.some(a: A)	转换回i: I

示例（在可选字段作为Option时使用精确性并将Null处理为缺失值）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    as: "Option",
    exact: true,
    nullable: true
  })
})

//     ┌─── { readonly quantity?: string | null; }
//     ▼
type Encoded = typeof Product.Encoded

//     ┌─── { readonly quantity: Option<number>; }
//     ▼
type Type = typeof Product.Type

console.log(Schema.decodeUnknownSync(Product)({}))
// Output: { quantity: { _id: 'Option', _tag: 'None' } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: null }))
// Output: { quantity: { _id: 'Option', _tag: 'None' } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: "2" }))
// Output: { quantity: { _id: 'Option', _tag: 'Some', value: 2 } }

console.log(Schema.decodeUnknownSync(Product)({ quantity: undefined }))
/*
throws:
ParseError: (Struct (Encoded side) <-> Struct (Type side))
└─ Encoded side transformation failure
   └─ Struct (Encoded side)
      └─ ["quantity"]
         └─ NumberFromString
            └─ Encoded side transformation failure
               └─ Expected string, actual undefined
*/

暴露的值

您可以使用from属性访问原始模式类型（在标记为可选之前）。

示例（访问原始模式）

import { Schema } from "effect"

const Product = Schema.Struct({
  quantity: Schema.optionalWith(Schema.NumberFromString, {
    as: "Option",
    exact: true,
    nullable: true
  })
})

//      ┌─── typeof Schema.NumberFromString
//      ▼
const from = Product.fields.quantity.from

可选字段原语

optionalToOptional

Schema.optionalToOptional API允许您管理从输入中的可选字段到输出中的可选字段的转换。这对于根据特定条件控制输出类型以及字段是否存在或缺失非常有用。

optionalToOptional的一个常见用例是处理特定输入值（如空字符串）应在输出中被视为缺失字段的字段。

语法

const optionalToOptional = <FA, FI, FR, TA, TI, TR>(
  from: Schema<FA, FI, FR>,
  to: Schema<TA, TI, TR>,
  options: {
    readonly decode: (o: Option.Option<FA>) => Option.Option<TI>,
    readonly encode: (o: Option.Option<TI>) => Option.Option<FA>
  }
): PropertySignature<"?:", TA, never, "?:", FI, false, FR | TR>

在此函数中：

• from参数指定输入模式，to指定输出模式。
• decode和encode函数定义字段在两侧应如何解释：
  • Option.none()作为输入参数表示输入中缺失字段。
  • 从任一函数返回Option.none()将在输出中省略该字段。

示例（从输出中省略空字符串）

考虑一个类型为string的可选字段，其中输入中的空字符串应从输出中删除。

import { Option, Schema } from "effect"

const schema = Schema.Struct({
  nonEmpty: Schema.optionalToOptional(Schema.String, Schema.String, {
    //         ┌─── Option<string>
    //         ▼
    decode: (maybeString) => {
      if (Option.isNone(maybeString)) {
        // 如果`maybeString`是`None`，则字段在输入中缺失。
        // 返回Option.none()以在输出中省略它。
        return Option.none()
      }
      // 从`Some`实例中提取值
      const value = maybeString.value
      if (value === "") {
        // 通过返回Option.none()将空字符串视为输出中的缺失。
        return Option.none()
      }
      // 在输出中包含非空字符串。
      return Option.some(value)
    },
    // 在编码阶段，您可以决定以类似于解码阶段的方式处理字段
    // 或使用不同的逻辑。
    // 这里，逻辑保持不变。
    //
    //         ┌─── Option<string>
    //         ▼
    encode: (maybeString) => maybeString
  })
})

// 解码示例

const decode = Schema.decodeUnknownSync(schema)

console.log(decode({}))
// Output: {}
console.log(decode({ nonEmpty: "" }))
// Output: {}
console.log(decode({ nonEmpty: "a non-empty string" }))
// Output: { nonEmpty: 'a non-empty string' }

// 编码示例

const encode = Schema.encodeSync(schema)

console.log(encode({}))
// Output: {}
console.log(encode({ nonEmpty: "" }))
// Output: { nonEmpty: '' }
console.log(encode({ nonEmpty: "a non-empty string" }))
// Output: { nonEmpty: 'a non-empty string' }

您可以使用Option.filter简化解码逻辑，它以简洁的方式过滤掉不需要的值。

示例（使用Option.filter进行解码）

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

const schema = Schema.Struct({
  nonEmpty: Schema.optionalToOptional(Schema.String, Schema.String, {
    decode: Option.filter((s) => s !== ""),
    encode: identity
  })
})

optionalToRequired

Schema.optionalToRequired API允许您将可选字段转换为必需字段，并使用自定义逻辑处理输入中字段缺失的情况。

语法

const optionalToRequired = <FA, FI, FR, TA, TI, TR>(
  from: Schema<FA, FI, FR>,
  to: Schema<TA, TI, TR>,
  options: {
    readonly decode: (o: Option.Option<FA>) => TI,
    readonly encode: (ti: TI) => Option.Option<FA>
  }
): PropertySignature<":", TA, never, "?:", FI, false, FR | TR>

在此函数中：

• from指定输入模式，而to指定输出模式。
• decode和encode函数定义转换行为：
  • 将Option.none()传递给decode意味着字段在输入中缺失。然后函数可以为输出返回默认值。
  • 在encode中返回Option.none()将在输出中省略该字段。

示例（为缺失字段设置null作为默认值）

此示例演示如何使用optionalToRequired在输入中缺失nullable字段时提供null默认值。在编码期间，值为null的字段将从输出中省略。

import { Option, Schema } from "effect"

const schema = Schema.Struct({
  nullable: Schema.optionalToRequired(
    // 可选字符串的输入模式
    Schema.String,
    // 允许null或字符串的输出模式
    Schema.NullOr(Schema.String),
    {
      //         ┌─── Option<string>
      //         ▼
      decode: (maybeString) => {
        if (Option.isNone(maybeString)) {
          // 如果`maybeString`是`None`，则字段在输入中缺失。
          // 返回`null`作为输出的默认值。
          return null
        }
        // 从`Some`实例中提取值
        // 并将其用作输出。
        return maybeString.value
      },
      // 在编码期间，将`null`视为缺失字段
      //
      //         ┌─── string | null
      //         ▼
      encode: (stringOrNull) =>
        stringOrNull === null
          ? // 通过返回`None`省略字段
            Option.none()
          : // 通过返回`Some`包含字段
            Option.some(stringOrNull)
    }
  )
})

// 解码示例

const decode = Schema.decodeUnknownSync(schema)

console.log(decode({}))
// Output: { nullable: null }
console.log(decode({ nullable: "a value" }))
// Output: { nullable: 'a value' }

// 编码示例

const encode = Schema.encodeSync(schema)

console.log(encode({ nullable: "a value" }))
// Output: { nullable: 'a value' }
console.log(encode({ nullable: null }))
// Output: {}

您可以使用Option.getOrElse和Option.liftPredicate简化解码和编码逻辑，以实现简洁和可读的转换。

示例（使用Option.getOrElse和Option.liftPredicate）

import { Option, Schema } from "effect"

const schema = Schema.Struct({
  nullable: Schema.optionalToRequired(
    Schema.String,
    Schema.NullOr(Schema.String),
    {
      decode: Option.getOrElse(() => null),
      encode: Option.liftPredicate((value) => value !== null)
    }
  )
})

requiredToOptional

requiredToOptional API允许您将必需字段转换为可选字段，应用自定义逻辑来确定何时可以省略该字段。

语法

const requiredToOptional = <FA, FI, FR, TA, TI, TR>(
  from: Schema<FA, FI, FR>,
  to: Schema<TA, TI, TR>,
  options: {
    readonly decode: (fa: FA) => Option.Option<TI>
    readonly encode: (o: Option.Option<TI>) => FA
  }
): PropertySignature<"?:", TA, never, ":", FI, false, FR | TR>

使用decode和encode函数，您可以控制字段的存在或缺失：

• decode中的Option.none()作为参数意味着字段在输入中缺失。
• encode中的Option.none()作为返回值意味着字段将在输出中省略。

示例（将空字符串处理为缺失值）

在此示例中，name字段是必需的，但如果它是空字符串，则被视为可选。在解码期间，name中的空字符串被视为缺失，而编码确保有值（如果name缺失，则使用空字符串作为默认值）。

import { Option, Schema } from "effect"

const schema = Schema.Struct({
  name: Schema.requiredToOptional(Schema.String, Schema.String, {
    //         ┌─── string
    //         ▼
    decode: (string) => {
      // 将空字符串视为缺失值
      if (string === "") {
        // 通过返回`None`省略字段
        return Option.none()
      }
      // 否则，按原样返回字符串
      return Option.some(string)
    },
    //         ┌─── Option<string>
    //         ▼
    encode: (maybeString) => {
      // 检查字段是否缺失
      if (Option.isNone(maybeString)) {
        // 提供空字符串作为默认值
        return ""
      }
      // 否则，按原样返回字符串
      return maybeString.value
    }
  })
})

// 解码示例

const decode = Schema.decodeUnknownSync(schema)

console.log(decode({ name: "John" }))
// Output: { name: 'John' }
console.log(decode({ name: "" }))
// Output: {}

// 编码示例

const encode = Schema.encodeSync(schema)

console.log(encode({ name: "John" }))
// Output: { name: 'John' }
console.log(encode({}))
// Output: { name: '' }

您可以使用Option.liftPredicate和Option.getOrElse简化解码和编码逻辑，以实现简洁和可读的转换。

示例（使用Option.liftPredicate和Option.getOrElse）

import { Option, Schema } from "effect"

const schema = Schema.Struct({
  name: Schema.requiredToOptional(Schema.String, Schema.String, {
    decode: Option.liftPredicate((s) => s !== ""),
    encode: Option.getOrElse(() => "")
  })
})

扩展模式

effect中的模式可以通过多种方式扩展，允许您将现有类型与其他字段或功能组合或增强。一种常见方法是使用Struct模式中可用的fields属性。此属性提供了一种便捷的方式来添加字段或合并来自不同结构的字段，同时保留原始的Struct类型。这种方法还使访问和修改字段变得更容易。

对于更复杂的情况，例如使用联合扩展结构，您可能希望使用Schema.extend函数，它在直接字段展开可能不够的场景中提供了灵活性。

Retaining Struct Type with Field Spreading

By using field spreading with ...Struct.fields, you maintain the schema’s Struct type, which allows continued access to the fields property for further modifications.

展开Struct字段

Struct通过fields属性提供对其字段的访问，这允许您通过添加其他字段或组合来自多个结构的字段来扩展现有结构。

示例（添加新字段）

import { Schema } from "effect"

const Original = Schema.Struct({
  a: Schema.String,
  b: Schema.String
})

const Extended = Schema.Struct({
  ...Original.fields,
  // Adding new fields
  c: Schema.String,
  d: Schema.String
})

//     ┌─── {
//     |      readonly a: string;
//     |      readonly b: string;
//     |      readonly c: string;
//     |      readonly d: string;
//     |    }
//     ▼
type Type = typeof Extended.Type

示例（添加额外的索引签名）

import { Schema } from "effect"

const Original = Schema.Struct({
  a: Schema.String,
  b: Schema.String
})

const Extended = Schema.Struct(
  Original.fields,
  // Adding an index signature
  Schema.Record({ key: Schema.String, value: Schema.String })
)

//     ┌─── {
//     │      readonly [x: string]: string;
//     |      readonly a: string;
//     |      readonly b: string;
//     |    }
//     ▼
type Type = typeof Extended.Type

示例（组合来自多个Struct的字段）

import { Schema } from "effect"

const Struct1 = Schema.Struct({
  a: Schema.String,
  b: Schema.String
})

const Struct2 = Schema.Struct({
  c: Schema.String,
  d: Schema.String
})

const Extended = Schema.Struct({
  ...Struct1.fields,
  ...Struct2.fields
})

//     ┌─── {
//     |      readonly a: string;
//     |      readonly b: string;
//     |      readonly c: string;
//     |      readonly d: string;
//     |    }
//     ▼
type Type = typeof Extended.Type

extend函数

Schema.extend函数提供了一种结构化的方法来扩展模式，特别是在直接字段展开不够用时——例如当您需要使用其他结构的联合来扩展结构时。

Extension Support Limitations

Not all extensions are supported, and compatibility depends on the type of schemas involved in the extension.

支持的扩展包括：

• Schema.String与另一个Schema.String细化或字符串字面量
• Schema.Number与另一个Schema.Number细化或数字字面量
• Schema.Boolean与另一个Schema.Boolean细化或布尔字面量
• 结构与另一个结构，其中重叠字段支持扩展
• 结构与索引签名
• 结构与支持的模式联合
• 结构的细化与支持的模式
• 结构的suspend与支持的模式
• 结构之间的转换，其中”from”和”to”侧与目标结构没有重叠字段

示例（使用结构联合扩展结构）

import { Schema } from "effect"

const Struct = Schema.Struct({
  a: Schema.String
})

const UnionOfStructs = Schema.Union(
  Schema.Struct({ b: Schema.String }),
  Schema.Struct({ c: Schema.String })
)

const Extended = Schema.extend(Struct, UnionOfStructs)

//     ┌─── {
//     |        readonly a: string;
//     |    } & ({
//     |        readonly b: string;
//     |    } | {
//     |        readonly c: string;
//     |    })
//     ▼
type Type = typeof Extended.Type

示例（尝试使用冲突字段扩展结构）

此示例演示了尝试使用包含重叠字段名称的另一个结构扩展结构，由于类型冲突而导致错误。

import { Schema } from "effect"

const Struct = Schema.Struct({
  a: Schema.String
})

const OverlappingUnion = Schema.Union(
  Schema.Struct({ a: Schema.Number }), // conflicting type for key "a"
  Schema.Struct({ d: Schema.String })
)

const Extended = Schema.extend(Struct, OverlappingUnion)
/*
throws:
Error: Unsupported schema or overlapping types
at path: ["a"]
details: cannot extend string with number
*/

示例（使用另一个细化扩展细化）

在此示例中，我们扩展了两个细化，Integer和Positive，创建了一个强制执行整数和正数约束的模式。

import { Schema } from "effect"

const Integer = Schema.Int.pipe(Schema.brand("Int"))
const Positive = Schema.Positive.pipe(Schema.brand("Positive"))

//      ┌─── Schema<number & Brand<"Positive"> & Brand<"Int">, number, never>
//      ▼
const PositiveInteger = Schema.asSchema(Schema.extend(Positive, Integer))

Schema.decodeUnknownSync(PositiveInteger)(-1)
/*
throws
ParseError: positive & Brand<"Positive"> & int & Brand<"Int">
└─ From side refinement failure
   └─ positive & Brand<"Positive">
      └─ Predicate refinement failure
         └─ Expected a positive number, actual -1
*/

Schema.decodeUnknownSync(PositiveInteger)(1.1)
/*
throws
ParseError: positive & Brand<"Positive"> & int & Brand<"Int">
└─ Predicate refinement failure
   └─ Expected an integer, actual 1.1
*/

重命名属性

在定义期间重命名属性

要在模式创建期间直接重命名属性，您可以使用Schema.fromKey函数。

示例（重命名必需属性）

import { Schema } from "effect"

const schema = Schema.Struct({
  a: Schema.propertySignature(Schema.String).pipe(Schema.fromKey("c")),
  b: Schema.Number
})

//     ┌─── { readonly c: string; readonly b: number; }
//     ▼
type Encoded = typeof schema.Encoded

//     ┌─── { readonly a: string; readonly b: number; }
//     ▼
type Type = typeof schema.Type

console.log(Schema.decodeUnknownSync(schema)({ c: "c", b: 1 }))
// Output: { a: "c", b: 1 }

示例（重命名可选属性）

import { Schema } from "effect"

const schema = Schema.Struct({
  a: Schema.optional(Schema.String).pipe(Schema.fromKey("c")),
  b: Schema.Number
})

//     ┌─── { readonly b: number; readonly c?: string | undefined; }
//     ▼
type Encoded = typeof schema.Encoded

//     ┌─── { readonly a?: string | undefined; readonly b: number; }
//     ▼
type Type = typeof schema.Type

console.log(Schema.decodeUnknownSync(schema)({ c: "c", b: 1 }))
// Output: { a: 'c', b: 1 }

console.log(Schema.decodeUnknownSync(schema)({ b: 1 }))
// Output: { b: 1 }

使用Schema.optional会自动返回PropertySignature，因此不需要像前面示例中重命名必需字段那样显式使用Schema.propertySignature。

重命名现有模式的属性

对于现有模式，Schema.rename API提供了一种在模式中系统地更改属性名称的方法，即使在联合等复杂结构中也是如此，尽管在结构的情况下您会丢失原始字段类型。

示例（重命名结构模式中的属性）

import { Schema } from "effect"

const Original = Schema.Struct({
  c: Schema.String,
  b: Schema.Number
})

// Renaming the "c" property to "a"
//
//
//      ┌─── SchemaClass<{
//      |      readonly a: string;
//      |      readonly b: number;
//      |    }>
//      ▼
const Renamed = Schema.rename(Original, { c: "a" })

console.log(Schema.decodeUnknownSync(Renamed)({ c: "c", b: 1 }))
// Output: { a: "c", b: 1 }

示例（重命名联合模式中的属性）

import { Schema } from "effect"

const Original = Schema.Union(
  Schema.Struct({
    c: Schema.String,
    b: Schema.Number
  }),
  Schema.Struct({
    c: Schema.String,
    d: Schema.Boolean
  })
)

// 为所有成员将"c"属性重命名为"a"
//
//      ┌─── SchemaClass<{
//      |      readonly a: string;
//      |      readonly b: number;
//      |    } | {
//      |      readonly a: string;
//      |      readonly d: number;
//      |    }>
//      ▼
const Renamed = Schema.rename(Original, { c: "a" })

console.log(Schema.decodeUnknownSync(Renamed)({ c: "c", b: 1 }))
// Output: { a: "c", b: 1 }

console.log(Schema.decodeUnknownSync(Renamed)({ c: "c", d: false }))
// Output: { a: 'c', d: false }

递归模式

Schema.suspend函数专为定义引用自身的模式而设计，例如在递归数据结构中。

示例（自引用模式）

在此示例中，Category模式通过subcategories字段引用自身，该字段是Category对象的数组。

import { Schema } from "effect"

interface Category {
  readonly name: string
  readonly subcategories: ReadonlyArray<Category>
}

const Category = Schema.Struct({
  name: Schema.String,
  subcategories: Schema.Array(
    Schema.suspend((): Schema.Schema<Category> => Category)
  )
})

Correct Inference

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

示例（类型推断错误）

import { Schema } from "effect"

const Category = Schema.Struct({
Error ts(7022)  ― 'Category' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.
  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.
})

简化模式定义的有用模式

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

示例（分离递归字段）

import { Schema } from "effect"

const fields = {
  name: Schema.String
  // ...other fields as needed
}

// 为Category模式定义接口，
// 扩展已定义字段的Type
interface Category extends Schema.Struct.Type<typeof fields> {
  // 使用递归定义`subcategories`
  readonly subcategories: ReadonlyArray<Category>
}

const Category = Schema.Struct({
  ...fields, // 展开基础字段
  subcategories: Schema.Array(
    // 使用递归定义`subcategories`
    Schema.suspend((): Schema.Schema<Category> => Category)
  )
})

互相递归模式

您还可以使用Schema.suspend创建互相递归模式，其中两个模式相互引用。在以下示例中，Expression和Operation通过相互引用形成简单的算术表达式树。

示例（定义互相递归模式）

import { Schema } from "effect"

interface Expression {
  readonly type: "expression"
  readonly value: number | Operation
}

interface Operation {
  readonly type: "operation"
  readonly operator: "+" | "-"
  readonly left: Expression
  readonly right: Expression
}

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

const Operation = Schema.Struct({
  type: Schema.Literal("operation"),
  operator: Schema.Literal("+", "-"),
  left: Expression,
  right: Expression
})

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

定义Encoded类型与Type类型不同的递归模式会增加另一层复杂性。在这种情况下，我们需要定义两个接口：一个用于Type类型（如前所见），另一个用于Encoded类型。

示例（具有不同编码和类型定义的递归模式）

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

import { Schema } from "effect"

const fields = {
  id: Schema.NumberFromString,
  name: Schema.String
}

interface Category extends Schema.Struct.Type<typeof fields> {
  readonly subcategories: ReadonlyArray<Category>
}

const Category = Schema.Struct({
  ...fields,
  subcategories: Schema.Array(
    Schema.suspend((): Schema.Schema<Category> => Category)
Error ts(2322)  ― Type 'Struct<{ subcategories: Array$<suspend<Category, Category, never>>; id: typeof NumberFromString; name: typeof String$; }>' 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'.
  )
})

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

import { Schema } from "effect"

const fields = {
  id: Schema.NumberFromString,
  name: Schema.String
}

interface Category extends Schema.Struct.Type<typeof fields> {
  readonly subcategories: ReadonlyArray<Category>
}

interface CategoryEncoded extends Schema.Struct.Encoded<typeof fields> {
  readonly subcategories: ReadonlyArray<CategoryEncoded>
}

const Category = Schema.Struct({
  ...fields,
  subcategories: Schema.Array(
    Schema.suspend(
      (): Schema.Schema<Category, CategoryEncoded> => Category
    )
  )
})