<K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(
self: Effect<A, E, R>
) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>
<A, E, R, K extends TagsWithReason<E>>(
self: Effect<A, E, R>,
errorTag: K
): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>Promotes nested reason errors into the Effect error channel, replacing the parent error.
Example (Extracting the reason from a tagged error)
import { Data, Effect } from "effect"
class RateLimitError extends Data.TaggedError("RateLimitError")<{
retryAfter: number
}> {}
class QuotaExceededError extends Data.TaggedError("QuotaExceededError")<{
limit: number
}> {}
class AiError extends Data.TaggedError("AiError")<{
reason: RateLimitError | QuotaExceededError
}> {}
declare const program: Effect.Effect<string, AiError>
// Before: Effect<string, AiError>
// After: Effect<string, RateLimitError | QuotaExceededError>
const unwrapped = program.pipe(Effect.unwrapReason("AiError"))export const const unwrapReason: {
<K extends TagsWithReason<E>, E>(errorTag: K): <
A,
R
>(
self: Effect<A, E, R>
) => Effect<
A,
ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>,
R
>
<A, E, R, K extends TagsWithReason<E>>(
self: Effect<A, E, R>,
errorTag: K
): Effect<
A,
ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>,
R
>
}
Promotes nested reason errors into the Effect error channel, replacing
the parent error.
Example (Extracting the reason from a tagged error)
import { Data, Effect } from "effect"
class RateLimitError extends Data.TaggedError("RateLimitError")<{
retryAfter: number
}> {}
class QuotaExceededError extends Data.TaggedError("QuotaExceededError")<{
limit: number
}> {}
class AiError extends Data.TaggedError("AiError")<{
reason: RateLimitError | QuotaExceededError
}> {}
declare const program: Effect.Effect<string, AiError>
// Before: Effect<string, AiError>
// After: Effect<string, RateLimitError | QuotaExceededError>
const unwrapped = program.pipe(Effect.unwrapReason("AiError"))
unwrapReason: {
<
function (type parameter) K in <K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>K extends type TagsWithReason<E> = {
[T in Tags<E>]: ReasonTags<
ExtractTag<E, T>
> extends never
? never
: T
}[Tags<E>]
Type helper that keeps only error tags whose tagged error contains a tagged reason field.
When to use
Use to constrain custom helpers or overloads to parent error tags whose error
contains a tagged reason.
Details
The mapped type keeps each parent error tag whose extracted tagged error has
at least one reason tag, and removes tags that do not carry tagged reasons.
TagsWithReason<function (type parameter) E in <K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E>,
function (type parameter) E in <K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E
>(
errorTag: K extends TagsWithReason<E>errorTag: function (type parameter) K in <K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>K
): <function (type parameter) A in <A, R>(self: Effect<A, E, R>): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>A, function (type parameter) R in <A, R>(self: Effect<A, E, R>): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>R>(self: Effect<A, E, R>(parameter) self: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) A in <A, R>(self: Effect<A, E, R>): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>A, function (type parameter) E in <K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E, function (type parameter) R in <A, R>(self: Effect<A, E, R>): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>R>) => interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) A in <A, R>(self: Effect<A, E, R>): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>A, type ExcludeTag<E, K extends string> = E extends {
readonly _tag: K;
} ? never : E
Excludes members of a tagged union by their _tag value.
When to use
Use to remove tagged-union members whose _tag matches a specific value in
type-level code.
Details
Non-tagged members of the union are preserved.
Example (Removing a variant)
import type { Types } from "effect"
type MyError =
| { readonly _tag: "NotFound"; readonly id: string }
| { readonly _tag: "Timeout"; readonly ms: number }
| string
type WithoutTimeout = Types.ExcludeTag<MyError, "Timeout">
// { readonly _tag: "NotFound"; readonly id: string } | string
ExcludeTag<function (type parameter) E in <K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E, function (type parameter) K in <K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>K> | type ReasonOf<E> = E extends {
readonly reason: infer R;
} ? R : never
Extracts the reason type from an error that has a reason field.
When to use
Use when an error type stores nested sub-errors in a reason field and you
need that field's full union type as a standalone type.
Details
Returns never if E has no reason field.
Example (Extracting reason types)
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 Reasons = Types.ReasonOf<ApiError>
// RateLimitError | QuotaError
ReasonOf<type ExtractTag<E, K extends string> = E extends {
readonly _tag: infer T;
} ? K extends T ? E : never : never
Extracts a specific member of a tagged union by its _tag value.
When to use
Use to select tagged-union members whose _tag matches a specific value in
type-level code.
Details
Returns never if no member matches the tag.
Example (Extracting a variant)
import type { Types } from "effect"
type MyError =
| { readonly _tag: "NotFound"; readonly id: string }
| { readonly _tag: "Timeout"; readonly ms: number }
type TimeoutError = Types.ExtractTag<MyError, "Timeout">
// { readonly _tag: "Timeout"; readonly ms: number }
ExtractTag<function (type parameter) E in <K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E, function (type parameter) K in <K extends TagsWithReason<E>, E>(errorTag: K): <A, R>(self: Effect<A, E, R>) => Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>K>>, function (type parameter) R in <A, R>(self: Effect<A, E, R>): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>R>
<
function (type parameter) A in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>A,
function (type parameter) E in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E,
function (type parameter) R in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>R,
function (type parameter) K in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>K extends type TagsWithReason<E> = {
[T in Tags<E>]: ReasonTags<
ExtractTag<E, T>
> extends never
? never
: T
}[Tags<E>]
Type helper that keeps only error tags whose tagged error contains a tagged reason field.
When to use
Use to constrain custom helpers or overloads to parent error tags whose error
contains a tagged reason.
Details
The mapped type keeps each parent error tag whose extracted tagged error has
at least one reason tag, and removes tags that do not carry tagged reasons.
TagsWithReason<function (type parameter) E in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E>
>(
self: Effect<A, E, R>(parameter) self: {
pipe: { <A>(this: A): A; <A, B = never>(this: A, ab: (_: A) => B): B; <A, B = never, C = never>(this: A, ab: (_: A) => B, bc: (_: B) => C): C; <A, B = never, C = never, D = never>(this: A, ab: (_: A) => B, bc: (_: B) => C, cd: (_: C) => D): D; <…;
toString: () => string;
toJSON: () => unknown;
}
interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) A in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>A, function (type parameter) E in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E, function (type parameter) R in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>R>,
errorTag: K extends TagsWithReason<E>errorTag: function (type parameter) K in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>K
): interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) A in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>A, type ExcludeTag<E, K extends string> = E extends {
readonly _tag: K;
} ? never : E
Excludes members of a tagged union by their _tag value.
When to use
Use to remove tagged-union members whose _tag matches a specific value in
type-level code.
Details
Non-tagged members of the union are preserved.
Example (Removing a variant)
import type { Types } from "effect"
type MyError =
| { readonly _tag: "NotFound"; readonly id: string }
| { readonly _tag: "Timeout"; readonly ms: number }
| string
type WithoutTimeout = Types.ExcludeTag<MyError, "Timeout">
// { readonly _tag: "NotFound"; readonly id: string } | string
ExcludeTag<function (type parameter) E in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E, function (type parameter) K in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>K> | type ReasonOf<E> = E extends {
readonly reason: infer R;
} ? R : never
Extracts the reason type from an error that has a reason field.
When to use
Use when an error type stores nested sub-errors in a reason field and you
need that field's full union type as a standalone type.
Details
Returns never if E has no reason field.
Example (Extracting reason types)
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 Reasons = Types.ReasonOf<ApiError>
// RateLimitError | QuotaError
ReasonOf<type ExtractTag<E, K extends string> = E extends {
readonly _tag: infer T;
} ? K extends T ? E : never : never
Extracts a specific member of a tagged union by its _tag value.
When to use
Use to select tagged-union members whose _tag matches a specific value in
type-level code.
Details
Returns never if no member matches the tag.
Example (Extracting a variant)
import type { Types } from "effect"
type MyError =
| { readonly _tag: "NotFound"; readonly id: string }
| { readonly _tag: "Timeout"; readonly ms: number }
type TimeoutError = Types.ExtractTag<MyError, "Timeout">
// { readonly _tag: "Timeout"; readonly ms: number }
ExtractTag<function (type parameter) E in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>E, function (type parameter) K in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>K>>, function (type parameter) R in <A, E, R, K extends TagsWithReason<E>>(self: Effect<A, E, R>, errorTag: K): Effect<A, ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>, R>R>
} = import internalinternal.const unwrapReason: {
<K extends Effect.TagsWithReason<E>, E>(
errorTag: K
): <A, R>(
self: Effect.Effect<A, E, R>
) => Effect.Effect<
A,
ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>,
R
>
<A, E, R, K extends Effect.TagsWithReason<E>>(
self: Effect.Effect<A, E, R>,
errorTag: K
): Effect.Effect<
A,
ExcludeTag<E, K> | ReasonOf<ExtractTag<E, K>>,
R
>
}