Registry / serialization / typescript-optional

typescript-optional

library3.0.0-alpha.3jsnpmunverified

typescript-optional provides an implementation of the `Optional<T>` type, inspired by Java 8+'s `Optional` class, designed to help developers manage the presence or absence of a value without resorting to null or undefined checks. It aims to reduce `NullPointerExceptions` (or `TypeError` in JavaScript) by providing a fluent API for handling nullable values. The current stable version is 2.0.1, though a 3.0.0-alpha.3 pre-release is available, indicating active development. The package has seen irregular release cycles, with a previous 2.0.0 release being abandoned due to deployment issues before 2.0.1 stabilized it. Key differentiators include its strong typing with TypeScript, direct inspiration from Java's `Optional` API (e.g., `isPresent`, `map`, `orElse`), and methods like `orNull()` and `orUndefined()` for easy conversion back to native JavaScript nullable types. It focuses on the core `Optional` functionality, explicitly noting missing methods like `equals` or `toString` compared to its Java counterpart.

serialization

npm install typescript-optional

github ↗package ↗

INSTALL

IMPORT

SIG · TYPESCRIPT-OPTIONA

typescript-optional

serializationjavascriptv3.0.0-alpha.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Optional

✓ import { Optional } from 'typescript-optional';

✗ const { Optional } = require('typescript-optional');

Primarily designed for ESM and TypeScript; CommonJS `require` is generally discouraged in modern TypeScript projects.

Optional (type import)

✓ import type { Optional } from 'typescript-optional';

✗ import { Optional } from 'typescript-optional';

Using `import type` is preferred for type-only imports to prevent accidental runtime side effects or bundle size issues.

Optional.ofNullable

✓ Optional.ofNullable(value);

✗ new Optional(value);

Always use static factory methods like `ofNullable`, `ofNonNull`, or `empty` to create `Optional` instances, as the constructor may not be public or stable.

Demonstrates how to import, create, and perform common operations like checking presence, conditional execution, mapping, filtering, and providing default values with the `Optional` class.

import { Optional } from "typescript-optional"; // Example with a potentially null string const userName: string | null = Math.random() > 0.5 ? "Alice" : null; const optionalUserName: Optional<string> = Optional.ofNullable(userName); console.log(`Is name present? ${optionalUserName.isPresent()}`); // Using ifPresentOrElse to handle both cases optionalUserName.ifPresentOrElse( (name) => console.log(`Hello, ${name}!`), () => console.log("User name is not available.") ); // Map and filter operations const nameLength: Optional<number> = optionalUserName .filter((name) => name.length > 3) .map((name) => name.length); nameLength.ifPresent((len) => console.log(`Name length (if > 3): ${len}`)); // Providing a default value const displayUserName: string = optionalUserName.orElse("Guest"); console.log(`Display name: ${displayUserName}`); // Converting to nullable JavaScript types const rawName: string | null = optionalUserName.orNull(); console.log(`Raw name (or null): ${rawName}`);

Debug

Known issues

breakingVersion 2.0.0 introduced several breaking changes, including `Optional#isPresent` and `Optional#isEmpty` changing from accessors (properties) to methods. `Optional#map` also had its type signature refined, representing that it exactly returns a value whose payload is non-null type, and `Optional.toJSON` was added.

fix

Update calls like `optional.isPresent` to `optional.isPresent()` and `optional.isEmpty` to `optional.isEmpty()`.

affects: >=2.0.0

gotchaThe `get()` method will throw a `TypeError` if the `Optional` instance is empty (does not contain a value). This behavior is consistent with Java's `Optional.get()` but is a common source of runtime errors if not properly guarded.

fix

Always check `optional.isPresent()` before calling `get()`, or use safer methods like `orElse()`, `orElseGet()`, `orElseThrow()`, `orNull()`, or `orUndefined()` to retrieve the value.

affects: >=1.0.0

gotchaThe static factory method `Optional.ofNonNull()` will throw a `TypeError` if the provided argument is `null` or `undefined`. It is specifically designed for situations where you expect a non-null value.

fix

Use `Optional.ofNullable(value)` instead if the value might be `null` or `undefined`. Only use `ofNonNull` when you are certain the value is not null.

affects: >=1.8.0

breakingThe `v2.0.0` release was initially abandoned due to deployment issues. While `v2.0.1` fixed these, developers targeting `v2` should ensure they use `v2.0.1` or newer to avoid potential problems.

fix

Upgrade to `typescript-optional@2.0.1` or a later compatible version.

affects: 2.0.0

Errors

Common errors & fixes

TypeError: optional.isPresent is not a function

In `typescript-optional` v2.0.0 and later, `isPresent` (and `isEmpty`) changed from a property accessor to a method.

fix

Change `optional.isPresent` to `optional.isPresent()` and `optional.isEmpty` to `optional.isEmpty()`.

TypeError: Cannot retrieve payload from empty Optional

You attempted to call the `get()` method on an `Optional` instance that does not contain a value.

fix

Before calling `get()`, verify the presence of a value with `optional.isPresent()`, or use alternative methods like `orElse()`, `orElseGet()`, `orNull()`, or `orUndefined()` to safely handle empty optionals.

TypeError: value must not be null

You passed `null` or `undefined` to `Optional.ofNonNull()`, which explicitly requires a non-null/non-undefined argument.

fix

If the value might be `null` or `undefined`, use `Optional.ofNullable(value)` instead. Only use `Optional.ofNonNull()` when you are absolutely sure the value is present.

Upgrade

Version history

3.0.0-alpha.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bromne/typescript-optional ↗

packagehttps://www.npmjs.com/package/typescript-optional ↗