        :else
        (parser env' query)))))
 
-(defn join-seq [{::keys [entity-key] :as env} coll]
+(defn join-seq
+  "Runs the current subquery against the items of the given collection."
+  [{::keys [entity-key] :as env} coll]
   (mapv #(join (-> env
                    (assoc entity-key %)
                    (update ::path conj %2))) coll (range)))

(defn key-dispatch [{:keys [ast]}]
  (:key ast))

(defn entity-dispatch [{:keys [ast]}]
  (if (vector? (:key ast))
    (first (:key ast))))


(defn entity
  "Fetch the entity according to the ::entity-key. If the entity is an IAtom, it will be derefed.

  If a second argument is sent, calls the parser against current element to guarantee that some fields are loaded. This
  is useful when you need to ensure some values are loaded in order to fetch some more complex data. NOTE: When using
  this call with an explicit vector of attributes the parser will not be invoked for attributes that already exist in
  the current value of the current entity."
  ([env]
   (let [e (raw-entity env)]
     (if (atom? e) (deref e) e)))
