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/Schema.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]
}