Rust Options for JavaScript

@marionebl/option

• Implements full Rust Options API
• Narrow types for easy usage
• Extensive documentation

API

Named Constructors

• .from
• .None
• .Some

Methods

• and
• andThen
• expect
• filter
• getOrInsert
• getOrInsertWith
• isNone
• isSome
• map
• mapOr
• mapOrElse
• okOr
• okOrElse
• or
• orElse
• replace
• take
• transpose
• unwrap
• unwrapOr
• unwrapOrElse
• xor
• None
• Some
• from

Named Constructors

None

▸ None(): None

Defined in option.ts:1037

Create a None value Option

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const none = Option.from(undefined);
assert.strictEqual(some.isNone(), true);

Returns: None

Some

▸ Some<Payload>(payload: Payload): Some<Payload>

Defined in option.ts:1022

Create a Some value Option

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.Some(2);
assert.strictEqual(some.isSome(), true);
assert.strictEqual(some.unwrap(), 2);

Type parameters:

Payload

Parameters:

| Name | Type | | ------ | ------ | | payload | Payload |

Returns: Some<Payload>

from

▸ from<Payload>(payload?: Payload): Option<Payload>

Defined in option.ts:1006

Create a new Option from unknown input

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.from(2);
assert.strictEqual(some.isSome(), true);
assert.strictEqual(some.unwrap(), 2);

const none = Option.from(undefined);
assert.strictEqual(some.isNone(), true);

Type parameters:

Payload

Parameters:

| Name | Type | | ------ | ------ | | Optional payload | Payload |

Returns: Option<Payload>

Methods

and

▸ and<T,V>(b: T): T | None

Defined in option.ts:1337

Returns None if the option is None, otherwise returns b.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

{
 const some = Option.Some("Thing");
 const none = Option.None();
 assert.deepStrictEqual(some.and(none), Option.None());
}

{
 const none = Option.None();
 const some = Option.Some("Thing");
 assert.deepStrictEqual(none.and(some), Option.None());
}

{
 const a = Option.Some("a");
 const b = Option.Some("b");
 assert.deepStrictEqual(a.and(b), b);
}

Type parameters:

T : Option<V>

V

Parameters:

| Name | Type | | ------ | ------ | | b | T |

Returns: T | None

andThen

▸ andThen<T,V>(fn: function): T | None

Defined in option.ts:1380

Returns None if the option is None, otherwise calls fn: (p: Payload) => T with the wrapped value p and returns the result T.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const square = (input: number) => Option.Some(input * input);
const nope = (_: unknown) => Option.None();

const a = Some(2)
 .andThen(square)
 .andThen(square);

assert.deepStrictEqual(a, Option.Some(16));

const b = Some(2)
 .andThen(square)
 .andThen(nope);

assert.deepStrictEqual(b, None);

const c = Some(2)
 .andThen(nope)
 .andThen(square);

assert.deepStrictEqual(c, None);

const d = None()
 .andThen(square)
 .andThen(square);

assert.deepStrictEqual(d, None);

Type parameters:

T : Option<V>

V

Parameters:

| Name | Type | | ------ | ------ | | fn | function |

Returns: T | None

expect

▸ expect(message: string): Payload

Defined in option.ts:1093

Unwraps an option, yielding the content of a Some.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.Some(2);
assert.strictEqual(some.expect("something bad"), 2);

const none = Option.None();
assert.throws(() => none.expect("something bad"), new Error("something bad"));

throws: Throws if the value is a None with a custom error message provided by {message}.

Parameters:

| Name | Type | | ------ | ------ | | message | string |

Returns: Payload

filter

▸ filter(fn: function): Option<Payload>

Defined in option.ts:1407

Returns None if the option is None, otherwise calls predicate with the wrapped value and returns:

• Some(t) if predicate returns true (where t is the wrapped value), and
• None if predicate returns false.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const isEven = (input: number) => input % 2 === 0;

assert.deepStrictEqual(Option.None().map(isEven), Option.None);
assert.deepStrictEqual(Option.Some(3).map(isEven), Option.None);
assert.deepStrictEqual(Option.Some(4).map(isEven), Option.Some(4));

Parameters:

| Name | Type | | ------ | ------ | | fn | function |

Returns: Option<Payload>

getOrInsert

▸ getOrInsert(payload: Payload): Some<Payload>

Defined in option.ts:1560

Inserts payload into the option if it is None.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.Some(2);
const none = Option.None();

const got = some.getOrInsert(5);
const inserted = none.getOrInsert(5);

assert.deepStrictEqual(got, some);
assert.deepStrictEqual(got, Option.Some(5));

Parameters:

| Name | Type | | ------ | ------ | | payload | Payload |

Returns: Some<Payload>

getOrInsertWith

▸ getOrInsertWith(fn: function): Some<Payload>

Defined in option.ts:1586

Inserts a value computed from fn into the option if it is None

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.Some(2);
const none = Option.None();

const got = some.getOrInsert(() => 5);
const inserted = none.getOrInsert(() => 5);

assert.deepStrictEqual(got, some);
assert.deepStrictEqual(got, Option.Some(5));

Parameters:

| Name | Type | | ------ | ------ | | fn | function |

Returns: Some<Payload>

isNone

▸ isNone(): boolean

Defined in option.ts:1073

Returns true if the option is a None value.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.Some(2);
assert.strictEqual(some.isNone(), false);

const none = Option.None();
assert.strictEqual(some.isNone(), true);

Returns: boolean

isSome

▸ isSome(): boolean

Defined in option.ts:1055

Returns true if the option is a Some value.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.Some(2);
assert.strictEqual(some.isSome(), true);

const none = Option.None();
assert.strictEqual(some.isNone(), false);

Returns: boolean

map

▸ map<T>(fn: function): Option<T>

Defined in option.ts:1189

Maps an Option

to Option by applying a function (p: P) => T to a contained value p.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const someString = Option.Some("Hello, World!");
const someLength = someString.map((s) => s.length);

assert.strictEqual(someLength.unwrap(), 13);

const none = Option.None()
const maybe = someString.map((s) => s.length);

assert.strictEqual(maybe.isNone(), true);
assert.throws(() => maybe.unwrap());

Type parameters:

T

Parameters:

| Name | Type | | ------ | ------ | | fn | function |

Returns: Option<T>

mapOr

▸ mapOr<V,T>(fallback: V, fn: function): V | T

Defined in option.ts:1217

Applies a function (p: P) => T to the contained value p (if any), or returns the provided fallback (if not).

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const someString = Option.Some("Thing");
const someLength = someString.mapOr((s) => s.length, 42);

assert.strictEqual(someLength.unwrap(), 5);

const none = Option.None();
const maybe = someString.mapOr((s) => s.length, 42);

assert.strictEqual(someLength.isSome(), true);
assert.strictEqual(someLength.unwrap(), 42);

Type parameters:

V

T

Parameters:

| Name | Type | | ------ | ------ | | fallback | V | | fn | function |

Returns: V | T

mapOrElse

▸ mapOrElse<V,T>(fallback: function, fn: function): V | T

Defined in option.ts:1245

Applies a function (p: P) => T to the contained value p (if any), or computes a fallback via a function () => V (if not).

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const someString = Option.Some("Thing");
const someLength = someString.mapOr((s) => s.length, () => 42);

assert.strictEqual(someLength.unwrap(), 5);

const none = Option.None();
const maybe = someString.mapOr((s) => s.length, () => 42);

assert.strictEqual(someLength.isSome(), true);
assert.strictEqual(someLength.unwrap(), 42);

Type parameters:

V

T

Parameters:

| Name | Type | | ------ | ------ | | fallback | function | | fn | function |

Returns: V | T

okOr

▸ okOr(message: string): Result<Payload>

Defined in option.ts:1276

Transforms the Option<Payload> into a Result<Payload, Error>, mapping Some(Payload) to Ok(Payload) and None to Err(err).

import * as assert from 'assert';
import { Option } from '@marionebl/option';
import { Result } from '@marionebl/result';

const some = Option.Some("Thing");
const ok = some.okOr("Something went wrong");

assert.deepStrictEqual(ok, Result.Ok("Thing"));

const none = Option.None();
const err = some.okOr("Something went wrong");

assert.deepStrictEqual(err, Result.Err(new Error("Something went wrong")));

Parameters:

| Name | Type | | ------ | ------ | | message | string |

Returns: Result<Payload>

okOrElse

▸ okOrElse(fn: function): Result<Payload>

Defined in option.ts:1303

Transforms the Option<Payload> into a Result<Payload, Error>, mapping Some(Payload) to Ok(Payload) and None to Err(err).

import * as assert from 'assert';
import { Option } from '@marionebl/option';
import { Result } from '@marionebl/result';

const some = Option.Some("Thing");
const ok = some.okOrElse(() => "Something went wrong");

assert.deepStrictEqual(ok, Result.Ok("Thing"));

const none = Option.None();
const err = some.okOrElse(() => "Something went wrong");

assert.deepStrictEqual(err, Result.Err(new Error("Something went wrong")));

Parameters:

| Name | Type | | ------ | ------ | | fn | function |

Returns: Result<Payload>

or

▸ or<T,V>(b: T): this | T

Defined in option.ts:1451

Returns the option if it contains a value, otherwise returns b.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

{
  const some = Option.Some(2);
  const none = Option.None();
  assert.deepStrictEqual(some.or(none), Option.Some(2));
}

{
  const none = Option.None();
  const some = Option.Some(2);
  assert.deepStrictEqual(none.or(some), Option.Some(2));
}

{
  const a = Option.Some(100);
  const b = Option.Some(2);
  assert.deepStrictEqual(a.or(b), a);
}

{
  const a = Option.None();
  const b = Option.None();
  assert.deepStrictEqual(a.or(b), Option.None());
}

Type parameters:

T : Option<V>

V

Parameters:

| Name | Type | | ------ | ------ | | b | T |

Returns: this | T

orElse

▸ orElse<T,V>(fn: function): this | T

Defined in option.ts:1491

Returns the option if it contains a value, otherwise calls fn and returns the result.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

{
  const some = Option.Some(2);
  const none = Option.None();
  assert.deepStrictEqual(some.orElse(() => none), Option.Some(2));
}

{
  const none = Option.None();
  const some = Option.Some(2);
  assert.deepStrictEqual(none.orElse(() => some), Option.Some(2));
}

{
  const a = Option.Some(100);
  const b = Option.Some(2);
  assert.deepStrictEqual(a.orElse(() => b), a);
}

{
  const a = Option.None();
  const b = Option.None();
  assert.deepStrictEqual(a.orElse(() => b), Option.None());
}

Type parameters:

T : Option<V>

V

Parameters:

| Name | Type | | ------ | ------ | | fn | function |

Returns: this | T

replace

▸ replace(payload: Payload): Option<Payload>

Defined in option.ts:1631

Replaces the actual value in the option by the value given in parameter, returning the old value if present, leaving a Some in its place.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const a = Option.Some(2);
const b = a.replace(5);

assert.deepStrictEqual(a, Option.Some(2));
assert.deepStrictEqual(b, Option.Some(5));

Parameters:

| Name | Type | | ------ | ------ | | payload | Payload |

Returns: Option<Payload>

take

▸ take(): Option<Payload>

Defined in option.ts:1609

Takes the value out of the option, leaving a None in its place.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const a = Option.Some(2);
const b = a.take();

assert.deepStrictEqual(a, Option.None());
assert.deepStrictEqual(b, Option.Some(2));

Returns: Option<Payload>

transpose

▸ transpose(): Promise<Result<Option<Payload>>>

Defined in option.ts:1654

Transposes an Option of a Result into Result of an Option.

None will be mapped to Ok(None). Some(Ok(_)) and Some(Err(_)) will be mapped to Ok(Some(_)) and Err(_).

import * as assert from 'assert';
import { Option } from '@marionebl/option';
import { Result } from '@marionebl/result';

const ok = Result.Ok(Option.Some(2));
const some = Option.Some(Result.Ok(2));

assert.deepStrictEqual(ok, some.transpose());

Returns: Promise<Result<Option<Payload>>>

unwrap

▸ unwrap(): Payload

Defined in option.ts:1117

Unwraps an option, yielding the content of a Some.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.Some(2);
assert.strictEqual(some.unwrap(), 2);

const none = Option.None();
assert.throws(() => none.unwrap());

throws: Throws if the value is a None

Returns: Payload

unwrapOr

▸ unwrapOr<T>(fallback: T): Payload | T

Defined in option.ts:1139

Returns the contained value or a fallback.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.Some(1);
assert.strictEqual(some.unwrapOr(2), 1);

const none = Option.None();
assert.strictEqual(none.unwrapOr(2), 2);

Type parameters:

T

Parameters:

| Name | Type | | ------ | ------ | | fallback | T |

Returns: Payload | T

unwrapOrElse

▸ unwrapOrElse<T>(fn: function): Payload | T

Defined in option.ts:1162

Returns the contained value or computes it from a closure.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

const some = Option.Some(1);
assert.strictEqual(some.unwrapOrElse(() => 2), 1);

const none = Option.None();
assert.strictEqual(none.unwrapOr(() => 2), 2);

Type parameters:

T

Parameters:

| Name | Type | | ------ | ------ | | fn | function |

Returns: Payload | T

xor

▸ xor<T,V>(b: T): this | T | None

Defined in option.ts:1531

Returns Some if exactly one of this or b is Some, otherwise returns None.

import * as assert from 'assert';
import { Option } from '@marionebl/option';

{
  const some = Option.Some(2);
  const none = Option.None();
  assert.deepStrictEqual(some.xor(none), Option.Some(2));
}

{
  const none = Option.None();
  const some = Option.Some(2);
  assert.deepStrictEqual(none.xor(some, Option.Some(2));
}

{
  const a = Option.Some(100);
  const b = Option.Some(2);
  assert.deepStrictEqual(a.xor(b), Option.None());
}

{
  const a = Option.None();
  const b = Option.None();
  assert.deepStrictEqual(a.xor(b), Option.None());
}

Type parameters:

T : Option<V>

V

Parameters:

| Name | Type | | ------ | ------ | | b | T |

Returns: this | T | None

License

MIT. Copyright 2019 - present Mario Nebl