Either

Either monad for functional, type-safe error handling. It represents a value that can be either a success (Right) or an error (Left), avoiding the use of exceptions.

How to import?

The library exposes the DEither and E namespaces from the main entry or via direct import (tree-shaking friendly), which lets you only load what you need.

typescript

import { DEither, E } from "@duplojs/utils";
import * as DEither from "@duplojs/utils/either";
import * as E from "@duplojs/utils/either";

What is an Either monad?

INFO

An Either monad is a container that represents a value that can be in one of two states: success or error. It enables elegant, type-safe error handling without throwing exceptions.

The Either monad has two constructors:

E.left: represents an error (the "bad" side)
E.right: represents a valid value (the "good" side)

typescript

if (result > 0) {
  return E.right("success", result);
} else {
  return E.left("error", result);
}

WARNING

Order matters: Left is conventionally used for errors and Right for successes. Do not invert them in your business logic.

Advantages:

Type-safe: TypeScript forces you to handle both cases
No exceptions: Avoids try-catch and unpredictable behavior
Composable: Either operations can be chained with map, flatMap, etc.
Readable: Code becomes more explicit about error paths

TIP

You can chain Either operations for elegant error handling without nested conditionals.

The power of contextualization with Info

INFO

The real strength of this library lies in the mandatory addition of an info to every state (success or error). This info stays both on the monad AND in the TypeScript typing, enabling precise, type-safe pattern matching.

The problem without info:

A monad can contain multiple different errors and multiple different successes. Without contextualization, you are forced to do generic pattern matching or re-validate to know what the monad really contains.

typescript

// Without info: ambiguous, what do we really have?
const result = someFunction();
if (E.isRight(result)) {
  // But which success? We don't really know
  const value = unwrap(result);
}

The solution with info:

The info is a literal string that contextualizes the output. It stays in the type, so TypeScript can help you during pattern matching.

typescript

const result = someFunction();

if (E.isRight(result) && E.hasInformation(result, "user.created")) {
	// TypeScript knows exactly which success!
	const newUser = unwrap(result);
} else if (E.isRight(result) && E.hasInformation(result, "user.updated")) {
	// Another success, completely different
	const updatedUser = unwrap(result);
} else if (E.isLeft(result) && E.hasInformation(result, "emailAlreadyExists")) {
	// A specific error, easy to handle
	const conflict = unwrap(result);
	...
}

Advantages of this approach:

No extra validation: The info is enough to precisely identify the state
Guaranteed exhaustiveness: TypeScript forces you to handle all possible cases
Clear semantics: The code documents itself about what happens
Avoids generic errors: No need for generic monads anymore, each case is explicit

WARNING

The info must be explicit and representative. Use clear names like "emailAlreadyExists", "validationFailed", "user.created" rather than generic codes.