Add docs for sugar namespace

wilkerlucio · Sep 19, 2019 · 28afb93 · 28afb93
1 parent 0f72a36
commit 28afb93
Show file tree

Hide file tree

Showing 4 changed files with 47 additions and 0 deletions.
diff --git a/docs-src/modules/ROOT/nav.adoc b/docs-src/modules/ROOT/nav.adoc
@@ -8,6 +8,7 @@
 ** xref:connect/indexes.adoc[Understanding the Indexes]
 ** xref:connect/exploration.adoc[Exploration with Pathom Viz]
 ** xref:connect/thread-pool.adoc[Using a Thread Pool]
+* xref:sugar.adoc[Sugar Helpers]
 * xref:plugins.adoc[Plugins]
 * xref:core.adoc[Core Engine]
 ** xref:core/getting-started.adoc[Getting Started]

diff --git a/docs-src/modules/ROOT/pages/introduction.adoc b/docs-src/modules/ROOT/pages/introduction.adoc
@@ -107,6 +107,7 @@ aliases used, assume that you have the following namespace requires in your envi
     [com.wsscode.pathom.connect :as pc]
     [com.wsscode.pathom.connect.graphql2 :as pcg]
     [com.wsscode.pathom.graphql :as pg]
+    [com.wsscode.pathom.sugar :as ps]
     [com.wsscode.pathom.trace :as pt]
     ; clj only
     [com.wsscode.common.async-clj :refer [let-chan go-catch <? <?maybe]

diff --git a/docs-src/modules/ROOT/pages/sugar.adoc b/docs-src/modules/ROOT/pages/sugar.adoc
@@ -0,0 +1,45 @@
+= Sugar Helpers
+
+Since version `2.2.15` Pathom provides helpers to start parsers with very little code.
+
+These helpers are available at the namespace `com.wsscode.pathom.sugar`.
+
+== Connect parser helpers
+
+First we have helpers to create parser with connect setup. There are three, one for
+the `serial parser`, one for `async parser` and one for the `parallel parser`.
+
+Usage example:
+
+[source,clojure]
+----
+(ns my-app.ns
+  (:require [com.wsscode.pathom.connect :as pc]
+            [com.wsscode.pathom.sugar :as ps]))
+
+(def name-alias-parser
+  (ps/connect-serial-parser
+    [(pc/alias-resolver :system-a/name :system-b/name)]))
+
+(name-alias-parser {::p/entity {:system-a/name "Jane"}} [:system-b/name])
+; => #:system-b{:name "Jane"}
+----
+
+The argument for all the sugar parsers is the Connect registry.
+
+== Parser context interface
+
+Continuing the previous example, the sugar namespace provides a parser interface wrapper
+to facilitate calling the parser sending an entity (as we did in the last example) with
+a simpler interface:
+
+[source,clojure]
+----
+(def context-name-parser (ps/context-parser name-alias-parser))
+
+(context-name-parser {:system-a/name "Jane"} [:system-b/name])
+; => #:system-b{:name "Jane"}
+----
+
+You can also use a custom `env` with the context parser, to do so add the env as the
+first argument (on arity 3).
diff --git a/src/com/wsscode/pathom/sugar.clj → src/com/wsscode/pathom/sugar.cljc b/src/com/wsscode/pathom/sugar.clj → src/com/wsscode/pathom/sugar.cljc