effect 4.0.0-beta.98 → 4.0.0-rc.108

package/src/Types.ts

@@ -10,7 +10,7 @@
  */
 
 /**
- * @category tuples
+ * @category utility types
  * @since 2.0.0
  */
 type TupleOf_<T, N extends number, R extends Array<unknown>> = `${N}` extends `-${number}` ? never
@@ -33,7 +33,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
@@ -48,7 +48,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
@@ -68,7 +68,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
@@ -81,7 +81,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>]
@@ -99,7 +99,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 =
@@ -109,12 +109,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 { readonly _tag: string } ? E["_tag"] : never
@@ -133,7 +135,7 @@ export type Tags<E> = E extends { readonly _tag: string } ? E["_tag"] : never
  *
  * **Example** (Removing a variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type MyError =
@@ -143,12 +145,14 @@ export type Tags<E> = E extends { readonly _tag: string } ? E["_tag"] : never
  *
  * 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, { readonly _tag: K }>
@@ -167,7 +171,7 @@ export type ExcludeTag<E, K extends string> = Exclude<E, { readonly _tag: K }>
  *
  * **Example** (Extracting a variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type MyError =
@@ -176,12 +180,14 @@ export type ExcludeTag<E, K extends string> = Exclude<E, { readonly _tag: K }>
  *
  * 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 { readonly _tag: infer T } ? K extends T ? E : never : never
@@ -203,17 +209,19 @@ export type ExtractTag<E, K extends string> = E extends { readonly _tag: infer T
  *
  * **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
@@ -233,18 +241,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> = {
@@ -266,7 +276,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
@@ -276,7 +286,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 <
@@ -297,7 +307,7 @@ export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <
  *
  * **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"
@@ -306,7 +316,7 @@ export type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <
  *
  * @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
@@ -326,14 +336,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
@@ -354,7 +364,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<
@@ -362,12 +372,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>
@@ -386,7 +398,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<
@@ -394,12 +406,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<
@@ -421,23 +435,21 @@ export type MergeRight<Target, Source> = Simplify<
  *
  * - `number` — run at most N effects concurrently.
  * - `"unbounded"` — run all effects concurrently with no limit.
- * - `"inherit"` — inherit the concurrency from the surrounding context.
  *
  * **Example** (Setting concurrency values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * const sequential: Types.Concurrency = 1
  * const limited: Types.Concurrency = 5
  * const unbounded: Types.Concurrency = "unbounded"
- * const inherit: Types.Concurrency = "inherit"
  * ```
  *
  * @category models
  * @since 2.0.0
  */
-export type Concurrency = number | "unbounded" | "inherit"
+export type Concurrency = number | "unbounded"
 
 /**
  * Removes `readonly` from all properties of `T`. Supports arrays, tuples,
@@ -453,7 +465,7 @@ export type Concurrency = number | "unbounded" | "inherit"
  *
  * **Example** (Converting shallowly to mutable types)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type Obj = Types.Mutable<{
@@ -468,11 +480,14 @@ export type Concurrency = number | "unbounded" | "inherit"
  *
  * 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> = {
@@ -494,7 +509,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<{
@@ -502,11 +517,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>>
@@ -529,16 +547,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]
@@ -559,20 +579,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
@@ -596,16 +618,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
    */
   export type Type<A> = A extends Invariant<infer U> ? U : never
@@ -627,20 +651,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
@@ -664,16 +690,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
    */
   export type Type<A> = A extends Covariant<infer U> ? U : never
@@ -695,20 +723,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
@@ -732,16 +765,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
    */
   export type Type<A> = A extends Contravariant<infer U> ? U : never
@@ -755,7 +790,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
@@ -773,14 +808,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
@@ -798,7 +835,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 }
@@ -806,9 +843,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>>
@@ -828,7 +867,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 {
@@ -850,7 +889,7 @@ export interface unassigned {
  *
  * @see {@link unassigned}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export interface unhandled {
@@ -873,7 +912,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
@@ -882,7 +921,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
@@ -901,7 +940,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 }
@@ -910,13 +949,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 { readonly reason: infer R } ? R : never
@@ -936,7 +977,7 @@ export type ReasonOf<E> = E extends { readonly reason: infer R } ? R : never
  *
  * **Example** (Getting reason tags)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -945,12 +986,14 @@ export type ReasonOf<E> = E extends { readonly reason: infer R } ? R : never
  *
  * 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 { readonly reason: { readonly _tag: string } } ? E["reason"]["_tag"]
@@ -971,7 +1014,7 @@ export type ReasonTags<E> = E extends { readonly reason: { readonly _tag: string
  *
  * **Example** (Extracting a reason variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -980,13 +1023,15 @@ export type ReasonTags<E> = E extends { readonly reason: { readonly _tag: string
  *
  * 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 { readonly reason: infer R }
@@ -1009,7 +1054,7 @@ export type ExtractReason<E, K extends string> = E extends { readonly reason: in
  *
  * **Example** (Narrowing a reason variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -1018,13 +1063,18 @@ export type ExtractReason<E, K extends string> = E extends { readonly reason: in
  *
  * 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 { readonly reason: infer R }
@@ -1047,7 +1097,7 @@ export type NarrowReason<E, K extends string> = E extends { readonly reason: inf
  *
  * **Example** (Omitting a reason variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -1056,6 +1106,11 @@ export type NarrowReason<E, K extends string> = E extends { readonly reason: inf
  *
  * 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}
@@ -1063,7 +1118,7 @@ export type NarrowReason<E, K extends string> = E extends { readonly reason: inf
  * @see {@link ReasonOf}
  * @see {@link ReasonTags}
  *
- * @category types
+ * @category utility types
  * @since 4.0.0
  */
 export type OmitReason<E, K extends string> = E extends { readonly reason: infer R }
@@ -1086,7 +1141,7 @@ export type OmitReason<E, K extends string> = E extends { readonly reason: infer
  *
  * **Example** (Excluding a reason variant)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import type { Types } from "effect"
  *
  * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
@@ -1095,13 +1150,15 @@ export type OmitReason<E, K extends string> = E extends { readonly reason: infer
  *
  * 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 { readonly reason: infer R }
@@ -1115,7 +1172,7 @@ export type ExcludeReason<E, K extends string> = E extends { readonly reason: in
  *
  * 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> = { [K in keyof T]-?: {} extends Pick<T, K> ? never : K }[keyof T]