@fp-utils/option NPM

Option

Option represents the presence of a value Some or the absence of a value None. It's commonly utilized to manage computations that might or might not yield a result, or those that could potentially fail.

Option is particularly useful, when dealing with operations that may return null or undefined values, providing a structured and safe approach to manage such scenarios.

By using option, the need for imperative and explicit null or undefined checks diminishes, reducing code noise and allowing for clearer focus on essential domain logic. Essentially, the Option enables to focus primarily on the 'happy path'.

import { Option } from "@fp-utils/option";

type BookId = number;
type BookName = string;

const books = new Map<BookId, BookName>([
  [1, "The Hobbit"],
  [2, "The Fellowship of the Ring"],
]);

const tryGetBook = (id: BookId): Option<BookName> => Option.from(books.get(id));

// Evaluates to None
const bookNotFound = tryGetBook(0);

// Evaluates to Some "The Hobbit"
const bookFound = tryGetBook(1);

Usage

Constructors

Similar as how String or Number constructors are used in JavaScript:

Use Some(42) constructor to wrap a value for existing value and for non-existent value use the static None class.

import { None, Some } from "@fp-utils/option";

const some = Some(42);
const none = None;

Option methods

Option methods are chainable functions that allow for a sequence of operation with the contained value T in the Option.

`Option.filter`

Signature: (predicate: (value: T) => boolean): boolean

Option.filter returns a boolean that is evaluated with the given predicate function which is applied on the option value T. None evaluates to false.

import { None, Some } from "@fp-utils/option";

Some(2)
  .filter((x) => x >= 5); // evaluates to false

Some(42)
  .filter((x) => x >= 5); // evaluates to true

None
  .filter((x) => x >= 5); // evaluates to false

`Option.flatMap`

Signature: (fn: (value: T) => Option): Option

Option.flatMap applies a function fn to the content of option T and transforms it into an option U.

import { None, Option, Some } from "@fp-utils/option";

type TryParse = (input: string) => Option<number>;

const tryParse: TryParse = (input: string) => {
  const value = parseInt(input);
  return isNaN(value) ? None : Some(value);
};

Some("42")
  .flatMap(tryParse); // Evaluates to Some 42

Some("Forty-two")
  .flatMap(tryParse); // Evaluates to None

None
  .flatMap(tryParse); // Evaluates to None

`Option.inspect`

Signature: (fn: (value: T) => void): Option<T>

Option.inspect calls the provided function fn with a reference to the contained option value T if the option is some.

import { None, Some } from "@fp-utils/option";

Some(42)
  .inspect((x) => console.log(x * 2)); // Prints 84

None
  .inspect((x) => console.log(x * 2)); // Prints nothing

`Option.isNone`

Signature: (): this is None

Option.isNone returns true if the option is None

import { None, Some } from "@fp-utils/option";

Some(42).isNone(); // Evaluates to false

None.isNone(); // Evaluates to true

`Option.isSome`

Signature: <T>(): this is Some<T>

Option.isSome returns true if the option is Some

import { None, Some } from "@fp-utils/option";

Some(42).isSome(); // Evaluates to true

None.isSome(); // Evaluates to false

`Option.map`

Signature: (fn: (value: T) => U): Option

Option.map applies a function fn to option value T and transforms it into value U.

import { None, Some } from "@fp-utils/option";

Some(42)
  .map((x) => x * 2); // Evaluates to Some 84

None
  .map((x) => x * 2); // Evaluates to None

`Option.match`

Signature: <U1, U2>(onSome: (value: T) => U1, onNone: () => U2): U1 | U2

Option.match transforms the option value T into U1 using onSome and then returns U1. If the option is None, onNone is called and U2 returned.

import { None, Some } from "@fp-utils/option";

Some(42)
  .match((x) => x * 2, () => 99); // Evaluates to 84

None
  .match((x) => x * 2, () => 99); // Evaluates to 99

`Option.toJSON`

Signature: (): T | null

Option.toJSON serializes the option into JSON format. If the option is None, it will be serialized to null. If the option is Some, it will be serialized to the unwrapped value T.

import { None, Some } from "@fp-utils/option";

Some(42)
  .toJSON(); // Evaluates to 42

None
  .toJSON(); // Evaluates to null

`Option.toString`

Signature: (): "Some(value)" | "None"

Option.toString returns the string representation of the result and the stringified value as Some(value) if the result is Some or None if the result is None.

import { None, Some } from "@fp-utils/option";

Some(42)
  .toString(); // Evaluates to "Some(42)"

None
  .toString(); // Evaluates to "None"

`Option.unwrap`

Signature: (): T

Option.unwrap returns the value T from the associated option if it is Some; otherwise it will throw.

import { None, Some } from "@fp-utils/option";

Some(42).unwrap(); // Evaluates to 42

None.unwrap(); // Throws an exception!

`Option.unwrapOr`

Signature: (defaultValue: T): T

Option.unwrapOr returns the value T from the associated option or returns the default value if the option is None.

import { None, Some } from "@fp-utils/option";

Some(42).unwrapOr(99); // Evaluates to 42

None.unwrapOr(99); // Evaluates to 99

`Option.zip`

Signature: (option: Option): Option<[T, U]>

Option.zip combines two option values into a tuple and returns the tuple wrapped in Option.

import { None, Some } from "@fp-utils/option";

Some(42).zip(Some(84)); // Evaluates to Some<[42, 84]>

Some(42).zip(None); // Evaluates to None

None.zip(Some(84)); // Evaluates to None

Option higher-order functions

Option higher-order functions allow for Option value T chainability within callbacks like Promise.then.

import { Option } from "@fp-utils/option";

Promise.resolve(42)
  .then(Option.from)
  .then(Option.inspect(console.log))
  .then(Option.map((value) => value + 10))
  .then(Option.unwrap); // Evaluates to 52

`Option.filter`

Signature: (predicate: (value: T) => boolean): (option: Option<T>) => boolean

Option.filter returns a boolean that is evaluated with the given predicate function which is applied on the option value T. None evaluates to false.

import { None, Option, Some } from "@fp-utils/option";

Option
  .filter((x: number) => x >= 5)(Some(2)); // evaluates to false

Option
  .filter((x: number) => x >= 5)(Some(42)); // evaluates to true

Option
  .filter((x: number) => x >= 5)(None); // evaluates to false

`Option.flatMap`

Signature: flatMap(fn: (value: T) => Option): (option: Option<T>) => Option

Option.flatMap applies a function fn to the content of option T and transforms it into an option U.

import { None, Option, Some } from "@fp-utils/option";

type TryParse = (input: string) => Option<number>;

const tryParse: TryParse = (input: string) => {
  const value = parseInt(input);
  return isNaN(value) ? None : Some(value);
};

Option
  .flatMap(tryParse)(Some("42")); // Evaluates to Some 42

Option
  .flatMap(tryParse)(Some("Forty-two")); // Evaluates to None

Option
  .flatMap(tryParse)(None); // Evaluates to None

`Option.inspect`

Signature: inspect(fn: (value: T) => void): (option: Option<T>) => Option<T>

Option.inspect calls the provided function fn with a reference to the contained option value T if the option is some.

import { None, Option, Some } from "@fp-utils/option";

Option
  .inspect((x: number) => console.log(x * 2))(Some(42)); // Prints 84

Option
  .inspect((x: number) => console.log(x * 2))(None); // Prints nothing

`Option.map`

Signature: map(fn: (value: T) => U): (option: Option<T>) => Option

Option.map applies a function fn to option value T and transforms it into value U.

import { None, Option, Some } from "@fp-utils/option";

Option
  .map((x: number) => x * 2)(Some(42)); // Evaluates to Some 84

Option
  .map((x: number) => x * 2)(None); // Evaluates to None

`Option.match`

Signature: match(onSome: (value: T) => U1, onNone: () => U2): (option: Option<T>) => U1 | U2

Option.match transforms the option value T into U1 using onSome and then returns U1. If the option is None, onNone is called and U2 returned.

import { None, Option, Some } from "@fp-utils/option";

Option
  .match((x: number) => x * 2, () => 99)(Some(42)); // Evaluates to 84

Option
  .match((x: number) => x * 2, () => 99)(None); // Evaluates to 99

`Option.unwrapOr`

Signature: unwrapOr(defaultValue: T): (option: Option<T>) => T

Option.unwrapOr returns the value T from the associated option or returns the default value if the option is None.

import { None, Option, Some } from "@fp-utils/option";

Option
  .unwrapOr(99)(Some(42)); // Evaluates to 42

Option
  .unwrapOr(99)(None); // Evaluates to 99

`Option.zip`

Signature: zip(option: Option): (option: Option<T>) => Option<[T, U]>

Option.zip combines two option values into a tuple and returns the tuple wrapped in Option.

import { None, Option, Some } from "@fp-utils/option";

Option
  .zip(Some(84))(Some(42)); // Evaluates to Some<[42, 84]>

Option
  .zip(None)(Some(42)); // Evaluates to None

Option
  .zip(Some(84))(None); // Evaluates to None

Option static methods

Static methods for working with options.

`Option.all`

Signature: all(options: Option<T>[]): Option<T[]>

Option.all returns all Some option values as an array within a Some option. If None option exists in the array, None is returned. An empty array signifies success, resulting in a Some with an empty array.

import { None, Option, Some } from "@fp-utils/option";

Option
  .all([]); // Evaluates to Some []

Option
  .all([Some(10), Some(42), Some(84)]); // Evaluates to Some [10, 42, 84]

Option
  .all([Some(10), Some(42), None, Some(84)]); // Evaluates to None

Option
  .all([None]); // Evaluates to None

`Option.any`

Signature: any(options: Option<T>[]): Option<T>

Option.any returns the first Some option encountered. If no Some options are found in the array None is returned.

import { None, Option, Some } from "@fp-utils/option";

Option
  .any([]); // Evaluates to None

Option
  .any([Some(10), Some(42), Some(84)]); // Evaluates to Some 10

Option
  .any([Some(10), Some(42), None, Some(84)]); // Evaluates to None

Option
  .any([None]); // Evaluates to None

`Option.from`

Signature: from(value: T | (() => T)): From<T>

Option.from converts a nullable value, non-nullable value, a function or a promise to an option.

import { Option } from "@fp-utils/option";

Option
  .from(undefined); // Evaluates to None

Option
  .from(null); // Evaluates to None

Option
  .from(42); // Evaluates to Some 42

Option
  .from(() => 42); // Evaluates to Some 42

Option
  .from(() => Promise.resolve(42)); // Evaluates to Promise<Some 42>

Option
  .from(() => Promise.reject()); // Evaluates to Promise<None>

Option
  .from(Promise.resolve(42)); // Evaluates to Promise<Some 42>

Option
  .from(Promise.resolve(undefined)); // Evaluates to Promise<None>

Option
  .from(Promise.reject()); // Evaluates to Promise<None>

`Option.isNone`

Signature: isNone(option: Option<T>): option is None

Option.isNone returns true if the option is None

import { None, Option, Some } from "@fp-utils/option";

Option
  .isNone(Some(42)); // Evaluates to false

Option
  .isNone(None); // Evaluates to true

`Option.isSome`

Signature: isSome(option: Option<T>): option is Some<T>

Option.isSome returns true if the option is Some

import { None, Option, Some } from "@fp-utils/option";

Option
  .isSome(Some(42)); // Evaluates to true

Option
  .isSome(None); // Evaluates to false

`Option.none`

Signature: none(): None

Option.none returns a None option.

import { Option } from "@fp-utils/option";

Option
  .none(); // Evaluates to None

`Option.some`

Signature: some(value: NonNullable<T>): Some<NonNullable<T>>

Option.some creates an option Some with value T.

import { Option } from "@fp-utils/option";

Option
  .some(42); // Evaluates to Some 42

Option
  .some(undefined); // Throws an exception or compiler error!

Option
  .some(null); // Throws an exception or compiler error!

`Option.toJSON`

Signature: toJSON(option: Option<T>): T | null

Option.toJSON serializes the option into JSON format. If the option is None, it will be serialized to null. If the option is Some, it will be serialized to the unwrapped value T.

import { None, Option, Some } from "@fp-utils/option";

Option
  .toJSON(Some(42)); // Evaluates to 42

Option
  .toJSON(None); // Evaluates to null

`Option.toString`

Signature: toString(option: Option<T>): "Some(value)" | "None"

Option.toString returns the string representation of the result and the stringified value as Some(value) if the result is Some or None if the result is None.

import { None, Option, Some } from "@fp-utils/option";

Option
  .toString(Some(42)); // Evaluates to "Some(42)"

Option
  .toString(None); // Evaluates to "None"

`Option.unwrap`

Signature: unwrap(option: Option<T>): T

Option.unwrap returns the value T from the associated option if it is Some; otherwise it will throw.

import { None, Option, Some } from "@fp-utils/option";

Option
  .unwrap(Some(42)); // Evaluates to 42

Option
  .unwrap(None); // Throws an exception!

typescript functional-programming option

1 year ago

1 year ago

1 year ago

11 months ago

1 year ago