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.
Completion
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
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
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>;
};Completes a request entry with a typed failure.
When to use
Use to report a request-specific typed error while implementing a RequestResolver.
See
failCausefor completing an entry with a fullCausecompletefor completing an entry with an existingExitcompleteEffectfor completing an entry from an effect resultsucceedfor 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>;
};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
failfor completing an entry with a typed error valuecompletefor completing an entry with an existingExitcompleteEffectfor completing an entry from an effect resultsucceedfor 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>;
};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
completefor completing an entry with a prebuiltExitcompleteEffectfor completing an entry from an effect resultfailfor completing an entry with a typed failurefailCausefor completing an entry with a failureCause
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
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>;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>;Creates a constructor function for a specific Request type.
Signature
declare function of<R extends Request<any, any, any>>(): Constructor<R>;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">;TaggedClass
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;
};Guards
Models
Constructor interface
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;
}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;
}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> {}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
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
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
Signature
type Any = Request<any, any, any>;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;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;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;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;
Completes a request entry with the provided result.
When to use
Use when you need to finish a
Request.Entrywith a prebuilt finalExitresult.See
completeEffectfor completing an entry from an effect that may succeed or failsucceedfor completing an entry with a successful valuefailfor completing an entry with a typed failurefailCausefor completing an entry with a failureCause