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

package/src/Unify.ts

@@ -1,16 +1,33 @@
 /**
- * The `Unify` module contains the type-level protocol Effect uses to normalize
- * unions of data types that opt in to unification. It is primarily a library
- * authoring tool: data types expose hidden symbol properties describing how
- * their variants should be widened, and {@link Unify} turns those protocol
- * entries into the user-facing union type that TypeScript should infer.
- *
- * Most application code does not need to interact with these symbols directly.
- * The main runtime helper, {@link unify}, is an identity function that preserves
- * values and functions at runtime while applying {@link Unify} to the relevant
- * static type. This is useful when authoring APIs that return branded or
- * protocol-enabled values and need inference to collapse to the public Effect
- * data type rather than exposing implementation details.
+ * The `Unify` module defines the type-level protocol Effect uses to collapse
+ * unions of protocol-enabled values into their public data types. It is mostly
+ * for maintainers of Effect data types and advanced library authors; ordinary
+ * application code usually benefits from unification through APIs such as
+ * `Effect`, `Option`, `Result`, `Stream`, `Layer`, and `Match`.
+ *
+ * **Mental model**
+ *
+ * A type opts in by carrying phantom entries keyed by {@link typeSymbol} and
+ * {@link unifySymbol}. {@link Unify} reads those entries, ignores any protocol
+ * members listed through {@link ignoreSymbol}, and widens matching union
+ * members to the public type each entry returns. The runtime helper
+ * {@link unify} is an identity function; it changes only the static type that
+ * TypeScript sees.
+ *
+ * **Common tasks**
+ *
+ * - Add unification support to a new Effect data type so mixed unions infer as
+ *   the public container type instead of an implementation shape.
+ * - Normalize the return type of branching APIs, matchers, or builders that can
+ *   produce several protocol-enabled values.
+ * - Apply unification to a value or curried function result with {@link unify}
+ *   while preserving the original runtime behavior.
+ *
+ * **Gotchas**
+ *
+ * - Unification is a compile-time protocol, not a runtime conversion hook.
+ * - Protocol entries should be specific to the data type they widen; overly
+ *   broad entries can make inferred unions less precise.
  *
  * @since 2.0.0
  */
@@ -18,12 +35,20 @@
 import { identity } from "./Function.ts"
 
 /**
- * A unique symbol used to identify unification behavior in Effect types.
+ * Defines the unique symbol used to identify unification behavior in Effect types.
+ *
+ * **When to use**
+ *
+ * Use to define the widened type produced by the `Unify` protocol for a custom
+ * protocol-enabled data type.
  *
  * **Details**
  *
- * This symbol is used internally by the Effect type system to enable automatic
- * unification of Effect types in unions and complex type operations.
+ * This symbol is a type-level protocol key. It describes how a protocol-enabled
+ * type widens during unification and has no runtime behavior.
+ *
+ * @see {@link typeSymbol} for storing the source type information used during unification
+ * @see {@link ignoreSymbol} for excluding protocol entries from unification
  *
  * @category symbols
  * @since 2.0.0
@@ -33,6 +58,11 @@ export declare const unifySymbol: unique symbol
 /**
  * The type of the unifySymbol.
  *
+ * **When to use**
+ *
+ * Use to reference the unification behavior property key in type-level
+ * protocol definitions.
+ *
  * **Details**
  *
  * This type represents the unique symbol used for identifying unification
@@ -45,12 +75,19 @@ export declare const unifySymbol: unique symbol
 export type unifySymbol = typeof unifySymbol
 
 /**
- * A unique symbol used to identify the type information for unification.
+ * Defines the unique symbol used to identify the type information for unification.
+ *
+ * **When to use**
+ *
+ * Use with `unifySymbol` to expose the source type that unification should read
+ * from a protocol-enabled data type.
  *
  * **Details**
  *
- * This symbol is used internally by the Effect type system to store type
- * information that can be used during type unification operations.
+ * This symbol is a type-level protocol key. It stores the source type that
+ * unification reads when widening protocol-enabled values.
+ *
+ * @see {@link unifySymbol} for defining how protocol entries widen
  *
  * @category symbols
  * @since 2.0.0
@@ -60,6 +97,11 @@ export declare const typeSymbol: unique symbol
 /**
  * The type of the typeSymbol.
  *
+ * **When to use**
+ *
+ * Use to reference the type information property key in type-level protocol
+ * definitions.
+ *
  * **Details**
  *
  * This type represents the unique symbol used for storing type information
@@ -72,13 +114,19 @@ export declare const typeSymbol: unique symbol
 export type typeSymbol = typeof typeSymbol
 
 /**
- * A unique symbol used to specify types that should be ignored during unification.
+ * Defines the unique symbol used to specify types that should be ignored during unification.
+ *
+ * **When to use**
+ *
+ * Use to hide helper protocol entries from `Unify` when they should not
+ * contribute to the widened type.
  *
  * **Details**
  *
- * This symbol is used internally by the Effect type system to mark types
- * that should be excluded from the unification process, allowing for more
- * precise type handling in complex scenarios.
+ * This symbol is a type-level protocol key. It lists protocol entries that
+ * unification should ignore when computing the widened type.
+ *
+ * @see {@link unifySymbol} for defining the protocol entries being filtered
  *
  * @category symbols
  * @since 2.0.0
@@ -88,6 +136,11 @@ export declare const ignoreSymbol: unique symbol
 /**
  * The type of the ignoreSymbol.
  *
+ * **When to use**
+ *
+ * Use to reference the ignored-property key in type-level protocol
+ * definitions.
+ *
  * **Details**
  *
  * This type represents the unique symbol used for marking types that should
@@ -133,6 +186,10 @@ type FilterOut<A> = A extends any ? typeSymbol extends keyof A ? never : A : nev
 /**
  * Unifies types that implement the unification protocol.
  *
+ * **When to use**
+ *
+ * Use to normalize unions of types that expose Effect's unification protocol.
+ *
  * **Details**
  *
  * This type performs automatic type unification for types that contain
@@ -163,6 +220,8 @@ type FilterOut<A> = A extends any ? typeSymbol extends keyof A ? never : A : nev
  * // Results in a properly unified type
  * ```
  *
+ * @see {@link unify} for applying this normalization to a value or function
+ *
  * @category models
  * @since 2.0.0
  */
@@ -192,6 +251,11 @@ export type Unify<A> = Values<
 /**
  * Applies `Unify` to a value or function return type at compile time.
  *
+ * **When to use**
+ *
+ * Use to keep a value or function unchanged at runtime while normalizing its
+ * inferred type with Effect's unification protocol.
+ *
  * **Details**
  *
  * This is an identity function at runtime. For functions, the returned function
@@ -223,6 +287,8 @@ export type Unify<A> = Values<
  * // Type: (a: string) => (b: number) => Unify<{ result: string }>
  * ```
  *
+ * @see {@link Unify} for the type-level normalization applied by this helper
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -230,6 +296,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -261,6 +332,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -277,6 +350,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -308,6 +386,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -323,6 +403,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -354,6 +439,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -366,6 +453,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -397,6 +489,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -408,6 +502,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -439,6 +538,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -449,6 +550,11 @@ export const unify: {
   /**
    * Applies `Unify` to a value or function return type at compile time.
    *
+   * **When to use**
+   *
+   * Use to keep a value or function unchanged at runtime while normalizing its
+   * inferred type with Effect's unification protocol.
+   *
    * **Details**
    *
    * This is an identity function at runtime. For functions, the returned function
@@ -480,6 +586,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @see {@link Unify} for the type-level normalization applied by this helper
+   *
    * @category utils
    * @since 2.0.0
    */

package/src/Utils.ts

@@ -61,14 +61,13 @@ import type { Kind, TypeLambda } from "./HKT.ts"
 import type * as Types from "./Types.ts"
 
 /**
- * An `IterableIterator` that yields its wrapped value exactly once.
+ * Yields its wrapped value exactly once through an `IterableIterator`.
  *
  * **When to use**
  *
- * Implement `[Symbol.iterator]()` on Effect-like types so they can be
+ * Use to implement `[Symbol.iterator]()` on Effect-like types so they can be
  * `yield*`-ed inside generator functions, such as `Effect.gen` and
- * `Option.gen`. You almost never construct this directly — it is created
- * internally by yieldable types.
+ * `Option.gen`.
  *
  * **Details**
  *
@@ -76,7 +75,6 @@ import type * as Types from "./Types.ts"
  * subsequent call returns `{ value: a, done: true }` where `a` is the argument
  * passed to `next()`. `[Symbol.iterator]()` returns a **new** `SingleShotGen`
  * wrapping the same value, so the outer type can be iterated multiple times.
- * It does not mutate the wrapped value.
  *
  * **Example** (Yielding a wrapped value in a generator)
  *
@@ -94,7 +92,7 @@ import type * as Types from "./Types.ts"
  * // { value: 42, done: true }
  * ```
  *
- * @see {@link Gen} — the type-level signature that relies on `SingleShotGen`
+ * @see {@link Gen} for the type-level signature that relies on `SingleShotGen`
  * @category constructors
  * @since 2.0.0
  */
@@ -109,6 +107,11 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
   /**
    * Yields the stored value once, then completes with the value sent back in.
    *
+   * **When to use**
+   *
+   * Use to advance a `SingleShotGen` through its single yield and completion
+   * step.
+   *
    * @since 2.0.0
    */
   next(a: A): IteratorResult<T, A> {
@@ -127,6 +130,11 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
   /**
    * Creates a fresh single-shot iterator over the stored value.
    *
+   * **When to use**
+   *
+   * Use to iterate the wrapped value again without reusing the consumed
+   * iterator state.
+   *
    * @since 2.0.0
    */
   [Symbol.iterator](): IterableIterator<T, A> {
@@ -140,9 +148,8 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
  *
  * **When to use**
  *
- * Define variance constraints for a higher-kinded type so that {@link Gen}
- * can correctly infer `R`, `O`, and `E` from yielded values. You typically
- * don't construct values of this type — it exists purely for type inference.
+ * Use to define variance constraints for a higher-kinded type so that
+ * {@link Gen} can correctly infer `R`, `O`, and `E` from yielded values.
  *
  * **Details**
  *
@@ -164,7 +171,7 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
  * >
  * ```
  *
- * @see {@link Gen} — uses `Variance` for type parameter inference
+ * @see {@link Gen} for the type-level signature that uses `Variance`
  * @category models
  * @since 2.0.0
  */
@@ -181,10 +188,8 @@ export interface Variance<in out F extends TypeLambda, in R, out O, out E> {
  *
  * **When to use**
  *
- * Type the `gen` function of a module that supports generator syntax, such as
- * `Option.gen`, `Result.gen`, and `Effect.gen`. It accepts either `(body)` or
- * `(self, body)` where `body` is a generator function. The `self` overload
- * binds `this` inside the generator.
+ * Use to type the `gen` function of a module that supports generator syntax,
+ * such as `Option.gen`, `Result.gen`, and `Effect.gen`.
  *
  * **Details**
  *
@@ -200,8 +205,8 @@ export interface Variance<in out F extends TypeLambda, in R, out O, out E> {
  * declare const gen: Utils.Gen<Option.OptionTypeLambda>
  * ```
  *
- * @see {@link Variance} — encodes the variance used for inference
- * @see {@link SingleShotGen} — the iterator protocol that makes yielding work
+ * @see {@link Variance} for encoding the variance used for inference
+ * @see {@link SingleShotGen} for the iterator protocol that makes yielding work
  * @category models
  * @since 2.0.0
  */