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

package/dist/Unify.d.ts

@@ -1,26 +1,51 @@
 /**
- * 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
  */
 /**
- * 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
@@ -29,6 +54,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
@@ -40,12 +70,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
@@ -54,6 +91,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
@@ -65,13 +107,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
@@ -80,6 +128,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
@@ -108,6 +161,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
@@ -138,6 +195,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
  */
@@ -149,6 +208,11 @@ export type Unify<A> = Values<ExtractTypes<(FilterIn<A> & {
 /**
  * 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
@@ -180,6 +244,8 @@ export type Unify<A> = Values<ExtractTypes<(FilterIn<A> & {
  * // 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
  */
@@ -187,6 +253,11 @@ export declare 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
@@ -218,6 +289,8 @@ export declare 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
      */
@@ -225,6 +298,11 @@ export declare 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
@@ -256,6 +334,8 @@ export declare 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
      */
@@ -263,6 +343,11 @@ export declare 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
@@ -294,6 +379,8 @@ export declare 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
      */
@@ -301,6 +388,11 @@ export declare 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
@@ -332,6 +424,8 @@ export declare 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
      */
@@ -339,6 +433,11 @@ export declare 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
@@ -370,6 +469,8 @@ export declare 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
      */
@@ -377,6 +478,11 @@ export declare 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
@@ -408,6 +514,8 @@ export declare 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/dist/Unify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Unify.d.ts","sourceRoot":"","sources":["../src/Unify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,OAAO,CAAC,MAAM,WAAW,EAAE,OAAO,MAAM,CAAA;AAE/C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAA;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,OAAO,CAAC,MAAM,UAAU,EAAE,OAAO,MAAM,CAAA;AAE9C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAA;AAE1C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAA;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAA;AAE9C,KAAK,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAA;AAElE,KAAK,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,GAC1F,KAAK,CAAA;AAET,KAAK,MAAM,CAAC,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,GACjE,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,CAAC,SAAS,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,KAAK,GACzF,KAAK,CAAA;AAET,KAAK,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,CAAA;CAAE,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,GAC9E,KAAK,CAAA;AAET,KAAK,YAAY,CACf,CAAC,IACC,CAAC,SAAS;IACZ,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,KAAK,CAAA;IAC1B,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,MAAM,CAAA;CAC7B,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAChC,KAAK,CAAA;AAET,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,GAAG,UAAU,SAAS,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,KAAK,CAAA;AAEjF,KAAK,iBAAiB,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,GAAG,GACxC,UAAU,SAAS,MAAM,CAAC,GACxB,CAAC,SAAS;IAAE,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,OAAO,CAAC,MAAM,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,GACtG,CAAC,GACH,KAAK,GACL,KAAK,CAAA;AAET,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,GAAG,UAAU,SAAS,MAAM,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG,KAAK,CAAA;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,MAAM,CAC3B,YAAY,CACV,CACI,QAAQ,CAAC,CAAC,CAAC,GACX;IAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;CAAE,CACtB,CACF,CACF,SAAS,MAAM,CAAC,GACX,CAAC,GACD,iBAAiB,CACjB,CAAC,EACD,IAAI,CACF,YAAY,CACV,CACI,QAAQ,CAAC,CAAC,CAAC,GACX;IAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;CAAE,CACtB,CACF,CACF,CACF,GACC,SAAS,CAAC,CAAC,CAAC,GACd,KAAK,CAAA;AAET;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,KAAK,EAAE;IAClB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,CACE,IAAI,SAAS,KAAK,CAAC,GAAG,CAAC,EACvB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,CAAC,EAED,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GACtG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,CAAA;IAC9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,CACE,IAAI,SAAS,KAAK,CAAC,GAAG,CAAC,EACvB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,CAAC,EAED,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAClF,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,CAAA;IAC1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,CACE,IAAI,SAAS,KAAK,CAAC,GAAG,CAAC,EACvB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,CAAC,EACD,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,CAAA;IACvI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,CACE,IAAI,SAAS,KAAK,CAAC,GAAG,CAAC,EACvB,KAAK,SAAS,KAAK,CAAC,GAAG,CAAC,EACxB,CAAC,EACD,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,CAAA;IAC/F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,CACE,IAAI,SAAS,KAAK,CAAC,GAAG,CAAC,EACvB,CAAC,EACD,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAA;IACvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;CACF,CAAA"}
+{"version":3,"file":"Unify.d.ts","sourceRoot":"","sources":["../src/Unify.ts"],"names":[],"mappings":"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"}

package/dist/Unify.js

@@ -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,6 +35,11 @@ import { identity } from "./Function.js";
 /**
  * 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
@@ -49,6 +71,8 @@ import { identity } from "./Function.js";
  * // 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/dist/Unify.js.map

@@ -1 +1 @@
-{"version":3,"file":"Unify.js","names":["identity","unify"],"sources":["../src/Unify.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;AAiBA,SAASA,QAAQ,QAAQ,eAAe;AA8KxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,OAAO,MAAMC,KAAK,GAkQdD,QAAe","ignoreList":[]}
+{"version":3,"file":"Unify.js","names":["identity","unify"],"sources":["../src/Unify.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,SAASA,QAAQ,QAAQ,eAAe;AAwNxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,OAAO,MAAMC,KAAK,GA4SdD,QAAe","ignoreList":[]}

package/dist/Utils.d.ts

@@ -60,14 +60,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**
  *
@@ -75,7 +74,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)
  *
@@ -93,7 +91,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
  */
@@ -104,12 +102,22 @@ export declare 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>;
     /**
      * 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>;
@@ -120,9 +128,8 @@ export declare 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**
  *
@@ -144,7 +151,7 @@ export declare 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
  */
@@ -160,10 +167,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**
  *
@@ -179,8 +184,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
  */

package/dist/Utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Utils.d.ts","sourceRoot":"","sources":["../src/Utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Utils.d.ts","sourceRoot":"","sources":["../src/Utils.ts"],"names":[],"mappings":"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"}

package/dist/Utils.js

@@ -1,12 +1,11 @@
 /**
- * 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**
  *
@@ -14,7 +13,6 @@
  * 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)
  *
@@ -32,7 +30,7 @@
  * // { 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
  */
@@ -45,6 +43,11 @@ export class SingleShotGen {
   /**
    * 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) {
@@ -59,6 +62,11 @@ export class SingleShotGen {
   /**
    * 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]() {

package/dist/Utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"Utils.js","names":["SingleShotGen","called","self","constructor","next","a","value","done","Symbol","iterator","InternalTypeId","standard","body","forced","isNotOptimizedAway","Error","stack","includes","internalCall"],"sources":["../src/Utils.ts"],"sourcesContent":[null],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,OAAM,MAAOA,aAAa;EAChBC,MAAM,GAAG,KAAK;EACbC,IAAI;EAEbC,YAAYD,IAAO;IACjB,IAAI,CAACA,IAAI,GAAGA,IAAI;EAClB;EAEA;;;;;EAKAE,IAAIA,CAACC,CAAI;IACP,OAAO,IAAI,CAACJ,MAAM,GACf;MACCK,KAAK,EAAED,CAAC;MACRE,IAAI,EAAE;KACP,IACA,IAAI,CAACN,MAAM,GAAG,IAAI,EAChB;MACCK,KAAK,EAAE,IAAI,CAACJ,IAAI;MAChBK,IAAI,EAAE;KACN,CAAC;EACT;EAEA;;;;;EAKA,CAACC,MAAM,CAACC,QAAQ,IAAC;IACf,OAAO,IAAIT,aAAa,CAAO,IAAI,CAACE,IAAI,CAAC;EAC3C;;AAqGF,MAAMQ,cAAc,GAAG,wBAAwB;AAE/C,MAAMC,QAAQ,GAAG;EACf,CAACD,cAAc,GAAOE,IAAa,IAAI;IACrC,OAAOA,IAAI,EAAE;EACf;CACD;AAED,MAAMC,MAAM,GAAG;EACb,CAACH,cAAc,GAAOE,IAAa,IAAI;IACrC,IAAI;MACF,OAAOA,IAAI,EAAE;IACf,CAAC,SAAS;MACR;IAAA;EAEJ;CACD;AAED,MAAME,kBAAkB,GAAG,aAAAH,QAAQ,CAACD,cAAc,CAAC,CAAC,MAAM,IAAIK,KAAK,EAAE,CAACC,KAAK,CAAC,EAAEC,QAAQ,CAACP,cAAc,CAAC,KAAK,IAAI;AAE/G;AACA,OAAO,MAAMQ,YAAY,GAAGJ,kBAAkB,GAAGH,QAAQ,CAACD,cAAc,CAAC,GAAGG,MAAM,CAACH,cAAc,CAAC","ignoreList":[]}
+{"version":3,"file":"Utils.js","names":["SingleShotGen","called","self","constructor","next","a","value","done","Symbol","iterator","InternalTypeId","standard","body","forced","isNotOptimizedAway","Error","stack","includes","internalCall"],"sources":["../src/Utils.ts"],"sourcesContent":[null],"mappings":"AA8DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,OAAM,MAAOA,aAAa;EAChBC,MAAM,GAAG,KAAK;EACbC,IAAI;EAEbC,YAAYD,IAAO;IACjB,IAAI,CAACA,IAAI,GAAGA,IAAI;EAClB;EAEA;;;;;;;;;;EAUAE,IAAIA,CAACC,CAAI;IACP,OAAO,IAAI,CAACJ,MAAM,GACf;MACCK,KAAK,EAAED,CAAC;MACRE,IAAI,EAAE;KACP,IACA,IAAI,CAACN,MAAM,GAAG,IAAI,EAChB;MACCK,KAAK,EAAE,IAAI,CAACJ,IAAI;MAChBK,IAAI,EAAE;KACN,CAAC;EACT;EAEA;;;;;;;;;;EAUA,CAACC,MAAM,CAACC,QAAQ,IAAC;IACf,OAAO,IAAIT,aAAa,CAAO,IAAI,CAACE,IAAI,CAAC;EAC3C;;AAkGF,MAAMQ,cAAc,GAAG,wBAAwB;AAE/C,MAAMC,QAAQ,GAAG;EACf,CAACD,cAAc,GAAOE,IAAa,IAAI;IACrC,OAAOA,IAAI,EAAE;EACf;CACD;AAED,MAAMC,MAAM,GAAG;EACb,CAACH,cAAc,GAAOE,IAAa,IAAI;IACrC,IAAI;MACF,OAAOA,IAAI,EAAE;IACf,CAAC,SAAS;MACR;IAAA;EAEJ;CACD;AAED,MAAME,kBAAkB,GAAG,aAAAH,QAAQ,CAACD,cAAc,CAAC,CAAC,MAAM,IAAIK,KAAK,EAAE,CAACC,KAAK,CAAC,EAAEC,QAAQ,CAACP,cAAc,CAAC,KAAK,IAAI;AAE/G;AACA,OAAO,MAAMQ,YAAY,GAAGJ,kBAAkB,GAAGH,QAAQ,CAACD,cAAc,CAAC,GAAGG,MAAM,CAACH,cAAc,CAAC","ignoreList":[]}