TypeScript Monads

Common errors

• TypeError: (0, typescript_monads_1.maybeToObservable) is not a function

  cause The `rxjs` package is not installed, but a function that integrates with RxJS (like `maybeToObservable`) is being called.
  fix Install RxJS as a dependency: `npm install rxjs` or `yarn add rxjs`.

• TS2305: Module ''typescript-monads'' has no exported member 'result'.

  cause Attempting to import `result` (lowercase) as a named export, but the primary factory functions are `ok` and `fail`, and the type is `Result` (uppercase).
  fix Use `import { ok, fail, Result } from 'typescript-monads'` instead. Factory functions are `ok()` and `fail()`, and the type is `Result<T, E>`.

• ReferenceError: typescriptMonads is not defined (in browser)

  cause The `typescript-monads` script was loaded directly in the browser via `unpkg` without ensuring it exposes a global variable, or it's trying to access `typescriptMonads` before the script fully loads or in a context where it's not exposed.
  fix Ensure the script is loaded and executed, and the correct global variable name is used. As per documentation, it exposes `typescriptMonads`. If using modern bundlers, prefer `import` statements.

• TS2339: Property 'value' does not exist on type 'Maybe<number>' (or 'Result<string, Error>').

  cause Directly trying to access a property like `.value` on a monad instance, which is an incorrect pattern as monads wrap values and require specific methods for safe extraction.
  fix Use the provided monadic methods for value extraction or transformation, such as `.valueOr(defaultValue)`, `.match(...)`, `.tapSome(...)`, `.map(...)`, or `.flatMap(...)`.

Warnings

• breaking The signature of `Maybe.apply` method was changed in v9.0.0. Code using the `apply` method might need adjustments.
  Fix: Review the specific usage of `Maybe.apply` and update its arguments according to the new signature, as detailed in the v9.0.0 release notes or updated documentation.
• gotcha Integration with RxJS features like `maybeToObservable` requires the `rxjs` package to be explicitly installed as a dependency in your project. It is not bundled with `typescript-monads`.
  Fix: Install RxJS: `npm install rxjs` or `yarn add rxjs`.
• gotcha Attempting to access a value from a `None` (for Maybe) or a `Fail` (for Result) directly without using safe methods like `valueOr`, `match`, or `tapSome`/`tapOk` will result in `undefined` or an unhandled value, negating the benefits of the monad.
  Fix: Always use provided monadic methods (e.g., `.valueOr(defaultValue)`, `.match({ some: ..., none: ... })`, `.flatMap(fn)`) to safely interact with values that may or may not be present, preventing unexpected runtime errors.
• gotcha The library heavily relies on TypeScript type inference. While it provides runtime safety, incorrect type declarations when creating monads or using `flatMap`/`map` can lead to type mismatches that TypeScript might catch but could lead to logical errors if types are asserted incorrectly.
  Fix: Ensure strict TypeScript settings are enabled. Pay close attention to the generic types when instantiating monads (e.g., `none<number>()` or `List.empty<string>()`) and verify the return types of functions passed to `map`, `flatMap`, and `filter`.

Install

• npm install typescript-monads npm
• yarn add typescript-monads yarn
• pnpm add typescript-monads pnpm

Imports

• maybe
  wrong:

  const { maybe } = require('typescript-monads')

  correct:

  import { maybe } from 'typescript-monads'

  The library primarily targets modern JavaScript environments supporting ESM. While some bundlers might handle CJS `require`, direct usage in Node.js without transpilation should prefer ESM imports. `maybe` is the primary factory function for the Maybe monad.
• List
  wrong:

  import List from 'typescript-monads'

  correct:

  import { List } from 'typescript-monads'

  List is a named export, not a default export. Incorrectly importing it as a default will result in `undefined`.
• Result
  wrong:

  import { result } from 'typescript-monads'

  correct:

  import { Result } from 'typescript-monads'

  The `Result` monad itself is exported as a class (`Result`), while factory functions for success/failure are `ok` and `fail` (e.g., `import { ok, fail } from 'typescript-monads'`).
• maybeToObservable

  import { maybeToObservable } from 'typescript-monads'

  Requires `rxjs` to be installed separately as an optional dependency. If `rxjs` is not present, calling this function will lead to a runtime error.

Quickstart

This quickstart illustrates the core usage of the Maybe, Result, and List monads for handling optional values, errors, and collections functionally. It demonstrates how to create instances, chain operations, and safely extract values or handle error conditions.

import { maybe, none, List, ok, fail } from 'typescript-monads';

// Demonstrating Maybe monad for optional values
function getUserDisplayName(user: { firstName?: string, lastName?: string }): string {
  return maybe(user.firstName)
    .flatMap(first => maybe(user.lastName).map(last => `${first} ${last}`))
    .valueOr('Guest');
}

console.log(getUserDisplayName({ firstName: 'Alice', lastName: 'Smith' }));
console.log(getUserDisplayName({ firstName: 'Bob' }));
console.log(getUserDisplayName({}));

// Demonstrating Result monad for error handling
function divide(a: number, b: number): typeof Result<number, string> {
  if (b === 0) {
    return fail('Cannot divide by zero');
  } 
  return ok(a / b);
}

divide(10, 2).match({
  ok: val => console.log(`Result: ${val}`), // Result: 5
  fail: err => console.error(`Error: ${err}`)
});

divide(10, 0).match({
  ok: val => console.log(`Result: ${val}`),
  fail: err => console.error(`Error: ${err}`)
}); // Error: Cannot divide by zero

// Demonstrating List monad for functional collections
const numbers = List.of(1, 2, 3, 4, 5);
const doubledEvens = numbers
  .filter(n => n % 2 === 0)
  .map(n => n * 2)
  .toArray();

console.log(doubledEvens); // [4, 8]