types.ts 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.
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; IntersectAndSimplify and ToKeyIntersection help build intersections in conditional types.

Runtime guards for these shapes live in MPredicate.

Common tasks

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

Models

AnyArray (interface)

Type that represents an array

Signature

export interface AnyArray extends Array<any> {}

Source

AnyFunction (interface)

Type that represents a function. Don’t use Function. For instance, value of type Function cannot be passed to MPredicate.isOneArgFunction

Signature

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

Source

AnyPredicate (type alias)

Type that represents any predicate or refinement

Signature

type AnyPredicate = Predicate.Predicate.Any

Source

AnyReadonlyArray (interface)

Type that represents a ReadonlyArray

Signature

export interface AnyReadonlyArray extends ReadonlyArray<any> {}

Source

AnyRefinement (type alias)

Type that represents any refinement

Signature

type AnyRefinement = Predicate.Refinement.Any

Source

NonNullablePrimitive (type alias)

Type that represents a primitive except null and undefined

Signature

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

Source

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. Roughly equivalent to the native object type (which is called ObjectKeyword in effect) 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
}

Source

NumberFromString (interface)

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

Signature

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

Source

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. Introduced because Predicate.isObject refines to this type but never intoduces it. And to pinpoint differences with NonPrimitive.

See

NonPrimitive — Includes class instances but also functions and arrays.

Signature

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

Source

OneArgFunction (interface)

Type that represents a function with one argument

Signature

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

Source

OverOne (type alias)

Type that represents a non empty array

Signature

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

Source

OverTwo (type alias)

Type that represents an array with at least two elements

Signature

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

Source

Pair (type alias)

Type that represents a tuple or array with two elements

Signature

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

Source

Primitive (type alias)

Type that represents a primitive

Signature

type Primitive = NonNullablePrimitive | null | undefined

Source

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
}

Source

ReadonlyObject (interface)

Same as Object but readonly

Signature

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

Source

ReadonlyOverOne (type alias)

Type that represents a non empty array

Signature

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

Source

ReadonlyOverTwo (type alias)

Type that represents an array with at least two elements

Signature

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

Source

ReadonlyPair (type alias)

Type that represents a tuple or array with two elements

Signature

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

Source

ReadonlySingleton (type alias)

Type that represents a tuple or array with one element

Signature

type ReadonlySingleton<A> = readonly [A]

Source

ReadonlyUnknown (type alias)

Same as Unknown but readonly

Signature

type ReadonlyUnknown = Primitive | ReadonlyNonPrimitive

Source

Singleton (type alias)

Type that represents a tuple or array with one element

Signature

type Singleton<A> = [A]

Source

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> {}

Source

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

type Unknown = Primitive | NonPrimitive

Source

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

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] }

Source

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

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

Source

MapToTarget (type alias)

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

Signature

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

Source

Proto (type alias)

Utility type that removes all data from a type.

Signature

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

Source

ToKeyIntersection (type alias)

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

Signature

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

Source

WithMutable (type alias)

Utility type that makes field field of target type X mutable

Signature

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]
}

Source

WithRequired (type alias)

Utility type that makes field field of target type X required

Signature

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]
}

Source