Add Documentation

Author: mirko-plowtech

README.md

@@ -1,98 +1,103 @@
-# rescript-react-update
+# rescript-react-restate
 
-> useReducer with updates and side effects!
+This library is a fork and re-design of [rescript-react-update](https://github.com/bloodyowl/rescript-react-update).
+
+Essentially what introduce is a fix on the effect cancellation mechanism. A fix in terms of following 
+React's philosophy about how we should ensure effects cancellation before re-render.
+
+As a consequence, of the fix, the library also introduce an elegant approach in the separation between pure state management and side effects. By introducing the concept of `deferred actions` and `schedulers`.
+
+A `deferred action` is an `action` that is not immediately dispatched, but rather scheduled to be dispatched later.
+In contrast with `reducers` (that given an action and the state, provides the new state), a `scheduler` is a function that given the current context and a deferred action, can execute (user defined) side effects, and return (or not) a cleanup/cancellation function associated with.
 
 ## Installation
 
 ```console
-$ yarn add rescript-react-update
+$ yarn add rescript-react-restate
 ```
 
 or
 
 ```console
-$ npm install --save rescript-react-update
+$ npm install --save rescript-react-restate
 ```
 
-Then add `rescript-react-update` to your `bsconfig.json` `bs-dependencies` field.
+Then add `rescript-react-restate` to your `bsconfig.json` `bs-dependencies` field.
 
-## ReactUpdate.useReducer
+## Handling side effects (Asynchronous actions, logging, etc.)
 
-```reason
-type state = int;
-
-type action =
-  | Increment
-  | Decrement;
-
-[@react.component]
-let make = () => {
-  let (state, send) =
-    ReactUpdate.useReducer((state, action) =>
-      switch (action) {
-      | Increment => Update(state + 1)
-      | Decrement => Update(state - 1)
-      },
-      0
-    );
-  <div>
-    {state->React.int}
-    <button onClick={_ => send(Decrement)}> {"-"->React.string} </button>
-    <button onClick={_ => send(Increment)}> {"+"->React.string} </button>
-  </div>;
-};
-```
+`Restate` powers up reducers by allow them not just update state, but also defer an action to be dispatched later if is desired. This is useful when you want to handle side effects (like logging, network requests, etc.) after the state has been updated.
 
-### Lazy initialisation
+```reason
 
-## ReactUpdate.useReducerWithMapState
+// Your state
 
-If you'd rather initialize state lazily (if there's some computation you don't want executed at every render for instance), use `useReducerWithMapState` where the first argument is a function taking `unit` and returning the initial state.
+type state = int
 
-```reason
-type state = int;
+// Your actions (both immediate and deferred ones)
 
 type action =
   | Increment
-  | Decrement;
-
-[@react.component]
+  | Decrement
+
+type deferredAction =
+  | LogIncrement
+  | LogDecrement
+
+// Because of implementation details related on how we clean up the side effects, we need to provide a way to identify each the deferred action. In other words, deferred actions must have a unique identifier.
+module DeferredAction: Restate.HasDeferredAction with type t = deferredAction = {
+  type t = deferredAction
+  let variantId = action =>
+    switch action {
+    | LogIncrement => "LogIncrement"
+    | LogDecrement => "LogDecrement"
+  }
+}
+
+// Instantiate the reducer with your deferred action type
+module RestateReducer = Restate.MakeReducer(DeferredAction)
+
+// A Reducer now can update the state and schedule deferred actions (if they need to)
+let reducer = (state, action) => 
+ switch action {
+   | Increment =>
+     RestateReducer.UpdateWithDeferred(
+       state + 1,
+       LogIncrement,
+     )
+   | Decrement =>
+     RestateReducer.UpdateWithDeferred(
+       state - 1,
+       LogDecrement,
+     )
+   }
+
+// A Scheduler handle deferred actions by triggering side effects and returning a cleanup function (if necessary)
+let scheduler: (RestateReducer.self<state, action>, deferredAction) => option<unit=>unit> = 
+  (self, deferredAction) =>
+    switch deferredAction {
+    | LogIncrement =>
+      Js.log2("increment side effect: ", self.state)
+      // Note: The state on the cleanup will the content of this scope, and
+      //       not the previous one that exist at moment of running the function.
+      Some(() => Js.log2("increment cleanup: ", self.state))
+    | LogDecrement =>
+      Js.log2("decrement side effect: ", self.state)
+      Some(() => Js.log2("decrement cleanup: ", self.state))
+    }
+
+@react.component
 let make = () => {
-  let (state, send) =
-    ReactUpdate.useReducerWithMapState(
-      (state, action) =>
-        switch (action) {
-        | Increment => Update(state + 1)
-        | Decrement => Update(state + 1)
-        },
-        () => 0
-    );
+  let (state, send, _defer) = RestateReducer.useReducer(reducer, scheduler, 0)
   <div>
     {state->React.int}
     <button onClick={_ => send(Decrement)}> {"-"->React.string} </button>
     <button onClick={_ => send(Increment)}> {"+"->React.string} </button>
-  </div>;
-};
+  </div>
+}
 ```
 
-### Cancelling a side effect
-
-The callback you pass to `SideEffects` & `UpdateWithSideEffect` returns an `option(unit => unit)`, which is the cancellation function.
+## Lazy initialisation
 
-```reason
-// doesn't cancel
-SideEffects(({send}) => {
-  Js.log(1);
-  None
-});
-// cancels
-SideEffects(({send}) => {
-  let request = Request.make();
-  request->Future.get(payload => send(Receive(payload)))
-  Some(() => {
-    Request.cancel(request)
-  })
-});
-```
+If you'd rather initialize state lazily (if there's some computation you don't want executed at every render for instance), use `useReducerWithMapState` where the first argument is a function taking `unit` and returning the initial state.
 
-If you want to copy/paste old reducers that don't support cancellation, you can use `ReactUpdateLegacy` instead in place of `ReactUpdate`. Its `SideEffects` and `UpdateWithSideEffects` functions accept functions that return `unit`.

examples/Counter_SideEffects.res

@@ -77,7 +77,7 @@ module ReactRestate = {
         switch deferredAction {
         | LogIncrement =>
           Js.log2("increment side effect: ", self.state)
-          // Note: the state on the cleanup will the content of this scope, and
+          // Note: The state on the cleanup will the content of this scope, and
           //       not the previous one that exist at moment of running the function.
           Some(() => Js.log2("increment cleanup: ", self.state))
         | LogDecrement =>

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "rescript-react-update",
+  "name": "rescript-react-restate",
   "version": "1.0.0",
   "scripts": {
     "dev": "yarn re:build && parcel examples/index.html",