react-elmish 2.2.0 → 3.2.0

package/README.md

@@ -25,66 +25,75 @@ An elmish component basically consists of the following parts:
 First import everything from `react-elmish` and declare the **Message** discriminated union type:
 
 ```ts
-import * as Elm from "react-elmish";
+import { Cmd, createCmd, InitResult, UpdateReturnType, UpdateMap } from "react-elmish";
 
 export type Message =
-    | { name: "Increment" }
-    | { name: "Decrement" }
-    ;
+    | { name: "increment" }
+    | { name: "decrement" };
 ```
 
-You can also create some convenience functions to dispatch a message:
+You can also create some convenience functions to create message objects:
 
 ```ts
 export const Msg = {
-    increment: (): Message => ({ name: "Increment" }),
-    decrement: (): Message => ({ name: "Decrement" }),
+    increment: (): Message => ({ name: "increment" }),
+    decrement: (): Message => ({ name: "decrement" }),
 };
 ```
 
-Now we can create a `cmd` object for our messages type:
-
-```ts
-const cmd = Elm.createCmd<Message>();
-```
-
 Next, declare the model:
 
 ```ts
-export type Model = Readonly<{
+export interface Model {
     value: number,
-}>;
+}
 ```
 
 The props are optional:
 
 ```ts
-export type Props = {
+export interface Props {
     initialValue: number,
-};
+}
 ```
 
 To create the initial model we need an **init** function:
 
 ```ts
-export const init = (props: Props): [Model, Elm.Cmd<Message>] => {
-    const model: Model = {
-        value: props.initialValue,
-    };
+export function init (props: Props): InitResult {
+    return [
+        {
+            value: props.initialValue,
+        }
+    ];
+};
+```
+
+To update the model based on a message we need an `UpdateMap` object:
 
-    return [model, cmd.none];
+```ts
+export const update: UpdateMap<Props, Model, Message> = {
+    increment (msg, model, props) {
+        return [{ value: model.value + 1 }];
+    },
+
+    decrement (msg, model, props) {
+        return [{ value: model.value - 1 }];
+    },
 };
 ```
 
-To update the model based on a message we need an **update** function:
+**Note:** When using an `UpdateMap` it is recommended to use camelCase for message names ("increment" instead of "Increment").
+
+Alternatively we can use an **update** function:
 
 ```ts
-export const update = (model: Model, msg: Msg, props: Props): Elm.UpdateReturnType<Model, Message> => {
+export const update = (model: Model, msg: Msg, props: Props): UpdateReturnType<Model, Message> => {
     switch (msg.name) {
-        case "Increment":
+        case "increment":
             return [{ value: model.value + 1 }];
 
-        case "Decrement":
+        case "decrement":
             return [{ value: model.value - 1 }];
     }
 };
@@ -96,25 +105,49 @@ export const update = (model: Model, msg: Msg, props: Props): Elm.UpdateReturnTy
 
 To put all this together and to render our component, we need a React component.
 
-This can be a **class component**:
+As a **function component**:
 
 ```tsx
 // Import everything from the App.ts
-import * as Shared from "../App";
+import { init, update, Msg, Props } from "../App";
+// Import the useElmish hook
+import { useElmish } from "react-elmish";
+
+function App (props: Props): JSX.Element {
+    // Call the useElmish hook, it returns the current model and the dispatch function
+    const [model, dispatch] = useElmish({ props, init, update, name: "App" });
+
+    return (
+        <div>
+            {/* Display our current value */}
+            <p>{model.value}</p>
+
+            {/* dispatch messages */}
+            <button onClick={() => dispatch(Msg.increment())}>Increment</button>
+            <button onClick={() => dispatch(Msg.decrement())}>Decrement</button>
+        </div>
+    );
+}
+```
+
+As a **class component**:
+
+```tsx
+// Import everything from the App.ts
+import { Model, Message, Props, init, update, Msg } as Shared from "../App";
 // Import the ElmComponent which extends the React.Component
 import { ElmComponent } from "react-elmish";
-// Don't forget to import react
 import React from "react";
 
 // Create an elmish class component
-class App extends ElmComponent<Shared.Model, Shared.Message, Shared.Props> {
+class App extends ElmComponent<Model, Message, Props> {
     // Construct the component with the props and init function
-    constructor(props: Shared.Props) {
-        super(props, Shared.init, "App");
+    constructor(props: Props) {
+        super(props, init, "App");
     }
 
     // Assign our update function to the component
-    update = Shared.update;
+    update = update;
 
     render(): React.ReactNode {
         // Access the model
@@ -126,72 +159,19 @@ class App extends ElmComponent<Shared.Model, Shared.Message, Shared.Props> {
                 <p>{value}</p>
 
                 {/* Dispatch messages */}
-                <button onClick={() => this.dispatch(Shared.Msg.increment())}>Increment</button>
-                <button onClick={() => this.dispatch(Shared.Msg.decrement())}>Decrement</button>
+                <button onClick={() => this.dispatch(Msg.increment())}>Increment</button>
+                <button onClick={() => this.dispatch(Msg.decrement())}>Decrement</button>
             </div>
         );
     }
 ```
 
-Or it can be a **functional component**:
-
-```tsx
-// Import everything from the App.ts
-import * as Shared from "../App";
-// Import the useElmish hook
-import { useElmish } from "react-elmish";
-
-const App = (props: Shared.Props) => {
-    // Call the useElmish hook, it returns the current model and the dispatch function
-    const [model, dispatch] = useElmish(props, Shared.init, Shared.update, "App");
-
-    return (
-        <div>
-            {/* Display our current value */}
-            <p>{model.value}</p>
-
-            {/* dispatch messages */}
-            <button onClick={() => dispatch(Shared.Msg.increment())}>Increment</button>
-            <button onClick={() => dispatch(Shared.Msg.decrement())}>Decrement</button>
-        </div>
-    );
-};
-```
-
 You can use these components like any other React component.
 
 > **Note**: It is recommended to separate business logic and the view into separate modules. Here we put the `Messages`, `Model`, `Props`, `init`, and `update` functions into **App.ts**. The elmish React Component resides in a **Components** subfolder and is named **App.tsx**.
 >
 > You can even split the contents of the **App.ts** into two files: **Types.ts** (`Message`, `Model`, and `Props`) and **State.ts** (`init` and `update`).
 
-## A new approach
-
-Instead of `useElmish` you can use the `useElmishMap` hook. Then you have an `UpdateMap` instead of an `update` function:
-
-```ts
-const updateMap: UpdateMap<Props, Model, Message> {
-    // Now the message is the first parameter, so it is easier to omit the model parameter.
-    Increment: (msg) => [{ value: model.value + 1 }],
-    Decrement: (msg) => [{ value: model.value - 1 }],
-}
-```
-
-Add your component looks like:
-
-```tsx
-import { useElmishMap } from "react-elmish";
-
-const App = (props: Shared.Props) => {
-    const [model, dispatch] = useElmishMap(props, init, updateMap, "App");
-
-    return (
-        <div>
-            ...
-        </div>
-    );
-};
-```
-
 ## More on messages
 
 ### Message arguments
@@ -200,11 +180,11 @@ Messages can also have arguments. You can modify the example above and pass an o
 
 ```ts
 export type Message =
-    | { name: "Increment", step?: number }
+    | { name: "increment", step?: number }
     ...
 
 export const Msg = {
-    increment: (step?: number): Message => ({ name: "Increment", step }),
+    increment: (step?: number): Message => ({ name: "increment", step }),
     ...
 }
 ```
@@ -213,7 +193,7 @@ Then use this argument in the **update** function:
 
 ```ts
 ...
-case "Increment":
+case "increment":
     return [{ value: model.value + (msg.step ?? 1)}]
 ...
 ```
@@ -264,74 +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
-    export type Message =
-        | ...
-        | { name: "Error", error: Error }
-        ;
-    ```
-
-1. Optionally add the convenient function to the **Msg** object:
-
-    ```ts
-    export const Msg = {
-        ...
-        error: (error: Error): Message => ({ name: "Error", error }),
-    }
-    ```
-
-1. Handle the error message in the **update** function:
-
-    ```ts
-    ...
-    case "Error":
-        return Elm.handleError(msg.error);
-    ...
-    ```
-
-The **handleError** function then calls your error handling middleware.
-
-## Dispatch commands in the update function
-
-In addition to modifying the model, you can dispatch new commands in the **update** function.
-
-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 |
 |---|---|
@@ -344,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
 
@@ -352,24 +278,26 @@ Let's assume you have a message to display the description of the last called me
 ```ts
 export type Message =
     ...
-    | { name: "PrintLastMessage", message: string }
+    | { name: "printLastMessage", message: string }
     ...
 
 export const Msg = {
     ...
-    printLastMessage: (message: string): Message => ({ name: "PrintLastMessage", message }),
+    printLastMessage: (message: string): Message => ({ name: "printLastMessage", message }),
     ...
 }
+
+const cmd = createCmd<Message>();
 ```
 
 In the **update** function you can dispatch that message like this:
 
 ```ts
-case "Increment":
+case "increment":
     return [{ value: model.value + 1 }, cmd.ofMsg(Msg.printLastMessage("Incremented by one"))];
 ```
 
-This new message will immediately be dispatched after returning from the **update** function.
+This new message will immediately be dispatched after returning from the **update**.
 
 ### Call an async function
 
@@ -387,16 +315,16 @@ you can define the following messages:
 ```ts
 export type Messages =
     ...
-    | { name: "LoadSettings" },
-    | { name: "SettingsLoaded", settings: Settings }
-    | { name: "Error", error: Error }
+    | { name: "loadSettings" },
+    | { name: "settingsLoaded", settings: Settings }
+    | ErrorMessage
     ...
 
 export const Msg = {
     ...
-    loadSettings: (): Message => ({ name: "LoadSettings" }),
-    settingsLoaded: (settings: Settings): Message => ({ name: "SettingsLoaded", settings }),
-    error: (error: Error): Message => ({ name: "Error", error }),
+    loadSettings: (): Message => ({ name: "loadSettings" }),
+    settingsLoaded: (settings: Settings): Message => ({ name: "settingsLoaded", settings }),
+    ...errorMsg,
     ...
 };
 ```
@@ -405,21 +333,185 @@ and handle the messages in the **update** function:
 
 ```ts
 ...
-case "LoadSettings":
+case "loadSettings":
     // Create a command out of the async function with the provided arguments
     // If loadSettings resolves it dispatches "SettingsLoaded"
     // If it fails it dispatches "Error"
     // The return type of loadSettings must fit Msg.settingsLoaded
     return [{}, cmd.ofPromise.either(loadSettings, Msg.settingsLoaded, Msg.error, "firstArg", 123)];
 
-case "SettingsLoaded":
+case "settingsLoaded":
     return [{ settings: msg.settings }];
 
-case "Error":
-    return Elm.handleError(msg.error);
+case "error":
+    return handleError(msg.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, 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.
+
 ## 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.
@@ -448,34 +540,141 @@ In a functional component you can use the **useEffect** hook as normal.
 
 If you have some business logic that you want to reuse in other components, you can do this by using different sources for messages.
 
+### With an `UpdateMap`
+
 Let's say you want to load some settings, you can write a module like this:
 
 ```ts LoadSettings.ts
-import * as Elm from "react-elmish";
+import { createCmd, Cmd, ErrorMessage, UpdateMap, handleError } from "react-elmish";
+
+export interface Settings {
+    // ...
+}
+
+export type Message =
+    | { name: "loadSettings" }
+    | { name: "settingsLoaded", settings: Settings }
+    | ErrorMessage;
+
+export const Msg = {
+    loadSettings: (): Message => ({ name: "loadSettings" }),
+    settingsLoaded: (settings: Settings): Message => ({ name: "settingsLoaded", settings }),
+    error: (error: Error): Message => ({ name: "error", error }),
+};
+
+const cmd = createCmd<Message>();
+
+export interface Model {
+    settings: Settings | null,
+}
+
+export function init (): Model {
+    return {
+        settings: null
+    };
+}
+
+export const update: UpdateMap<Props, Model, Message> = {
+    loadSettings () {
+        return [{}, cmd.ofPromise.either(loadSettings, Msg.settingsLoaded, Msg.error)];
+    }
+
+    settingsLoaded ({ settings }) {
+        return [{ settings }];
+    }
+
+    error ({ error }) {
+        return handleError(error);
+    }
+};
+
+async function loadSettings (): Promise<Settings> {
+    // Call some service (e.g. database or backend)
+    return {};
+}
+```
+
+> **Note**: This module has no **View**.
+
+Now let's integrate the **LoadSettings** module in our component:
+
+```ts Composition.ts
+// Import the LoadSettings module
+import * as LoadSettings from "./LoadSettings";
+import { createCmd, Cmd, } from "react-elmish";
+
+// Here we define our local messages
+type Message =
+    | { name: "myMessage" }
+    | LoadSettings.Message;
+
+// And spread the Msg of LoadSettings object
+export const Msg = {
+    myMessage: (): Message => ({ name: "myMessage" }),
+    ...LoadSettings.Msg,
+};
+
+const cmd = Elm.createCmd<Message>();
+
+interface Props {}
+
+// Extend the LoadSettings model
+interface Model extends LoadSettings.Model {
+    // ...
+}
+
+export const init = (): [Model, Cmd<Message>] => {
+    // Return the model and dispatch the LoadSettings message
+    return [
+        {
+            // Spread the initial model from LoadSettings
+            ...LoadSettings.init(),
+            // ...
+        },
+        cmd.ofMsg(Msg.loadSettings())
+    ];
+};
+
+// Spread the UpdateMap of LoadSettings into our update map
+const update: UpdateMap<Props, Model, Message> = {
+    myMessage () {
+        return [{}];
+    },
+
+    ...LoadSettings.update,
+};
+```
+
+## With an update function
+
+Let's say you want to load some settings, you can write a module like this:
+
+```ts LoadSettings.ts
+import { MsgSource, ErrorMessage, createCmd, UpdateReturnType, handleError } from "react-elmish";
 
 export type Settings = {
     // ...
 };
 
 // We use a MsgSource to differentiate between the messages
-type MessageSource = Elm.MsgSource<"LoadSettings">;
+type MessageSource = MsgSource<"LoadSettings">;
 
 // Add that MessageSource to all the messages
 export type Message =
-    | { name: "LoadSettings" } & MessageSource
-    | { name: "SettingsLoaded", settings: Settings } & MessageSource
-    | { name: "Error", error: Error } & MessageSource
+    | { name: "loadSettings" } & MessageSource
+    | { name: "settingsLoaded", settings: Settings } & MessageSource
+    | ErrorMessage & MessageSource
 
 // Do the same for the convenient functions
 const MsgSource: MessageSource = { source: "LoadSettings" };
 
 export const Msg = {
-    loadSettings: (): Message => ({ name: "LoadSettings", ...MsgSource }),
-    settingsLoaded: (settings: Settings): Message => ({ name: "SettingsLoaded", settings, ...MsgSource }),
-    error: (error: Error): Message => ({ name: "Error", error, ...MsgSource }),
+    loadSettings: (): Message => ({ name: "loadSettings", ...MsgSource }),
+    settingsLoaded: (settings: Settings): Message => ({ name: "settingsLoaded", settings, ...MsgSource }),
+    error: (error: Error): Message => ({ name: "error", error, ...MsgSource }),
 };
 
-const cmd = Elm.createCmd<Message>();
+const cmd = createCmd<Message>();
 
 export type Model = Readonly<{
     settings: Settings | null,
@@ -485,23 +684,23 @@ export const init = (): Model => ({
     settings: null,
 });
 
-export const update = (_model: Model, msg: Message): Elm.UpdateReturnType<Model, Message> => {
+export const update = (_model: Model, msg: Message): UpdateReturnType<Model, Message> => {
     switch (msg.name) {
-        case "LoadSettings":
+        case "loadSettings":
             return [{}, cmd.ofPromise.either(loadSettings, Msg.settingsLoaded, Msg.error)];
 
-        case "SettingsLoaded":
+        case "settingsLoaded":
             return [{ settings: msg.settings }];
 
-        case "Error":
-            return Elm.handleError(msg.error);
+        case "error":
+            return handleError(msg.error);
     }
 };
 
-const loadSettings = async (): Promise<Settings> => {
+async function loadSettings (): Promise<Settings> {
     // Call some service (e.g. database or backend)
-    return Promise.resolve({});
-};
+    return {};
+}
 ```
 
 > **Note**: This module has no **View**.
@@ -509,51 +708,51 @@ const loadSettings = async (): Promise<Settings> => {
 In other components where we want to use this **LoadSettings** module, we also need a message source:
 
 ```ts Composition.ts
-import * as Elm from "react-elmish";
+import { createCmd, MsgSource, UpdateReturnType, Cmd } from "react-elmish";
 // Import the LoadSettings module
 import * as LoadSettings from "./LoadSettings";
 
 // Create a message source for this module
-type MessageSource = Elm.MsgSource<"Composition">;
+type MessageSource = MsgSource<"Composition">;
 
 // Here we define our local messages
 // We don't need to export them
 type CompositionMessage =
-    | { name: "MyMessage" } & MessageSource
-    ;
+    | { name: "myMessage" } & MessageSource;
 
 // Combine the local messages and the ones from LoadSettings
 export type Message =
     | CompositionMessage
-    | LoadSettings.Message
-    ;
+    | LoadSettings.Message;
 
 const MsgSource: MessageSource = { source: "Composition" };
 
 export const Msg = {
-    myMessage: (): Message => ({ name: "MyMessage", ...MsgSource }),
+    myMessage: (): Message => ({ name: "myMessage", ...MsgSource }),
+    ...LoadSettings.Msg,
 };
 
-const cmd = Elm.createCmd<Message>();
+const cmd = createCmd<Message>();
 
 // Include the LoadSettings Model
-export type Model = Readonly<{
+export interface Model extends LoadSettings.Model {
     // ...
-}> & LoadSettings.Model;
-
-export const init = (): [Model, Elm.Cmd<Message>] => {
-    const model: Model = {
-        // Spread the initial model from LoadSettings
-        ...LoadSettings.init(),
-        // ...
-    };
+}
 
+export const init = (): [Model, Cmd<Message>] => {
     // Return the model and dispatch the LoadSettings message
-    return [model, cmd.ofMsg(LoadSettings.Msg.loadSettings())];
+    return [
+        {
+            // Spread the initial model from LoadSettings
+            ...LoadSettings.init(),
+            // ...
+        },
+        cmd.ofMsg(Msg.loadSettings())
+    ];
 };
 
 // In our update function, we first distinguish between the sources of the messages
-export const update = (model: Model, msg: Message): Elm.UpdateReturnType<Model, Message> => {
+export function update (model: Model, msg: Message): UpdateReturnType<Model, Message> {
     switch (msg.source) {
         case "Composition":
             // Then call the update function for the local messages
@@ -568,7 +767,7 @@ export const update = (model: Model, msg: Message): Elm.UpdateReturnType<Model,
 // For the msg parameter we use the local CompositionMessage type
 const updateComposition = (model: Model, msg: CompositionMessage): Elm.UpdateReturnType<Model, Message> => {
     switch (msg.name) {
-        case "MyMessage":
+        case "myMessage":
             return [{}];
     }
 }
@@ -585,12 +784,12 @@ To inform the parent component about some action, let's say to close a dialog fo
     ```ts Dialog.ts
     export type Message =
         ...
-        | { name: "Close" }
+        | { name: "close" }
         ...
 
     export const Msg = {
         ...
-        close: (): Message => ({ name: "Close" }),
+        close: (): Message => ({ name: "close" }),
         ...
     }
     ```
@@ -607,8 +806,9 @@ To inform the parent component about some action, let's say to close a dialog fo
 
     ```ts Dialog.ts
     ...
-    case "Close":
+    case "close":
         props.onClose();
+
         return [{}];
     ...
     ```
@@ -629,6 +829,7 @@ To test your **update** function you can use some helper functions in `react-elm
 | --- | --- |
 | `getOfMsgParams` | Extracts the messages out of a command |
 | `execCmd` | Executes the provided command and returns an array of all messages. |
+| `getUpdateFn` | returns an `update` function for your update map object. |
 
 ### Testing the model and simple message commands
 
@@ -690,10 +891,10 @@ it("returns the correct cmd", () => {
 
 ### Testing with an UpdateMap
 
-To test your update map (when using `useElmishMap`), you can get your `update` function by calling `getUpdateFn`:
+To test your update map, you can get an `update` function by calling `getUpdateFn`:
 
 ```ts
-import * as Testing from "react-elmish/dist/Testing";
+import { getUpdateFn } from "react-elmish/dist/Testing";
 
 const update = getUpdateFn(updateMap);
 
@@ -701,7 +902,7 @@ const update = getUpdateFn(updateMap);
 const [model, cmd] = update(msg, model, props);
 ```
 
-## Migration from v1.x to 2.x
+## Migration from v1.x to v2.x
 
 * Use `Logger` and `Message` instead of `ILogger` and `IMessage`.
 * The global declaration of the `Nullable` type was removed, because it is unexpected for this library to declare such a type. You can declare this type for yourself if needed:
@@ -711,3 +912,16 @@ const [model, cmd] = update(msg, model, props);
         type Nullable<T> = T | null;
     }
     ```
+
+## Migration from v2.x to v3.x
+
+The signature of `useElmish` has changed. It takes an options object now. Thus there is no need for the `useElmishMap` function. Use the new `useElmish` hook with an `UpdateMap` instead.
+
+To use the old `useElmish` and `useElmishMap` functions, import them from the legacy namespace:
+
+```ts
+import { useElmish } from "react-elmish/dist/legacy/useElmish";
+import { useElmishMap } from "react-elmish/dist/legacy/useElmishMap";
+```
+
+**Notice**: These functions are marked as deprecated and will be removed in a later release.