   (into [] (remove #{'*}) query))
 
 (defn join
-  "Runs a parser with current sub-query."
+  "Runs a parser with current sub-query. When run with an `entity` argument, that entity is set as the new environment
+   value of `::entity`, and the subquery is parsered with that new environment. When run without an `entity` it
+   parses the current subquery in the context of whatever entity was already in `::entity` of the env."
   ([entity {::keys [entity-key] :as env}] (join (assoc env entity-key entity)))
   ([{:keys  [parser ast query]
      ::keys [union-path parent-query]

(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 garantee 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."
  ([env]
   (let [e (raw-entity env)]
     (if (atom? e) (deref e) e)))

       :else
       (parser env' query)))))

(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)))
