some docs, and some top-level Korma tests

README.md

@@ -4,14 +4,40 @@
 
 A library which provides a sequence abstraction for use with Korma and ClojureQL queries
 
+Results are sorted by a key, which may be a compound key. The direction of the sort may be specified
+
+Results are fetched in batches for efficiency. The batch-size may be specified
+
+A transactor function should be supplied, which will be called with a function which executes SQL requests. The
+transactor should set up a transaction and call its parameter function. A function is supplied to construct a
+transactor from a JDBC DataSource, and the `\*default-transactor\*` dynamic variable can be set for some forms for
+the thread using the `with-default-transactor` macro, after which a transactor need not be supplied
+
 ## Usage
 
-  (require '[clojureql.core :as q])
-  (require '[qseq.core :as qs])
+    (require '[clojureql.core :as q])
+    (require '[korma.core :as k])
+    (require '[qseq.core :as qs])
+
+    (qs/with-default-transactor (qs/transactor my-data-source)
+
+      (-> (q/table :users)
+          qs/qseq
+          first)
+
+      (-> (k/select* :users)
+          qs/qseq
+          first)
+
+      (-> (k/select* :users)
+          (qs/qseq :batch-size 100 :key [:name :rank] :dir :desc :transactor my-transactor)
+          first)
+
+      (-> (q/table :users)
+          (q/join (q/table :posts)
+                  (q/where (= :posts.user_id :users.id)))
+          (qs/qseq [:users.id :posts.id] :dir :asc)))
 
-  (-> (q/table :users)
-      qs/q-seq
-      first)
 
 ## License
 

src/qseq/core.clj

@@ -7,14 +7,18 @@
   (:require [clojure.java.jdbc :as jdbc]
             [clojureql.core :as q]))
 
-(def ^:dynamic *default-transactor* nil)
+(def ^:dynamic *default-transactor*
+  "if a *default-transactor* is set it will be used in calls where a transactor is required
+   but not explicitly given"
+  nil)
 
 (defn with-default-transactor-fn
   [transactor fn]
   (binding [*default-transactor* transactor]
     (fn)))
 
 (defmacro with-default-transactor
+  "execute forms with *default-transactor* bound to transactor"
   [transactor & forms]
   `(with-default-transactor-fn ~transactor (fn [] ~@forms)))
 
@@ -24,7 +28,7 @@
   `(~transactor (fn [] ~@forms)))
 
 (defn transactor
-  "construct a simple transactor, which runs a transaction on a connection from db"
+  "construct a transactor, which runs a transaction on a connection from db"
   [db]
   (fn [fn]
     (jdbc/with-connection db

test/qseq/core_test.clj

@@ -55,34 +55,41 @@
   (fact
     (doall (qseq-batches (q/table :foo) :batch-size 2)) => [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] [{:id 5}]]
     (provided
-      (execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] [{:id 5}]] ))
+      (qseq.clojureql/execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] [{:id 5}]] ))
 
   (fact
     (doall (qseq-batches (q/table :foo) :batch-size 2)) => [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] []]
     (provided
-      (execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] []] ))
+      (qseq.clojureql/execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] []] ))
 
   (fact
     (doall (qseq-batches (q/table :foo) :batch-size 2)) => [ [] ]
     (provided
-      (execute anything) =streams=> [ [] ] ))
+      (qseq.clojureql/execute anything) =streams=> [ [] ] ))
 
-  )
+  (fact
+    (doall (qseq-batches (k/select* :foo) :batch-size 2)) => [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] []]
+    (provided
+      (qseq.korma/execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] []] )))
 
 (with-default-transactor (fn [f] (f))
 
   (fact
     (doall (qseq (q/table :foo) :batch-size 2)) => [ {:id 1} {:id 2} {:id 3} {:id 4} {:id 5} ]
     (provided
-      (execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] [{:id 5}]] ))
+      (qseq.clojureql/execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] [{:id 5}]] ))
 
   (fact
     (doall (qseq (q/table :foo) :batch-size 2)) => [ {:id 1} {:id 2} {:id 3} {:id 4} ]
     (provided
-      (execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] []] ))
+      (qseq.clojureql/execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] []] ))
 
   (fact
     (doall (qseq (q/table :foo) :batch-size 2)) => [ ]
     (provided
-      (execute anything) =streams=> [ [] ] ))
-  )
+      (qseq.clojureql/execute anything) =streams=> [ [] ] ))
+
+  (fact
+    (doall (qseq (k/select* :foo) :batch-size 2)) => [ {:id 1} {:id 2} {:id 3} {:id 4} ]
+    (provided
+      (qseq.korma/execute anything) =streams=> [ [{:id 1} {:id 2}] [{:id 3} {:id 4}] []] ))  )