effect 4.0.0-beta.3 → 4.0.0-beta.30

package/src/Types.ts

@@ -205,7 +205,7 @@ export type ExcludeTag<E, K extends string> = Exclude<E, { readonly _tag: K }>
  * @category types
  * @since 2.0.0
  */
-export type ExtractTag<E, K extends string> = Extract<E, { readonly _tag: K }>
+export type ExtractTag<E, K extends string> = E extends { readonly _tag: infer T } ? K extends T ? E : never : never
 
 /**
  * Transforms a union type into an intersection type.
@@ -708,26 +708,13 @@ export declare namespace Contravariant {
 }
 
 /**
- * Conditional type that checks if `S` is an empty object type.
+ * Conditional type that returns `void` if `S` is an empty object type,
+ * otherwise returns `S`.
  *
- * - Returns `onTrue` if `S` matches `{}` (i.e., has no required properties).
- * - Returns `onFalse` otherwise.
- * - Useful for branching type-level logic based on whether a service/context
- *   type has requirements.
- *
- * **Example** (Branching on empty record)
- *
- * ```ts
- * import type { Types } from "effect"
- *
- * type A = Types.MatchRecord<{}, "empty", "not empty"> // "empty"
- * type B = Types.MatchRecord<{ a: number }, "empty", "not empty"> // "not empty"
- * ```
- *
- * @since 2.0.0
+ * @since 4.0.0
  * @category types
  */
-export type MatchRecord<S, onTrue, onFalse> = {} extends S ? onTrue : onFalse
+export type VoidIfEmpty<S> = keyof S extends never ? void : S
 
 /**
  * Excludes function types from a union, keeping only non-function members.
@@ -914,7 +901,74 @@ export type ReasonTags<E> = E extends { readonly reason: { readonly _tag: string
  * @category types
  */
 export type ExtractReason<E, K extends string> = E extends { readonly reason: infer R }
-  ? Extract<R, { readonly _tag: K }>
+  ? R extends { readonly _tag: infer T } ? K extends T ? R : never
+  : never
+  : never
+
+/**
+ * Narrows a specific reason variant by its `_tag` from an error's `reason`
+ * field.
+ *
+ * - Use to narrow down to a single reason variant from a nested error type.
+ * - Returns `never` if `E` has no matching reason variant.
+ *
+ * **Example** (Narrowing a reason variant)
+ *
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
+ * type QuotaError = { readonly _tag: "QuotaError"; readonly limit: number }
+ * type ApiError = { readonly _tag: "ApiError"; readonly reason: RateLimitError | QuotaError }
+ *
+ * type Result = Types.NarrowReason<ApiError, "RateLimitError">
+ * // ApiError & { readonly reason: { readonly _tag: "RateLimitError"; readonly retryAfter: number } }
+ * ```
+ *
+ * @see {@link ExcludeReason}
+ * @see {@link ReasonOf}
+ * @see {@link ReasonTags}
+ *
+ * @since 4.0.0
+ * @category types
+ */
+export type NarrowReason<E, K extends string> = E extends { readonly reason: infer R }
+  ? R extends { readonly _tag: infer T } ? K extends T ? E & { readonly reason: R } : never
+  : never
+  : never
+
+/**
+ * Narrows an error's `reason` field to exclude a specific reason variant by
+ * its `_tag`.
+ *
+ * - Use to narrow the error to only the remaining reason variants after
+ *   excluding the matched one.
+ * - Returns `never` if `E` has no `reason` field or no remaining variants.
+ *
+ * **Example** (Omitting a reason variant)
+ *
+ * ```ts
+ * import type { Types } from "effect"
+ *
+ * type RateLimitError = { readonly _tag: "RateLimitError"; readonly retryAfter: number }
+ * type QuotaError = { readonly _tag: "QuotaError"; readonly limit: number }
+ * type ApiError = { readonly _tag: "ApiError"; readonly reason: RateLimitError | QuotaError }
+ *
+ * type Result = Types.OmitReason<ApiError, "RateLimitError">
+ * // ApiError & { readonly reason: { readonly _tag: "QuotaError"; readonly limit: number } }
+ * ```
+ *
+ * @see {@link NarrowReason}
+ * @see {@link ExcludeReason}
+ * @see {@link ReasonOf}
+ * @see {@link ReasonTags}
+ *
+ * @since 4.0.0
+ * @category types
+ */
+export type OmitReason<E, K extends string> = E extends { readonly reason: infer R }
+  ? R extends { readonly _tag: infer T } ? K extends T ? never : E & { readonly reason: R }
+  : never
   : never
 
 /**

package/src/Utils.ts

@@ -1,65 +1,102 @@
 /**
+ * Internal utilities for the Effect ecosystem's generator-based syntax and
+ * higher-kinded type machinery.
+ *
+ * ## Mental model
+ *
+ * - **SingleShotGen** — an `IterableIterator` wrapper that yields its value
+ *   exactly once. Used internally by `[Symbol.iterator]()` on Effect, Option,
+ *   Result, and other yieldable types so they work inside generator functions.
+ * - **Gen** — a type-level signature for generator-based monadic composition
+ *   (`gen` functions). Parametric over any `TypeLambda` so each module
+ *   (Effect, Option, Result, ...) can expose its own `gen` with correct types.
+ * - **Variance** — a type-level marker that encodes the variance (covariant,
+ *   contravariant, invariant) of a `TypeLambda`'s type parameters.
+ *   Used by {@link Gen} for type inference.
+ *
+ * ## Common tasks
+ *
+ * - Make a type yieldable in generators -> implement `[Symbol.iterator]()` returning a {@link SingleShotGen}
+ * - Define a generator-based API for a new TypeLambda -> type it as {@link Gen}`<MyTypeLambda>`
+ * - Encode variance for a higher-kinded type -> use {@link Variance}
+ *
+ * ## Gotchas
+ *
+ * - {@link SingleShotGen} yields its value only on the first `.next()` call.
+ *   Calling `.next()` again returns `{ done: true }`. Iterating the same
+ *   instance twice will skip the value on the second pass; call
+ *   `[Symbol.iterator]()` to get a fresh iterator.
+ * - {@link Gen} and {@link Variance} are pure type-level constructs — they
+ *   have no runtime representation.
+ *
+ * ## Quickstart
+ *
+ * **Example** (Using SingleShotGen to make a type yieldable)
+ *
+ * ```ts
+ * import { Utils } from "effect"
+ *
+ * class MyWrapper<A> {
+ *   constructor(readonly value: A) {}
+ *   [Symbol.iterator]() {
+ *     return new Utils.SingleShotGen<MyWrapper<A>, A>(this)
+ *   }
+ * }
+ *
+ * const w = new MyWrapper(42)
+ * const iter = w[Symbol.iterator]()
+ * console.log(iter.next(undefined as any))
+ * // { value: MyWrapper { value: 42 }, done: false }
+ * console.log(iter.next(42))
+ * // { value: 42, done: true }
+ * ```
+ *
+ * @see {@link SingleShotGen}
+ * @see {@link Gen}
+ * @see {@link Variance}
+ *
  * @since 2.0.0
  */
-import { identity } from "./Function.ts"
 import type { Kind, TypeLambda } from "./HKT.ts"
-import { isObject } from "./Predicate.ts"
 import type * as Types from "./Types.ts"
 
 /**
- * @since 2.0.0
- */
-const GenKindTypeId = "~effect/Utils/GenKind"
-
-/**
- * @category models
- * @since 2.0.0
- */
-export interface GenKind<F extends TypeLambda, R, O, E, A> extends Variance<F, R, O, E> {
-  readonly value: Kind<F, R, O, E, A>
-
-  [Symbol.iterator](): IterableIterator<GenKind<F, R, O, E, A>, A>
-}
-
-/**
- * @category predicates
- * @since 3.0.6
- */
-export const isGenKind = (u: unknown): u is GenKind<any, any, any, any, any> => isObject(u) && GenKindTypeId in u
-
-class GenKindImpl<F extends TypeLambda, R, O, E, A> implements GenKind<F, R, O, E, A> {
-  readonly value: Kind<F, R, O, E, A>
-
-  constructor(
-    value: Kind<F, R, O, E, A>
-  ) {
-    this.value = value
-  }
-
-  get _F() {
-    return identity
-  }
-
-  get _R() {
-    return (_: R) => _
-  }
-
-  get _O() {
-    return (_: never): O => _
-  }
-
-  get _E() {
-    return (_: never): E => _
-  }
-
-  readonly [GenKindTypeId]: typeof GenKindTypeId = GenKindTypeId;
-
-  [Symbol.iterator](): IterableIterator<GenKind<F, R, O, E, A>, A> {
-    return new SingleShotGen<GenKind<F, R, O, E, A>, A>(this as any)
-  }
-}
-
-/**
+ * An `IterableIterator` that yields its wrapped value exactly once.
+ *
+ * When to use:
+ *
+ * - Implement `[Symbol.iterator]()` on Effect-like types so they can be
+ *   `yield*`-ed inside generator functions (e.g. `Effect.gen`, `Option.gen`).
+ * - You almost never construct this directly — it is created internally by
+ *   yieldable types.
+ *
+ * Behavior:
+ *
+ * - The first call to `next()` returns `{ value: self, done: false }`.
+ * - Every 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.
+ * - Does not mutate the wrapped value.
+ *
+ * **Example** (Yielding a wrapped value in a generator)
+ *
+ * ```ts
+ * import { Utils } from "effect"
+ *
+ * const gen = new Utils.SingleShotGen<string, number>("hello")
+ *
+ * // First call yields the wrapped value
+ * console.log(gen.next(0))
+ * // { value: "hello", done: false }
+ *
+ * // Second call signals completion with the provided value
+ * console.log(gen.next(42))
+ * // { value: 42, done: true }
+ * ```
+ *
+ * @see {@link Gen} — the type-level signature that relies on `SingleShotGen`
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -96,20 +133,29 @@ export class SingleShotGen<T, A> implements IterableIterator<T, A> {
 }
 
 /**
- * @category constructors
- * @since 2.0.0
- */
-export const makeGenKind = <F extends TypeLambda, R, O, E, A>(
-  kind: Kind<F, R, O, E, A>
-): GenKind<F, R, O, E, A> => new GenKindImpl(kind)
-
-/**
- * @example
+ * Type-level marker encoding the variance of a `TypeLambda`'s type
+ * parameters.
+ *
+ * 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.
+ *
+ * Behavior:
+ *
+ * - `F` is invariant (must match exactly).
+ * - `R` is contravariant (input / environment position).
+ * - `O` and `E` are covariant (output / error position).
+ * - Pure type-level construct — no runtime representation.
+ *
+ * **Example** (Declaring variance for a TypeLambda)
+ *
  * ```ts
  * import type { Utils } from "effect"
  * import type * as Option from "effect/Option"
  *
- * // Variance defines the type parameter relationships
  * declare const variance: Utils.Variance<
  *   Option.OptionTypeLambda,
  *   never,
@@ -118,11 +164,12 @@ export const makeGenKind = <F extends TypeLambda, R, O, E, A>(
  * >
  * ```
  *
+ * @see {@link Gen} — uses `Variance` for type parameter inference
+ *
  * @category models
  * @since 2.0.0
  */
 export interface Variance<in out F extends TypeLambda, in R, out O, out E> {
-  readonly [GenKindTypeId]: typeof GenKindTypeId
   readonly _F: Types.Invariant<F>
   readonly _R: Types.Contravariant<R>
   readonly _O: Types.Covariant<O>
@@ -130,14 +177,34 @@ export interface Variance<in out F extends TypeLambda, in R, out O, out E> {
 }
 
 /**
- * @example
+ * Type-level signature for generator-based monadic composition over any
+ * `TypeLambda`.
+ *
+ * When to use:
+ *
+ * - Type the `gen` function of a module that supports generator syntax
+ *   (e.g. `Option.gen`, `Result.gen`, `Effect.gen`).
+ * - Accepts either `(body)` or `(self, body)` where `body` is a generator
+ *   function. The `self` overload binds `this` inside the generator.
+ *
+ * Behavior:
+ *
+ * - Pure type alias — no runtime behavior.
+ * - Infers `R`, `O`, `E` from the yielded values via {@link Variance} or
+ *   `Kind` constraints.
+ * - The generator's return type `A` becomes the output's `A` parameter.
+ *
+ * **Example** (Typing a gen function for Option)
+ *
  * ```ts
  * import type { Option, Utils } from "effect"
  *
- * // Gen enables generator-based syntax for any TypeLambda
  * 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
+ *
  * @category models
  * @since 2.0.0
  */
@@ -168,22 +235,7 @@ export type Gen<F extends TypeLambda> = <
   A
 >
 
-/**
- * @example
- * ```ts
- * import type { Utils } from "effect"
- *
- * const value1: Utils.OptionalNumber = 42
- * const value2: Utils.OptionalNumber = null
- * const value3: Utils.OptionalNumber = undefined
- * ```
- *
- * @category models
- * @since 2.0.0
- */
-export type OptionalNumber = number | null | undefined
-
-const InternalTypeId = "~effect/Effect/internal"
+const InternalTypeId = "~effect/Utils/internal"
 
 const standard = {
   [InternalTypeId]: <A>(body: () => A) => {
@@ -203,31 +255,5 @@ const forced = {
 
 const isNotOptimizedAway = standard[InternalTypeId](() => new Error().stack)?.includes(InternalTypeId) === true
 
-/**
- * @since 3.2.2
- * @status experimental
- * @category tracing
- */
+/** @internal */
 export const internalCall = isNotOptimizedAway ? standard[InternalTypeId] : forced[InternalTypeId]
-
-const genConstructor = (function*() {}).constructor
-
-/**
- * @example
- * ```ts
- * import { Utils } from "effect"
- *
- * function* generatorFn() {
- *   yield 1
- *   yield 2
- * }
- *
- * console.log(Utils.isGeneratorFunction(generatorFn)) // true
- * console.log(Utils.isGeneratorFunction(() => {})) // false
- * ```
- *
- * @category predicates
- * @since 3.11.0
- */
-export const isGeneratorFunction = (u: unknown): u is (...args: Array<any>) => Generator<any, any, any> =>
-  isObject(u) && u.constructor === genConstructor