TypeScript Nullable

Common errors

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

  cause 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

  cause 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'.

  cause 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.

Warnings

• breaking The 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.
• gotcha All 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)`).
• gotcha The `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.

Install

• npm install typescript-nullable npm
• yarn add typescript-nullable yarn
• pnpm add typescript-nullable pnpm

Imports

• 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
  wrong:

  import { isSome } from 'typescript-nullable';

  correct:

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

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

  import { None } from 'typescript-nullable';

  correct:

  type None = null | undefined;

  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.

Quickstart

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)}`);