Tuple

This module provides utility functions for working with tuples in TypeScript.

15 exports Added in v2.0.0 Source

This function creates and returns a new Order for a tuple of values based on the given Orders for each element in the tuple. The returned Order compares two tuples of the same type by applying the corresponding Order to each element in the tuple. It is useful when you need to compare two tuples of the same type and you have a specific way of comparing each element of the tuple.

Signature

declare const getOrder: <T extends ReadonlyArray<order.Order<any>>>(
  ...elements: T
) => order.Order<{ [I in keyof T]: [T[I]] extends [order.Order<infer A>] ? A : never }>;

Concatenating

appendElement

Added in v2.0.0 Source

Appends an element to the end of a tuple.

Signature

declare const appendElement: {
  <B>(that: B): <A extends readonly Array<unknown>>(self: A) => [...Array<A>, B];
  <A extends readonly Array<unknown>, B>(self: A, that: B): [...Array<A>, B];
}

Constructors

make

Added in v2.0.0 Source

Constructs a new tuple from the provided values.

Signature

declare function make<A extends readonly Array<any>>(...elements: A): A

Getters

at

Added in v3.4.0 Source

Retrieves the element at a specified index from a tuple.

Signature

declare const at: {
  <N extends number>(index: N): <A extends readonly Array<unknown>>(self: A) => A[N];
  <A extends readonly Array<unknown>, N extends number>(self: A, index: N): A[N];
}

Example

import * as assert from "node:assert"
import { Tuple } from "effect"

assert.deepStrictEqual(Tuple.at([1, "hello", true], 1), "hello")

getFirst

Added in v2.0.0 Source

Return the first element from a tuple with two elements.

Signature

declare function getFirst<L, R>(self: readonly [L, R]): L;

getSecond

Added in v2.0.0 Source

Return the second element from a tuple with two elements.

Signature

declare function getSecond<L, R>(self: readonly [L, R]): R;

Guards

isTupleOf

Added in v3.3.0 Source

A refinement that checks if a ReadonlyArray<T> is a tuple with exactly N elements. If the check is successful, the type is narrowed to TupleOf<N, T>.

Signature

declare const isTupleOf: {
  <N extends number>(n: N): <T>(self: readonly Array<T>) => self is TupleOf<N, T>;
  <T, N extends number>(self: readonly Array<T>, n: N): self is TupleOf<N, T>;
}

Example

import * as assert from "node:assert"
import { isTupleOf } from "effect/Predicate"

const isTupleOf3 = isTupleOf(3)

assert.strictEqual(isTupleOf3([1, 2, 3]), true)
assert.strictEqual(isTupleOf3([1, 2]), false)

const arr: number[] = [1, 2, 3]
if (isTupleOf(arr, 3)) {
  // The type of arr is now [number, number, number]
  const [a, b, c] = arr
  assert.deepStrictEqual([a, b, c], [1, 2, 3])
}

isTupleOfAtLeast

Added in v3.3.0 Source

A refinement that checks if a ReadonlyArray<T> is a tuple with at least N elements. If the check is successful, the type is narrowed to TupleOfAtLeast<N, T>.

Signature

declare const isTupleOfAtLeast: {
  <N extends number>(n: N): <T>(self: readonly Array<T>) => self is [...Array<TupleOf<N, T>>, ...Array<T>];
  <T, N extends number>(self: readonly Array<T>, n: N): self is [...Array<TupleOf<N, T>>, ...Array<T>];
}

Example

import * as assert from "node:assert"
import { isTupleOfAtLeast } from "effect/Predicate"

const isTupleOfAtLeast3 = isTupleOfAtLeast(3)

assert.strictEqual(isTupleOfAtLeast3([1, 2, 3]), true)
assert.strictEqual(isTupleOfAtLeast3([1, 2, 3, 4]), true)
assert.strictEqual(isTupleOfAtLeast3([1, 2]), false)

const arr: number[] = [1, 2, 3, 4]
if (isTupleOfAtLeast(arr, 3)) {
  // The type of arr is now [number, number, number, ...number[]]
  const [a, b, c] = arr
  assert.deepStrictEqual([a, b, c], [1, 2, 3])
}

Mapping

map

Added in v3.9.0 Source

Transforms each element of tuple using the given function, treating tuple homomorphically

Signature

declare const map: {
  <T extends readonly Array<any> | [], B>(fn: (element: T[number]) => B): (self: T) => TupleOf<T["length"], B>;
  <B, T extends readonly Array<any> | []>(self: T, fn: (element: T[number]) => B): TupleOf<T["length"], B>;
}

Example

import * as assert from "node:assert"
import { pipe, Tuple } from "effect"

const result = pipe(
  ["a", 1, false] as const,
  Tuple.map((el) => el.toString().toUpperCase()),
)
assert.deepStrictEqual(result, ["A", "1", "FALSE"])

mapBoth

Added in v2.0.0 Source

Transforms both elements of a tuple with two elements using the given functions.

Signature

declare const mapBoth: {
  <L1, L2, R1, R2>(options: {
    readonly onFirst: (e: L1) => L2;
    readonly onSecond: (a: R1) => R2;
  }): (self: readonly [L1, R1]) => [L2, R2];
  <L1, R1, L2, R2>(
    self: readonly [L1, R1],
    options: {
      readonly onFirst: (e: L1) => L2;
      readonly onSecond: (a: R1) => R2;
    },
  ): [L2, R2];
};

Example

import * as assert from "node:assert"
import { mapBoth } from "effect/Tuple"

assert.deepStrictEqual(
  mapBoth(["hello", 42], { onFirst: (s) => s.toUpperCase(), onSecond: (n) => n.toString() }),
  ["HELLO", "42"],
)

mapFirst

Added in v2.0.0 Source

Transforms the first component of a tuple with two elements using a given function.

Signature

declare const mapFirst: {
  <L1, L2>(f: (left: L1) => L2): <R>(self: readonly [L1, R]) => [L2, R];
  <L1, R, L2>(self: readonly [L1, R], f: (left: L1) => L2): [L2, R];
};

Example

import * as assert from "node:assert"
import { mapFirst } from "effect/Tuple"

assert.deepStrictEqual(
  mapFirst(["hello", 42], (s) => s.toUpperCase()),
  ["HELLO", 42],
)

mapSecond

Added in v2.0.0 Source

Transforms the second component of a tuple with two elements using a given function.

Signature

declare const mapSecond: {
  <R1, R2>(f: (right: R1) => R2): <L>(self: readonly [L, R1]) => [L, R2];
  <L, R1, R2>(self: readonly [L, R1], f: (right: R1) => R2): [L, R2];
};

Example

import * as assert from "node:assert"
import { mapSecond } from "effect/Tuple"

assert.deepStrictEqual(
  mapSecond(["hello", 42], (n) => n.toString()),
  ["hello", "42"],
)

Other

swap

Added in v2.0.0 Source

Swaps the elements of a tuple with two elements.

Signature

declare function swap<L, R>(self: readonly [L, R]): [R, L];

Type Lambdas

TupleTypeLambda interface

Added in v2.0.0 Source

Signature

interface TupleTypeLambda extends TypeLambda {
  readonly type: [unknown, unknown];
}