Default Constructors

Every schema exposes constructors for creating values of its Type while applying constructor defaults and type-side checks.

Use make when a failure should throw, makeOption when you only need to know whether construction succeeded, and makeEffect when you need the SchemaError in the Effect error channel.

Example (Using a Refinement Default Constructor)

1
import { Schema } from "effect"
2

3
const schema = Schema.FiniteFromString.check(
4
  Schema.isBetween({ minimum: 1, maximum: 10 }),
5
)
6

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

11
// This will throw an error because the number is outside the valid range
12
console.log(schema.make(20))
13
/*
14
throws:
15
Expected a number between 1 and 10
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
Expected a value with a length of at least 1
15
  at ["name"]
16
*/

When the input is already trusted, make can skip schema checks. This is not recommended for untrusted values.

Example (Skipping Checks)

1
import { Schema } from "effect"
2

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

7
// Skip checks when the input is already trusted
8
Struct.make({ name: "" }, { disableChecks: 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(Schema.String, Schema.NonEmptyString)
4

5
// Successful creation
6
Record.make({ a: "a", b: "b" })
7

8
// This will throw an error because 'b' is empty
9
Record.make({ a: "a", b: "" })
10
/*
11
throws
12
Expected a value with a length of at least 1
13
  at ["b"]
14
*/
15

16
// Skips checks
17
Record.make({ a: "a", b: "" }, { disableChecks: 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.Finite.check(
4
  Schema.isBetween({ minimum: 1, maximum: 10 }),
5
)
6

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

10
// This will throw an error because the number is outside the valid range
11
MyNumber.make(20)
12
/*
13
throws
14
Expected a value between 1 and 10
15
*/
16

17
// Skips checks
18
MyNumber.make(20, { disableChecks: 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.Finite.pipe(
4
  Schema.check(Schema.isBetween({ minimum: 1, maximum: 10 })),
5
  Schema.brand("MyNumber"),
6
)
7

8
// Successful creation
9
const n = BrandedNumberSchema.make(5)
10

11
// This will throw an error because the number is outside the valid range
12
BrandedNumberSchema.make(20)
13
/*
14
throws
15
Expected a value between 1 and 10
16
*/
17

18
// Skips checks
19
BrandedNumberSchema.make(20, { disableChecks: 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

make is appropriate when invalid constructor input is exceptional. If failure is expected, use makeOption or makeEffect instead.

makeOption returns Option.some on success and Option.none for schema issues. Use makeEffect when you need the full SchemaError.

Example (Constructing Without Throwing)

1
import { Option, Schema } from "effect"
2

3
const schema = Schema.FiniteFromString.check(
4
  Schema.isBetween({ minimum: 1, maximum: 10 }),
5
)
6

7
schema.makeOption(5) // => Option.some(5)
8
schema.makeOption(20) // => Option.none()
9

10
// Effect.Effect<number, SchemaError>
11
const safely = schema.makeEffect(20)

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.Finite,
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 { Effect, Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Finite.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
6
})
7

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

15
console.log(Person.make({ name: "John", age: 30 }))
16
/*
17
Output:
18
{ name: 'John', age: 30 }
19
*/

Nested Defaults

Constructor defaults compose through nested schemas. Inner defaults are resolved after the value for the outer field is supplied or defaulted.

Example (Resolving Nested Defaults)

1
import { Effect, Schema } from "effect"
2

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

14
console.log(Config.make({}))
15
/*
16
Output:
17
{
18
  web: {
19
    application_url: 'http://localhost',
20
    application_port: 3000
21
  }
22
}
23
*/

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 { Effect, Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Finite.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
6
  timestamp: Schema.Finite.pipe(
7
    Schema.withConstructorDefault(Effect.sync(() => new Date().getTime())),
8
  ),
9
})
10

11
console.log(Person.make({ name: "name1" }))
12
/*
13
Example Output:
14
{ age: 0, timestamp: 1714232909221, name: 'name1' }
15
*/
16

17
console.log(Person.make({ name: "name2" }))
18
/*
19
Example Output:
20
{ age: 0, timestamp: 1714232909227, name: 'name2' }
21
*/

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 { Effect, Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Finite.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
6
  timestamp: Schema.Finite.pipe(
7
    Schema.withConstructorDefault(Effect.sync(() => new Date().getTime())),
8
  ),
9
})
10

11
const AnotherSchema = Schema.Struct({
12
  foo: Schema.String,
13
  age: Person.fields.age,
14
})
15

16
console.log(AnotherSchema.make({ foo: "bar" }))
17
/*
18
Output:
19
{ foo: 'bar', age: 0 }
20
*/

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 { Effect, Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  name: Schema.NonEmptyString,
5
  age: Schema.Finite.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
6
  timestamp: Schema.Finite.pipe(
7
    Schema.withConstructorDefault(Effect.sync(() => new Date().getTime())),
8
  ),
9
}) {}
10

11
console.log(new Person({ name: "name1" }))
12
/*
13
Example Output:
14
Person { age: 0, timestamp: 1714400867208, name: 'name1' }
15
*/
16

17
console.log(new Person({ name: "name2" }))
18
/*
19
Example Output:
20
Person { age: 0, timestamp: 1714400867215, name: 'name2' }
21
*/