Option Type for JavaScript

Common errors

• TypeError: Cannot read properties of null (reading 'value') OR TypeError: Cannot read property 'value' of undefined

  cause Attempting to access `.value()` on an `option.none` instance after it was converted implicitly or explicitly from `null` or `undefined`.
  fix Refactor code to use safe unwrapping methods like `option.valueOrElse(defaultValue)` or `option.map(func).valueOrElse(defaultValue)` instead of direct `.value()` calls on potentially empty options.

• Error: value of none()

  cause Directly calling `.value()` on an `option.none` instance, which is explicitly designed to throw an error in this scenario.
  fix Use methods that handle the 'none' case gracefully, such as `.map()`, `.flatMap()`, or `.valueOrElse(defaultValue)` to provide a fallback value or transform the option without directly unwrapping it when it might be empty.

Warnings

• abandoned The `option` package (mwilliamson/node-options) has not been updated in approximately nine years (last published version 0.2.4). It is considered abandoned and may have unaddressed bugs or security vulnerabilities.
  Fix: Consider migrating to a more actively maintained option/maybe type library in the JavaScript ecosystem, such as 'fp-ts', 'neverthrow', or similar alternatives that provide better modern JavaScript/TypeScript support and community backing.
• gotcha Attempting to call `.value()` directly on an `option.none` instance will throw a runtime error. This design choice forces explicit handling of the 'none' case, but can lead to unhandled exceptions if not properly anticipated.
  Fix: Always use safer methods like `.valueOrElse(defaultValue)`, `.map()`, `.flatMap()`, or `.orElse()` to handle the absence of a value. Wrap direct `.value()` calls in `try...catch` blocks if absolutely necessary, but prefer functional approaches.
• gotcha This package is written in CommonJS and does not provide native TypeScript typings or explicit ESM (ECMAScript Modules) support. Integrating it into modern TypeScript or ESM-first projects may require manual type declarations or CJS interoperability layers.
  Fix: For TypeScript projects, you may need to create a `d.ts` declaration file (e.g., `declare module 'option';`). For ESM, it can be imported using `import * as option from 'option';` in Node.js, but native ESM support is not guaranteed.

Install

• npm install option npm
• yarn add option yarn
• pnpm add option pnpm

Imports

• option
  wrong:

  import option from 'option';

  correct:

  const option = require('option');

  The package is CommonJS-only. There is no official ESM support.
• option.some
  wrong:

  import { some } from 'option';

  correct:

  const someValue = option.some('hello');

  Some is a property of the default export, not a named export. Requires CommonJS.
• option.none
  wrong:

  import { none } from 'option';

  correct:

  const noValue = option.none;

  None is a property of the default export, not a named export. Requires CommonJS.
• option.fromNullable

  const maybeValue = option.fromNullable(someNullableVar);

  A utility function to convert null or undefined to option.none.

Quickstart

Demonstrates creating 'some' and 'none' options, performing checks, safely unwrapping values with `valueOrElse`, and using `fromNullable`.

const option = require("option");

// Creating Option instances
const someUser = option.some({
    id: 1,
    name: () => "Alice"
});
const noUser = option.none;

// Basic checks
console.log(`someUser isSome: ${someUser.isSome()}`); // true
console.log(`noUser isNone: ${noUser.isNone()}`);     // true

// Retrieving values safely
function greet(userOption) {
    return userOption.map(user => user.name())
                     .valueOrElse("Anonymous");
}

console.log(`Greeting someUser: Hello ${greet(someUser)}`); // Hello Alice
console.log(`Greeting noUser: Hello ${greet(noUser)}`);     // Hello Anonymous

// Using fromNullable
const nullableString = Math.random() > 0.5 ? "A string" : null;
const safeOption = option.fromNullable(nullableString);
console.log(`From nullable: ${safeOption.valueOrElse("No string provided")}`);