Schema Transformations

Transformations play a key role in working with schemas, especially when you need to convert data from one type to another, such as parsing a string into a number or converting a date string into a Date object.

transform

The Schema.transform function is designed to facilitate these conversions by linking two schemas together: one for the input type and one for the output type.

Here’s an overview of the Schema.transform function, which accepts five parameters:

Parameter	Description	Type
from	The source schema, representing the starting point of the transformation.	Schema<B, A, R1> where A is the input type and B is the intermediate type after initial validation.
to	The target schema, representing the endpoint of the transformation.	Schema<D, C, R2> where C is the transformed type from B, and D is the final output type.
decode	A function that converts an intermediate value of type B to a value of type C.	(b: B, a: A) => C
encode	A function that reverses the transformation, converting type C back to type B.	(c: C, d: D) => B
strict	optional (but recommended)	boolean

This function results in a schema Schema<D, A, R1 | R2>, integrating both the dependencies and transformations of the from and to schemas.

Example (Doubling a Number)

Here’s an example that demonstrates a schema transformation to double an input number:

import { Schema } from "effect"

// Define a transformation that doubles the input number
const Double = Schema.transform(
  // Source schema
  Schema.Number,
  // Target schema
  Schema.Number,
  {
    // optional but you get better error messages from TypeScript
    strict: true,
    // Transformation function to double the number
    decode: (n) => n * 2,
    // Reverse transformation to revert to the original number
    encode: (n) => n / 2
  }
)

//     ┌─── number
//     ▼
type Encoded = typeof Double.Encoded

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

console.log(Schema.decodeUnknownSync(Double)(2))
// Output: 4

console.log(Schema.encodeUnknownSync(Double)(4))
// Output: 2

Example (Converting an array to a ReadonlySet)

Here’s how you can convert an array to a ReadonlySet:

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.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"]))
// Output: Set(3) { 'a', 'b', 'c' }

console.log(Schema.encodeSync(schema)(new Set(["a", "b", "c"])))
// Output: [ 'a', 'b', 'c' ]

Note

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).

Example (Trim Whitespace)

Here’s how to use the transform function to trim whitespace from strings:

import { Schema } from "effect"

const Trim = Schema.transform(
  // Source schema: accepts any string
  Schema.String,
  // Target schema: also accepts any string
  Schema.String,
  {
    strict: true,
    // Trim the string during decoding
    decode: (s) => s.trim(),
    // No change during encoding
    encode: (s) => s
  }
)

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

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

console.log(Schema.decodeUnknownSync(Trim)("a  "))
// Output: "a"

console.log(Schema.encodeUnknownSync(Trim)("a  "))
// Output: "a  "

This schema automatically trims leading and trailing whitespace from a string during decoding. During encoding, it returns the string unchanged.

Improving the Transformation with a Filter

To ensure that strings are not only trimmed but also validated to exclude untrimmed inputs, you can restrict the target schema to only accept strings that are already trimmed:

import { Schema } from "effect"

const Trim = Schema.transform(
  // Source schema: accepts any string
  Schema.String,
  // Target schema now only accepts strings that are trimmed
  Schema.String.pipe(Schema.filter((s) => s === s.trim())),
  {
    strict: true,
    // Trim the string during decoding
    decode: (s) => s.trim(),
    // No change during encoding
    encode: (s) => s
  }
)

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

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

console.log(JSON.stringify(Schema.encodeUnknownSync(Trim)("a")))
// Output: "a"

console.log(JSON.stringify(Schema.encodeUnknownSync(Trim)("a  ")))
/*
throws:
ParseError: (string <-> { string | filter })
└─ Type side transformation failure
   └─ { string | filter }
      └─ Predicate refinement failure
         └─ Expected { string | filter }, actual "a  "
*/

In this improved example, the target schema is piped through a Schema.filter function. This function checks that the string is equal to its trimmed version, effectively ensuring that only strings without leading or trailing whitespace are considered valid. This is particularly useful for maintaining data integrity and can help prevent errors or inconsistencies in data processing.

Non-strict option

In some cases, strict type checking can create issues during data transformations, especially when the types might slightly differ in specific transformations. To address these scenarios, Schema.transform offers the option strict: false, which relaxes type constraints and allows more flexible transformations.

Example (Creating a Clamping Constructor)

Let’s consider the scenario where you need to define a constructor clamp that ensures a number falls within a specific range. This function returns a schema that “clamps” a number to a specified minimum and maximum range:

import { Schema } from "effect"
import { 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)
      ),
      // @ts-expect-error
      {
        strict: true,
        decode: (a) => Number.clamp(a, { minimum, maximum }),
        encode: (a) => a
      }
    )
/*
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'.ts(2345)
*/

In this code, Number.clamp is a function that adjusts the given number to stay within the specified range. However, the return type of Number.clamp may not strictly be of type A but just a number, which can lead to type mismatches according to TypeScript’s strict type-checking.

There are two ways to resolve the type mismatch:

1. Using Type Assertion: Adding a type cast can enforce the return type to be treated as type A:

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

2. Using the Non-Strict Option: Setting strict: false in the transformation options allows the schema to bypass some of TypeScript’s type-checking rules, accommodating the type discrepancy:

   import { Schema } from "effect"
   import { 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

While the Schema.transform function is suitable for error-free transformations, the Schema.transformOrFail function is designed for more complex scenarios where transformations can fail during the decoding or encoding stages.

This function enables decoding/encoding functions to return either a successful result or an error, making it particularly useful for validating and processing data that might not always conform to expected formats.

Error Handling

The Schema.transformOrFail function utilizes the ParseResult module to manage potential errors:

Constructor	Description
ParseResult.succeed	Indicates a successful transformation, where no errors occurred.
ParseResult.fail	Signals a failed transformation, creating a new ParseError based on the provided ParseIssue.

Additionally, the ParseResult module provides constructors for dealing with various types of parse issues, such as:

Parse Issue Type	Description
Type	Indicates a type mismatch error.
Missing	Used when a required field is missing.
Unexpected	Used for unexpected fields that are not allowed in the schema.
Forbidden	Flags the decoding or encoding operation being forbidden by the schema.
Pointer	Points to a specific location in the data where an issue occurred.
Refinement	Used when a value does not meet a specific refinement or constraint.
Transformation	Flags issues that occur during transformation from one type to another.
Composite	Represents a composite error, combining multiple issues into one, helpful for grouped errors.

These tools allow for detailed and specific error handling, enhancing the reliability of data processing operations.

Example (Converting a String to a Number)

A common use case for Schema.transformOrFail is converting string representations of numbers into actual numeric types. This scenario is typical when dealing with user inputs or data from external sources.

import { ParseResult, Schema } from "effect"

export const NumberFromString = Schema.transformOrFail(
  Schema.String, // Source schema: accepts any string
  Schema.Number, // Target schema: expects a number
  {
    strict: true, // Optional: enables better TypeScript error messages
    decode: (input, options, ast) => {
      const parsed = parseFloat(input)
      // If parsing fails (NaN), return a ParseError with a custom error
      if (isNaN(parsed)) {
        return ParseResult.fail(
          // Create a Type Mismatch error
          new ParseResult.Type(
            ast, // Provide the schema's abstract syntax tree for context
            input, // Include the problematic input
            "Failed to convert string to number" // Custom error message
          )
        )
      }
      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"))
// Output: 123

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

Both decode and encode functions not only receive the value to transform (input), but also the parse options that the user sets when using the resulting schema, and the ast, which represents the low level definition of the schema you’re transforming.

Async Transformations

In modern applications, especially those interacting with external APIs, you might need to transform data asynchronously. Schema.transformOrFail supports asynchronous transformations by allowing you to return an Effect.

Example (Validating Data with an API Call)

Consider a scenario where you need to validate a person’s ID by making an API call. Here’s how you can implement it:

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

// Define a function to make API requests
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))
  })

// Create a branded schema for a person's ID
const PeopleId = Schema.String.pipe(Schema.brand("PeopleId"))

// Define a schema with async transformation
const PeopleIdFromString = Schema.transformOrFail(
  Schema.String,
  PeopleId,
  {
    strict: true,
    decode: (s, _, ast) =>
      // Make an API call to validate the ID
      Effect.mapBoth(get(`https://swapi.dev/api/people/${s}`), {
        // Error handling for failed API call
        onFailure: (e) => new ParseResult.Type(ast, s, e.message),
        // Return the ID if the API call succeeds
        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

// Run a successful decode operation
Effect.runPromiseExit(Schema.decodeUnknown(PeopleIdFromString)("1")).then(
  console.log
)
/*
Output:
{ _id: 'Exit', _tag: 'Success', value: '1' }
*/

// Run a decode operation that will fail
Effect.runPromiseExit(
  Schema.decodeUnknown(PeopleIdFromString)("fail")
).then(console.log)
/*
Output:
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Fail',
    failure: {
      _id: 'ParseError',
      message: '(string <-> string & Brand<"PeopleId">)\n' +
        '└─ Transformation process failure\n' +
        '   └─ Error: 404'
    }
  }
}
*/

Declaring Dependencies

In cases where your transformation depends on external services, you can inject these services in the decode or encode functions. These dependencies are then tracked in the Requirements channel of the schema:

Schema<Type, Encoded, Requirements>

Example (Validating Data with a Service)

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

// Define a Validation service for dependency injection
class Validation extends Context.Tag("Validation")<
  Validation,
  {
    readonly validatePeopleid: (s: string) => Effect.Effect<void, Error>
  }
>() {}

// Create a branded schema for a person's ID
const PeopleId = Schema.String.pipe(Schema.brand("PeopleId"))

// Transform a string into a validated PeopleId,
// using an external validation service
const PeopleIdFromString = Schema.transformOrFail(
  Schema.String,
  PeopleId,
  {
    strict: true,
    decode: (s, _, ast) =>
      // Asynchronously validate the ID using the injected service
      Effect.gen(function* (_) {
        // Access the validation service
        const validator = yield* Validation
        // Use service to validate ID
        yield* validator.validatePeopleid(s)
        return s
      }).pipe(
        Effect.mapError((e) => new ParseResult.Type(ast, s, e.message))
      ),
    encode: ParseResult.succeed // Encode by simply returning the string
  }
)

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

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

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

// Layer to provide a successful validation service
const SuccessTest = Layer.succeed(Validation, {
  validatePeopleid: (_) => Effect.void
})

// Run a successful decode operation
Effect.runPromiseExit(
  Schema.decodeUnknown(PeopleIdFromString)("1").pipe(
    Effect.provide(SuccessTest)
  )
).then(console.log)
/*
Output:
{ _id: 'Exit', _tag: 'Success', value: '1' }
*/

// Layer to provide a failing validation service
const FaailureTest = Layer.succeed(Validation, {
  validatePeopleid: (_) => Effect.fail(new Error("404"))
})

// Run a decode operation that will fail
Effect.runPromiseExit(
  Schema.decodeUnknown(PeopleIdFromString)("fail").pipe(
    Effect.provide(FaailureTest)
  )
).then(console.log)
/*
Output:
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Fail',
    failure: {
      _id: 'ParseError',
      message: '(string <-> string & Brand<"PeopleId">)\n' +
        '└─ Transformation process failure\n' +
        '   └─ Error: 404'
    }
  }
}
*/

Composition

Combining and reusing schemas is often needed in complex applications, and the Schema.compose combinator provides an efficient way to do this. With Schema.compose, you can chain two schemas, Schema<B, A, R1> and Schema<C, B, R2>, into a single schema Schema<C, A, R1 | R2>:

Example (Composing Schemas to Parse a Delimited String into Numbers)

import { Schema } from "effect"

// Schema to split a string by commas into an array of strings
//
//     ┌─── Schema<readonly string[], string, never>
//     ▼
const schema1 = Schema.asSchema(Schema.split(","))

// Schema to convert an array of strings to an array of numbers
//
//     ┌─── Schema<readonly number[], readonly string[], never>
//     ▼
const schema2 = Schema.asSchema(Schema.Array(Schema.NumberFromString))

// Composed schema that takes a string, splits it by commas,
// and converts the result into an array of numbers
//
//     ┌─── Schema<readonly number[], string, never>
//     ▼
const ComposedSchema = Schema.asSchema(Schema.compose(schema1, schema2))

Non-strict Option

When composing schemas, you may encounter cases where the output of one schema does not perfectly match the input of the next, for example, if you have Schema<R1, A, B> and Schema<R2, C, D> where C differs from B. To handle these cases, you can use the { strict: false } option to relax type constraints.

Example (Using Non-strict Option in Composition)

import { Schema } from "effect"

// Without the `strict: false` option,
// this composition would raise a TypeScript error
Schema.compose(
  // @ts-expect-error: Type mismatch between schemas
  Schema.Union(Schema.Null, Schema.Literal("0")),
  Schema.NumberFromString
)

// Using `strict: false` to allow for type flexibility
Schema.compose(
  Schema.Union(Schema.Null, Schema.Literal("0")),
  Schema.NumberFromString,
  { strict: false }
)

Effectful Filters

The Schema.filterEffect function enables validations that require asynchronous or dynamic scenarios, making it suitable for cases where validations involve side effects like network requests or database queries. For simple synchronous validations, see Schema.filter.

Example (Asynchronous Username Validation)

import { Effect, Schema } from "effect"

// Mock async function to validate a username
async function validateUsername(username: string) {
  return Promise.resolve(username === "gcanti")
}

// Define a schema with an effectful filter
const ValidUsername = Schema.String.pipe(
  Schema.filterEffect((username) =>
    Effect.promise(() =>
      // Validate the username asynchronously,
      // returning an error message if invalid
      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
*/

String Transformations

split

Splits a string by a specified delimiter into an array of substrings.

Example (Splitting a String by Comma)

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

Removes whitespace from the beginning and end of a string.

Example (Trimming Whitespace)

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

Converts a string to lowercase.

Example (Converting to 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

Converts a string to uppercase.

Example (Converting to 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

Converts the first character of a string to uppercase.

Example (Capitalizing a String)

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

Converts the first character of a string to lowercase.

Example (Uncapitalizing a String)

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

The Schema.parseJson constructor offers a method to convert JSON strings into the unknown type using the underlying functionality of JSON.parse. It also employs JSON.stringify for encoding.

Example (Parsing JSON Strings)

import { Schema } from "effect"

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

// Parse valid JSON strings
console.log(decode("{}")) // Output: {}
console.log(decode(`{"a":"b"}`)) // Output: { a: "b" }

// Attempting to decode an empty string results in an error
decode("")
/*
throws:
ParseError: (JsonString <-> unknown)
└─ Transformation process failure
   └─ Unexpected end of JSON input
*/

To further refine the result of JSON parsing, you can provide a schema to the Schema.parseJson constructor. This schema will validate that the parsed JSON matches a specific structure.

Example (Parsing JSON with Structured Validation)

In this example, Schema.parseJson uses a struct schema to ensure the parsed JSON is an object with a numeric property a. This adds validation to the parsed data, confirming that it follows the expected structure.

import { Schema } from "effect"

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

StringFromBase64

Decodes a base64 (RFC4648) encoded string into a UTF-8 string.

Example (Decoding Base64)

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.StringFromBase64)

console.log(decode("Zm9vYmFy"))
// Output: "foobar"

StringFromBase64Url

Decodes a base64 (URL) encoded string into a UTF-8 string.

Example (Decoding Base64 URL)

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.StringFromBase64Url)

console.log(decode("Zm9vYmFy"))
// Output: "foobar"

StringFromHex

Decodes a hex encoded string into a UTF-8 string.

Example (Decoding Hex String)

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.StringFromHex)

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

Number Transformations

NumberFromString

Converts a string to a number using parseFloat, supporting special values “NaN”, “Infinity”, and “-Infinity”.

Example (Parsing Number from String)

import { Schema } from "effect"

const schema = Schema.NumberFromString

const decode = Schema.decodeUnknownSync(schema)

// success cases
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

// failure cases
decode("a")
/*
throws:
ParseError: NumberFromString
└─ Transformation process failure
   └─ Expected NumberFromString, actual "a"
*/

clamp

Restricts a number within a specified range.

Example (Clamping a Number)

import { Schema } from "effect"

// clamps the input to -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

Transforms a string into a number by parsing the string using the parse function of the effect/Number module.

It returns an error if the value can’t be converted (for example when non-numeric characters are provided).

The following special string values are supported: “NaN”, “Infinity”, “-Infinity”.

Example (Parsing and Validating Numbers)

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("-"))
/*
throws
ParseError: (string <-> number)
└─ Transformation process failure
   └─ Expected (string <-> number), actual "-"
*/

Boolean Transformations

Not

Negates a boolean value.

Example (Negating Boolean)

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Not)

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

Symbol transformations

Symbol

Converts a string to a symbol using Symbol.for.

Example (Creating Symbols from Strings)

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Symbol)

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

BigInt transformations

BigInt

Converts a string to a BigInt using the BigInt constructor.

Example (Parsing BigInt from String)

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.BigInt)

// success cases
console.log(decode("1")) // 1n
console.log(decode("-1")) // -1n

// failure cases
decode("a")
/*
throws:
ParseError: bigint
└─ Transformation process failure
   └─ Expected bigint, actual "a"
*/
decode("1.5") // throws
decode("NaN") // throws
decode("Infinity") // throws
decode("-Infinity") // throws

BigIntFromNumber

Converts a number to a BigInt using the BigInt constructor.

Example (Parsing BigInt from Number)

import { Schema } from "effect"

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

// success cases
console.log(decode(1)) // 1n
console.log(decode(-1)) // -1n
console.log(encode(1n)) // 1
console.log(encode(-1n)) // -1

// failure cases
decode(1.5)
/*
throws:
ParseError: BigintFromNumber
└─ Transformation process failure
   └─ Expected BigintFromNumber, actual 1.5
*/

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

clampBigInt

Restricts a BigInt within a specified range.

Example (Clamping BigInt)

import { Schema } from "effect"

// clamps the input to -1n <= x <= 1n
const schema = Schema.BigIntFromSelf.pipe(Schema.clampBigInt(-1n, 1n))

const decode = Schema.decodeUnknownSync(schema)

console.log(decode(-3n))
// Output: -1n

console.log(decode(0n))
// Output: 0n

console.log(decode(3n))
// Output: 1n

Date transformations

Date

Converts a string into a valid Date, ensuring that invalid dates, such as new Date("Invalid Date"), are rejected.

Example (Parsing and Validating Date)

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.Date)

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

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

const validate = Schema.validateSync(Schema.Date)

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

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

BigDecimal Transformations

BigDecimal

Converts a string to a BigDecimal.

Example (Parsing BigDecimal from String)

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.BigDecimal)

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

BigDecimalFromNumber

Converts a number to a BigDecimal.

Invalid Range

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

Example (Parsing BigDecimal from Number)

import { Schema } from "effect"

const decode = Schema.decodeUnknownSync(Schema.BigDecimalFromNumber)

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

clampBigDecimal

Clamps a BigDecimal within a specified range.

Example (Clamping 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"))
// Output: { _id: 'BigDecimal', value: '-1', scale: 0 }

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

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