Assertcheck Selector

assertcheck-selector

Full API reference: https://thonymg.github.io/assertcheck/

LAWS

LAW 1 — Always pick the most specific assertion. assert.string beats assert.notNil when a value must be a string. assert.notEmpty beats assert.notNil when a value must be non-empty. The more specific the assertion, the more useful the error at runtime.

LAW 2 — Use check() chains when 3+ assertions target the same value. Never write 3+ assert.* calls on the same variable when a chain is available.

LAW 3 — Every assertion must have msg. Add note when the fix is non-obvious. msg describes the invariant ("orderId must be a non-empty string"). note gives the actionable fix ("check that the caller passes a valid order id"). msg: "value is null" is a violation of this law.

LAW 4 — Return exactly one assertion recommendation per invariant. Do not return a list of options. Pick the most specific. Explain if alternatives exist.

Triggers

• "Which assert function should I use for…"
• "What is the assertcheck equivalent of…"
• Called by assertcheck-spec, assertcheck-feature, assertcheck-audit, assertcheck-refactor

Decision tree

1. Existence

value must not be null/undefined          → assert.notNil(v, opts)
value must not be empty (string or array) → assert.notEmpty(v, opts)   ← covers nil too
value must be null/undefined (rare)       → assert.nil(v, opts)

2. Type

must be a string       → assert.string(v, opts)
must be a number       → assert.number(v, opts)
must be a boolean      → assert.boolean(v, opts)
must be an integer     → assert.integer(v, opts)
must be finite         → assert.finite(v, opts)
must be an array       → assert.array(v, opts)
must be a function     → assert.func(v, opts)
must be instance of T  → assert.instanceOf(v, T, opts)

3. Value / equality

must strictly equal expected   → assert.equal(a, b, opts)
must NOT equal                 → assert.not(assert.equal, a, b)   (not() takes no opts)
must deep equal                → assert.deepEqual(a, b, opts)
must be > b                    → assert.greater(a, b, opts)
must be >= b                   → assert.greaterOrEqual(a, b, opts)
must be < b                    → assert.less(a, b, opts)
must be <= b                   → assert.lessOrEqual(a, b, opts)
must be within ± delta of b    → assert.inDelta(a, b, delta, opts)

4. Object shape

must have key "k"               → assert.hasKey(obj, "k", opts)
must have all of keys           → assert.hasKeys(obj, keys, opts)
must have EXACTLY these keys    → assert.hasExactKeys(obj, keys, opts)
nested path must equal value    → assert.dig(obj, "a.b.c", expected, opts)
must match shape of reference   → assert.homomorphic(obj, ref, opts)

5. Collection

must not be empty               → assert.notEmpty(arr, opts)
must have exactly N elements    → assert.len(arr, n, opts)
must include element            → assert.includes(arr, el, opts)
must contain all of elements    → assert.containsAll(arr, els, opts)
must contain none of elements   → assert.containsNone(arr, els, opts)
every element satisfies P       → assert.all(arr, p, opts)
at least one element satisfies  → assert.any(arr, p, opts)
all elements are instance of T  → assert.allInstanceOf(arr, T, opts)
elements match expected array   → assert.elementsMatch(arr, expected, opts)

6. assert.* vs check() — the rule

2 or fewer assertions on the same value → assert.*  (one per line)
3 or more assertions on the same value  → check()   (chain)

// ❌ 3 assert.* on the same value — use check() instead
assert.array(users)
assert.notEmpty(users)
assert.all(users, u => u.active)

// ✅ chain
check(users)
  .notEmpty("users must not be empty")
  .all(u => u.active, "all users must be active")

7. AssertOptions — exact rules

msg — describes the invariant, not the violation:

note — gives the actionable fix:

Full example:

// ❌ No context
assert.notNil(order)

// ✅ Domain context
assert.notNil(order, {
  msg:    "order must exist before processing payment",
  actual: "orderId",
  note:   "verify the orderId comes from a valid creation flow",
})

Anti-patterns

SELF-CHECK — run before delivering

• Recommendation is a single, most-specific assertion (not a list of options)
• check() used when 3+ assertions on the same value
• msg describes the invariant, not the violation
• note included when the fix is non-obvious
• No assert.notNil where assert.string or assert.notEmpty is more precise

If any item fails → fix before delivering.