Skip to content
Effect Days 2026 Get your ticket

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 Added in v2.0.0 Source

Combining

assign

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v4.0.0 Source

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

Added in v2.0.0 Source

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

Added in v3.6.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v2.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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 }