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

Tuple.ts overview

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

Since v2.0.0

Exports Grouped by Category

combinators

getEquivalence

Given a tuple of Equivalences returns a new Equivalence that compares values of a tuple by applying each Equivalence to the corresponding element of the tuple.

Signature

declare const getEquivalence: <T extends ReadonlyArray<Equivalence.Equivalence<any>>>(
  ...isEquivalents: T
) => Equivalence.Equivalence<
  Readonly<{ [I in keyof T]: [T[I]] extends [Equivalence.Equivalence<infer A>] ? A : never }>
>

Source

Since v2.0.0

getOrder

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

Source

Since v2.0.0

concatenating

appendElement

Appends an element to the end of a tuple.

Signature

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

Source

Since v2.0.0

constructors

make

Constructs a new tuple from the provided values.

Example

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

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

Signature

declare const make: <A extends ReadonlyArray<any>>(...elements: A) => A

Source

Since v2.0.0

getters

at

Retrieves the element at a specified index from a tuple.

Example

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

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

Signature

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

Source

Since v3.4.0

getFirst

Return the first element of a tuple.

Example

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

assert.deepStrictEqual(getFirst(["hello", 42]), "hello")

Signature

declare const getFirst: <L, R>(self: readonly [L, R]) => L

Source

Since v2.0.0

getSecond

Return the second element of a tuple.

Example

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

assert.deepStrictEqual(getSecond(["hello", 42]), 42)

Signature

declare const getSecond: <L, R>(self: readonly [L, R]) => R

Source

Since v2.0.0

guards

isTupleOf

Determine if an Array is a tuple with exactly N elements, narrowing down the type to TupleOf.

An Array is considered to be a TupleOf if its length is exactly N.

Example

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

assert.deepStrictEqual(isTupleOf([1, 2, 3], 3), true)
assert.deepStrictEqual(isTupleOf([1, 2, 3], 2), false)
assert.deepStrictEqual(isTupleOf([1, 2, 3], 4), false)

const arr: number[] = [1, 2, 3]
if (isTupleOf(arr, 3)) {
  console.log(arr)
  // ^? [number, number, number]
}

Signature

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

Source

Since v3.3.0

isTupleOfAtLeast

Determine if an Array is a tuple with at least N elements, narrowing down the type to TupleOfAtLeast.

An Array is considered to be a TupleOfAtLeast if its length is at least N.

Example

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

assert.deepStrictEqual(isTupleOfAtLeast([1, 2, 3], 3), true)
assert.deepStrictEqual(isTupleOfAtLeast([1, 2, 3], 2), true)
assert.deepStrictEqual(isTupleOfAtLeast([1, 2, 3], 4), false)

const arr: number[] = [1, 2, 3, 4]
if (isTupleOfAtLeast(arr, 3)) {
  console.log(arr)
  // ^? [number, number, number, ...number[]]
}

Signature

declare const isTupleOfAtLeast: {
  <N extends number>(n: N): <T>(self: ReadonlyArray<T>) => self is TupleOfAtLeast<N, T>
  <T, N extends number>(self: ReadonlyArray<T>, n: N): self is TupleOfAtLeast<N, T>
}

Source

Since v3.3.0

mapping

map

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

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"])

Signature

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

Source

Since v3.9.0

mapBoth

Transforms both elements of a tuple using the given functions.

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"
])

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

Source

Since v2.0.0

mapFirst

Transforms the first component of a tuple using a given function.

Example

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

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

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

Source

Since v2.0.0

mapSecond

Transforms the second component of a tuple using a given function.

Example

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

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

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

Source

Since v2.0.0

type lambdas

TupleTypeLambda (interface)

Signature

export interface TupleTypeLambda extends TypeLambda {
  readonly type: [this["Out1"], this["Target"]]
}

Source

Since v2.0.0

utils

swap

Swaps the two elements of a tuple.

Example

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

assert.deepStrictEqual(swap(["hello", 42]), [42, "hello"])

Signature

declare const swap: <L, R>(self: readonly [L, R]) => [R, L]

Source

Since v2.0.0