Interface Try<T>

Base interface for sum-type containers (Either, Try, etc.) that are NOT iterables.

Unlike FunctypeBase, this base deliberately excludes Traversable — which bundles reduce / reduceRight / size / isEmpty. Those methods force A-invariance on their containers (signature (f: (A, A) => A) => A puts A in both contravariant and covariant positions) and have no semantic meaning for disjoint-union types where the "success" branch is 0-or-1, not a collection.

Sum types that extend FunctypeSum can be declared covariant in their type parameter (interface Foo<out A>) without structural check failures. This mirrors Scala's model: Either[+L, +R] and Try[+T] do not extend Iterable; only Option[+A] extends the lighter IterableOnce[+A].

Only the covariance-safe subset of ContainerOps is included inline: contains, exists, and forEach all place A only in contravariant (callback input) position. find (returns Option<A>) and count are intentionally omitted — if a sum type needs them it can declare them directly.

interface Try<out T> {
 _tag: TypeNames;
 "[toStringTag]": string;
 ap: (ff: Try<(value: T) => U>) => Try;
 error: Error | undefined;
 expect: (handler: (error: Error) => never) => T;
 flatMap: (f: (value: T) => Try) => Try;
 flatMapAsync: (f: (value: T) => Promise<Try>) => Promise<Try>;
 fold: (
 onFailure: (error: Error) => U,
 onSuccess: (value: T) => U,
 ) => U;
 foldAsync: (
 onFailure: (error: Error) => U | Promise,
 onSuccess: (value: T) => U | Promise,
 ) => Promise;
 map: (f: (value: T) => U) => Try;
 orNull: () => T | null;
 orThrow: (error?: Error) => T;
 orUndefined: () => T | undefined;
 toArray: () => readonly T[];
 toEither: <E extends unknown>(
 leftOrBuilder: E | ((err: Error) => E),
 ) => Either<E, T>;
 toOption: () => Option<T>;
 toString: () => string;
 toTry: () => Try<T>;
 contains(value: T): boolean;
 doUnwrap(): DoResult<T>;
 exists(p: (a: T) => boolean): boolean;
 foldLeft(z: B): (op: (b: B, a: T) => B) => B;
 foldRight(z: B): (op: (a: T, b: B) => B) => B;
 forEach(f: (a: T) => void): void;
 isFailure(): this is Try<T> & { _tag: "Failure"; error: Error };
 isSuccess(): this is Try<T> & { _tag: "Success"; error: undefined };
 match<R>(
 patterns: { Failure: (error: Error) => R; Success: (value: T) => R },
 ): R;
 or<T2 extends unknown>(alternative: Try<T2>): Try<T | T2>;
 orElse<T2 extends unknown>(defaultValue: T2): T | T2;
 pipe(f: (value: T) => U): U;
 recover(f: (error: Error) => U): Try<T | U>;
 recoverWith(f: (error: Error) => Try): Try<T | U>;
 serialize(): SerializationMethods<T>;
 toJSON(): | { _tag: "Success"; "@functype": "Try"; value: T }
 | { _tag: "Failure"; "@functype": "Try"; error: SerializedError };
 toList(): List<T>;
 toPromise(): Promise<T>;
 toValue(): { _tag: TypeNames; value: Error | T };
}

Type Parameters

out T
the type of the "success" branch value

Hierarchy (View Summary)

Properties

`Readonly`_tag

_tag: TypeNames

`Readonly`[toStringTag]

"[toStringTag]": string

ap

ap: (ff: Try<(value: T) => U>) => Try

`Readonly`error

error: Error | undefined

expect

expect: (handler: (error: Error) => never) => T

Returns the success value, or calls the never-returning handler with the Failure's error. Use this when you have a helper like (msg) => fail(msg, 2) that terminates the program — the result type is unconditionally T, so you avoid the TypeScript narrowing trap where if (t.isFailure()) fail(...) fails to narrow t.value when fail is an arrow function typed as (...): never.

flatMap

flatMap: (f: (value: T) => Try) => Try

flatMapAsync

flatMapAsync: (f: (value: T) => Promise<Try>) => Promise<Try>

fold

fold: (
onFailure: (error: Error) => U,
onSuccess: (value: T) => U,
) => U

Pattern matches over the Try, applying onFailure if Failure and onSuccess if Success

Type Declaration

- (
 onFailure: (error: Error) => U,
 onSuccess: (value: T) => U,
 ): U
- Type Parameters
 - U extends unknown
 Parameters
 - onFailure: (error: Error) => U
 Function to apply if the Try is Failure
 - onSuccess: (value: T) => U
 Function to apply if the Try is Success
 Returns U
 The result of applying the appropriate function

foldAsync

foldAsync: (
onFailure: (error: Error) => U | Promise,
onSuccess: (value: T) => U | Promise,
) => Promise

Async variant of fold. Accepts sync or async handlers on either branch and always returns a Promise.

map

map: (f: (value: T) => U) => Try

orNull

orNull: () => T | null

Returns the contained value or null

Type Declaration

- (): T | null
- Returns T | null
  The contained value or null

orThrow

orThrow: (error?: Error) => T

Extract the value or throw an error

Type Declaration

- (error?: Error): T
- Parameters
  - Optionalerror: Error
    Optional custom error to throw. If not provided, uses type-appropriate default error
  Returns T
  The contained value

Throws

The specified error, container's error, or a sensible default

orUndefined

orUndefined: () => T | undefined

Returns the contained value or undefined

Type Declaration

- (): T | undefined
- Returns T | undefined
  The contained value or undefined

toArray

toArray: () => readonly T[]

Converts to a plain readonly array: [value] for Success, [] for Failure. Symmetric with Try.toList() but skips the List wrapper for code that just wants to feed Array.prototype methods or spread into another array.

toEither

toEither: <E extends unknown>(
leftOrBuilder: E | ((err: Error) => E),
) => Either<E, T>

Converts to Either<E, T>. Failure becomes Left(builder(error)) when given a function, or Left(leftValue) when given a value. Success becomes Right(value).

Prefer the function form to thread the underlying Error's context into the Left:

Try.fromYAML(text).toEither((e) => parse failed: ${e.message})

toOption

toOption: () => Option<T>

Converts this monad to an Option.

Conversion rules:

Option: returns self
Either: Right → Some, Left → None
List: non-empty → Some(head), empty → None
Try: Success → Some, Failure → None

Type Declaration

- (): Option<T>
- Returns Option<T>
 An Option containing the value if present, None otherwise

toString

toString: () => string

Returns a string representation of an object.

toTry

toTry: () => Try<T>

Converts this monad to a Try.

Conversion rules:

Option: Some → Success, None → Failure(Error("None"))
Either: Right → Success, Left → Failure(Error(leftValue))
List: non-empty → Success(head), empty → Failure(Error("Empty list"))
Try: returns self

Type Declaration

- (): Try<T>
- Returns Try<T>
 A Try containing Success with the value or Failure with an appropriate error

Methods

contains

contains(value: T): boolean
Parameters
- value: T
Returns boolean
Inherited from FunctypeSum.contains

doUnwrap

doUnwrap(): DoResult<T>
Returns DoResult<T>
Inherited from Doable.doUnwrap

exists

exists(p: (a: T) => boolean): boolean
Parameters
- p: (a: T) => boolean
Returns boolean
Inherited from FunctypeSum.exists

foldLeft

foldLeft(z: B): (op: (b: B, a: T) => B) => B
Left-associative fold using the provided zero value and operation
Type Parameters
- B
Parameters
- z: B
 Zero/identity value
Returns (op: (b: B, a: T) => B) => B
A function that takes an operation to apply

Inherited from FunctypeSum.foldLeft

foldRight

foldRight(z: B): (op: (a: T, b: B) => B) => B
Right-associative fold using the provided zero value and operation
Type Parameters
- B
Parameters
- z: B
 Zero/identity value
Returns (op: (a: T, b: B) => B) => B
A function that takes an operation to apply

Inherited from FunctypeSum.foldRight

forEach

forEach(f: (a: T) => void): void
Parameters
- f: (a: T) => void
Returns void
Inherited from FunctypeSum.forEach

isFailure

isFailure(): this is Try<T> & { _tag: "Failure"; error: Error }
Returns this is Try<T> & { _tag: "Failure"; error: Error }

isSuccess

isSuccess(): this is Try<T> & { _tag: "Success"; error: undefined }
Returns this is Try<T> & { _tag: "Success"; error: undefined }

match

match<R>(
patterns: { Failure: (error: Error) => R; Success: (value: T) => R },
): R
Pattern matches over the Try, applying a handler function based on the variant
Type Parameters
- R
Parameters
- patterns: { Failure: (error: Error) => R; Success: (value: T) => R }
 Object with handler functions for Success and Failure variants
Returns R
The result of applying the matching handler function

or

or<T2 extends unknown>(alternative: Try<T2>): Try<T | T2>
Returns this container if it has a value, otherwise returns the alternative container. The alternative may carry a different type; the result widens to Extractable<T | T2>.
Type Parameters
- T2 extends unknown
Parameters
- alternative: Try<T2>
 The alternative container
Returns Try<T | T2>
This container or the alternative

Overrides Extractable.or

orElse

orElse<T2 extends unknown>(defaultValue: T2): T | T2
Returns the contained value or a default value. The default may be of a different type; the result widens to T | T2.
Type Parameters
- T2 extends unknown
Parameters
- defaultValue: T2
 The value to return if extraction fails
Returns T | T2
The contained value or defaultValue

Overrides Extractable.orElse

pipe

pipe(f: (value: T) => U): U
Pipes the value through the provided function
Type Parameters
- U extends unknown
 The return type of the function
Parameters
- f: (value: T) => U
 The function to apply to the value
Returns U
The result of applying the function to the value

Inherited from Pipe.pipe

recover

recover(f: (error: Error) => U): Try<T | U>
Recovers from a Failure by applying a function to the error, returning a new Try. The recovery value may be a wider type; the result is Try<T | U>, matching Scala's recover[U >: T] shape so Try stays covariant in T.
Type Parameters
- U extends unknown
Parameters
- f: (error: Error) => U
Returns Try<T | U>

recoverWith

recoverWith(f: (error: Error) => Try): Try<T | U>
Recovers from a Failure by applying a function that returns a new Try. As with recover, the recovery Try may carry a wider type; the result widens accordingly.
Type Parameters
- U extends unknown
Parameters
- f: (error: Error) => Try
Returns Try<T | U>

serialize

serialize(): SerializationMethods<T>
Returns SerializationMethods<T>
Inherited from FunctypeSum.serialize

toJSON

toJSON(): | { _tag: "Success"; "@functype": "Try"; value: T }
| { _tag: "Failure"; "@functype": "Try"; error: SerializedError }
Custom JSON serialization. Success emits {"@functype":"Try","_tag":"Success","value":T}. Failure emits {"@functype":"Try","_tag":"Failure","error":SerializedError} where SerializedError captures name, message, stack, and the full cause chain — e.name survives round-trip but instanceof SomeError does not.

Returns
| { _tag: "Success"; "@functype": "Try"; value: T }
| { _tag: "Failure"; "@functype": "Try"; error: SerializedError }
Overrides FunctypeSum.toJSON

toList

toList(): List<T>
Converts this monad to a List.

Conversion rules:
- Option: Some → List([value]), None → List([])
- Either: Right → List([value]), Left → List([])
- List: returns self
- Try: Success → List([value]), Failure → List([])
Returns List<T>
A List containing the value(s) if present, empty List otherwise

Inherited from Reshapeable.toList

toPromise

toPromise(): Promise<T>
Converts this container to a Promise

The behavior depends on the implementing container:
- Success/Right/Some containers resolve with their value
- Failure/Left/None containers reject with their error/default error
Returns Promise<T>
A Promise that resolves or rejects based on the container's state

Inherited from Promisable.toPromise

toValue

toValue(): { _tag: TypeNames; value: Error | T }
Returns { _tag: TypeNames; value: Error | T }

Interface Try<T>

Type Parameters

Hierarchy (View Summary)

Index

Properties

Methods

Properties

Readonly_tag

Readonly[toStringTag]

ap

Readonlyerror

expect

flatMap

flatMapAsync

fold

Type Declaration

Type Parameters

Parameters

Returns U

foldAsync

map

orNull

Type Declaration

Returns T | null

orThrow

Type Declaration

Parameters

Returns T

Throws

orUndefined

Type Declaration

Returns T | undefined

toArray

toEither

toOption

Type Declaration

Returns Option<T>

toString

toTry

Type Declaration

Returns Try<T>

Methods

contains

Parameters

Returns boolean

doUnwrap

Returns DoResult<T>

exists

Parameters

Returns boolean

foldLeft

Type Parameters

Parameters

Returns (op: (b: B, a: T) => B) => B

foldRight

Type Parameters

Parameters

Returns (op: (a: T, b: B) => B) => B

forEach

Parameters

Returns void

isFailure

Returns this is Try<T> & { _tag: "Failure"; error: Error }

isSuccess

Returns this is Try<T> & { _tag: "Success"; error: undefined }

match

Type Parameters

Parameters

Returns R

or

Type Parameters

Parameters

Returns Try<T | T2>

orElse

Type Parameters

Parameters

Returns T | T2

pipe

Type Parameters

Parameters

`Readonly`_tag

`Readonly`[toStringTag]

`Readonly`error

Returns
| { _tag: "Success"; "@functype": "Try"; value: T }
| { _tag: "Failure"; "@functype": "Try"; error: SerializedError }