Skip to content
Effect Days 2026 Get your ticket

Types

Provides compile-time utility types for TypeScript.

Everything in this module is type-level only; it does not define runtime values. The types are used throughout Effect to work with tuple lengths, object shapes, tagged unions, reason-tagged errors, mutability, exactness, required keys, concurrency settings, and variance markers.

35 exports Added in v2.0.0 Source

Models

Concurrency type

Added in v2.0.0 Source

Describes the concurrency level for Effect operations that run multiple effects.

When to use

Use to type options that control how many effects may run at the same time.

Details

  • number — run at most N effects concurrently.
  • "unbounded" — run all effects concurrently with no limit.

Signature

type Concurrency = number | "unbounded"

Example

(Setting concurrency values)

import type { Types } from "effect"


const sequential: Types.Concurrency = 1
const limited: Types.Concurrency = 5
const unbounded: Types.Concurrency = "unbounded"

Other

Contravariant

Added in v3.9.0 Source

Namespace for Contravariant-related utilities.

When to use

Use when referring to type-level helpers nested under Contravariant.

Covariant

Added in v3.9.0 Source

Namespace for Covariant-related utilities.

When to use

Use when referring to type-level helpers nested under Covariant.

Invariant

Added in v3.9.0 Source

Namespace for Invariant-related utilities.

When to use

Use when referring to type-level helpers nested under Invariant.

Utility Types

Contravariant type

Added in v2.0.0 Source

Function-type alias encoding contravariant variance for a phantom type parameter.

When to use

Use as a phantom field type to make a type parameter contravariant in input position.

Details

Contravariant<A> is assignable to Contravariant<B> when B extends A, following the supertype direction.

See

Signature

type Contravariant<A> = (_: A) => void

Example

(Defining a contravariant phantom type)

import type { Types } from "effect"


interface Consumer<T> {
  readonly _phantom: Types.Contravariant<T>
  readonly accept: (value: T) => void
}


const consumer: Consumer<string> = {
  _phantom: () => {},
  accept: (_value) => {}
}

Covariant type

Added in v2.0.0 Source

Function-type alias encoding covariant variance for a phantom type parameter.

When to use

Use as a phantom field type to make a type parameter covariant in output position.

Details

Covariant<A> is assignable to Covariant<B> when A extends B, following the subtype direction.

See

Signature

type Covariant<A> = (_: never) => A

Example

(Defining a covariant phantom type)

import type { Types } from "effect"


interface Producer<T> {
  readonly _phantom: Types.Covariant<T>
  readonly get: () => T
}


const producer: Producer<string> = { _phantom: () => "value", get: () => "value" }

DeepMutable type

Added in v3.1.0 Source

Recursively removes readonly from all properties, including nested objects, arrays, Map, and Set.

When to use

Use when you need a fully mutable version of a deeply readonly type.

Details

Recursion stops at primitives (string, number, boolean, bigint, symbol) and functions.

See

Signature

type DeepMutable<T> = T extends ReadonlyMap<infer K, infer V> ? Map<DeepMutable<K>, DeepMutable<V>> : T extends ReadonlySet<infer V> ? Set<DeepMutable<V>> : T extends string | number | boolean | bigint | symbol | Function ? T : { [K in keyof T]: DeepMutable<T[K]> }

Example

(Converting deeply to mutable types)

import type { Types } from "effect"


type Deep = Types.DeepMutable<{
  readonly a: string
  readonly b: ReadonlyArray<{ readonly c: number }>
}>
// { a: string; b: Array<{ c: number }> }


const witness: Deep = { a: "value", b: [{ c: 1 }] }
witness.b[0].c = 2

Equals type

Added in v2.0.0 Source

Determines if two types are exactly equal at the type level.

When to use

Use to assert type equality in conditional types or type-level tests.

Details

  • Uses the <T>() => T extends X ? 1 : 2 trick for exact equality, distinguishing between any, unknown, never, and other types.
  • Resolves to true if X and Y are identical, false otherwise.

See

Signature

type Equals<X, Y> = <T>() => T extends X ? 1 : 2 extends <T>() => T extends Y ? 1 : 2 ? true : false

Example

(Checking type equality)

import type { Types } from "effect"


type Yes = Types.Equals<{ a: number }, { a: number }> // true
type No = Types.Equals<{ a: number }, { a: string }> // false
type AnyCheck = Types.Equals<any, string> // false

EqualsWith type

Added in v3.15.0 Source

Determines if two types are equal, returning custom types for each case.

When to use

Use when you need a type-level if/else based on type equality.

Details

Returns Y when A and B are equal, N otherwise.

See

Signature

type EqualsWith<A, B, Y, N> = <T>() => T extends A ? 1 : 2 extends <T>() => T extends B ? 1 : 2 ? Y : N

Example

(Choosing a conditional type based on equality)

import type { Types } from "effect"


type R1 = Types.EqualsWith<string, string, "same", "diff"> // "same"
type R2 = Types.EqualsWith<string, number, "same", "diff"> // "diff"

ExcludeReason type

Added in v4.0.0 Source

Excludes a specific reason variant by its _tag from an error's reason field.

When to use

Use when you need the remaining nested reason union type after removing variants handled by _tag, rather than the enclosing error type.

Details

Returns never if E has no reason field.

See

Signature

type ExcludeReason<E, K extends string> = E extends {
  readonly reason: infer R;
} ? Exclude<R, {
  readonly _tag: K;
}> : never

Example

(Excluding a reason variant)

import type { Types } from "effect"


type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
type QuotaError = { readonly _tag: "QuotaError"; readonly limit: number }
type ApiError = { readonly _tag: "ApiError"; readonly reason: RateLimitError | QuotaError }


type Result = Types.ExcludeReason<ApiError, "RateLimitError">
// { readonly _tag: "QuotaError"; readonly limit: number }


const witness: Result = { _tag: "QuotaError", limit: 10 }

ExcludeTag type

Added in v2.0.0 Source

Excludes members of a tagged union by their _tag value.

When to use

Use to remove tagged-union members whose _tag matches a specific value in type-level code.

Details

Non-tagged members of the union are preserved.

See

Signature

type ExcludeTag<E, K extends string> = Exclude<E, {
  readonly _tag: K;
}>

Example

(Removing a variant)

import type { Types } from "effect"


type MyError =
  | { readonly _tag: "NotFound"; readonly id: string }
  | { readonly _tag: "Timeout"; readonly ms: number }
  | string


type WithoutTimeout = Types.ExcludeTag<MyError, "Timeout">
// { readonly _tag: "NotFound"; readonly id: string } | string


const witness: WithoutTimeout = { _tag: "NotFound", id: "1" }

ExtractReason type

Added in v4.0.0 Source

Extracts a specific reason variant by its _tag from an error's reason field.

When to use

Use when you need the nested reason variant type itself, selected by _tag, rather than the enclosing error type.

Details

Returns never if E has no matching reason variant.

See

Signature

type ExtractReason<E, K extends string> = E extends {
  readonly reason: infer R;
} ? R extends {
  readonly _tag: infer T;
} ? K extends T ? R : never : never : never

Example

(Extracting a reason variant)

import type { Types } from "effect"


type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
type QuotaError = { readonly _tag: "QuotaError"; readonly limit: number }
type ApiError = { readonly _tag: "ApiError"; readonly reason: RateLimitError | QuotaError }


type Result = Types.ExtractReason<ApiError, "RateLimitError">
// { readonly _tag: "RateLimitError"; readonly retryAfter: number }


const witness: Result = { _tag: "RateLimitError", retryAfter: 30 }

ExtractTag type

Added in v2.0.0 Source

Extracts a specific member of a tagged union by its _tag value.

When to use

Use to select tagged-union members whose _tag matches a specific value in type-level code.

Details

Returns never if no member matches the tag.

See

Signature

type ExtractTag<E, K extends string> = E extends {
  readonly _tag: infer T;
} ? K extends T ? E : never : never

Example

(Extracting a variant)

import type { Types } from "effect"


type MyError =
  | { readonly _tag: "NotFound"; readonly id: string }
  | { readonly _tag: "Timeout"; readonly ms: number }


type TimeoutError = Types.ExtractTag<MyError, "Timeout">
// { readonly _tag: "Timeout"; readonly ms: number }


const witness: TimeoutError = { _tag: "Timeout", ms: 100 }

Has type

Added in v2.0.0 Source

Checks whether an object type contains any of the specified keys.

When to use

Use to branch type-level logic when at least one key from a candidate key set exists on an object type.

Details

Returns true if at least one key from Key exists in A, false otherwise.

Signature

type Has<A, Key extends string> = Key extends infer K ? K extends keyof A ? true : never : never extends never ? false : true

Example

(Checking key presence)

import type { Types } from "effect"


type Yes = Types.Has<{ a: number; b: string }, "a" | "c"> // true
type No = Types.Has<{ a: number }, "b" | "c"> // false

Invariant type

Added in v2.0.0 Source

Function-type alias encoding invariant variance for a phantom type parameter.

When to use

Use as a phantom field type to make a type parameter invariant, neither covariant nor contravariant.

Details

A value of type Invariant<A> cannot be assigned to Invariant<B> unless A and B are the same type.

See

Signature

type Invariant<A> = (_: A) => A

Example

(Defining an invariant phantom type)

import type { Types } from "effect"


interface Container<T> {
  readonly _phantom: Types.Invariant<T>
  readonly value: T
}


const container: Container<number> = { _phantom: (value) => value, value: 1 }

IsUnion type

Added in v4.0.0 Source

Checks whether a type T is a union type.

When to use

Use to branch type-level logic depending on whether a type is a union.

Details

  • Compares [T] against [UnionToIntersection<T>]. If they differ, T must be a union.
  • Returns true if T is a union of two or more members.
  • Returns false for single types, never, or any.

See

Signature

type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true

Example

(Detecting union types)

import type { Types } from "effect"


type Yes = Types.IsUnion<"a" | "b"> // true
type No = Types.IsUnion<string> // false

MergeLeft type

Added in v2.0.0 Source

Left-biased merge of two object types where keys from Source take precedence over Target on conflict.

When to use

Use when you want left-biased merging where the first argument wins.

Details

Implemented as MergeRight<Target, Source>.

See

Signature

type MergeLeft<Source, Target> = MergeRight<Target, Source>

Example

(Merging with left bias)

import type { Types } from "effect"


type Result = Types.MergeLeft<
  { a: number; b: number },
  { a: string; c: boolean }
>
// { a: number; b: number; c: boolean }


const witness: Result = { a: 1, b: 2, c: true }

MergeRight type

Added in v2.0.0 Source

Right-biased merge of two object types where keys from Source take precedence over Target on conflict.

When to use

Use when you want right-biased merging where the second argument wins.

Details

The result is automatically simplified via Simplify.

See

Signature

type MergeRight<Target, Source> = Simplify<Source & { [Key in keyof Target]: Target[Key] }>

Example

(Right-biased merge)

import type { Types } from "effect"


type Result = Types.MergeRight<
  { a: number; b: number },
  { a: string; c: boolean }
>
// { a: string; b: number; c: boolean }


const witness: Result = { a: "value", b: 2, c: true }

Mutable type

Added in v2.0.0 Source

Removes readonly from all properties of T. Supports arrays, tuples, and records.

When to use

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

Details

Only affects the top level; nested properties remain readonly.

See

Signature

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

Example

(Converting shallowly to mutable types)

import type { Types } from "effect"


type Obj = Types.Mutable<{
  readonly a: string
  readonly b: ReadonlyArray<number>
}>
// { a: string; b: ReadonlyArray<number> }
//   ^ mutable    ^ still readonly inside


type Arr = Types.Mutable<ReadonlyArray<string>>
// string[]


type Tup = Types.Mutable<readonly [string, number]>
// [string, number]


const tuple: Tup = ["value", 1]
tuple[1] = 2

NarrowReason type

Added in v4.0.0 Source

Narrows a specific reason variant by its _tag from an error's reason field.

When to use

Use to preserve the original error shape while narrowing its nested reason field to the matching variant.

Details

Returns never if E has no matching reason variant.

See

Signature

type NarrowReason<E, K extends string> = E extends {
  readonly reason: infer R;
} ? R extends {
  readonly _tag: infer T;
} ? K extends T ? E & {
  readonly reason: R;
} : never : never : never

Example

(Narrowing a reason variant)

import type { Types } from "effect"


type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
type QuotaError = { readonly _tag: "QuotaError"; readonly limit: number }
type ApiError = { readonly _tag: "ApiError"; readonly reason: RateLimitError | QuotaError }


type Result = Types.NarrowReason<ApiError, "RateLimitError">
// ApiError & { readonly reason: { readonly _tag: "RateLimitError"; readonly retryAfter: number } }


const witness: Result = {
  _tag: "ApiError",
  reason: { _tag: "RateLimitError", retryAfter: 30 }
}

NoExcessProperties type

Added in v3.9.0 Source

Constrains a type to prevent excess properties not present in T.

When to use

Use to catch accidental extra properties in generic functions at compile time.

Details

Extra keys from U that are not in T are mapped to never.

Signature

type NoExcessProperties<T, U> = T & Readonly<Record<Exclude<keyof U, keyof T>, never>>

Example

(Preventing extra properties)

import type { Types } from "effect"


type Expected = { a: number; b: string }
type Input = { a: number; b: string; c: boolean }


type Result = Types.NoExcessProperties<Expected, Input>
// { a: number; b: string; readonly c: never }


const accepted: Types.NoExcessProperties<Expected, Expected> = { a: 1, b: "value" }

NoInfer type

Added in v2.0.0 Source

Prevents TypeScript from inferring a type parameter from a specific position.

When to use

Use when a function parameter must match an inferred type without becoming an inference source.

Details

The parameter using NoInfer must still match the inferred type.

Signature

type NoInfer<A> = [A][A extends any ? 0 : never]

Example

(Controlling inference)

import type { Types } from "effect"


function withDefault<T>(value: T, _fallback: Types.NoInfer<T>): T {
  return value
}


// T is inferred as "a" | "b" from the first argument only
const result = withDefault<"a" | "b">("a", "b")

NotFunction type

Added in v2.0.0 Source

Excludes function types from a union, keeping only non-function members.

When to use

Use to filter out callable types from a union.

Details

Returns never if the entire union consists of function types.

Signature

type NotFunction<T> = T extends Function ? never : T

Example

(Filtering out functions)

import type { Types } from "effect"


type Result = Types.NotFunction<string | (() => void) | number>
// string | number


const witness: Result = "value"

OmitReason type

Added in v4.0.0 Source

Narrows an error's reason field to exclude a specific reason variant by its _tag.

When to use

Use to narrow the error to only the remaining reason variants after excluding the matched one.

Details

Returns never if E has no reason field or no remaining variants.

See

Signature

type OmitReason<E, K extends string> = E extends {
  readonly reason: infer R;
} ? R extends {
  readonly _tag: infer T;
} ? K extends T ? never : E & {
  readonly reason: R;
} : never : never

Example

(Omitting a reason variant)

import type { Types } from "effect"


type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
type QuotaError = { readonly _tag: "QuotaError"; readonly limit: number }
type ApiError = { readonly _tag: "ApiError"; readonly reason: RateLimitError | QuotaError }


type Result = Types.OmitReason<ApiError, "RateLimitError">
// ApiError & { readonly reason: { readonly _tag: "QuotaError"; readonly limit: number } }


const witness: Result = {
  _tag: "ApiError",
  reason: { _tag: "QuotaError", limit: 10 }
}

ReasonOf type

Added in v4.0.0 Source

Extracts the reason type from an error that has a reason field.

When to use

Use when an error type stores nested sub-errors in a reason field and you need that field's full union type as a standalone type.

Details

Returns never if E has no reason field.

See

Signature

type ReasonOf<E> = E extends {
  readonly reason: infer R;
} ? R : never

Example

(Extracting reason types)

import type { Types } from "effect"


type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
type QuotaError = { readonly _tag: "QuotaError"; readonly limit: number }
type ApiError = { readonly _tag: "ApiError"; readonly reason: RateLimitError | QuotaError }


type Reasons = Types.ReasonOf<ApiError>
// RateLimitError | QuotaError


const witness: Reasons = { _tag: "QuotaError", limit: 10 }

ReasonTags type

Added in v4.0.0 Source

Extracts the _tag values from the reason type of an error.

When to use

Use to get the discriminant values available inside a nested reason error union.

Details

This is shorthand for Tags<ReasonOf<E>>. It returns never if E has no reason field or the reason has no _tag.

See

Signature

type ReasonTags<E> = E extends {
  readonly reason: {
    readonly _tag: string;
  };
} ? E["reason"]["_tag"] : never

Example

(Getting reason tags)

import type { Types } from "effect"


type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
type QuotaError = { readonly _tag: "QuotaError"; readonly limit: number }
type ApiError = { readonly _tag: "ApiError"; readonly reason: RateLimitError | QuotaError }


type Result = Types.ReasonTags<ApiError>
// "RateLimitError" | "QuotaError"


const witness: Result = "RateLimitError"

RequiredKeys type

Added in v4.0.0 Source

Extracts the required keys from a type.

When to use

Use to derive the keys whose properties must be present on an object type.

Signature

type RequiredKeys<T> = { [K in keyof T]: {} extends Pick<T, K> ? never : K }[keyof T]

Simplify type

Added in v2.0.0 Source

Flattens an intersection type into a single object type for readability.

When to use

Use to clean up IDE tooltips that show A & B & C instead of a merged object.

Details

Does not change the type semantically, only its display.

See

Signature

type Simplify<A> = { [K in keyof A]: A[K] } extends infer B ? B : never

Example

(Simplifying an intersection)

import type { Types } from "effect"


// Without Simplify: IDE shows { a: number } & { b: string }
// With Simplify: IDE shows { a: number; b: string }
type Clean = Types.Simplify<{ a: number } & { b: string }>


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

Tags type

Added in v2.0.0 Source

Extracts the _tag string literal types from a union.

When to use

Use to get all discriminant values from a tagged union type.

Details

Members without a _tag field are ignored and produce never.

See

Signature

type Tags<E> = E extends {
  readonly _tag: string;
} ? E["_tag"] : never

Example

(Extracting tags)

import type { Types } from "effect"


type MyError =
  | { readonly _tag: "NotFound"; readonly id: string }
  | { readonly _tag: "Timeout"; readonly ms: number }
  | string


type Result = Types.Tags<MyError>
// "NotFound" | "Timeout"


const witness: Result = "NotFound"

TupleOf type

Added in v3.3.0 Source

Constructs a tuple type with exactly N elements of type T.

When to use

Use when you need a fixed-length array type, especially instead of manually writing [T, T, T, ...] for longer tuples.

Details

  • If N is a literal number, produces a tuple of that exact length.
  • If N is the general number type (non-literal), degrades to Array<T>.
  • Negative numbers produce never.

See

Signature

type TupleOf<N extends number, T> = N extends N ? number extends N ? Array<T> : TupleOf_<T, N, []> : never

Example

(Checking fixed-length tuples)

import type { Types } from "effect"


// Exactly 3 numbers
const triple: Types.TupleOf<3, number> = [1, 2, 3]


// @ts-expect-error - too few elements
const tooFew: Types.TupleOf<3, number> = [1, 2]


// @ts-expect-error - too many elements
const tooMany: Types.TupleOf<3, number> = [1, 2, 3, 4]

TupleOfAtLeast type

Added in v3.3.0 Source

Constructs a tuple type with at least N elements of type T.

When to use

Use when you need a minimum-length array type that still allows additional elements. This is useful for variadic function signatures that require a minimum arity.

Details

Produces a tuple with N fixed positions followed by ...Array<T>.

See

Signature

type TupleOfAtLeast<N extends number, T> = [...TupleOf<N, T>, ...Array<T>]

Example

(Checking minimum-length tuples)

import type { Types } from "effect"


// At least 2 strings
const ok1: Types.TupleOfAtLeast<2, string> = ["a", "b"]
const ok2: Types.TupleOfAtLeast<2, string> = ["a", "b", "c", "d"]


// @ts-expect-error - too few elements
const bad: Types.TupleOfAtLeast<2, string> = ["a"]

unassigned interface

Added in v4.0.0 Source

Branded marker interface representing an unassigned type parameter.

When to use

Use when Effect's type-level machinery needs to represent a type parameter that has not been assigned yet.

Details

Used internally by the Effect type system to indicate that a type parameter has not been assigned a concrete type.

See

Signature

interface unassigned {
  readonly _: typeof _;
}

unhandled interface

Added in v4.0.0 Source

Branded marker interface representing an unhandled error type.

When to use

Use when Effect's type-level machinery needs to represent an error type that has not been handled yet.

Details

Used internally by the Effect type system to indicate that an error type has not been handled.

See

Signature

interface unhandled {
  readonly _: typeof _;
}

UnionToIntersection type

Added in v2.0.0 Source

Transforms a union type into an intersection type.

When to use

Use to combine all members of a union into a single type with all their properties. This is useful in advanced generic code where you need to merge union variants.

Details

  • Uses distributive conditional types and contra-variant inference.
  • If the union members are incompatible (e.g. string | number), the result is never.

See

Signature

type UnionToIntersection<T> = T extends any ? (x: T) => any : never extends (x: infer R) => any ? R : never

Example

(Converting a union to an intersection)

import type { Types } from "effect"


type Union = { a: string } | { b: number }
type Result = Types.UnionToIntersection<Union>
// { a: string } & { b: number }


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

VoidIfEmpty type

Added in v3.19.20 Source

Conditional type that returns void if S is an empty object type, otherwise returns S.

When to use

Use to erase an empty object type from an API result or parameter position.

Signature

type VoidIfEmpty<S> = keyof S extends never ? void : S