effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Function.ts

@@ -52,6 +52,10 @@ import { pipeArguments } from "./Pipeable.ts"
 /**
  * Type lambda for function types, used for higher-kinded type operations.
  *
+ * **When to use**
+ *
+ * Use to represent unary function types in higher-kinded type operations.
+ *
  * **Example** (Creating a function type with a type lambda)
  *
  * ```ts
@@ -73,6 +77,11 @@ export interface FunctionTypeLambda extends TypeLambda {
  * Creates a function that can be called in data-first style or data-last
  * (`pipe`-friendly) style.
  *
+ * **When to use**
+ *
+ * Use to expose one implementation through both direct and `pipe`-friendly
+ * call styles.
+ *
  * **Details**
  *
  * Pass either the arity of the uncurried function or a predicate that decides
@@ -132,6 +141,11 @@ export const dual: {
    * Creates a function that can be called in data-first style or data-last
    * (`pipe`-friendly) style.
    *
+   * **When to use**
+   *
+   * Use to expose one implementation through both direct and `pipe`-friendly
+   * call styles.
+   *
    * **Details**
    *
    * Pass either the arity of the uncurried function or a predicate that decides
@@ -191,6 +205,11 @@ export const dual: {
    * Creates a function that can be called in data-first style or data-last
    * (`pipe`-friendly) style.
    *
+   * **When to use**
+   *
+   * Use to expose one implementation through both direct and `pipe`-friendly
+   * call styles.
+   *
    * **Details**
    *
    * Pass either the arity of the uncurried function or a predicate that decides
@@ -294,7 +313,16 @@ export const dual: {
   }
 }
 /**
- * Apply a function to a given value.
+ * Applies a function to a given value.
+ *
+ * **When to use**
+ *
+ * Use to pass a fixed value into a unary function, especially when the function
+ * is the value flowing through `pipe`.
+ *
+ * **Details**
+ *
+ * `apply(a)(f)` is equivalent to `f(a)`.
  *
  * **Example** (Applying an argument to a function)
  *
@@ -305,6 +333,8 @@ export const dual: {
  * assert.deepStrictEqual(pipe(String.length, Function.apply("hello")), 5)
  * ```
  *
+ * @see {@link pipe} for building left-to-right pipelines
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -313,6 +343,10 @@ export const apply = <A>(a: A) => <B>(self: (a: A) => B): B => self(a)
 /**
  * A zero-argument function that produces a value when invoked.
  *
+ * **When to use**
+ *
+ * Use to type a lazy value provider that should not run until called.
+ *
  * **Example** (Creating a lazy argument)
  *
  * ```ts
@@ -329,6 +363,11 @@ export type LazyArg<A> = () => A
 /**
  * Represents a function with multiple arguments.
  *
+ * **When to use**
+ *
+ * Use to describe a function whose argument list is represented as a tuple
+ * type.
+ *
  * **Example** (Typing a variadic function)
  *
  * ```ts
@@ -345,7 +384,11 @@ export type LazyArg<A> = () => A
 export type FunctionN<A extends ReadonlyArray<unknown>, B> = (...args: A) => B
 
 /**
- * The identity function, i.e. A function that returns its input argument.
+ * Returns its input argument unchanged.
+ *
+ * **When to use**
+ *
+ * Use to return a value unchanged where a function is required.
  *
  * **Example** (Returning the same value)
  *
@@ -362,9 +405,14 @@ export type FunctionN<A extends ReadonlyArray<unknown>, B> = (...args: A) => B
 export const identity = <A>(a: A): A => a
 
 /**
- * A function that ensures that the type of an expression matches some type,
+ * Ensures that the type of an expression matches some type,
  * without changing the resulting type of that expression.
  *
+ * **When to use**
+ *
+ * Use to check assignability while preserving the expression's precise inferred
+ * type.
+ *
  * **Example** (Checking an expression against a type)
  *
  * ```ts
@@ -380,6 +428,8 @@ export const identity = <A>(a: A): A => a
  * assert.deepStrictEqual(Function.satisfies<number>()(5), 5)
  * ```
  *
+ * @see {@link cast} for changing only the static TypeScript type
+ *
  * @category type utils
  * @since 2.0.0
  */
@@ -388,11 +438,18 @@ export const satisfies = <A>() => <B extends A>(b: B) => b
 /**
  * Returns the input value with a different static type.
  *
+ * **When to use**
+ *
+ * Use when you need an explicit type-level cast and accept that the value is
+ * returned unchanged at runtime.
+ *
  * **Gotchas**
  *
  * This is a type-level cast only; it performs no runtime validation or
  * conversion.
  *
+ * @see {@link satisfies} for checking assignability without changing the resulting type
+ *
  * @category type utils
  * @since 4.0.0
  */
@@ -403,7 +460,7 @@ export const cast: <A, B>(a: A) => B = identity as any
  *
  * **When to use**
  *
- * Use `constant` when an API expects a thunk or callback and every invocation
+ * Use when an API expects a thunk or callback and every invocation
  * should return the same value.
  *
  * **Example** (Creating a constant thunk)
@@ -424,7 +481,11 @@ export const cast: <A, B>(a: A) => B = identity as any
 export const constant = <A>(value: A): LazyArg<A> => () => value
 
 /**
- * A thunk that returns always `true`.
+ * Returns `true` when called.
+ *
+ * **When to use**
+ *
+ * Use when an API expects a thunk and every invocation should return `true`.
  *
  * **Example** (Returning true from a thunk)
  *
@@ -441,7 +502,11 @@ export const constant = <A>(value: A): LazyArg<A> => () => value
 export const constTrue: LazyArg<boolean> = constant(true)
 
 /**
- * A thunk that returns always `false`.
+ * Returns `false` when called.
+ *
+ * **When to use**
+ *
+ * Use when an API expects a thunk and every invocation should return `false`.
  *
  * **Example** (Returning false from a thunk)
  *
@@ -458,7 +523,11 @@ export const constTrue: LazyArg<boolean> = constant(true)
 export const constFalse: LazyArg<boolean> = constant(false)
 
 /**
- * A thunk that returns always `null`.
+ * Returns `null` when called.
+ *
+ * **When to use**
+ *
+ * Use when an API expects a thunk and every invocation should return `null`.
  *
  * **Example** (Returning null from a thunk)
  *
@@ -475,7 +544,12 @@ export const constFalse: LazyArg<boolean> = constant(false)
 export const constNull: LazyArg<null> = constant(null)
 
 /**
- * A thunk that returns always `undefined`.
+ * Returns `undefined` when called.
+ *
+ * **When to use**
+ *
+ * Use when an API expects a thunk and every invocation should return
+ * `undefined`.
  *
  * **Example** (Returning undefined from a thunk)
  *
@@ -492,7 +566,12 @@ export const constNull: LazyArg<null> = constant(null)
 export const constUndefined: LazyArg<undefined> = constant(undefined)
 
 /**
- * A thunk that returns always `void`.
+ * Returns no meaningful value when called.
+ *
+ * **When to use**
+ *
+ * Use when an API expects a thunk used only for its call effect and not for a
+ * meaningful return value.
  *
  * **Example** (Returning void from a thunk)
  *
@@ -511,6 +590,11 @@ export const constVoid: LazyArg<void> = constUndefined
 /**
  * Reverses the order of arguments for a curried function.
  *
+ * **When to use**
+ *
+ * Use to adapt a curried function when its argument groups need to be supplied
+ * in the opposite order.
+ *
  * **Example** (Flipping curried arguments)
  *
  * ```ts
@@ -535,6 +619,10 @@ export const flip = <A extends Array<unknown>, B extends Array<unknown>, C>(
  * 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`.
  *
+ * **When to use**
+ *
+ * Use to compose exactly two unary functions into a reusable unary function.
+ *
  * **Example** (Composing two functions)
  *
  * ```ts
@@ -547,6 +635,9 @@ export const flip = <A extends Array<unknown>, B extends Array<unknown>, C>(
  * assert.strictEqual(Function.compose(increment, square)(2), 9)
  * ```
  *
+ * @see {@link flow} for composing a left-to-right sequence of functions
+ * @see {@link pipe} for applying a value through a left-to-right sequence immediately
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -555,6 +646,10 @@ export 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`.
    *
+   * **When to use**
+   *
+   * Use to compose exactly two unary functions into a reusable unary function.
+   *
    * **Example** (Composing two functions)
    *
    * ```ts
@@ -567,6 +662,9 @@ export const compose: {
    * assert.strictEqual(Function.compose(increment, square)(2), 9)
    * ```
    *
+   * @see {@link flow} for composing a left-to-right sequence of functions
+   * @see {@link pipe} for applying a value through a left-to-right sequence immediately
+   *
    * @category combinators
    * @since 2.0.0
    */
@@ -575,6 +673,10 @@ export 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`.
    *
+   * **When to use**
+   *
+   * Use to compose exactly two unary functions into a reusable unary function.
+   *
    * **Example** (Composing two functions)
    *
    * ```ts
@@ -587,6 +689,9 @@ export const compose: {
    * assert.strictEqual(Function.compose(increment, square)(2), 9)
    * ```
    *
+   * @see {@link flow} for composing a left-to-right sequence of functions
+   * @see {@link pipe} for applying a value through a left-to-right sequence immediately
+   *
    * @category combinators
    * @since 2.0.0
    */
@@ -599,7 +704,7 @@ export const compose: {
  *
  * **When to use**
  *
- * Use `absurd` when exhaustive checks prove a branch cannot be reached, but
+ * Use when exhaustive checks prove a branch cannot be reached, but
  * TypeScript still needs a return value.
  *
  * **Gotchas**
@@ -627,6 +732,10 @@ export const absurd = <A>(_: never): A => {
 /**
  * Creates a tupled version of this function: instead of `n` arguments, it accepts a single tuple argument.
  *
+ * **When to use**
+ *
+ * Use to adapt a multi-argument function so it accepts one tuple argument.
+ *
  * **Example** (Converting arguments to a tuple)
  *
  * ```ts
@@ -638,13 +747,19 @@ export const absurd = <A>(_: never): A => {
  * assert.deepStrictEqual(sumTupled([1, 2]), 3)
  * ```
  *
+ * @see {@link untupled} for adapting a tuple-argument function back to multiple arguments
+ *
  * @category combinators
  * @since 2.0.0
  */
 export const tupled = <A extends ReadonlyArray<unknown>, B>(f: (...a: A) => B): (a: A) => B => (a) => f(...a)
 
 /**
- * Inverse function of `tupled`
+ * Converts a tupled function back to an uncurried function.
+ *
+ * **When to use**
+ *
+ * Use to adapt a tuple-argument function so it accepts multiple arguments.
  *
  * **Example** (Converting a tuple to arguments)
  *
@@ -657,6 +772,8 @@ export const tupled = <A extends ReadonlyArray<unknown>, B>(f: (...a: A) => B):
  * assert.deepStrictEqual(getFirst(1, 2), 1)
  * ```
  *
+ * @see {@link tupled} for adapting a multi-argument function to one tuple argument
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -668,7 +785,7 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  *
  * **When to use**
  *
- * Use `pipe` with data-last functions to build readable transformation
+ * Use when you use `pipe` with data-last functions to build readable transformation
  * pipelines and to write method-style chains as ordinary function calls.
  *
  * **Details**
@@ -682,7 +799,7 @@ export const untupled = <A extends ReadonlyArray<unknown>, B>(f: (a: A) => B): (
  * Each function passed after the initial value must accept a single argument,
  * because `pipe` calls each step with only the previous result.
  *
- * **Example** (Showing pipeline syntax)
+ * **Example** (Using pipeline syntax)
  *
  * In this example, `1` is passed to the first function, and each result becomes
  * the input for the next function.
@@ -1223,10 +1340,15 @@ export function pipe(a: unknown, ...args: Array<any>): unknown {
 /**
  * Performs left-to-right function composition.
  *
+ * **When to use**
+ *
+ * Use to build a reusable function from a left-to-right sequence of
+ * transformations.
+ *
  * **Details**
  *
  * The first function may have any arity. Every following function must be
- * unary. See also [`pipe`](#pipe).
+ * unary.
  *
  * **Example** (Composing functions left to right)
  *
@@ -1242,6 +1364,9 @@ export function pipe(a: unknown, ...args: Array<any>): unknown {
  * assert.strictEqual(f("aaa"), 6)
  * ```
  *
+ * @see {@link pipe} for applying a value through a left-to-right sequence immediately
+ * @see {@link compose} for composing exactly two functions
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -1413,6 +1538,10 @@ export function flow(
 /**
  * Creates a compile-time placeholder for a value of any type.
  *
+ * **When to use**
+ *
+ * Use as a temporary typed placeholder while developing incomplete code.
+ *
  * **Gotchas**
  *
  * `hole` is intended for temporary development use. If the placeholder is
@@ -1438,13 +1567,13 @@ export function flow(
 export const hole: <T>() => T = cast(absurd)
 
 /**
- * The SK combinator, also known as the "S-K combinator" or "S-combinator", is
+ * Returns the second argument and discards the first. The SK combinator is
  * a fundamental combinator in the lambda calculus and the SKI combinator
  * calculus.
  *
  * **When to use**
  *
- * Use `SK` to discard the first argument and return the second argument.
+ * Use to discard the first argument and return the second argument.
  *
  * **Example** (Discarding the first argument)
  *
@@ -1461,8 +1590,25 @@ export const hole: <T>() => T = cast(absurd)
 export const SK = <A, B>(_: A, b: B): B => b
 
 /**
- * Memoizes a function whose input is an object, caching results by object
- * identity.
+ * Creates a memoized function whose input is an object, caching results by
+ * object identity.
+ *
+ * **When to use**
+ *
+ * Use to reuse the result of a synchronous computation whose output is stable
+ * for a given object reference.
+ *
+ * **Details**
+ *
+ * Each memoized wrapper owns a private `WeakMap` keyed by object identity.
+ * Cached `undefined` results are still returned because the cache is checked
+ * with `WeakMap.has`.
+ *
+ * **Gotchas**
+ *
+ * Structurally equal objects do not share cache entries. If the same object is
+ * mutated after its first call, later calls still return the cached result for
+ * that reference.
  *
  * @category utils
  * @since 4.0.0