Skip to content

Pull

Models one low-level pull step for stream-like consumers.

A Pull<A, E, Done, R> is an Effect that can produce one A, fail with an ordinary error E, or signal end-of-input with Cause.Done<Done>. The separate done signal lets low-level consumers distinguish normal completion from failure. This module includes type extractors and helpers for detecting, filtering, catching, converting, and matching done signals separately from ordinary failures.

15 exports Added in v4.0.0 Source

Converting

doneExitFromCause

Added in v4.0.0 Source

Converts a Cause into an Exit, treating Cause.Done as successful completion.

When to use

Use to produce an Exit for finalizing a low-level pull workflow when a Cause.Done signal should be treated as success and any remaining cause should fail.

Details

If the cause contains a done value, that leftover becomes the successful value. Otherwise the non-done cause becomes the failure cause.

See

  • filterDone for extracting the done signal without converting the cause to an Exit
  • matchEffect for handling Pull success, failure, and done outcomes directly

Signature

declare function doneExitFromCause<E>(cause: Cause<E>): Exit<Extract<E>, Exclude<E, Done<any>>>;

Error Handling

catchDone

Added in v4.0.0 Source

Handles Cause.Done failures in an effect while leaving ordinary failures in the error channel.

When to use

Use to recover from a Cause.Done completion signal in an effect, such as turning a pull leftover value into a successful recovery effect while preserving ordinary failures.

Details

The handler receives the done leftover value and may recover with a new effect. Non-done errors are preserved.

See

  • matchEffect for handling success, ordinary failure, and done outcomes explicitly
  • filterDoneLeftover for extracting a done leftover from an existing Cause

Signature

declare const catchDone: {
  <E, A2, E2, R2>(
    f: (leftover: Extract<E>) => Effect<A2, E2, R2>,
  ): <A, R>(self: Effect<A, E, R>) => Effect<A2 | A, E2 | Exclude<E, Done<any>>, R2 | R>;
  <A, R, E, A2, E2, R2>(
    self: Effect<A, E, R>,
    f: (leftover: Extract<E>) => Effect<A2, E2, R2>,
  ): Effect<A | A2, E2 | Exclude<E, Done<any>>, R | R2>;
};

Filtering

filterDone

Added in v4.0.0 Source

Finds a Cause.Done failure in a Cause.

When to use

Use to separate Cause.Done completion from ordinary causes while preserving the typed done value.

Details

Returns a successful Result with the Cause.Done value when one is present, otherwise returns a failed Result containing the non-done cause.

Signature

declare const filterDone: <E>(
  input: Cause.Cause<E>,
) => Result.Result<Cause.Done.Only<E>, Cause.Cause<ExcludeDone<E>>>;

filterDoneLeftover

Added in v4.0.0 Source

Filters a Cause to extract the leftover value from done errors.

When to use

Use to extract only the leftover value carried by a Cause.Done completion signal.

Signature

declare const filterDoneLeftover: <E>(
  cause: Cause.Cause<E>,
) => Result.Result<Cause.Done.Extract<E>, Cause.Cause<ExcludeDone<E>>>;

filterDoneVoid

Added in v4.0.0 Source

Finds a Cause.Done failure in a cause whose done value is not used.

When to use

Use to detect Cause.Done completion in a Cause when the completion value is not part of the downstream logic.

Details

Returns a successful Result with the done marker when present, otherwise returns a failed Result with the non-done cause.

See

  • filterDone for preserving the typed Cause.Done value when the done payload matters
  • filterDoneLeftover for extracting only the done leftover value
  • filterNoDone for the inverse filter that succeeds only when no done failure is present

Signature

declare const filterDoneVoid: <E extends Cause.Done>(
  input: Cause.Cause<E>,
) => Result.Result<Cause.Done, Cause.Cause<Exclude<E, Cause.Done>>>;

filterNoDone

Added in v4.0.0 Source

Keeps a Cause only when it contains no Cause.Done failures.

When to use

Use to select ordinary failure causes for handling while leaving Cause.Done completion causes outside that handler.

Details

Returns a successful Result with the cause when every failure is non-done; otherwise returns a failed Result with the original cause.

See

Signature

declare const filterNoDone: <E>(
  input: Cause.Cause<E>,
) => Result.Result<Cause.Cause<ExcludeDone<E>>, Cause.Cause<E>>;

Guards

isDoneFailure

Added in v4.0.0 Source

Checks whether a Cause.Reason is a Fail reason whose error is a Cause.Done signal.

When to use

Use when you need to identify done completion reasons while traversing cause.reasons, before handling ordinary failures.

See

  • isDoneCause for checking an entire Cause for any done reason
  • filterDone for extracting the Cause.Done value from a Cause

Signature

declare function isDoneFailure<E>(failure: Reason<E>): failure is Fail<E & Done<any>>;

Models

Pull interface

Added in v4.0.0 Source

An effectful pull step that either produces a value, fails with E, or signals completion with Cause.Done<Done>.

When to use

Use to model one low-level pull step when a consumer repeatedly evaluates an effect that may emit a value, fail normally, or signal normal completion through Cause.Done.

Details

Pull represents completion in the error channel so low-level stream consumers can distinguish ordinary failures from end-of-input and carry a leftover value when needed.

Signature

interface Pull<out A, out E = never, out Done = void, out R = never> extends Effect<
  A,
  E | Cause.Done<Done>,
  R
> {}

Pattern Matching

matchEffect

Added in v4.0.0 Source

Pattern matches on a Pull, handling success, failure, and done cases.

When to use

Use to handle all three Pull outcomes with effectful handlers.

Signature

declare const matchEffect: {
  <A, E, L, AS, ES, RS, AF, EF, RF, AH, EH, RH>(options: {
    readonly onDone: (leftover: L) => Effect<AH, EH, RH>;
    readonly onFailure: (failure: Cause.Cause<E>) => Effect<AF, EF, RF>;
    readonly onSuccess: (value: A) => Effect<AS, ES, RS>;
  }): <R>(self: Pull<A, E, L, R>) => Effect<AS | AF | AH, ES | EF | EH, RS | RF | RH | R>;
  <A, E, L, R, AS, ES, RS, AF, EF, RF, AH, EH, RH>(
    self: Pull<A, E, L, R>,
    options: {
      readonly onDone: (leftover: L) => Effect<AH, EH, RH>;
      readonly onFailure: (failure: Cause.Cause<E>) => Effect<AF, EF, RF>;
      readonly onSuccess: (value: A) => Effect<AS, ES, RS>;
    },
  ): Effect<AS | AF | AH, ES | EF | EH, R | RS | RF | RH>;
};

Predicates

isDoneCause

Added in v4.0.0 Source

Checks whether a Cause contains any done errors.

When to use

Use when you need to test whether a pull failure cause represents normal completion and only need a boolean result.

See

Signature

declare function isDoneCause<E>(cause: Cause<E>): boolean;

Utility Types

Error type

Added in v4.0.0 Source

Extracts the error type from a Pull type, excluding Done errors.

When to use

Use to derive only the ordinary failure type from a Pull when declaring wrappers or APIs that handle completion separately.

See

  • Success for extracting the pulled value type instead
  • Leftover for extracting the completion leftover type
  • Services for extracting the required services type instead
  • ExcludeDone for excluding Cause.Done from an error union

Signature

type Error<P> =
  P extends Effect<infer _A, infer _E, infer _R>
    ? _E extends Cause.Done<infer _L>
      ? never
      : _E
    : never;

ExcludeDone type

Added in v4.0.0 Source

Excludes Cause.Done completion signals from an error type union.

When to use

Use to describe the ordinary error type that remains after Cause.Done completion signals have been handled or filtered out of an error union.

See

  • Error for extracting ordinary failures from a Pull
  • Leftover for extracting the completion leftover type

Signature

type ExcludeDone<E> = Exclude<E, Cause.Done<any>>;

Leftover type

Added in v4.0.0 Source

Extracts the leftover type from a Pull type.

When to use

Use to derive the completion leftover type from an existing Pull when declaring reusable type aliases or helper signatures that preserve a pull's done value.

See

  • Success for extracting the pulled value type instead
  • Error for extracting the ordinary failure type, excluding Cause.Done
  • Services for extracting the required services type instead

Signature

type Leftover<P> =
  P extends Effect<infer _A, infer _E, infer _R>
    ? _E extends Cause.Done<infer _L>
      ? _L
      : never
    : never;

Services type

Added in v4.0.0 Source

Extracts the service requirements (context) type from a Pull type.

When to use

Use to derive the context requirements of a generic or inferred Pull without restating its R type parameter.

See

  • Success for extracting the pulled value type instead
  • Error for extracting the ordinary failure type
  • Leftover for extracting the completion leftover type

Signature

type Services<P> = P extends Effect<infer _A, infer _E, infer _R> ? _R : never;

Success type

Added in v4.0.0 Source

Extracts the success type from a Pull type.

When to use

Use to derive the value produced by an existing Pull when declaring reusable type aliases, low-level stream helpers, or function signatures.

See

  • Error for extracting the ordinary failure type
  • Leftover for extracting the completion leftover type
  • Services for extracting the required services type instead

Signature

type Success<P> = P extends Effect<infer _A, infer _E, infer _R> ? _A : never;