effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/Function.ts

@@ -21,7 +21,7 @@ import { pipeArguments } from "./Pipeable.ts"
  *
  * **Example** (Creating a function type with a type lambda)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Function, HKT } from "effect"
  *
  * // Create a function type using the type lambda
@@ -29,7 +29,7 @@ import { pipeArguments } from "./Pipeable.ts"
  * // Equivalent to: (a: string) => number
  * ```
  *
- * @category type lambdas
+ * @category utility types
  * @since 2.0.0
  */
 export interface FunctionTypeLambda extends TypeLambda {
@@ -53,7 +53,7 @@ export interface FunctionTypeLambda extends TypeLambda {
  *
  * **Example** (Selecting data-first or data-last style by arity)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function, pipe } from "effect"
  *
  * const sum = Function.dual<
@@ -61,13 +61,13 @@ export interface FunctionTypeLambda extends TypeLambda {
  *   (self: number, that: number) => number
  * >(2, (self, that) => self + that)
  *
- * console.log(sum(2, 3)) // 5
- * console.log(pipe(2, sum(3))) // 5
+ * sum(2, 3) // => 5
+ * pipe(2, sum(3)) // => 5
  * ```
  *
  * **Example** (Defining overloads with call signatures)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function, pipe } from "effect"
  *
  * const sum: {
@@ -75,13 +75,13 @@ export interface FunctionTypeLambda extends TypeLambda {
  *   (self: number, that: number): number
  * } = Function.dual(2, (self: number, that: number): number => self + that)
  *
- * console.log(sum(2, 3)) // 5
- * console.log(pipe(2, sum(3))) // 5
+ * sum(2, 3) // => 5
+ * pipe(2, sum(3)) // => 5
  * ```
  *
  * **Example** (Selecting data-first or data-last style with a predicate)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function, pipe } from "effect"
  *
  * const sum = Function.dual<
@@ -92,8 +92,8 @@ export interface FunctionTypeLambda extends TypeLambda {
  *   (self, that) => self + that
  * )
  *
- * console.log(sum(2, 3)) // 5
- * console.log(pipe(2, sum(3))) // 5
+ * sum(2, 3) // => 5
+ * pipe(2, sum(3)) // => 5
  * ```
  *
  * @category combinators
@@ -117,7 +117,7 @@ export const dual: {
    *
    * **Example** (Selecting data-first or data-last style by arity)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Function, pipe } from "effect"
    *
    * const sum = Function.dual<
@@ -125,13 +125,13 @@ export const dual: {
    *   (self: number, that: number) => number
    * >(2, (self, that) => self + that)
    *
-   * console.log(sum(2, 3)) // 5
-   * console.log(pipe(2, sum(3))) // 5
+   * sum(2, 3) // => 5
+   * pipe(2, sum(3)) // => 5
    * ```
    *
    * **Example** (Defining overloads with call signatures)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Function, pipe } from "effect"
    *
    * const sum: {
@@ -139,13 +139,13 @@ export const dual: {
    *   (self: number, that: number): number
    * } = Function.dual(2, (self: number, that: number): number => self + that)
    *
-   * console.log(sum(2, 3)) // 5
-   * console.log(pipe(2, sum(3))) // 5
+   * sum(2, 3) // => 5
+   * pipe(2, sum(3)) // => 5
    * ```
    *
    * **Example** (Selecting data-first or data-last style with a predicate)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Function, pipe } from "effect"
    *
    * const sum = Function.dual<
@@ -156,8 +156,8 @@ export const dual: {
    *   (self, that) => self + that
    * )
    *
-   * console.log(sum(2, 3)) // 5
-   * console.log(pipe(2, sum(3))) // 5
+   * sum(2, 3) // => 5
+   * pipe(2, sum(3)) // => 5
    * ```
    *
    * @category combinators
@@ -181,7 +181,7 @@ export const dual: {
    *
    * **Example** (Selecting data-first or data-last style by arity)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Function, pipe } from "effect"
    *
    * const sum = Function.dual<
@@ -189,13 +189,13 @@ export const dual: {
    *   (self: number, that: number) => number
    * >(2, (self, that) => self + that)
    *
-   * console.log(sum(2, 3)) // 5
-   * console.log(pipe(2, sum(3))) // 5
+   * sum(2, 3) // => 5
+   * pipe(2, sum(3)) // => 5
    * ```
    *
    * **Example** (Defining overloads with call signatures)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Function, pipe } from "effect"
    *
    * const sum: {
@@ -203,13 +203,13 @@ export const dual: {
    *   (self: number, that: number): number
    * } = Function.dual(2, (self: number, that: number): number => self + that)
    *
-   * console.log(sum(2, 3)) // 5
-   * console.log(pipe(2, sum(3))) // 5
+   * sum(2, 3) // => 5
+   * pipe(2, sum(3)) // => 5
    * ```
    *
    * **Example** (Selecting data-first or data-last style with a predicate)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Function, pipe } from "effect"
    *
    * const sum = Function.dual<
@@ -220,8 +220,8 @@ export const dual: {
    *   (self, that) => self + that
    * )
    *
-   * console.log(sum(2, 3)) // 5
-   * console.log(pipe(2, sum(3))) // 5
+   * sum(2, 3) // => 5
+   * pipe(2, sum(3)) // => 5
    * ```
    *
    * @category combinators
@@ -289,11 +289,10 @@ export const dual: {
  *
  * **Example** (Applying an argument to a function)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function, pipe, String } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(pipe(String.length, Function.apply("hello")), 5)
+ * pipe(String.length, Function.apply("hello")) // => 5
  * ```
  *
  * @see {@link pipe} for building left-to-right pipelines
@@ -312,10 +311,11 @@ export const apply = <A>(a: A) => <B>(self: (a: A) => B): B => self(a)
  *
  * **Example** (Creating a lazy argument)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
  *
  * const constNull: Function.LazyArg<null> = Function.constant(null)
+ * constNull() // => null
  * ```
  *
  * @category models
@@ -333,12 +333,11 @@ export type LazyArg<A> = () => A
  *
  * **Example** (Typing a variadic function)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Function } from "effect"
- * import * as assert from "node:assert"
  *
  * const sum: Function.FunctionN<[number, number], number> = (a, b) => a + b
- * assert.deepStrictEqual(sum(2, 3), 5)
+ * sum(2, 3) // => 5
  * ```
  *
  * @category models
@@ -355,11 +354,10 @@ export type FunctionN<A extends ReadonlyArray<unknown>, B> = (...args: A) => B
  *
  * **Example** (Returning the same value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { identity } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(identity(5), 5)
+ * identity(5) // => 5
  * ```
  *
  * @category combinators
@@ -378,17 +376,14 @@ export const identity = <A>(a: A): A => a
  *
  * **Example** (Checking an expression against a type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
- * const test1 = Function.satisfies<number>()(5 as const)
+ * const test1 = Function.satisfies<number>()(5 as const) // => 5
  * // ^? const test: 5
  * // @ts-expect-error
  * const test2 = Function.satisfies<string>()(5)
  * // ^? Argument of type 'number' is not assignable to parameter of type 'string'
- *
- * assert.deepStrictEqual(Function.satisfies<number>()(5), 5)
  * ```
  *
  * @see {@link cast} for changing only the static TypeScript type
@@ -428,14 +423,13 @@ export const cast: <A, B>(a: A) => B = identity as any
  *
  * **Example** (Creating a constant thunk)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
  * const constNull = Function.constant(null)
  *
- * assert.deepStrictEqual(constNull(), null)
- * assert.deepStrictEqual(constNull(), null)
+ * constNull() // => null
+ * constNull() // => null
  * ```
  *
  * @category constructors
@@ -452,11 +446,10 @@ export const constant = <A>(value: A): LazyArg<A> => () => value
  *
  * **Example** (Returning true from a thunk)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Function.constTrue(), true)
+ * Function.constTrue() // => true
  * ```
  *
  * @category constants
@@ -473,11 +466,10 @@ export const constTrue: LazyArg<boolean> = constant(true)
  *
  * **Example** (Returning false from a thunk)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Function.constFalse(), false)
+ * Function.constFalse() // => false
  * ```
  *
  * @category constants
@@ -494,11 +486,10 @@ export const constFalse: LazyArg<boolean> = constant(false)
  *
  * **Example** (Returning null from a thunk)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Function.constNull(), null)
+ * Function.constNull() // => null
  * ```
  *
  * @category constants
@@ -515,11 +506,10 @@ export const constNull: LazyArg<null> = constant(null)
  *
  * **Example** (Returning undefined from a thunk)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Function.constUndefined(), undefined)
+ * Function.constUndefined() // => undefined
  * ```
  *
  * @category constants
@@ -537,11 +527,10 @@ export const constUndefined: LazyArg<undefined> = constant(undefined)
  *
  * **Example** (Returning void from a thunk)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Function.constVoid(), undefined)
+ * Function.constVoid() // => undefined
  * ```
  *
  * @category constants
@@ -559,13 +548,12 @@ export const constVoid: LazyArg<void> = constUndefined
  *
  * **Example** (Flipping curried arguments)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
  * const f = (a: number) => (b: string) => a - b.length
  *
- * assert.deepStrictEqual(Function.flip(f)("aaa")(2), -1)
+ * Function.flip(f)("aaa")(2) // => -1
  * ```
  *
  * @category combinators
@@ -587,14 +575,13 @@ export const flip = <A extends Array<unknown>, B extends Array<unknown>, C>(
  *
  * **Example** (Composing two functions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
  * const increment = (n: number) => n + 1
  * const square = (n: number) => n * n
  *
- * assert.strictEqual(Function.compose(increment, square)(2), 9)
+ * Function.compose(increment, square)(2) // => 9
  * ```
  *
  * @see {@link flow} for composing a left-to-right sequence of functions
@@ -614,14 +601,13 @@ export const compose: {
    *
    * **Example** (Composing two functions)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Function } from "effect"
-   * import * as assert from "node:assert"
    *
    * const increment = (n: number) => n + 1
    * const square = (n: number) => n * n
    *
-   * assert.strictEqual(Function.compose(increment, square)(2), 9)
+   * Function.compose(increment, square)(2) // => 9
    * ```
    *
    * @see {@link flow} for composing a left-to-right sequence of functions
@@ -641,14 +627,13 @@ export const compose: {
    *
    * **Example** (Composing two functions)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Function } from "effect"
-   * import * as assert from "node:assert"
    *
    * const increment = (n: number) => n + 1
    * const square = (n: number) => n * n
    *
-   * assert.strictEqual(Function.compose(increment, square)(2), 9)
+   * Function.compose(increment, square)(2) // => 9
    * ```
    *
    * @see {@link flow} for composing a left-to-right sequence of functions
@@ -676,7 +661,7 @@ export const compose: {
  *
  * **Example** (Handling impossible values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { absurd } from "effect"
  *
  * const handleNever = (value: never) => {
@@ -700,13 +685,12 @@ export const absurd = <A>(_: never): A => {
  *
  * **Example** (Converting arguments to a tuple)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
  * const sumTupled = Function.tupled((x: number, y: number): number => x + y)
  *
- * assert.deepStrictEqual(sumTupled([1, 2]), 3)
+ * sumTupled([1, 2]) // => 3
  * ```
  *
  * @see {@link untupled} for adapting a tuple-argument function back to multiple arguments
@@ -725,13 +709,12 @@ export const tupled = <A extends ReadonlyArray<unknown>, B>(f: (...a: A) => B):
  *
  * **Example** (Converting a tuple to arguments)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
  * const getFirst = Function.untupled(<A, B>(tuple: [A, B]): A => tuple[0])
  *
- * assert.deepStrictEqual(getFirst(1, 2), 1)
+ * getFirst(1, 2) // => 1
  * ```
  *
  * @see {@link tupled} for adapting a multi-argument function to one tuple argument
@@ -765,82 +748,33 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  * In this example, `1` is passed to the first function, and each result becomes
  * the input for the next function.
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { pipe } from "effect"
  *
- * const result = pipe(
+ * pipe(
  *   1,
  *   (n) => n + 1,
  *   (n) => n * 2,
  *   (n) => `result: ${n}`
- * )
- *
- * console.log(result) // "result: 4"
- * ```
- *
- * **Example** (Chaining methods before conversion)
- *
- * ```ts
- * const numbers = [1, 2, 3, 4]
- * const double = (n: number) => n * 2
- * const greaterThanFour = (n: number) => n > 4
- *
- * const result = numbers.map(double).filter(greaterThanFour)
- *
- * console.log(result) // [6, 8]
+ * ) // => "result: 4"
  * ```
  *
  * **Example** (Rewriting method chains with pipe)
  *
  * The same transformation can be written with data-last functions.
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Array, pipe } from "effect"
  *
  * const numbers = [1, 2, 3, 4]
  * const double = (n: number) => n * 2
  * const greaterThanFour = (n: number) => n > 4
  *
- * const result = pipe(
+ * pipe(
  *   numbers,
  *   Array.map(double),
  *   Array.filter(greaterThanFour)
- * )
- *
- * console.log(result) // [6, 8]
- * ```
- *
- * **Example** (Chaining arithmetic operations)
- *
- * ```ts
- * import { pipe } from "effect"
- *
- * // Define simple arithmetic operations
- * const increment = (x: number) => x + 1
- * const double = (x: number) => x * 2
- * const subtractTen = (x: number) => x - 10
- *
- * // Sequentially apply these operations using `pipe`
- * const result = pipe(5, increment, double, subtractTen)
- *
- * console.log(result)
- * // Output: 2
- * ```
- *
- * **Example** (Building a simple transformation pipeline)
- *
- * ```ts
- * import { pipe } from "effect"
- *
- * // Simple transformation pipeline
- * const result = pipe(
- *   5,
- *   (x) => x * 2, // 10
- *   (x) => x + 1, // 11
- *   (x) => x.toString() // "11"
- * )
- *
- * console.log(result) // "11"
+ * ) // => [6, 8]
  * ```
  *
  * @category combinators
@@ -1313,16 +1247,15 @@ export function pipe(a: unknown, ...args: Array<any>): unknown {
  *
  * **Example** (Composing functions left to right)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { flow } from "effect"
- * import * as assert from "node:assert"
  *
  * const len = (s: string): number => s.length
  * const double = (n: number): number => n * 2
  *
  * const f = flow(len, double)
  *
- * assert.strictEqual(f("aaa"), 6)
+ * f("aaa") // => 6
  * ```
  *
  * @see {@link pipe} for applying a value through a left-to-right sequence immediately
@@ -1510,7 +1443,7 @@ export function flow(
  *
  * **Example** (Creating a development placeholder)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { hole } from "effect"
  *
  * // Intentionally not called: `hole` throws if the placeholder is evaluated.
@@ -1519,7 +1452,6 @@ export function flow(
  *   name: hole<string>()
  * })
  *
- * console.log(typeof buildUser) // "function"
  * ```
  *
  * @category utility types
@@ -1538,11 +1470,10 @@ export const hole: <T>() => T = cast(absurd)
  *
  * **Example** (Discarding the first argument)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Function } from "effect"
- * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Function.SK(0, "hello"), "hello")
+ * Function.SK(0, "hello") // => "hello"
  * ```
  *
  * @category combinators