Registry / serialization / typescript-nullable

typescript-nullable

library0.6.0jsnpmunverified

typescript-nullable is a utility library for TypeScript that formalizes the concept of possibly absent values, providing a type-safe and functional approach to handling `null` and `undefined`. It defines a `Nullable<T>` type, which is explicitly `T | null | undefined`, mirroring the `Maybe` type found in functional languages like Haskell or Elm. Beyond the type definition, the library exports a `Nullable` object containing a suite of utility functions designed to interact safely with these potentially absent values. These functions, such as `map`, `withDefault`, `isNone`, and `isSome`, are curried and pure, promoting a functional programming style and enhancing type safety by leveraging TypeScript's type guards. As of version 0.6.0, the library is actively maintained, with incremental updates focusing on API refinements and feature additions, though a specific release cadence is not formally published. Its core value proposition lies in enabling developers to write more resilient code by explicitly managing the presence or absence of values, thereby reducing runtime errors associated with unexpected `null` or `undefined` references and offering a robust alternative to imperative null checks.

serialization

npm install typescript-nullable

github ↗package ↗

INSTALL

IMPORT

SIG · TYPESCRIPT-NULLABL

typescript-nullable

serializationjavascriptv0.6.0

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.

Nullable

✓ import { Nullable } from 'typescript-nullable';

This named import provides both the `Nullable<T>` type for type annotations and the `Nullable` object that contains all utility functions.

Nullable object functions

✓ import { Nullable } from 'typescript-nullable'; Nullable.isSome(value);

✗ import { isSome } from 'typescript-nullable';

Utility functions like `isSome`, `map`, and `withDefault` are properties of the imported `Nullable` object, not direct named exports from the package root.

None

✓ type None = null | undefined;

✗ import { None } from 'typescript-nullable';

The `None` type is an internal type alias (`null | undefined`) used in the definition of `Nullable<T>` and is not directly exported for import. You should define it locally if needed, or use `null | undefined` directly.

This quickstart demonstrates the core `Nullable<T>` type definition and shows how to use key utility functions like `map`, `withDefault`, `isSome`, and `isNone` with examples of currying and TypeScript type guards for safe null handling.

import { Nullable } from 'typescript-nullable'; // Demonstrate Nullable type definition implicitly type UserName = Nullable<string>; const userName1: UserName = 'Alice'; const userName2: UserName = null; const userName3: UserName = undefined; console.log(`User Name 1: ${userName1}`); console.log(`User Name 2: ${userName2}`); console.log(`User Name 3: ${userName3}`); // Demonstrate utility functions const toUpperCase = (text: string) => text.toUpperCase(); // Nullable.map - example with curried usage const mappedName1 = Nullable.map(toUpperCase)(userName1); const mappedName2 = Nullable.map(toUpperCase)(userName2); console.log(`Mapped Name 1: ${mappedName1}`); console.log(`Mapped Name 2: ${mappedName2}`); // Nullable.withDefault const displayName1 = Nullable.withDefault('Guest')(userName1); const displayName2 = Nullable.withDefault('Guest')(userName2); console.log(`Display Name 1: ${displayName1}`); console.log(`Display Name 2: ${displayName2}`); // Nullable.isSome and Nullable.isNone with TypeScript type guards const potentiallyNullString: Nullable<string> = Math.random() > 0.5 ? 'Hello' : null; if (Nullable.isSome(potentiallyNullString)) { console.log(`Value is present: ${potentiallyNullString.length}`); // TS knows it's a string here } else { console.log('Value is absent.'); // TS knows it's null | undefined here } // Explicit currying example const mapToUpper = Nullable.map(toUpperCase); console.log(`Curried map result: ${mapToUpper('world')}`); console.log(`Curried map result (null): ${mapToUpper(null)}`);

Debug

Known issues

breakingThe library is currently in version 0.x.x, indicating that the API might not be stable. Expect potential breaking changes in minor or even patch releases before a 1.0.0 release.

fix

Always pin to exact versions (e.g., `"typescript-nullable": "~0.6.0"` or `"^0.6.0"` carefully) and review release notes for any new updates.

affects: <1.0.0

gotchaAll utility functions are curried, meaning they can be called with arguments one at a time, returning new functions until all arguments are satisfied. Forgetting this pattern can lead to unexpected `TypeError`s.

fix

Ensure you call curried functions correctly, either by providing all arguments at once (e.g., `Nullable.map(func, value)`) or by explicitly chaining calls (e.g., `Nullable.map(func)(value)`).

affects: >=0.1.0

gotchaThe `Nullable` symbol is used for both the `Nullable<T>` type and the `Nullable` object containing utility functions. While convenient in TypeScript, it can be confusing if you expect them to be separate imports or if migrating from languages with distinct type/value namespaces.

fix

Be mindful that `Nullable` refers to both the type and the value-level object. TypeScript handles this distinction correctly in most contexts, but avoid shadowing or ambiguous variable names.

affects: >=0.1.0

Errors

Common errors & fixes

TS2305: Module '"typescript-nullable"' has no exported member 'isSome'.

Attempting to import utility functions (like `isSome`, `map`, `withDefault`) directly from the package.

fix

Utility functions are properties of the `Nullable` object. Import `Nullable` and then access the functions: `import { Nullable } from 'typescript-nullable'; Nullable.isSome(value);`

TypeError: Nullable.map is not a function

This usually happens when `Nullable` is not imported correctly, or when using CommonJS `require` without properly handling the ES module interop, leading to `Nullable` being `undefined` or an unexpected object.

fix

Ensure you are using `import { Nullable } from 'typescript-nullable';` for ESM environments. If in CommonJS, try `const { Nullable } = require('typescript-nullable');` or `const Nullable = require('typescript-nullable').Nullable;`

TS2305: Module '"typescript-nullable"' has no exported member 'None'.

Attempting to import the `None` type alias directly from the package.

fix

The `None` type is an internal alias for `null | undefined` and is not exported. You should use `null | undefined` directly or define your own `type None = null | undefined;` if you wish to use that alias in your code.

Upgrade

Version history

0.6.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kylecorbelli/typescript-nullable ↗

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