默认构造器

在处理数据结构时，以最少的努力创建符合模式的值会很有帮助。 为此，Schema模块为各种模式类型提供了默认构造器，包括Structs、Records、filters和brands。

Constructor Scope

Default constructors associated with a schema of type Schema<A, I, R> operate specifically on the decoded type (A), not the encoded type (I).

• A (Decoded Type): This is the type produced after decoding and validation. The constructor creates values of this type.
• I (Encoded Type): This is the type expected when decoding raw input. The constructor does not accept this type directly.

This distinction is important when working with schemas that transform data. For example, if a schema decodes a string into a number, the default constructor will only accept numbers, not strings.

默认构造器是不安全的，这意味着如果输入不符合模式，它们会抛出错误。 如果您需要更安全的替代方案，请考虑使用Schema.validateEither，它返回指示成功或失败的结果，而不是抛出错误。

示例（使用细化默认构造器）

import { Schema } from "effect"

const schema = Schema.NumberFromString.pipe(Schema.between(1, 10))

// 构造器只接受数字
console.log(schema.make(5))
// Output: 5

// 这将抛出错误，因为数字超出了有效范围
console.log(schema.make(20))
/*
throws:
ParseError: between(1, 10)
└─ Predicate refinement failure
   └─ Expected a number between 1 and 10, actual 20
*/

结构

结构模式允许您定义具有特定字段和约束的对象。make函数可用于创建结构模式的实例。

示例（创建结构实例）

import { Schema } from "effect"

const Struct = Schema.Struct({
  name: Schema.NonEmptyString
})

// 成功创建
Struct.make({ name: "a" })

// 这将抛出错误，因为名称为空
Struct.make({ name: "" })
/*
throws
ParseError: { readonly name: NonEmptyString }
└─ ["name"]
   └─ NonEmptyString
      └─ Predicate refinement failure
         └─ Expected NonEmptyString, actual ""
*/

在某些情况下，您可能需要绕过验证。虽然在大多数情况下不建议这样做，但make提供了禁用验证的选项。

示例（绕过验证）

import { Schema } from "effect"

const Struct = Schema.Struct({
  name: Schema.NonEmptyString
})

// 在实例化期间绕过验证
Struct.make({ name: "" }, true)

// 或显式使用`disableValidation`选项
Struct.make({ name: "" }, { disableValidation: true })

记录

记录模式允许您定义键值映射，其中键和值必须满足特定条件。

示例（创建记录实例）

import { Schema } from "effect"

const Record = Schema.Record({
  key: Schema.String,
  value: Schema.NonEmptyString
})

// 成功创建
Record.make({ a: "a", b: "b" })

// 这将抛出错误，因为'b'为空
Record.make({ a: "a", b: "" })
/*
throws
ParseError: { readonly [x: string]: NonEmptyString }
└─ ["b"]
   └─ NonEmptyString
      └─ Predicate refinement failure
         └─ Expected NonEmptyString, actual ""
*/

// 绕过验证
Record.make({ a: "a", b: "" }, { disableValidation: true })

过滤器

过滤器允许您定义对单个值的约束。

示例（使用过滤器强制范围）

import { Schema } from "effect"

const MyNumber = Schema.Number.pipe(Schema.between(1, 10))

// 成功创建
const n = MyNumber.make(5)

// 这将抛出错误，因为数字超出了有效范围
MyNumber.make(20)
/*
throws
ParseError: a number between 1 and 10
└─ Predicate refinement failure
   └─ Expected a number between 1 and 10, actual 20
*/

// 绕过验证
MyNumber.make(20, { disableValidation: true })

品牌类型

品牌模式为值添加元数据以赋予其更具体的类型，同时仍保留其原始类型。

示例（创建品牌值）

import { Schema } from "effect"

const BrandedNumberSchema = Schema.Number.pipe(
  Schema.between(1, 10),
  Schema.brand("MyNumber")
)

// 成功创建
const n = BrandedNumberSchema.make(5)

// 这将抛出错误，因为数字超出了有效范围
BrandedNumberSchema.make(20)
/*
throws
ParseError: a number between 1 and 10 & Brand<"MyNumber">
└─ Predicate refinement failure
   └─ Expected a number between 1 and 10 & Brand<"MyNumber">, actual 20
*/

// 绕过验证
BrandedNumberSchema.make(20, { disableValidation: true })

使用默认构造器时，了解它们产生的值类型很有帮助。

例如，在BrandedNumberSchema示例中，构造器的返回类型是number & Brand<"MyNumber">。这表明结果值是带有额外品牌信息"MyNumber"的number。

这种行为与过滤器示例形成对比，在过滤器示例中，返回类型只是number。品牌添加了额外的类型信息层，这可以帮助更有效地识别和处理您的数据。

构造器中的错误处理

默认构造器被认为是”不安全的”，因为如果输入不符合模式，它们会抛出错误。此错误包括对出错原因的详细描述。默认构造器的目的是提供一种直接的方式来创建有效值，例如用于测试或配置，其中无效输入预期是异常情况。

如果您需要一个”安全”的构造器，它不抛出错误，而是返回指示成功或失败的结果，您可以使用Schema.validateEither。

示例（使用Schema.validateEither进行安全验证）

import { Schema } from "effect"

const schema = Schema.NumberFromString.pipe(Schema.between(1, 10))

// 创建验证未知输入的安全构造器
const safeMake = Schema.validateEither(schema)

// 有效输入返回Right值
console.log(safeMake(5))
/*
Output:
{ _id: 'Either', _tag: 'Right', right: 5 }
*/

// 无效输入返回带有详细错误信息的Left值
console.log(safeMake(20))
/*
Output:
{
  _id: 'Either',
  _tag: 'Left',
  left: {
    _id: 'ParseError',
    message: 'between(1, 10)\n' +
      '└─ Predicate refinement failure\n' +
      '   └─ Expected a number between 1 and 10, actual 20'
  }
}
*/

// 这将抛出错误，因为它是不安全的
schema.make(20)
/*
throws:
ParseError: between(1, 10)
└─ Predicate refinement failure
   └─ Expected a number between 1 and 10, actual 20
*/

设置默认值

创建对象时，您可能希望为某些字段分配默认值以简化对象构造。Schema.withConstructorDefault函数让您处理默认值，使字段在默认构造器中变为可选。

示例（具有必需字段的结构）

在此示例中，创建新实例时所有字段都是必需的。

import { Schema } from "effect"

const Person = Schema.Struct({
  name: Schema.NonEmptyString,
  age: Schema.Number
})

// 必须提供name和age
console.log(Person.make({ name: "John", age: 30 }))
/*
Output: { name: 'John', age: 30 }
*/

示例（具有默认值的结构）

在这里，age字段是可选的，因为它有默认值0。

import { Schema } from "effect"

const Person = Schema.Struct({
  name: Schema.NonEmptyString,
  age: Schema.Number.pipe(
    Schema.propertySignature,
    Schema.withConstructorDefault(() => 0)
  )
})

// age字段是可选的，默认为0
console.log(Person.make({ name: "John" }))
/*
Output:
{ name: 'John', age: 0 }
*/

console.log(Person.make({ name: "John", age: 30 }))
/*
Output:
{ name: 'John', age: 30 }
*/

嵌套结构和浅默认值

模式中的默认值是浅层的，这意味着在嵌套结构中定义的默认值不会自动传播到顶级构造器。

示例（嵌套结构中的浅默认值）

import { Schema } from "effect"

const Config = Schema.Struct({
  // 定义具有默认值的嵌套结构
  web: Schema.Struct({
    application_url: Schema.String.pipe(
      Schema.propertySignature,
      Schema.withConstructorDefault(() => "http://localhost")
    ),
    application_port: Schema.Number
  })
})

// 这将导致类型错误，因为嵌套结构中缺少`application_url`
Config.make({ web: { application_port: 3000 } })
Error ts(2741)  ― Property 'application_url' is missing in type '{ application_port: number; }' but required in type '{ readonly application_url: string; readonly application_port: number; }'.

出现这种行为是因为Schema接口不包含从嵌套结构传递默认构造器类型的类型参数。

要解决此限制，请提取嵌套结构的构造器并将其直接应用于其字段。这确保嵌套默认值得到尊重。

示例（使用嵌套结构构造器）

import { Schema } from "effect"

const Config = Schema.Struct({
  web: Schema.Struct({
    application_url: Schema.String.pipe(
      Schema.propertySignature,
      Schema.withConstructorDefault(() => "http://localhost")
    ),
    application_port: Schema.Number
  })
})

// 提取嵌套结构构造器
const { web: Web } = Config.fields

// 使用嵌套结构的构造器
console.log(Config.make({ web: Web.make({ application_port: 3000 }) }))
/*
Output:
{
  web: {
    application_url: 'http://localhost',
    application_port: 3000
  }
}
*/

默认值的延迟求值

默认值是延迟求值的，这意味着每次调用构造器时都会生成默认值的新实例：

示例（默认值的延迟求值）

在此示例中，timestamp字段为每个实例生成新值。

import { Schema } from "effect"

const Person = Schema.Struct({
  name: Schema.NonEmptyString,
  age: Schema.Number.pipe(
    Schema.propertySignature,
    Schema.withConstructorDefault(() => 0)
  ),
  timestamp: Schema.Number.pipe(
    Schema.propertySignature,
    Schema.withConstructorDefault(() => new Date().getTime())
  )
})

console.log(Person.make({ name: "name1" }))
/*
Example Output:
{ age: 0, timestamp: 1714232909221, name: 'name1' }
*/

console.log(Person.make({ name: "name2" }))
/*
Example Output:
{ age: 0, timestamp: 1714232909227, name: 'name2' }
*/

跨模式重用默认值

默认值也是”可移植的”，这意味着如果您在另一个模式中重用相同的属性签名，默认值会被传递：

示例（在另一个模式中重用默认值）

import { Schema } from "effect"

const Person = Schema.Struct({
  name: Schema.NonEmptyString,
  age: Schema.Number.pipe(
    Schema.propertySignature,
    Schema.withConstructorDefault(() => 0)
  ),
  timestamp: Schema.Number.pipe(
    Schema.propertySignature,
    Schema.withConstructorDefault(() => new Date().getTime())
  )
})

const AnotherSchema = Schema.Struct({
  foo: Schema.String,
  age: Person.fields.age
})

console.log(AnotherSchema.make({ foo: "bar" }))
/*
Output:
{ foo: 'bar', age: 0 }
*/

在类中使用默认值

在使用Class API时也可以应用默认值，确保基于类的模式的一致性。

示例（类中的默认值）

import { Schema } from "effect"

class Person extends Schema.Class<Person>("Person")({
  name: Schema.NonEmptyString,
  age: Schema.Number.pipe(
    Schema.propertySignature,
    Schema.withConstructorDefault(() => 0)
  ),
  timestamp: Schema.Number.pipe(
    Schema.propertySignature,
    Schema.withConstructorDefault(() => new Date().getTime())
  )
}) {}

console.log(new Person({ name: "name1" }))
/*
Example Output:
Person { age: 0, timestamp: 1714400867208, name: 'name1' }
*/

console.log(new Person({ name: "name2" }))
/*
Example Output:
Person { age: 0, timestamp: 1714400867215, name: 'name2' }
*/