Request

Typed request values for data loading with Effect.request.

A request describes one logical piece of work without performing it. It records the success type, typed error, service requirements, and fields a resolver needs to complete the request. Requests are paired with RequestResolver, which performs backend-specific loading and completes each pending request entry with a success, failure, cause, exit, or effect.

21 exports Added in v2.0.0 Source

Completion

complete

Added in v2.0.0 Source

Completes a request entry with the provided result.

When to use

Use when you need to finish a Request.Entry with a prebuilt final Exit result.

See

completeEffect for completing an entry from an effect that may succeed or fail
succeed for completing an entry with a successful value
fail for completing an entry with a typed failure
failCause for completing an entry with a failure Cause

Signature

declare const complete: {
  <A extends Any>(result: Result<A>): (self: Entry<A>) => Effect<void>;
  <A extends Any>(self: Entry<A>, result: Result<A>): Effect<void>;
}

completeEffect

Added in v2.0.0 Source

Completes a request entry with the result of an effect.

When to use

Use to finish a Request.Entry by running an effect whose success or typed failure should become the request result.

Details

If the effect succeeds, the entry is completed successfully with its value. If the effect fails, the entry is completed with that failure.

Gotchas

The returned effect itself does not fail with the request error.

See

complete for completing an entry with a prebuilt Exit
succeed for completing an entry with a successful value
fail for completing an entry with a typed failure
failCause for completing an entry with a failure Cause

Signature

declare const completeEffect: {
  <A extends Any, R>(effect: Effect<Success<A>, Error<A>, R>): (self: Entry<A>) => Effect<void, never, R>;
  <A extends Any, R>(self: Entry<A>, effect: Effect<Success<A>, Error<A>, R>): Effect<void, never, R>;
}

fail

Added in v2.0.0 Source

Completes a request entry with a typed failure.

When to use

Use to report a request-specific typed error while implementing a RequestResolver.

See

failCause for completing an entry with a full Cause
complete for completing an entry with an existing Exit
completeEffect for completing an entry from an effect result
succeed for completing an entry successfully

Signature

declare const fail: {
  <A extends Any>(error: Error<A>): (self: Entry<A>) => Effect<void>;
  <A extends Any>(self: Entry<A>, error: Error<A>): Effect<void>;
}

failCause

Added in v2.0.0 Source

Completes a request entry with a failure Cause.

When to use

Use when you need a RequestResolver to complete an entry with structured cause information rather than only the request's typed error value.

See

fail for completing an entry with a typed error value
complete for completing an entry with an existing Exit
completeEffect for completing an entry from an effect result
succeed for completing an entry successfully

Signature

declare const failCause: {
  <A extends Any>(cause: Cause<Error<A>>): (self: Entry<A>) => Effect<void>;
  <A extends Any>(self: Entry<A>, cause: Cause<Error<A>>): Effect<void>;
}

succeed

Added in v2.0.0 Source

Completes a request entry successfully with the supplied value.

When to use

Use when you need to finish a Request.Entry with a successful request value.

See

complete for completing an entry with a prebuilt Exit
completeEffect for completing an entry from an effect result
fail for completing an entry with a typed failure
failCause for completing an entry with a failure Cause

Signature

declare const succeed: {
  <A extends Any>(value: Success<A>): (self: Entry<A>) => Effect<void>;
  <A extends Any>(self: Entry<A>, value: Success<A>): Effect<void>;
}

Constructors

Class

Added in v2.0.0 Source

Defines request types with TypeScript classes.

Details

Subclasses pass their data fields to super, and instances are marked as Request values while retaining the provided readonly fields.

Signature

declare const Class: <A extends Record<string, any>, Success, Error = never, Context = never>(args: Types.Equals<Omit<A, keyof Request<unknown, unknown>>, {}> extends true ? void : { [P in keyof A]: A[P] }) => Request<Success, Error, Context> & Readonly<A>

Example

(Defining request classes)

import { Request } from "effect"

class GetUser extends Request.Class<{ id: number }, string, Error> {
  constructor(readonly id: number) {
    super({ id })
  }
}

const getUserRequest = new GetUser(123)
getUserRequest.id // => 123

makeEntry

Added in v2.0.0 Source

Creates a Request.Entry from its component fields.

Details

This is a low-level helper for request runtime and resolver infrastructure; most application code receives entries from a RequestResolver instead of constructing them directly.

Signature

declare function makeEntry<R>(options: {
  readonly completeUnsafe: (exit: Exit<[R] extends [Request<_A, _E, _R>] ? _A : never, [R] extends [Request<_A, _E, _R>] ? _E : never>) => void;
  readonly context: Context<[R] extends [Request<_A, _E, _R>] ? _R : never>;
  readonly request: R;
  readonly uninterruptible: boolean;
}): Entry<R>

of

Added in v2.0.0 Source

Creates a constructor function for a specific Request type.

Signature

declare function of<R extends Request<any, any, any>>(): Constructor<R>

Example

(Creating untagged request constructors)

import { Request } from "effect"

declare const UserProfile: unique symbol
declare const ProfileError: unique symbol
type UserProfile = typeof UserProfile
type ProfileError = typeof ProfileError

interface GetUserProfile extends Request.Request<UserProfile, ProfileError> {
  readonly id: string
  readonly includeSettings: boolean
}

const GetUserProfile = Request.of<GetUserProfile>()

const request = GetUserProfile({
  id: "user-123",
  includeSettings: true
})

request.id // => "user-123"
request.includeSettings // => true

tagged

Added in v2.0.0 Source

Creates a constructor function for a tagged Request type. The tag is automatically added to the request, making it useful for discriminated unions.

Signature

declare function tagged<R extends Request<any, any, any> & {
  _tag: string;
}>(tag: R["_tag"]): Constructor<R, "_tag">

Example

(Creating tagged request constructors)

import { Request } from "effect"

declare const User: unique symbol
declare const UserNotFound: unique symbol
declare const Post: unique symbol
declare const PostNotFound: unique symbol
type User = typeof User
type UserNotFound = typeof UserNotFound
type Post = typeof Post
type PostNotFound = typeof PostNotFound

interface GetUser extends Request.Request<User, UserNotFound> {
  readonly _tag: "GetUser"
  readonly id: string
}

interface GetPost extends Request.Request<Post, PostNotFound> {
  readonly _tag: "GetPost"
  readonly id: string
}

const GetUser = Request.tagged<GetUser>("GetUser")
const GetPost = Request.tagged<GetPost>("GetPost")

const userRequest = GetUser({ id: "user-123" })
const postRequest = GetPost({ id: "post-456" })

// _tag is automatically set
Array.of(userRequest._tag, postRequest._tag) // => ["GetUser", "GetPost"]

TaggedClass

Added in v2.0.0 Source

Creates a class constructor for requests with a fixed _tag field.

Details

Use this when defining class-based request types that should participate in tagged unions or tag-based request resolvers.

Signature

declare function TaggedClass<Tag extends string>(tag: Tag): <A extends Record<string, any>, Success, Error = never, Services = never>(args: Equals<Omit<A, "~effect/Request">, {}> extends true ? void : { [P in string | number | symbol]: A[P] }) => Request<Success, Error, Services> & Readonly<A> & {
  readonly _tag: Tag;
}

Example

(Defining tagged request classes)

import { Request } from "effect"

class GetUserById
  extends Request.TaggedClass("GetUserById")<{ id: number }, string, Error>
{}

const request = new GetUserById({ id: 123 })

request._tag // => "GetUserById"
request.id // => 123

Guards

isRequest

Added in v2.0.0 Source

Checks whether a value is a Request.

Signature

declare function isRequest(u: unknown): u is Request<unknown, unknown, unknown>

Example

(Checking request values)

import { Request } from "effect"

declare const User: unique symbol
declare const UserNotFound: unique symbol
type User = typeof User
type UserNotFound = typeof UserNotFound

interface GetUser extends Request.Request<User, UserNotFound> {
  readonly _tag: "GetUser"
  readonly id: string
}
const GetUser = Request.tagged<GetUser>("GetUser")

const request = GetUser({ id: "123" })
Request.isRequest(request) // => true
Request.isRequest("not a request") // => false

Models

Constructor interface

Added in v2.0.0 Source

The constructor type returned by Request.of and Request.tagged.

Details

The constructor accepts the request's data fields, excluding request variance fields and any fields already supplied by the constructor such as _tag, and returns a value of the request type.

Signature

interface Constructor<R extends Request<any, any, any>, T extends keyof R = never> {
  (args: VoidIfEmpty<Simplify<Omit<R, "~effect/Request" | T>>>): R;
}

Example

(Using generated request constructors)

import { Request } from "effect"

interface GetUser extends Request.Request<string, Error> {
  readonly _tag: "GetUser"
  readonly id: number
}

// Constructor type is used internally by Request.of() and Request.tagged()
const GetUser = Request.tagged<GetUser>("GetUser")
const request = GetUser({ id: 123 })

request._tag // => "GetUser"
request.id // => 123

Entry interface

Added in v2.0.0 Source

A pending request handed to a RequestResolver.

Details

An entry contains the original request, the fiber context needed to run it, an uninterruptible flag used by batching and caching internals, and the completeUnsafe callback used by resolvers to supply the final Exit.

Signature

interface Entry<out R> {
  readonly context: Context<[R] extends [Request<_A, _E, _R>] ? _R : never>;
  readonly request: R;
  uninterruptible: boolean;
  completeUnsafe(exit: Exit<[R] extends [Request<_A, _E, _R>] ? _A : never, [R] extends [Request<_A, _E, _R>] ? _E : never>): void;
}

Request interface

Added in v2.0.0 Source

A Request<A, E, R> is a request from a data source for a value of type A that may fail with an E and have requirements of type R.

Signature

interface Request<out A, out E = never, out R = never> extends Variance<A, E, R> {}

Example

(Defining typed requests)

import type { Request } from "effect"

// Define a request that fetches a user by ID
interface GetUser extends Request.Request<string, Error> {
  readonly _tag: "GetUser"
  readonly id: number
}

// Define a request that fetches all users
interface GetAllUsers extends Request.Request<ReadonlyArray<string>, Error> {
  readonly _tag: "GetAllUsers"
}

Variance interface

Added in v2.0.0 Source

Variance marker carried by every Request.

Details

This marker preserves the success, error, and service requirement types for Effect's type-level machinery. Users normally get it by extending Request.

Signature

interface Variance<out A, out E, out R> {
  readonly "~effect/Request": {
    readonly _A: Covariant<A>;
    readonly _E: Covariant<E>;
    readonly _R: Covariant<R>;
  };
}

Prototypes

RequestPrototype

Added in v4.0.0 Source

Prototype used by Effect's request constructors.

Details

This low-level value provides the structural request marker for values created by Request.of, Request.tagged, Request.Class, and Request.TaggedClass. Most users should use those constructors instead of interacting with the prototype directly.

Signature

declare const RequestPrototype: Request<any, any, any>

Utility Types

Any type

Added in v4.0.0 Source

Alias for any Request, regardless of its success, error, or service requirements.

When to use

Use as a generic constraint for APIs that accept any request while preserving each concrete request's success, error, and service types.

See

Request for the request interface
Success for extracting a request's success type
Error for extracting a request's error type
Services for extracting a request's service requirements
Result for the exit type produced by completing a request

Signature

type Any = Request<any, any, any>

Error type

Added in v2.0.0 Source

A utility type to extract the error type from a Request.

Signature

type Error<T extends Request<any, any, any>> = [T] extends [Request<infer _A, infer _E, infer _R>] ? _E : never

Example

(Extracting a request error type)

import type { Request } from "effect"

interface GetUser extends Request.Request<string, Error> {
  readonly id: number
}

// Extract the error type from a Request using the utility
type UserError = Request.Error<GetUser> // Error

Result type

Added in v2.0.0 Source

A utility type to extract the result type from a Request.

Signature

type Result<T extends Request<any, any, any>> = T extends Request<infer A, infer E, infer _R> ? Exit.Exit<A, E> : never

Example

(Extracting a request result type)

import type { Request } from "effect"

interface GetUser extends Request.Request<string, Error> {
  readonly _tag: "GetUser"
  readonly id: number
}

// Extract the result type from a Request using the utility
type UserResult = Request.Result<GetUser> // Exit.Exit<string, Error>

Services type

Added in v4.0.0 Source

A utility type to extract the requirements type from a Request.

Signature

type Services<T extends Request<any, any, any>> = [T] extends [Request<infer _A, infer _E, infer _R>] ? _R : never

Success type

Added in v2.0.0 Source

A utility type to extract the value type from a Request.

Signature

type Success<T extends Request<any, any, any>> = [T] extends [Request<infer _A, infer _E, infer _R>] ? _A : never

Example

(Extracting a request success type)

import type { Request } from "effect"

interface GetUser extends Request.Request<string, Error> {
  readonly _tag: "GetUser"
  readonly id: number
}

// Extract the success type from a Request using the utility
type UserSuccess = Request.Success<GetUser> // string