过滤器

开发人员可以定义超越基本类型检查的自定义验证逻辑，从而更好地控制数据验证方式。

声明过滤器

过滤器使用 Schema.filter 函数声明。此函数需要两个参数：要验证的模式和谓词函数。谓词函数是用户定义的，用于确定数据是否满足条件。如果数据验证失败，可以提供错误消息。

示例（定义最小字符串长度过滤器）

import { Schema } from "effect"

// 定义一个带有过滤器的字符串模式，以确保字符串
// 至少有 10 个字符长
const LongString = Schema.String.pipe(
  Schema.filter(
    // 对于少于 10 个字符的字符串的自定义错误消息
    (s) => s.length >= 10 || "a string at least 10 characters long"
  )
)

//     ┌─── string
//     ▼
type Type = typeof LongString.Type

console.log(Schema.decodeUnknownSync(LongString)("a"))
/*
抛出：
ParseError: { string | filter }
└─ Predicate refinement failure
   └─ a string at least 10 characters long
*/

请注意，过滤器不会改变模式的 Type：

//     ┌─── string
//     ▼
type Type = typeof LongString.Type

过滤器添加额外的验证约束，而不修改模式的底层类型。

Tip

如果您需要修改 Type，请考虑使用品牌类型。

谓词函数

过滤器中的谓词函数遵循以下结构：

type Predicate = (
  a: A,
  options: ParseOptions,
  self: AST.Refinement
) => FilterReturnType

其中

interface FilterIssue {
  readonly path: ReadonlyArray<PropertyKey>
  readonly issue: string | ParseResult.ParseIssue
}

type FilterOutput =
  | undefined
  | boolean
  | string
  | ParseResult.ParseIssue
  | FilterIssue

type FilterReturnType = FilterOutput | ReadonlyArray<FilterOutput>

过滤器的谓词可以返回几种类型的值，每种都以不同的方式影响验证：

返回类型	行为
true 或 undefined	数据满足过滤器的条件并通过验证。
false	数据不满足条件，且不提供特定的错误消息。
string	验证失败，提供的字符串用作错误消息。
ParseResult.ParseIssue	验证失败并提供详细的错误结构，指定失败的位置和原因。
FilterIssue	允许使用特定路径提供更详细的错误消息，提供增强的错误报告。
ReadonlyArray<FilterOutput>	如果需要报告多个验证错误，可以返回问题数组。

效果过滤器

普通过滤器只处理同步、无副作用的验证。如果您需要涉及异步逻辑或副作用的过滤器，请考虑使用 Schema.filterEffect。

添加注解

在模式中嵌入元数据，如标识符、JSON模式规范和描述，可以增强对模式约束和目的的理解和分析。

示例（使用注解添加元数据）

import { Schema, JSONSchema } from "effect"

const LongString = Schema.String.pipe(
  Schema.filter(
    (s) =>
      s.length >= 10 ? undefined : "a string at least 10 characters long",
    {
      identifier: "LongString",
      jsonSchema: { minLength: 10 },
      description: "Lorem ipsum dolor sit amet, ..."
    }
  )
)

console.log(Schema.decodeUnknownSync(LongString)("a"))
/*
抛出：
ParseError: LongString
└─ Predicate refinement failure
   └─ a string at least 10 characters long
*/

console.log(JSON.stringify(JSONSchema.make(LongString), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$defs": {
    "LongString": {
      "type": "string",
      "description": "Lorem ipsum dolor sit amet, ...",
      "minLength": 10
    }
  },
  "$ref": "#/$defs/LongString"
}
*/

指定错误路径

在验证表单或结构化数据时，可以将特定的错误消息与特定的字段或路径关联。这增强了错误报告，在与react-hook-form等库集成时特别有用。

示例（匹配密码）

import { Either, Schema, ParseResult } from "effect"

const Password = Schema.Trim.pipe(Schema.minLength(2))

const MyForm = Schema.Struct({
  password: Password,
  confirm_password: Password
}).pipe(
  // 添加过滤器以确保密码匹配
  Schema.filter((input) => {
    if (input.password !== input.confirm_password) {
      // 返回与"confirm_password"字段关联的错误消息
      return {
        path: ["confirm_password"],
        message: "Passwords do not match"
      }
    }
  })
)

console.log(
  JSON.stringify(
    Schema.decodeUnknownEither(MyForm)({
      password: "abc",
      confirm_password: "abd" // 确认密码不匹配
    }).pipe(
      Either.mapLeft((error) =>
        ParseResult.ArrayFormatter.formatErrorSync(error)
      )
    ),
    null,
    2
  )
)
/*
  "_id": "Either",
  "_tag": "Left",
  "left": [
    {
      "_tag": "Type",
      "path": [
        "confirm_password"
      ],
      "message": "Passwords do not match"
    }
  ]
}
*/

在此示例中，我们定义了一个带有两个密码字段（password和confirm_password）的MyForm模式。我们使用Schema.filter来检查两个密码是否匹配。如果不匹配，将返回一个错误消息，特别与confirm_password字段关联。这使得更容易精确定位验证失败的位置。

错误使用ArrayFormatter以结构化方式格式化，便于后处理和与表单库集成。

Using ArrayFormatter for Structured Errors

The ArrayFormatter provides a detailed and structured error format rather than a simple error string. This is especially useful when handling complex forms or structured data. For more information, see ArrayFormatter.

多重错误报告

Schema.filter API支持一次报告多个验证问题，这在表单验证等场景中特别有用，因为可能同时有多个检查失败。

示例（报告多个验证错误）

import { Either, Schema, ParseResult } from "effect"

const Password = Schema.Trim.pipe(Schema.minLength(2))
const OptionalString = Schema.optional(Schema.String)

const MyForm = Schema.Struct({
  password: Password,
  confirm_password: Password,
  name: OptionalString,
  surname: OptionalString
}).pipe(
  Schema.filter((input) => {
    const issues: Array<Schema.FilterIssue> = []

    // 检查密码是否匹配
    if (input.password !== input.confirm_password) {
      issues.push({
        path: ["confirm_password"],
        message: "Passwords do not match"
      })
    }

    // 确保姓名或姓氏至少存在一个
    if (!input.name && !input.surname) {
      issues.push({
        path: ["surname"],
        message: "Surname must be present if name is not present"
      })
    }
    return issues
  })
)

console.log(
  JSON.stringify(
    Schema.decodeUnknownEither(MyForm)({
      password: "abc",
      confirm_password: "abd" // 确认密码不匹配
    }).pipe(
      Either.mapLeft((error) =>
        ParseResult.ArrayFormatter.formatErrorSync(error)
      )
    ),
    null,
    2
  )
)
/*
{
  "_id": "Either",
  "_tag": "Left",
  "left": [
    {
      "_tag": "Type",
      "path": [
        "confirm_password"
      ],
      "message": "Passwords do not match"
    },
    {
      "_tag": "Type",
      "path": [
        "surname"
      ],
      "message": "Surname must be present if name is not present"
    }
  ]
}
*/

在此示例中，我们定义了一个MyForm模式，包含密码验证字段和可选的姓名/姓氏字段。Schema.filter函数检查密码是否匹配，并确保提供姓名或姓氏中的至少一个。如果任一验证失败，相应的错误消息将与相关字段关联，并以结构化格式返回两个错误。

Using ArrayFormatter for Structured Errors

The ArrayFormatter provides a detailed and structured error format rather than a simple error string. This is especially useful when handling complex forms or structured data. For more information, see ArrayFormatter.

暴露的值

对于带有过滤器的模式，您可以使用from属性访问基础模式（应用过滤器之前的模式）：

import { Schema } from "effect"

const LongString = Schema.String.pipe(
  Schema.filter((s) => s.length >= 10)
)

// 访问基础模式，即应用过滤器之前的字符串模式
//
//      ┌─── typeof Schema.String
//      ▼
const From = LongString.from

内置过滤器

字符串过滤器

以下是Schema模块提供的有用字符串过滤器列表：

import { Schema } from "effect"

// 指定字符串的最大长度
Schema.String.pipe(Schema.maxLength(5))

// 指定字符串的最小长度
Schema.String.pipe(Schema.minLength(5))

// 等同于minLength(1)
Schema.String.pipe(Schema.nonEmptyString())
// or
Schema.NonEmptyString

// 指定字符串的确切长度
Schema.String.pipe(Schema.length(5))

// 指定字符串长度的范围
Schema.String.pipe(Schema.length({ min: 2, max: 4 }))

// 根据正则表达式模式匹配字符串
Schema.String.pipe(Schema.pattern(/^[a-z]+$/))

// 确保字符串以特定子字符串开头
Schema.String.pipe(Schema.startsWith("prefix"))

// 确保字符串以特定子字符串结尾
Schema.String.pipe(Schema.endsWith("suffix"))

// 检查字符串是否包含特定子字符串
Schema.String.pipe(Schema.includes("substring"))

// 验证字符串没有前导或尾随空格
Schema.String.pipe(Schema.trimmed())

// 验证字符串完全是小写
Schema.String.pipe(Schema.lowercased())

// 验证字符串完全是大写
Schema.String.pipe(Schema.uppercased())

// 验证字符串是首字母大写
Schema.String.pipe(Schema.capitalized())

// 验证字符串是首字母小写
Schema.String.pipe(Schema.uncapitalized())

Trim vs Trimmed

The trimmed combinator does not make any transformations, it only validates. If what you were looking for was a combinator to trim strings, then check out the trim combinator or the Trim schema.

数字过滤器

以下是Schema模块提供的有用数字过滤器列表：

import { Schema } from "effect"

// 指定大于5的数字
Schema.Number.pipe(Schema.greaterThan(5))

// 指定大于或等于5的数字
Schema.Number.pipe(Schema.greaterThanOrEqualTo(5))

// 指定小于5的数字
Schema.Number.pipe(Schema.lessThan(5))

// 指定小于或等于5的数字
Schema.Number.pipe(Schema.lessThanOrEqualTo(5))

// 指定-2到2之间的数字，包含边界
Schema.Number.pipe(Schema.between(-2, 2))

// 指定值必须是整数
Schema.Number.pipe(Schema.int())
// or
Schema.Int

// 确保值不是NaN
Schema.Number.pipe(Schema.nonNaN())
// or
Schema.NonNaN

// 确保提供的值是有限数字
// （排除NaN、+Infinity和-Infinity）
Schema.Number.pipe(Schema.finite())
// or
Schema.Finite

// 指定正数（> 0）
Schema.Number.pipe(Schema.positive())
// or
Schema.Positive

// 指定非负数（>= 0）
Schema.Number.pipe(Schema.nonNegative())
// or
Schema.NonNegative

// 非负整数
Schema.NonNegativeInt

// 指定负数（< 0）
Schema.Number.pipe(Schema.negative())
// or
Schema.Negative

// 指定非正数（<= 0）
Schema.Number.pipe(Schema.nonPositive())
// or
Schema.NonPositive

// 指定能被5整除的数字
Schema.Number.pipe(Schema.multipleOf(5))

// 8位无符号整数（0到255）
Schema.Uint8

只读数组过滤器

以下是Schema模块提供的有用数组过滤器列表：

import { Schema } from "effect"

// 指定数组中项目的最大数量
Schema.Array(Schema.Number).pipe(Schema.maxItems(2))

// 指定数组中项目的最小数量
Schema.Array(Schema.Number).pipe(Schema.minItems(2))

// 指定数组中项目的确切数量
Schema.Array(Schema.Number).pipe(Schema.itemsCount(2))

日期过滤器

import { Schema } from "effect"

// 指定有效日期（拒绝像`new Date("Invalid Date")`这样的值）
Schema.DateFromSelf.pipe(Schema.validDate())
// or
Schema.ValidDateFromSelf

// 指定大于当前日期的日期
Schema.Date.pipe(Schema.greaterThanDate(new Date()))

// 指定大于或等于当前日期的日期
Schema.Date.pipe(Schema.greaterThanOrEqualToDate(new Date()))

// 指定小于当前日期的日期
Schema.Date.pipe(Schema.lessThanDate(new Date()))

// 指定小于或等于当前日期的日期
Schema.Date.pipe(Schema.lessThanOrEqualToDate(new Date()))

// 指定两个日期之间的日期
Schema.Date.pipe(Schema.betweenDate(new Date(0), new Date()))

BigInt过滤器

以下是Schema模块提供的有用BigInt过滤器列表：

import { Schema } from "effect"

// 指定大于5的BigInt
Schema.BigInt.pipe(Schema.greaterThanBigInt(5n))

// 指定大于或等于5的BigInt
Schema.BigInt.pipe(Schema.greaterThanOrEqualToBigInt(5n))

// 指定小于5的BigInt
Schema.BigInt.pipe(Schema.lessThanBigInt(5n))

// 指定小于或等于5的BigInt
Schema.BigInt.pipe(Schema.lessThanOrEqualToBigInt(5n))

// 指定-2n到2n之间的BigInt，包含边界
Schema.BigInt.pipe(Schema.betweenBigInt(-2n, 2n))

// 指定正BigInt（> 0n）
Schema.BigInt.pipe(Schema.positiveBigInt())
// or
Schema.PositiveBigIntFromSelf

// 指定非负BigInt（>= 0n）
Schema.BigInt.pipe(Schema.nonNegativeBigInt())
// or
Schema.NonNegativeBigIntFromSelf

// 指定负BigInt（< 0n）
Schema.BigInt.pipe(Schema.negativeBigInt())
// or
Schema.NegativeBigIntFromSelf

// 指定非正BigInt（<= 0n）
Schema.BigInt.pipe(Schema.nonPositiveBigInt())
// or
Schema.NonPositiveBigIntFromSelf

BigDecimal过滤器

以下是Schema模块提供的有用BigDecimal过滤器列表：

import { Schema, BigDecimal } from "effect"

// 指定大于5的BigDecimal
Schema.BigDecimal.pipe(
  Schema.greaterThanBigDecimal(BigDecimal.unsafeFromNumber(5))
)

// 指定大于或等于5的BigDecimal
Schema.BigDecimal.pipe(
  Schema.greaterThanOrEqualToBigDecimal(BigDecimal.unsafeFromNumber(5))
)
// 指定小于5的BigDecimal
Schema.BigDecimal.pipe(
  Schema.lessThanBigDecimal(BigDecimal.unsafeFromNumber(5))
)

// 指定小于或等于5的BigDecimal
Schema.BigDecimal.pipe(
  Schema.lessThanOrEqualToBigDecimal(BigDecimal.unsafeFromNumber(5))
)

// 指定-2到2之间的BigDecimal，包含边界
Schema.BigDecimal.pipe(
  Schema.betweenBigDecimal(
    BigDecimal.unsafeFromNumber(-2),
    BigDecimal.unsafeFromNumber(2)
  )
)

// 指定正BigDecimal（> 0）
Schema.BigDecimal.pipe(Schema.positiveBigDecimal())

// 指定非负BigDecimal（>= 0）
Schema.BigDecimal.pipe(Schema.nonNegativeBigDecimal())

// 指定负BigDecimal（< 0）
Schema.BigDecimal.pipe(Schema.negativeBigDecimal())

// 指定非正BigDecimal（<= 0）
Schema.BigDecimal.pipe(Schema.nonPositiveBigDecimal())

持续时间过滤器

以下是Schema模块提供的有用持续时间过滤器列表：

import { Schema } from "effect"

// 指定大于5秒的持续时间
Schema.Duration.pipe(Schema.greaterThanDuration("5 seconds"))

// 指定大于或等于5秒的持续时间
Schema.Duration.pipe(Schema.greaterThanOrEqualToDuration("5 seconds"))

// 指定小于5秒的持续时间
Schema.Duration.pipe(Schema.lessThanDuration("5 seconds"))

// 指定小于或等于5秒的持续时间
Schema.Duration.pipe(Schema.lessThanOrEqualToDuration("5 seconds"))

// 指定5秒到10秒之间的持续时间，包含边界
Schema.Duration.pipe(Schema.betweenDuration("5 seconds", "10 seconds"))