Skip to content

Utils

Internal and advanced utilities used by Effect's generator-based syntax and higher-kinded type support. This is not a general-purpose utility module for application code.

SingleShotGen makes an Effect-style value work with yield* inside generator helpers. Variance and Gen provide the type-level signatures used by modules such as Effect, Option, and Result to type their gen APIs.

3 exports Added in v2.0.0 Source

Constructors

SingleShotGen

Added in v2.0.0 Source

Yields its wrapped value exactly once through an IterableIterator.

When to use

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.

Details

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.

See

  • Gen for the type-level signature that relies on SingleShotGen

Signature

declare class SingleShotGen<T, A> implements IterableIterator<T, A> {
  constructor<T, A>(self: T);
  readonly self: T;
  [iterator](): IterableIterator<T, A>;
  next(a: A): IteratorResult<T, A>;
}

Models

Gen type

Added in v2.0.0 Source

Type-level signature for generator-based monadic composition over any TypeLambda.

When to use

Use to type the gen function of a module that supports generator syntax, such as Option.gen, Result.gen, and Effect.gen.

Details

This is a pure type alias with no runtime behavior. It infers R, O, and E from the yielded values via Variance or Kind constraints. The generator's return type A becomes the output's A parameter.

See

  • Variance for encoding the variance used for inference
  • SingleShotGen for the iterator protocol that makes yielding work

Signature

type Gen<F extends TypeLambda> = <
  Self,
  K extends Variance<F, any, any, any> | Kind<F, any, any, any, any>,
  A,
>(
  ...args:
    | [self: Self, body: (this: Self) => Generator<K, A, never>]
    | [body: () => Generator<K, A, never>]
) => Kind<
  F,
  [K] extends [Variance<F, infer R, any, any>]
    ? R
    : [K] extends [Kind<F, infer R, any, any, any>]
      ? R
      : never,
  [K] extends [Variance<F, any, infer O, any>]
    ? O
    : [K] extends [Kind<F, any, infer O, any, any>]
      ? O
      : never,
  [K] extends [Variance<F, any, any, infer E>]
    ? E
    : [K] extends [Kind<F, any, any, infer E, any>]
      ? E
      : never,
  A
>;

Variance interface

Added in v2.0.0 Source

Type-level marker encoding the variance of a TypeLambda's type parameters.

When to use

Use to define variance constraints for a higher-kinded type so that Gen can correctly infer R, O, and E from yielded values.

Details

F is invariant and must match exactly. R is contravariant in the input or environment position. O and E are covariant in the output and error positions. This is a pure type-level construct with no runtime representation.

See

  • Gen for the type-level signature that uses Variance

Signature

interface Variance<in out F extends TypeLambda, in R, out O, out E> {
  readonly _E: Covariant<E>;
  readonly _F: Invariant<F>;
  readonly _O: Covariant<O>;
  readonly _R: Contravariant<R>;
}