{"id":13469590,"url":"https://github.com/supermacro/neverthrow","last_synced_at":"2025-05-13T15:06:56.158Z","repository":{"id":37072035,"uuid":"183857874","full_name":"supermacro/neverthrow","owner":"supermacro","description":"Type-Safe Errors for JS \u0026 TypeScript","archived":false,"fork":false,"pushed_at":"2025-03-11T15:06:02.000Z","size":2004,"stargazers_count":5412,"open_issues_count":55,"forks_count":111,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-06T14:51:11.687Z","etag":null,"topics":["functional-programming","hacktoberfest","hacktoberfest-accepted","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supermacro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-28T05:02:32.000Z","updated_at":"2025-05-06T13:21:46.000Z","dependencies_parsed_at":"2023-12-21T21:23:26.599Z","dependency_job_id":"3d743372-c438-400a-9087-7114ef6a3cfb","html_url":"https://github.com/supermacro/neverthrow","commit_stats":{"total_commits":414,"total_committers":37,"mean_commits":11.18918918918919,"dds":0.5797101449275363,"last_synced_commit":"cab111f3378fd5bd0810b543d481185796333474"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermacro%2Fneverthrow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermacro%2Fneverthrow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermacro%2Fneverthrow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supermacro%2Fneverthrow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supermacro","download_url":"https://codeload.github.com/supermacro/neverthrow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253969226,"owners_count":21992262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["functional-programming","hacktoberfest","hacktoberfest-accepted","typescript"],"created_at":"2024-07-31T15:01:46.100Z","updated_at":"2025-05-13T15:06:56.119Z","avatar_url":"https://github.com/supermacro.png","language":"TypeScript","readme":"# NeverThrow 🙅\n\n[![GitHub Workflow Status](https://github.com/supermacro/neverthrow/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/supermacro/neverthrow/actions)\n\n## Description\n\nEncode failure into your program.\n\nThis package contains a `Result` type that represents either success (`Ok`) or failure (`Err`).\n\nFor asynchronous tasks, `neverthrow` offers a `ResultAsync` class which wraps a `Promise\u003cResult\u003cT, E\u003e\u003e` and gives you the same level of expressivity and control as a regular `Result\u003cT, E\u003e`.\n\n`ResultAsync` is `thenable` meaning it **behaves exactly like a native `Promise\u003cResult\u003e`** ... except you have access to the same methods that `Result` provides without having to `await` or `.then` the promise! Check out [the wiki](https://github.com/supermacro/neverthrow/wiki/Basic-Usage-Examples#asynchronous-api) for examples and best practices.\n\n\u003e Need to see real-life examples of how to leverage this package for error handling? See this repo: https://github.com/parlez-vous/server\n\n\u003cdiv id=\"toc\"\u003e\u003c/div\u003e\n\n## Table Of Contents\n\n* [Installation](#installation)\n* [Recommended: Use `eslint-plugin-neverthrow`](#recommended-use-eslint-plugin-neverthrow)\n* [Top-Level API](#top-level-api)\n* [API Documentation](#api-documentation)\n  + [Synchronous API (`Result`)](#synchronous-api-result)\n    - [`ok`](#ok)\n    - [`err`](#err)\n    - [`Result.isOk` (method)](#resultisok-method)\n    - [`Result.isErr` (method)](#resultiserr-method)\n    - [`Result.map` (method)](#resultmap-method)\n    - [`Result.mapErr` (method)](#resultmaperr-method)\n    - [`Result.unwrapOr` (method)](#resultunwrapor-method)\n    - [`Result.andThen` (method)](#resultandthen-method)\n    - [`Result.asyncAndThen` (method)](#resultasyncandthen-method)\n    - [`Result.orElse` (method)](#resultorelse-method)\n    - [`Result.match` (method)](#resultmatch-method)\n    - [`Result.asyncMap` (method)](#resultasyncmap-method)\n    - [`Result.andTee` (method)](#resultandtee-method)\n    - [`Result.orTee` (method)](#resultortee-method)\n    - [`Result.andThrough` (method)](#resultandthrough-method)\n    - [`Result.asyncAndThrough` (method)](#resultasyncandthrough-method)\n    - [`Result.fromThrowable` (static class method)](#resultfromthrowable-static-class-method)\n    - [`Result.combine` (static class method)](#resultcombine-static-class-method)\n    - [`Result.combineWithAllErrors` (static class method)](#resultcombinewithallerrors-static-class-method)\n    - [`Result.safeUnwrap()`](#resultsafeunwrap)\n  + [Asynchronous API (`ResultAsync`)](#asynchronous-api-resultasync)\n    - [`okAsync`](#okasync)\n    - [`errAsync`](#errasync)\n    - [`ResultAsync.fromThrowable` (static class method)](#resultasyncfromthrowable-static-class-method)\n    - [`ResultAsync.fromPromise` (static class method)](#resultasyncfrompromise-static-class-method)\n    - [`ResultAsync.fromSafePromise` (static class method)](#resultasyncfromsafepromise-static-class-method)\n    - [`ResultAsync.map` (method)](#resultasyncmap-method)\n    - [`ResultAsync.mapErr` (method)](#resultasyncmaperr-method)\n    - [`ResultAsync.unwrapOr` (method)](#resultasyncunwrapor-method)\n    - [`ResultAsync.andThen` (method)](#resultasyncandthen-method)\n    - [`ResultAsync.orElse` (method)](#resultasyncorelse-method)\n    - [`ResultAsync.match` (method)](#resultasyncmatch-method)\n    - [`ResultAsync.andTee` (method)](#resultasyncandtee-method)\n    - [`ResultAsync.orTee` (method)](#resultasyncortee-method)\n    - [`ResultAsync.andThrough` (method)](#resultasyncandthrough-method)\n    - [`ResultAsync.combine` (static class method)](#resultasynccombine-static-class-method)\n    - [`ResultAsync.combineWithAllErrors` (static class method)](#resultasynccombinewithallerrors-static-class-method)\n    - [`ResultAsync.safeUnwrap()`](#resultasyncsafeunwrap)\n  + [Utilities](#utilities)\n    - [`fromThrowable`](#fromthrowable)\n    - [`fromAsyncThrowable`](#fromasyncthrowable)\n    - [`fromPromise`](#frompromise)\n    - [`fromSafePromise`](#fromsafepromise)\n    - [`safeTry`](#safetry)\n  + [Testing](#testing)\n* [A note on the Package Name](#a-note-on-the-package-name)\n\n## Installation\n\n```sh\n\u003e npm install neverthrow\n```\n\n## Recommended: Use `eslint-plugin-neverthrow`\n\nAs part of `neverthrow`s [bounty program](https://github.com/supermacro/neverthrow/issues/314), user [mdbetancourt](https://github.com/mdbetancourt) created [`eslint-plugin-neverthrow`](https://github.com/mdbetancourt/eslint-plugin-neverthrow) to ensure that errors are not gone unhandled.\n\nInstall by running:\n\n```sh\n\u003e npm install eslint-plugin-neverthrow\n```\n\nWith `eslint-plugin-neverthrow`, you are forced to consume the result in one of the following three ways:\n\n- Calling `.match`\n- Calling `.unwrapOr`\n- Calling `._unsafeUnwrap`\n\nThis ensures that you're explicitly handling the error of your `Result`.\n\nThis plugin is essentially a porting of Rust's [`must-use`](https://doc.rust-lang.org/std/result/#results-must-be-used) attribute. \n\n\n## Top-Level API\n\n`neverthrow` exposes the following:\n\n- `ok` convenience function to create an `Ok` variant of `Result`\n- `err` convenience function to create an `Err` variant of `Result`\n- `Ok` class and type\n- `Err` class and type\n- `Result` Type as well as namespace / object from which to call [`Result.fromThrowable`](#resultfromthrowable-static-class-method), [Result.combine](#resultcombine-static-class-method).\n- `ResultAsync` class\n- `okAsync` convenience function to create a `ResultAsync` containing an `Ok` type `Result`\n- `errAsync` convenience function to create a `ResultAsync` containing an `Err` type `Result`\n\n```typescript\nimport {\n  ok,\n  Ok,\n  err,\n  Err,\n  Result,\n  okAsync,\n  errAsync,\n  ResultAsync,\n  fromAsyncThrowable,\n  fromThrowable,\n  fromPromise,\n  fromSafePromise,\n  safeTry,\n} from 'neverthrow'\n```\n\n---\n\n**Check out the [wiki](https://github.com/supermacro/neverthrow/wiki) for help on how to make the most of `neverthrow`.**\n\nIf you find this package useful, please consider [sponsoring me](https://github.com/sponsors/supermacro/) or simply [buying me a coffee](https://ko-fi.com/gdelgado)!\n\n---\n\n## API Documentation\n\n### Synchronous API (`Result`)\n\n#### `ok`\n\nConstructs an `Ok` variant of `Result`\n\n**Signature:**\n\n```typescript\nok\u003cT, E\u003e(value: T): Ok\u003cT, E\u003e { ... }\n```\n\n**Example:**\n\n```typescript\nimport { ok } from 'neverthrow'\n\nconst myResult = ok({ myData: 'test' }) // instance of `Ok`\n\nmyResult.isOk() // true\nmyResult.isErr() // false\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `err`\n\nConstructs an `Err` variant of `Result`\n\n**Signature:**\n\n```typescript\nerr\u003cT, E\u003e(error: E): Err\u003cT, E\u003e { ... }\n```\n\n**Example:**\n\n```typescript\nimport { err } from 'neverthrow'\n\nconst myResult = err('Oh noooo') // instance of `Err`\n\nmyResult.isOk() // false\nmyResult.isErr() // true\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.isOk` (method)\n\nReturns `true` if the result is an `Ok` variant\n\n**Signature:**\n\n```typescript\nisOk(): boolean { ... }\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.isErr` (method)\n\nReturns `true` if the result is an `Err` variant\n\n**Signature**:\n\n```typescript\nisErr(): boolean { ... }\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.map` (method)\n\nMaps a `Result\u003cT, E\u003e` to `Result\u003cU, E\u003e` by applying a function to a contained `Ok` value, leaving an `Err` value untouched.\n\nThis function can be used to compose the results of two functions.\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  map\u003cU\u003e(callback: (value: T) =\u003e U): Result\u003cU, E\u003e { ... }\n}\n```\n\n**Example**:\n\n```typescript\nimport { getLines } from 'imaginary-parser'\n// ^ assume getLines has the following signature:\n// getLines(str: string): Result\u003cArray\u003cstring\u003e, Error\u003e\n\n// since the formatting is deemed correct by `getLines`\n// then it means that `linesResult` is an Ok\n// containing an Array of strings for each line of code\nconst linesResult = getLines('1\\n2\\n3\\n4\\n')\n\n// this Result now has a Array\u003cnumber\u003e inside it\nconst newResult = linesResult.map(\n  (arr: Array\u003cstring\u003e) =\u003e arr.map(parseInt)\n)\n\nnewResult.isOk() // true\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.mapErr` (method)\n\nMaps a `Result\u003cT, E\u003e` to `Result\u003cT, F\u003e` by applying a function to a contained `Err` value, leaving an `Ok` value untouched.\n\nThis function can be used to pass through a successful result while handling an error.\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  mapErr\u003cF\u003e(callback: (error: E) =\u003e F): Result\u003cT, F\u003e { ... }\n}\n```\n\n**Example**:\n\n```typescript\nimport { parseHeaders } from 'imaginary-http-parser'\n// imagine that parseHeaders has the following signature:\n// parseHeaders(raw: string): Result\u003cSomeKeyValueMap, ParseError\u003e\n\nconst rawHeaders = 'nonsensical gibberish and badly formatted stuff'\n\nconst parseResult = parseHeaders(rawHeaders)\n\nparseResult.mapErr(parseError =\u003e {\n  res.status(400).json({\n    error: parseError\n  })\n})\n\nparseResult.isErr() // true\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.unwrapOr` (method)\n\nUnwrap the `Ok` value, or return the default if there is an `Err`\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  unwrapOr\u003cT\u003e(value: T): T { ... }\n}\n```\n\n**Example**:\n\n```typescript\nconst myResult = err('Oh noooo')\n\nconst multiply = (value: number): number =\u003e value * 2\n\nconst unwrapped: number = myResult.map(multiply).unwrapOr(10)\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.andThen` (method)\n\nSame idea as `map` above. Except you must return a new `Result`.\n\nThe returned value will be a `Result`. As of `v4.1.0-beta`, you are able to return distinct error types (see signature below). Prior to `v4.1.0-beta`, the error type could not be distinct.\n\nThis is useful for when you need to do a subsequent computation using the inner `T` value, but that computation might fail.\n\nAdditionally, `andThen` is really useful as a tool to flatten a `Result\u003cResult\u003cA, E2\u003e, E1\u003e` into a `Result\u003cA, E2\u003e` (see example below).\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  // Note that the latest version lets you return distinct errors as well.\n  // If the error types (E and F) are the same (like `string | string`)\n  // then they will be merged into one type (`string`)\n  andThen\u003cU, F\u003e(\n    callback: (value: T) =\u003e Result\u003cU, F\u003e\n  ): Result\u003cU, E | F\u003e { ... }\n}\n```\n\n**Example 1: Chaining Results**\n\n```typescript\nimport { err, ok } from 'neverthrow'\n\nconst sq = (n: number): Result\u003cnumber, number\u003e =\u003e ok(n ** 2)\n\nok(2)\n  .andThen(sq)\n  .andThen(sq) // Ok(16)\n\nok(2)\n  .andThen(sq)\n  .andThen(err) // Err(4)\n\nok(2)\n  .andThen(err)\n  .andThen(sq) // Err(2)\n\nerr(3)\n  .andThen(sq)\n  .andThen(sq) // Err(3)\n```\n\n**Example 2: Flattening Nested Results**\n\n```typescript\n// It's common to have nested Results\nconst nested = ok(ok(1234))\n\n// notNested is a Ok(1234)\nconst notNested = nested.andThen((innerResult) =\u003e innerResult)\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.asyncAndThen` (method)\n\nSame idea as [`andThen` above](#resultandthen-method), except you must return a new `ResultAsync`.\n\nThe returned value will be a `ResultAsync`.\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  asyncAndThen\u003cU, F\u003e(\n    callback: (value: T) =\u003e ResultAsync\u003cU, F\u003e\n  ): ResultAsync\u003cU, E | F\u003e { ... }\n}\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.orElse` (method)\n\nTakes an `Err` value and maps it to a `Result\u003cT, SomeNewType\u003e`. This is useful for error recovery.\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  orElse\u003cU, A\u003e(\n    callback: (error: E) =\u003e Result\u003cU, A\u003e\n  ): Result\u003cU | T, A\u003e { ... }\n}\n```\n\n**Example:**\n\n```typescript\nenum DatabaseError {\n  PoolExhausted = 'PoolExhausted',\n  NotFound = 'NotFound',\n}\n\nconst dbQueryResult: Result\u003cstring, DatabaseError\u003e = err(DatabaseError.NotFound)\n\nconst updatedQueryResult = dbQueryResult.orElse((dbError) =\u003e\n  dbError === DatabaseError.NotFound\n    ? ok('User does not exist') // error recovery branch: ok() must be called with a value of type string\n    //\n    //\n    // err() can be called with a value of any new type that you want\n    // it could also be called with the same error value\n    //     \n    //     err(dbError)\n    : err(500) \n)\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.match` (method)\n\nGiven 2 functions (one for the `Ok` variant and one for the `Err` variant) execute the function that matches the `Result` variant.\n\nMatch callbacks do not necessitate to return a `Result`, however you can return a `Result` if you want to.\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  match\u003cA, B = A\u003e(\n    okCallback: (value: T) =\u003e  A,\n    errorCallback: (error: E) =\u003e  B\n  ): A | B =\u003e { ... }\n}\n```\n\n`match` is like chaining `map` and `mapErr`, with the distinction that with `match` both functions must have the same return type.\nThe differences between `match` and chaining `map` and `mapErr` are that:\n- with `match` both functions must have the same return type `A`\n- `match` unwraps the `Result\u003cT, E\u003e` into an `A` (the match functions' return type)\n  - This makes no difference if you are performing side effects only\n\n**Example:**\n\n```typescript\n// map/mapErr api\n// note that you DON'T have to append mapErr\n// after map which means that you are not required to do\n// error handling\ncomputationThatMightFail().map(console.log).mapErr(console.error)\n\n// match api\n// works exactly the same as above since both callbacks\n// only perform side effects,\n// except, now you HAVE to do error handling :)\ncomputationThatMightFail().match(console.log, console.error)\n\n// Returning values\nconst attempt = computationThatMightFail()\n  .map((str) =\u003e str.toUpperCase())\n  .mapErr((err) =\u003e `Error: ${err}`)\n// `attempt` is of type `Result\u003cstring, string\u003e`\n\nconst answer = computationThatMightFail().match(\n  (str) =\u003e str.toUpperCase(),\n  (err) =\u003e `Error: ${err}`\n)\n// `answer` is of type `string`\n```\n\nIf you don't use the error parameter in your match callback then `match` is equivalent to chaining `map` with `unwrapOr`:\n```ts\nconst answer = computationThatMightFail().match(\n  (str) =\u003e str.toUpperCase(),\n  () =\u003e 'ComputationError'\n)\n// `answer` is of type `string`\n\nconst answer = computationThatMightFail()\n  .map((str) =\u003e str.toUpperCase())\n  .unwrapOr('ComputationError')\n```\n\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.asyncMap` (method)\n\nSimilar to `map` except for two things:\n\n- the mapping function must return a `Promise`\n- asyncMap returns a `ResultAsync`\n\nYou can then chain the result of `asyncMap` using the `ResultAsync` apis (like `map`, `mapErr`, `andThen`, etc.)\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  asyncMap\u003cU\u003e(\n    callback: (value: T) =\u003e Promise\u003cU\u003e\n  ): ResultAsync\u003cU, E\u003e { ... }\n}\n```\n\n**Example:**\n\n```typescript\nimport { parseHeaders } from 'imaginary-http-parser'\n// imagine that parseHeaders has the following signature:\n// parseHeaders(raw: string): Result\u003cSomeKeyValueMap, ParseError\u003e\n\nconst asyncRes = parseHeaders(rawHeader)\n  .map(headerKvMap =\u003e headerKvMap.Authorization)\n  .asyncMap(findUserInDatabase)\n```\n\nNote that in the above example if `parseHeaders` returns an `Err` then `.map` and `.asyncMap` will not be invoked, and `asyncRes` variable will resolve to an `Err` when turned into a `Result` using `await` or `.then()`.\n  \n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.andTee` (method)\n\nTakes a `Result\u003cT, E\u003e` and lets the original `Result\u003cT, E\u003e` pass through regardless the result of the passed-in function.\nThis is a handy way to handle side effects whose failure or success should not affect your main logics such as logging. \n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  andTee(\n    callback: (value: T) =\u003e unknown\n  ): Result\u003cT, E\u003e { ... }\n}\n```\n\n**Example:**\n\n```typescript\nimport { parseUserInput } from 'imaginary-parser'\nimport { logUser } from 'imaginary-logger'\nimport { insertUser } from 'imaginary-database'\n\n// ^ assume parseUserInput, logUser and insertUser have the following signatures:\n// parseUserInput(input: RequestData): Result\u003cUser, ParseError\u003e\n// logUser(user: User): Result\u003cvoid, LogError\u003e \n// insertUser(user: User): ResultAsync\u003cvoid, InsertError\u003e\n// Note logUser returns void upon success but insertUser takes User type.\n\nconst resAsync = parseUserInput(userInput)\n               .andTee(logUser)\n               .asyncAndThen(insertUser)\n\n// Note no LogError shows up in the Result type\nresAsync.then((res: Result\u003cvoid, ParseError | InsertError\u003e) =\u003e {\n  if(res.isErr()){\n    console.log(\"Oops, at least one step failed\", res.error)\n  }\n  else{\n    console.log(\"User input has been parsed and inserted successfully.\")\n  }\n})\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.orTee` (method)\n\nLike `andTee` for the error track. Takes a `Result\u003cT, E\u003e` and lets the `Err` value pass through regardless the result of the passed-in function.\nThis is a handy way to handle side effects whose failure or success should not affect your main logics such as logging.\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  orTee(\n    callback: (value: E) =\u003e unknown\n  ): Result\u003cT, E\u003e { ... }\n}\n```\n\n**Example:**\n\n```typescript\nimport { parseUserInput } from 'imaginary-parser'\nimport { logParseError } from 'imaginary-logger'\nimport { insertUser } from 'imaginary-database'\n\n// ^ assume parseUserInput, logParseError and insertUser have the following signatures:\n// parseUserInput(input: RequestData): Result\u003cUser, ParseError\u003e\n// logParseError(parseError: ParseError): Result\u003cvoid, LogError\u003e \n// insertUser(user: User): ResultAsync\u003cvoid, InsertError\u003e\n// Note logParseError returns void upon success but insertUser takes User type.\n\nconst resAsync = parseUserInput(userInput)\n               .orTee(logParseError)\n               .asyncAndThen(insertUser)\n\n// Note no LogError shows up in the Result type\nresAsync.then((res: Result\u003cvoid, ParseError | InsertError\u003e) =\u003e {\n  if(res.isErr()){\n    console.log(\"Oops, at least one step failed\", res.error)\n  }\n  else{\n    console.log(\"User input has been parsed and inserted successfully.\")\n  }\n})\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.andThrough` (method)\n\nSimilar to `andTee` except for:\n\n- when there is an error from the passed-in function, that error will be passed along.\n\n**Signature:**\n\n```typescript\nclass Result\u003cT, E\u003e {\n  andThrough\u003cF\u003e(\n    callback: (value: T) =\u003e Result\u003cunknown, F\u003e\n  ): Result\u003cT, E | F\u003e { ... }\n}\n```\n\n**Example:**\n\n```typescript\nimport { parseUserInput } from 'imaginary-parser'\nimport { validateUser } from 'imaginary-validator'\nimport { insertUser } from 'imaginary-database'\n\n// ^ assume parseUseInput, validateUser and insertUser have the following signatures:\n// parseUserInput(input: RequestData): Result\u003cUser, ParseError\u003e\n// validateUser(user: User): Result\u003cvoid, ValidateError\u003e\n// insertUser(user: User): ResultAsync\u003cvoid, InsertError\u003e\n// Note validateUser returns void upon success but insertUser takes User type. \n\nconst resAsync = parseUserInput(userInput)\n               .andThrough(validateUser)\n               .asyncAndThen(insertUser)\n\nresAsync.then((res: Result\u003cvoid, ParseErro | ValidateError | InsertError\u003e) =\u003e {\n  if(res.isErr()){\n    console.log(\"Oops, at least one step failed\", res.error)\n  }\n  else{\n    console.log(\"User input has been parsed, validated, inserted successfully.\")\n  }\n})\n```\n  \n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.asyncAndThrough` (method)\n\nSimilar to `andThrough` except you must return a ResultAsync. \n\nYou can then chain the result of `asyncAndThrough` using the `ResultAsync` apis (like `map`, `mapErr`, `andThen`, etc.)\n\n**Signature:**\n\n```typescript\nimport { parseUserInput } from 'imaginary-parser'\nimport { insertUser } from 'imaginary-database'\nimport { sendNotification } from 'imaginary-service'\n\n// ^ assume parseUserInput, insertUser and sendNotification have the following signatures:\n// parseUserInput(input: RequestData): Result\u003cUser, ParseError\u003e\n// insertUser(user: User): ResultAsync\u003cvoid, InsertError\u003e\n// sendNotification(user: User): ResultAsync\u003cvoid, NotificationError\u003e\n// Note insertUser returns void upon success but sendNotification takes User type. \n\nconst resAsync = parseUserInput(userInput)\n               .asyncAndThrough(insertUser)\n               .andThen(sendNotification)\n\nresAsync.then((res: Result\u003cvoid, ParseError | InsertError | NotificationError\u003e) =\u003e {\n  if(res.isErr()){\n    console.log(\"Oops, at least one step failed\", res.error)\n  }\n  else{\n    console.log(\"User has been parsed, inserted and notified successfully.\")\n  }\n})\n```\n  \n[⬆️  Back to top](#toc)\n\n---\n#### `Result.fromThrowable` (static class method)\n\n\u003e Although Result is not an actual JS class, the way that `fromThrowable` has been implemented requires that you call `fromThrowable` as though it were a static method on `Result`. See examples below.\n\nThe JavaScript community has agreed on the convention of throwing exceptions.\nAs such, when interfacing with third party libraries it's imperative that you\nwrap third-party code in try / catch blocks.\n\nThis function will create a new function that returns an `Err` when the original\nfunction throws.\n\nIt is not possible to know the types of the errors thrown in the original\nfunction, therefore it is recommended to use the second argument `errorFn` to\nmap what is thrown to a known type.\n\n**Example**:\n\n```typescript\nimport { Result } from 'neverthrow'\n\ntype ParseError = { message: string }\nconst toParseError = (): ParseError =\u003e ({ message: \"Parse Error\" })\n\nconst safeJsonParse = Result.fromThrowable(JSON.parse, toParseError)\n\n// the function can now be used safely, if the function throws, the result will be an Err\nconst res = safeJsonParse(\"{\");\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.combine` (static class method)\n\n\u003e Although Result is not an actual JS class, the way that `combine` has been implemented requires that you call `combine` as though it were a static method on `Result`. See examples below.\n\nCombine lists of `Result`s.\n\nIf you're familiar with `Promise.all`, the combine function works conceptually the same.\n\n**`combine` works on both heterogeneous and homogeneous lists**. This means that you can have lists that contain different kinds of `Result`s and still be able to combine them. Note that you cannot combine lists that contain both `Result`s **and** `ResultAsync`s.\n\nThe combine function takes a list of results and returns a single result. If all the results in the list are `Ok`, then the return value will be a `Ok` containing a list of all the individual `Ok` values.\n\nIf just one of the results in the list is an `Err` then the combine function returns that Err value (it short circuits and returns the first Err that it finds).\n\nFormally speaking:\n\n```typescript\n// homogeneous lists\nfunction combine\u003cT, E\u003e(resultList: Result\u003cT, E\u003e[]): Result\u003cT[], E\u003e\n\n// heterogeneous lists\nfunction combine\u003cT1, T2, E1, E2\u003e(resultList: [ Result\u003cT1, E1\u003e, Result\u003cT2, E2\u003e ]): Result\u003c[ T1, T2 ], E1 | E2\u003e\nfunction combine\u003cT1, T2, T3, E1, E2, E3\u003e =\u003e Result\u003c[ T1, T2, T3 ], E1 | E2 | E3\u003e\nfunction combine\u003cT1, T2, T3, T4, E1, E2, E3, E4\u003e =\u003e Result\u003c[ T1, T2, T3, T4 ], E1 | E2 | E3 | E4\u003e\n// ... etc etc ad infinitum\n\n```\n\nExample:\n```typescript\nconst resultList: Result\u003cnumber, never\u003e[] =\n  [ok(1), ok(2)]\n\nconst combinedList: Result\u003cnumber[], unknown\u003e =\n  Result.combine(resultList)\n```\n\nExample with tuples:\n```typescript\n/** @example tuple(1, 2, 3) === [1, 2, 3] // with type [number, number, number] */\nconst tuple = \u003cT extends any[]\u003e(...args: T): T =\u003e args\n\nconst resultTuple: [Result\u003cstring, never\u003e, Result\u003cstring, never\u003e] =\n  tuple(ok('a'), ok('b'))\n\nconst combinedTuple: Result\u003c[string, string], unknown\u003e =\n  Result.combine(resultTuple)\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `Result.combineWithAllErrors` (static class method)\n\n\u003e Although Result is not an actual JS class, the way that `combineWithAllErrors` has been implemented requires that you call `combineWithAllErrors` as though it were a static method on `Result`. See examples below.\n\nLike `combine` but without short-circuiting. Instead of just the first error value, you get a list of all error values of the input result list.\n\nIf only some results fail, the new combined error list will only contain the error value of the failed results, meaning that there is no guarantee of the length of the new error list.\n\nFunction signature:\n\n```typescript\n// homogeneous lists\nfunction combineWithAllErrors\u003cT, E\u003e(resultList: Result\u003cT, E\u003e[]): Result\u003cT[], E[]\u003e\n\n// heterogeneous lists\nfunction combineWithAllErrors\u003cT1, T2, E1, E2\u003e(resultList: [ Result\u003cT1, E1\u003e, Result\u003cT2, E2\u003e ]): Result\u003c[ T1, T2 ], (E1 | E2)[]\u003e\nfunction combineWithAllErrors\u003cT1, T2, T3, E1, E2, E3\u003e =\u003e Result\u003c[ T1, T2, T3 ], (E1 | E2 | E3)[]\u003e\nfunction combineWithAllErrors\u003cT1, T2, T3, T4, E1, E2, E3, E4\u003e =\u003e Result\u003c[ T1, T2, T3, T4 ], (E1 | E2 | E3 | E4)[]\u003e\n// ... etc etc ad infinitum\n```\n\nExample usage:\n\n```typescript\nconst resultList: Result\u003cnumber, string\u003e[] = [\n  ok(123),\n  err('boooom!'),\n  ok(456),\n  err('ahhhhh!'),\n]\n\nconst result = Result.combineWithAllErrors(resultList)\n\n// result is Err(['boooom!', 'ahhhhh!'])\n```\n\n[⬆️  Back to top](#toc)\n\n#### `Result.safeUnwrap()`\n\n**Deprecated**. You don't need to use this method anymore.\n\nAllows for unwrapping a `Result` or returning an `Err` implicitly, thereby reducing boilerplate.\n\n\n[⬆️  Back to top](#toc)\n\n---\n\n### Asynchronous API (`ResultAsync`)\n\n#### `okAsync`\n\nConstructs an `Ok` variant of `ResultAsync`\n\n**Signature:**\n\n```typescript\nokAsync\u003cT, E\u003e(value: T): ResultAsync\u003cT, E\u003e\n```\n\n**Example:**\n\n```typescript\nimport { okAsync } from 'neverthrow'\n\nconst myResultAsync = okAsync({ myData: 'test' }) // instance of `ResultAsync`\n\nconst myResult = await myResultAsync // instance of `Ok`\n\nmyResult.isOk() // true\nmyResult.isErr() // false\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `errAsync`\n\nConstructs an `Err` variant of `ResultAsync`\n\n**Signature:**\n\n```typescript\nerrAsync\u003cT, E\u003e(error: E): ResultAsync\u003cT, E\u003e\n```\n\n**Example:**\n\n```typescript\nimport { errAsync } from 'neverthrow'\n\nconst myResultAsync = errAsync('Oh nooo') // instance of `ResultAsync`\n\nconst myResult = await myResultAsync // instance of `Err`\n\nmyResult.isOk() // false\nmyResult.isErr() // true\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.fromThrowable` (static class method)\n\nSimilar to [Result.fromThrowable](#resultfromthrowable-static-class-method), but for functions that return a `Promise`.\n\n**Example**:\n\n```typescript\nimport { ResultAsync } from 'neverthrow'\nimport { insertIntoDb } from 'imaginary-database'\n// insertIntoDb(user: User): Promise\u003cUser\u003e\n\nconst insertUser = ResultAsync.fromThrowable(insertIntoDb, () =\u003e new Error('Database error'))\n// `res` has a type of (user: User) =\u003e ResultAsync\u003cUser, Error\u003e\n```\n\nNote that this can be safer than using [ResultAsync.fromPromise](#resultasyncfrompromise-static-class-method) with\nthe result of a function call, because not all functions that return a `Promise` are `async`, and thus they can throw\nerrors synchronously rather than returning a rejected `Promise`. For example:\n\n```typescript\n// NOT SAFE !!\nimport { ResultAsync } from 'neverthrow'\nimport { db } from 'imaginary-database'\n// db.insert\u003cT\u003e(table: string, value: T): Promise\u003cT\u003e\n\nconst insertUser = (user: User): Promise\u003cUser\u003e =\u003e {\n  if (!user.id) {\n    // this throws synchronously!\n    throw new TypeError('missing user id')\n  }\n  return db.insert('users', user)\n}\n\n// this will throw, NOT return a `ResultAsync`\nconst res = ResultAsync.fromPromise(insertIntoDb(myUser), () =\u003e new Error('Database error'))\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.fromPromise` (static class method)\n\nTransforms a `PromiseLike\u003cT\u003e` (that may throw) into a `ResultAsync\u003cT, E\u003e`.\n\nThe second argument handles the rejection case of the promise and maps the error from `unknown` into some type `E`.\n\n\n**Signature:**\n\n```typescript\n// fromPromise is a static class method\n// also available as a standalone function\n// import { fromPromise } from 'neverthrow'\nResultAsync.fromPromise\u003cT, E\u003e(\n  promise: PromiseLike\u003cT\u003e,\n  errorHandler: (unknownError: unknown) =\u003e E)\n): ResultAsync\u003cT, E\u003e { ... }\n```\n\nIf you are working with `PromiseLike` objects that you **know for a fact** will not throw, then use `fromSafePromise` in order to avoid having to pass a redundant `errorHandler` argument.\n\n**Example**:\n\n```typescript\nimport { ResultAsync } from 'neverthrow'\nimport { insertIntoDb } from 'imaginary-database'\n// insertIntoDb(user: User): Promise\u003cUser\u003e\n\nconst res = ResultAsync.fromPromise(insertIntoDb(myUser), () =\u003e new Error('Database error'))\n// `res` has a type of ResultAsync\u003cUser, Error\u003e\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.fromSafePromise` (static class method)\n\nSame as `ResultAsync.fromPromise` except that it does not handle the rejection of the promise. **Ensure you know what you're doing, otherwise a thrown exception within this promise will cause ResultAsync to reject, instead of resolve to a Result.**\n\n**Signature:**\n\n```typescript\n// fromPromise is a static class method\n// also available as a standalone function\n// import { fromPromise } from 'neverthrow'\nResultAsync.fromSafePromise\u003cT, E\u003e(\n  promise: PromiseLike\u003cT\u003e\n): ResultAsync\u003cT, E\u003e { ... }\n```\n\n**Example**:\n\n```typescript\nimport { RouteError } from 'routes/error'\n\n// simulate slow routes in an http server that works in a Result / ResultAsync context\n// Adopted from https://github.com/parlez-vous/server/blob/2496bacf55a2acbebc30631b5562f34272794d76/src/routes/common/signup.ts\nexport const slowDown = \u003cT\u003e(ms: number) =\u003e (value: T) =\u003e\n  ResultAsync.fromSafePromise\u003cT, RouteError\u003e(\n    new Promise((resolve) =\u003e {\n      setTimeout(() =\u003e {\n        resolve(value)\n      }, ms)\n    })\n  )\n\nexport const signupHandler = route\u003cUser\u003e((req, sessionManager) =\u003e\n  decode(userSignupDecoder, req.body, 'Invalid request body').map((parsed) =\u003e {\n    return createUser(parsed)\n      .andThen(slowDown(3000)) // slowdown by 3 seconds\n      .andThen(sessionManager.createSession)\n      .map(({ sessionToken, admin }) =\u003e AppData.init(admin, sessionToken))\n  })\n)\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.map` (method)\n\nMaps a `ResultAsync\u003cT, E\u003e` to `ResultAsync\u003cU, E\u003e` by applying a function to a contained `Ok` value, leaving an `Err` value untouched.\n\nThe applied function can be synchronous or asynchronous (returning a `Promise\u003cU\u003e`) with no impact to the return type.\n\nThis function can be used to compose the results of two functions.\n\n**Signature:**\n\n```typescript\nclass ResultAsync\u003cT, E\u003e {\n  map\u003cU\u003e(\n    callback: (value: T) =\u003e U | Promise\u003cU\u003e\n  ): ResultAsync\u003cU, E\u003e { ... }\n}\n```\n\n**Example**:\n\n```typescript\nimport { findUsersIn } from 'imaginary-database'\n// ^ assume findUsersIn has the following signature:\n// findUsersIn(country: string): ResultAsync\u003cArray\u003cUser\u003e, Error\u003e\n\nconst usersInCanada = findUsersIn(\"Canada\")\n\n// Let's assume we only need their names\nconst namesInCanada = usersInCanada.map((users: Array\u003cUser\u003e) =\u003e users.map(user =\u003e user.name))\n// namesInCanada is of type ResultAsync\u003cArray\u003cstring\u003e, Error\u003e\n\n// We can extract the Result using .then() or await\nnamesInCanada.then((namesResult: Result\u003cArray\u003cstring\u003e, Error\u003e) =\u003e {\n  if(namesResult.isErr()){\n    console.log(\"Couldn't get the users from the database\", namesResult.error)\n  }\n  else{\n    console.log(\"Users in Canada are named: \" + namesResult.value.join(','))\n  }\n})\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.mapErr` (method)\n\nMaps a `ResultAsync\u003cT, E\u003e` to `ResultAsync\u003cT, F\u003e` by applying a function to a contained `Err` value, leaving an `Ok` value untouched.\n\nThe applied function can be synchronous or asynchronous (returning a `Promise\u003cF\u003e`) with no impact to the return type.\n\nThis function can be used to pass through a successful result while handling an error.\n\n**Signature:**\n\n```typescript\nclass ResultAsync\u003cT, E\u003e {\n  mapErr\u003cF\u003e(\n    callback: (error: E) =\u003e F | Promise\u003cF\u003e\n  ): ResultAsync\u003cT, F\u003e { ... }\n}\n```\n\n**Example**:\n\n```typescript\nimport { findUsersIn } from 'imaginary-database'\n// ^ assume findUsersIn has the following signature:\n// findUsersIn(country: string): ResultAsync\u003cArray\u003cUser\u003e, Error\u003e\n\n// Let's say we need to low-level errors from findUsersIn to be more readable\nconst usersInCanada = findUsersIn(\"Canada\").mapErr((error: Error) =\u003e {\n  // The only error we want to pass to the user is \"Unknown country\"\n  if(error.message === \"Unknown country\"){\n    return error.message\n  }\n  // All other errors will be labelled as a system error\n  return \"System error, please contact an administrator.\"\n})\n\n// usersInCanada is of type ResultAsync\u003cArray\u003cUser\u003e, string\u003e\n\nusersInCanada.then((usersResult: Result\u003cArray\u003cUser\u003e, string\u003e) =\u003e {\n  if(usersResult.isErr()){\n    res.status(400).json({\n      error: usersResult.error\n    })\n  }\n  else{\n    res.status(200).json({\n      users: usersResult.value\n    })\n  }\n})\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.unwrapOr` (method)\n\nUnwrap the `Ok` value, or return the default if there is an `Err`.  \nWorks just like `Result.unwrapOr` but returns a `Promise\u003cT\u003e` instead of `T`.\n\n**Signature:**\n\n```typescript\nclass ResultAsync\u003cT, E\u003e {\n  unwrapOr\u003cT\u003e(value: T): Promise\u003cT\u003e { ... }\n}\n```\n\n**Example**:\n\n```typescript\nconst unwrapped: number = await errAsync(0).unwrapOr(10)\n// unwrapped = 10\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.andThen` (method)\n\nSame idea as `map` above. Except the applied function must return a `Result` or `ResultAsync`.\n\n`ResultAsync.andThen` always returns a `ResultAsync` no matter the return type of the applied function.\n\nThis is useful for when you need to do a subsequent computation using the inner `T` value, but that computation might fail.\n\n`andThen` is really useful as a tool to flatten a `ResultAsync\u003cResultAsync\u003cA, E2\u003e, E1\u003e` into a `ResultAsync\u003cA, E2\u003e` (see example below).\n\n**Signature:**\n\n```typescript\n// Note that the latest version (v4.1.0-beta) lets you return distinct errors as well.\n// If the error types (E and F) are the same (like `string | string`)\n// then they will be merged into one type (`string`)\n\nclass ResultAsync\u003cT, E\u003e {\n  andThen\u003cU, F\u003e(\n    callback: (value: T) =\u003e Result\u003cU, F\u003e | ResultAsync\u003cU, F\u003e\n  ): ResultAsync\u003cU, E | F\u003e { ... }\n}\n```\n\n**Example**\n\n```typescript\n\nimport { validateUser } from 'imaginary-validator'\nimport { insertUser } from 'imaginary-database'\nimport { sendNotification } from 'imaginary-service'\n\n// ^ assume validateUser, insertUser and sendNotification have the following signatures:\n// validateUser(user: User): Result\u003cUser, Error\u003e\n// insertUser(user): ResultAsync\u003cUser, Error\u003e\n// sendNotification(user): ResultAsync\u003cvoid, Error\u003e\n\nconst resAsync = validateUser(user)\n               .andThen(insertUser)\n               .andThen(sendNotification)\n\n// resAsync is a ResultAsync\u003cvoid, Error\u003e\n\nresAsync.then((res: Result\u003cvoid, Error\u003e) =\u003e {\n  if(res.isErr()){\n    console.log(\"Oops, at least one step failed\", res.error)\n  }\n  else{\n    console.log(\"User has been validated, inserted and notified successfully.\")\n  }\n})\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.orElse` (method)\n\nTakes an `Err` value and maps it to a `ResultAsync\u003cT, SomeNewType\u003e`. This is useful for error recovery.\n\n**Signature:**\n\n```typescript\nclass ResultAsync\u003cT, E\u003e {\n  orElse\u003cU, A\u003e(\n    callback: (error: E) =\u003e Result\u003cU, A\u003e | ResultAsync\u003cU, A\u003e\n  ): ResultAsync\u003cU | T, A\u003e { ... }\n}\n```\n\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.match` (method)\n\nGiven 2 functions (one for the `Ok` variant and one for the `Err` variant) execute the function that matches the `ResultAsync` variant.\n\nThe difference with `Result.match` is that it always returns a `Promise` because of the asynchronous nature of the `ResultAsync`.\n\n**Signature:**\n\n```typescript\nclass ResultAsync\u003cT, E\u003e {\n  match\u003cA, B = A\u003e(\n    okCallback: (value: T) =\u003e  A,\n    errorCallback: (error: E) =\u003e  B\n  ): Promise\u003cA | B\u003e =\u003e { ... }\n}\n```\n\n**Example:**\n\n```typescript\n\nimport { validateUser } from 'imaginary-validator'\nimport { insertUser } from 'imaginary-database'\n\n// ^ assume validateUser and insertUser have the following signatures:\n// validateUser(user: User): Result\u003cUser, Error\u003e\n// insertUser(user): ResultAsync\u003cUser, Error\u003e\n\n// Handle both cases at the end of the chain using match\nconst resultMessage = await validateUser(user)\n        .andThen(insertUser)\n        .match(\n            (user: User) =\u003e `User ${user.name} has been successfully created`,\n            (error: Error) =\u003e  `User could not be created because ${error.message}`\n        )\n\n// resultMessage is a string\n```\n\n[⬆️  Back to top](#toc)\n\n---\n#### `ResultAsync.andTee` (method)\n\nTakes a `ResultAsync\u003cT, E\u003e` and lets the original `ResultAsync\u003cT, E\u003e` pass through regardless \nthe result of the passed-in function.\nThis is a handy way to handle side effects whose failure or success should not affect your main logics such as logging. \n\n**Signature:**\n\n```typescript\nclass ResultAsync\u003cT, E\u003e {\n  andTee(\n    callback: (value: T) =\u003e unknown\n  ): ResultAsync\u003cT, E\u003e  =\u003e { ... }\n}\n```\n\n**Example:**\n\n```typescript\nimport { insertUser } from 'imaginary-database'\nimport { logUser } from 'imaginary-logger'\nimport { sendNotification } from 'imaginary-service'\n\n// ^ assume insertUser, logUser and sendNotification have the following signatures:\n// insertUser(user: User): ResultAsync\u003cUser, InsertError\u003e\n// logUser(user: User): Result\u003cvoid, LogError\u003e\n// sendNotification(user: User): ResultAsync\u003cvoid, NotificationError\u003e\n// Note logUser returns void on success but sendNotification takes User type. \n\nconst resAsync = insertUser(user)\n                .andTee(logUser)\n                .andThen(sendNotification)\n\n// Note there is no LogError in the types below \nresAsync.then((res: Result\u003cvoid, InsertError | NotificationError\u003e) =\u003e {\n  if(res.isErr()){\n    console.log(\"Oops, at least one step failed\", res.error)\n  }\n  else{\n    console.log(\"User has been inserted and notified successfully.\")\n  }\n})\n```\n\n[⬆️  Back to top](#toc)\n\n---\n#### `ResultAsync.orTee` (method)\n\nLike `andTee` for the error track. Takes a `ResultAsync\u003cT, E\u003e` and lets the original `Err` value pass through regardless \nthe result of the passed-in function.\nThis is a handy way to handle side effects whose failure or success should not affect your main logics such as logging. \n\n**Signature:**\n\n```typescript\nclass ResultAsync\u003cT, E\u003e {\n  orTee(\n    callback: (value: E) =\u003e unknown\n  ): ResultAsync\u003cT, E\u003e  =\u003e { ... }\n}\n```\n\n**Example:**\n\n```typescript\nimport { insertUser } from 'imaginary-database'\nimport { logInsertError } from 'imaginary-logger'\nimport { sendNotification } from 'imaginary-service'\n\n// ^ assume insertUser, logInsertError and sendNotification have the following signatures:\n// insertUser(user: User): ResultAsync\u003cUser, InsertError\u003e\n// logInsertError(insertError: InsertError): Result\u003cvoid, LogError\u003e\n// sendNotification(user: User): ResultAsync\u003cvoid, NotificationError\u003e\n// Note logInsertError returns void on success but sendNotification takes User type. \n\nconst resAsync = insertUser(user)\n                .orTee(logUser)\n                .andThen(sendNotification)\n\n// Note there is no LogError in the types below \nresAsync.then((res: Result\u003cvoid, InsertError | NotificationError\u003e) =\u003e {\n  if(res.isErr()){\n    console.log(\"Oops, at least one step failed\", res.error)\n  }\n  else{\n    console.log(\"User has been inserted and notified successfully.\")\n  }\n})\n```\n\n[⬆️  Back to top](#toc)\n\n---\n#### `ResultAsync.andThrough` (method)\n\n\nSimilar to `andTee` except for:\n\n- when there is an error from the passed-in function, that error will be passed along.\n\n**Signature:**\n\n```typescript\nclass ResultAsync\u003cT, E\u003e {\n  andThrough\u003cF\u003e(\n    callback: (value: T) =\u003e Result\u003cunknown, F\u003e | ResultAsync\u003cunknown, F\u003e,\n  ): ResultAsync\u003cT, E | F\u003e =\u003e { ... }\n}\n```\n\n**Example:**\n\n```typescript\n\nimport { buildUser } from 'imaginary-builder'\nimport { insertUser } from 'imaginary-database'\nimport { sendNotification } from 'imaginary-service'\n\n// ^ assume buildUser, insertUser and sendNotification have the following signatures:\n// buildUser(userRaw: UserRaw): ResultAsync\u003cUser, BuildError\u003e\n// insertUser(user: User): ResultAsync\u003cvoid, InsertError\u003e\n// sendNotification(user: User): ResultAsync\u003cvoid, NotificationError\u003e\n// Note insertUser returns void upon success but sendNotification takes User type. \n\nconst resAsync = buildUser(userRaw)\n                .andThrough(insertUser)\n                .andThen(sendNotification)\n\nresAsync.then((res: Result\u003cvoid, BuildError | InsertError | NotificationError\u003e) =\u003e {\n  if(res.isErr()){\n    console.log(\"Oops, at least one step failed\", res.error)\n  }\n  else{\n    console.log(\"User data has been built, inserted and notified successfully.\")\n  }\n})\n```\n\n[⬆️  Back to top](#toc)\n\n---\n#### `ResultAsync.combine` (static class method)\n\nCombine lists of `ResultAsync`s.\n\nIf you're familiar with `Promise.all`, the combine function works conceptually the same.\n\n**`combine` works on both heterogeneous and homogeneous lists**. This means that you can have lists that contain different kinds of `ResultAsync`s and still be able to combine them. Note that you cannot combine lists that contain both `Result`s **and** `ResultAsync`s.\n\nThe combine function takes a list of results and returns a single result. If all the results in the list are `Ok`, then the return value will be a `Ok` containing a list of all the individual `Ok` values.\n\nIf just one of the results in the list is an `Err` then the combine function returns that Err value (it short circuits and returns the first Err that it finds).\n\nFormally speaking:\n\n```typescript\n// homogeneous lists\nfunction combine\u003cT, E\u003e(resultList: ResultAsync\u003cT, E\u003e[]): ResultAsync\u003cT[], E\u003e\n\n// heterogeneous lists\nfunction combine\u003cT1, T2, E1, E2\u003e(resultList: [ ResultAsync\u003cT1, E1\u003e, ResultAsync\u003cT2, E2\u003e ]): ResultAsync\u003c[ T1, T2 ], E1 | E2\u003e\nfunction combine\u003cT1, T2, T3, E1, E2, E3\u003e =\u003e ResultAsync\u003c[ T1, T2, T3 ], E1 | E2 | E3\u003e\nfunction combine\u003cT1, T2, T3, T4, E1, E2, E3, E4\u003e =\u003e ResultAsync\u003c[ T1, T2, T3, T4 ], E1 | E2 | E3 | E4\u003e\n// ... etc etc ad infinitum\n\n```\n\nExample:\n```typescript\nconst resultList: ResultAsync\u003cnumber, never\u003e[] =\n  [okAsync(1), okAsync(2)]\n\nconst combinedList: ResultAsync\u003cnumber[], unknown\u003e =\n  ResultAsync.combine(resultList)\n```\n\nExample with tuples:\n```typescript\n/** @example tuple(1, 2, 3) === [1, 2, 3] // with type [number, number, number] */\nconst tuple = \u003cT extends any[]\u003e(...args: T): T =\u003e args\n\nconst resultTuple: [ResultAsync\u003cstring, never\u003e, ResultAsync\u003cstring, never\u003e] =\n  tuple(okAsync('a'), okAsync('b'))\n\nconst combinedTuple: ResultAsync\u003c[string, string], unknown\u003e =\n  ResultAsync.combine(resultTuple)\n```\n[⬆️  Back to top](#toc)\n\n---\n\n#### `ResultAsync.combineWithAllErrors` (static class method)\n\nLike `combine` but without short-circuiting. Instead of just the first error value, you get a list of all error values of the input result list.\n\nIf only some results fail, the new combined error list will only contain the error value of the failed results, meaning that there is no guarantee of the length of the new error list.\n\nFunction signature:\n\n```typescript\n// homogeneous lists\nfunction combineWithAllErrors\u003cT, E\u003e(resultList: ResultAsync\u003cT, E\u003e[]): ResultAsync\u003cT[], E[]\u003e\n\n// heterogeneous lists\nfunction combineWithAllErrors\u003cT1, T2, E1, E2\u003e(resultList: [ ResultAsync\u003cT1, E1\u003e, ResultAsync\u003cT2, E2\u003e ]): ResultAsync\u003c[ T1, T2 ], (E1 | E2)[]\u003e\nfunction combineWithAllErrors\u003cT1, T2, T3, E1, E2, E3\u003e =\u003e ResultAsync\u003c[ T1, T2, T3 ], (E1 | E2 | E3)[]\u003e\nfunction combineWithAllErrors\u003cT1, T2, T3, T4, E1, E2, E3, E4\u003e =\u003e ResultAsync\u003c[ T1, T2, T3, T4 ], (E1 | E2 | E3 | E4)[]\u003e\n// ... etc etc ad infinitum\n```\n\nExample usage:\n\n```typescript\nconst resultList: ResultAsync\u003cnumber, string\u003e[] = [\n  okAsync(123),\n  errAsync('boooom!'),\n  okAsync(456),\n  errAsync('ahhhhh!'),\n]\n\nconst result = ResultAsync.combineWithAllErrors(resultList)\n\n// result is Err(['boooom!', 'ahhhhh!'])\n```\n\n#### `ResultAsync.safeUnwrap()`\n\n**Deprecated**. You don't need to use this method anymore.\n\nAllows for unwrapping a `Result` or returning an `Err` implicitly, thereby reducing boilerplate.\n\n[⬆️  Back to top](#toc)\n\n---\n\n### Utilities\n\n#### `fromThrowable`\n\nTop level export of `Result.fromThrowable`.\nPlease find documentation at [Result.fromThrowable](#resultfromthrowable-static-class-method)\n\n[⬆️  Back to top](#toc)\n\n#### `fromAsyncThrowable`\n\nTop level export of `ResultAsync.fromThrowable`.\nPlease find documentation at [ResultAsync.fromThrowable](#resultasyncfromthrowable-static-class-method)\n\n[⬆️  Back to top](#toc)\n\n#### `fromPromise`\n\nTop level export of `ResultAsync.fromPromise`.\nPlease find documentation at [ResultAsync.fromPromise](#resultasyncfrompromise-static-class-method)\n\n[⬆️  Back to top](#toc)\n\n#### `fromSafePromise`\n\nTop level export of `ResultAsync.fromSafePromise`.\nPlease find documentation at [ResultAsync.fromSafePromise](#resultasyncfromsafepromise-static-class-method)\n\n[⬆️  Back to top](#toc)\n\n#### `safeTry`\n\nUsed to implicitly return errors and reduce boilerplate.\n\nLet's say we are writing a function that returns a `Result`, and in that function we call some functions which also return `Result`s and we check those results to see whether we should keep going or abort. Usually, we will write like the following.\n```typescript\ndeclare function mayFail1(): Result\u003cnumber, string\u003e;\ndeclare function mayFail2(): Result\u003cnumber, string\u003e;\n\nfunction myFunc(): Result\u003cnumber, string\u003e {\n    // We have to define a constant to hold the result to check and unwrap its value.\n    const result1 = mayFail1();\n    if (result1.isErr()) {\n        return err(`aborted by an error from 1st function, ${result1.error}`);\n    }\n    const value1 = result1.value\n\n    // Again, we need to define a constant and then check and unwrap.\n    const result2 = mayFail2();\n    if (result2.isErr()) {\n        return err(`aborted by an error from 2nd function, ${result2.error}`);\n    }\n    const value2 = result2.value\n\n    // And finally we return what we want to calculate\n    return ok(value1 + value2);\n}\n```\nBasically, we need to define a constant for each result to check whether it's a `Ok` and read its `.value` or `.error`.\n\nWith safeTry, we can state 'Return here if its an `Err`, otherwise unwrap it here and keep going.' in just one expression.\n```typescript\ndeclare function mayFail1(): Result\u003cnumber, string\u003e;\ndeclare function mayFail2(): Result\u003cnumber, string\u003e;\n\nfunction myFunc(): Result\u003cnumber, string\u003e {\n    return safeTry\u003cnumber, string\u003e(function*() {\n        return ok(\n            // If the result of mayFail1().mapErr() is an `Err`, the evaluation is\n            // aborted here and the enclosing `safeTry` block is evaluated to that `Err`.\n            // Otherwise, this `(yield* ...)` is evaluated to its `.value`.\n            (yield* mayFail1()\n                .mapErr(e =\u003e `aborted by an error from 1st function, ${e}`))\n            +\n            // The same as above.\n            (yield* mayFail2()\n                .mapErr(e =\u003e `aborted by an error from 2nd function, ${e}`))\n        )\n    })\n}\n```\n\nTo use `safeTry`, the points are as follows.\n* Wrap the entire block in a [generator function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*)\n* In that block, you can use `yield* \u003cRESULT\u003e` to state 'Return `\u003cRESULT\u003e` if it's an `Err`, otherwise evaluate to its `.value`'\n* Pass the generator function to `safeTry`\n\nYou can also use [async generator function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function*) to pass an async block to `safeTry`.\n```typescript\n// You can use either Promise\u003cResult\u003e or ResultAsync.\ndeclare function mayFail1(): Promise\u003cResult\u003cnumber, string\u003e\u003e;\ndeclare function mayFail2(): ResultAsync\u003cnumber, string\u003e;\n\nfunction myFunc(): Promise\u003cResult\u003cnumber, string\u003e\u003e {\n    return safeTry\u003cnumber, string\u003e(async function*() {\n        return ok(\n            // You have to await if the expression is Promise\u003cResult\u003e\n            (yield* (await mayFail1())\n                .mapErr(e =\u003e `aborted by an error from 1st function, ${e}`))\n            +\n            // You can call `safeUnwrap` directly if its ResultAsync\n            (yield* mayFail2()\n                .mapErr(e =\u003e `aborted by an error from 2nd function, ${e}`))\n        )\n    })\n}\n```\n\nFor more information, see https://github.com/supermacro/neverthrow/pull/448 and https://github.com/supermacro/neverthrow/issues/444\n\n[⬆️  Back to top](#toc)\n\n---\n\n### Testing\n\n`Result` instances have two unsafe methods, aptly called `_unsafeUnwrap` and `_unsafeUnwrapErr` which **should only be used in a test environment**.\n\n`_unsafeUnwrap` takes a `Result\u003cT, E\u003e` and returns a `T` when the result is an `Ok`, otherwise it throws a custom object.\n\n`_unsafeUnwrapErr` takes a `Result\u003cT, E\u003e` and returns a `E` when the result is an `Err`, otherwise it throws a custom object.\n\nThat way you can do something like:\n\n```typescript\nexpect(myResult._unsafeUnwrap()).toBe(someExpectation)\n```\n\nHowever, do note that `Result` instances are comparable. So you don't necessarily need to unwrap them in order to assert expectations in your tests. So you could also do something like this:\n\n```typescript\nimport { ok } from 'neverthrow'\n\n// ...\n\nexpect(callSomeFunctionThatReturnsAResult(\"with\", \"some\", \"args\")).toEqual(ok(someExpectation));\n```\n\nBy default, the thrown value does not contain a stack trace. This is because stack trace generation [makes error messages in Jest harder to understand](https://github.com/supermacro/neverthrow/pull/215). If you want stack traces to be generated, call `_unsafeUnwrap` and / or `_unsafeUnwrapErr` with a config object:\n\n```typescript\n_unsafeUnwrapErr({\n  withStackTrace: true,\n})\n\n// ^ Now the error object will have a `.stack` property containing the current stack\n```\n\n---\n\nIf you find this package useful, please consider [sponsoring me](https://github.com/sponsors/supermacro/) or simply [buying me a coffee](https://ko-fi.com/gdelgado)!\n\n---\n\n## A note on the Package Name\n\nAlthough the package is called `neverthrow`, please don't take this literally. I am simply encouraging the developer to think a bit more about the ergonomics and usage of whatever software they are writing.\n\n`Throw`ing and `catching` is very similar to using `goto` statements - in other words; it makes reasoning about your programs harder. Secondly, by using `throw` you make the assumption that the caller of your function is implementing `catch`. This is a known source of errors. Example: One dev `throw`s and another dev uses the function without prior knowledge that the function will throw. Thus, and edge case has been left unhandled and now you have unhappy users, bosses, cats, etc.\n\nWith all that said, there are definitely good use cases for throwing in your program. But much less than you might think.\n\n### License\n\nThe neverthrow project is available as open source under the terms of the [MIT license](https://github.com/supermacro/neverthrow/blob/master/LICENSE).\n","funding_links":["https://github.com/sponsors/supermacro/","https://ko-fi.com/gdelgado)!"],"categories":["TypeScript","typescript","Recently Updated","Packages","**1. Libraries**","Libraries"],"sub_categories":["[May 11, 2025](/content/2025/05/11/README.md)","Others","Algebraic Data Types"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermacro%2Fneverthrow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupermacro%2Fneverthrow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupermacro%2Fneverthrow/lists"}