BBizKit

equal.bool

v0.1.0 latest

Boolean equality per ECMA-262 ToBoolean semantics with normalization of diverse boolean representations (true/false, 0/1, strings).

equalitybooleannormalizationtype-coercionapi-response

Boolean equality per ECMA-262 ToBoolean semantics with normalization of diverse boolean representations (true/false, 0/1, strings).

Signature

function bool(a: BoolLike, b: BoolLike): boolean

Type Definitions:

Problem

APIs and databases represent booleans inconsistently: true/false, 0/1, '0'/'1', 'true'/'false'. Comparing values across these representations requires safe normalization that handles all variants.

How It Works

Normalizes diverse boolean representations (true, 1, '1', 'true' → true; false, 0, '0', 'false' → false), then compares. Out-of-set values (e.g. 'yes', 2) → returns false.

Boundaries

  • null or undefined for either argument → TypeError.
  • Values outside the BoolLike set (e.g. 'yes', 2, 'TRUE') → returns false (out-of-set).
  • Comparison is type-aware: 'true' equals true equals 1 equals '1'.
  • String inputs are trimmed before normalization (E-01).

Replaces

Common boilerplate this function replaces:

const toBool = v => v === true || v === 1 || v === '1' || v === 'true'; toBool(a) === toBool(b);

Examples

equal.bool(true, "true");  // true
equal.bool(1, "1");  // true
equal.bool("0", false);  // true
equal.bool(true, false);  // false
equal.bool("yes", "yes");  // false

Standards

Caveats

  • Case-sensitive string matching: 'TRUE' and 'True' are out-of-set (only 'true' and 'false' are recognized).
  • Two out-of-set values always return false, even if they are equal strings.

FAQ

How to compare boolean-like values from different APIs?

equal.bool(1, 'true') returns true. Normalizes true/false, 0/1, '0'/'1', 'true'/'false' before comparison.

Does equal.bool handle 'yes'/'no'?

No. 'yes' and 'no' are out-of-set and always return false, even compared to each other.

Is 'TRUE' (uppercase) recognized?

No. Only lowercase 'true' and 'false' are recognized. 'TRUE' is out-of-set.

What happens with null inputs?

TypeError is thrown. null and undefined are not valid BoolLike values.

Why do two 'yes' values return false?

Both are out-of-set (normalized to null). null !== null in the comparison, so false is returned.

Referenced Standards