purescript-halogen / purescript-halogen-subscriptions

Utilities for creating and transforming push-based subscriptions.

Halogen Subscriptions

Utilities for creating and managing push-based subscriptions, inspired by the event library. This library is used to implement subscriptions in Halogen, but it can be used independently of Halogen.

Installation

Install halogen-subscriptions with Spago:

spago install halogen-subscriptions

Quick start

The halogen-subscriptions library helps you create and transform push-based subscriptions. Most subscriptions follow this pattern:

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":

module Main where

import Prelude

import Effect (Effect)
import Effect.Console as Console
import Halogen.Subscription as HS

main :: Effect Unit
main = do
  { emitter, listener } <- HS.create

  subscription <- HS.subscribe emitter \str -> Console.log str

  HS.notify listener "Hello"
  HS.notify listener "Goodbye!"

  HS.unsubscribe subscription

Emitters can be combined and transformed to make more sophisticated subscriptions.

Documentation

Module documentation is published on Pursuit.

purescript-halogen-subscriptions's Issues

Add at least some documentation to makeEmitter

Is your change request related to a problem? Please describe.

makeEmitter
  :: forall a
   . ((a -> Effect Unit) -> Effect (Effect Unit))
  -> Emitter a
makeEmitter = coerce

This is a very confusing signature and definition for someone of novice-intermediate language experience. There's no examples, no test case, and what even is ((a -> Effect Unit) -> Effect (Effect Unit))? I think even adding a type alias like the type Canceler = Effect (Effect Unit) could help clarify what's going on. Not sure on the best solution, but currently I find it hard to understand.

Describe the solution you'd like
I started a thread on Discourse about requestAnimationFrame that has a useful, and probably popular use-case for makeEmitter in getting ticks for each frame. It could perhaps be common enough to have an Halogen.Subscriptions.{Common,Extra,Solutions,HTML,DOM,etc.} so the community can have a standardized solution for common problems -- especially for people looking for batteries-included, zephyr-will-clean-up-the-excess fix to "get sh*t done". Obviously you don't want to add DOM/HTML dependencies here, but it'd be a common dep in an application setting.

Additional context
Control.Plus.empty