Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Result
✓ import { Result } from 'ts-results'
✗ const Result = require('ts-results').Result
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
✓ import { Ok } from 'ts-results'
✗ import { ok } from 'ts-results' // Case sensitive
Use 'Ok' for a successful result. It can be instantiated directly as 'new Ok(value)' or as a factory function 'Ok(value)'.
Err
✓ import { Err } from 'ts-results'
✗ import { error } from 'ts-results' // Incorrect name for the error variant
Use 'Err' for a failed result. Like 'Ok', it can be instantiated as 'new Err(error)' or 'Err(error)'.
Option
✓ import { Option } from 'ts-results'
✗ import { option } from 'ts-results'
The Option type represents an optional value: either Some(value) or None.
Some
✓ import { Some } from 'ts-results'
✗ import { Value } from 'ts-results' // Not a part of the API
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'.
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);
Debug
Known issues
gotchaThe 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'.fixFor 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.
affects: >=1.0.0
deprecatedThe 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.fixEvaluate migrating to `ts-results-es` (e.g., `npm install ts-results-es`). Be aware of API changes in the fork (see related warning).
affects: >=3.3.0
breakingIf 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()`.fixUpdate 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()`).
affects: >=1.0.0 (when migrating to ts-results-es >=1.0.0)
Errors
Common errors & fixes
Cannot use import statement outside a module
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.
fix1. 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>'
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.
fixAlways 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`.
Audit
Dependencies
No dependency data recorded yet.