effect 4.0.0-beta.102 → 4.0.0-beta.103

package/dist/Types.d.ts

@@ -9,7 +9,7 @@
  * @since 4.0.0
  */
 /**
- * @category tuples
+ * @category utility types
  * @since 2.0.0
  */
 type TupleOf_<T, N extends number, R extends Array<unknown>> = `${N}` extends `-${number}` ? never : R["length"] extends N ? R : TupleOf_<T, N, [T, ...R]>;
@@ -29,7 +29,7 @@ type TupleOf_<T, N extends number, R extends Array<unknown>> = `${N}` extends `-
  *
  * **Example** (Checking fixed-length tuples)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * // Exactly 3 numbers
@@ -44,7 +44,7 @@ type TupleOf_<T, N extends number, R extends Array<unknown>> = `${N}` extends `-
  *
  * @see {@link TupleOfAtLeast}
  *
- * @category tuples
+ * @category utility types
  * @since 3.3.0
  */
 export type TupleOf<N extends number, T> = N extends N ? number extends N ? Array<T> : TupleOf_<T, N, []> : never;
@@ -63,7 +63,7 @@ export type TupleOf<N extends number, T> = N extends N ? number extends N ? Arra
  *
  * **Example** (Checking minimum-length tuples)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * // At least 2 strings
@@ -76,7 +76,7 @@ export type TupleOf<N extends number, T> = N extends N ? number extends N ? Arra
  *
  * @see {@link TupleOf}
  *
- * @category tuples
+ * @category utility types
  * @since 3.3.0
  */
 export type TupleOfAtLeast<N extends number, T> = [...TupleOf<N, T>, ...Array<T>];
@@ -93,7 +93,7 @@ export type TupleOfAtLeast<N extends number, T> = [...TupleOf<N, T>, ...Array<T>
  *
  * **Example** (Extracting tags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type MyError =
@@ -103,12 +103,14 @@ export type TupleOfAtLeast<N extends number, T> = [...TupleOf<N, T>, ...Array<T>
  *
  * type Result = Types.Tags<MyError>
  * // "NotFound" | "Timeout"
+ *
+ * const witness: Result = "NotFound"
  * ```
  *
  * @see {@link ExtractTag}
  * @see {@link ExcludeTag}
  *
- * @category types
+ * @category utility types
  * @since 2.0.0
  */
 export type Tags<E> = E extends {
@@ -128,7 +130,7 @@ export type Tags<E> = E extends {
  *
  * **Example** (Removing a variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type MyError =
@@ -138,12 +140,14 @@ export type Tags<E> = E extends {
  *
  * type WithoutTimeout = Types.ExcludeTag<MyError, "Timeout">
  * // { readonly _tag: "NotFound"; readonly id: string } | string
+ *
+ * const witness: WithoutTimeout = { _tag: "NotFound", id: "1" }
  * ```
  *
  * @see {@link ExtractTag}
  * @see {@link Tags}
  *
- * @category types
+ * @category utility types
  * @since 2.0.0
  */
 export type ExcludeTag<E, K extends string> = Exclude<E, {
@@ -163,7 +167,7 @@ export type ExcludeTag<E, K extends string> = Exclude<E, {
  *
  * **Example** (Extracting a variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type MyError =
@@ -172,12 +176,14 @@ export type ExcludeTag<E, K extends string> = Exclude<E, {
  *
  * type TimeoutError = Types.ExtractTag<MyError, "Timeout">
  * // { readonly _tag: "Timeout"; readonly ms: number }
+ *
+ * const witness: TimeoutError = { _tag: "Timeout", ms: 100 }
  * ```
  *
  * @see {@link ExcludeTag}
  * @see {@link Tags}
  *
- * @category types
+ * @category utility types
  * @since 2.0.0
  */
 export type ExtractTag<E, K extends string> = E extends {
@@ -200,17 +206,19 @@ export type ExtractTag<E, K extends string> = E extends {
  *
  * **Example** (Converting a union to an intersection)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Union = { a: string } | { b: number }
  * type Result = Types.UnionToIntersection<Union>
  * // { a: string } & { b: number }
+ *
+ * const witness: Result = { a: "value", b: 1 }
  * ```
  *
  * @see {@link IsUnion}
  *
- * @category types
+ * @category utility types
  * @since 2.0.0
  */
 export type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) extends (x: infer R) => any ? R : never;
@@ -228,18 +236,20 @@ export type UnionToIntersection<T> = (T extends any ? (x: T) => any : never) ext
  *
  * **Example** (Simplifying an intersection)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * // Without Simplify: IDE shows { a: number } & { b: string }
  * // With Simplify: IDE shows { a: number; b: string }
  * type Clean = Types.Simplify<{ a: number } & { b: string }>
+ *
+ * const witness: Clean = { a: 1, b: "value" }
  * ```
  *
  * @see {@link MergeLeft}
  * @see {@link MergeRight}
  *
- * @category types
+ * @category utility types
  * @since 2.0.0
  */
 export type Simplify<A> = {
@@ -260,7 +270,7 @@ export type Simplify<A> = {
  *
  * **Example** (Checking type equality)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Yes = Types.Equals<{ a: number }, { a: number }> // true
@@ -270,7 +280,7 @@ export type Simplify<A> = {
  *
  * @see {@link EqualsWith}
  *
- * @category models
+ * @category utility types
  * @since 2.0.0
  */
 export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => (T extends Y ? 1 : 2) ? true : false;
@@ -287,7 +297,7 @@ export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => (T ex
  *
  * **Example** (Choosing a conditional type based on equality)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type R1 = Types.EqualsWith<string, string, "same", "diff"> // "same"
@@ -296,7 +306,7 @@ export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => (T ex
  *
  * @see {@link Equals}
  *
- * @category models
+ * @category utility types
  * @since 3.15.0
  */
 export type EqualsWith<A, B, Y, N> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? Y : N;
@@ -315,14 +325,14 @@ export type EqualsWith<A, B, Y, N> = (<T>() => T extends A ? 1 : 2) extends (<T>
  *
  * **Example** (Checking key presence)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Yes = Types.Has<{ a: number; b: string }, "a" | "c"> // true
  * type No = Types.Has<{ a: number }, "b" | "c"> // false
  * ```
  *
- * @category models
+ * @category utility types
  * @since 2.0.0
  */
 export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof A ? true : never : never) extends never ? false : true;
@@ -340,7 +350,7 @@ export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof
  *
  * **Example** (Merging with left bias)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Result = Types.MergeLeft<
@@ -348,12 +358,14 @@ export type Has<A, Key extends string> = (Key extends infer K ? K extends keyof
  *   { a: string; c: boolean }
  * >
  * // { a: number; b: number; c: boolean }
+ *
+ * const witness: Result = { a: 1, b: 2, c: true }
  * ```
  *
  * @see {@link MergeRight}
  * @see {@link Simplify}
  *
- * @category models
+ * @category utility types
  * @since 2.0.0
  */
 export type MergeLeft<Source, Target> = MergeRight<Target, Source>;
@@ -371,7 +383,7 @@ export type MergeLeft<Source, Target> = MergeRight<Target, Source>;
  *
  * **Example** (Right-biased merge)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Result = Types.MergeRight<
@@ -379,12 +391,14 @@ export type MergeLeft<Source, Target> = MergeRight<Target, Source>;
  *   { a: string; c: boolean }
  * >
  * // { a: string; b: number; c: boolean }
+ *
+ * const witness: Result = { a: "value", b: 2, c: true }
  * ```
  *
  * @see {@link MergeLeft}
  * @see {@link Simplify}
  *
- * @category models
+ * @category utility types
  * @since 2.0.0
  */
 export type MergeRight<Target, Source> = Simplify<Source & {
@@ -405,7 +419,7 @@ export type MergeRight<Target, Source> = Simplify<Source & {
  *
  * **Example** (Setting concurrency values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * const sequential: Types.Concurrency = 1
@@ -431,7 +445,7 @@ export type Concurrency = number | "unbounded";
  *
  * **Example** (Converting shallowly to mutable types)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Obj = Types.Mutable<{
@@ -446,11 +460,14 @@ export type Concurrency = number | "unbounded";
  *
  * type Tup = Types.Mutable<readonly [string, number]>
  * // [string, number]
+ *
+ * const tuple: Tup = ["value", 1]
+ * tuple[1] = 2
  * ```
  *
  * @see {@link DeepMutable}
  *
- * @category types
+ * @category utility types
  * @since 2.0.0
  */
 export type Mutable<T> = {
@@ -471,7 +488,7 @@ export type Mutable<T> = {
  *
  * **Example** (Converting deeply to mutable types)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Deep = Types.DeepMutable<{
@@ -479,11 +496,14 @@ export type Mutable<T> = {
  *   readonly b: ReadonlyArray<{ readonly c: number }>
  * }>
  * // { a: string; b: Array<{ c: number }> }
+ *
+ * const witness: Deep = { a: "value", b: [{ c: 1 }] }
+ * witness.b[0].c = 2
  * ```
  *
  * @see {@link Mutable}
  *
- * @category types
+ * @category utility types
  * @since 3.1.0
  */
 export type DeepMutable<T> = T extends ReadonlyMap<infer K, infer V> ? Map<DeepMutable<K>, DeepMutable<V>> : T extends ReadonlySet<infer V> ? Set<DeepMutable<V>> : T extends string | number | boolean | bigint | symbol | Function ? T : {
@@ -504,16 +524,18 @@ export type DeepMutable<T> = T extends ReadonlyMap<infer K, infer V> ? Map<DeepM
  *
  * **Example** (Controlling inference)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
- * declare function withDefault<T>(value: T, fallback: Types.NoInfer<T>): T
+ * function withDefault<T>(value: T, _fallback: Types.NoInfer<T>): T {
+ *   return value
+ * }
  *
  * // T is inferred as "a" | "b" from the first argument only
  * const result = withDefault<"a" | "b">("a", "b")
  * ```
  *
- * @category models
+ * @category utility types
  * @since 2.0.0
  */
 export type NoInfer<A> = [A][A extends any ? 0 : never];
@@ -533,20 +555,22 @@ export type NoInfer<A> = [A][A extends any ? 0 : never];
  *
  * **Example** (Defining an invariant phantom type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * interface Container<T> {
  *   readonly _phantom: Types.Invariant<T>
  *   readonly value: T
  * }
+ *
+ * const container: Container<number> = { _phantom: (value) => value, value: 1 }
  * ```
  *
  * @see {@link Invariant.Type}
  * @see {@link Covariant}
  * @see {@link Contravariant}
  *
- * @category models
+ * @category utility types
  * @since 2.0.0
  */
 export type Invariant<A> = (_: A) => A;
@@ -569,16 +593,18 @@ export declare namespace Invariant {
      *
      * **Example** (Extracting the inner type)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import type { Types } from "effect"
      *
      * type Inner = Types.Invariant.Type<Types.Invariant<number>>
      * // number
+     *
+     * const witness: Inner = 1
      * ```
      *
      * @see {@link Invariant}
      *
-     * @category models
+     * @category utility types
      * @since 3.9.0
      */
     type Type<A> = A extends Invariant<infer U> ? U : never;
@@ -599,20 +625,22 @@ export declare namespace Invariant {
  *
  * **Example** (Defining a covariant phantom type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * interface Producer<T> {
  *   readonly _phantom: Types.Covariant<T>
  *   readonly get: () => T
  * }
+ *
+ * const producer: Producer<string> = { _phantom: () => "value", get: () => "value" }
  * ```
  *
  * @see {@link Covariant.Type}
  * @see {@link Contravariant}
  * @see {@link Invariant}
  *
- * @category models
+ * @category utility types
  * @since 2.0.0
  */
 export type Covariant<A> = (_: never) => A;
@@ -635,16 +663,18 @@ export declare namespace Covariant {
      *
      * **Example** (Extracting the inner type)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import type { Types } from "effect"
      *
      * type Inner = Types.Covariant.Type<Types.Covariant<string>>
      * // string
+     *
+     * const witness: Inner = "value"
      * ```
      *
      * @see {@link Covariant}
      *
-     * @category models
+     * @category utility types
      * @since 3.9.0
      */
     type Type<A> = A extends Covariant<infer U> ? U : never;
@@ -665,20 +695,25 @@ export declare namespace Covariant {
  *
  * **Example** (Defining a contravariant phantom type)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * interface Consumer<T> {
  *   readonly _phantom: Types.Contravariant<T>
  *   readonly accept: (value: T) => void
  * }
+ *
+ * const consumer: Consumer<string> = {
+ *   _phantom: () => {},
+ *   accept: (_value) => {}
+ * }
  * ```
  *
  * @see {@link Contravariant.Type}
  * @see {@link Covariant}
  * @see {@link Invariant}
  *
- * @category models
+ * @category utility types
  * @since 2.0.0
  */
 export type Contravariant<A> = (_: A) => void;
@@ -701,16 +736,18 @@ export declare namespace Contravariant {
      *
      * **Example** (Extracting the inner type)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import type { Types } from "effect"
      *
      * type Inner = Types.Contravariant.Type<Types.Contravariant<string>>
      * // string
+     *
+     * const witness: Inner = "value"
      * ```
      *
      * @see {@link Contravariant}
      *
-     * @category models
+     * @category utility types
      * @since 3.9.0
      */
     type Type<A> = A extends Contravariant<infer U> ? U : never;
@@ -723,7 +760,7 @@ export declare namespace Contravariant {
  *
  * Use to erase an empty object type from an API result or parameter position.
  *
- * @category types
+ * @category utility types
  * @since 3.19.20
  */
 export type VoidIfEmpty<S> = keyof S extends never ? void : S;
@@ -740,14 +777,16 @@ export type VoidIfEmpty<S> = keyof S extends never ? void : S;
  *
  * **Example** (Filtering out functions)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Result = Types.NotFunction<string | (() => void) | number>
  * // string | number
+ *
+ * const witness: Result = "value"
  * ```
  *
- * @category types
+ * @category utility types
  * @since 2.0.0
  */
 export type NotFunction<T> = T extends Function ? never : T;
@@ -764,7 +803,7 @@ export type NotFunction<T> = T extends Function ? never : T;
  *
  * **Example** (Preventing extra properties)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Expected = { a: number; b: string }
@@ -772,9 +811,11 @@ export type NotFunction<T> = T extends Function ? never : T;
  *
  * type Result = Types.NoExcessProperties<Expected, Input>
  * // { a: number; b: string; readonly c: never }
+ *
+ * const accepted: Types.NoExcessProperties<Expected, Expected> = { a: 1, b: "value" }
  * ```
  *
- * @category types
+ * @category utility types
  * @since 3.9.0
  */
 export type NoExcessProperties<T, U> = T & Readonly<Record<Exclude<keyof U, keyof T>, never>>;
@@ -793,7 +834,7 @@ export type NoExcessProperties<T, U> = T & Readonly<Record<Exclude<keyof U, keyo
  *
  * @see {@link unhandled}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export interface unassigned {
@@ -814,7 +855,7 @@ export interface unassigned {
  *
  * @see {@link unassigned}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export interface unhandled {
@@ -836,7 +877,7 @@ export interface unhandled {
  *
  * **Example** (Detecting union types)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Yes = Types.IsUnion<"a" | "b"> // true
@@ -845,7 +886,7 @@ export interface unhandled {
  *
  * @see {@link UnionToIntersection}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
@@ -863,7 +904,7 @@ export type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
  *
  * **Example** (Extracting reason types)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -872,13 +913,15 @@ export type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
  *
  * type Reasons = Types.ReasonOf<ApiError>
  * // RateLimitError | QuotaError
+ *
+ * const witness: Reasons = { _tag: "QuotaError", limit: 10 }
  * ```
  *
  * @see {@link ReasonTags}
  * @see {@link ExtractReason}
  * @see {@link ExcludeReason}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export type ReasonOf<E> = E extends {
@@ -899,7 +942,7 @@ export type ReasonOf<E> = E extends {
  *
  * **Example** (Getting reason tags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -908,12 +951,14 @@ export type ReasonOf<E> = E extends {
  *
  * type Result = Types.ReasonTags<ApiError>
  * // "RateLimitError" | "QuotaError"
+ *
+ * const witness: Result = "RateLimitError"
  * ```
  *
  * @see {@link ReasonOf}
  * @see {@link ExtractReason}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export type ReasonTags<E> = E extends {
@@ -936,7 +981,7 @@ export type ReasonTags<E> = E extends {
  *
  * **Example** (Extracting a reason variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -945,13 +990,15 @@ export type ReasonTags<E> = E extends {
  *
  * type Result = Types.ExtractReason<ApiError, "RateLimitError">
  * // { readonly _tag: "RateLimitError"; readonly retryAfter: number }
+ *
+ * const witness: Result = { _tag: "RateLimitError", retryAfter: 30 }
  * ```
  *
  * @see {@link ExcludeReason}
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export type ExtractReason<E, K extends string> = E extends {
@@ -974,7 +1021,7 @@ export type ExtractReason<E, K extends string> = E extends {
  *
  * **Example** (Narrowing a reason variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -983,13 +1030,18 @@ export type ExtractReason<E, K extends string> = E extends {
  *
  * type Result = Types.NarrowReason<ApiError, "RateLimitError">
  * // ApiError & { readonly reason: { readonly _tag: "RateLimitError"; readonly retryAfter: number } }
+ *
+ * const witness: Result = {
+ *   _tag: "ApiError",
+ *   reason: { _tag: "RateLimitError", retryAfter: 30 }
+ * }
  * ```
  *
  * @see {@link ExcludeReason}
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export type NarrowReason<E, K extends string> = E extends {
@@ -1014,7 +1066,7 @@ export type NarrowReason<E, K extends string> = E extends {
  *
  * **Example** (Omitting a reason variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -1023,6 +1075,11 @@ export type NarrowReason<E, K extends string> = E extends {
  *
  * type Result = Types.OmitReason<ApiError, "RateLimitError">
  * // ApiError & { readonly reason: { readonly _tag: "QuotaError"; readonly limit: number } }
+ *
+ * const witness: Result = {
+ *   _tag: "ApiError",
+ *   reason: { _tag: "QuotaError", limit: 10 }
+ * }
  * ```
  *
  * @see {@link NarrowReason}
@@ -1030,7 +1087,7 @@ export type NarrowReason<E, K extends string> = E extends {
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export type OmitReason<E, K extends string> = E extends {
@@ -1055,7 +1112,7 @@ export type OmitReason<E, K extends string> = E extends {
  *
  * **Example** (Excluding a reason variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -1064,13 +1121,15 @@ export type OmitReason<E, K extends string> = E extends {
  *
  * type Result = Types.ExcludeReason<ApiError, "RateLimitError">
  * // { readonly _tag: "QuotaError"; readonly limit: number }
+ *
+ * const witness: Result = { _tag: "QuotaError", limit: 10 }
  * ```
  *
  * @see {@link ExtractReason}
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export type ExcludeReason<E, K extends string> = E extends {
@@ -1085,7 +1144,7 @@ export type ExcludeReason<E, K extends string> = E extends {
  *
  * Use to derive the keys whose properties must be present on an object type.
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export type RequiredKeys<T> = {