TypeScript Optional

Common errors

• TypeError: optional.isPresent is not a function

  cause In `typescript-optional` v2.0.0 and later, `isPresent` (and `isEmpty`) changed from a property accessor to a method.
  fix Change `optional.isPresent` to `optional.isPresent()` and `optional.isEmpty` to `optional.isEmpty()`.

• TypeError: Cannot retrieve payload from empty Optional

  cause You attempted to call the `get()` method on an `Optional` instance that does not contain a value.
  fix Before calling `get()`, verify the presence of a value with `optional.isPresent()`, or use alternative methods like `orElse()`, `orElseGet()`, `orNull()`, or `orUndefined()` to safely handle empty optionals.

• TypeError: value must not be null

  cause You passed `null` or `undefined` to `Optional.ofNonNull()`, which explicitly requires a non-null/non-undefined argument.
  fix If the value might be `null` or `undefined`, use `Optional.ofNullable(value)` instead. Only use `Optional.ofNonNull()` when you are absolutely sure the value is present.

Warnings

• breaking Version 2.0.0 introduced several breaking changes, including `Optional#isPresent` and `Optional#isEmpty` changing from accessors (properties) to methods. `Optional#map` also had its type signature refined, representing that it exactly returns a value whose payload is non-null type, and `Optional.toJSON` was added.
  Fix: Update calls like `optional.isPresent` to `optional.isPresent()` and `optional.isEmpty` to `optional.isEmpty()`.
• gotcha The `get()` method will throw a `TypeError` if the `Optional` instance is empty (does not contain a value). This behavior is consistent with Java's `Optional.get()` but is a common source of runtime errors if not properly guarded.
  Fix: Always check `optional.isPresent()` before calling `get()`, or use safer methods like `orElse()`, `orElseGet()`, `orElseThrow()`, `orNull()`, or `orUndefined()` to retrieve the value.
• gotcha The static factory method `Optional.ofNonNull()` will throw a `TypeError` if the provided argument is `null` or `undefined`. It is specifically designed for situations where you expect a non-null value.
  Fix: Use `Optional.ofNullable(value)` instead if the value might be `null` or `undefined`. Only use `ofNonNull` when you are certain the value is not null.
• breaking The `v2.0.0` release was initially abandoned due to deployment issues. While `v2.0.1` fixed these, developers targeting `v2` should ensure they use `v2.0.1` or newer to avoid potential problems.
  Fix: Upgrade to `typescript-optional@2.0.1` or a later compatible version.

Install

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

Imports

• Optional
  wrong:

  const { Optional } = require('typescript-optional');

  correct:

  import { Optional } from 'typescript-optional';

  Primarily designed for ESM and TypeScript; CommonJS `require` is generally discouraged in modern TypeScript projects.
• Optional (type import)
  wrong:

  import { Optional } from 'typescript-optional';

  correct:

  import type { Optional } from 'typescript-optional';

  Using `import type` is preferred for type-only imports to prevent accidental runtime side effects or bundle size issues.
• Optional.ofNullable
  wrong:

  new Optional(value);

  correct:

  Optional.ofNullable(value);

  Always use static factory methods like `ofNullable`, `ofNonNull`, or `empty` to create `Optional` instances, as the constructor may not be public or stable.

Quickstart

Demonstrates how to import, create, and perform common operations like checking presence, conditional execution, mapping, filtering, and providing default values with the `Optional` class.

import { Optional } from "typescript-optional";

// Example with a potentially null string
const userName: string | null = Math.random() > 0.5 ? "Alice" : null;
const optionalUserName: Optional<string> = Optional.ofNullable(userName);

console.log(`Is name present? ${optionalUserName.isPresent()}`);

// Using ifPresentOrElse to handle both cases
optionalUserName.ifPresentOrElse(
  (name) => console.log(`Hello, ${name}!`),
  () => console.log("User name is not available.")
);

// Map and filter operations
const nameLength: Optional<number> = optionalUserName
  .filter((name) => name.length > 3)
  .map((name) => name.length);

nameLength.ifPresent((len) => console.log(`Name length (if > 3): ${len}`));

// Providing a default value
const displayUserName: string = optionalUserName.orElse("Guest");
console.log(`Display name: ${displayUserName}`);

// Converting to nullable JavaScript types
const rawName: string | null = optionalUserName.orNull();
console.log(`Raw name (or null): ${rawName}`);