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

package/src/Unify.ts

@@ -1,4 +1,17 @@
 /**
+ * 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.
+ *
  * @since 2.0.0
  */
 
@@ -10,19 +23,8 @@ import { identity } from "./Function.ts"
  * This symbol is used internally by the Effect type system to enable automatic
  * unification of Effect types in unions and complex type operations.
  *
- * @example
- * ```ts
- * import type { Unify } from "effect"
- *
- * // The unifySymbol is used internally in Effect types
- * // to enable automatic type unification
- * declare const effect: {
- *   readonly [Unify.unifySymbol]?: any
- * }
- * ```
- *
- * @since 2.0.0
  * @category symbols
+ * @since 2.0.0
  */
 export declare const unifySymbol: unique symbol
 
@@ -33,19 +35,8 @@ export declare const unifySymbol: unique symbol
  * behavior in Effect types. It's typically used in type-level operations
  * to enable automatic type unification.
  *
- * @example
- * ```ts
- * import type { Unify } from "effect"
- *
- * // The unifySymbol type is used in type declarations
- * // to enable unification behavior
- * type UnifyableType = {
- *   [Unify.unifySymbol]?: any
- * }
- * ```
- *
- * @since 2.0.0
  * @category symbols
+ * @since 2.0.0
  */
 export type unifySymbol = typeof unifySymbol
 
@@ -55,19 +46,8 @@ export type unifySymbol = typeof unifySymbol
  * This symbol is used internally by the Effect type system to store type
  * information that can be used during type unification operations.
  *
- * @example
- * ```ts
- * import type { Unify } from "effect"
- *
- * // The typeSymbol is used internally in Effect types
- * // to store type information for unification
- * declare const effect: {
- *   readonly [Unify.typeSymbol]?: any
- * }
- * ```
- *
- * @since 2.0.0
  * @category symbols
+ * @since 2.0.0
  */
 export declare const typeSymbol: unique symbol
 
@@ -78,19 +58,8 @@ export declare const typeSymbol: unique symbol
  * in types that support unification. It's used in type-level operations
  * to access and manipulate type information.
  *
- * @example
- * ```ts
- * import type { Unify } from "effect"
- *
- * // The typeSymbol type is used in type declarations
- * // to store type information for unification
- * type TypedValue = {
- *   [Unify.typeSymbol]?: string
- * }
- * ```
- *
- * @since 2.0.0
  * @category symbols
+ * @since 2.0.0
  */
 export type typeSymbol = typeof typeSymbol
 
@@ -101,19 +70,8 @@ export type typeSymbol = typeof typeSymbol
  * that should be excluded from the unification process, allowing for more
  * precise type handling in complex scenarios.
  *
- * @example
- * ```ts
- * import type { Unify } from "effect"
- *
- * // The ignoreSymbol is used internally in Effect types
- * // to mark types that should be ignored during unification
- * declare const effect: {
- *   readonly [Unify.ignoreSymbol]?: any
- * }
- * ```
- *
- * @since 2.0.0
  * @category symbols
+ * @since 2.0.0
  */
 export declare const ignoreSymbol: unique symbol
 
@@ -124,19 +82,8 @@ export declare const ignoreSymbol: unique symbol
  * be ignored during unification operations. It's used in type-level operations
  * to exclude specific types from the unification process.
  *
- * @example
- * ```ts
- * import type { Unify } from "effect"
- *
- * // The ignoreSymbol type is used in type declarations
- * // to mark types that should be ignored during unification
- * type IgnorableType = {
- *   [Unify.ignoreSymbol]?: unknown
- * }
- * ```
- *
- * @since 2.0.0
  * @category symbols
+ * @since 2.0.0
  */
 export type ignoreSymbol = typeof ignoreSymbol
 
@@ -179,9 +126,10 @@ type FilterOut<A> = A extends any ? typeSymbol extends keyof A ? never : A : nev
  * It's primarily used internally by the Effect type system to handle
  * complex type unions and provide better type inference.
  *
- * @example
+ * **Example** (Unifying protocol types)
+ *
  * ```ts
- * import type * as Unify from "effect/Unify"
+ * import type { Unify } from "effect"
  *
  * // Example of types that can be unified
  * type UnifiableA = {
@@ -201,8 +149,8 @@ type FilterOut<A> = A extends any ? typeSymbol extends keyof A ? never : A : nev
  * // Results in a properly unified type
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export type Unify<A> = Values<
   ExtractTypes<
@@ -228,13 +176,14 @@ export type Unify<A> = Values<
   : never
 
 /**
- * Unifies the return type of a function or value.
+ * Applies `Unify` to a value or function return type at compile time.
  *
- * This function applies type unification to the result of a function or to a value directly.
- * It's useful when you need to ensure that complex type unions are properly unified according
- * to the Effect type system's unification protocol.
+ * This is an identity function at runtime. For functions, the returned function
+ * has the same runtime behavior while its return type is normalized with the
+ * Effect unification protocol.
+ *
+ * **Example** (Unifying values and function results)
  *
- * @example
  * ```ts
  * import { Unify } from "effect"
  *
@@ -258,18 +207,19 @@ export type Unify<A> = Values<
  * // Type: (a: string) => (b: number) => Unify<{ result: string }>
  * ```
  *
+ * @category utils
  * @since 2.0.0
- * @category utilities
  */
 export const unify: {
   /**
-   * Unifies the return type of a function or value.
+   * Applies `Unify` to a value or function return type at compile time.
+   *
+   * This is an identity function at runtime. For functions, the returned function
+   * has the same runtime behavior while its return type is normalized with the
+   * Effect unification protocol.
    *
-   * This function applies type unification to the result of a function or to a value directly.
-   * It's useful when you need to ensure that complex type unions are properly unified according
-   * to the Effect type system's unification protocol.
+   * **Example** (Unifying values and function results)
    *
-   * @example
    * ```ts
    * import { Unify } from "effect"
    *
@@ -293,8 +243,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <
     Args extends Array<any>,
@@ -307,13 +257,14 @@ export const unify: {
     x: (...args: Args) => (...args: Args2) => (...args: Args3) => (...args: Args4) => (...args: Args5) => T
   ): (...args: Args) => (...args: Args2) => (...args: Args3) => (...args: Args4) => (...args: Args5) => Unify<T>
   /**
-   * Unifies the return type of a function or value.
+   * Applies `Unify` to a value or function return type at compile time.
    *
-   * This function applies type unification to the result of a function or to a value directly.
-   * It's useful when you need to ensure that complex type unions are properly unified according
-   * to the Effect type system's unification protocol.
+   * This is an identity function at runtime. For functions, the returned function
+   * has the same runtime behavior while its return type is normalized with the
+   * Effect unification protocol.
+   *
+   * **Example** (Unifying values and function results)
    *
-   * @example
    * ```ts
    * import { Unify } from "effect"
    *
@@ -337,8 +288,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <
     Args extends Array<any>,
@@ -350,13 +301,14 @@ export const unify: {
     x: (...args: Args) => (...args: Args2) => (...args: Args3) => (...args: Args4) => T
   ): (...args: Args) => (...args: Args2) => (...args: Args3) => (...args: Args4) => Unify<T>
   /**
-   * Unifies the return type of a function or value.
+   * Applies `Unify` to a value or function return type at compile time.
+   *
+   * This is an identity function at runtime. For functions, the returned function
+   * has the same runtime behavior while its return type is normalized with the
+   * Effect unification protocol.
    *
-   * This function applies type unification to the result of a function or to a value directly.
-   * It's useful when you need to ensure that complex type unions are properly unified according
-   * to the Effect type system's unification protocol.
+   * **Example** (Unifying values and function results)
    *
-   * @example
    * ```ts
    * import { Unify } from "effect"
    *
@@ -380,8 +332,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <
     Args extends Array<any>,
@@ -390,13 +342,14 @@ export const unify: {
     T
   >(x: (...args: Args) => (...args: Args2) => (...args: Args3) => T): (...args: Args) => (...args: Args2) => (...args: Args3) => Unify<T>
   /**
-   * Unifies the return type of a function or value.
+   * Applies `Unify` to a value or function return type at compile time.
    *
-   * This function applies type unification to the result of a function or to a value directly.
-   * It's useful when you need to ensure that complex type unions are properly unified according
-   * to the Effect type system's unification protocol.
+   * This is an identity function at runtime. For functions, the returned function
+   * has the same runtime behavior while its return type is normalized with the
+   * Effect unification protocol.
+   *
+   * **Example** (Unifying values and function results)
    *
-   * @example
    * ```ts
    * import { Unify } from "effect"
    *
@@ -420,8 +373,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <
     Args extends Array<any>,
@@ -429,13 +382,14 @@ export const unify: {
     T
   >(x: (...args: Args) => (...args: Args2) => T): (...args: Args) => (...args: Args2) => Unify<T>
   /**
-   * Unifies the return type of a function or value.
+   * Applies `Unify` to a value or function return type at compile time.
+   *
+   * This is an identity function at runtime. For functions, the returned function
+   * has the same runtime behavior while its return type is normalized with the
+   * Effect unification protocol.
    *
-   * This function applies type unification to the result of a function or to a value directly.
-   * It's useful when you need to ensure that complex type unions are properly unified according
-   * to the Effect type system's unification protocol.
+   * **Example** (Unifying values and function results)
    *
-   * @example
    * ```ts
    * import { Unify } from "effect"
    *
@@ -459,21 +413,22 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <
     Args extends Array<any>,
     T
   >(x: (...args: Args) => T): (...args: Args) => Unify<T>
   /**
-   * Unifies the return type of a function or value.
+   * Applies `Unify` to a value or function return type at compile time.
+   *
+   * This is an identity function at runtime. For functions, the returned function
+   * has the same runtime behavior while its return type is normalized with the
+   * Effect unification protocol.
    *
-   * This function applies type unification to the result of a function or to a value directly.
-   * It's useful when you need to ensure that complex type unions are properly unified according
-   * to the Effect type system's unification protocol.
+   * **Example** (Unifying values and function results)
    *
-   * @example
    * ```ts
    * import { Unify } from "effect"
    *
@@ -497,8 +452,8 @@ export const unify: {
    * // Type: (a: string) => (b: number) => Unify<{ result: string }>
    * ```
    *
+   * @category utils
    * @since 2.0.0
-   * @category utilities
    */
   <T>(x: T): Unify<T>
 } = identity as any

package/src/Utils.ts

@@ -109,6 +109,8 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
   }
 
   /**
+   * Yields the stored value once, then completes with the value sent back in.
+   *
    * @since 2.0.0
    */
   next(a: A): IteratorResult<T, A> {
@@ -125,6 +127,8 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
   }
 
   /**
+   * Creates a fresh single-shot iterator over the stored value.
+   *
    * @since 2.0.0
    */
   [Symbol.iterator](): IterableIterator<T, A> {
@@ -153,8 +157,7 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
  * **Example** (Declaring variance for a TypeLambda)
  *
  * ```ts
- * import type { Utils } from "effect"
- * import type * as Option from "effect/Option"
+ * import type { Option, Utils } from "effect"
  *
  * declare const variance: Utils.Variance<
  *   Option.OptionTypeLambda,