Opt-in clojure.spec contracts for the public vaelii.core API.
The engine already validates the content of what it stores — naming invariants,
well-formedness, disjointness (vaelii.impl.naming / vaelii.impl.wff). These
specs guard the other side: the shape of the arguments a caller passes, the
option and budget maps especially, so a typo like {:strength :monotone} or a
string where a millisecond count belongs is rejected at the door with a spec
explanation rather than surfacing as a downstream error.
Nothing here runs unless a caller opts in with
(clojure.spec.test.alpha/instrument public-syms) — instrumentation is a
dev/test tool, so shipping the specs costs a populated registry and no more. They
double as machine-checked documentation and as generators for property tests.
The s/fdefs name their targets by fully-qualified symbol, so loading this
namespace does not load vaelii.core — the specs register against the public var
names, which are the stable contract, independent of how the implementation is
split across vaelii.impl.*.
Coverage is the whole shape-carrying surface: every entry point that takes a
handle, a context, a level, a strength/direction, or one of the option / budget
maps. The pure taxonomy reads (genls, context-up, …) are specced too, since a
wrong-arity call to one of them is exactly the kind of mistake instrumentation
should surface early.
Opt-in `clojure.spec` contracts for the public `vaelii.core` API.
The engine already validates the *content* of what it stores — naming invariants,
well-formedness, disjointness (`vaelii.impl.naming` / `vaelii.impl.wff`). These
specs guard the other side: the *shape* of the arguments a caller passes, the
option and budget maps especially, so a typo like `{:strength :monotone}` or a
string where a millisecond count belongs is rejected at the door with a spec
explanation rather than surfacing as a downstream error.
Nothing here runs unless a caller opts in with
`(clojure.spec.test.alpha/instrument public-syms)` — instrumentation is a
dev/test tool, so shipping the specs costs a populated registry and no more. They
double as machine-checked documentation and as generators for property tests.
The `s/fdef`s name their targets by fully-qualified symbol, so loading this
namespace does not load `vaelii.core` — the specs register against the public var
names, which are the stable contract, independent of how the implementation is
split across `vaelii.impl.*`.
Coverage is the whole shape-carrying surface: every entry point that takes a
handle, a context, a level, a strength/direction, or one of the option / budget
maps. The pure taxonomy reads (`genls`, `context-up`, …) are specced too, since a
wrong-arity call to one of them is exactly the kind of mistake instrumentation
should surface early.The fully-qualified symbols the s/fdefs above cover — pass to
clojure.spec.test.alpha/instrument / unstrument. This is the shape-carrying
public surface: everything that takes a handle, context, level, strength,
direction, or an option / budget map, plus the taxonomy and equality reads.
The fully-qualified symbols the `s/fdef`s above cover — pass to `clojure.spec.test.alpha/instrument` / `unstrument`. This is the shape-carrying public surface: everything that takes a handle, context, level, strength, direction, or an option / budget map, plus the taxonomy and equality reads.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |