feat: assert_not()

[jonthegeek]

Summary

As a package developer, in order to reject values that match a disallowed specification, I would like a function that errors when its input would satisfy a given spec and otherwise returns the input unchanged.

Details

assert_not() is the inverse of a single spec: it errors when x would be accepted by spec, and returns x otherwise. Under Postel's law, "would be accepted" means "would coerce" — so assert_not("1", specify_int()) errors because "1" is int-ish, even though it isn't literally an integer.

Because assert_*() functions return their input unchanged, they compose cleanly with the stabilize_*_of() family (see Coordination below).

JSON Schema connection

This is the analog of JSON Schema not: a subschema the instance must not validate against. The converter maps not: <S> to assert_not(x, <spec for S>).

Proposed signature

assert_not(
  x,
  spec,
  ...,
  x_arg = caller_arg(x),
  call = caller_env(),
  x_class = object_type(x)
)

Arguments

• x — The value to check.
• spec — A single stabilizer function, to_* function, or specify_*() result that x must not match. Same spec form as stabilize_each() in feat: stabilize_each() #287.
• ... — Reserved for now (error if supplied, matching sibling functions).
• x_arg, call, x_class — As in other functions.

Returns x unchanged (invisibly) when x does not match spec; errors when x matches.

Behavior

• Evaluate spec against x by trying to coerce/validate (reuse the same machinery stabilize_*_of() uses to run a spec). If it succeeds, throw; if it fails, return x.
• Use an error subclass consistent with the family.
• No British-spelling synonym is needed (assert has no spelling variant).

Coordination

• If they have already been implemented, update the ... documentation of the stabilize_*_of() composition functions (stabilize_any_of() stabilize_one_of() function #215 / chore: rename stabilize_one_of() / to_one_of() to *_any_of() #285, stabilize_one_of() feat: stabilize_one_of() (exactly one) #286, stabilize_all_of() feat: stabilize_all_of() family #278) to mention assert_not() — and, more generally, any assert_*() function that returns its input unchanged — as a valid value in .... This "advertises" that composition accepts asserts, so a branch can require that a value is not something.

References

• JSON Schema draft 2020-12, not: https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html
• Related: spec argument shape from feat: stabilize_each() #287; composition family (stabilize_any_of() / stabilize_one_of() / stabilize_all_of()).