Skip to main content Link Search Menu Expand Document (external link)
effect-libs

types overview

Foundational primitive / container types used throughout effect-lib.

Mental model

  • Containers: NonPrimitive, Object, Pair, Singleton, OverOne (non-empty), OverTwo (≥ 2 elements), and their readonly variants — typed views over Array/ReadonlyArray used by the rest of the package.
  • Primitives: Primitive, NonNullablePrimitive, Unknown — describe the shape space of JavaScript values.
  • All values type union: Unknown — same as unknown but defined as a type union, allows pattern matching.
  • Function shapes: AnyFunction, OneArgFunction, StringTransformer, NumberFromString.
  • Predicate / refinement shapes: AnyPredicate, AnyRefinement, RefinementFrom.
  • Type-level utilities: Data strips inherited / pipeable / equality fields off an object type to produce its plain-data view (used by class constructors); Proto is its complement; Tuple<T, N> materializes a fixed-size tuple; IntersectAndSimplify and ToKeyIntersection help build intersections in conditional types.

Runtime guards for these shapes live in MPredicate.

Common tasks

  • Tuple / array shapes: {@link Pair}, {@link Singleton}, {@link OverOne}, {@link OverTwo}
  • Primitive shapes: {@link Primitive}, {@link NonNullablePrimitive}, {@link NonPrimitive}, {@link Unknown}
  • Type-level helpers: {@link Data}, {@link Proto}, {@link Tuple}, {@link ReadonlyTuple}, {@link MapToTarget}, {@link IntersectAndSimplify}, {@link ToKeyIntersection}, {@link WithMutable}, {@link WithRequired}

Table of contents

Models

AnyArray (interface)

Type that represents an array

Signature

export interface AnyArray extends Array<any> {}

AnyFunction (interface)

Type that represents a function

Signature

export interface AnyFunction {
  (...args: ReadonlyArray<any>): any
}

AnyPredicate (type alias)

Type that represents any predicate or refinement

Signature

export type AnyPredicate = Predicate.Predicate.Any

AnyReadonlyArray (interface)

Type that represents a ReadonlyArray

Signature

export interface AnyReadonlyArray extends ReadonlyArray<any> {}

AnyRefinement (type alias)

Type that represents any refinement

Signature

export type AnyRefinement = Predicate.Refinement.Any

EmptyArray (type alias)

Type that represents an empty array or tuple

Signature

export type EmptyArray = []

EmptyReadonlyArray (type alias)

Type that represents an empty array or tuple

Signature

export type EmptyReadonlyArray = readonly []

NonNullablePrimitive (type alias)

Type that represents a primitive except null and undefined

Signature

export type NonNullablePrimitive = string | number | bigint | boolean | symbol

NonPrimitive (interface)

Type that represents anything but a JavaScript primitive. It includes records (in their usual computer science meaning), class instances, arrays, and functions but not null or undefined. Equivalent to the Effect ObjectKeyword type. Should be defined as an alias to the object type but the object type cannot be indexed so this definition is better

Signature

export interface NonPrimitive {
  // DO NOT REPLACE any by unknown: in that case, arrays and functions are excluded.
  [key: PropertyKey]: any
}

NumberFromString (interface)

Type that represents a function that transforms a string into a number.

Signature

export interface NumberFromString extends OneArgFunction<string, number> {}

Object (interface)

Type that represents a real object, not an array, not a function, not null. However, this type does not represent a class instance. So prefer using NonPrimitive when class instances are important (even though this type includes functions and arrays which may not be desirable)

Signature

export interface Object {
  [x: PropertyKey]: unknown
}

OneArgFunction (interface)

Type that represents a function with one argument

Signature

export interface OneArgFunction<in A, out B = A> {
  (a: A): B
}

OverOne (type alias)

Type that represents a non empty array

Signature

export type OverOne<A> = [A, ...Array<A>]

OverTwo (type alias)

Type that represents an array with at least two elements

Signature

export type OverTwo<A> = [A, A, ...Array<A>]

Pair (type alias)

Type that represents a tuple or array with two elements

Signature

export type Pair<A, B> = [A, B]

Primitive (type alias)

Type that represents a primitive

Signature

export type Primitive = NonNullablePrimitive | null | undefined

ReadonlyNonPrimitive (interface)

Same as NonPrimitive but readonly

Signature

export interface ReadonlyNonPrimitive {
  // DO NOT REPLACE any by unknown: in that case, arrays and functions are excluded.
  readonly [key: PropertyKey]: any
}

ReadonlyObject (interface)

Same as Object but readonly

Signature

export interface ReadonlyObject {
  readonly [x: PropertyKey]: unknown
}

ReadonlyOverOne (type alias)

Type that represents a non empty array

Signature

export type ReadonlyOverOne<A> = readonly [A, ...ReadonlyArray<A>]

ReadonlyOverTwo (type alias)

Type that represents an array with at least two elements

Signature

export type ReadonlyOverTwo<A> = readonly [A, A, ...ReadonlyArray<A>]

ReadonlyPair (type alias)

Type that represents a tuple or array with two elements

Signature

export type ReadonlyPair<A, B> = readonly [A, B]

ReadonlySingleton (type alias)

Type that represents a tuple or array with one element

Signature

export type ReadonlySingleton<A> = readonly [A]

ReadonlyUnknown (type alias)

Same as Unknown but readonly

Signature

export type ReadonlyUnknown = Primitive | ReadonlyNonPrimitive

RefinementFrom (type alias)

Type that represents any refinement from a given type

Signature

export type RefinementFrom<Source> = Predicate.Refinement<Source, any>

Singleton (type alias)

Type that represents a tuple or array with one element

Signature

export type Singleton<A> = [A]

StringTransformer (interface)

Type of a string transformer, i.e. a function that transforms a string into another one

Signature

export interface StringTransformer extends OneArgFunction<string> {}

Unknown (type alias)

Type that represents all possible Javascript values but not all possible Typescript types (it does not represent Branded types for instance)

Signature

export type Unknown = Primitive | NonPrimitive

Utility types

Data (type alias)

Utility type that removes all non-data. An Optionals parameter can be passed with a list of fields to make optional

Signature

export type Data<T extends NonPrimitive, Optionals extends string = never> = {
  [
    k in keyof T as [k] extends [
      symbol | `_${string}` | "toString" | "toJSON" | "pipe" | typeof Equal.symbol | typeof Hash.symbol | Optionals
    ]
      ? never
      : k
  ]: T[k]
} & { [k in keyof T as [k] extends [Optionals] ? k : never]?: T[k] }

IntersectAndSimplify (type alias)

Utility type that creates an intersection and simplifies it which Typescript does not do by itself (see https://stackoverflow.com/questions/72395823/why-does-typescript-not-simplify-the- intersection-of-a-type-and-one-of-its-super)

Signature

export type IntersectAndSimplify<T, U> = [T] extends [U] ? T : [U] extends [T] ? U : T & U

MapToTarget (type alias)

Utility type that changes the types of all keys of a tuple, array, struct or record to Target

Signature

export type MapToTarget<T, Target> = {
  [k in keyof T]: Target
}

Proto (type alias)

Utility type that removes all data from a type.

Signature

export type Proto<T extends NonPrimitive> = Omit<T, keyof Data<T>>

ReadonlyTuple (type alias)

Utility type that generates a readonly tuple of N T’s

Signature

export type ReadonlyTuple<T, N extends number> = Readonly<Tuple<T, N>>

ToKeyIntersection (type alias)

Utility type that creates an intersection of the types all keys of a type. Meant to be used with Tuples even though not set as a constraint

Signature

export type ToKeyIntersection<T> = [
  {
    readonly [K in keyof T]: (x: T[K]) => void
  }
] extends [
  {
    readonly [K: number]: (x: infer I) => void
  }
]
  ? I
  : never

Tuple (type alias)

Utility type that generates a tuple of N T’s

Signature

export type Tuple<T, N extends number> = N extends N ? (number extends N ? Array<T> : _TupleOf<T, N, []>) : never

WithMutable (type alias)

Utility type that makes field field of target type X mutable

Signature

export type WithMutable<X, field extends string | symbol> = {
  readonly [k in keyof X as [k] extends [field] ? never : k]: X[k]
} & {
  -readonly [k in keyof X as [k] extends readonly [field] ? k : never]: X[k]
}

WithRequired (type alias)

Utility type that makes field field of target type X required

Signature

export type WithRequired<X, field extends string | symbol> = {
  readonly [k in keyof X as readonly [k] extends readonly [field] ? never : k]: X[k]
} & {
  readonly [k in keyof X as readonly [k] extends readonly [field] ? k : never]-?: X[k]
}