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.
Maybe
✓ import { Maybe, Just, Nothing } from 'purify-ts'
✗ const Maybe = require('purify-ts').Maybe
Purify-TS is primarily designed for ESM usage in TypeScript. While CJS 'require' might technically work in some setups, it's not the recommended or fully supported way, especially since v2.0.0 removed dedicated CJS builds.
Either
✓ import { Either, Left, Right } from 'purify-ts'
✗ import Either from 'purify-ts/Either'
All major ADTs (Maybe, Either, MaybeAsync, EitherAsync) and helper functions are directly exported from the main 'purify-ts' module. Do not attempt to import from subpaths unless explicitly documented.
MaybeAsync
✓ import { MaybeAsync } from 'purify-ts'
✗ import { MaybeAsyncTypeRef } from 'purify-ts'
While `MaybeAsyncTypeRef` is exported since v2.0.0, the primary symbol for constructing and working with async maybes is `MaybeAsync` itself. TypeRef is for advanced type-level usage.
This quickstart demonstrates the core usage of Purify-TS's Maybe and Either ADTs for safely handling optional values and propagating errors, respectively. It also shows `fromPredicate` for type-safe validation.
import { Maybe, Either, Just, Nothing, Left, Right } from 'purify-ts';
// Example 1: Handling optional values with Maybe
function getUserEmail(id: number): Maybe<string> {
const users = {
1: { name: 'Alice', email: 'alice@example.com' },
2: { name: 'Bob', email: undefined },
3: { name: 'Charlie', email: 'charlie@example.com' }
};
const user = users[id];
return Maybe.fromNullable(user?.email); // Safely get email, handles null/undefined
}
console.log(`User 1 email: ${getUserEmail(1).map(e => e.toUpperCase()).getOrElse('No email found')}`);
// Expected: User 1 email: ALICE@EXAMPLE.COM
console.log(`User 2 email: ${getUserEmail(2).map(e => e.toUpperCase()).getOrElse('No email found')}`);
// Expected: User 2 email: No email found
console.log(`User 4 email: ${getUserEmail(4).map(e => e.toUpperCase()).getOrElse('No email found')}`);
// Expected: User 4 email: No email found
// Example 2: Working with Either for success/failure
function divide(a: number, b: number): Either<string, number> {
return b === 0 ? Left('Cannot divide by zero') : Right(a / b);
}
const result1 = divide(10, 2);
result1.ifRight(val => console.log(`10 / 2 = ${val}`)); // Expected: 10 / 2 = 5
result1.ifLeft(err => console.error(`Error: ${err}`));
const result2 = divide(10, 0);
result2.ifRight(val => console.log(`10 / 0 = ${val}`));
result2.ifLeft(err => console.error(`Error: ${err}`)); // Expected: Error: Cannot divide by zero
// Example 3: Using fromPredicate with type guards
const isPositive = (num: number): num is number => num > 0;
const maybePositive = Maybe.fromPredicate(isPositive, 5);
console.log(`Is 5 positive? ${maybePositive.isJust()}`); // Expected: Is 5 positive? true
const maybeNegative = Maybe.fromPredicate(isPositive, -1);
console.log(`Is -1 positive? ${maybeNegative.isJust()}`); // Expected: Is -1 positive? false
Debug
Known issues
breakingVersion 2.0.0 introduced significant breaking changes, including changing the default TypeScript compile target from `es5` to `es2015`. It also removed the legacy `/es` build output, replacing it with a new `/esm` output. Projects relying on older compile targets or specific build paths will need to adjust their configurations.fixEnsure your TypeScript compiler target is `es2015` or higher. Update import paths, especially if you were previously targeting specific CommonJS or ES Module sub-paths, as the main 'purify-ts' module now exports everything directly for ESM.
affects: >=2.0.0
gotchaMultiple recent versions (2.1.3, 2.1.1, 2.0.2) have shipped with broken ESM builds, explicitly marked as 'DO NOT USE' in release notes. This can lead to module resolution errors or runtime issues in ESM projects.fixAlways check the release notes for any new version before updating. If you encounter ESM build issues, downgrade to the previous stable version (e.g., 2.1.4 is stable after 2.1.3's broken build) or consult the official GitHub issues for a workaround.
affects: 2.0.2, 2.1.1, 2.1.3
gotchaWhile Purify-TS is written with TypeScript and type safety in mind, explicit support for newer TypeScript versions (e.g., TS 5.5 support in v2.1.0) implies potential type-related compatibility issues with significantly older TypeScript compiler versions.fixIt is recommended to use a recent stable version of TypeScript (e.g., TS 5.0+). If you encounter type errors, try updating your TypeScript compiler to match or exceed the version officially supported by your Purify-TS library version.
affects: <2.1.0 (for TS <5.5)
gotchaPre-v2.0.0, the structure and export patterns might differ, particularly for async ADTs like `MaybeAsync` and `EitherAsync`. Issues like incorrect type definitions for `ap` and `extend` were fixed in older versions (e.g., v1.3.5).fixUpgrade to v2.0.0 or later for the most stable and consistent API, especially if you are working with asynchronous operations and functional combinators.
affects: <2.0.0
Errors
Common errors & fixes
Module not found: Can't resolve 'purify-ts'
This often occurs when using one of the Purify-TS versions known to have a broken ESM build (e.g., 2.0.2, 2.1.1, 2.1.3) or when a bundler struggles with the module resolution after the v2.0.0 build changes.
fixCheck your `purify-ts` version. If it's one of the problematic ones, update to the latest stable patch (e.g., `npm install purify-ts@latest`). Ensure your `tsconfig.json` `moduleResolution` is set appropriately for ESM (`bundler` or `node16`).
TypeError: __webpack_require__(...).Maybe is not a function
This error typically indicates an attempt to `require` Purify-TS in a CommonJS context when it's expecting an ESM import, or a mixing of module systems that Webpack (or another bundler) cannot reconcile with the library's ES module output.
fixFor modern TypeScript projects, always use `import { Maybe } from 'purify-ts';` instead of `const Maybe = require('purify-ts').Maybe;`. Ensure your project's `package.json` has `"type": "module"` if you intend to use ESM natively, or configure your bundler to correctly handle ES module imports. Property 'map' does not exist on type 'unknown' or 'any'
This can happen if you're not correctly handling the `Maybe` or `Either` types, perhaps extracting values too early, or if TypeScript's type inference is failing due to incorrect usage, leading to the value being treated as `unknown` or `any`.
fixEnsure you are using `map`, `chain`, `ap`, or other combinators on the `Maybe` or `Either` instance itself, rather than attempting to access properties on the extracted value before it's guaranteed to be present (e.g., after `getOrElse`). Verify your TypeScript version is compatible with Purify-TS.
Audit
Dependencies
No dependency data recorded yet.