react-elmish 3.0.0 → 3.3.0

package/README.md

@@ -25,7 +25,7 @@ An elmish component basically consists of the following parts:
 First import everything from `react-elmish` and declare the **Message** discriminated union type:
 
 ```ts
-import { Cmd, createCmd, UpdateReturnType, UpdateMap } from "react-elmish";
+import { Cmd, createCmd, InitResult, UpdateReturnType, UpdateMap } from "react-elmish";
 
 export type Message =
     | { name: "increment" }
@@ -57,21 +57,14 @@ export interface Props {
 }
 ```
 
-Now we create a `cmd` object for our messages type:
-
-```ts
-const cmd = createCmd<Message>();
-```
-
 To create the initial model we need an **init** function:
 
 ```ts
-export function init (props: Props): [Model, Cmd<Message>] {
+export function init (props: Props): InitResult {
     return [
         {
             value: props.initialValue,
-        },
-        cmd.none
+        }
     ];
 };
 ```
@@ -251,75 +244,19 @@ You can also use **Symbols** for the message type instead of strings:
     ...
     ```
 
-## Setup
+## Dispatch commands in the update map or update function
 
-**react-elmish** works without a setup. But if you want to use logging or some middleware, you can setup **react-elmish** at the start of your program.
+In addition to modifying the model, you can dispatch new commands here.
 
-```ts
-import * as Elm from "react-elmish";
+To do so, you have to create a `cmd` object:
 
-const myLogger = {
-    debug(...args: unknown []) {
-        console.debug(...args);
-    },
-    info(...args: unknown []) {
-        console.info(...args);
-    },
-    error(...args: unknown []) {
-        console.error(...args);
-    },
-}
+```ts
+import { createCmd } from "react-elmish";
 
-Elm.init({
-    logger: myLogger,
-    errorMiddleware: error => Toast.error(error.message),
-    dispatchMiddleware: msg => console.log(msg),
-});
+const cmd = createCmd<Message>();
 ```
 
-The error middleware function is called by the `handleError` function (see [Error handling](#error-handling)).
-
-The dispatch middleware function is called whenever a Message is dispatched.
-
-## Error handling
-
-You can handle errors easily with the following pattern.
-
-1. Add an error message:
-
-    ```ts
-    import { ErrorMessage, errorMsg, handleError } from "react-elmish";
-
-    export type Message =
-        | ...
-        | ErrorMessage;
-    ```
-
-1. Optionally add the convenient function to the **Msg** object:
-
-    ```ts
-    export const Msg = {
-        ...
-        ...errorMsg,
-    }
-    ```
-
-1. Handle the error message in the **update** function:
-
-    ```ts
-    ...
-    case "error":
-        return handleError(msg.error);
-    ...
-    ```
-
-The **handleError** function then calls your error handling middleware.
-
-## Dispatch commands in the update map or update function
-
-In addition to modifying the model, you can dispatch new commands here.
-
-To do so, you can call one of the functions in the `cmd` object:
+Then you can call one of the functions of that object:
 
 | Function | Description |
 |---|---|
@@ -332,6 +269,7 @@ To do so, you can call one of the functions in the `cmd` object:
 | `cmd.ofPromise.either` | Calls an async function and maps the result into a message. |
 | `cmd.ofPromise.attempt` | Like `either` but ignores the success case. |
 | `cmd.ofPromise.perform` | Like `either` but ignores the error case. |
+| `cmd.ofSub` | Use this function to trigger a command in a subscription. |
 
 ### Dispatch a message
 
@@ -348,6 +286,8 @@ export const Msg = {
     printLastMessage: (message: string): Message => ({ name: "printLastMessage", message }),
     ...
 }
+
+const cmd = createCmd<Message>();
 ```
 
 In the **update** function you can dispatch that message like this:
@@ -408,6 +348,191 @@ case "error":
 ...
 ```
 
+### Dispatch a command from `init`
+
+The same way as in the `update` map or function, you can also dispatch an initial command in the `init` function:
+
+```ts
+export function init (props: Props): InitResult {
+    return [
+        {
+            value: props.initialValue,
+        },
+        cmd.ofMsg(Msg.loadData())
+    ];
+};
+```
+
+## Subscriptions
+
+### Working with external sources of events
+
+If you want to use external sources of events (e.g. a timer), you can use a `subscription`. With this those events can be processed by our `update` handler.
+
+Let's define a `Model` and a `Message`:
+
+```ts
+type Message =
+    | { name: "timer", date: Date };
+
+interface Model {
+    date: Date,
+}
+
+const Msg = {
+    timer: (date: Date): Message => ({ name: "timer", date }),
+};
+```
+
+Now we define the `init` function and the `update` object:
+
+```ts
+const cmd = createCmd<Message>();
+
+function init (props: Props): InitResult<Model, Message> {
+    return [{
+        date: new Date(),
+    }];
+}
+
+const update: UpdateMap<Props, Model, Message> = {
+    timer ({ date }) {
+        return [{ date }];
+    },
+};
+```
+
+Then we write our `subscription` function:
+
+```ts
+function subscription (model: Model): SubscriptionResult<Message> {
+    const sub = (dispatch: Dispatch<Message>): void => {
+        setInterval(() => dispatch(Msg.timer(new Date())), 1000) as unknown as number;
+    }
+
+    return [cmd.ofSub(sub)];
+}
+```
+
+This function gets the initialized model as parameter and returns a command.
+
+In the function component we call `useElmish` and pass the subscription to it:
+
+```ts
+const [{ date }] = useElmish({ name: "Subscriptions", props, init, update, subscription })
+```
+
+You can define and aggregate multiple subscriptions with a call to `cmd.batch(...)`.
+
+### Cleanup subscriptions
+
+In the solution above `setInterval` will trigger events even if the component is removed from the DOM. To cleanup subscriptions, we can return a `destructor` function from the subscription the same as in the `useEffect` hook.
+
+Let's rewrite our `subscription` function:
+
+```ts
+function subscription (model: Model): SubscriptionResult<Message> {
+    let timer: NodeJS.Timer;
+
+    const sub = (dispatch: Dispatch<Message>): void => {
+        timer = setInterval(() => dispatch(Msg.timer(new Date())), 1000);
+    }
+
+    const destructor = () => {
+        clearInterval(timer1);
+    }
+
+    return [cmd.ofSub(sub), destructor];
+}
+```
+
+Here we save the return value of `setInterval` and clear that interval in the returned `destructor` function.
+
+## Setup
+
+**react-elmish** works without a setup. But if you want to use logging or some middleware, you can setup **react-elmish** at the start of your program.
+
+```ts
+import { init } from "react-elmish";
+
+const myLogger = {
+    debug(...args: unknown []) {
+        console.debug(...args);
+    },
+    info(...args: unknown []) {
+        console.info(...args);
+    },
+    error(...args: unknown []) {
+        console.error(...args);
+    },
+}
+
+init({
+    logger: myLogger,
+    errorMiddleware: error => Toast.error(error.message),
+    dispatchMiddleware: msg => myLogger.debug(msg),
+});
+```
+
+The error middleware function is called by the `handleError` function (see [Error handling](#error-handling)).
+
+The dispatch middleware function is called whenever a Message is dispatched.
+
+## Error handling
+
+You can handle errors easily with the following pattern.
+
+1. Add an error message:
+
+    ```ts
+    import { ErrorMessage, errorHandler, errorMsg, handleError } from "react-elmish";
+
+    export type Message =
+        // | ...
+        | ErrorMessage;
+    ```
+
+1. Optionally add the convenient function to the `Msg` object:
+
+    ```ts
+    export const Msg = {
+        // ...
+        ...errorMsg,
+    }
+    ```
+
+1. Handle the error message
+    1. In the `update` function:
+
+        ```ts
+        // ...
+        case "error":
+            return handleError(msg.error);
+        // ...
+        ```
+
+    1. Or in the `UpdateMap`:
+
+        ```ts
+        const updateMap = {
+            // ...
+            error ({ error }) {
+                return handleError(error);
+            }
+        };
+        ```
+
+        Your can also use the `errorHandler` helper function:
+
+        ```ts
+        const updateMap = {
+            // ...
+            ...errorHandler()
+        };
+        ```
+
+The **handleError** function then calls your error handling middleware.
+
 ## React life cycle management
 
 If you want to use `componentDidMount` or `componentWillUnmount` in a class component, don't forget to call the base class implementation of it as the **ElmComponent** is using them internally.

package/dist/Cmd.d.ts

@@ -9,25 +9,29 @@ declare type Sub<TMsg> = (dispatch: Dispatch<TMsg>, fallback?: FallbackHandler)
  */
 export declare type Cmd<TMsg> = Sub<TMsg>[];
 /**
- * Class to create commands.
- * @class Command
- * @template TMsg Type of the Msg discriminated union.
+ * Contains functions to create commands.
+ * @template TMsg Type of the Message discriminated union.
  */
-declare class Command<TMsg> {
+interface Command<TMsg> {
     /**
      * Represents an empty command.
      */
-    none: never[];
+    none: [];
     /**
      * Creates a command out of a specific message.
      * @param {TMsg} msg The specific message.
      */
-    ofMsg(msg: TMsg): Cmd<TMsg>;
+    ofMsg: (msg: TMsg) => Cmd<TMsg>;
     /**
      * Aggregates multiple commands.
      * @param {Cmd<TMsg> []} commands Array of commands.
      */
-    batch(...commands: Cmd<TMsg>[]): Cmd<TMsg>;
+    batch: (...commands: Cmd<TMsg>[]) => Cmd<TMsg>;
+    /**
+     * Command to call the subscriber.
+     * @param {Sub<TMsg>} sub The subscriber function.
+     */
+    ofSub: (sub: Sub<TMsg>) => Cmd<TMsg>;
     /**
      * Provides functionalities to create commands from simple functions.
      */
@@ -39,21 +43,21 @@ declare class Command<TMsg> {
         * @param ofError Creates the message to dispatch when an error occurred.
         * @param args The parameters of the task.
         */
-        either<TArgs extends unknown[], TReturn>(task: (...args: TArgs) => TReturn, ofSuccess: (result: TReturn) => TMsg, ofError: (error: Error) => TMsg, ...args: TArgs): Cmd<TMsg>;
+        either: <TArgs extends unknown[], TReturn>(task: (...args: TArgs) => TReturn, ofSuccess: (result: TReturn) => TMsg, ofError: (error: Error) => TMsg, ...args: TArgs) => Cmd<TMsg>;
         /**
         * Creates a command out of a simple function and ignores the error case.
         * @param task The function to call.
         * @param ofSuccess Creates the message to dispatch after a successful call of the task.
         * @param args The parameters of the task.
         */
-        perform<TArgs_1 extends unknown[], TReturn_1>(task: (...args: TArgs_1) => TReturn_1, ofSuccess: (result: TReturn_1) => TMsg, ...args: TArgs_1): Cmd<TMsg>;
+        perform: <TArgs extends unknown[], TReturn>(task: (...args: TArgs) => TReturn, ofSuccess: (result: TReturn) => TMsg, ...args: TArgs) => Cmd<TMsg>;
         /**
         * Creates a command out of a simple function and ignores the success case.
         * @param task The function to call.
         * @param ofError Creates the message to dispatch when an error occurred.
         * @param args The parameters of the task.
         */
-        attempt<TArgs_2 extends unknown[], TReturn_2>(task: (...args: TArgs_2) => TReturn_2, ofError: (error: Error) => TMsg, ...args: TArgs_2): Cmd<TMsg>;
+        attempt: <TArgs extends unknown[], TReturn>(task: (...args: TArgs) => TReturn, ofError: (error: Error) => TMsg, ...args: TArgs) => Cmd<TMsg>;
     };
     /**
      * Provides functionalities to create commands from async functions.
@@ -66,27 +70,26 @@ declare class Command<TMsg> {
         * @param ofError Creates the message to dispatch when the promise is rejected.
         * @param args The parameters of the task.
         */
-        either<TArgs extends unknown[], TReturn>(task: (...args: TArgs) => Promise<TReturn>, ofSuccess: (result: TReturn) => TMsg, ofError: (error: Error) => TMsg, ...args: TArgs): Cmd<TMsg>;
+        either: <TArgs extends unknown[], TReturn>(task: (...args: TArgs) => Promise<TReturn>, ofSuccess: (result: TReturn) => TMsg, ofError: (error: Error) => TMsg, ...args: TArgs) => Cmd<TMsg>;
         /**
         * Creates a command out of an async function and ignores the error case.
         * @param task The async function to call.
         * @param ofSuccess Creates the message to dispatch when the promise is resolved.
         * @param args The parameters of the task.
         */
-        perform<TArgs_1 extends unknown[], TReturn_1>(task: (...args: TArgs_1) => Promise<TReturn_1>, ofSuccess: (result: TReturn_1) => TMsg, ...args: TArgs_1): Cmd<TMsg>;
+        perform: <TArgs extends unknown[], TReturn>(task: (...args: TArgs) => Promise<TReturn>, ofSuccess: (result: TReturn) => TMsg, ...args: TArgs) => Cmd<TMsg>;
         /**
         * Creates a command out of an async function and ignores the success case.
         * @param task The async function to call.
         * @param ofError Creates the message to dispatch when the promise is rejected.
         * @param args The parameters of the task.
         */
-        attempt<TArgs_2 extends unknown[], TReturn_2>(task: (...args: TArgs_2) => Promise<TReturn_2>, ofError: (error: Error) => TMsg, ...args: TArgs_2): Cmd<TMsg>;
+        attempt: <TArgs extends unknown[], TReturn>(task: (...args: TArgs) => Promise<TReturn>, ofError: (error: Error) => TMsg, ...args: TArgs) => Cmd<TMsg>;
     };
 }
 /**
  * Creates a typed instance of the Command class.
  * @template TMsg The type of the Msg discriminated union.
- * @see Command
  */
 export declare function createCmd<TMsg>(): Command<TMsg>;
 export {};