Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

Struct

Works with plain TypeScript objects, also called structs.

The runtime helpers in this module create new objects instead of mutating their inputs. They cover common object workflows such as reading properties, listing typed keys, picking or omitting fields, assigning and renaming keys, transforming values, deriving comparison helpers, and creating records from a list of keys. The module also includes type-level helpers for simplifying and merging object shapes.

23 exports Since v2.0.0 Source

Combining

assign

Since v4.0.0

Merges two structs into a new struct. When both structs share a key, the value from that (the second struct) wins.

When to use

Use when you want { ...self, ...that } with proper types.

Details

The result type is Simplify<Assign<S, O>>.

See

  • Assign – the type-level equivalent
  • evolve – transform individual values instead of replacing them

Signature

declare const assign: {
  <O extends object>(that: O): <S extends object>(self: S) => { [K in string | number | symbol]: keyof S & keyof O extends never ? S & O : Omit<S, keyof S & keyof O> & O[K] };
  <O extends object, S extends object>(self: S, that: O): { [K in string | number | symbol]: keyof S & keyof O extends never ? S & O : Omit<S, keyof S & keyof O> & O[K] };
}

Example Merging structs with overlapping keys 

import { pipe, Struct } from "effect"


const defaults = { theme: "light", lang: "en" }
const overrides = { theme: "dark", fontSize: 14 }
pipe(defaults, Struct.assign(overrides)) // => { theme: "dark", lang: "en", fontSize: 14 }

makeCombiner

Since v4.0.0

Creates a Combiner for a struct shape by providing a Combiner for each property. When two structs are combined, each property is merged using its corresponding combiner.

When to use

Use when you need to merge two same-shape records by combining each property independently, such as summing counters or concatenating strings.

Details

Pass omitKeyWhen to drop properties whose merged value matches a predicate, such as omitting zero counters.

See

  • makeReducer – like makeCombiner but with an initial value

Signature

declare function makeCombiner<A>(combiners: { [K in string | number | symbol]: Combiner<A[K]> }, options?: {
  readonly omitKeyWhen?: (a: A[keyof A]) => boolean;
}): Combiner<A>

Example Combining struct properties 

import { Number, String, Struct } from "effect"


const C = Struct.makeCombiner<{ readonly n: number; readonly s: string }>({
  n: Number.ReducerSum,
  s: String.ReducerConcat
})


C.combine({ n: 1, s: "hello" }, { n: 2, s: " world" }) // => { n: 3, s: "hello world" }

Constructors

lambda

Since v4.0.0

Wraps a plain function as a Lambda value so it can be used with map, mapPick, and mapOmit.

When to use

Use to create a typed lambda for struct mapping APIs that need type-level input and output tracking.

Details

The type parameter L encodes both the input and output types at the type level, allowing the compiler to track how struct value types change. At runtime, the returned value is the same function; lambda only adjusts the type.

See

  • Lambda – the type-level interface
  • map – apply a lambda to all struct values

Signature

declare function lambda<L extends (a: any) => any>(f: (a: Parameters<L>[0]) => ReturnType<L>): L

Example Wrapping values in arrays 

import { pipe, Struct } from "effect"


interface AsArray extends Struct.Lambda {
  <A>(self: A): Array<A>
  readonly "~lambda.out": Array<this["~lambda.in"]>
}


const asArray = Struct.lambda<AsArray>((a) => [a])
const result = pipe({ x: 1, y: "hello" }, Struct.map(asArray))
result // => { x: [1], y: ["hello"] }

Record

Since v4.0.0

Creates a record with the given keys and value.

When to use

Use to build an object where each provided key receives the same value.

Signature

declare function Record<Keys extends readonly Array<string | symbol>, Value>(keys: Keys, value: Value): Record<Keys[number], Value>

Example Creating a record 

import { Struct } from "effect"


Struct.Record(["a", "b"], "value") // => { a: "value", b: "value" }

Filtering

omit

Since v2.0.0

Creates a new struct with the specified keys removed.

When to use

Use to exclude sensitive or irrelevant fields from a struct.

Gotchas

Keys not present in the struct are silently ignored.

See

  • pick – the inverse (keep only specified keys)

Signature

declare const omit: {
  <S extends object, Keys extends readonly Array<keyof S>>(keys: Keys): (self: S) => { [K in string | number | symbol]: Omit<S, Keys[number]>[K] };
  <S extends object, Keys extends readonly Array<keyof S>>(self: S, keys: Keys): { [K in string | number | symbol]: Omit<S, Keys[number]>[K] };
}

Example Removing a property 

import { pipe, Struct } from "effect"


const user = { name: "Alice", age: 30, password: "secret" }
pipe(user, Struct.omit(["password"])) // => { name: "Alice", age: 30 }

pick

Since v2.0.0

Creates a new struct containing only the specified keys.

When to use

Use to narrow a struct down to a subset of its properties.

Gotchas

Keys not present in the struct are silently ignored.

See

  • omit – the inverse (exclude keys instead)
  • get – extract a single value

Signature

declare const pick: {
  <S extends object, Keys extends readonly Array<keyof S>>(keys: Keys): (self: S) => { [K in string | number | symbol]: Pick<S, Keys[number]>[K] };
  <S extends object, Keys extends readonly Array<keyof S>>(self: S, keys: Keys): { [K in string | number | symbol]: Pick<S, Keys[number]>[K] };
}

Example Selecting specific properties 

import { pipe, Struct } from "effect"


const user = { name: "Alice", age: 30, admin: true }
pipe(user, Struct.pick(["name", "age"])) // => { name: "Alice", age: 30 }

Folding

makeReducer

Since v4.0.0

Creates a Reducer for a struct shape by providing a Reducer for each property. The initial value is derived from each property's Reducer.initialValue. When reducing a collection of structs, each property is combined independently.

When to use

Use when you need to fold same-shape records by accumulating each property independently into one summary record.

Details

Pass omitKeyWhen to drop properties whose reduced value matches a predicate.

See

  • makeCombiner – like makeReducer but without an initial value

Signature

declare function makeReducer<A>(reducers: { [K in string | number | symbol]: Reducer<A[K]> }, options?: {
  readonly omitKeyWhen?: (a: A[keyof A]) => boolean;
}): Reducer<A>

Example Reducing a collection of structs 

import { Number, String, Struct } from "effect"


const R = Struct.makeReducer<{ readonly n: number; readonly s: string }>({
  n: Number.ReducerSum,
  s: String.ReducerConcat
})


const result = R.combineAll([
  { n: 1, s: "a" },
  { n: 2, s: "b" },
  { n: 3, s: "c" }
])
result // => { n: 6, s: "abc" }

Getters

get

Since v2.0.0

Retrieves the value at key from a struct.

When to use

Use to extract a single property from a struct in a pipeline.

Details

The return type is narrowed to S[K].

See

  • keys – list all string keys of a struct
  • pick – extract multiple properties into a new struct

Signature

declare const get: {
  <S extends object, K extends string | number | symbol>(key: K): (self: S) => S[K];
  <S extends object, K extends string | number | symbol>(self: S, key: K): S[K];
}

Example Extracting a property in a pipeline 

import { pipe, Struct } from "effect"


pipe({ name: "Alice", age: 30 }, Struct.get("name")) // => "Alice"

keys

Since v3.6.0

Returns the string keys of a struct as a properly typed Array<keyof S & string>.

When to use

Use when you want a typed replacement for Object.keys that narrows the result to the known string keys of the struct.

Gotchas

Symbol keys are excluded; only string keys are returned.

See

  • get – access a single key's value
  • pick – select a subset of keys into a new struct

Signature

declare function keys<S extends object>(self: S): Array<keyof S & string>

Example Reading typed keys 

import { Struct } from "effect"


const user = { name: "Alice", age: 30, [Symbol.for("id")]: 1 }


const k: Array<"name" | "age"> = Struct.keys(user)
k // => ["name", "age"]

Instances

makeEquivalence

Since v4.0.0

Creates an Equivalence for a struct by providing an Equivalence for each property. Two structs are equivalent when all their corresponding properties are equivalent.

When to use

Use when you need equality for a record-like object to be decided field by field, with a custom equality rule for each property.

Details

This is an alias of Equivalence.Struct. Each property's equivalence is checked independently; all must return true for the overall result to be true.

See

Signature

declare const makeEquivalence: <R extends Record<string, Equivalence<any>>>(fields: R) => Equivalence<{ [K in string | number | symbol]: [R[K]] extends [Equivalence<A>] ? A : never }>

Example Comparing structs for equivalence 

import { Equivalence, Struct } from "effect"


const PersonEquivalence = Struct.makeEquivalence({
  name: Equivalence.strictEqual<string>(),
  age: Equivalence.strictEqual<number>()
})


PersonEquivalence({ name: "Alice", age: 30 }, { name: "Alice", age: 30 }) // => true
PersonEquivalence({ name: "Alice", age: 30 }, { name: "Bob", age: 30 }) // => false

Mapping

map

Since v4.0.0

Applies a Lambda transformation to every value in a struct.

When to use

Use when you want to apply the same function to every value in a struct.

Details

The lambda must be created with lambda so the compiler can track the output types.

See

  • mapPick – apply a lambda only to selected keys
  • mapOmit – apply a lambda to all keys except selected ones
  • evolve – apply different functions to different keys

Signature

declare const map: {
  <L extends Lambda>(lambda: L): <S extends object>(self: S) => { [K in string | number | symbol]: Apply<L, S[K]> };
  <S extends object, L extends Lambda>(self: S, lambda: L): { [K in string | number | symbol]: Apply<L, S[K]> };
}

Example Wrapping every value in an array 

import { pipe, Struct } from "effect"


interface AsArray extends Struct.Lambda {
  <A>(self: A): Array<A>
  readonly "~lambda.out": Array<this["~lambda.in"]>
}


const asArray = Struct.lambda<AsArray>((a) => [a])
const result = pipe({ width: 10, height: 20 }, Struct.map(asArray))
result // => { width: [10], height: [20] }

mapOmit

Since v4.0.0

Applies a Lambda transformation to all keys except the specified ones; the excluded keys are copied unchanged.

When to use

Use when most keys should be transformed but a few should be preserved.

See

  • map – apply a lambda to all keys
  • mapPick – apply a lambda only to selected keys

Signature

declare const mapOmit: {
  <S extends object, Keys extends readonly Array<keyof S>, L extends Lambda>(keys: Keys, lambda: L): (self: S) => { [K in string | number | symbol]: K extends Keys[number] ? S[K] : Apply<L, S[K]> };
  <S extends object, Keys extends readonly Array<keyof S>, L extends Lambda>(self: S, keys: Keys, lambda: L): { [K in string | number | symbol]: K extends Keys[number] ? S[K] : Apply<L, S[K]> };
}

Example Wrapping all values except one in arrays 

import { pipe, Struct } from "effect"


interface AsArray extends Struct.Lambda {
  <A>(self: A): Array<A>
  readonly "~lambda.out": Array<this["~lambda.in"]>
}


const asArray = Struct.lambda<AsArray>((a) => [a])
const result = pipe(
  { x: 1, y: 2, z: 3 },
  Struct.mapOmit(["y"], asArray)
)
result // => { x: [1], y: 2, z: [3] }

mapPick

Since v4.0.0

Applies a Lambda transformation only to the specified keys; all other keys are copied unchanged.

When to use

Use when you want to apply the same transformation to a subset of properties.

See

  • map – apply a lambda to all keys
  • mapOmit – apply a lambda to all keys except selected ones

Signature

declare const mapPick: {
  <S extends object, Keys extends readonly Array<keyof S>, L extends Lambda>(keys: Keys, lambda: L): (self: S) => { [K in string | number | symbol]: K extends Keys[number] ? Apply<L, S[K]> : S[K] };
  <S extends object, Keys extends readonly Array<keyof S>, L extends Lambda>(self: S, keys: Keys, lambda: L): { [K in string | number | symbol]: K extends Keys[number] ? Apply<L, S[K]> : S[K] };
}

Example Wrapping only selected values in arrays 

import { pipe, Struct } from "effect"


interface AsArray extends Struct.Lambda {
  <A>(self: A): Array<A>
  readonly "~lambda.out": Array<this["~lambda.in"]>
}


const asArray = Struct.lambda<AsArray>((a) => [a])
const result = pipe(
  { x: 1, y: 2, z: 3 },
  Struct.mapPick(["x", "z"], asArray)
)
result // => { x: [1], y: 2, z: [3] }

Ordering

makeOrder

Since v4.0.0

Creates an Order for a struct by providing an Order for each property. Properties are compared in the order they appear in the fields object; the first non-zero comparison determines the result.

When to use

Use when you need to sort record-like objects lexicographically by several fields, with each field using its own ordering rule.

Details

This is an alias of Order.Struct. The order of keys in the fields object determines comparison priority.

See

Signature

declare const makeOrder: <R extends {
  [x: string]: Order<any>;
}>(fields: R) => Order<{ [K in string | number | symbol]: [R[K]] extends [Order<A>] ? A : never }>

Example Ordering structs by name then age 

import { Number, String, Struct } from "effect"


const PersonOrder = Struct.makeOrder({
  name: String.Order,
  age: Number.Order
})


PersonOrder({ name: "Alice", age: 30 }, { name: "Bob", age: 25 }) // => -1

Transforming

evolve

Since v2.0.0

Transforms values of a struct selectively using per-key functions. Keys without a corresponding function are copied unchanged.

When to use

Use when you want to update specific fields while keeping the rest intact.

Details

Each transform function receives the current value and returns the new value; the return type can differ from the input type.

See

  • evolveKeys – transform keys instead of values
  • evolveEntries – transform both keys and values
  • map – apply the same transformation to all values

Signature

declare const evolve: {
  <S extends object, E extends Evolver<S>>(e: E): (self: S) => { [K in string | number | symbol]: { [K in string | number | symbol]: K extends keyof E ? E[K] extends (...a: any) => R ? R : S[K] : S[K] }[K] };
  <S extends object, E extends Evolver<S>>(self: S, e: E): { [K in string | number | symbol]: { [K in string | number | symbol]: K extends keyof E ? E[K] extends (...a: any) => R ? R : S[K] : S[K] }[K] };
}

Example Transforming selected values 

import { pipe, Struct } from "effect"


const result = pipe(
  { name: "alice", age: 30, active: true },
  Struct.evolve({
    name: (s) => s.toUpperCase(),
    age: (n) => n + 1
  })
)
result // => { name: "ALICE", age: 31, active: true }

evolveEntries

Since v4.0.0

Transforms both keys and values of a struct selectively. Each per-key function receives (key, value) and must return a [newKey, newValue] tuple. Keys without a corresponding function are copied unchanged.

When to use

Use when you need to rename a key and change its value in one step.

Details

The return type is fully tracked at the type level.

See

Signature

declare const evolveEntries: {
  <S extends object, E extends EntryEvolver<S>>(e: E): (self: S) => EntryEvolved<S, E>;
  <S extends object, E extends EntryEvolver<S>>(self: S, e: E): EntryEvolved<S, E>;
}

Example Transforming keys and values together 

import { pipe, Struct } from "effect"


const result = pipe(
  { amount: 100, label: "total" },
  Struct.evolveEntries({
    amount: (k, v) => [`${k}Cents`, v * 100],
    label: (k, v) => [k, v.toUpperCase()]
  })
)
result // => { amountCents: 10000, label: "TOTAL" }

evolveKeys

Since v4.0.0

Transforms keys of a struct selectively using per-key functions. Keys without a corresponding function are copied unchanged.

When to use

Use when you need computed key names, such as uppercasing or prefixing.

Details

Each transform function receives the key name and must return a new PropertyKey.

See

Signature

declare const evolveKeys: {
  <S extends object, E extends KeyEvolver<S>>(e: E): (self: S) => { [K in string | number | symbol]: { [K in string | number | symbol]: S[K] }[K] };
  <S extends object, E extends KeyEvolver<S>>(self: S, e: E): { [K in string | number | symbol]: { [K in string | number | symbol]: S[K] }[K] };
}

Example Renaming keys with functions 

import { pipe, Struct } from "effect"


const result = pipe(
  { name: "Alice", age: 30 },
  Struct.evolveKeys({
    name: (k) => k.toUpperCase()
  })
)
result // => { NAME: "Alice", age: 30 }

renameKeys

Since v4.0.0

Renames keys in a struct using a static { oldKey: newKey } mapping. Keys not mentioned in the mapping are copied unchanged.

When to use

Use when you need simple, declarative key renaming without custom logic.

Details

For computed key names, use evolveKeys instead.

See

Signature

declare const renameKeys: {
  <S extends object, M extends { [K in string | number | symbol]: PropertyKey }>(mapping: M): (self: S) => { [K in string | number | symbol]: S[K] };
  <S extends object, M extends { [K in string | number | symbol]: PropertyKey }>(self: S, mapping: M): { [K in string | number | symbol]: S[K] };
}

Example Renaming keys 

import { pipe, Struct } from "effect"


const result = pipe(
  { firstName: "Alice", lastName: "Smith", age: 30 },
  Struct.renameKeys({ firstName: "first", lastName: "last" })
)
result // => { first: "Alice", last: "Smith", age: 30 }

Utility Types

Apply

type
Since v4.0.0

Applies a Lambda type-level function to a value type V, producing the output type.

When to use

Use when you need to compute what type a Lambda would produce for a given input.

Details

This works by intersecting the Lambda with { "~lambda.in": V } and reading "~lambda.out".

See

  • Lambda – the base interface

Signature

type Apply<L extends Lambda, V> = L & {
  readonly "~lambda.in": V;
}["~lambda.out"]

Example Computing the output type of a lambda 

import type { Struct } from "effect"


interface ToString extends Struct.Lambda {
  readonly "~lambda.out": string
}


// string
type Result = Struct.Apply<ToString, number>


const witness: Result = "value"

Assign

type
Since v4.0.0

Merges two object types with properties from U taking precedence over T on overlapping keys (like Object.assign at the type level).

When to use

Use when you need the type-level equivalent of { ...T, ...U }.

Details

When no keys overlap, this returns a simple intersection for efficiency. When keys overlap, the type from U wins.

See

  • assign – the runtime equivalent
  • Simplify – flatten the resulting intersection

Signature

type Assign<T, U> = Simplify<keyof T & keyof U extends never ? T & U : Omit<T, keyof T & keyof U> & U>

Example Merging two types with overlapping keys 

import type { Struct } from "effect"


type A = { a: string; b: number }
type B = { b: boolean; c: string }
type Merged = Struct.Assign<A, B>
// { a: string; b: boolean; c: string }


const witness: Merged = { a: "value", b: true, c: "other" }

Lambda

interface
Since v4.0.0

Interface for type-level functions used by map, mapPick, and mapOmit.

When to use

Use when defining a typed function for map, mapPick, or mapOmit.

Details

Extend this interface with concrete ~lambda.in and ~lambda.out types to describe how a function transforms values at the type level. At runtime, create lambda values with lambda.

See

  • Apply – apply a Lambda to a concrete type
  • lambda – create a runtime lambda value
  • map – use a lambda to transform all struct values

Signature

interface Lambda {
  readonly "~lambda.in": unknown;
  readonly "~lambda.out": unknown;
}

Example Defining a lambda type 

import type { Struct } from "effect"


interface ToString extends Struct.Lambda {
  readonly "~lambda.out": string
}


const witness: ToString = { "~lambda.in": 1, "~lambda.out": "1" }

Mutable

type
Since v4.0.0

Removes readonly modifiers from all properties of an object type.

When to use

Use when you need a mutable version of a readonly interface.

Details

This helper is purely cosmetic at the type level and has no runtime effect. It also flattens intersections like Simplify.

See

  • Simplify – flattens intersections without removing readonly

Signature

type Mutable<T> = { [K in keyof T]: T[K] } & {}

Example Making a readonly type mutable 

import type { Struct } from "effect"


type ReadOnly = { readonly a: string; readonly b: number }
type Writable = Struct.Mutable<ReadOnly>
// { a: string; b: number }


const witness: Writable = { a: "value", b: 1 }
witness.b = 2
witness // => { a: "value", b: 2 }

Simplify

type
Since v4.0.0

Flattens intersection types into a single object type for readability.

When to use

Use when hovering over a type shows A & B & C instead of the merged shape.

Details

This helper is purely cosmetic at the type level and has no runtime effect. It preserves readonly modifiers; use Mutable to strip them.

See

  • Mutable – also flattens but removes readonly
  • Assign – merges two types with right-side precedence

Signature

type Simplify<T> = { [K in keyof T]: T[K] } & {}

Example Flattening an intersection 

import type { Struct } from "effect"


type Original = { a: string } & { b: number }


// Without Simplify, the type displays as `{ a: string } & { b: number }`
type Simplified = Struct.Simplify<Original>
// { a: string; b: number }


const witness: Simplified = { a: "value", b: 1 }