effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Function.d.ts

@@ -1,17 +1,62 @@
 /**
+ * The `Function` module provides small, pure helpers for defining, composing,
+ * adapting, and reusing TypeScript functions. It is the foundation for the
+ * data-first and data-last APIs used throughout Effect, and it includes the
+ * core pipeline utilities that make those APIs ergonomic.
+ *
+ * **Mental model**
+ *
+ * - {@link pipe} starts with a value and passes it through one unary function at
+ *   a time
+ * - {@link flow} composes unary functions into a reusable function
+ * - {@link dual} builds APIs that support both direct calls and `pipe`-friendly
+ *   data-last calls
+ * - {@link identity}, {@link constant}, and the `const*` helpers model common
+ *   identity and thunk patterns without allocating ad hoc callbacks
+ * - {@link tupled}, {@link untupled}, {@link flip}, and {@link apply} adapt
+ *   call shapes without changing the underlying behavior
+ * - Type helpers such as {@link LazyArg}, {@link FunctionN}, {@link satisfies},
+ *   and {@link cast} describe or constrain functions at the type level
+ *
+ * **Common tasks**
+ *
+ * - Build readable transformation pipelines: {@link pipe}
+ * - Create reusable composed functions: {@link flow}, {@link compose}
+ * - Define functions callable in both data-first and data-last style: {@link dual}
+ * - Return a value unchanged: {@link identity}
+ * - Create thunks and common constant functions: {@link constant},
+ *   {@link constTrue}, {@link constFalse}, {@link constNull},
+ *   {@link constUndefined}, {@link constVoid}
+ * - Convert between rest-argument and tuple-argument functions: {@link tupled},
+ *   {@link untupled}
+ * - Express impossible branches: {@link absurd}
+ * - Cache results for object keys: {@link memoize}
+ *
+ * **Gotchas**
+ *
+ * - Functions passed to {@link pipe} and {@link flow} are applied left-to-right
+ *   and should be unary at each step
+ * - {@link dual} uses either an arity or a predicate to decide whether a call is
+ *   data-first or data-last; use a predicate when optional arguments make arity
+ *   ambiguous
+ * - {@link cast} changes only the static TypeScript type and performs no runtime
+ *   validation
+ * - {@link memoize} is intended for object keys and stores cached values in a
+ *   `WeakMap`
+ *
  * @since 2.0.0
  */
 import type { TypeLambda } from "./HKT.ts";
 /**
  * Type lambda for function types, used for higher-kinded type operations.
  *
- * @example
+ * **Example** (Creating a function type with a type lambda)
+ *
  * ```ts
- * import type { FunctionTypeLambda } from "effect/Function"
- * import type { Kind } from "effect/HKT"
+ * import type { Function, HKT } from "effect"
  *
  * // Create a function type using the type lambda
- * type StringToNumber = Kind<FunctionTypeLambda, string, never, never, number>
+ * type StringToNumber = HKT.Kind<Function.FunctionTypeLambda, string, never, never, number>
  * // Equivalent to: (a: string) => number
  * ```
  *
@@ -38,26 +83,12 @@ export interface FunctionTypeLambda extends TypeLambda {
  * which determines if the function is being used in a data-first or
  * data-last style.
  *
- * @example
- * ```ts
- * import { dual, pipe } from "effect/Function"
- *
- * // Using arity to determine data-first or data-last style
- * const sum = dual<
- *   (that: number) => (self: number) => number,
- *   (self: number, that: number) => number
- * >(2, (self, that) => self + that)
- *
- * console.log(sum(2, 3)) // 5 (data-first)
- * console.log(pipe(2, sum(3))) // 5 (data-last)
- * ```
- *
  * **Example** (Using arity to determine data-first or data-last style)
  *
  * ```ts
- * import { dual, pipe } from "effect/Function"
+ * import { Function, pipe } from "effect"
  *
- * const sum = dual<
+ * const sum = Function.dual<
  *   (that: number) => (self: number) => number,
  *   (self: number, that: number) => number
  * >(2, (self, that) => self + that)
@@ -69,12 +100,12 @@ export interface FunctionTypeLambda extends TypeLambda {
  * **Example** (Using call signatures to define the overloads)
  *
  * ```ts
- * import { dual, pipe } from "effect/Function"
+ * import { Function, pipe } from "effect"
  *
  * const sum: {
  *   (that: number): (self: number) => number
  *   (self: number, that: number): number
- * } = dual(2, (self: number, that: number): number => self + that)
+ * } = Function.dual(2, (self: number, that: number): number => self + that)
  *
  * console.log(sum(2, 3)) // 5
  * console.log(pipe(2, sum(3))) // 5
@@ -83,9 +114,9 @@ export interface FunctionTypeLambda extends TypeLambda {
  * **Example** (Using a predicate to determine data-first or data-last style)
  *
  * ```ts
- * import { dual, pipe } from "effect/Function"
+ * import { Function, pipe } from "effect"
  *
- * const sum = dual<
+ * const sum = Function.dual<
  *   (that: number) => (self: number) => number,
  *   (self: number, that: number) => number
  * >(
@@ -118,26 +149,12 @@ export declare const dual: {
      * which determines if the function is being used in a data-first or
      * data-last style.
      *
-     * @example
-     * ```ts
-     * import { dual, pipe } from "effect/Function"
-     *
-     * // Using arity to determine data-first or data-last style
-     * const sum = dual<
-     *   (that: number) => (self: number) => number,
-     *   (self: number, that: number) => number
-     * >(2, (self, that) => self + that)
-     *
-     * console.log(sum(2, 3)) // 5 (data-first)
-     * console.log(pipe(2, sum(3))) // 5 (data-last)
-     * ```
-     *
      * **Example** (Using arity to determine data-first or data-last style)
      *
      * ```ts
-     * import { dual, pipe } from "effect/Function"
+     * import { Function, pipe } from "effect"
      *
-     * const sum = dual<
+     * const sum = Function.dual<
      *   (that: number) => (self: number) => number,
      *   (self: number, that: number) => number
      * >(2, (self, that) => self + that)
@@ -149,12 +166,12 @@ export declare const dual: {
      * **Example** (Using call signatures to define the overloads)
      *
      * ```ts
-     * import { dual, pipe } from "effect/Function"
+     * import { Function, pipe } from "effect"
      *
      * const sum: {
      *   (that: number): (self: number) => number
      *   (self: number, that: number): number
-     * } = dual(2, (self: number, that: number): number => self + that)
+     * } = Function.dual(2, (self: number, that: number): number => self + that)
      *
      * console.log(sum(2, 3)) // 5
      * console.log(pipe(2, sum(3))) // 5
@@ -163,9 +180,9 @@ export declare const dual: {
      * **Example** (Using a predicate to determine data-first or data-last style)
      *
      * ```ts
-     * import { dual, pipe } from "effect/Function"
+     * import { Function, pipe } from "effect"
      *
-     * const sum = dual<
+     * const sum = Function.dual<
      *   (that: number) => (self: number) => number,
      *   (self: number, that: number) => number
      * >(
@@ -198,26 +215,12 @@ export declare const dual: {
      * which determines if the function is being used in a data-first or
      * data-last style.
      *
-     * @example
-     * ```ts
-     * import { dual, pipe } from "effect/Function"
-     *
-     * // Using arity to determine data-first or data-last style
-     * const sum = dual<
-     *   (that: number) => (self: number) => number,
-     *   (self: number, that: number) => number
-     * >(2, (self, that) => self + that)
-     *
-     * console.log(sum(2, 3)) // 5 (data-first)
-     * console.log(pipe(2, sum(3))) // 5 (data-last)
-     * ```
-     *
      * **Example** (Using arity to determine data-first or data-last style)
      *
      * ```ts
-     * import { dual, pipe } from "effect/Function"
+     * import { Function, pipe } from "effect"
      *
-     * const sum = dual<
+     * const sum = Function.dual<
      *   (that: number) => (self: number) => number,
      *   (self: number, that: number) => number
      * >(2, (self, that) => self + that)
@@ -229,12 +232,12 @@ export declare const dual: {
      * **Example** (Using call signatures to define the overloads)
      *
      * ```ts
-     * import { dual, pipe } from "effect/Function"
+     * import { Function, pipe } from "effect"
      *
      * const sum: {
      *   (that: number): (self: number) => number
      *   (self: number, that: number): number
-     * } = dual(2, (self: number, that: number): number => self + that)
+     * } = Function.dual(2, (self: number, that: number): number => self + that)
      *
      * console.log(sum(2, 3)) // 5
      * console.log(pipe(2, sum(3))) // 5
@@ -243,9 +246,9 @@ export declare const dual: {
      * **Example** (Using a predicate to determine data-first or data-last style)
      *
      * ```ts
-     * import { dual, pipe } from "effect/Function"
+     * import { Function, pipe } from "effect"
      *
-     * const sum = dual<
+     * const sum = Function.dual<
      *   (that: number) => (self: number) => number,
      *   (self: number, that: number) => number
      * >(
@@ -265,13 +268,13 @@ export declare const dual: {
 /**
  * Apply a function to a given value.
  *
- * @example
+ * **Example** (Applying an argument to a function)
+ *
  * ```ts
- * import { apply, pipe } from "effect/Function"
- * import { length } from "effect/String"
+ * import { Function, pipe, String } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(pipe(length, apply("hello")), 5)
+ * assert.deepStrictEqual(pipe(String.length, Function.apply("hello")), 5)
  * ```
  *
  * @category combinators
@@ -279,13 +282,14 @@ export declare const dual: {
  */
 export declare const apply: <A>(a: A) => <B>(self: (a: A) => B) => B;
 /**
- * A lazy argument.
+ * A zero-argument function that produces a value when invoked.
+ *
+ * **Example** (Creating a lazy argument)
  *
- * @example
  * ```ts
- * import { constant, type LazyArg } from "effect/Function"
+ * import { Function } from "effect"
  *
- * const constNull: LazyArg<null> = constant(null)
+ * const constNull: Function.LazyArg<null> = Function.constant(null)
  * ```
  *
  * @category models
@@ -295,12 +299,13 @@ export type LazyArg<A> = () => A;
 /**
  * Represents a function with multiple arguments.
  *
- * @example
+ * **Example** (Typing a variadic function)
+ *
  * ```ts
- * import type { FunctionN } from "effect/Function"
+ * import type { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * const sum: FunctionN<[number, number], number> = (a, b) => a + b
+ * const sum: Function.FunctionN<[number, number], number> = (a, b) => a + b
  * assert.deepStrictEqual(sum(2, 3), 5)
  * ```
  *
@@ -311,9 +316,10 @@ export type FunctionN<A extends ReadonlyArray<unknown>, B> = (...args: A) => B;
 /**
  * The identity function, i.e. A function that returns its input argument.
  *
- * @example
+ * **Example** (Returning the same value)
+ *
  * ```ts
- * import { identity } from "effect/Function"
+ * import { identity } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(identity(5), 5)
@@ -327,18 +333,19 @@ export declare const identity: <A>(a: A) => A;
  * A function that ensures that the type of an expression matches some type,
  * without changing the resulting type of that expression.
  *
- * @example
+ * **Example** (Checking an expression against a type)
+ *
  * ```ts
- * import { satisfies } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * const test1 = satisfies<number>()(5 as const)
+ * const test1 = Function.satisfies<number>()(5 as const)
  * // ^? const test: 5
  * // @ts-expect-error
- * const test2 = satisfies<string>()(5)
+ * const test2 = Function.satisfies<string>()(5)
  * // ^? Argument of type 'number' is not assignable to parameter of type 'string'
  *
- * assert.deepStrictEqual(satisfies<number>()(5), 5)
+ * assert.deepStrictEqual(Function.satisfies<number>()(5), 5)
  * ```
  *
  * @category type utils
@@ -346,24 +353,28 @@ export declare const identity: <A>(a: A) => A;
  */
 export declare const satisfies: <A>() => <B extends A>(b: B) => B;
 /**
- * Casts the result to the specified type.
+ * Returns the input value with a different static type.
+ *
+ * This is a type-level cast only; it performs no runtime validation or
+ * conversion.
  *
  * @category type utils
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const cast: <A, B>(a: A) => B;
 /**
- * Creates a constant value that never changes.
+ * Creates a zero-argument function that always returns the provided value.
+ *
+ * Use `constant` when an API expects a thunk or callback and every invocation
+ * should return the same value.
  *
- * This is useful when you want to pass a value to a higher-order function (a function that takes another function as its argument)
- * and want that inner function to always use the same value, no matter how many times it is called.
+ * **Example** (Creating a constant thunk)
  *
- * @example
  * ```ts
- * import { constant } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * const constNull = constant(null)
+ * const constNull = Function.constant(null)
  *
  * assert.deepStrictEqual(constNull(), null)
  * assert.deepStrictEqual(constNull(), null)
@@ -376,12 +387,13 @@ export declare const constant: <A>(value: A) => LazyArg<A>;
 /**
  * A thunk that returns always `true`.
  *
- * @example
+ * **Example** (Returning true from a thunk)
+ *
  * ```ts
- * import { constTrue } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(constTrue(), true)
+ * assert.deepStrictEqual(Function.constTrue(), true)
  * ```
  *
  * @category constants
@@ -391,12 +403,13 @@ export declare const constTrue: LazyArg<boolean>;
 /**
  * A thunk that returns always `false`.
  *
- * @example
+ * **Example** (Returning false from a thunk)
+ *
  * ```ts
- * import { constFalse } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(constFalse(), false)
+ * assert.deepStrictEqual(Function.constFalse(), false)
  * ```
  *
  * @category constants
@@ -406,12 +419,13 @@ export declare const constFalse: LazyArg<boolean>;
 /**
  * A thunk that returns always `null`.
  *
- * @example
+ * **Example** (Returning null from a thunk)
+ *
  * ```ts
- * import { constNull } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(constNull(), null)
+ * assert.deepStrictEqual(Function.constNull(), null)
  * ```
  *
  * @category constants
@@ -421,12 +435,13 @@ export declare const constNull: LazyArg<null>;
 /**
  * A thunk that returns always `undefined`.
  *
- * @example
+ * **Example** (Returning undefined from a thunk)
+ *
  * ```ts
- * import { constUndefined } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(constUndefined(), undefined)
+ * assert.deepStrictEqual(Function.constUndefined(), undefined)
  * ```
  *
  * @category constants
@@ -436,12 +451,13 @@ export declare const constUndefined: LazyArg<undefined>;
 /**
  * A thunk that returns always `void`.
  *
- * @example
+ * **Example** (Returning void from a thunk)
+ *
  * ```ts
- * import { constVoid } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(constVoid(), undefined)
+ * assert.deepStrictEqual(Function.constVoid(), undefined)
  * ```
  *
  * @category constants
@@ -451,14 +467,15 @@ export declare const constVoid: LazyArg<void>;
 /**
  * Reverses the order of arguments for a curried function.
  *
- * @example
+ * **Example** (Flipping curried arguments)
+ *
  * ```ts
- * import { flip } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
  * const f = (a: number) => (b: string) => a - b.length
  *
- * assert.deepStrictEqual(flip(f)("aaa")(2), -1)
+ * assert.deepStrictEqual(Function.flip(f)("aaa")(2), -1)
  * ```
  *
  * @category combinators
@@ -469,15 +486,16 @@ export declare const flip: <A extends Array<unknown>, B extends Array<unknown>,
  * Composes two functions, `ab` and `bc` into a single function that takes in an argument `a` of type `A` and returns a result of type `C`.
  * The result is obtained by first applying the `ab` function to `a` and then applying the `bc` function to the result of `ab`.
  *
- * @example
+ * **Example** (Composing two functions)
+ *
  * ```ts
- * import { compose } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
  * const increment = (n: number) => n + 1
  * const square = (n: number) => n * n
  *
- * assert.strictEqual(compose(increment, square)(2), 9)
+ * assert.strictEqual(Function.compose(increment, square)(2), 9)
  * ```
  *
  * @category combinators
@@ -488,15 +506,16 @@ export declare const compose: {
      * Composes two functions, `ab` and `bc` into a single function that takes in an argument `a` of type `A` and returns a result of type `C`.
      * The result is obtained by first applying the `ab` function to `a` and then applying the `bc` function to the result of `ab`.
      *
-     * @example
+     * **Example** (Composing two functions)
+     *
      * ```ts
-     * import { compose } from "effect/Function"
+     * import { Function } from "effect"
      * import * as assert from "node:assert"
      *
      * const increment = (n: number) => n + 1
      * const square = (n: number) => n * n
      *
-     * assert.strictEqual(compose(increment, square)(2), 9)
+     * assert.strictEqual(Function.compose(increment, square)(2), 9)
      * ```
      *
      * @category combinators
@@ -507,15 +526,16 @@ export declare const compose: {
      * Composes two functions, `ab` and `bc` into a single function that takes in an argument `a` of type `A` and returns a result of type `C`.
      * The result is obtained by first applying the `ab` function to `a` and then applying the `bc` function to the result of `ab`.
      *
-     * @example
+     * **Example** (Composing two functions)
+     *
      * ```ts
-     * import { compose } from "effect/Function"
+     * import { Function } from "effect"
      * import * as assert from "node:assert"
      *
      * const increment = (n: number) => n + 1
      * const square = (n: number) => n * n
      *
-     * assert.strictEqual(compose(increment, square)(2), 9)
+     * assert.strictEqual(Function.compose(increment, square)(2), 9)
      * ```
      *
      * @category combinators
@@ -529,28 +549,30 @@ export declare const compose: {
  *
  * This function is particularly useful when it's necessary to specify that certain cases are impossible.
  *
- * @example
+ * **Example** (Handling impossible values)
+ *
  * ```ts
- * import { absurd } from "effect/Function"
+ * import { absurd } from "effect"
  *
  * const handleNever = (value: never) => {
  *   return absurd(value) // This will throw an error if called
  * }
  * ```
  *
- * @category utilities
+ * @category utils
  * @since 2.0.0
  */
 export declare const absurd: <A>(_: never) => A;
 /**
  * Creates a tupled version of this function: instead of `n` arguments, it accepts a single tuple argument.
  *
- * @example
+ * **Example** (Converting arguments to a tuple)
+ *
  * ```ts
- * import { tupled } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * const sumTupled = tupled((x: number, y: number): number => x + y)
+ * const sumTupled = Function.tupled((x: number, y: number): number => x + y)
  *
  * assert.deepStrictEqual(sumTupled([1, 2]), 3)
  * ```
@@ -562,12 +584,13 @@ export declare const tupled: <A extends ReadonlyArray<unknown>, B>(f: (...a: A)
 /**
  * Inverse function of `tupled`
  *
- * @example
+ * **Example** (Converting a tuple to arguments)
+ *
  * ```ts
- * import { untupled } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * const getFirst = untupled(<A, B>(tuple: [A, B]): A => tuple[0])
+ * const getFirst = Function.untupled(<A, B>(tuple: [A, B]): A => tuple[0])
  *
  * assert.deepStrictEqual(getFirst(1, 2), 1)
  * ```
@@ -586,23 +609,31 @@ export declare const untupled: <A extends ReadonlyArray<unknown>, B>(f: (a: A) =
  * passes it as the input to the next function in the pipeline. This enables us
  * to build complex transformations by chaining multiple functions together.
  *
- * ```ts skip-type-checking
+ * **Example** (Showing pipeline syntax)
+ *
+ * ```ts
  * import { pipe } from "effect"
  *
- * const result = pipe(input, func1, func2, ..., funcN)
+ * const result = pipe(
+ *   1,
+ *   (n) => n + 1,
+ *   (n) => n * 2,
+ *   (n) => `result: ${n}`
+ * )
+ *
+ * console.log(result) // "result: 4"
  * ```
  *
- * In this syntax, `input` is the initial value, and `func1`, `func2`, ...,
- * `funcN` are the functions to be applied in sequence. The result of each
- * function becomes the input for the next function, and the final result is
- * returned.
+ * In this syntax, `1` is the initial value, and each function is applied in
+ * sequence. The result of each function becomes the input for the next
+ * function, and the final result is returned.
  *
  * Here's an illustration of how `pipe` works:
  *
  * ```
- * ┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐    ┌───────┐    ┌────────┐
- * │ input │───►│ func1 │───►│ func2 │───►│  ...  │───►│ funcN │───►│ result │
- * └───────┘    └───────┘    └───────┘    └───────┘    └───────┘    └────────┘
+ * ┌───┐    ┌───────┐    ┌─────────────┐    ┌────────┐
+ * │ 1 │───►│ add 1 │───►│ multiply 2  │───►│ format │───► "result: 4"
+ * └───┘    └───────┘    └─────────────┘    └────────┘
  * ```
  *
  * It's important to note that functions passed to `pipe` must have a **single
@@ -613,16 +644,36 @@ export declare const untupled: <A extends ReadonlyArray<unknown>, B>(f: (a: A) =
  * This is useful in combination with data-last functions as a simulation of
  * methods:
  *
- * ```ts skip-type-checking
- * as.map(f).filter(g)
+ * **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]
  * ```
  *
  * becomes:
  *
- * ```ts skip-type-checking
+ * **Example** (Rewriting method chains with pipe)
+ *
+ * ```ts
  * import { Array, pipe } from "effect"
  *
- * pipe(as, Array.map(f), Array.filter(g))
+ * const numbers = [1, 2, 3, 4]
+ * const double = (n: number) => n * 2
+ * const greaterThanFour = (n: number) => n > 4
+ *
+ * const result = pipe(
+ *   numbers,
+ *   Array.map(double),
+ *   Array.filter(greaterThanFour)
+ * )
+ *
+ * console.log(result) // [6, 8]
  * ```
  *
  * **Example** (Chaining Arithmetic Operations)
@@ -642,7 +693,8 @@ export declare const untupled: <A extends ReadonlyArray<unknown>, B>(f: (a: A) =
  * // Output: 2
  * ```
  *
- * @example
+ * **Example** (Building a simple transformation pipeline)
+ *
  * ```ts
  * import { pipe } from "effect"
  *
@@ -685,9 +737,10 @@ export declare function pipe<A, B = never, C = never, D = never, E = never, F =
  *
  * See also [`pipe`](#pipe).
  *
- * @example
+ * **Example** (Composing functions left to right)
+ *
  * ```ts
- * import { flow } from "effect/Function"
+ * import { flow } from "effect"
  * import * as assert from "node:assert"
  *
  * const len = (s: string): number => s.length
@@ -711,17 +764,26 @@ export declare function flow<A extends ReadonlyArray<unknown>, B = never, C = ne
 export declare function flow<A extends ReadonlyArray<unknown>, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I): (...a: A) => I;
 export declare function flow<A extends ReadonlyArray<unknown>, B = never, C = never, D = never, E = never, F = never, G = never, H = never, I = never, J = never>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J): (...a: A) => J;
 /**
- * Type hole simulation. Creates a placeholder for any type, primarily used during development.
+ * Creates a compile-time placeholder for a value of any type.
+ *
+ * `hole` is intended for temporary development use. If the placeholder is
+ * evaluated at runtime, it throws.
+ *
+ * **Example** (Creating a development placeholder)
  *
- * @example
  * ```ts
- * import { hole } from "effect/Function"
+ * import { hole } from "effect"
+ *
+ * // Intentionally not called: `hole` throws if the placeholder is evaluated.
+ * const buildUser = (id: number): { readonly id: number; readonly name: string } => ({
+ *   id,
+ *   name: hole<string>()
+ * })
  *
- * // Use during development as a placeholder
- * const placeholder: string = hole<string>()
+ * console.log(typeof buildUser) // "function"
  * ```
  *
- * @category utilities
+ * @category utils
  * @since 2.0.0
  */
 export declare const hole: <T>() => T;
@@ -731,12 +793,13 @@ export declare const hole: <T>() => T;
  *
  * This function is useful for discarding the first argument passed to it and returning the second argument.
  *
- * @example
+ * **Example** (Discarding the first argument)
+ *
  * ```ts
- * import { SK } from "effect/Function"
+ * import { Function } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(SK(0, "hello"), "hello")
+ * assert.deepStrictEqual(Function.SK(0, "hello"), "hello")
  * ```
  *
  * @category combinators
@@ -744,6 +807,10 @@ export declare const hole: <T>() => T;
  */
 export declare const SK: <A, B>(_: A, b: B) => B;
 /**
+ * Memoizes a function whose input is an object, caching results by object
+ * identity.
+ *
+ * @category utils
  * @since 4.0.0
  */
 export declare function memoize<A extends object, O>(f: (a: A) => O): (ast: A) => O;