@clayroach/effect 3.19.14-source-capture.8 → 3.19.14-source-trace.1

package/src/Tuple.ts

@@ -0,0 +1,305 @@
+/**
+ * This module provides utility functions for working with tuples in TypeScript.
+ *
+ * @since 2.0.0
+ */
+import * as Equivalence from "./Equivalence.js"
+import { dual } from "./Function.js"
+import type { TypeLambda } from "./HKT.js"
+import * as order from "./Order.js"
+import type { TupleOf } from "./Types.js"
+
+/**
+ * @category type lambdas
+ * @since 2.0.0
+ */
+export interface TupleTypeLambda extends TypeLambda {
+  readonly type: [this["Out1"], this["Target"]]
+}
+
+/**
+ * Constructs a new tuple from the provided values.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert"
+ * import { make } from "effect/Tuple"
+ *
+ * assert.deepStrictEqual(make(1, 'hello', true), [1, 'hello', true])
+ * ```
+ *
+ * @category constructors
+ * @since 2.0.0
+ */
+export const make = <A extends ReadonlyArray<any>>(...elements: A): A => elements
+
+/**
+ * Return the first element from a tuple with two elements.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert"
+ * import { getFirst } from "effect/Tuple"
+ *
+ * assert.deepStrictEqual(getFirst(["hello", 42]), "hello")
+ * ```
+ *
+ * @category getters
+ * @since 2.0.0
+ */
+export const getFirst = <L, R>(self: readonly [L, R]): L => self[0]
+
+/**
+ * Return the second element from a tuple with two elements.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert"
+ * import { getSecond } from "effect/Tuple"
+ *
+ * assert.deepStrictEqual(getSecond(["hello", 42]), 42)
+ * ```
+ *
+ * @category getters
+ * @since 2.0.0
+ */
+export const getSecond = <L, R>(self: readonly [L, R]): R => self[1]
+
+/**
+ * Transforms each element of tuple using the given function, treating tuple homomorphically
+ *
+ * @example
+ * ```ts
+ * 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'])
+ * ```
+ *
+ * @category mapping
+ * @since 3.9.0
+ */
+export 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>
+} = dual(
+  2,
+  <N extends number, A, B>(
+    self: TupleOf<N, A>,
+    fn: (element: A) => B
+  ): TupleOf<N, B> => self.map((element) => fn(element)) as TupleOf<N, B>
+)
+
+/**
+ * Transforms both elements of a tuple with two elements using the given functions.
+ *
+ * @example
+ * ```ts
+ * 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"]
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 2.0.0
+ */
+export 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]
+} = dual(
+  2,
+  <L1, R1, L2, R2>(
+    self: readonly [L1, R1],
+    { onFirst, onSecond }: {
+      readonly onFirst: (e: L1) => L2
+      readonly onSecond: (a: R1) => R2
+    }
+  ): [L2, R2] => [onFirst(self[0]), onSecond(self[1])]
+)
+
+/**
+ * Transforms the first component of a tuple with two elements using a given function.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert"
+ * import { mapFirst } from "effect/Tuple"
+ *
+ * assert.deepStrictEqual(
+ *   mapFirst(["hello", 42], s => s.toUpperCase()),
+ *   ["HELLO", 42]
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 2.0.0
+ */
+export 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]
+} = dual(2, <L1, R, L2>(self: readonly [L1, R], f: (left: L1) => L2): [L2, R] => [f(self[0]), self[1]])
+
+/**
+ * Transforms the second component of a tuple with two elements using a given function.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert"
+ * import { mapSecond } from "effect/Tuple"
+ *
+ * assert.deepStrictEqual(
+ *   mapSecond(["hello", 42], n => n.toString()),
+ *   ["hello", "42"]
+ * )
+ * ```
+ *
+ * @category mapping
+ * @since 2.0.0
+ */
+export 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]
+} = dual(2, <L, R1, R2>(self: readonly [L, R1], f: (right: R1) => R2): [L, R2] => [self[0], f(self[1])])
+
+/**
+ * Swaps the elements of a tuple with two elements.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert"
+ * import { swap } from "effect/Tuple"
+ *
+ * assert.deepStrictEqual(swap(["hello", 42]), [42, "hello"])
+ * ```
+ *
+ * @since 2.0.0
+ */
+export const swap = <L, R>(self: readonly [L, R]): [R, L] => [self[1], self[0]]
+
+/**
+ * Given a tuple of `Equivalence`s returns a new `Equivalence` that compares values of a tuple
+ * by applying each `Equivalence` to the corresponding element of the tuple.
+ *
+ * @category combinators
+ * @since 2.0.0
+ */
+export 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 }>
+> = Equivalence.tuple
+
+/**
+ * This function creates and returns a new `Order` for a tuple of values based on the given `Order`s 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.
+ *
+ * @category combinators
+ * @since 2.0.0
+ */
+export 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 }> = order.tuple
+
+/**
+ * Appends an element to the end of a tuple.
+ *
+ * @category concatenating
+ * @since 2.0.0
+ */
+export const appendElement: {
+  <B>(that: B): <A extends ReadonlyArray<unknown>>(self: A) => [...A, B]
+  <A extends ReadonlyArray<unknown>, B>(self: A, that: B): [...A, B]
+} = dual(2, <A extends ReadonlyArray<unknown>, B>(self: A, that: B): [...A, B] => [...self, that])
+
+/**
+ * Retrieves the element at a specified index from a tuple.
+ *
+ * @example
+ * ```ts
+ * import * as assert from "node:assert"
+ * import { Tuple } from "effect"
+ *
+ * assert.deepStrictEqual(Tuple.at([1, 'hello', true], 1), 'hello')
+ * ```
+ *
+ * @category getters
+ * @since 3.4.0
+ */
+export 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]
+} = dual(2, <A extends ReadonlyArray<unknown>, N extends number>(self: A, index: N): A[N] => self[index])
+
+export {
+  /**
+   * 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
+   * ```ts
+   * 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]
+   * }
+   *
+   * ```
+   * @category guards
+   * @since 3.3.0
+   */
+  isTupleOf,
+  /**
+   * 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
+   * ```ts
+   * 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[]]
+   * }
+   *
+   * ```
+   * @category guards
+   * @since 3.3.0
+   */
+  isTupleOfAtLeast
+} from "./Predicate.js"

package/src/Types.ts

@@ -0,0 +1,353 @@
+/**
+ * A collection of types that are commonly used types.
+ *
+ * @since 2.0.0
+ */
+
+type _TupleOf<T, N extends number, R extends Array<unknown>> = `${N}` extends `-${number}` ? never
+  : R["length"] extends N ? R
+  : _TupleOf<T, N, [T, ...R]>
+
+/**
+ * Represents a tuple with a fixed number of elements of type `T`.
+ *
+ * This type constructs a tuple that has exactly `N` elements of type `T`.
+ *
+ * @typeParam N - The number of elements in the tuple.
+ * @typeParam T - The type of elements in the tuple.
+ *
+ * @example
+ * ```ts
+ * import { TupleOf } from "effect/Types"
+ *
+ * // A tuple with exactly 3 numbers
+ * const example1: TupleOf<3, number> = [1, 2, 3]; // valid
+ * // @ts-expect-error
+ * const example2: TupleOf<3, number> = [1, 2]; // invalid
+ * // @ts-expect-error
+ * const example3: TupleOf<3, number> = [1, 2, 3, 4]; // invalid
+ * ```
+ *
+ * @category tuples
+ * @since 3.3.0
+ */
+export type TupleOf<N extends number, T> = N extends N ? number extends N ? Array<T> : _TupleOf<T, N, []> : never
+
+/**
+ * Represents a tuple with at least `N` elements of type `T`.
+ *
+ * This type constructs a tuple that has a fixed number of elements `N` of type `T` at the start,
+ * followed by any number (including zero) of additional elements of the same type `T`.
+ *
+ * @typeParam N - The minimum number of elements in the tuple.
+ * @typeParam T - The type of elements in the tuple.
+ *
+ * @example
+ * ```ts
+ * import { TupleOfAtLeast } from "effect/Types"
+ *
+ * // A tuple with at least 3 numbers
+ * const example1: TupleOfAtLeast<3, number> = [1, 2, 3]; // valid
+ * const example2: TupleOfAtLeast<3, number> = [1, 2, 3, 4, 5]; // valid
+ * // @ts-expect-error
+ * const example3: TupleOfAtLeast<3, number> = [1, 2]; // invalid
+ * ```
+ *
+ * @category tuples
+ * @since 3.3.0
+ */
+export type TupleOfAtLeast<N extends number, T> = [...TupleOf<N, T>, ...Array<T>]
+
+/**
+ * Returns the tags in a type.
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type Res = Types.Tags<string | { _tag: "a" } | { _tag: "b" } > // "a" | "b"
+ * ```
+ *
+ * @category types
+ * @since 2.0.0
+ */
+export type Tags<E> = E extends { _tag: string } ? E["_tag"] : never
+
+/**
+ * Excludes the tagged object from the type.
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type Res = Types.ExcludeTag<string | { _tag: "a" } | { _tag: "b" }, "a"> // string | { _tag: "b" }
+ * ```
+ *
+ * @category types
+ * @since 2.0.0
+ */
+export type ExcludeTag<E, K extends Tags<E>> = Exclude<E, { _tag: K }>
+
+/**
+ * Extracts the type of the given tag.
+ *
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type Res = Types.ExtractTag<{ _tag: "a", a: number } | { _tag: "b", b: number }, "b"> // { _tag: "b", b: number }
+ * ```
+ *
+ * @category types
+ * @since 2.0.0
+ */
+export type ExtractTag<E, K extends Tags<E>> = Extract<E, { _tag: K }>
+
+/**
+ * A utility type that transforms a union type `T` into an intersection type.
+ *
+ * @since 2.0.0
+ * @category types
+ */
+export type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R
+  : never
+
+/**
+ * Simplifies the type signature of a type.
+ *
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type Res = Types.Simplify<{ a: number } & { b: number }> // { a: number; b: number; }
+ * ```
+ *
+ * @since 2.0.0
+ * @category types
+ */
+export type Simplify<A> = {
+  [K in keyof A]: A[K]
+} extends infer B ? B : never
+
+/**
+ * Determines if two types are equal.
+ *
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type Res1 = Types.Equals<{ a: number }, { a: number }> // true
+ * type Res2 = Types.Equals<{ a: number }, { b: number }> // false
+ * ```
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <
+  T
+>() => T extends Y ? 1 : 2 ? true
+  : false
+
+/**
+ * Determines if two types are equal, allowing to specify the return types.
+ *
+ * @since 3.15.0
+ * @category models
+ */
+export type EqualsWith<A, B, Y, N> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? Y : N
+
+/**
+ * Determines if a record contains any of the given keys.
+ *
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type Res1 = Types.Has<{ a: number }, "a" | "b"> // true
+ * type Res2 = Types.Has<{ c: number }, "a" | "b"> // false
+ * ```
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof A ? true : never : never) extends never
+  ? false
+  : true
+
+/**
+ * Merges two object where the keys of the left object take precedence in the case of a conflict.
+ *
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ * type MergeLeft = Types.MergeLeft<{ a: number, b: number; }, { a: string }> // { a: number; b: number; }
+ * ```
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type MergeLeft<Source, Target> = MergeRight<Target, Source>
+
+/**
+ * Merges two object where the keys of the right object take precedence in the case of a conflict.
+ *
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ * type MergeRight = Types.MergeRight<{ a: number, b: number; }, { a: string }> // { a: string; b: number; }
+ * ```
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type MergeRight<Target, Source> = Simplify<
+  & Source
+  & {
+    [Key in keyof Target as Key extends keyof Source ? never : Key]: Target[Key]
+  }
+>
+
+/**
+ * @since 2.0.0
+ * @category models
+ */
+export type MergeRecord<Source, Target> = MergeLeft<Source, Target>
+
+/**
+ * Describes the concurrency to use when executing multiple Effect's.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type Concurrency = number | "unbounded" | "inherit"
+
+/**
+ * Make all properties in `T` mutable. Supports arrays, tuples, and records as well.
+ *
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type MutableStruct = Types.Mutable<{ readonly a: string; readonly b: number }> // { a: string; b: number; }
+ *
+ * type MutableArray = Types.Mutable<ReadonlyArray<string>> // string[]
+ *
+ * type MutableTuple = Types.Mutable<readonly [string, number]> // [string, number]
+ *
+ * type MutableRecord = Types.Mutable<{ readonly [_: string]: number }> // { [x: string]: number; }
+ * ```
+ *
+ * @since 2.0.0
+ * @category types
+ */
+export type Mutable<T> = {
+  -readonly [P in keyof T]: T[P]
+}
+
+/**
+ * Like `Types.Mutable`, but works recursively.
+ *
+ * @example
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type DeepMutableStruct = Types.DeepMutable<{
+ *   readonly a: string;
+ *   readonly b: readonly string[]
+ * }>
+ * // { a: string; b: string[] }
+ * ```
+ *
+ * @since 3.1.0
+ * @category types
+ */
+export type DeepMutable<T> = T extends ReadonlyMap<infer K, infer V> ? Map<DeepMutable<K>, DeepMutable<V>>
+  : T extends ReadonlySet<infer V> ? Set<DeepMutable<V>>
+  : T extends string | number | boolean | bigint | symbol | Function ? T
+  : { -readonly [K in keyof T]: DeepMutable<T[K]> }
+
+/**
+ * Avoid inference on a specific parameter
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type NoInfer<A> = [A][A extends any ? 0 : never]
+
+/**
+ * Invariant helper.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type Invariant<A> = (_: A) => A
+
+/**
+ * @since 3.9.0
+ * @category models
+ */
+export declare namespace Invariant {
+  /**
+   * @since 3.9.0
+   * @category models
+   */
+  export type Type<A> = A extends Invariant<infer U> ? U : never
+}
+
+/**
+ * Covariant helper.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type Covariant<A> = (_: never) => A
+
+/**
+ * @since 3.9.0
+ * @category models
+ */
+export declare namespace Covariant {
+  /**
+   * @since 3.9.0
+   * @category models
+   */
+  export type Type<A> = A extends Covariant<infer U> ? U : never
+}
+
+/**
+ * Contravariant helper.
+ *
+ * @since 2.0.0
+ * @category models
+ */
+export type Contravariant<A> = (_: A) => void
+
+/**
+ * @since 3.9.0
+ * @category models
+ */
+export declare namespace Contravariant {
+  /**
+   * @since 3.9.0
+   * @category models
+   */
+  export type Type<A> = A extends Contravariant<infer U> ? U : never
+}
+
+/**
+ * @since 2.0.0
+ */
+export type MatchRecord<S, onTrue, onFalse> = {} extends S ? onTrue : onFalse
+
+/**
+ * @since 2.0.0
+ */
+export type NotFunction<T> = T extends Function ? never : T
+
+/**
+ * @since 3.9.0
+ */
+export type NoExcessProperties<T, U> = T & { readonly [K in Exclude<keyof U, keyof T>]: never }
+
+/**
+ * @since 3.15.0
+ */
+export type Ctor<T = {}> = new(...args: Array<any>) => T