Add initial documentation and instances (#1)

Author: thomashoneyman

README.md

@@ -6,7 +6,7 @@
 [![Maintainer: garyb](https://img.shields.io/badge/maintainer-garyb-teal.svg)](https://github.com/garyb)
 [![Maintainer: thomashoneyman](https://img.shields.io/badge/maintainer-thomashoneyman-teal.svg)](https://github.com/thomashoneyman)
 
-The library summary hasn't been written yet (contributions are welcome!). The library summary describes the library's purpose in one to three sentences.
+Utilities for creating and managing push-based subscriptions, inspired by the [event](https://github.com/paf31/purescript-event) library. This library is used to implement subscriptions in [Halogen](https://github.com/purescript-halogen/purescript-halogen), but it can be used independently of Halogen.
 
 ## Installation
 
@@ -18,27 +18,38 @@ spago install halogen-subscriptions
 
 ## Quick start
 
-The quick start hasn't been written yet (contributions are welcome!). The quick start covers a common, minimal use case for the library, whereas longer examples and tutorials are kept in the [docs directory](./docs).
+The `halogen-subscriptions` library helps you create and transform push-based subscriptions. Most subscriptions follow this pattern:
 
-## Documentation
+1. Use the `create` function to produce a paired `Emitter` and `Listener`. An emitter is a possibly-infinite list of values that you can subscribe to, and a listener is a mechanism for pushing values to the emitter.
+2. Use the `subscribe` function to subscribe to outputs from the emitter by providing a callback function to run each time a value is emitted.
+3. Use the `notify` function to push values to the emitter via the listener.
+4. Use the `unsubscribe` function to end a subscription to an emitter.
+
+Here's a simple example that logs "Hello" and then "Goodbye":
 
-`halogen-subscriptions` documentation is stored in a few places:
+```purs
+module Main where
 
-1. Module documentation is [published on Pursuit](https://pursuit.purescript.org/packages/purescript-halogen-subscriptions).
-2. Written documentation is kept in the [docs directory](./docs).
-3. Usage examples can be found in [the test suite](./test).
+import Prelude
 
-If you get stuck, there are several ways to get help:
+import Effect (Effect)
+import Effect.Console as Console
+import Halogen.Subscription as HS
 
-- [Open an issue](https://github.com/purescript-halogen/purescript-halogen-subscriptions/issues) if you have encountered a bug or problem.
-- [Search or start a thread on the PureScript Discourse](https://discourse.purescript.org) if you have general questions. You can also ask questions in the `#purescript` and `#purescript-beginners` channels on the [Functional Programming Slack](https://functionalprogramming.slack.com) ([invite link](https://fpchat-invite.herokuapp.com/)).
+main :: Effect Unit
+main = do
+  { emitter, listener } <- HS.create
 
-## Contributing
+  subscription <- HS.subscribe emitter \str -> Console.log str
 
-You can contribute to `halogen-subscriptions` in several ways:
+  HS.notify listener "Hello"
+  HS.notify listener "Goodbye!"
 
-1. If you encounter a problem or have a question, please [open an issue](https://github.com/purescript-halogen/purescript-halogen-subscriptions/issues). We'll do our best to work with you to resolve or answer it.
+  HS.unsubscribe subscription
+```
 
-2. If you would like to contribute code, tests, or documentation, please [read the contributor guide](./CONTRIBUTING.md). It's a short, helpful introduction to contributing to this library, including development instructions.
+Emitters can be combined and transformed to make more sophisticated subscriptions.
+
+## Documentation
 
-3. If you have written a library, tutorial, guide, or other resource based on this package, please share it on the [PureScript Discourse](https://discourse.purescript.org)! Writing libraries and learning resources are a great way to help this library succeed.
+Module documentation is [published on Pursuit](https://pursuit.purescript.org/packages/purescript-halogen-subscriptions).

docs/README.md

@@ -8,23 +8,49 @@ module Halogen.Subscription
   , Subscription
   , subscribe
   , unsubscribe
+  , fold
+  , filter
+  , fix
   ) where
 
 import Prelude
 
+import Control.Alt (class Alt)
+import Control.Alternative (class Alternative)
+import Control.Apply (lift2)
+import Control.Plus (class Plus)
 import Data.Array (deleteBy)
 import Data.Foldable (traverse_)
 import Data.Functor.Contravariant (class Contravariant)
+import Data.Maybe (Maybe(..))
 import Effect (Effect)
 import Effect.Ref as Ref
+import Effect.Unsafe (unsafePerformEffect)
 import Safe.Coerce (coerce)
 import Unsafe.Reference (unsafeRefEq)
 
+-- | A paired `Listener` and `Emitter` produced with the `create` function.
 type SubscribeIO a =
   { listener :: Listener a
   , emitter :: Emitter a
   }
 
+-- | Create a paired `Listener` and `Emitter`, where you can push values to
+-- | the listener and subscribe to values from the emitter.
+-- |
+-- | ```purs
+-- | { emitter, listener } <- create
+-- |
+-- | -- Push values into the listener:
+-- | notify listener "hello"
+-- |
+-- | -- Subscribe to outputs from the emitter with a callback:
+-- | subscription <- subscribe emitter \value ->
+-- |   Console.log value
+-- |
+-- | -- Unsubscribe at any time:
+-- | unsubscribe subscription
+-- | ```
 create :: forall a. Effect (SubscribeIO a)
 create = do
   subscribers <- Ref.new []
@@ -37,36 +63,130 @@ create = do
         Ref.read subscribers >>= traverse_ \k -> k a
     }
 
-newtype Listener a = Listener (a -> Effect Unit)
-
-instance contravariantListener :: Contravariant Listener where
-  cmap f (Listener g) = Listener (g <<< f)
-
-notify :: forall a. Listener a -> a -> Effect Unit
-notify (Listener f) a = f a
-
+-- | An `Emitter` represents a collection of discrete occurrences of an event;
+-- | conceptually, an emitter is a possibly-infinite list of values.
+-- |
+-- | Emitters are created from real events like timers or mouse clicks and can
+-- | be combined or transformed with the functions and instances in this module.
+-- |
+-- | Emitters are consumed by providing a callback via the `subscribe` function.
 newtype Emitter a = Emitter ((a -> Effect Unit) -> Effect Subscription)
 
 instance functorEmitter :: Functor Emitter where
   map f (Emitter e) = Emitter \k -> e (k <<< f)
 
+instance applyEmitter :: Apply Emitter where
+  apply (Emitter e1) (Emitter e2) = Emitter \k -> do
+    latestA <- Ref.new Nothing
+    latestB <- Ref.new Nothing
+    Subscription c1 <- e1 \a -> do
+      Ref.write (Just a) latestA
+      Ref.read latestB >>= traverse_ (k <<< a)
+    Subscription c2 <- e2 \b -> do
+      Ref.write (Just b) latestB
+      Ref.read latestA >>= traverse_ (k <<< (_ $ b))
+    pure (Subscription (c1 *> c2))
+
+instance applicativeEmitter :: Applicative Emitter where
+  pure a = Emitter \k -> do
+    k a
+    pure (Subscription (pure unit))
+
+instance altEmitter :: Alt Emitter where
+  alt (Emitter f) (Emitter g) = Emitter \k -> do
+    Subscription c1 <- f k
+    Subscription c2 <- g k
+    pure (Subscription (c1 *> c2))
+
+instance plusEmitter :: Plus Emitter where
+  empty = Emitter \_ -> pure (Subscription (pure unit))
+
+instance alternativeEmitter :: Alternative Emitter
+
+instance semigroupEmitter :: Semigroup a => Semigroup (Emitter a) where
+  append = lift2 append
+
+instance monoidEmitter :: Monoid a => Monoid (Emitter a) where
+  mempty = Emitter mempty
+
+-- | Make an `Emitter` from a function which accepts a callback and returns an
+-- | unsubscription function.
+-- |
+-- | Note: You should use `create` unless you need explicit control over
+-- | unsubscription.
 makeEmitter
   :: forall a
    . ((a -> Effect Unit) -> Effect (Effect Unit))
   -> Emitter a
 makeEmitter = coerce
 
+-- | Conceptually, a `Listener` represents an input source to an `Emitter`. You
+-- | can push a value to its paired emitter with the `notify` function.
+newtype Listener a = Listener (a -> Effect Unit)
+
+instance contravariantListener :: Contravariant Listener where
+  cmap f (Listener g) = coerce (g <<< f)
+
+-- | Push a value to the `Emitter` paired with the provided `Listener` argument.
+-- |
+-- | ```purs
+-- | -- Create an emitter and listener with `create`:
+-- | { emitter, listener } <- create
+-- |
+-- | -- Then, push values to the emitter via the listener with `notify`:
+-- | notify listener "hello"
+-- | ```
+notify :: forall a. Listener a -> a -> Effect Unit
+notify (Listener f) a = f a
+
+-- | A `Subscription` results from subscribing to an `Emitter` with `subscribe`;
+-- | the subscription can be ended at any time with `unsubscribe`.
 newtype Subscription = Subscription (Effect Unit)
 
 derive newtype instance semigroupSubscription :: Semigroup Subscription
 derive newtype instance monoidSubscription :: Monoid Subscription
 
+-- | Subscribe to an `Emitter` by providing a callback to run on values produced
+-- | by the emitter:
+-- |
+-- | ```purs
+-- | -- Produce an emitter / listener pair with `create`:
+-- | { emitter, listener } <- create
+-- |
+-- | -- Then, subscribe to the emitter by providing a callback:
+-- | subscription <- subscribe emitter \emitted ->
+-- |   doSomethingWith emitted
+-- |
+-- | -- End the subscription at any time with `unsubscribe`:
+-- | unsubscribe subscription
+-- | ```
 subscribe
   :: forall r a
    . Emitter a
   -> (a -> Effect r)
   -> Effect Subscription
 subscribe (Emitter e) k = e (void <<< k)
 
+-- | End a subscription to an `Emitter`.
 unsubscribe :: Subscription -> Effect Unit
 unsubscribe (Subscription unsub) = unsub
+
+-- | Fold over values received from some `Emitter`, creating a new `Emitter`.
+fold :: forall a b. (a -> b -> b) -> Emitter a -> b -> Emitter b
+fold f (Emitter e) b = Emitter \k -> do
+  result <- Ref.new b
+  e \a -> Ref.modify (f a) result >>= k
+
+-- | Create an `Emitter` which only fires when a predicate holds.
+filter :: forall a. (a -> Boolean) -> Emitter a -> Emitter a
+filter p (Emitter e) = Emitter \k -> e \a -> if p a then k a else pure unit
+
+-- | Compute a fixed point.
+fix :: forall i o. (Emitter i -> { input :: Emitter i, output :: Emitter o }) -> Emitter o
+fix f = Emitter \k -> do
+  Subscription c1 <- subscribe input (notify listener)
+  Subscription c2 <- subscribe output k
+  pure (Subscription (c1 *> c2))
+  where
+  { emitter, listener } = unsafePerformEffect create
+  { input, output } = f emitter

src/Halogen/Subscription.purs

@@ -2,10 +2,26 @@ module Test.Main where
 
 import Prelude
 
+import Data.Array (replicate)
+import Data.Foldable (sequence_)
 import Effect (Effect)
-import Effect.Class.Console (log)
+import Effect.Ref as Ref
+import Halogen.Subscription as HS
+import Test.Assert (assertEqual)
 
 main :: Effect Unit
 main = do
-  log "🍝"
-  log "You should add some tests."
+  emittedCount <- Ref.new 0
+  { emitter, listener } <- HS.create
+
+  -- The count should increment after subscribing to the emitter with a counter.
+  sub <- HS.subscribe emitter \_ -> Ref.modify_ (_ + 1) emittedCount
+  _ <- sequence_ $ replicate 5 (HS.notify listener "hello")
+  count0 <- Ref.read emittedCount
+  assertEqual  { actual: count0, expected: 5 }
+
+  -- The count should not change after unsubscribing from the emitter.
+  HS.unsubscribe sub
+  _ <- sequence_ $ replicate 5 (HS.notify listener "hello")
+  count1 <- Ref.read emittedCount
+  assertEqual { actual: count1, expected: 5 }