Generates an Invariant verifying that there are no cyclic properties within the element currently being verified. This needs two functions:

• edge-fn: takes the state and the current value and produces a map of node IDs to a set of successor nodes,
• describe-fn: takes the state and the current value and produces a function that maps node IDs to a more descriptive representation to be included in errors (defaults to returning the node ID itself).

edge-fn should produce a map like the following, describing the edges of a graph constructed from the value currently being verified:

{:a #{:b :c}
 :c #{:d}
 :d #{:a}}

describe-fn can be given to provide more information to errors (e.g. to retain more of the original input than just the node ID). E.g., if the input is a seq of nodes akin to {:id "A", :children #{...}} one could retain the full values using:

(defn describe-nodes
  [nodes]
  (into {} (map (juxt :id identity) nodes)))

Any error container produced by this invariant will provide the detected cycle, as well as the relevant edges within the :invariant/error key.

Generates an Invariant that will be applied to the seq of all elements currently being verified.

Generate an Invariant combining all of the given ones.

(invariant/and
    (invariant/value :int? (comp integer? :value))
    (-> (invariant/on [:children ALL])
        (invariant/each ...)))

An Invariant that will never produce an error.

Generates an Invariant that uses the given specter path, reduce fn and value to attach a key to the invariant state, based on the current value.

(-> (invariant/as :declared-variables [:declarations ALL :name] conj #{})
    (invariant/on [:usages ALL :name])
    ...)

The resulting invariant state can be used e.g. in bind, property and state and will be shaped similarly to the following:

{:declared-variables {"a", "b", "c"}}

An inner invariant can be supplied, in which case the state will be computed from the selected values.

Generate an Invariant that will use bind-fn, applied to the invariant state and the value currently being verified, to decide on an invariant to use.

(-> (invariant/on [:functions ALL])
    (invariant/each
      (invariant/bind
        (fn [_ {:keys [function-name]}]
          (case function-name
            "F" (invariant/property :f-args-valid? ...)
            "G" (invariant/property :g-args-valid? ...)
            ...)))))

This can be used to do invariant dispatch based on concrete values.

Like run but will return either nil or a seq of errors.

Like as, collecting all elements at the given specter path at the desired key within the invariant state. If :unique? (default: true) is set the result will be a set.

Like as, computing a value by applying f to the current state and all elements matching path and storing it under the given key.

(-> (invariant/as :name->dependencies ...)
    (invariant/on [:elements ALL])
    (invariant/compute-as
      :current-dependencies
      (fn [{:keys [name->dependencies]} [name]]
        (name->dependencies name))
      [:name])
    ...)

The above example will:

• create :name->dependencies in the state by analyzing the top-level value,
• iterate over each value in :elements,
• create current-dependencies in the state by looking it up in the previously created :name->dependencies.

Like as, storing the number of elements at the given specter path at the desired key within the invariant state.

Generates an Invariant that will be individually applied to all elements currently being verified.

Generate an Invariant that will always produce an error.

Like as, storing the first element currently being verified under the given key.

Transform each element currently being verified.

(-> (invariant/on [:declarations ALL :name]
    (invariant/fmap
      #(assoc % :name-count (count (:name %))))))

Returns true if running the invariant against the given data does not produce any errors.

Generates an Invariant that will be applied to the single element currently being verified. Will throw an exception if a selector like on matched multiple elements.

(-> (invariant/on [(must :right)])
    (invariant/is? tree-balanced-invariant))

This behaves like each but will not pollute the invariant error path with a zero index.

Generates an Invariant that uses the given specter path to collect all pieces of data the invariant should apply to. This is basically a selector, producing elements subsequent invariants will be applied to.

(-> (invariant/on [:declarations ALL])
    (invariant/each ...))

Optionally, an inner invariant can be supplied in which case the selector is run on its result. This lets you, e.g., collect state while stepping through your data:

(-> (invariant/on [:body])
    (invariant/collect-as :variables [:declarations ALL])
    (invariant/on [:usages ALL])
    ...)

Here, you’ll collect all declarations at [:body :declarations ALL] before continueing with [:body :usages ALL].

If you need to generate a selector dynamically or from a path stored within a var/binding, use on*.

Generates an Invariant that uses the given specter path to collect all pieces of data the invariant should apply to. This is basically a selector, producing elements subsequent invariants will be applied to.

(-> (invariant/on* [:declarations ALL] '[:declarations ALL])
    (invariant/each ...))

on should be preferred since it will automatically generate path-form for you.

An Invariant selector pointing at the current (i.e. top-level) value. Equivalent to (on [STAY]) without polluting the path with STAY elements.

Generates an Invariant that will run selector-fn on the invariant state and the seq of elements currently being verified, replacing the latter with the produced result.

This behaves like on but uses a function to directly generate the values to verify.

Generates an Invariant that will run selector-fn on the invariant state and the seq of elements currently being verified, replacing the latter with the produced result.

Generates a predicate whose pred-fn will be called with the invariant state and the value currently being verified.

(-> (invariant/on [:usages ALL :name])
    (invariant/collect-as :declared-variables [:declarations ALL :name])
    (invariant/each
      (invariant/property
        :declared?
        (fn [{:keys [declared-variables]} n]
          (contains? declared-variables n)))))

Generate a recursive invariant bound to self-sym within the body.

(invariant/recursive
  [self]
  (invariant/and
    (invariant/value :int? (comp integer? :value))
    (-> (invariant/on [:children ALL])
        (invariant/each self))))

The above could be used to verify e.g. the following nested map:

{:value 1
 :children [{:value :x
             :children [{:value 4}]}]}

Verify that the given invariant holds for the given piece of data.

Behaves like property but expects each element currently being verified to be a seq.

Invariant errors will contain the input seq as their :invariant/values.

Generates a predicate whose pred-fn will be called with the current state, ignoring any values currently being verified.

(-> (invariant/on-current-value)
    (invariant/as :count count)
    (invariant/is?
      (invariant/state :at-least-one? #(pos? (:count %)))))

If you need the values being verified to decide on whether the invariant holds, use property.

Generates an Invariant verifying that all current elements are unique.

(-> (invariant/on [:declarations ALL :name])
    (invariant/unique :declarations-unique?))

Errors will be reported per-element.

Generates a stateless predicate whose pred-fn will be called with the value currently being verified.

(-> (invariant/on [:declarations ALL :name])
    (invariant/each
      (invariant/value :prefix-valid? #(string/starts-with? % "var_"))))

If you need the invariant state to decide on whether the invariant holds, use property.

Behaves like value but expectes each element currently being verified to be a seq.

Invariant errors will contain the input seq as their :invariant/values.

Generates an Invariant that attaches an error context to each invariant error produced by invariant.

(-> (invariant/on [:fields ALL])
    (invariant/each ...)
    (invariant/with-error-context
      (fn [_ {:keys [record-name]}]
        {:record-name record-name})))

The result of error-context-fn will be merged into each invariant error’s :invariant/error-context entry.

Like with-error-context but merging a static map into any invariant error’s :invariant/error-context entry.