ts-results: Rust-like Result and Option for TypeScript

Common errors

• Cannot use import statement outside a module

  cause The `ts-results` package (v3.3.0) is primarily configured as CommonJS. When a project is set up for ES Modules (`"type": "module"` in `package.json` or `.mjs` files), direct `import` statements for CJS packages can cause this error.
  fix 1. If your project *must* be ESM, consider migrating to the `ts-results-es` fork which has explicit ESM support. 2. If staying with `ts-results`, ensure your build process (e.g., Webpack, Rollup) or TypeScript configuration (`tsconfig.json`) correctly handles CommonJS interoperability, or configure your output module system to CommonJS (`"module": "CommonJS"`). 3. For Node.js, you might need to use `require()` if not using a bundler, but this can lead to type issues.

• Property 'val' does not exist on type 'Err<E>'

  cause This error occurs when attempting to access `result.val` directly on an `Err` variant of a `Result<T, E>` without a preceding type guard (e.g., `if (result.ok)`), or attempting to access `result.val` on an `Ok` variant when `val` refers to the error type.
  fix Always use a type guard to narrow the `Result` type before accessing its value. For an `Ok` result, check `if (result.ok)` then `result.val` will be `T`. For an `Err` result, check `if (!result.ok)` (or `if (result.err)` if using the fork), then `result.val` will be `E`.

Warnings

• gotcha The original `ts-results` package (v3.3.0) primarily targets CommonJS modules. Using it in native ES Module environments without proper transpilation (e.g., via a bundler) may lead to import errors like 'Cannot use import statement outside a module' or 'require is not defined'.
  Fix: For active maintenance and full ES Module compatibility, consider migrating to the `ts-results-es` fork. Otherwise, ensure your build configuration correctly handles CommonJS dependencies within an ESM project, or configure your TypeScript compiler to output CommonJS.
• deprecated The original `ts-results` package has not been updated since 2021 (v3.3.0). It is effectively in a maintenance state with no active development. Users seeking new features, bug fixes, or dedicated ESM support should consider the `ts-results-es` fork, which is actively maintained.
  Fix: Evaluate migrating to `ts-results-es` (e.g., `npm install ts-results-es`). Be aware of API changes in the fork (see related warning).
• breaking If migrating from `ts-results` to the `ts-results-es` fork, be aware of API breaking changes. Direct property access like `result.val` (for `Ok` and `Some` values) and `result.val` (for `Err` errors) have been replaced by `.value` or `.error` respectively. Additionally, boolean flags like `result.ok`, `result.err`, `option.some`, `option.none` are replaced by methods such as `result.isOk()`, `result.isErr()`, `option.isSome()`, `option.isNone()`.
  Fix: Update property access from `.val` to `.value` (for `Ok`/`Some`) or `.error` (for `Err`). Replace boolean checks (`.ok`, `.err`, `.some`, `.none`) with their respective method calls (`.isOk()`, `.isErr()`, `.isSome()`, `.isNone()`).

Install

• npm install ts-results npm
• yarn add ts-results yarn
• pnpm add ts-results pnpm

Imports

• Result
  wrong:

  const Result = require('ts-results').Result

  correct:

  import { Result } from 'ts-results'

  While 'ts-results' v3.3.0 ships with CommonJS support, ES Module imports are the standard for modern TypeScript. The original package may have issues with native ESM environments without proper configuration or a bundler.
• Ok
  wrong:

  import { ok } from 'ts-results' // Case sensitive

  correct:

  import { Ok } from 'ts-results'

  Use 'Ok' for a successful result. It can be instantiated directly as 'new Ok(value)' or as a factory function 'Ok(value)'.
• Err
  wrong:

  import { error } from 'ts-results' // Incorrect name for the error variant

  correct:

  import { Err } from 'ts-results'

  Use 'Err' for a failed result. Like 'Ok', it can be instantiated as 'new Err(error)' or 'Err(error)'.
• Option
  wrong:

  import { option } from 'ts-results'

  correct:

  import { Option } from 'ts-results'

  The Option type represents an optional value: either Some(value) or None.
• Some
  wrong:

  import { Value } from 'ts-results' // Not a part of the API

  correct:

  import { Some } from 'ts-results'

  Use 'Some' to represent the presence of a value within an 'Option'.
• None

  import { None } from 'ts-results'

  Use 'None' to represent the absence of a value within an 'Option'.

Quickstart

Demonstrates `Result` for explicit error handling in a file read operation and `Option` for handling potentially missing user configuration values, ensuring type safety at compile time.

import { Ok, Err, Result, Some, None, Option } from 'ts-results';
import { readFileSync, existsSync } from 'fs';

// --- Result Example: Handling file operations ---

function readFileSafe(path: string): Result<string, 'file_not_found' | 'read_error'> {
  if (!existsSync(path)) {
    return new Err('file_not_found');
  }
  try {
    const content = readFileSync(path, 'utf8');
    return new Ok(content);
  } catch (e) {
    return new Err('read_error');
  }
}

const filePath = 'test.txt';
// Simulate creating a file for the example
require('fs').writeFileSync(filePath, 'Hello, ts-results world!');

const fileResult = readFileSafe(filePath);

if (fileResult.ok) {
  console.log(`File content: ${fileResult.val}`);
} else {
  console.error(`Error reading file: ${fileResult.val}`);
}

// --- Option Example: Handling potentially missing configuration ---

interface UserConfig {
  theme?: string;
  notificationsEnabled?: boolean;
}

function getUserTheme(config: UserConfig): Option<string> {
  if (config.theme) {
    return new Some(config.theme);
  } else {
    return None;
  }
}

const userSettings: UserConfig = { notificationsEnabled: true };
const themeOption = getUserTheme(userSettings);

if (themeOption.some) {
  console.log(`User theme: ${themeOption.val}`);
} else {
  console.log('User theme not set, using default.');
}

// Clean up simulated file
require('fs').unlinkSync(filePath);