Schema 注解

Schema 设计的关键特性之一是其灵活性和可定制能力。 这是通过”注解”实现的。 模式的 ast 字段中的每个节点都有一个 annotations: Record<string | symbol, unknown> 字段， 它允许您向模式附加额外信息。 您可以使用 annotations 方法或 Schema.annotations API 来管理这些注解。

示例（使用注解自定义模式）

import { Schema } from "effect"

// 定义一个 Password 模式，从字符串类型开始
const Password = Schema.String
  // 为非字符串值添加自定义错误消息
  .annotations({ message: () => "not a string" })
  .pipe(
    // 强制非空字符串并提供自定义错误消息
    Schema.nonEmptyString({ message: () => "required" }),
    // 将字符串长度限制为 10 个字符或更少
    // 并为超出长度提供自定义错误消息
    Schema.maxLength(10, {
      message: (issue) => `${issue.actual} is too long`
    })
  )
  .annotations({
    // 为模式添加唯一标识符
    identifier: "Password",
    // 为模式提供标题
    title: "password",
    // 包含解释此模式代表什么的描述
    description:
      "A password is a secret string used to authenticate a user",
    // 添加示例以提高清晰度
    examples: ["1Ki77y", "jelly22fi$h"],
    // 包含任何额外的文档
    documentation: `...technical information on Password schema...`
  })

内置注解

下表提供了常见内置注解及其用途的概述：

注解	描述
identifier	为模式分配唯一标识符，适用于 TypeScript 标识符和代码生成目的。通常在 TreeFormatter 等工具中使用以澄清输出。示例包括 "Person"、"Product"。
title	为模式设置简短的描述性标题，类似于 JSON Schema 标题。对文档或 UI 标题很有用。它也被 TreeFormatter 用来增强错误消息的可读性。
description	提供关于模式目的的详细解释，类似于 JSON Schema 描述。被 TreeFormatter 用来提供更详细的错误消息。
documentation	为模式扩展详细文档，对开发人员或自动文档生成有益。
examples	列出有效模式值的示例，类似于 JSON Schema 中的示例属性，对文档和验证测试很有用。
default	为模式定义默认值，类似于 JSON Schema 中的默认属性，以确保模式在适用的地方预先填充。
message	自定义验证失败的错误消息，在解码或验证错误期间改善 TreeFormatter 和 ArrayFormatter 等工具输出的清晰度。
jsonSchema	指定影响 JSON Schema 文档生成的注解，自定义模式的表示方式。
arbitrary	配置生成 Arbitrary 测试数据的设置。
pretty	配置生成 Pretty 输出的设置。
equivalence	配置评估数据 Equivalence 的设置。
concurrency	控制并发行为，确保模式在并发操作下表现最佳。有关详细用法，请参阅并发注解。
batching	管理批处理操作的设置，以在可以分组操作时提高性能。
parseIssueTitle	为解析问题提供自定义标题，增强 TreeFormatter 输出中的错误描述。有关更多信息，请参阅 ParseIssueTitle 注解。
parseOptions	允许在模式级别覆盖解析选项，提供对解析行为的精细控制。有关应用详细信息，请参阅在模式级别自定义解析行为。
decodingFallback	提供一种定义自定义回退行为的方法，当解码操作失败时触发。有关详细用法，请参阅使用回退处理解码错误。

Concurrency Annotation

For more complex schemas like Struct, Array, or Union that contain multiple nested schemas, the concurrency annotation provides a way to control how validations are executed concurrently.

type ConcurrencyAnnotation = number | "unbounded" | "inherit" | undefined

Here’s a shorter version presented in a table:

Value	Description
number	Limits the maximum number of concurrent tasks.
"unbounded"	All tasks run concurrently with no limit.
"inherit"	Inherits concurrency settings from the parent context.
undefined	Tasks run sequentially, one after the other (default behavior).

Example (Sequential Execution)

In this example, we define three tasks that simulate asynchronous operations with different durations. Since no concurrency is specified, the tasks are executed sequentially, one after the other.

import { Schema } from "effect"
import type { Duration } from "effect"
import { Effect } from "effect"

// Simulates an async task
const item = (id: number, duration: Duration.DurationInput) =>
  Schema.String.pipe(
    Schema.filterEffect(() =>
      Effect.gen(function* () {
        yield* Effect.sleep(duration)
        console.log(`Task ${id} done`)
        return true
      })
    )
  )

const Sequential = Schema.Tuple(
  item(1, "30 millis"),
  item(2, "10 millis"),
  item(3, "20 millis")
)

Effect.runPromise(Schema.decode(Sequential)(["a", "b", "c"]))
/*
Output:
Task 1 done
Task 2 done
Task 3 done
*/

Example (Concurrent Execution)

By adding a concurrency annotation set to "unbounded", the tasks can now run concurrently, meaning they don’t wait for one another to finish before starting. This allows faster execution when multiple tasks are involved.

import { Schema } from "effect"
import type { Duration } from "effect"
import { Effect } from "effect"

// Simulates an async task
const item = (id: number, duration: Duration.DurationInput) =>
  Schema.String.pipe(
    Schema.filterEffect(() =>
      Effect.gen(function* () {
        yield* Effect.sleep(duration)
        console.log(`Task ${id} done`)
        return true
      })
    )
  )

const Concurrent = Schema.Tuple(
  item(1, "30 millis"),
  item(2, "10 millis"),
  item(3, "20 millis")
).annotations({ concurrency: "unbounded" })

Effect.runPromise(Schema.decode(Concurrent)(["a", "b", "c"]))
/*
Output:
Task 2 done
Task 3 done
Task 1 done
*/

Handling Decoding Errors with Fallbacks

The DecodingFallbackAnnotation allows you to handle decoding errors by providing a custom fallback logic.

type DecodingFallbackAnnotation<A> = (
  issue: ParseIssue
) => Effect<A, ParseIssue>

This annotation enables you to specify fallback behavior when decoding fails, making it possible to recover gracefully from errors.

Example (Basic Fallback)

In this basic example, when decoding fails (e.g., the input is null), the fallback value is returned instead of an error.

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

// Schema with a fallback value
const schema = Schema.String.annotations({
  decodingFallback: () => Either.right("<fallback>")
})

console.log(Schema.decodeUnknownSync(schema)("valid input"))
// Output: valid input

console.log(Schema.decodeUnknownSync(schema)(null))
// Output: <fallback>

Example (Advanced Fallback with Logging)

In this advanced example, when a decoding error occurs, the schema logs the issue and then returns a fallback value. This demonstrates how you can incorporate logging and other side effects during error handling.

import { Schema } from "effect"
import { Effect } from "effect"

// Schema with logging and fallback
const schemaWithLog = Schema.String.annotations({
  decodingFallback: (issue) =>
    Effect.gen(function* () {
      // Log the error issue
      yield* Effect.log(issue._tag)
      // Simulate a delay
      yield* Effect.sleep(10)
      // Return a fallback value
      return yield* Effect.succeed("<fallback>")
    })
})

// Run the effectful fallback logic
Effect.runPromise(Schema.decodeUnknown(schemaWithLog)(null)).then(
  console.log
)
/*
Output:
timestamp=2024-07-25T13:22:37.706Z level=INFO fiber=#0 message=Type
<fallback>
*/

Custom Annotations

In addition to built-in annotations, you can define custom annotations to meet specific requirements. For instance, here’s how to create a deprecated annotation:

Example (Defining a Custom Annotation)

import { Schema } from "effect"

// Define a unique identifier for your custom annotation
const DeprecatedId = Symbol.for(
  "some/unique/identifier/for/your/custom/annotation"
)

// Apply the custom annotation to the schema
const MyString = Schema.String.annotations({ [DeprecatedId]: true })

console.log(MyString)
/*
Output:
[class SchemaClass] {
  ast: StringKeyword {
    annotations: {
      [Symbol(@effect/docs/schema/annotation/Title)]: 'string',
      [Symbol(@effect/docs/schema/annotation/Description)]: 'a string',
      [Symbol(some/unique/identifier/for/your/custom/annotation)]: true
    },
    _tag: 'StringKeyword'
  },
  ...
}
*/

To make your new custom annotation type-safe, you can use a module augmentation. In the next example, we want our custom annotation to be a boolean.

Example (Adding Type Safety to Custom Annotations)

import { Schema } from "effect"

const DeprecatedId = Symbol.for(
  "some/unique/identifier/for/your/custom/annotation"
)

// Module augmentation
declare module "effect/Schema" {
  namespace Annotations {
    interface GenericSchema<A> extends Schema<A> {
      [DeprecatedId]?: boolean
    }
  }
}

const MyString = Schema.String.annotations({
  [DeprecatedId]: "bad value"
Error ts(2418)  ― Type of computed property's value is 'string', which is not assignable to type 'boolean'.
})

You can retrieve custom annotations using the SchemaAST.getAnnotation helper function.

Example (Retrieving a Custom Annotation)

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

const DeprecatedId = Symbol.for(
  "some/unique/identifier/for/your/custom/annotation"
)

declare module "effect/Schema" {
  namespace Annotations {
    interface GenericSchema<A> extends Schema<A> {
      [DeprecatedId]?: boolean
    }
  }
}

const MyString = Schema.String.annotations({ [DeprecatedId]: true })

// Helper function to check if a schema is marked as deprecated
const isDeprecated = <A, I, R>(schema: Schema.Schema<A, I, R>): boolean =>
  SchemaAST.getAnnotation<boolean>(DeprecatedId)(schema.ast).pipe(
    Option.getOrElse(() => false)
  )

console.log(isDeprecated(Schema.String))
// Output: false

console.log(isDeprecated(MyString))
// Output: true