@rafikidota/monadia

@rafikidota/monadia

Sometimes, the best way to solve your own problems is to help someone else.

Monads for TypeScript. Zero dependencies, dual CJS/ESM.

npm install @rafikidota/monadia

ResultSync

Holds either a value R or an error E — never both, never neither.

import { ResultSync } from '@rafikidota/monadia';

function parse(raw: string): ResultSync<number, RangeError> {
  const port = Number(raw);
  if (!Number.isInteger(port) || port < 1 || port > 65535) {
    return ResultSync.Fail(new RangeError(`invalid port: ${raw}`));
  }
  return ResultSync.Ok(port);
}

parse('8080')
  .map((port) => `http://localhost:${port}`)
  .unwrapOr('http://localhost:3000');

ResultSync.Ok() with no argument is ResultSync<void, E>. The class is final: the constructor is private and instances are frozen. To extend behaviour, wrap it. private is a compile-time guarantee, so the constructor also validates its state at runtime for JavaScript consumers.

ResultAsync

Wraps a Promise<ResultSync<R, E>>. Combinators return a new ResultAsync, so a chain reads as one expression.

import { ResultAsync } from '@rafikidota/monadia';

const view = await ResultAsync.fromPromise(
  repo.findOneOrFail(id),
  (e) => new NotFoundError(String(e)),
)
  .andThen(loadOrders)
  .map(format)
  .unwrapOr(EMPTY);

Callbacks can be sync or async, and andThen accepts a function returning a ResultSync, a ResultAsync or a Promise<ResultSync>, so sync and async steps mix in one chain.

Notes

• mapOrElse(def, func) takes the error callback first, then the value callback, on both classes.
• Rejections propagate. A callback that throws inside map/andThen rejects the resulting promise; it is not converted into a Fail. fromPromise is the only entry point from throwing code — its onErr is what keeps E honest. from takes a promise that already resolves to a ResultSync and assumes it does not reject.
• No *Async methods on ResultSync by design: a method returning Promise<ResultSync<T, E>> is not a ResultSync, so it would not compose.

License

MIT