Coercion Utilities

The Coercion utilities turn loose input — attribute strings, query params, form values, JSON — into the type you actually want. Each returns the target type or null when the input has no clean representation, so a failed coercion is a value you can guard with ??, never an Invalid Date, NaN, or "[object Object]" that poisons code downstream.

const page = toNumber(params.get('page')) ?? 1;
const when = toDate(input.value) ?? new Date();

Each helper is also exported as coerceBoolean, coerceNumber, coerceInteger, coerceDate, and coerceString for callers who think in coercion terms.

Every helper accepts an onInvalid setting. It defaults to 'null' (the failed coercion returns null, composing with ??). Pass { onInvalid: 'passthrough' } to return the original value instead, so a schema or validator can flag the bad input rather than see an erasing null — and the TypeScript return widens to include the input type (number | string for toNumber(str, { onInvalid: 'passthrough' })).

Functions

toBoolean

function toBoolean(value, { truthy, falsy, loose = false, onInvalid = 'null' } = {})

Coerces a value to a boolean, or null when it recognizes no boolean reading. Booleans pass through, numbers read by zero-ness, and strings match a generous set case-insensitively: true, t, yes, y, on, enabled read as true, and false, f, no, n, off, disabled, null, undefined, nan read as false, alongside numeric strings by their value. Anything else returns null.

Parameters

Options

Returns

true, false, or null if unrecognized. Never null under loose.

Example

import { toBoolean } from '@semantic-ui/utils';

console.log(toBoolean('yes')); // true
console.log(toBoolean('off')); // false
console.log(toBoolean('false')); // false (not the native Boolean('false') === true)
console.log(toBoolean('1')); // true

// unrecognized input is null, so it composes with ??
console.log(toBoolean('banana')); // null
console.log(toBoolean('banana') ?? false); // false

// loose falls back to native truthiness, never null
console.log(toBoolean('banana', { loose: true })); // true

// extend the falsy set without losing the defaults
console.log(toBoolean('nope', { falsy: ['nope'] })); // false

toBoolean.config

toBoolean.config holds the recognized vocabulary (truthy, falsy) and the defaults for loose and onInvalid. Edit it once at app boot and every call inherits it, so a locale or domain adds its own spellings in one place instead of passing truthy/falsy on every call. Per-call settings still win over it.

import { toBoolean } from '@semantic-ui/utils';

// teach it another language, once
toBoolean.config.truthy.push('oui', 'sí');
toBoolean.config.falsy.push('non', 'nein');

console.log(toBoolean('oui')); // true
console.log(toBoolean('non')); // false

// flip a default for every call
toBoolean.config.onInvalid = 'passthrough';
console.log(toBoolean('banana')); // 'banana'

toNumber

function toNumber(value, { onInvalid = 'null' } = {})

Coerces a value to a finite number, or null when it can’t be converted. Numeric strings parse via Number (so hex, scientific, and surrounding whitespace are fine), booleans read as 1 and 0, and NaN, Infinity, blanks, unit-tagged strings, arrays, and objects return null. It never hands back NaN or Infinity.

Parameters

Returns

The finite number, or null if unconvertible.

Example

import { toNumber } from '@semantic-ui/utils';

console.log(toNumber('3.14')); // 3.14
console.log(toNumber('  42 ')); // 42
console.log(toNumber('5px')); // null
console.log(toNumber('1e999')); // null (overflow to Infinity)
console.log(toNumber(true)); // 1

console.log(toNumber('abc') ?? 0); // 0

toInteger

function toInteger(value, { onInvalid = 'null' } = {})

Coerces a value to an integer by truncating toward zero, or null when it’s unconvertible or non-finite. Equivalent to toNumber followed by a truncation, so Infinity joins the null bucket. Under { onInvalid: 'passthrough' } it returns the original value, never a truncated NaN.

Parameters

Returns

The truncated integer, or null if unconvertible.

Example

import { toInteger } from '@semantic-ui/utils';

console.log(toInteger('3.9')); // 3
console.log(toInteger('-3.9')); // -3
console.log(toInteger(42.7)); // 42
console.log(toInteger(Infinity)); // null

toDate

function toDate(value, { onInvalid = 'null', epoch = 'milliseconds' } = {})

Coerces a value to a Date, or null when it can’t be parsed — never an Invalid Date. Accepts a Date, a number read as epoch milliseconds, or an ISO-8601 string. Ambiguous or locale-dependent spellings return null rather than a guessed date: bare years, slash and text dates, and day overflow all reject, so '01/15/2024' and '2024-02-30' never become a wrong Date. A zoneless datetime resolves in the ambient timezone (the user’s zone on the client) and is returned as a UTC instant, the same as native new Date on an <input type="datetime-local"> value. A date-only string is read as UTC, and a timestamp passed as a string is rejected, so pass a number for epoch ms.

Parameters

Options

Returns

The Date, or null if unparseable.

Example

import { toDate } from '@semantic-ui/utils';

console.log(toDate('2024-01-01')); // Date for 2024-01-01
console.log(toDate(1700000000000)); // Date from epoch ms
console.log(toDate(payload.exp, { epoch: 'seconds' })); // Date from a unix-second JWT exp
console.log(toDate('01/15/2024')); // null (ambiguous format)
console.log(toDate('banana')); // null (never an Invalid Date)

const when = toDate(userInput) ?? new Date();

toString

function toString(value, { loose = false, onInvalid = 'null' } = {})

Coerces a value to a string, or null when there is no faithful string form. Strings pass through and a finite number, a boolean, or a bigint goes through String(). Objects, arrays, functions, symbols, non-finite numbers, and nullish return null, so a String field never silently stores "[object Object]" or "NaN". Under loose, objects and arrays render with JSON for display output, still returning null on unserializable input rather than throwing.

Parameters

Options

Returns

The string, or null if there is no faithful string form.

The loose output is a display string, not a round-trippable serialization — JSON drops undefined and functions and rewrites Date and NaN, so it should not be fed back through toDate or toNumber.

Example

import { toString } from '@semantic-ui/utils';

console.log(toString(42)); // '42'
console.log(toString(true)); // 'true'
console.log(toString({ a: 1 })); // null
console.log(toString({ a: 1 }, { loose: true })); // '{"a":1}'
console.log(toString([1, 2], { loose: true })); // '[1,2]'