Skip to main content Link Search Menu Expand Document (external link)

NonNullableX overview

Helpers for working with non-nullable values.

Added in v0.0.0


Table of contents


mapping

lift

Adapts a function (a: A) => B to tolerate nullish input, applying it to present values and passing null/undefined through unchanged.

Where map operates on a value, lift transforms the function itself, yielding a reusable (a: A | null | undefined) => B | null | undefined you can drop into a pipe. Use it to adapt a plain transform to a nullable pipeline without wrapping each call site.

Signature

export declare const lift: <A, B>(function_: (a: A) => B) => (a: A | null | undefined) => B | null | undefined

Example

import { NonNullableX } from "@nunofyobiz/effect-extras"
import { pipe } from "effect"

// Reuse the same trimming transform across optional form fields.
const trimField = NonNullableX.lift((field: string) => field.trim())

assert.deepStrictEqual(pipe("  Mira  ", trimField), "Mira")
// Untouched fields keep their original missing value.
assert.deepStrictEqual(pipe(null, trimField), null)
assert.deepStrictEqual(pipe(undefined, trimField), undefined)

Added in v0.0.0

map

Transforms a only when it is present, passing nullish inputs through unchanged.

This is the nullable-preserving map: a present value is transformed to B, while null stays null and undefined stays undefined, so nullability is carried through the transformation. Supports both data-first and data-last (pipeable) call styles.

Signature

export declare const map: (<A, B>(map: (a: NonNullable<A>) => B) => (a: A) => B | (null & A) | (undefined & A)) &
  (<A, B>(a: A, map: (a: NonNullable<A>) => B) => B | (null & A) | (undefined & A))

Example

import { NonNullableX } from "@nunofyobiz/effect-extras"
import { pipe } from "effect"

// Turn a saved delivery address into a display label.
const address = { street: "12 Oak Street" }
assert.deepStrictEqual(
  NonNullableX.map(address, (address) => `Deliver to ${address.street}`),
  "Deliver to 12 Oak Street"
)

// An address that has not been supplied stays missing (data-last).
const missingAddress: typeof address | null = null
assert.deepStrictEqual(
  pipe(
    missingAddress,
    NonNullableX.map<typeof address | null, string>((address) => `Deliver to ${address.street}`)
  ),
  null
)

Added in v0.0.0

ordering

nullableOrder

Extends an Order.Order<A> to an Order.Order<A | null>, deciding where null sorts relative to present values via the behavior argument.

Pass "value-null" to push nulls to the end and "null-value" to pull them to the front; two present values fall back to the wrapped order. Use it to sort collections that mix real values with gaps without a bespoke comparator. Supports both data-first and data-last (pipeable) call styles.

Signature

export declare const nullableOrder: ((
  behavior: "value-null" | "null-value"
) => <A>(order: Order.Order<A>) => Order.Order<A | null>) &
  (<A>(order: Order.Order<A>, behavior: "value-null" | "null-value") => Order.Order<A | null>)

Example

import { NonNullableX } from "@nunofyobiz/effect-extras"
import { Array, Order, pipe } from "effect"

const deliveryMinutes = [null, 25, 40, null, 30]
// List measured deliveries fastest first, with missing measurements last.
assert.deepStrictEqual(pipe(deliveryMinutes, Array.sort(NonNullableX.nullableOrder(Order.Number, "value-null"))), [
  25,
  30,
  40,
  null,
  null
])

// Put missing measurements first so they can be filled in (data-last).
assert.deepStrictEqual(
  pipe(deliveryMinutes, Array.sort(pipe(Order.Number, NonNullableX.nullableOrder("null-value")))),
  [null, null, 25, 30, 40]
)

Added in v0.0.0

pattern matching

match

Branches on whether value is nullish, passing the value narrowed to NonNullable<A> to the whenNotNullable handler.

A nullable-aware sibling of Match.value: it folds a present-or-absent value into a single B without an if/else or a manual != null check. Note that falsy-but-present values ("", 0, false) take the whenNotNullable branch — only null and undefined are treated as absent. Supports both data-first and data-last (pipeable) call styles.

Signature

export declare const match: (<A, B>(handlers: {
  whenNullable: () => B
  whenNotNullable: (value: NonNullable<A>) => B
}) => (value: A) => B) &
  (<A, B>(value: A, handlers: { whenNullable: () => B; whenNotNullable: (value: NonNullable<A>) => B }) => B)

Example

import { NonNullableX } from "@nunofyobiz/effect-extras"
import { pipe } from "effect"

// Display the saved nickname when one is present.
assert.deepStrictEqual(
  NonNullableX.match("Mira", {
    whenNullable: () => "Guest",
    whenNotNullable: (nickname) => `Hello, ${nickname}`
  }),
  "Hello, Mira"
)

// Without a saved nickname, show a fallback label (data-last).
assert.deepStrictEqual(
  pipe(
    null,
    NonNullableX.match({
      whenNullable: () => "Guest",
      whenNotNullable: (nickname) => `Hello, ${nickname}`
    })
  ),
  "Guest"
)

Added in v0.0.0

unsafe

fromNullableOrThrow

Returns value narrowed to NonNullable<A>, throwing an Error if it is null or undefined.

Use it at trusted boundaries where a value is known to be present but typed as nullable, turning a silent undefined into a loud failure. An optional variableName is woven into the thrown message to aid debugging. This is the function re-exported as nn from the module barrel, a terse shorthand handy inside string interpolations.

Signature

export declare const fromNullableOrThrow: <A>(value: A, variableName?: string) => NonNullable<A>

Example

import { NonNullableX } from "@nunofyobiz/effect-extras"

const settings: { supportEmail: string | null } = {
  supportEmail: "help@example.com"
}
// A required setting can be used directly after checking this trusted boundary.
assert.deepStrictEqual(NonNullableX.fromNullableOrThrow(settings.supportEmail, "supportEmail"), "help@example.com")

// A missing setting names the field that needs attention.
assert.throws(
  () => NonNullableX.fromNullableOrThrow(null, "supportEmail"),
  /Value is nullable: null \(variable name: supportEmail\)/
)

Added in v0.0.0