Add Option.{fromNullable, fromOptional, fromNullish} (#253)

I keep reimplementing these in projects using ts-results-es,
I figured the could be added to the core.

Add three static methods to the Option namespace for converting
nullable, optional, and nullish values to Option<T>. fromNullable
and fromOptional are the preferred APIs for T | null and T | undefined
respectively as they avoid accidentally treating undefined and null
the same way if the input type ever changes. fromNullish handles
tT | null | undefined.

Author: jstasiak

CHANGELOG.md

@@ -8,6 +8,9 @@ Backwards incompatible:
 
 Added:
 
+- Added `Option.fromNullable`, `Option.fromOptional`, and `Option.fromNullish`
+  static methods for converting nullable, optional, and nullish values to
+  `Option`.
 - Added array parameter overloads for `Option.all` and `Option.any`,
   allowing `Option.all([a, b, c])` instead of `Option.all(a, b, c)`.
 

docs/explanation/index.rst

@@ -2,4 +2,5 @@ Explanation
 ===========
 
 .. toctree::
+    nullable-optional-nullish
     ts-results-relationship

docs/explanation/nullable-optional-nullish.rst

@@ -0,0 +1,42 @@
+.. _explanation-nullable-optional-nullish:
+
+Why three methods for converting nullable values to Option
+==========================================================
+
+TypeScript distinguishes between ``null`` and ``undefined``, but it is common to treat them
+interchangeably using the ``T | null | undefined`` (nullish) type. This is not always correct.
+
+``null`` and ``undefined`` can carry different meanings. A value that is ``null`` might mean
+"explicitly empty" while ``undefined`` might mean "not yet provided." If your code conflates the
+two, a type change from ``T | null`` to ``T | null | undefined`` — intended to introduce a new
+``undefined`` case that should be handled differently — will compile silently and the new case
+will be swallowed.
+
+This is why ts-results-es provides three separate methods:
+
+- :ref:`fromNullable() <method-Option-fromNullable>` for ``T | null`` — only ``null`` becomes
+  ``None``, ``undefined`` stays in ``Some``.
+- :ref:`fromOptional() <method-Option-fromOptional>` for ``T | undefined`` — only ``undefined``
+  becomes ``None``, ``null`` stays in ``Some``.
+- :ref:`fromNullish() <method-Option-fromNullish>` for ``T | null | undefined`` — both ``null``
+  and ``undefined`` become ``None``.
+
+By using the most specific method, the compiler will catch it if the value type changes in a way
+that requires attention. For example, suppose you have a value of type ``string | null`` and convert
+it using :ref:`fromNullable() <method-Option-fromNullable>`:
+
+.. code-block:: typescript
+
+    const name: string | null = getName();
+    const option = Option.fromNullable(name); // Option<string>
+
+If the type of ``name`` later changes to ``string | null | undefined`` — with the intention that
+``undefined`` should be handled differently — the code above will fail to compile, forcing you to
+decide how to handle the new case. Had you used
+:ref:`fromNullish() <method-Option-fromNullish>` instead, the change would compile silently and
+``undefined`` would be swallowed into ``None``.
+
+Prefer :ref:`fromNullable() <method-Option-fromNullable>` or
+:ref:`fromOptional() <method-Option-fromOptional>` when possible. Use
+:ref:`fromNullish() <method-Option-fromNullish>` only when the value is already both nullable and
+optional and you genuinely want ``null`` and ``undefined`` to be treated the same.

docs/reference/option.rst

@@ -75,6 +75,86 @@ Example:
     Option.any([None, None, Some(3)]); // Some(3), type: Option<number>
     Option.any([None, None, None]); // None, type: Option<never>
 
+.. _method-Option-fromNullable:
+
+``fromNullable()``
+------------------
+
+.. code-block:: typescript
+
+    static fromNullable<T>(value: T): Option<Exclude<T, null>>
+
+Converts a nullable value to an :ref:`Option <class-Option>`.
+Returns ``None`` if the value is ``null``, otherwise returns ``Some`` containing the value.
+
+See also :ref:`fromOptional() <method-Option-fromOptional>` for ``T | undefined`` and :ref:`fromNullish() <method-Option-fromNullish>` for ``T | null | undefined``.
+
+See also the explanation :ref:`explanation-nullable-optional-nullish`.
+
+Example:
+
+.. code-block:: typescript
+
+    const value: string | null = 'hello';
+    Option.fromNullable(value); // Some('hello'), type: Option<string>
+
+    const missing: string | null = null;
+    Option.fromNullable(missing); // None, type: Option<string>
+
+.. _method-Option-fromOptional:
+
+``fromOptional()``
+------------------
+
+.. code-block:: typescript
+
+    static fromOptional<T>(value: T): Option<Exclude<T, undefined>>
+
+Converts an optional value to an :ref:`Option <class-Option>`.
+Returns ``None`` if the value is ``undefined``, otherwise returns ``Some`` containing the value.
+
+See also :ref:`fromNullable() <method-Option-fromNullable>` for ``T | null`` and :ref:`fromNullish() <method-Option-fromNullish>` for ``T | null | undefined``.
+
+See also the explanation :ref:`explanation-nullable-optional-nullish`.
+
+Example:
+
+.. code-block:: typescript
+
+    const value: string | undefined = 'hello';
+    Option.fromOptional(value); // Some('hello'), type: Option<string>
+
+    const missing: string | undefined = undefined;
+    Option.fromOptional(missing); // None, type: Option<string>
+
+.. _method-Option-fromNullish:
+
+``fromNullish()``
+-----------------
+
+.. code-block:: typescript
+
+    static fromNullish<T>(value: T): Option<NonNullable<T>>
+
+Converts a nullish value to an :ref:`Option <class-Option>`.
+Returns ``None`` if the value is ``null`` or ``undefined``, otherwise returns ``Some`` containing the value.
+
+Prefer :ref:`fromNullable() <method-Option-fromNullable>` for ``T | null`` or :ref:`fromOptional() <method-Option-fromOptional>` for ``T | undefined``.
+Use this method only when the value is already both nullable and optional and you genuinely want
+``null`` and ``undefined`` to be treated the same.
+
+See also the explanation :ref:`explanation-nullable-optional-nullish`.
+
+Example:
+
+.. code-block:: typescript
+
+    const value: string | null | undefined = 'hello';
+    Option.fromNullish(value); // Some('hello'), type: Option<string>
+
+    const missing: string | null | undefined = null;
+    Option.fromNullish(missing); // None, type: Option<string>
+
 .. _attribute-Some-EMPTY:
 
 ``Some.EMPTY``

src/option.ts

@@ -391,4 +391,63 @@ export namespace Option {
     export function isOption<T = any>(value: unknown): value is Option<T> {
         return value instanceof Some || value === None;
     }
+
+    /**
+     * Converts a nullable value to an {@link Option}.
+     * Returns {@link None} if the value is `null`, otherwise returns {@link Some} containing the value.
+     *
+     * See also {@link fromOptional} for `T | undefined` and {@link fromNullish} for `T | null | undefined`.
+     *
+     * @example
+     * ```typescript
+     * const value: string | null = 'hello';
+     * Option.fromNullable(value); // Some('hello'), type: Option<string>
+     *
+     * const missing: string | null = null;
+     * Option.fromNullable(missing); // None, type: Option<string>
+     * ```
+     */
+    export function fromNullable<T>(value: T): Option<Exclude<T, null>> {
+        return (value === null ? None : Some(value)) as Option<Exclude<T, null>>;
+    }
+
+    /**
+     * Converts an optional value to an {@link Option}.
+     * Returns {@link None} if the value is `undefined`, otherwise returns {@link Some} containing the value.
+     *
+     * See also {@link fromNullable} for `T | null` and {@link fromNullish} for `T | null | undefined`.
+     *
+     * @example
+     * ```typescript
+     * const value: string | undefined = 'hello';
+     * Option.fromOptional(value); // Some('hello'), type: Option<string>
+     *
+     * const missing: string | undefined = undefined;
+     * Option.fromOptional(missing); // None, type: Option<string>
+     * ```
+     */
+    export function fromOptional<T>(value: T): Option<Exclude<T, undefined>> {
+        return (value === undefined ? None : Some(value)) as Option<Exclude<T, undefined>>;
+    }
+
+    /**
+     * Converts a nullish value to an {@link Option}.
+     * Returns {@link None} if the value is `null` or `undefined`, otherwise returns {@link Some} containing the value.
+     *
+     * Prefer {@link fromNullable} for `T | null` or {@link fromOptional} for `T | undefined`.
+     * Use this method only when the value is already both nullable and optional and you genuinely
+     * want `null` and `undefined` to be treated the same.
+     *
+     * @example
+     * ```typescript
+     * const value: string | null | undefined = 'hello';
+     * Option.fromNullish(value); // Some('hello'), type: Option<string>
+     *
+     * const missing: string | null | undefined = null;
+     * Option.fromNullish(missing); // None, type: Option<string>
+     * ```
+     */
+    export function fromNullish<T>(value: T): Option<NonNullable<T>> {
+        return value === null || value === undefined ? None : Some(value);
+    }
 }

test/option.test.ts

@@ -254,3 +254,69 @@ test('iteration', () => {
     expect(Array.from(Some(1))).toEqual([1]);
     expect(Array.from(None)).toEqual([]);
 });
+
+test('fromNullable', () => {
+    const value = 'hello' as string | null;
+    const result = Option.fromNullable(value);
+    expect(result).toEqual(Some('hello'));
+    eq<Option<string>, typeof result>(true);
+
+    const missing = null as string | null;
+    const resultMissing = Option.fromNullable(missing);
+    expect(resultMissing).toEqual(None);
+    eq<Option<string>, typeof resultMissing>(true);
+
+    // Falsy but non-null values → Some
+    const zero = Option.fromNullable(0 as number | null);
+    expect(zero).toEqual(Some(0));
+    eq<Option<number>, typeof zero>(true);
+
+    // undefined is NOT null → Some(undefined)
+    const undef = Option.fromNullable(undefined as undefined | null);
+    expect(undef).toEqual(Some(undefined));
+    eq<Option<undefined>, typeof undef>(true);
+});
+
+test('fromOptional', () => {
+    const value = 'hello' as string | undefined;
+    const result = Option.fromOptional(value);
+    expect(result).toEqual(Some('hello'));
+    eq<Option<string>, typeof result>(true);
+
+    const missing = undefined as string | undefined;
+    const resultMissing = Option.fromOptional(missing);
+    expect(resultMissing).toEqual(None);
+    eq<Option<string>, typeof resultMissing>(true);
+
+    // Falsy but non-undefined values → Some
+    const zero = Option.fromOptional(0 as number | undefined);
+    expect(zero).toEqual(Some(0));
+    eq<Option<number>, typeof zero>(true);
+
+    // null is NOT undefined → Some(null)
+    const nul = Option.fromOptional(null as null | undefined);
+    expect(nul).toEqual(Some(null));
+    eq<Option<null>, typeof nul>(true);
+});
+
+test('fromNullish', () => {
+    const value = 'hello' as string | null | undefined;
+    const result = Option.fromNullish(value);
+    expect(result).toEqual(Some('hello'));
+    eq<Option<string>, typeof result>(true);
+
+    const missingNull = null as string | null | undefined;
+    const resultNull = Option.fromNullish(missingNull);
+    expect(resultNull).toEqual(None);
+    eq<Option<string>, typeof resultNull>(true);
+
+    const missingUndefined = undefined as string | null | undefined;
+    const resultUndefined = Option.fromNullish(missingUndefined);
+    expect(resultUndefined).toEqual(None);
+    eq<Option<string>, typeof resultUndefined>(true);
+
+    // Falsy but non-nullish values → Some
+    const zero = Option.fromNullish(0 as number | null | undefined);
+    expect(zero).toEqual(Some(0));
+    eq<Option<number>, typeof zero>(true);
+});