@marionebl/result v1.0.8

Rust Results for JavaScript

@marionebl/result

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

API

Named Constructors

• Err
• Ok
• from

Methods

• and
• err
• expect
• expectErr
• isErr
• isOk
• map
• mapErr
• mapOrElse
• ok
• or
• orElse
• sync
• transpose
• unwrap
• unwrapErr
• unwrapOr
• unwrapOrElse

Named Constructors

<Static> Err

▸ Err(err: Error): Err

Defined in result.ts:164

Create an Err from an Error

import * as assert from "assert";
import { Result } from "@marionebl/result";

async function main() {
  const exn = new Error("Something went wrong");
  const err = Result.from(exn);
  const asyncErr = Result.from(Promise.resolve().then(() => exn));

  assert.strictEqual(await err, await Result.Err(exn));
  assert.strictEqual(await asyncErr, await Result.Err(exn));
}

main().catch((err) => {
  throw err
});

Parameters:

Returns: Err

<Static> Ok

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

Defined in result.ts:139

Create an Ok from any payload

import * as assert from "assert";
import { Result } from "@marionebl/result";

async function main() {
  const ok = Result.Ok(1);
  const asyncOk = Result.Ok(Promise.resolve(1));

  assert.strictEqual(await ok, await Result.Ok(1));
  assert.strictEqual(await asyncOk, await Result.Ok(1));
}

main().catch((err) => {
  throw err
});

Type parameters:

Payload

Parameters:

Returns: Ok<Payload>

<Static> from

▸ from<Payload>(payload: Payload): Result<Payload>

Defined in result.ts:115

Create a Result from an unknown input payload or Error

• Error yields Err(Error)
• any yields Ok(any)

import * as assert from "assert";
import { Result } from "@marionebl/result";

async function main() {
  const ok = Result.from(1);
  const asyncOk = Result.from(Promise.resolve(1));

  const exn = new Error("Something went wrong");
  const err = Result.from(exn);
  const asyncErr = Result.from(Promise.resolve().then(() => exn));

  assert.strictEqual(await ok, await Result.Ok(1));
  assert.strictEqual(await asyncOk, await Result.Ok(1));

  assert.strictEqual(await err, await Result.Err(exn));
  assert.strictEqual(await asyncErr, await Result.Err(exn));
}

main().catch((err) => {
  throw err
});

Type parameters:

Payload

Parameters:

Returns: Result<Payload>

Methods

and

▸ and<T>(b: Result<T>): Promise<Result<Payload | T>>

Defined in result.ts:413

Returns b if the result is Ok, otherwise returns the Err value of self.

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

async function main() {
 const someA = Result.Ok('a');
 const someB = Result.Ok('b');
 const noneA = Result.Err(new Error('c'));
 const noneB = Result.Err(new Error('d'));

 const someSome = await someA.and(someB);
 const someNone = await someA.and(noneA);
 const noneSome = await noneA.and(someA);
 const noneNone = await noneB.and(noneA);

 assert.strictDeepEqual(await someSome.ok(), Option.Ok('b'));
 assert.strictDeepEqual(await someNone.err(), Result.Err(new Error('c')));
 assert.strictDeepEqual(await noneSome.err(), Result.Err(new Error('c')));
 assert.strictDeepEqual(await noneNone.err(), Result.Err(new Error('d')));
}

main().catch((err) => {
  throw err
});

Type parameters:

T

Parameters:

Returns: Promise<Result<Payload | T>>

err

▸ err(): Promise<Option<Error>>

Defined in result.ts:278

Converts from Result<T> to Option<T>.

Converts into an Option<T>, and discarding the success value, if any.

import * as assert from "assert";
import { Result } from "@marionebl/result";

async function main() {
 const ok = Result.Ok(1);
 const err = Result.Err(new Error('Something went wrong.'));

 assert.strictDeepEqual(await ok.ok(), Option.Some(1));
 assert.strictDeepEqual(await err.ok(), Option.None());
}

main().catch((err) => {
  throw err
});

Returns: Promise<Option<Error>>

expect

▸ expect(message: string): Promise<Payload>

Defined in result.ts:633

Unwraps a result, yielding the content of an Ok.

throws: Throws if the value is an Err, with a panic message including the passed message, and the content of the Err.

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

async function main() {
  const some = Result.Ok(1);
  assert.strictEqual(await some.expect("Booh!"), 1);

  const none = Result.Err(new Error("..."));
  assert.rejects(async () => await none.expect("Booh!"), new Error("Booh!"));
}

main().catch(err => {
  throw err;
});

Parameters:

Returns: Promise<Payload>

expectErr

▸ expectErr(message: string): Promise<Error>

Defined in result.ts:703

Unwraps a result, yielding the content of an Err.

throws: Throws if the value is an Ok, with a panic message including the passed message, and the content of the Ok.

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

async function main() {
  const some = Result.Ok(1);
  assert.rejects(async () => await some.expectErr("Booh!"), new Error("Booh!"))

  const none = Result.Err(new Error("..."));
  assert.strictEqual(await none.expectErr("Booh!"), new Error("..."));
}

main().catch(err => {
  throw err;
});

Parameters:

Returns: Promise<Error>

isErr

▸ isErr(): Promise<boolean>

Defined in result.ts:188

Returns true if the result is Err.

import * as assert from "assert";
import { Result } from "@marionebl/result";

async function main() {
 const ok = Result.Ok(1);
 const err = Result.Err(new Error('Something went wrong.'));

 assert.ok(!(await ok.isErr()));
 assert.ok(await ok.isOk());
}

main().catch((err) => {
  throw err
});

Returns: Promise<boolean>

isOk

▸ isOk(): Promise<boolean>

Defined in result.ts:217

Returns true if the result is Ok.

import * as assert from "assert";
import { Result } from "@marionebl/result";

async function main() {
 const ok = Result.Ok(1);
 const err = Result.Err(new Error('Something went wrong.'));

 assert.ok(await ok.isErr());
 assert.ok(!(await ok.isOk()));
}

main().catch((err) => {
  throw err
});

Returns: Promise<boolean>

map

▸ map<V>(fn: function): Promise<Ok<V> | Err>

Defined in result.ts:308

Maps a Result<T> to Result<V> by applying a function to a contained Ok value, leaving an Err value untouched.

import * as assert from "assert";
import { Result } from "@marionebl/result";

async function main() {
 const ok = Result.Ok(1);
 const expn = new Error('Something went wrong.');
 const err = Result.Err(expn);

 assert.strictDeepEqual(await ok.map(async i => i + 1).ok(), Option.Some(2));
 assert.strictDeepEqual(await err.map(async i => i + 1).err(), Option.Some(expn));
}

main().catch((err) => {
  throw err
});

Type parameters:

V

Parameters:

Returns: Promise<Ok<V> | Err>

mapErr

▸ mapErr(fn: function): Promise<Result<Payload>>

Defined in result.ts:372

Maps a Result<T, E> to Result<T, F> by applying a function to a contained Err value, leaving an Ok value untouched.

This function can be used to pass through a successful result while handling an error.

`ts import * as assert from "assert"; import { Result } from "@marionebl/result";

async function main() { const ok = Result.Ok(1); const expn = new Error('Something went wrong.'); const err = Result.Err(expn);

assert.strictDeepEqual(await ok.mapErr((err) => new Error(err.message + ' Booh!')).ok(), Option.Some(1)); assert.strictDeepEqual(await err.mapErr(err) => new Error(err.message + ' Booh!')).err(), Option.Some(new Error('Something went wrong. Booh!'))); }

main().catch((err) => { throw err });

Parameters:

Returns: Promise<Result<Payload>>

mapOrElse

▸ mapOrElse<V>(fallback: function, fn: function): Promise<Ok<V>>

Defined in result.ts:338

Maps a Result<T> to Result<V> by applying a function to a contained Ok value, leaving an Err value untouched.

import * as assert from "assert";
import { Result } from "@marionebl/result";

async function main() {
 const ok = Result.Ok(1);
 const expn = new Error('Something went wrong.');
 const err = Result.Err(expn);

 assert.strictDeepEqual(await ok.mapOrElse(() => 0, async i => i + 1).ok(), Option.Some(2));
 assert.strictDeepEqual(await err.mapOrElse(() => 0, async i => i + 1).ok(), Option.Some(0));
}

main().catch((err) => {
  throw err
});

Type parameters:

V

Parameters:

Returns: Promise<Ok<V>>

ok

▸ ok(): Promise<Option<Payload>>

Defined in result.ts:248

Converts from Result<T> to Option<T>.

Converts into an Option<T>, and discarding the error, if any.

import * as assert from "assert";
import { Result } from "@marionebl/result";

async function main() {
 const ok = Result.Ok(1);
 const err = Result.Err(new Error('Something went wrong.'));

 assert.strictDeepEqual(await ok.ok(), Option.Some(1));
 assert.strictDeepEqual(await err.ok(), Option.None());
}

main().catch((err) => {
  throw err
});

Returns: Promise<Option<Payload>>

or

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

Defined in result.ts:467

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

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

async function main() {
  {
    const ok = Result.Ok(2);
    const err = Result.Err(new Error(""));
    const result = await ok.or(err);
    assert.deepStrictEqual(await result.sync(), await Result.Ok(2).sync());
  }

  {
    const err = Result.Err(new Error(""));
    const ok = Result.Ok(2);
    const result = await err.or(ok);
    assert.deepStrictEqual(await result.sync(), await Result.Ok(2).sync());
  }

  {
    const a = Result.Ok(100);
    const b = Result.Ok(2);
    const result = await a.or(b);
    assert.deepStrictEqual(await result.sync(), await a.sync());
  }

  {
    const a = Result.Err(new Error(""));
    const b = Result.Err(new Error(""));
    const result = await a.or(b);
    assert.deepStrictEqual(await result.sync(), await Option.Err(new Error("")).sync());
  }
}

 main().catch((err) => {
  throw err
});

Type parameters:

T : Result<V>

V

Parameters:

Returns: Promise<this | T>

orElse

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

Defined in result.ts:517

Calls fn if the result is Err, otherwise returns the Ok value.

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

async function main() {
  {
    const ok = Result.Ok(2);
    const err = Result.Err(new Error(""));
    const result = await ok.orElse(async () => err);
    assert.deepStrictEqual(await result.sync(), await Result.Ok(2).sync());
  }

  {
    const err = Result.Err(new Error(""));
    const ok = Result.Ok(2);
    const result = await err.orElse(async () => ok);
    assert.deepStrictEqual(await result.sync(), await Result.Ok(2).sync());
  }

  {
    const a = Result.Ok(100);
    const b = Result.Ok(2);
    const result = await a.orElse(async () => b);
    assert.deepStrictEqual(await result.sync(), await a.sync());
  }

  {
    const a = Result.Err(new Error(""));
    const b = Result.Err(new Error(""));
    const result = await a.orElse(async () => b);
    assert.deepStrictEqual(await result.sync(), await Option.Err(new Error("")).sync());
  }
}

 main().catch((err) => {
  throw err
});

Type parameters:

T : Result<V>

V

Parameters:

Returns: Promise<this | T>

sync

▸ sync(): Promise<Result<Payload>>

Defined in result.ts:74

Returns: Promise<Result<Payload>>

transpose

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

Defined in result.ts:717

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

unwrap

▸ unwrap(): Promise<Payload>

Defined in result.ts:602

Unwraps a result, yielding the content of an Ok.

throws: Throws if the value is an Err, with a panic message provided by the Err value.

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

async function main() {
  const some = Result.Ok(1);
  assert.strictEqual(await some.unwrap(), 1);

  const none = Result.Err(new Error("..."));
  assert.rejects(async () => await none.unwrap(), new Error("..."));
}

main().catch(err => {
  throw err;
});

Returns: Promise<Payload>

unwrapErr

▸ unwrapErr(): Promise<Error>

Defined in result.ts:668

Unwraps a result, yielding the content of an Err.

throws: Throws if the value is an Ok, with a panic message including the content of the Ok.

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

async function main() {
  const some = Result.Ok(1);
  assert.rejects(async () => await some.unwrapErr(), new Error("1"))

  const none = Result.Err(new Error("..."));
  assert.strictEqual(await none.unwrapErr(), new Error("..."));
}

main().catch(err => {
  throw err;
});

Returns: Promise<Error>

unwrapOr

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

Defined in result.ts:545

Unwraps a result, yielding the content of an Ok. Else, it returns b.

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

async function main() {
  const some = Result.Ok(1);
  assert.strictEqual(await some.unwrapOr(2), 1);

  const none = Result.Err(new Error(""));
  assert.strictEqual(await none.unwrapOr(2), 2);
}

main().catch(err => {
  throw err;
});

Type parameters:

T

Parameters:

Returns: Promise<Payload | T>

unwrapOrElse

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

Defined in result.ts:573

Unwraps a result, yielding the content of an Ok. If the value is an Err then it calls fn with its value.

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

async function main() {
  const some = Result.Ok(1);
  assert.strictEqual(await some.unwrapOrElse(async () => 2), 1);

  const none = Result.Err(new Error("..."));
  assert.strictEqual(await none.unwrapOrElse(async (err) => err.message.length), 3);
}

main().catch(err => {
  throw err;
});

Type parameters:

T

Parameters:

Returns: Promise<Payload | T>

License

MIT. Copyright 2019 - present Mario Nebl