LanguageExt.Core

LanguageExt.Core Common

Error

The Error type works like a discriminated-union, it is an abstract record type with many sub-cases (which are listed below). It is used extensively with various monadic types, like Fin<A>, the Effect System monads of Eff<A>, Eff<RT, A>, Aff<A>, Aff<RT, A> and the compositional streaming Pipes features.

The reason they're buried in the Common namespace is because, Error is a common type name. And so, this gives the programmer a chance to not include it when using LanguageExt;

Error exists because Exception is really only meant for exceptional errors. However, in C#-land we've been trained to throw them even for expected errors.

Instead we use Error to represent three key types of error:

These are the key base-types that indicate the 'flavour' of the error. For example, a 'user not found' error isn't something exceptional, it's something we expect might happen. An OutOfMemoryException however, is exceptional - it should never happen, and we should treat it as such.

Most of the time we want sensible handling of expected errors, and bail out completely for something exceptional. We also want to protect ourselves from information leakage. Leaking exceptional errors via public APIs is a surefire way to open up more information to hackers than you would like. The Error derived types all try to protect against this kind of leakage without losing the context of the type of error thrown.

Essentially an error is either created from an Exception or it isn't. This allows for expected errors to be represented without throwing exceptions, but also it allows for more principled error handling. We can pattern-match on the type, or use some of the built-in properties and methods to inspect the Error:

The Error type can be constructed to be exceptional or expected. For example, this is an expected error:

Error.New("This error was expected")

When expected errors are used with codes then equality and matching is done via the code only:

Error.New(404, "Page not found");

And this is an exceptional error:

try
{
    // This wraps up the exceptional error
}
catch(Exception e)
{
    return Error.New(e);
}

Finally, you can collect many errors:

Error.Many(Error.New("error one"), Error.New("error two"));

Or more simply:

Error.New("error one") + Error.New("error two")

You can extend the set of error types (perhaps for passing through extra data) by creating a new record inherits Exceptional or Expected:

public record BespokeError(bool MyData) 
    : Expected("Something bespoke", 100, None); 

By default the properties of the new error-type won't be serialised. So, if you want to pass a payload over the wire, add the [property: DataMember] attribute to each member:

public record BespokeError([property: DataMember] bool MyData) 
    : Expected("Something bespoke", 100, None); 

Using this technique it's trivial to create new error-types when additional data needs to be moved around, but also there's a ton of built-in functionality for the most common use-cases.

Contents

record Error Source #

Abstract error value

Properties

property int Code Source #

Error code

property string Message Source #

Error message

property Option<Error> Inner Source #

Inner error

property bool IsExceptional Source #

True if the error is exceptional

property bool IsExpected Source #

True if the error is expected

property Error Head Source #

Get the first error (this will be Errors.None if there are zero errors)

property Error Tail Source #

Get the errors with the head removed (this may be Errors.None if there are zero errors in the tail)

property bool IsEmpty Source #

This type can contain zero or more errors.

If IsEmpty is true then this is like None in Option: still an error, but without any specific information about the error.

property int Count Source #

This type can contain zero or more errors. This property returns the number of information carrying errors.

If Count is 0 then this is like None in Option: still an error, but without any specific information about the error.

property Option<Exception> Exception Source #

If this error represents an exceptional error, then this will return that exception, otherwise None

property Error Empty Source #

Methods

method bool Is <E> () Source #

where E : Exception

If this error represents an exceptional error, then this will return true if the exceptional error is of type E

method bool Is (Error error) Source #

Return true if this error contains or is the error provided

method Exception ToException () Source #

If this error represents an exceptional error, then this will return that exception, otherwise it will generate a new ErrorException that contains the code, message, and inner of this Error.

method ErrorException ToErrorException () Source #

Convert to an ErrorException which is like Error but derived from the Exception hierarchy

method Error Combine (Error error) Source #

Append an error to this error

Single errors will be converted to ManyErrors; ManyErrors will have their collection updated

Parameters

param error

Error

returns

method EnumerableM<Error> AsEnumerable () Source #

method string ToString () Source #

Convert the error to a string

method Error New (Exception? thisException) Source #

Create an Exceptional error

Parameters

param thisException

Exception

method Error New (string message, Exception? thisException) Source #

Create a Exceptional error with an overriden message. This can be useful for sanitising the display message when internally we're carrying the exception.

Parameters

param message

Error message

param thisException

Exception

method Error New (string message) Source #

Create an Expected error

Parameters

param message

Error message

method Error New (int code, string message) Source #

Create an Expected error

Parameters

param code

Error code

param message

Error message

method Error New (int code, string message, Error inner) Source #

Create an Expected error

Parameters

param code

Error code

param message

Error message

param inner

The inner error to this error

method Error New (string message, Error inner) Source #

Create an Expected error

Parameters

param message

Error message

param inner

The inner error to this error

method Error Many (params Error[] errors) Source #

Create a ManyErrors error

Collects many errors into a single Error type, called ManyErrors

Parameters

param code

Error code

param inner

The inner error to this error

method Error Many (Seq<Error> errors) Source #

Create a new error

Parameters

param code

Error code

param inner

The inner error to this error

method Error FromObject (object? value) Source #

Attempt to recover an error from an object. Will accept Error, ErrorException, Exception, string, Option If it fails, Errors.Bottom is returned

method Unit Throw () Source #

Throw the error as an exception

method R Throw <R> () Source #

Throw the error as an exception

Operators

operator + (Error lhs, Error rhs) Source #

Append an error to this error

Single errors will be converted to ManyErrors; ManyErrors will have their collection updated

record Expected (string Message, int Code, Option<Error> Inner = default) Source #

Contains the following:

  • Code - an integer value
  • Message - display text
  • Option<Error> - a nested inner error

It returns false when IsExceptional is called against it; and true when IsExpected is called against it.

Equality is done via the Code, so any two Expected errors with the same Code will be considered the same. This is useful when using the @catch behaviours with the Aff and Eff monads. If the Code is 0 then equality is done by comparing Message.

This allows for localised error messages where the message is ignored when matching/catching

Parameters

param Message

Error message

param Code

Error code

param Inner

Optional inner error

Properties

property string Message Source #

Error message

property int Code Source #

Error code

property Option<Error> Inner Source #

Inner error

property bool IsExceptional Source #

True if the error is exceptional

property bool IsExpected Source #

True if the error is expected

Methods

method string ToString () Source #

method ErrorException ToErrorException () Source #

Generates a new ErrorException that contains the Code, Message, and Inner of this Error.

method bool Is <E> () Source #

Returns false because this type isn't exceptional

record Exceptional (string Message, int Code) Source #

This contains an Exception is the classic sense. This also returns true when IsExceptional is called against it; and false when IsExpected is called against it.

If this record is constructed via deserialisation, or the default constructor then the internal Exception will will be null. This is intentional to stop exceptions leaking over application boundaries. The type will gracefully handle that, but all stack-trace information (and the like) will be erased. It is still considered an exceptional error however.

Properties

property string Message Source #

property int Code Source #

property Option<Error> Inner Source #

Returns the inner exception as an Error (if one exists), None otherwise

property bool IsExceptional Source #

True if the error is exceptional

property bool IsExpected Source #

True if the error is expected

Methods

method string ToString () Source #

method Exception ToException () Source #

Gets the Exception

Parameters

returns

method ErrorException ToErrorException () Source #

Gets the ErrorException

Parameters

returns

method bool Is <E> () Source #

Return true if the exceptional error is of type E

method bool Is (Error error) Source #

record BottomError () Source #

Bottom error

Properties

property int Code Source #

property string Message Source #

property bool IsExceptional Source #

True if the error is exceptional

property bool IsExpected Source #

True if the error is expected

Methods

method string ToString () Source #

method Exception ToException () Source #

Gets the Exception

Parameters

returns

method ErrorException ToErrorException () Source #

Gets the ErrorException

Parameters

returns

method bool Is <E> () Source #

Return true if the exceptional error is of type E

method bool Is (Error error) Source #

Return true this error contains or is the error provided

record ManyErrors ([property: DataMember] Seq<Error> Errors) Source #

ManyErrors allows for zero or more errors to be collected. This is useful for applicative behaviours like validation. It effectively turns the Error type into a monoid, with 'zero' being Errors.None, and 'append' coming from the Append method or use of operator+

Parameters

param Errors

Errors

Properties

property Error Empty Source #

property int Code Source #

property string Message Source #

property bool IsExceptional Source #

True if any of the the errors are exceptional

property bool IsExpected Source #

True if all of the the errors are expected

property Error Head Source #

Get the first error (this may be Errors.None if there are zero errors)

property Error Tail Source #

Get the errors with the head removed (this may be Errors.None if there are zero errors in the tail)

property bool IsEmpty Source #

This type can contain zero or more errors. If IsEmpty is true then this is like None in Option: still an error, but without any specific information about the error.

property int Count Source #

This type can contain zero or more errors. This property returns the number of information carrying errors.

If Count is 0 then this is like None in Option: still an error, but without any specific information about the error.

Methods

method string ToString () Source #

method Exception ToException () Source #

Gets the Exception

method ErrorException ToErrorException () Source #

Gets the ErrorException

method bool Is <E> () Source #

False

method bool Is (Error error) Source #

Return true this error contains or is the error provided

method EnumerableM<Error> AsEnumerable () Source #

class ErrorException Source #

Error value

Unlike exceptions, Error can be either:

  • Exceptional - representing an unexpected error
  • LabelledExceptional - representing an unexpected error with additional context (a message)
  • Expected - representing an expected error
  • ManyErrors - representing an many errors

i.e. it is either created from an exception or it isn't. This allows for expected errors to be represented without throwing exceptions.

Properties

property int Code Source #

Error code

property Option<ErrorException> Inner Source #

Inner error

property bool IsEmpty Source #

This type can contain zero or more errors. If IsEmpty is true then this is like None in Option: still an error, but without any specific information about the error.

property bool IsExceptional Source #

True if the error is exceptional

property bool IsExpected Source #

True if the error is expected

property ErrorException Empty Source #

Methods

method Error ToError () Source #

Convert to an Error

method ErrorException Combine (ErrorException error) Source #

Append an error to this error

Single errors will be converted to ManyErrors; ManyErrors will have their collection updated

method IEnumerator<ErrorException> GetEnumerator () Source #

method string ToString () Source #

Convert the error to a string

method ErrorException New (Exception thisException) Source #

Create a new error

Parameters

param message

Error message

method ErrorException New (string message, Exception thisException) Source #

Create a new error

Parameters

param message

Error message

param thisException

The exception this error represents

method ErrorException New (string message) Source #

Create a new error

Parameters

param message

Error message

method ErrorException New (int code, string message) Source #

Create a new error

Parameters

param code

Error code

param message

Error message

method ErrorException New (int code, string message, ErrorException inner) Source #

Create a new error

Parameters

param code

Error code

param message

Error message

param inner

The inner error to this error

method ErrorException New (string message, ErrorException inner) Source #

Create a new error

Parameters

param code

Error code

param inner

The inner error to this error

method ErrorException Many (params ErrorException[] errors) Source #

Create a new error

Parameters

param code

Error code

param inner

The inner error to this error

method ErrorException Many (Seq<ErrorException> errors) Source #

Create a new error

Parameters

param code

Error code

param inner

The inner error to this error

Operators

operator + (ErrorException lhs, ErrorException rhs) Source #

Append an error to this error

Single errors will be converted to ManyErrors; ManyErrors will have their collection updated

class ExpectedException Source #

Represents expected errors

Properties

property int Code Source #

Error code

property string Message Source #

Error message

property Option<ErrorException> Inner Source #

Inner error

property bool IsExceptional Source #

True if the error is exceptional

property bool IsExpected Source #

True if the error is expected

Constructors

constructor ExpectedException (string message, int code, Option<ErrorException> inner) Source #

Methods

method Error ToError () Source #

Generates a new Error that contains the Code, Message, and Inner of this ErrorException.

method ErrorException Combine (ErrorException error) Source #

Append an error to this error

Single errors will be converted to ManyErrors; ManyErrors will have their collection updated

class ExceptionalException Source #

Represents an exceptional (unexpected) error

Parameters

param Exception

Exceptional error

Fields

field Exception? Exception Source #

Properties

property int Code Source #

property string Message Source #

property Option<ErrorException> Inner Source #

Returns the inner exception as an Error (if one exists), None otherwise

property bool IsExceptional Source #

True if the error is exceptional

property bool IsExpected Source #

True if the error is expected

Constructors

constructor ExceptionalException (Exception Exception) Source #

constructor ExceptionalException (string Message, int Code) Source #

constructor ExceptionalException (string Message, Exception Exception) Source #

Methods

method Error ToError () Source #

Gets the Error

Parameters

returns

method ErrorException Combine (ErrorException error) Source #

Append an error to this error

Single errors will be converted to ManyErrors; ManyErrors will have their collection updated

Parameters

param error

Error

returns

class ManyExceptions Source #

Represents multiple errors

Parameters

param Errors

Errors

Fields

field Seq<ErrorException> Errors Source #

Properties

property ErrorException Empty Source #

property int Code Source #

property string Message Source #

property Option<ErrorException> Inner Source #

Returns the inner exception as an Error (if one exists), None otherwise

property bool IsEmpty Source #

This type can contain zero or more errors. If IsEmpty is true then this is like None in Option: still an error, but without any specific information about the error.

property bool IsExceptional Source #

True if any of the the errors are exceptional

property bool IsExpected Source #

True if all of the the errors are expected

Constructors

constructor ManyExceptions (Seq<ErrorException> errors) Source #

Methods

method Error ToError () Source #

Gets the Exception

method ErrorException Combine (ErrorException error) Source #

Append an error to this error

Single errors will be converted to ManyErrors; ManyErrors will have their collection updated

Parameters

param error

Error

returns

method IEnumerator<ErrorException> GetEnumerator () Source #

class BottomException Source #

Value is bottom

Fields

field BottomException Default Source #

Properties

property string Message Source #

property int Code Source #

property Option<ErrorException> Inner Source #

Constructors

constructor BottomException () Source #

Methods

method Error ToError () Source #

method ErrorException Combine (ErrorException error) Source #

class ExceptionExtensions Source #

Methods

method Unit Rethrow (this Exception e) Source #

Throw the error as an exception

method R Rethrow <R> (this Exception e) Source #

Throw the error as an exception

class Errors Source #

Fields

field Error None = new ManyErrors(Seq<Error>.Empty) Source #

An error state without any error values

field int BottomCode = -2000000001 Source #

Bottom error code

field Error Bottom = BottomError.Default Source #

An error that indicates a value from an operation couldn't be evaluated. This is a hard fail for systems that depend on expressions to produce results.

field string CancelledText = "cancelled" Source #

Cancelled error text

field int CancelledCode = -2000000000 Source #

Cancelled error code

field string TimedOutText = "timed out" Source #

Timed-out error text

field int TimedOutCode = -2000000002 Source #

Timed-out error code

field Error TimedOut = (TimedOutCode, TimedOutText) Source #

Timed-out error

field string SequenceEmptyText = "sequence empty" Source #

Sequence-empty error text

field int SequenceEmptyCode = -2000000003 Source #

Sequence-empty error code

field string ClosedText = "closed" Source #

Closed error text

field int ClosedCode = -2000000004 Source #

Closed error code

field Error Closed = (ClosedCode, ClosedText) Source #

Closed error

field int ParseErrorCode = -2000000005 Source #

Parse error code

field int ManyErrorsCode = -2000000006 Source #

Many errors code

field int IONotInTransformerStackCode = -2000000007 Source #

IO monad not in transformer stack code

field int UnliftIONotSupportedCode = -2000000008 Source #

Transformer stack has no unliftIO support code

field Error UnliftIONotSupported = (UnliftIONotSupportedCode, UnliftIONotSupportedText) Source #

Transformer stack has no unliftIO support error

field string EndOfStreamText = "end of stream" Source #

End-of-stream text

field int EndOfStreamCode = -2000000009 Source #

End-of-stream code

Methods

method Error ParseError (string msg) Source #

Parse error