clojure.spec, a part of Clojure's core library that is intended to help with specification, testing and error messages. I recommend you to read the linked rationale, you will get the gist even without knowledge of Clojure. In any case here's my best attempt of a summary:
[0, 1]. (In a statically typed language like Java the idiomatic way would be an instance of a
SoccerScore class.) This data is passed around between modules of your code or sent to external systems, yet the knowledge about what this list of integers stands for is not available anywhere. Maybe you described it in the project's documentation, which is likely outdated. Most probably it is implicitly assumed in your code (
var goals_scored = score + score;). If the semantics change (e.g. list contains also teams), your code breaks.
One way to mitigate this is by static analysis tools (Flow) or typed languages (Typescript), but they only get you so far. For instance they don't work at runtime (duh!) and offer limited expressiveness. (They also need more tooling, but that's another story.) So what you're left with is manual parsing and checking, which is repetitive and half-assed at worst (
if (!Array.isArray(score)) ...), and non-standard at best, ie. there is no way for users of your function to know where exactly their provided input failed your specification.
js.spec tries to solve those problems.
For a quick usage example see example.js. Otherwise please refer to the documentation.
npm install js.spec
This will install the current release candidate, as there is no 1.0 yet.
If you want to include it into a web page directly via
script, please use the UMD build like this:
The 0.0.x published versions should be seen as developer previews. Code may or may not work. API may or may not witness breaking changes.
- ✅ Primitives
- ✅ Map
- ✅ Collection
- ✅ And
- ✅ Or
- ✅ Tuple
- ✅ Nilable
- ✅ Enum
✅ Spec RegistryRemoved after discussion in #21
- 🚧 Spec Regexes (
- 😰 Generator Functions
- 😫 Function Specs (Not even sure if it's possible the way it works in
Why not use Clojurescript?
If you already thought about using CLJS, go ahead.
clojure.spec is already available there. However if you meant to pull in CLJS as a dependency:
clojure.spec is macro-heavy. Macros exist only at compile-time, so all the "functions" (they are macros) are gone.
MIT, see LICENSE