BBizKit

equal.literal

v0.1.0 latest

Equality comparison per ECMA-262 strict equality with string trimming (E-01) and no type coercion.

equalitycomparisontrimmingstricttype-safe

Equality comparison per ECMA-262 strict equality with string trimming (E-01) and no type coercion.

Signature

function literal(a: unknown, b: unknown): boolean

Problem

Comparing values from different sources often requires handling leading/trailing whitespace in strings while maintaining strict type checking. Using === directly fails for ' abc ' vs 'abc'. Using == introduces unwanted type coercion.

How It Works

Trims both arguments if they are strings (E-01 compliance), then compares with ===. No type coercion — 1 and '1' are never equal.

Boundaries

  • String inputs are trimmed before comparison (E-01 compliance).
  • Non-string inputs are compared with === as-is — no normalization.
  • NaN === NaN is false (standard JavaScript semantics).
  • Accepts unknown for both arguments — works with any type.
  • For raw identity comparison without trimming, use the native === operator.

Replaces

Common boilerplate this function replaces:

a?.toString().trim() === b?.toString().trim() // but without type coercion

Examples

equal.literal("abc", "abc");  // true
equal.literal(" abc ", "abc");  // true
equal.literal(1, "1");  // false
equal.literal(NaN, NaN);  // false
equal.literal(null, undefined);  // false

Standards

Caveats

  • NaN is not equal to itself — standard IEEE 754 / JavaScript behavior.
  • String trimming is always applied to string inputs. Use === directly if you need whitespace-sensitive comparison.

FAQ

How to compare strings ignoring whitespace in JavaScript?

equal.literal(' abc ', 'abc') returns true. Trims both string arguments before comparison.

Does equal.literal do type coercion?

No. equal.literal(1, '1') returns false. Only string trimming is applied.

Why does equal.literal(NaN, NaN) return false?

Standard JavaScript semantics: NaN !== NaN per IEEE 754.

When should I use equal.literal vs ===?

Use equal.literal when string inputs may have leading/trailing whitespace. Use === for exact identity.

Can equal.literal compare objects?

It uses === for non-strings, so objects are compared by reference, not by value.

Referenced Standards