Schema 转换

在使用模式时，转换非常重要。它们允许您将数据从一种类型更改为另一种类型。例如，您可能将字符串解析为数字或将日期字符串转换为 Date 对象。

Schema.transform 和 Schema.transformOrFail 函数帮助您连接两个模式，以便您可以在它们之间转换数据。

transform

Schema.transform 通过获取一个模式（“源”）的输出并将其作为另一个模式（“目标”）的输入来创建新模式。当您知道转换总是会成功时使用此方法。如果可能失败，请改用 Schema.transformOrFail。

理解输入和输出

“输出”和”输入”取决于您正在执行的操作（解码或编码）：

解码时：

• 源模式 Schema<SourceType, SourceEncoded> 产生 SourceType。
• 目标模式 Schema<TargetType, TargetEncoded> 期望 TargetEncoded。
• 解码路径如下所示：SourceEncoded → TargetType。

如果 SourceType 和 TargetEncoded 不同，您可以提供 decode 函数将源模式的输出转换为目标模式的输入。

编码时：

• 目标模式 Schema<TargetType, TargetEncoded> 产生 TargetEncoded。
• 源模式 Schema<SourceType, SourceEncoded> 期望 SourceType。
• 编码路径如下所示：TargetType → SourceEncoded。

如果 TargetEncoded 和 SourceType 不同，您可以提供 encode 函数将目标模式的输出转换为源模式的输入。

组合两个基础模式

在此示例中，我们从接受 "on" 或 "off" 的模式开始，并将其转换为布尔模式。decode 函数将 "on" 转换为 true，将 "off" 转换为 false。encode 函数执行相反的操作。这为我们提供了 Schema<boolean, "on" | "off">。

示例（将字符串转换为布尔值）

import { Schema } from "effect"

// 将 "on"/"off" 转换为布尔值并返回
const BooleanFromString = Schema.transform(
  // 源模式："on" 或 "off"
  Schema.Literal("on", "off"),
  // 目标模式：布尔值
  Schema.Boolean,
  {
    // 可选，但您可以从 TypeScript 获得更好的错误消息
    strict: true,
    // 转换以将源模式的输出（"on" | "off"）
    // 转换为目标模式的输入（布尔值）
    decode: (literal) => literal === "on", // 这里总是成功
    // 反向转换
    encode: (bool) => (bool ? "on" : "off")
  }
)

//     ┌─── "on" | "off"
//     ▼
type Encoded = typeof BooleanFromString.Encoded

//     ┌─── boolean
//     ▼
type Type = typeof BooleanFromString.Type

console.log(Schema.decodeUnknownSync(BooleanFromString)("on"))
// 输出：true

上面的decode函数本身永远不会失败。但是，如果输入不符合源模式，完整的解码过程仍然可能失败。例如，如果您提供"wrong"而不是"on"或"off"，源模式将在调用decode之前失败。

示例（处理无效输入）

import { Schema } from "effect"

// Convert "on"/"off" to boolean and back
const BooleanFromString = Schema.transform(
  Schema.Literal("on", "off"),
  Schema.Boolean,
  {
    strict: true,
    decode: (s) => s === "on",
    encode: (bool) => (bool ? "on" : "off")
  }
)

// 提供源模式不允许的输入
Schema.decodeUnknownSync(BooleanFromString)("wrong")
/*
抛出：
ParseError: ("on" | "off" <-> boolean)
└─ Encoded side transformation failure
   └─ "on" | "off"
      ├─ Expected "on", actual "wrong"
      └─ Expected "off", actual "wrong"
*/

组合两个转换模式

以下是源模式和目标模式都转换其数据的示例：

• 源模式是Schema.NumberFromString，即Schema<number, string>。
• 目标模式是BooleanFromString（上面定义的），即Schema<boolean, "on" | "off">。

此示例涉及四种类型并需要两次转换：

• 解码时，将number转换为"on" | "off"。例如，将任何正数视为"on"。
• 编码时，将"on" | "off"转换回number。例如，将"on"视为1，将"off"视为-1。

通过组合这些转换，我们得到一个将字符串解码为布尔值并将布尔值编码回字符串的模式。结果模式是Schema<boolean, string>。

示例（组合两个转换模式）

import { Schema } from "effect"

// Convert "on"/"off" to boolean and back
const BooleanFromString = Schema.transform(
  Schema.Literal("on", "off"),
  Schema.Boolean,
  {
    strict: true,
    decode: (s) => s === "on",
    encode: (bool) => (bool ? "on" : "off")
  }
)

const BooleanFromNumericString = Schema.transform(
  // Source schema: Convert string -> number
  Schema.NumberFromString,
  // Target schema: Convert "on"/"off" -> boolean
  BooleanFromString,
  {
    strict: true,
    // 如果数字为正，使用"on"，否则使用"off"
    decode: (n) => (n > 0 ? "on" : "off"),
    // 如果布尔值为"on"，使用1，否则使用-1
    encode: (bool) => (bool === "on" ? 1 : -1)
  }
)

//     ┌─── string
//     ▼
type Encoded = typeof BooleanFromNumericString.Encoded

//     ┌─── boolean
//     ▼
type Type = typeof BooleanFromNumericString.Type

console.log(Schema.decodeUnknownSync(BooleanFromNumericString)("100"))
// 输出：true

示例（将数组转换为ReadonlySet）

在此示例中，我们将数组转换为ReadonlySet。decode函数接受一个数组并创建一个新的ReadonlySet。encode函数将集合转换回数组。我们还提供数组项的模式，以便它们得到正确验证。

import { Schema } from "effect"

// 此函数构建一个在只读数组和只读项集合之间转换的模式
const ReadonlySetFromArray = <A, I, R>(
  itemSchema: Schema.Schema<A, I, R>
): Schema.Schema<ReadonlySet<A>, ReadonlyArray<I>, R> =>
  Schema.transform(
    // 源模式：项目数组
    Schema.Array(itemSchema),
    // 目标模式：只读项集合
    // **重要** 我们在这里使用`Schema.typeSchema`来获取项的模式
    // 以避免对元素进行两次解码
    Schema.ReadonlySetFromSelf(Schema.typeSchema(itemSchema)),
    {
      strict: true,
      decode: (items) => new Set(items),
      encode: (set) => Array.from(set.values())
    }
  )

const schema = ReadonlySetFromArray(Schema.String)

//     ┌─── readonly string[]
//     ▼
type Encoded = typeof schema.Encoded

//     ┌─── ReadonlySet<string>
//     ▼
type Type = typeof schema.Type

console.log(Schema.decodeUnknownSync(schema)(["a", "b", "c"]))
// 输出：Set(3) { 'a', 'b', 'c' }

console.log(Schema.encodeSync(schema)(new Set(["a", "b", "c"])))
// 输出：[ 'a', 'b', 'c' ]

Why Schema.typeSchema is used

Please note that to define the target schema, we used Schema.typeSchema. This is because the decoding/encoding of the elements is already handled by the from schema: Schema.Array(itemSchema), avoiding double decoding.

非严格选项

在某些情况下，严格的类型检查可能在数据转换过程中造成问题，特别是当类型在特定转换中可能略有不同时。为了解决这些场景，Schema.transform提供了strict: false选项，它放宽类型约束并允许更灵活的转换。

示例（创建限制构造函数）

让我们考虑这样一个场景：您需要定义一个构造函数clamp，确保数字在特定范围内。此函数返回一个将数字”限制”到指定最小和最大范围的模式：

import { Schema, Number } from "effect"

const clamp =
  (minimum: number, maximum: number) =>
  <A extends number, I, R>(self: Schema.Schema<A, I, R>) =>
    Schema.transform(
      // 源模式
      self,
      // 目标模式：基于最小/最大范围过滤
      self.pipe(
        Schema.typeSchema,
        Schema.filter((a) => a <= minimum || a >= maximum)
      ),
      {
Error ts(2345)  ― Argument of type '{ strict: true; decode: (a: A) => number; encode: (a: A) => A; }' is not assignable to parameter of type '{ readonly decode: (fromA: A, fromI: I) => A; readonly encode: (toI: A, toA: A) => A; readonly strict?: true; } | { readonly decode: (fromA: A, fromI: I) => unknown; readonly encode: (toI: A, toA: A) => unknown; readonly strict: false; }'.
  The types returned by 'decode(...)' are incompatible between these types.
    Type 'number' is not assignable to type 'A'.
      'number' is assignable to the constraint of type 'A', but 'A' could be instantiated with a different subtype of constraint 'number'.
        strict: true,
        // 将数字限制在指定范围内
        decode: (a) => Number.clamp(a, { minimum, maximum }),
        encode: (a) => a
      }
    )

在此示例中，Number.clamp返回一个可能不被识别为特定A类型的number，这在严格检查下导致类型不匹配。

有两种方法可以解决这个问题：

1. 使用类型断言： 添加类型转换可以强制将返回类型视为类型A：

   decode: (a) => Number.clamp(a, { minimum, maximum }) as A

2. 使用非严格选项： 在转换选项中设置strict: false允许模式绕过TypeScript的一些类型检查规则，适应类型差异：

   import { Schema, Number } from "effect"
   
   const clamp =
     (minimum: number, maximum: number) =>
     <A extends number, I, R>(self: Schema.Schema<A, I, R>) =>
       Schema.transform(
         self,
         self.pipe(
           Schema.typeSchema,
           Schema.filter((a) => a >= minimum && a <= maximum)
         ),
         {
           strict: false,
           decode: (a) => Number.clamp(a, { minimum, maximum }),
           encode: (a) => a
         }
       )

transformOrFail

虽然Schema.transform函数适用于无错误转换， Schema.transformOrFail函数专为更复杂的场景而设计，其中转换可能在解码或编码阶段失败。

此函数使解码/编码函数能够返回成功结果或错误， 使其特别适用于验证和处理可能不总是符合预期格式的数据。

错误处理

Schema.transformOrFail函数利用ParseResult模块来管理潜在错误：

构造函数	描述
ParseResult.succeed	表示成功的转换，没有发生错误。
ParseResult.fail	表示失败的转换，基于提供的ParseIssue创建新的ParseError。

此外，ParseResult模块提供了处理各种类型解析问题的构造函数，例如：

解析问题类型	描述
Type	表示类型不匹配错误。
Missing	当缺少必需字段时使用。
Unexpected	用于模式中不允许的意外字段。
Forbidden	标记模式禁止的解码或编码操作。
Pointer	指向数据中发生问题的特定位置。
Refinement	当值不满足特定细化或约束时使用。
Transformation	标记从一种类型转换为另一种类型时发生的问题。
Composite	表示复合错误，将多个问题合并为一个，对分组错误很有帮助。

这些工具允许详细和特定的错误处理，增强数据处理操作的可靠性。

示例（将字符串转换为数字）

Schema.transformOrFail的常见用例是将数字的字符串表示转换为实际的数字类型。这种场景在处理用户输入或来自外部源的数据时很典型。

import { ParseResult, Schema } from "effect"

export const NumberFromString = Schema.transformOrFail(
  // 源模式：接受任何字符串
  Schema.String,
  // 目标模式：期望数字
  Schema.Number,
  {
    // 可选，但您可以从TypeScript获得更好的错误消息
    strict: true,
    decode: (input, options, ast) => {
      const parsed = parseFloat(input)
      // 如果解析失败（NaN），返回带有自定义错误的ParseError
      if (isNaN(parsed)) {
        return ParseResult.fail(
          // 创建类型不匹配错误
          new ParseResult.Type(
            // 提供模式的抽象语法树作为上下文
            ast,
            // 包含有问题的输入
            input,
            // 可选的自定义错误消息
            "Failed to convert string to number"
          )
        )
      }
      return ParseResult.succeed(parsed)
    },
    encode: (input, options, ast) => ParseResult.succeed(input.toString())
  }
)

//     ┌─── string
//     ▼
type Encoded = typeof NumberFromString.Encoded

//     ┌─── number
//     ▼
type Type = typeof NumberFromString.Type

console.log(Schema.decodeUnknownSync(NumberFromString)("123"))
// 输出：123

console.log(Schema.decodeUnknownSync(NumberFromString)("-"))
/*
抛出：
ParseError: (string <-> number)
└─ Transformation process failure
   └─ Failed to convert string to number
*/

无论是decode还是encode函数，不仅接收要转换的值（input），还接收用户在使用结果模式时设置的解析选项，以及ast，它表示您正在转换的模式的低级定义。

异步转换

在现代应用程序中，特别是那些与外部API交互的应用程序，您可能需要异步转换数据。Schema.transformOrFail通过允许您返回Effect来支持异步转换。

示例（通过API调用验证数据）

考虑这样一个场景：您需要通过进行API调用来验证人员的ID。以下是您可以实现它的方法：

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

// 定义进行API请求的函数
const get = (url: string): Effect.Effect<unknown, Error> =>
  Effect.tryPromise({
    try: () =>
      fetch(url).then((res) => {
        if (res.ok) {
          return res.json() as Promise<unknown>
        }
        throw new Error(String(res.status))
      }),
    catch: (e) => new Error(String(e))
  })

// 为人员ID创建品牌模式
const PeopleId = Schema.String.pipe(Schema.brand("PeopleId"))

// 定义带有异步转换的模式
const PeopleIdFromString = Schema.transformOrFail(
  Schema.String,
  PeopleId,
  {
    strict: true,
    decode: (s, _, ast) =>
      // 进行API调用以验证ID
      Effect.mapBoth(get(`https://swapi.dev/api/people/${s}`), {
        // 失败API调用的错误处理
        onFailure: (e) => new ParseResult.Type(ast, s, e.message),
        // 如果API调用成功则返回ID
        onSuccess: () => s
      }),
    encode: ParseResult.succeed
  }
)

//     ┌─── string
//     ▼
type Encoded = typeof PeopleIdFromString.Encoded

//     ┌─── string & Brand<"PeopleId">
//     ▼
type Type = typeof PeopleIdFromString.Type

//     ┌─── never
//     ▼
type Context = typeof PeopleIdFromString.Context

// 运行成功的解码操作
Effect.runPromiseExit(Schema.decodeUnknown(PeopleIdFromString)("1")).then(
  console.log
)
/*
输出：
{ _id: 'Exit', _tag: 'Success', value: '1' }
*/

// 运行将失败的解码操作
Effect.runPromiseExit(
  Schema.decodeUnknown(PeopleIdFromString)("fail")
).then(console.log)
/*
输出：
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Fail',
    failure: {
      _id: 'ParseError',
      message: '(string <-> string & Brand<"PeopleId">)\n' +
        '└─ Transformation process failure\n' +
        '   └─ Error: 404'
    }
  }
}
*/

声明依赖项

在您的转换依赖于外部服务的情况下，您可以在decode或encode函数中注入这些服务。然后在模式的Requirements通道中跟踪这些依赖项：

Schema<Type, Encoded, Requirements>

示例（使用服务验证数据）

import { Context, Effect, Schema, ParseResult, Layer } from "effect"

// 定义用于依赖注入的验证服务
class Validation extends Context.Tag("Validation")<
  Validation,
  {
    readonly validatePeopleid: (s: string) => Effect.Effect<void, Error>
  }
>() {}

// 为人员ID创建品牌模式
const PeopleId = Schema.String.pipe(Schema.brand("PeopleId"))

// 将字符串转换为经过验证的PeopleId，
// 使用外部验证服务
const PeopleIdFromString = Schema.transformOrFail(
  Schema.String,
  PeopleId,
  {
    strict: true,
    decode: (s, _, ast) =>
      // 使用注入的服务异步验证ID
      Effect.gen(function* () {
        // 访问验证服务
        const validator = yield* Validation
        // 使用服务验证ID
        yield* validator.validatePeopleid(s)
        return s
      }).pipe(
        Effect.mapError((e) => new ParseResult.Type(ast, s, e.message))
      ),
    encode: ParseResult.succeed // 通过简单返回字符串进行编码
  }
)

//     ┌─── string
//     ▼
type Encoded = typeof PeopleIdFromString.Encoded

//     ┌─── string & Brand<"PeopleId">
//     ▼
type Type = typeof PeopleIdFromString.Type

//     ┌─── Validation
//     ▼
type Context = typeof PeopleIdFromString.Context

// 提供成功验证服务的层
const SuccessTest = Layer.succeed(Validation, {
  validatePeopleid: (_) => Effect.void
})

// 运行成功的解码操作
Effect.runPromiseExit(
  Schema.decodeUnknown(PeopleIdFromString)("1").pipe(
    Effect.provide(SuccessTest)
  )
).then(console.log)
/*
输出：
{ _id: 'Exit', _tag: 'Success', value: '1' }
*/

// 提供失败验证服务的层
const FailureTest = Layer.succeed(Validation, {
  validatePeopleid: (_) => Effect.fail(new Error("404"))
})

// 运行将失败的解码操作
Effect.runPromiseExit(
  Schema.decodeUnknown(PeopleIdFromString)("fail").pipe(
    Effect.provide(FailureTest)
  )
).then(console.log)
/*
输出：
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Fail',
    failure: {
      _id: 'ParseError',
      message: '(string <-> string & Brand<"PeopleId">)\n' +
        '└─ Transformation process failure\n' +
        '   └─ Error: 404'
    }
  }
}
*/

禁止编码的单向转换

在某些情况下，将值编码回其原始形式可能没有意义或不可取。您可以使用Schema.transformOrFail来定义单向转换，并在编码过程中显式返回Forbidden解析错误。这确保一旦值被转换，就无法恢复到其原始形式。

示例（禁止编码的密码哈希）

考虑这样一个场景：您需要对用户的明文密码进行哈希处理以进行安全存储。重要的是，哈希密码不能被逆转回明文。通过使用Schema.transformOrFail，您可以强制执行此限制，确保从明文到哈希密码的单向转换。

import { Schema, ParseResult, Redacted } from "effect"
import { createHash } from "node:crypto"

// 定义明文密码的模式
// 具有最小长度要求
const PlainPassword = Schema.String.pipe(
  Schema.minLength(6),
  Schema.brand("PlainPassword", { identifier: "PlainPassword" })
)

// 将哈希密码定义为单独的品牌类型模式
const HashedPassword = Schema.String.pipe(
  Schema.brand("HashedPassword", { identifier: "HashedPassword" })
)

// 定义从明文密码到哈希密码的单向转换
export const PasswordHashing = Schema.transformOrFail(
  PlainPassword,
  // 将输出包装在Redacted中以增加安全性
  Schema.RedactedFromSelf(HashedPassword),
  {
    strict: true,
    // 解码：将明文密码转换为哈希密码
    decode: (plainPassword) => {
      const hash = createHash("sha256")
        .update(plainPassword)
        .digest("hex")
      // 将哈希包装在Redacted中
      return ParseResult.succeed(Redacted.make(hash))
    },
    // 编码：禁止将哈希密码逆转回明文
    encode: (hashedPassword, _, ast) =>
      ParseResult.fail(
        new ParseResult.Forbidden(
          ast,
          hashedPassword,
          "禁止将哈希密码编码回明文。"
        )
      )
  }
)

//     ┌─── string
//     ▼
type Encoded = typeof PasswordHashing.Encoded

//     ┌─── Redacted<string & Brand<"HashedPassword">>
//     ▼
type Type = typeof PasswordHashing.Type

// 示例：将明文密码解码为哈希密码
console.log(
  Schema.decodeUnknownSync(PasswordHashing)("myPlainPassword123")
)
// 输出：<redacted>

// 示例：尝试将哈希密码编码回明文
console.log(
  Schema.encodeUnknownSync(PasswordHashing)(Redacted.make("2ef2b7..."))
)
/*
抛出：
ParseError: (PlainPassword <-> Redacted(<redacted>))
└─ Transformation process failure
   └─ (PlainPassword <-> Redacted(<redacted>))
      └─ 禁止将哈希密码编码回明文。
*/

组合

在复杂应用程序中经常需要组合和重用模式，Schema.compose组合器提供了一种有效的方法来实现这一点。使用Schema.compose，您可以将两个模式Schema<B, A, R1>和Schema<C, B, R2>链接成单个模式Schema<C, A, R1 | R2>：

示例（组合模式将分隔字符串解析为数字）

import { Schema } from "effect"

// 将字符串按逗号分割为字符串数组的模式
//
//     ┌─── Schema<readonly string[], string, never>
//     ▼
const schema1 = Schema.asSchema(Schema.split(","))

// 将字符串数组转换为数字数组的模式
//
//     ┌─── Schema<readonly number[], readonly string[], never>
//     ▼
const schema2 = Schema.asSchema(Schema.Array(Schema.NumberFromString))

// 组合模式，接受字符串，按逗号分割，
// 并将结果转换为数字数组
//
//     ┌─── Schema<readonly number[], string, never>
//     ▼
const ComposedSchema = Schema.asSchema(Schema.compose(schema1, schema2))

非严格选项

在组合模式时，您可能遇到一个模式的输出与下一个模式的输入不完全匹配的情况，例如，如果您有Schema<R1, A, B>和Schema<R2, C, D>，其中C与B不同。为了处理这些情况，您可以使用{ strict: false }选项来放宽类型约束。

示例（在组合中使用非严格选项）

import { Schema } from "effect"

// 没有`strict: false`选项，
// 此组合会引发TypeScript错误
Schema.compose(
  Schema.Union(Schema.Null, Schema.Literal("0")),
Error ts(2769)  ― No overload matches this call.
  The last overload gave the following error.
    Argument of type 'Union<[typeof Null, Literal<["0"]>]>' is not assignable to parameter of type 'Union<[typeof Null, Literal<["0"]>]> & Schema<string, "0" | null, never>'.
      Type 'Union<[typeof Null, Literal<["0"]>]>' is not assignable to type 'Schema<string, "0" | null, never>'.
        Types of property 'Type' are incompatible.
          Type 'string | null' is not assignable to type 'string'.
            Type 'null' is not assignable to type 'string'.
  Schema.NumberFromString
)

// 使用`strict: false`允许类型灵活性
Schema.compose(
  Schema.Union(Schema.Null, Schema.Literal("0")),
  Schema.NumberFromString,
  { strict: false }
)

有效果的过滤器

Schema.filterEffect函数启用需要异步或动态场景的验证，使其适用于涉及网络请求或数据库查询等副作用的验证情况。对于简单的同步验证，请参阅Schema.filter。

示例（异步用户名验证）

import { Effect, Schema } from "effect"

// 模拟异步函数来验证用户名
async function validateUsername(username: string) {
  return Promise.resolve(username === "gcanti")
}

// 定义带有有效果过滤器的模式
const ValidUsername = Schema.String.pipe(
  Schema.filterEffect((username) =>
    Effect.promise(() =>
      // 异步验证用户名，
      // 如果无效则返回错误消息
      validateUsername(username).then(
        (valid) => valid || "Invalid username"
      )
    )
  )
).annotations({ identifier: "ValidUsername" })

Effect.runPromise(Schema.decodeUnknown(ValidUsername)("xxx")).then(
  console.log
)
/*
ParseError: ValidUsername
└─ Transformation process failure
   └─ Invalid username
*/

字符串转换

split

按指定分隔符将字符串分割为子字符串数组。

示例（按逗号分割字符串）

import { Schema } from "effect"

const schema = Schema.split(",")

const decode = Schema.decodeUnknownSync(schema)

console.log(decode("")) // [""]
console.log(decode(",")) // ["", ""]
console.log(decode("a,")) // ["a", ""]
console.log(decode("a,b")) // ["a", "b"]

Trim

从字符串的开头和结尾删除空格。

示例（修剪空格）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Trim)

console.log(decode("a")) // "a"
console.log(decode(" a")) // "a"
console.log(decode("a ")) // "a"
console.log(decode(" a ")) // "a"

Trimmed Check

If you were looking for a combinator to check if a string is trimmed, check out the Schema.trimmed filter.

Lowercase

将字符串转换为小写。

示例（转换为小写）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Lowercase)

console.log(decode("A")) // "a"
console.log(decode(" AB")) // " ab"
console.log(decode("Ab ")) // "ab "
console.log(decode(" ABc ")) // " abc "

Lowercase And Lowercased

If you were looking for a combinator to check if a string is lowercased, check out the Schema.Lowercased schema or the Schema.lowercased filter.

Uppercase

将字符串转换为大写。

示例（转换为大写）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Uppercase)

console.log(decode("a")) // "A"
console.log(decode(" ab")) // " AB"
console.log(decode("aB ")) // "AB "
console.log(decode(" abC ")) // " ABC "

Uppercase And Uppercased

If you were looking for a combinator to check if a string is uppercased, check out the Schema.Uppercased schema or the Schema.uppercased filter.

Capitalize

将字符串的第一个字符转换为大写。

示例（首字母大写字符串）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Capitalize)

console.log(decode("aa")) // "Aa"
console.log(decode(" ab")) // " ab"
console.log(decode("aB ")) // "AB "
console.log(decode(" abC ")) // " abC "

Capitalize And Capitalized

If you were looking for a combinator to check if a string is capitalized, check out the Schema.Capitalized schema or the Schema.capitalized filter.

Uncapitalize

将字符串的第一个字符转换为小写。

示例（首字母小写字符串）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Uncapitalize)

console.log(decode("AA")) // "aA"
console.log(decode(" AB")) // " AB"
console.log(decode("Ab ")) // "ab "
console.log(decode(" AbC ")) // " AbC "

Uncapitalize And Uncapitalized

If you were looking for a combinator to check if a string is uncapitalized, check out the Schema.Uncapitalized schema or the Schema.uncapitalized filter.

parseJson

Schema.parseJson构造函数提供了一种使用JSON.parse的底层功能将JSON字符串转换为unknown类型的方法。 它还使用JSON.stringify进行编码。

示例（解析JSON字符串）

import { Schema } from "effect"

const schema = Schema.parseJson()
const decode = Schema.decodeUnknownSync(schema)

// 解析有效的JSON字符串
console.log(decode("{}")) // 输出：{}
console.log(decode(`{"a":"b"}`)) // 输出：{ a: "b" }

// 尝试解码空字符串会导致错误
decode("")
/*
抛出：
ParseError: (JsonString <-> unknown)
└─ Transformation process failure
   └─ Unexpected end of JSON input
*/

为了进一步细化JSON解析的结果，您可以向Schema.parseJson构造函数提供模式。此模式将验证解析的JSON是否匹配特定结构。

示例（带结构验证的JSON解析）

在此示例中，Schema.parseJson使用结构模式来确保解析的JSON是具有数字属性a的对象。这为解析的数据添加了验证，确认它遵循预期的结构。

import { Schema } from "effect"

//     ┌─── SchemaClass<{ readonly a: number; }, string, never>
//     ▼
const schema = Schema.parseJson(Schema.Struct({ a: Schema.Number }))

StringFromBase64

将base64（RFC4648）编码的字符串解码为UTF-8字符串。

示例（解码Base64）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.StringFromBase64)

console.log(decode("Zm9vYmFy"))
// 输出："foobar"

StringFromBase64Url

将base64（URL）编码的字符串解码为UTF-8字符串。

示例（解码Base64 URL）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.StringFromBase64Url)

console.log(decode("Zm9vYmFy"))
// 输出："foobar"

StringFromHex

将十六进制编码的字符串解码为UTF-8字符串。

示例（解码十六进制字符串）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.StringFromHex)

console.log(new TextEncoder().encode(decode("0001020304050607")))
/*
输出：
Uint8Array(8) [
  0, 1, 2, 3,
  4, 5, 6, 7
]
*/

StringFromUriComponent

将URI编码的字符串解码为UTF-8字符串。它对于在URL中编码和解码数据很有用。

示例（解码URI组件）

import { Schema } from "effect"

const PaginationSchema = Schema.Struct({
  maxItemPerPage: Schema.Number,
  page: Schema.Number
})

const UrlSchema = Schema.compose(
  Schema.StringFromUriComponent,
  Schema.parseJson(PaginationSchema)
)

console.log(Schema.encodeSync(UrlSchema)({ maxItemPerPage: 10, page: 1 }))
// 输出：%7B%22maxItemPerPage%22%3A10%2C%22page%22%3A1%7D

数字转换

NumberFromString

通过使用effect/Number模块的parse函数解析字符串，将字符串转换为数字。

如果值无法转换（例如提供非数字字符时），它会返回错误。

支持以下特殊字符串值：“NaN”、“Infinity”、“-Infinity”。

示例（从字符串解析数字）

import { Schema } from "effect"

const schema = Schema.NumberFromString

const decode = Schema.decodeUnknownSync(schema)

// 成功案例
console.log(decode("1")) // 1
console.log(decode("-1")) // -1
console.log(decode("1.5")) // 1.5
console.log(decode("NaN")) // NaN
console.log(decode("Infinity")) // Infinity
console.log(decode("-Infinity")) // -Infinity

// 失败案例
decode("a")
/*
抛出：
ParseError: NumberFromString
└─ Transformation process failure
   └─ Expected NumberFromString, actual "a"
*/

clamp

将数字限制在指定范围内。

示例（限制数字）

import { Schema } from "effect"

// 将输入限制在-1 <= x <= 1
const schema = Schema.Number.pipe(Schema.clamp(-1, 1))

const decode = Schema.decodeUnknownSync(schema)

console.log(decode(-3)) // -1
console.log(decode(0)) // 0
console.log(decode(3)) // 1

parseNumber

通过使用effect/Number模块的parse函数解析字符串，将字符串转换为数字。

如果值无法转换（例如提供非数字字符时），它会返回错误。

支持以下特殊字符串值：“NaN”、“Infinity”、“-Infinity”。

示例（解析和验证数字）

import { Schema } from "effect"

const schema = Schema.String.pipe(Schema.parseNumber)

const decode = Schema.decodeUnknownSync(schema)

console.log(decode("1")) // 1
console.log(decode("Infinity")) // Infinity
console.log(decode("NaN")) // NaN
console.log(decode("-"))
/*
抛出
ParseError: (string <-> number)
└─ Transformation process failure
   └─ Expected (string <-> number), actual "-"
*/

布尔值转换

Not

对布尔值取反。

示例（布尔值取反）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Not)

console.log(decode(true)) // false
console.log(decode(false)) // true

符号转换

Symbol

使用Symbol.for将字符串转换为符号。

示例（从字符串创建符号）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Symbol)

console.log(decode("a")) // Symbol(a)

BigInt转换

BigInt

使用BigInt构造函数将字符串转换为BigInt。

示例（从字符串解析BigInt）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.BigInt)

// 成功案例
console.log(decode("1")) // 1n
console.log(decode("-1")) // -1n

// 失败案例
decode("a")
/*
抛出：
ParseError: bigint
└─ Transformation process failure
   └─ Expected bigint, actual "a"
*/
decode("1.5") // 抛出
decode("NaN") // 抛出
decode("Infinity") // 抛出
decode("-Infinity") // 抛出

BigIntFromNumber

使用BigInt构造函数将数字转换为BigInt。

示例（从数字解析BigInt）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.BigIntFromNumber)
const encode = Schema.encodeSync(Schema.BigIntFromNumber)

// 成功案例
console.log(decode(1)) // 1n
console.log(decode(-1)) // -1n
console.log(encode(1n)) // 1
console.log(encode(-1n)) // -1

// 失败案例
decode(1.5)
/*
抛出：
ParseError: BigintFromNumber
└─ Transformation process failure
   └─ Expected BigintFromNumber, actual 1.5
*/

decode(NaN) // 抛出
decode(Infinity) // 抛出
decode(-Infinity) // 抛出
encode(BigInt(Number.MAX_SAFE_INTEGER) + 1n) // 抛出
encode(BigInt(Number.MIN_SAFE_INTEGER) - 1n) // 抛出

clampBigInt

将BigInt限制在指定范围内。

示例（限制BigInt）

import { Schema } from "effect"

// 将输入限制在-1n <= x <= 1n
const schema = Schema.BigIntFromSelf.pipe(Schema.clampBigInt(-1n, 1n))

const decode = Schema.decodeUnknownSync(schema)

console.log(decode(-3n))
// 输出：-1n

console.log(decode(0n))
// 输出：0n

console.log(decode(3n))
// 输出：1n

日期转换

Date

将字符串转换为有效的Date，确保拒绝无效日期，如new Date("Invalid Date")。

示例（解析和验证日期）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Date)

console.log(decode("1970-01-01T00:00:00.000Z"))
// 输出：1970-01-01T00:00:00.000Z

decode("a")
/*
抛出：
ParseError: Date
└─ Predicate refinement failure
   └─ Expected Date, actual Invalid Date
*/

const validate = Schema.validateSync(Schema.Date)

console.log(validate(new Date(0)))
// 输出：1970-01-01T00:00:00.000Z

console.log(validate(new Date("Invalid Date")))
/*
抛出：
ParseError: Date
└─ Predicate refinement failure
   └─ Expected Date, actual Invalid Date
*/

BigDecimal转换

BigDecimal

将字符串转换为BigDecimal。

示例（从字符串解析BigDecimal）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.BigDecimal)

console.log(decode(".124"))
// 输出：{ _id: 'BigDecimal', value: '124', scale: 3 }

BigDecimalFromNumber

将数字转换为BigDecimal。

Invalid Range

When encoding, this Schema will produce incorrect results if the BigDecimal exceeds the 64-bit range of a number.

示例（从数字解析BigDecimal）

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.BigDecimalFromNumber)

console.log(decode(0.111))
// 输出：{ _id: 'BigDecimal', value: '111', scale: 3 }

clampBigDecimal

将BigDecimal限制在指定范围内。

示例（限制BigDecimal）

import { Schema } from "effect"
import { BigDecimal } from "effect"

const schema = Schema.BigDecimal.pipe(
  Schema.clampBigDecimal(
    BigDecimal.fromNumber(-1),
    BigDecimal.fromNumber(1)
  )
)

const decode = Schema.decodeUnknownSync(schema)

console.log(decode("-2"))
// 输出：{ _id: 'BigDecimal', value: '-1', scale: 0 }

console.log(decode("0"))
// 输出：{ _id: 'BigDecimal', value: '0', scale: 0 }

console.log(decode("3"))
// 输出：{ _id: 'BigDecimal', value: '1', scale: 0 }