add Capability Pattern recipe (#257)

* add Capability Pattern recipe

* import README from source repo

* comment out failing test, update README

Author: afcondon

README.md

@@ -95,6 +95,7 @@ Running a web-compatible recipe:
 |   | :heavy_check_mark: ([try](https://try.ps.ai/?github=JordanMartinez/purescript-cookbook/master/recipes/BookReactHooks/src/Main.purs)) | [BookReactHooks](recipes/BookReactHooks) | A React port of the ["HTTP - Book" Elm Example](https://elm-lang.org/examples/book). |
 |   | :heavy_check_mark: ([try](https://try.ps.ai/?github=JordanMartinez/purescript-cookbook/master/recipes/ButtonsHalogenHooks/src/Main.purs)) | [ButtonsHalogenHooks](recipes/ButtonsHalogenHooks) | A Halogen port of the ["User Input - Buttons" Elm Example](https://elm-lang.org/examples/buttons). |
 |   | :heavy_check_mark: ([try](https://try.ps.ai/?github=JordanMartinez/purescript-cookbook/master/recipes/ButtonsReactHooks/src/Main.purs)) | [ButtonsReactHooks](recipes/ButtonsReactHooks) | A React port of the ["User Input - Buttons" Elm Example](https://elm-lang.org/examples/buttons). |
+| :heavy_check_mark: |   | [CapabilityPatternNode](recipes/CapabilityPatternNode) | A skeletal version of an application structuring pattern |
 |   | :heavy_check_mark: ([try](https://try.ps.ai/?github=JordanMartinez/purescript-cookbook/master/recipes/CardsHalogenHooks/src/Main.purs)) | [CardsHalogenHooks](recipes/CardsHalogenHooks) | A Halogen port of the ["Random - Cards" Elm Example](https://elm-lang.org/examples/cards). |
 |   | :heavy_check_mark: ([try](https://try.ps.ai/?github=JordanMartinez/purescript-cookbook/master/recipes/CardsReactHooks/src/Main.purs)) | [CardsReactHooks](recipes/CardsReactHooks) | A React port of the ["Random - Cards" Elm Example](https://elm-lang.org/examples/cards). |
 |   | :heavy_check_mark: ([try](https://try.ps.ai/?github=JordanMartinez/purescript-cookbook/master/recipes/CatGifsHalogenHooks/src/Main.purs)) | [CatGifsHalogenHooks](recipes/CatGifsHalogenHooks) | A Halogen port of the ["HTTP - Cat GIFs" Elm Example](https://elm-lang.org/examples/cat-gifs). |

recipes/CapabilityPatternNode/.DS_Store

@@ -0,0 +1,13 @@
+/bower_components/
+/node_modules/
+/.pulp-cache/
+/output/
+/generated-docs/
+/.psc-package/
+/.psc*
+/.purs*
+/.psa*
+/.spago
+/web-dist/
+/prod-dist/
+/prod/

recipes/CapabilityPatternNode/.gitignore

@@ -0,0 +1,68 @@
+# CapabilityPatternNode
+
+A skeletal version of an application structuring pattern
+
+Expanded example of the design pattern illustrated in Jordan Martinez'
+[reference](https://jordanmartinez.github.io/purescript-jordans-reference-site/content/21-Hello-World/05-Application-Structure/src/02-MTL/32-The-ReaderT-Capability-Design-Pattern.html).
+
+## What's in each "Layer"?
+
+### Layer 4 - Types 
+
+Strong types & pure, total functions on those types
+
+You'd hope to write as much of your code in this layer as possible but in this
+skeleton it's intentionally almost empty because we're concerned with the less
+obvious business of adapting this bit to your application, infrastructure and
+runtime.
+
+### Layer 3 - Application
+
+Effectful functions - `program` and `capabilities`
+
+Called "business logic" in some descriptions of this pattern this layer
+contains code that essentially weaves together the concrete code from Layer 4
+with the abstract capabilities that can be provided _differently_ in different
+scenarios, such as a logging capability that maybe goes to the console in Test
+but goes to a Database or a socket or systemd or a logfile in development and
+production.
+
+This layer defines:
+ * a *program* that will run in some Monad (thus giving you freedom to run it in different Monads, see above)
+ * all the *capabilities* that it will require of the Monad in which it runs
+ 
+The capabilities are like "container requirements", an API to a structure in which this program is embedded
+
+### Layer 2 (API) & Layer 1 (Infrastructure) 
+
+Together these two layers define a complete instance of one monadic container for a program
+These two layers need to be co-located in one file in PureScript to avoid orphan instances.
+
+Together they define:
+ * a particular Monad in which our `program` from Layer 3 can be run
+ * a `run` function that runs the `program` in _this_ Monad
+ * the instances for the Monad
+     * Functor, Apply, Applicative, Bind & Monad can all be derived trivially
+     * others that a particular Monad might need can be written explicitly
+     * the instances that are required by the `program` in Layer 3, also will have to be written explicitly
+ 
+There are three versions of this monadic container shown here:
+ * *ProductionSync* - which runs in Reader & Effect
+ * *ProductionAsync* - which runs in Reader & Aff
+ * *Test* - which runs in only Reader
+
+ ### Layer 0 - Main
+ This layer is where it all comes together. A `main` is called by the underlying runtime and runs the `program` in one or another Monad.
+
+## Expected Behavior:
+
+The `main` runs the `program` (see linked readme) in three successive, different monad contexts: `Aff`, `Effect` and `Test`. 
+
+If you want to verify that a failing test would still terminate the process with an error, you can simply uncomment the second call to `Test.runApp`
+
+### Node.js
+
+Prints the contents of this repo's LICENSE file. Note that this recipe is run from the repo's root directory.
+
+
+

recipes/CapabilityPatternNode/README.md

@@ -0,0 +1 @@
+Ahab

recipes/CapabilityPatternNode/async.txt

@@ -0,0 +1,2 @@
+This file just indicates that the node backend is supported.
+It is used for CI and autogeneration purposes.

recipes/CapabilityPatternNode/nodeSupported.md

@@ -0,0 +1,14 @@
+{ name = "CapabilityPatternNode"
+, dependencies =
+  [ "aff"
+  , "assert"
+  , "console"
+  , "effect"
+  , "node-fs"
+  , "node-fs-aff"
+  , "node-readline"
+  , "transformers"
+  ]
+, packages = ../../packages.dhall
+, sources = [ "recipes/CapabilityPatternNode/src/**/*.purs" ]
+}

recipes/CapabilityPatternNode/spago.dhall

@@ -0,0 +1,26 @@
+module App.Application where -- Layers 4 & 3 common to Production and Test
+
+import App.Types (Name, getName)
+import Prelude (class Monad, Unit, bind, discard, pure, ($), (<>))
+
+-- | Layer 3
+-- | "business" logic: effectful functions
+
+-- | Monads to define each capability required by the program
+class (Monad m) <= Logger m where
+    log :: String -> m Unit
+
+class (Monad m) <= GetUserName m where
+    getUserName :: m Name
+
+-- | a program that will run in _any_ monad that can fulfill the
+-- | requirements (Logger and GetUserName)
+program :: forall m.
+    Logger m =>
+    GetUserName m =>
+    m String
+program = do
+    log "what is your name?"
+    name <- getUserName
+    log $ "Your name is " <> getName name
+    pure $ getName name

recipes/CapabilityPatternNode/src/Application.purs

@@ -0,0 +1,43 @@
+module CapabilityPatternNode.Main where
+
+import Prelude
+
+import App.Production.Sync (runApp, Environment) as Sync
+import App.Production.Async (runApp, Environment) as Async
+import App.Test (runApp, Environment) as Test
+import App.Application (program)
+import Effect (Effect)
+import Effect.Aff (launchAff_)
+import Effect.Class (liftEffect)
+import Effect.Class.Console (log)
+import Test.Assert (assert)
+
+
+-- | Layer 0 - Running the `program` in three different contexts
+main :: Effect Unit
+main = launchAff_ do
+  -- we can do aff-ish things here with Async/ProductionA version
+  result <- Async.runApp program { asyncEnv: "recipes/CapabilityPatternNode/async.txt" }
+  -- ...also able to do synchronous things (within Aff) using liftEffect
+  liftEffect $ mainSync { productionEnv: "recipes/CapabilityPatternNode/sync.txt" }
+  liftEffect $ mainTest { testEnv: "Test" }
+  pure unit
+
+
+
+-- Three different "main" functions for three different scenarios
+mainSync :: Sync.Environment -> Effect Unit
+mainSync env = do
+  result <- Sync.runApp program env
+  pure unit
+
+mainTest :: Test.Environment -> Effect Unit
+mainTest env = do
+  assert $ (Test.runApp program env) == "succeeds"
+  log "first test succeeded, now a failing test which will crash"
+  -- assert $ (Test.runApp program env) == "failing test"
+
+mainAff1 :: Async.Environment -> Effect Unit
+mainAff1 env = launchAff_ do
+  result <- Async.runApp program env
+  pure unit

recipes/CapabilityPatternNode/src/Main.purs

@@ -0,0 +1,53 @@
+module App.Production.Async where
+-- Layers One and Two have to be in same file due to orphan instance restriction
+
+import Prelude
+
+import App.Types (Name(..))
+import App.Application (class Logger, class GetUserName)
+import Control.Monad.Reader (class MonadAsk, ReaderT, ask, asks, runReaderT)
+import Effect.Aff (Aff, Milliseconds(..), delay)
+import Effect.Aff.Class (class MonadAff, liftAff)
+import Effect.Class (class MonadEffect, liftEffect)
+import Effect.Class.Console (log) as Console
+import Node.Encoding (Encoding(..))
+import Node.FS.Aff (readTextFile) as Async
+import Type.Equality (class TypeEquals, from)
+
+-- | Layer 2 Define our "Production" Monad but using Aff...
+type Environment = { asyncEnv :: String }
+newtype AppMA a = AppMA (ReaderT Environment Aff a)
+
+-- | ...and the means to run computations in it
+runApp :: forall a. AppMA a -> Environment -> Aff a
+runApp (AppMA reader_T) env = runReaderT reader_T env
+
+-- | Layer 1 Production in Aff
+derive newtype instance functorAppMA     :: Functor AppMA
+derive newtype instance applyAppMA       :: Apply AppMA
+derive newtype instance applicativeAppMA :: Applicative AppMA
+derive newtype instance bindAppMA        :: Bind AppMA
+derive newtype instance monadAppMA       :: Monad AppMA
+derive newtype instance monadEffectAppMA :: MonadEffect AppMA
+derive newtype instance monadAffAppMA    :: MonadAff AppMA
+
+-- | Reader instance not quite as simple a derivation as "derive newtype",
+-- | as it needs TypeEquals for the env
+instance monadAskAppMA :: TypeEquals e Environment => MonadAsk e AppMA where
+  ask = AppMA $ asks from
+
+-- | implementing Logger here just to the console, but in real world you'd use
+-- | the available Env to determine log levels, output destination, DB handles etc
+-- | because this version runs in Aff you can do Aff-ish things here (not shown)
+instance loggerAppMA :: Logger AppMA where
+  log = liftEffect <<< Console.log
+
+-- | a version of getUserName that reads the name from a file 
+-- | given in the Environment
+instance getUserNameAppMA :: GetUserName AppMA where
+  getUserName = do
+    env <- ask -- we still have access to underlying ReaderT
+    liftAff do -- but we can also run computations in Aff
+      delay $ Milliseconds 1000.0 -- 1 second
+      contents <- Async.readTextFile UTF8 env.asyncEnv
+      pure $ Name $ contents