 
 
 ;; ----- error reporting -----
+
+
+(defn expected
+  "Throw illegal input exception citing `expectation` and what was `found` did not match. Optionally accept a predicate
+  fn to test `found` before throwing the exception."
+  ([expectation found]
+    (throw (IllegalArgumentException.
+             (format "Expected %s, but found (%s) %s" expectation (class found) (pr-str found)))))
+  ([pred expectation found]
+    (when-not (pred found)
+      (expected expectation found))))
 
 
 (defn illegal-arg

  String
  ;;====
  (get-sql    [sql] sql)
  (set-params [sql ^PreparedStatement prepared-statement params] (set-params! prepared-statement params))
  (read-col   [sql ^ResultSet result-set ^long column-index]     (read-column-value result-set column-index))
  (read-row   [sql ^ResultSet result-set ^long column-count]     (read-columns result-set column-count)))


  ;;=========
  (get-sql    [template] (.-sql template))
  (set-params [template ^PreparedStatement prepared-statement params]
    (cond
      (map? params)    (set-params-map! prepared-statement (.-param-keys template) (.-param-types template) params)
      (vector? params) (set-params-vec! prepared-statement (.-param-types template) params)
      (nil? params)    nil
      :otherwise       (expected "map, vector or nil" params)))
  (read-col   [template ^ResultSet result-set ^long column-index]
    (let [^bytes types (.-result-types template)]
      (if (pos? (alength types))
