TypeScript Result Type for Error Handling

Common errors

• Property 'value' does not exist on type 'Err<any>'

  cause Attempting to access the `value` property on a `Result` that is an `Err` variant without first checking its type.
  fix Always use `if (result.isOk()) { /* access result.value */ }` or other safe methods (`map`, `andThen`, `match`) to ensure you are operating on an `Ok` variant.

• TypeError: Cannot read properties of undefined (reading 'unwrap')

  cause This typically occurs in JavaScript (runtime) when `unwrap()` is called on a `Result` instance that is actually `undefined` or `null`, often due to a preceding operation failing silently or not returning a `Result` as expected.
  fix Ensure that the variable you are calling `unwrap()` on is indeed a `Result` instance. In TypeScript, this is usually caught at compile-time. If it's a valid `Result` but `Err`, the error will be `Error: Called unwrap() on an Err value`.

• Error: Called unwrap() on an Err value

  cause The `unwrap()` method was invoked on a `Result` instance that contained an error (`Err` variant). This is by design to explicitly throw if an error is unhandled.
  fix Refactor your code to explicitly handle the `Err` case using `isOk()`, `mapErr()`, `orElse()`, or `match()` before attempting to access the successful `value`. Only use `unwrap()` when you are absolutely certain the `Result` will always be `Ok` (e.g., after validation).

• Error: [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()

  cause Attempting to import `typescript-result` using CommonJS `require()` syntax in an environment configured for ES Modules, or when the library itself is primarily ESM.
  fix Switch to ES Module import syntax: `import { Result } from 'typescript-result';`. Ensure your project's `package.json` has `"type": "module"` or use a bundler that transpiles correctly.

Warnings

• gotcha Calling `unwrap()` or `expect()` on an `Err` result will throw a runtime error, bypassing the type-safety benefits of the Result type. Always check `isOk()` or use safe methods like `mapErr()`, `andThen()`, `orElse()`, or `match()` to handle the error variant explicitly.
  Fix: Use `if (result.isOk()) { ... } else { ... }` blocks or methods like `result.mapErr(() => ...)` and `result.match().when(...)` to safely handle both success and error cases.
• breaking Prior to v3.5.2, the static methods `Result.try` and `Result.fromAsyncCatching` might not have caught exceptions thrown *inside* their error transformation callbacks (the `errorFn` argument). This could lead to uncaught exceptions escaping the `Result`'s handling mechanism.
  Fix: Upgrade to `typescript-result@3.5.2` or higher to ensure that errors within error transformation callbacks are properly caught and encapsulated within the `Err` variant.
• gotcha Before v3.4.1, using generator syntax (`yield*`, `async function*`) with `Result` types could fail due to an incorrect `@internal` annotation on the `[Symbol.iterator]()` method, preventing proper iteration.
  Fix: Update to `typescript-result@3.4.1` or later if you are using generators with `Result` types to ensure correct functionality. Manual iteration or workarounds were necessary on older versions.
• gotcha Prior to v3.5.1, TypeScript's inference engine could struggle with `Result` types when the underlying success `value` had a structural shape that overlapped with the `Result` type itself (e.g., an object with an `ok` or `error` property). This could lead to incorrect type narrowing.
  Fix: Upgrade to `typescript-result@3.5.1` or later. If upgrading isn't immediately possible, explicit type assertions (`as Result<T, E>`) might be necessary to guide the TypeScript compiler.

Install

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

Imports

• Result
  wrong:

  const { Result, Ok, Err } = require('typescript-result')

  correct:

  import { Result, Ok, Err } from 'typescript-result'

  The library primarily uses ES Modules. Use named imports for core types and constructors. CommonJS `require()` may lead to issues in modern environments or bundling.
• Ok
  wrong:

  import { ok } from 'typescript-result'

  correct:

  import { Ok } from 'typescript-result'

  `Ok` is a class constructor for the success variant, typically imported as a named export. It's not a default export or a lowercase helper.
• fromAsyncCatching
  wrong:

  import { fromAsyncCatching } from 'typescript-result'

  correct:

  import { Result } from 'typescript-result'; const asyncOp = Result.fromAsyncCatching(async () => {...});

  `fromAsyncCatching` is a static method on the `Result` class, not a standalone export. Access it via `Result.fromAsyncCatching`.

Quickstart

Demonstrates asynchronous `Result` usage, basic error checking with `isOk()`, accessing `value` or `error`, and handling different error types using the `match()` method.

import { Result, Ok, Err } from 'typescript-result';

interface User { id: string; name: string; }

// Simulate a database operation that might fail
async function getUserById(id: string): Promise<Result<User, Error>> {
  return new Promise(resolve => {
    setTimeout(() => {
      if (id === '123') {
        resolve(Ok({ id: '123', name: 'Alice' }));
      } else if (id === 'error') {
        resolve(Err(new Error('Database error: Failed to fetch user.')));
      } else {
        resolve(Err(new Error('User not found.')));
      }
    }, 100);
  });
}

async function processUser(userId: string) {
  const userResult = await getUserById(userId);

  if (userResult.isOk()) {
    console.log(`Successfully fetched user: ${userResult.value.name}`);
    // Further processing with userResult.value
  } else {
    console.error(`Failed to fetch user: ${userResult.error.message}`);
    // Handle specific errors using match() available since v3.5.0
    userResult
      .match()
      .when(Error, (err) => {
        if (err.message.includes('not found')) {
          console.warn('User ID not recognized.');
        } else {
          console.error(`Unhandled error type: ${err.message}`);
        }
      })
      .run();
  }
}

processUser('123'); // Success
processUser('456'); // User not found
processUser('error'); // Database error