Result
Models a value that has already succeeded or failed.
A Result<A, E> is Success<A, E> when a value is available and Failure<A, E> when an error is available. It is plain data, so inspecting or transforming it does not run side effects. This module includes helpers for creating, checking, mapping, combining, and extracting results, plus conversions to and from Option and nullable values.
Constructors
Signature
declare const Do: Result<{}>;Creates a Result holding a Failure value.
When to use
Use to represent a failed Result with a typed failure value.
Details
- The success type A defaults to never
See
Signature
declare const fail: <E>(left: E) => Result<never, E>;Provides a pre-built failed Result whose failure value is undefined.
When to use
Use when you need a failed Result value that acts only as a control signal without failure data.
Details
This is equivalent to Result.fail(undefined) with type Result<never, void>, but reuses a shared Failure wrapper instead of allocating one each time.
See
failto create a Failure with a specific value
Signature
declare const failVoid: Result<never, void>;fromNullishOr
Converts a possibly null or undefined value into a Result.
When to use
Use when you need null or undefined input to become a Failure while present values remain available as Success.
Details
- Non-nullish values become Success<NonNullable<A>> - null or undefined becomes Failure<E> using the provided function - Supports both data-first and data-last (piped) usage - The onNullish callback receives the original value
See
fromOptionto convert from an Optionsucceed/ fail for direct construction
Signature
declare const fromNullishOr: {
<A, E>(onNullish: (a: A) => E): (self: A) => Result<NonNullable<A>, E>;
<A, E>(self: A, onNullish: (a: A) => E): Result<NonNullable<A>, E>;
};fromOption
Converts an Option<A> into a Result<A, E>.
When to use
Use when an existing Option should become a Result, preserving Some as success and turning None into a caller-provided failure.
Details
- Some<A> becomes Success<A> - None becomes Failure<E> using the provided function - Supports both data-first and data-last (piped) usage
See
getSuccessto extract the success value as an OptiongetFailureto extract the failure value as an OptionfromNullishOrto build a Result from nullable values
Signature
declare const fromOption: {
<E>(onNone: () => E): <A>(self: Option<A>) => Result<A, E>;
<A, E>(self: Option<A>, onNone: () => E): Result<A, E>;
};liftPredicate
Lifts a value into a Result based on a predicate or refinement.
When to use
Use to construct a Result from a raw value guarded by a predicate or refinement.
Details
- If the predicate returns true, the value becomes Success<A> - If the predicate returns false, orFailWith produces the error for Failure<E> - Also accepts a Refinement to narrow the success type - Supports both data-first and data-last (piped) usage
See
filterOrFailto validate a value that is already in aResultfromNullishOrfor nullable-based construction
Signature
declare const liftPredicate: {
<A, B, E>(refinement: Refinement<A, B>, orFailWith: (a: A) => E): (a: A) => Result<B, E>;
<B, E, A = B>(predicate: Predicate<A>, orFailWith: (a: A) => E): (a: B) => Result<B, E>;
<A, E, B>(self: A, refinement: Refinement<A, B>, orFailWith: (a: A) => E): Result<B, E>;
<B, E, A = B>(self: B, predicate: Predicate<A>, orFailWith: (a: A) => E): Result<B, E>;
};Creates a Result holding a Success value.
Details
- Use when you have a value and want to lift it into the Result type - The error type E defaults to never
See
Signature
declare const succeed: <A>(right: A) => Result<A>;succeedNone
Provides a pre-built Result<Option<never>> that succeeds with None.
When to use
Use when an optional success should be absent, such as the None branch of transposeOption or transposeMapOption.
Details
This is equivalent to Result.succeed(Option.none()), but reuses a shared Success wrapper instead of allocating one each time.
See
succeedSomefor theSomecounterparttransposeOptionto transpose an Option that already contains a ResulttransposeMapOptionto map and transpose an Option in one step
Signature
declare const succeedNone: Result<Option<never>, never>;succeedSome
Creates a Result<Option<A>> that succeeds with Some(a).
Details
- Equivalent to Result.succeed(Option.some(a)) - Useful with transposeOption patterns
See
succeedNonefor theNonecounterpart
Signature
declare function succeedSome<A, E = never>(a: A): Result<Option<A>, E>;Error Handling
Returns the original Result if it is a Success, otherwise applies that to the error and returns the resulting Result.
When to use
Use when a failure should recover into another Result while keeping successes unchanged.
Details
- Success<A> is returned unchanged - Failure<E> calls that(e) to produce a new Result
See
Signature
declare const orElse: {
<E, A2, E2>(that: (err: E) => Result<A2, E2>): <A>(self: Result<A, E>) => Result<A2 | A, E2>;
<A, E, A2, E2>(self: Result<A, E>, that: (err: E) => Result<A2, E2>): Result<A | A2, E2>;
};Filtering
filterOrFail
Validates the success value of a Result using a predicate, failing with a custom error if the predicate returns false.
When to use
Use to validate an already-successful Result value with a predicate or refinement.
Details
- If the result is already a Failure, it is returned as-is - If the predicate passes, the Success is returned unchanged - If the predicate fails, orFailWith produces the error for a new Failure - Also accepts a Refinement to narrow the success type - The error type of the output is the union of both error types
See
liftPredicateto create aResultfrom a raw value with a predicateflatMapfor general conditional chaining
Signature
declare const filterOrFail: {
<A, B, E2>(
refinement: Refinement<NoInfer<A>, B>,
orFailWith: (value: NoInfer<A>) => E2,
): <E>(self: Result<A, E>) => Result<B, E2 | E>;
<A, E2>(
predicate: Predicate<NoInfer<A>>,
orFailWith: (value: NoInfer<A>) => E2,
): <E>(self: Result<A, E>) => Result<A, E2 | E>;
<A, E, B, E2>(
self: Result<A, E>,
refinement: Refinement<A, B>,
orFailWith: (value: A) => E2,
): Result<B, E | E2>;
<A, E, E2>(
self: Result<A, E>,
predicate: Predicate<A>,
orFailWith: (value: A) => E2,
): Result<A, E | E2>;
};Generators
Provides generator-based syntax for composing Result values sequentially.
When to use
Use when you need generator syntax to compose sequential Result computations instead of nested flatMap calls.
Details
- Use yield* to unwrap a Result inside the generator; if any yielded Result is a Failure, the generator short-circuits and returns that failure - The return value of the generator is wrapped in Success - Evaluated eagerly and synchronously (unlike Effect.gen)
See
Signature
declare const gen: Gen.Gen<ResultTypeLambda>;ResultIterator interface
Iterator protocol used to yield a Result inside gen, returning the success value type back to the generator.
When to use
Use when defining or typing [Symbol.iterator]() for Result values so yield* can pass the success value type back into Result.gen.
See
genfor writing generator-basedResultcode that consumes this iterator protocol
Signature
interface ResultIterator<T extends Result<any, any>> {
next(...args: readonly Array<any>): IteratorResult<T, Success<T>>;
}Getters
getFailure
Extracts the failure value as an Option, discarding the success.
When to use
Use when you need to extract the failure value from a Result as an Option and discard successful values.
Details
- Failure<E> becomes Some<E> - Success<A> becomes None
See
getSuccessto extract the success insteadfromOptionfor the reverse conversion
Signature
declare const getFailure: <A, E>(self: Result<A, E>) => Option<E>;Extracts the success value, or computes a fallback from the error.
When to use
Use when you need the success value from a Result, with a fallback computed from the failure value.
Details
- Success<A> returns the inner value - Failure<E> applies onFailure to the error and returns the result - The return type is A | A2 (union of both branches)
See
getOrNull/ getOrUndefined for simpler fallbacksgetOrThrowto throw on failurematchto map both branchesorElseto recover with another Result instead of unwrapping
Signature
declare const getOrElse: {
<E, A2>(onFailure: (err: E) => A2): <A>(self: Result<A, E>) => A2 | A;
<A, E, A2>(self: Result<A, E>, onFailure: (err: E) => A2): A | A2;
};Extracts the success value, or returns null on failure.
When to use
Use when you need to pass failed Result values to APIs that represent absence as null.
Details
- Success<A> returns A - Failure<E> returns null
See
getOrUndefinedto returnundefinedinsteadgetOrElsefor a custom fallback
Signature
declare const getOrNull: <A, E>(self: Result<A, E>) => A | null;getOrThrow
Extracts the success value or throws the raw failure value E.
When to use
Use when unchecked boundaries should turn failures into thrown exceptions.
Details
- Success<A> returns A - Failure<E> throws E directly - Use getOrThrowWith for a custom error object
See
getOrThrowWithfor custom error mappinggetOrElsefor a non-throwing alternative
Signature
declare const getOrThrow: <A, E>(self: Result<A, E>) => A;getOrThrowWith
Extracts the success value or throws a custom error derived from the failure.
When to use
Use when converting a Result into a thrown exception with a custom error message or error type.
Details
- Success<A> returns A - Failure<E> throws the value returned by onFailure(e)
See
getOrThrowto throw the raw failure valuegetOrElsefor a non-throwing alternative
Signature
declare const getOrThrowWith: {
<E>(onFailure: (err: E) => unknown): <A>(self: Result<A, E>) => A;
<A, E>(self: Result<A, E>, onFailure: (err: E) => unknown): A;
};getOrUndefined
Extracts the success value, or returns undefined on failure.
When to use
Use when you need to pass failed Result values to APIs that represent absence as undefined.
Details
- Success<A> returns A - Failure<E> returns undefined
See
Signature
declare const getOrUndefined: <A, E>(self: Result<A, E>) => A | undefined;getSuccess
Extracts the success value as an Option, discarding the failure.
When to use
Use when you need to extract the success value from a Result as an Option and discard failure information.
Details
- Success<A> becomes Some<A> - Failure<E> becomes None
See
getFailureto extract the error insteadfromOptionfor the reverse conversion
Signature
declare const getSuccess: <A, E>(self: Result<A, E>) => Option<A>;Unwraps a Result into A | E by returning the inner value regardless of whether it is a success or failure.
Details
- Success<A> returns A - Failure<E> returns E - Useful when both channels share a compatible type
See
Signature
declare const merge: <A, E>(self: Result<A, E>) => E | A;Guards
Checks whether a Result is a Failure.
When to use
Use to narrow a known Result to the Failure variant.
Details
- Acts as a TypeScript type guard, narrowing to Failure<A, E> - After narrowing, you can access .failure to read the error value
See
Signature
declare const isFailure: <A, E>(self: Result<A, E>) => self is Failure<A, E>;Checks whether a value is a Result (either Success or Failure).
When to use
Use to validate unknown input before operating on it as a Result.
Details
- Returns true for both Success and Failure variants - Acts as a TypeScript type guard, narrowing to Result<unknown, unknown>
See
isSuccess/ isFailure to narrow to a specific variant
Signature
declare const isResult: (input: unknown) => input is Result<unknown, unknown>;Checks whether a Result is a Success.
When to use
Use to narrow a known Result to the Success variant.
Details
- Acts as a TypeScript type guard, narrowing to Success<A, E> - After narrowing, you can access .success to read the value
See
Signature
declare const isSuccess: <A, E>(self: Result<A, E>) => self is Success<A, E>;Instances
makeEquivalence
Creates an Equivalence for comparing two Result values.
Details
- Two Success values are equal when the success equivalence says so - Two Failure values are equal when the failure equivalence says so - A Success and a Failure are never equal
Signature
declare function makeEquivalence<A, E>(
success: Equivalence<A>,
failure: Equivalence<E>,
): Equivalence<Result<A, E>>;Mapping
Wraps the success value of a Result into a named field, producing a Result<Record<N, A>>.
When to use
Use to name the success value of an existing Result before continuing a do-notation pipeline.
Details
This is typically used to start a do-notation chain from an existing Result.
See
Signature
declare const bindTo: {
<N extends string>(name: N): <R, L>(self: Result<R, L>) => Result<Record<N, R>, L>;
<R, L, N extends string>(self: Result<R, L>, name: N): Result<Record<N, R>, L>;
};Transforms the success channel of a Result, leaving the failure channel unchanged.
When to use
Use to apply a transformation to the success value of a Result while preserving any existing failure.
Details
- If the result is a Success, applies f to the value and returns a new Success - If the result is a Failure, returns it as-is - Use flatMap if f returns a Result (to avoid nested Results)
See
Signature
declare const map: {
<A, A2>(f: (ok: A) => A2): <E>(self: Result<A, E>) => Result<A2, E>;
<A, E, A2>(self: Result<A, E>, f: (ok: A) => A2): Result<A2, E>;
};Transforms both the success and failure channels of a Result.
When to use
Use to transform both success and failure values without changing whether the result succeeds or fails.
Details
- Applies onSuccess if the result is a Success - Applies onFailure if the result is a Failure
See
Signature
declare const mapBoth: {
<E, E2, A, A2>(options: {
readonly onFailure: (left: E) => E2;
readonly onSuccess: (right: A) => A2;
}): (self: Result<A, E>) => Result<A2, E2>;
<E, A, E2, A2>(
self: Result<A, E>,
options: {
readonly onFailure: (left: E) => E2;
readonly onSuccess: (right: A) => A2;
},
): Result<A2, E2>;
};Transforms the failure channel of a Result, leaving the success channel unchanged.
When to use
Use to transform only the failure channel while preserving success values.
Details
- If the result is a Failure, applies f to the error and returns a new Failure - If the result is a Success, returns it as-is
See
Signature
declare const mapError: {
<E, E2>(f: (err: E) => E2): <A>(self: Result<A, E>) => Result<A, E2>;
<A, E, E2>(self: Result<A, E>, f: (err: E) => E2): Result<A, E2>;
};Runs a side-effect on the success value without altering the Result.
Details
- If the result is a Success, calls f with the value (return value is ignored) - If the result is a Failure, f is not called - Returns the original Result unchanged (same reference) - Useful for logging, debugging, or performing mutations outside the Result chain
See
mapto transform the success value
Signature
declare const tap: {
<A>(f: (a: A) => void): <E>(self: Result<A, E>) => Result<A, E>;
<A, E>(self: Result<A, E>, f: (a: A) => void): Result<A, E>;
};Models
The failure variant of Result. Wraps an error of type E.
Details
- Access the error via the .failure property - Use isFailure to narrow a Result to Failure - Create with fail
See
Signature
interface Failure<out A, out E> extends Pipeable, Inspectable {
readonly _op: "Failure";
readonly _tag: "Failure";
[ignoreSymbol]?: ResultUnifyIgnore;
[typeSymbol]?: unknown;
[unifySymbol]?: ResultUnify<Failure<A, E>>;
readonly "~effect/data/Result": {
readonly _A: Covariant<E>;
readonly _E: Covariant<A>;
};
readonly failure: E;
[iterator](): ResultIterator<Result<A, E>>;
}A value that is either Success<A, E> or Failure<A, E>.
When to use
Use when both success and failure should remain available as data and Option would lose failure information.
Details
- Use succeed / fail to construct - Use match to fold both branches - Use isSuccess / isFailure to narrow the type
E defaults to never, so Result<number> means a result that cannot fail.
See
Signature
type Result<A, E = never> = Success<A, E> | Failure<A, E>;ResultUnify interface
Type-level utility for unifying Result types in generic contexts.
Details
This is an internal interface used by the Effect type system. You typically do not need to reference it directly.
Signature
interface ResultUnify<
T extends {
[typeSymbol]?: any;
},
> {
Result?: () => T[typeof typeSymbol] extends Result<A, E> | _ ? Result<A, E> : never;
}ResultUnifyIgnore interface
Marker interface for ignoring unification in Result types.
Details
This is an internal interface used by the Effect type system. You typically do not need to reference it directly.
Signature
interface ResultUnifyIgnore {}The success variant of Result. Wraps a value of type A.
Details
- Access the value via the .success property - Use isSuccess to narrow a Result to Success - Create with succeed
See
Signature
interface Success<out A, out E> extends Pipeable, Inspectable {
readonly _op: "Success";
readonly _tag: "Success";
[ignoreSymbol]?: ResultUnifyIgnore;
[typeSymbol]?: unknown;
[unifySymbol]?: ResultUnify<Success<A, E>>;
readonly "~effect/data/Result": {
readonly _A: Covariant<E>;
readonly _E: Covariant<A>;
};
readonly success: A;
[iterator](): ResultIterator<Result<A, E>>;
}Other
Signature
declare const let: {
<N extends string, R extends object, B>(
name: Exclude<N, keyof R>,
f: (r: NoInfer<R>) => B,
): <L>(
self: Result<R, L>,
) => Result<{ [K in string | number | symbol]: K extends keyof R ? R[K] : B }, L>;
<R extends object, L, N extends string, B>(
self: Result<R, L>,
name: Exclude<N, keyof R>,
f: (r: NoInfer<R>) => B,
): Result<{ [K in string | number | symbol]: K extends keyof R ? R[K] : B }, L>;
};Namespace containing type-level utilities for extracting the inner types of a Result.
Signature
declare const try: {
<A, E>(options: {
readonly catch: (error: unknown) => E;
readonly try: LazyArg<A>;
}): Result<A, E>;
<A>(evaluate: LazyArg<A>): Result<A, unknown>;
}Signature
declare const void: Result<void>Pattern Matching
Folds a Result into a single value by applying one of two functions.
When to use
Use when a Result's success and failure branches should be collapsed into one plain output type.
Details
- Applies onSuccess if the result is a Success - Applies onFailure if the result is a Failure - Both branches must return the same type (or a common supertype)
See
Signature
declare const match: {
<E, B, A, C = B>(options: {
readonly onFailure: (error: E) => B;
readonly onSuccess: (ok: A) => C;
}): (self: Result<A, E>) => B | C;
<A, E, B, C = B>(
self: Result<A, E>,
options: {
readonly onFailure: (error: E) => B;
readonly onSuccess: (ok: A) => C;
},
): B | C;
};Sequencing
Collects a structure of Results into a single Result of collected values.
When to use
Use to collect independent Result values into one Result while preserving the original structure.
Details
Accepts: - A tuple/array: returns Result with a tuple/array of success values - A struct (record): returns Result with a struct of success values - An iterable: returns Result with an array of success values
Short-circuits on the first Failure encountered; later elements are not inspected.
See
Signature
declare const all: <I extends Iterable<Result<any, any>> | Record<string, Result<any, any>>>(
input: I,
) => [I] extends [ReadonlyArray<Result<any, any>>]
? Result<
{ [K in keyof I]: [I[K]] extends [Result<infer R, any>] ? R : never },
I[number] extends never ? never : [I[number]] extends [Result<any, infer L>] ? L : never
>
: [I] extends [Iterable<Result<infer R, infer L>>]
? Result<Array<R>, L>
: Result<
{ [K in keyof I]: [I[K]] extends [Result<infer R, any>] ? R : never },
I[keyof I] extends never ? never : [I[keyof I]] extends [Result<any, infer L>] ? L : never
>;Provides a flexible variant of flatMap that accepts multiple input shapes.
When to use
Use to sequence a next step that may be a Result, a function, or a plain value.
Details
The second argument can be: - A function (a: A) => Result<A2, E2> (same as flatMap) - A function (a: A) => A2 (auto-wrapped in succeed) - A Result<A2, E2> value (ignores the success of self) - A plain value A2 (auto-wrapped in succeed, ignores self)
If self is a Failure, the second argument is never evaluated.
See
Signature
declare const andThen: {
<A, A2, E2>(f: (a: A) => Result<A2, E2>): <E>(self: Result<A, E>) => Result<A2, E2 | E>;
<A2, E2>(f: Result<A2, E2>): <A, E>(self: Result<A, E>) => Result<A2, E2 | E>;
<A, A2>(f: (a: A) => A2): <E>(self: Result<A, E>) => Result<A2, E>;
<A2>(right: NotFunction<A2>): <A, E>(self: Result<A, E>) => Result<A2, E>;
<A, E, A2, E2>(self: Result<A, E>, f: (a: A) => Result<A2, E2>): Result<A2, E | E2>;
<A, E, A2, E2>(self: Result<A, E>, f: Result<A2, E2>): Result<A2, E | E2>;
<A, E, A2>(self: Result<A, E>, f: (a: A) => A2): Result<A2, E>;
<A, E, A2>(self: Result<A, E>, f: NotFunction<A2>): Result<A2, E>;
};Adds a named field to the do-notation accumulator by running a Result-producing function that receives the current accumulated object.
When to use
Use when you need to add a Result-producing step to a Result do-notation pipeline and store its successful value under a named field in the accumulated object.
Details
- Short-circuits on the first Failure - The field name must not collide with existing keys - Use let for pure (non-Result) computed fields
See
Signature
declare const bind: {
<N extends string, A extends object, B, L2>(
name: Exclude<N, keyof A>,
f: (a: NoInfer<A>) => Result<B, L2>,
): <L1>(
self: Result<A, L1>,
) => Result<{ [K in string | number | symbol]: K extends keyof A ? A[K] : B }, L2 | L1>;
<A extends object, L1, N extends string, B, L2>(
self: Result<A, L1>,
name: Exclude<N, keyof A>,
f: (a: NoInfer<A>) => Result<B, L2>,
): Result<{ [K in string | number | symbol]: K extends keyof A ? A[K] : B }, L1 | L2>;
};Chains a function that returns a Result onto a successful value.
When to use
Use to sequence Result-returning computations that should short-circuit on failure.
Details
- If self is a Success, applies f to the value and returns the resulting Result - If self is a Failure, short-circuits and returns it unchanged - The error types are merged into a union (E | E2) - This is the monadic bind / >>= for Result
See
Signature
declare const flatMap: {
<A, A2, E2>(f: (a: A) => Result<A2, E2>): <E>(self: Result<A, E>) => Result<A2, E2 | E>;
<A, E, A2, E2>(self: Result<A, E>, f: (a: A) => Result<A2, E2>): Result<A2, E | E2>;
};Transforming
Swaps the success and failure channels of a Result.
When to use
Use to swap channels when failure-focused operations are easier through success-oriented combinators.
Details
- Success<A> becomes Failure<A> (i.e., Result<E, A>) - Failure<E> becomes Success<E> (i.e., Result<E, A>) - Useful when you want to apply success-oriented operations (like map) to the error channel, then flip back
See
mapErrorto transform the error without swapping
Signature
declare function flip<A, E>(self: Result<A, E>): Result<E, A>;Transposing
transposeMapOption
Maps an Option value with a Result-producing function, then transposes the structure from Option<Result<B, E>> to Result<Option<B>, E>.
When to use
Use when an optional value should be validated only when present, preserving absence as a successful None.
Details
- None becomes Success(None) (the function is never called) - Some(a) where f(a) is Success(b) becomes Success(Some(b)) - Some(a) where f(a) is Failure(e) becomes Failure(e)
See
transposeOptionwhen the Option already contains a Result
Signature
declare const transposeMapOption: <A, B, E = never>(f: (self: A) => Result<B, E>) => (self: Option<A>) => Result<Option<B>, E> & <A, B, E = never>(self: Option<A>, f: (self: A) => Result<B, E>) => Result<Option<B>, E>transposeOption
Transforms Option<Result<A, E>> into Result<Option<A>, E>.
When to use
Use when optional absence should be treated as a successful None, while an inner Result failure should still fail the whole result.
Details
- None becomes Success(None) - Some(Success(a)) becomes Success(Some(a)) - Some(Failure(e)) becomes Failure(e)
See
transposeMapOptionto map and transpose in one step
Signature
declare function transposeOption<A = never, E = never>(
self: Option<Result<A, E>>,
): Result<Option<A>, E>;Utility Types
ResultTypeLambda interface
Higher-kinded type representation for Result.
Details
Used internally to integrate Result with generic type-class utilities (e.g., map, flatMap abstractions). You typically do not need to reference this directly.
Signature
interface ResultTypeLambda extends TypeLambda {
readonly type: Result<unknown, unknown>;
}
Provides the starting point for the "do notation" simulation with
Result.When to use
Use to start a
Resultdo-notation pipeline from an empty successful record before adding named fields fromResult-producing computations and pure computed values.Details
Creates a
Result<{}>(success with an empty object). Use with bind to addResult-producing fields and let to add pure computed fields.See
bindto add Result-producing fieldsletto add pure computed fieldsgenfor an alternative generator-based syntaxbindTofor starting a do-notation chain from an existing Result