coalesce

import { coalesce } from 'cx/util';

coalesce returns the first non-null/non-undefined value from its arguments. Similar to SQL’s COALESCE or JavaScript’s nullish coalescing (??), but works with multiple arguments.

Signature

function coalesce(...args: any[]): any

Parameters

Parameter	Type	Description
`args`	`any[]`	Values to check.

Return Value

Returns the first argument that is not null or undefined. Returns null if all arguments are null/undefined.

Examples

Basic usage

coalesce(null, undefined, "hello");      // "hello"
coalesce(null, "first", "second");       // "first"
coalesce("a", "b", "c");                 // "a"
coalesce(null, null, null);              // null

With falsy values

Unlike ||, coalesce only checks for null/undefined, not all falsy values:

coalesce(0, 10);                         // 0 (not 10)
coalesce("", "default");                 // "" (not "default")
coalesce(false, true);                   // false (not true)

// Compare with ||
0 || 10;                                 // 10
"" || "default";                         // "default"
false || true;                           // true

Default values

const name = coalesce(user.nickname, user.name, "Anonymous");
const port = coalesce(config.port, env.PORT, 3000);
const theme = coalesce(userPrefs.theme, systemTheme, "light");

With function returns

const result = coalesce(
  cache.get(key),
  storage.get(key),
  computeDefault(),
);

coalesce vs ??

JavaScript’s ?? operator only works with two operands:

// With ??
const value = a ?? b ?? c ?? d;

// With coalesce
const value = coalesce(a, b, c, d);

coalesce vs ||

The || operator treats all falsy values as “empty”:

// || treats 0, "", false as falsy
0 || 100;              // 100
"" || "default";       // "default"

// coalesce only treats null/undefined as empty
coalesce(0, 100);      // 0
coalesce("", "default"); // ""