Default Constructors

When working with data structures, it can be helpful to create values that conform to a schema with minimal effort. For this purpose, the Schema module provides default constructors for various schema types, including Structs, Records, filters, and brands.

Default constructors are unsafe, meaning they throw an error if the input does not conform to the schema. If you need a safer alternative, consider using Schema.validateEither, which returns a result indicating success or failure instead of throwing an error.

Example (Using a Refinement Default Constructor)

1
import { Schema } from "effect"
2

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

5
// The constructor only accepts numbers
6
console.log(schema.make(5))
7
// Output: 5
8

9
// This will throw an error because the number is outside the valid range
10
console.log(schema.make(20))
11
/*
12
throws:
13
ParseError: between(1, 10)
14
└─ Predicate refinement failure
15
   └─ Expected a number between 1 and 10, actual 20
16
*/

Structs

Struct schemas allow you to define objects with specific fields and constraints. The make function can be used to create instances of a struct schema.

Example (Creating Struct Instances)

1
import { Schema } from "effect"
2

3
const Struct = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
})
6

7
// Successful creation
8
Struct.make({ name: "a" })
9

10
// This will throw an error because the name is empty
11
Struct.make({ name: "" })
12
/*
13
throws
14
ParseError: { readonly name: NonEmptyString }
15
└─ ["name"]
16
   └─ NonEmptyString
17
      └─ Predicate refinement failure
18
         └─ Expected NonEmptyString, actual ""
19
*/

In some cases, you might need to bypass validation. While not recommended in most scenarios, make provides an option to disable validation.

Example (Bypassing Validation)

1
import { Schema } from "effect"
2

3
const Struct = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
})
6

7
// Bypass validation during instantiation
8
Struct.make({ name: "" }, true)
9

10
// Or use the `disableValidation` option explicitly
11
Struct.make({ name: "" }, { disableValidation: true })

Records

Record schemas allow you to define key-value mappings where the keys and values must meet specific criteria.

Example (Creating Record Instances)

1
import { Schema } from "effect"
2

3
const Record = Schema.Record({
4
  key: Schema.String,
5
  value: Schema.NonEmptyString,
6
})
7

8
// Successful creation
9
Record.make({ a: "a", b: "b" })
10

11
// This will throw an error because 'b' is empty
12
Record.make({ a: "a", b: "" })
13
/*
14
throws
15
ParseError: { readonly [x: string]: NonEmptyString }
16
└─ ["b"]
17
   └─ NonEmptyString
18
      └─ Predicate refinement failure
19
         └─ Expected NonEmptyString, actual ""
20
*/
21

22
// Bypasses validation
23
Record.make({ a: "a", b: "" }, { disableValidation: true })

Filters

Filters allow you to define constraints on individual values.

Example (Using Filters to Enforce Ranges)

1
import { Schema } from "effect"
2

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

5
// Successful creation
6
const n = MyNumber.make(5)
7

8
// This will throw an error because the number is outside the valid range
9
MyNumber.make(20)
10
/*
11
throws
12
ParseError: a number between 1 and 10
13
└─ Predicate refinement failure
14
   └─ Expected a number between 1 and 10, actual 20
15
*/
16

17
// Bypasses validation
18
MyNumber.make(20, { disableValidation: true })

Branded Types

Branded schemas add metadata to a value to give it a more specific type, while still retaining its original type.

Example (Creating Branded Values)

1
import { Schema } from "effect"
2

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

5
// Successful creation
6
const n = BrandedNumberSchema.make(5)
7

8
// This will throw an error because the number is outside the valid range
9
BrandedNumberSchema.make(20)
10
/*
11
throws
12
ParseError: a number between 1 and 10 & Brand<"MyNumber">
13
└─ Predicate refinement failure
14
   └─ Expected a number between 1 and 10 & Brand<"MyNumber">, actual 20
15
*/
16

17
// Bypasses validation
18
BrandedNumberSchema.make(20, { disableValidation: true })

When using default constructors, it is helpful to understand the type of value they produce.

For instance, in the BrandedNumberSchema example, the return type of the constructor is number & Brand<"MyNumber">. This indicates that the resulting value is a number with additional branding information, "MyNumber".

This behavior contrasts with the filter example, where the return type is simply number. Branding adds an extra layer of type information, which can assist in identifying and working with your data more effectively.

Error Handling in Constructors

Default constructors are considered “unsafe” because they throw an error if the input does not conform to the schema. This error includes a detailed description of what went wrong. The intention behind default constructors is to provide a straightforward way to create valid values, such as for tests or configurations, where invalid inputs are expected to be exceptional cases.

If you need a “safe” constructor that does not throw errors but instead returns a result indicating success or failure, you can use Schema.validateEither.

Example (Using Schema.validateEither for Safe Validation)

1
import { Schema } from "effect"
2

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

5
// Create a safe constructor that validates an unknown input
6
const safeMake = Schema.validateEither(schema)
7

8
// Valid input returns a Right value
9
console.log(safeMake(5))
10
/*
11
Output:
12
{ _id: 'Either', _tag: 'Right', right: 5 }
13
*/
14

15
// Invalid input returns a Left value with detailed error information
16
console.log(safeMake(20))
17
/*
18
Output:
19
{
20
  _id: 'Either',
21
  _tag: 'Left',
22
  left: {
23
    _id: 'ParseError',
24
    message: 'between(1, 10)\n' +
25
      '└─ Predicate refinement failure\n' +
26
      '   └─ Expected a number between 1 and 10, actual 20'
27
  }
28
}
29
*/
30

31
// This will throw an error because it's unsafe
32
schema.make(20)
33
/*
34
throws:
35
ParseError: between(1, 10)
36
└─ Predicate refinement failure
37
   └─ Expected a number between 1 and 10, actual 20
38
*/

Setting Default Values

When creating objects, you might want to assign default values to certain fields to simplify object construction. The Schema.withConstructorDefault function lets you handle default values, making fields optional in the default constructor.

Example (Struct with Required Fields)

In this example, all fields are required when creating a new instance.

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Number,
6
})
7

8
// Both name and age must be provided
9
console.log(Person.make({ name: "John", age: 30 }))
10
/*
11
Output: { name: 'John', age: 30 }
12
*/

Example (Struct with Default Value)

Here, the age field is optional because it has a default value of 0.

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Number.pipe(
6
    Schema.propertySignature,
7
    Schema.withConstructorDefault(() => 0),
8
  ),
9
})
10

11
// The age field is optional and defaults to 0
12
console.log(Person.make({ name: "John" }))
13
/*
14
Output:
15
{ name: 'John', age: 0 }
16
*/
17

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

Nested Structs and Shallow Defaults

Default values in schemas are shallow, meaning that defaults defined in nested structs do not automatically propagate to the top-level constructor.

Example (Shallow Defaults in Nested Structs)

1
import { Schema } from "effect"
2

3
const Config = Schema.Struct({
4
  // Define a nested struct with a default value
5
  web: Schema.Struct({
6
    application_url: Schema.String.pipe(
7
      Schema.propertySignature,
8
      Schema.withConstructorDefault(() => "http://localhost"),
9
    ),
10
    application_port: Schema.Number,
11
  }),
12
})
13

14
// This will cause a type error because `application_url`
15
// is missing in the nested struct
16
// @errors: 2741
17
Config.make({ web: { application_port: 3000 } })

This behavior occurs because the Schema interface does not include a type parameter to carry over default constructor types from nested structs.

To work around this limitation, extract the constructor for the nested struct and apply it to its fields directly. This ensures that the nested defaults are respected.

Example (Using Nested Struct Constructors)

1
import { Schema } from "effect"
2

3
const Config = Schema.Struct({
4
  web: Schema.Struct({
5
    application_url: Schema.String.pipe(
6
      Schema.propertySignature,
7
      Schema.withConstructorDefault(() => "http://localhost"),
8
    ),
9
    application_port: Schema.Number,
10
  }),
11
})
12

13
// Extract the nested struct constructor
14
const { web: Web } = Config.fields
15

16
// Use the constructor for the nested struct
17
console.log(Config.make({ web: Web.make({ application_port: 3000 }) }))
18
/*
19
Output:
20
{
21
  web: {
22
    application_url: 'http://localhost',
23
    application_port: 3000
24
  }
25
}
26
*/

Lazy Evaluation of Defaults

Defaults are lazily evaluated, meaning that a new instance of the default is generated every time the constructor is called:

Example (Lazy Evaluation of Defaults)

In this example, the timestamp field generates a new value for each instance.

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Number.pipe(
6
    Schema.propertySignature,
7
    Schema.withConstructorDefault(() => 0),
8
  ),
9
  timestamp: Schema.Number.pipe(
10
    Schema.propertySignature,
11
    Schema.withConstructorDefault(() => new Date().getTime()),
12
  ),
13
})
14

15
console.log(Person.make({ name: "name1" }))
16
/*
17
Example Output:
18
{ age: 0, timestamp: 1714232909221, name: 'name1' }
19
*/
20

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

Reusing Defaults Across Schemas

Default values are also “portable”, meaning that if you reuse the same property signature in another schema, the default is carried over:

Example (Reusing Defaults in Another Schema)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Number.pipe(
6
    Schema.propertySignature,
7
    Schema.withConstructorDefault(() => 0),
8
  ),
9
  timestamp: Schema.Number.pipe(
10
    Schema.propertySignature,
11
    Schema.withConstructorDefault(() => new Date().getTime()),
12
  ),
13
})
14

15
const AnotherSchema = Schema.Struct({
16
  foo: Schema.String,
17
  age: Person.fields.age,
18
})
19

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

Using Defaults in Classes

Default values can also be applied when working with the Class API, ensuring consistency across class-based schemas.

Example (Defaults in a Class)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Number.pipe(
6
    Schema.propertySignature,
7
    Schema.withConstructorDefault(() => 0),
8
  ),
9
  timestamp: Schema.Number.pipe(
10
    Schema.propertySignature,
11
    Schema.withConstructorDefault(() => new Date().getTime()),
12
  ),
13
}) {}
14

15
console.log(new Person({ name: "name1" }))
16
/*
17
Example Output:
18
Person { age: 0, timestamp: 1714400867208, name: 'name1' }
19
*/
20

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