From 28afb937fe9836cbd9055f420e4f4860d80cfebb Mon Sep 17 00:00:00 2001
From: Wilker Lucio <wilkerlucio@gmail.com>
Date: Thu, 19 Sep 2019 10:54:14 -0300
Subject: [PATCH] Add docs for sugar namespace

---
 docs-src/modules/ROOT/nav.adoc                |  1 +
 docs-src/modules/ROOT/pages/introduction.adoc |  1 +
 docs-src/modules/ROOT/pages/sugar.adoc        | 45 +++++++++++++++++++
 .../wsscode/pathom/{sugar.clj => sugar.cljc}  |  0
 4 files changed, 47 insertions(+)
 create mode 100644 docs-src/modules/ROOT/pages/sugar.adoc
 rename src/com/wsscode/pathom/{sugar.clj => sugar.cljc} (100%)

diff --git a/docs-src/modules/ROOT/nav.adoc b/docs-src/modules/ROOT/nav.adoc
index 6e7fce16..d7a95a6f 100644
--- 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
index d16210aa..93f02b05 100644
--- 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
new file mode 100644
index 00000000..fe0b88d6
--- /dev/null
+++ 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 b/src/com/wsscode/pathom/sugar.cljc
similarity index 100%
rename from src/com/wsscode/pathom/sugar.clj
rename to src/com/wsscode/pathom/sugar.cljc