Updates docs

Author: ctrlplusb

website/docs/.vuepress/config.js

@@ -112,6 +112,9 @@ module.exports = {
             'typescript-tutorial/typed-hooks',
             'typescript-tutorial/adding-typed-actions',
             'typescript-tutorial/adding-typed-thunks',
+            'typescript-tutorial/using-typed-injections',
+            'typescript-tutorial/typing-thunk-against-the-store',
+            'typescript-tutorial/adding-typed-listeners',
           ],
         },
         {

website/docs/docs/typescript-tutorial/README.md

@@ -2,4 +2,6 @@
 
 This section will guide you through integrating and using Typescript with Easy Peasy. It will start with the basics, focusing on state only, and then introduce each of the APIs (e.g. an [action](/docs/api/action), [thunk](/docs/api/thunk), etc) as it proceeds.
 
+If you aren't familiar with Easy Peasy then I would recommend that you first familiarise yourself with it by reading the [tutorial](/docs/tutorial). This Typescript tutorial will not go into detail regarding the APIs.
+
 > **Note:** this section is a work in progress. I will be updating it as I get through it. Hopefully within a week it will be fairly complete. I appreciate your patience.

website/docs/docs/typescript-tutorial/adding-typed-actions.md

@@ -1,22 +1,22 @@
 # Adding typed actions
 
-In order to declare an action Easy Peasy exports an `Action` type. The full typing definition for the `Action` type is:
+Easy Peasy exports an `Action` type, allowing you declare an [action](/docs/api/action) against your model interface. The definition for this type is:
 
 ```typescript
 Action<Model extends Object = {}, Payload = void>
 ```
 
-As you can see it accepts 2 type parameters. They can be described as follows.
+As you can see it accepts 2 type parameters, with both being optional. These type parameters can be described as follows.
 
  - `Model`
 
-   The model against which the action is being bound. This allows us to ensure the the `state` that is exposed to our action is correctly typed.
+   The model against which the action is being bound. This allows us to ensure the the `state` that is exposed to our [action](/docs/api/action) implementation is correctly typed.
 
 - `Payload`
 
-  If you expect the action to receive a payload then you should provide the type for the payload. If your action will not receive any payload you can omit this type parameter.
+  If you expect the [action](/docs/api/action) implementation to receive a payload then you should provide the type for the payload. If your [action](/docs/api/action) will not receive any payload you can omit this type parameter.
 
-Let's define an action that will allow us to add another todo.
+Let's define an [action](/docs/api/action) that will allow us to add a todo.
 
 ```typescript
 import { Action } from 'easy-peasy'; // 👈 import the type
@@ -27,9 +27,9 @@ export interface TodosModel {
 }
 ```
 
-As you can see our `Action` is operating against the `TodosModel` and it expects a payload of `string`.
+We have provided type parameter to our `Action` informing it that it is operating against the `TodosModel` and that it should expect a payload of type `string`.
 
-We can now implement this action against our model.
+We can now implement this [action](/docs/api/action) against our model.
 
 ```typescript
 import { action } from 'easy-peasy';
@@ -42,11 +42,11 @@ const todos: TodosModel = {
 };
 ```
 
-You will have noted that Typescript was providing us with the typing information and assertions whilst we implemented our action.
+You will have noted that Typescript was providing us with the typing information and assertions whilst we implemented our [action](/docs/api/action).
 
 ***TODO: Screenshot of typing information on action implementation***
 
-We can now consume the action within our component, making sure we use the typed version of `useStoreActions` that we exported from our store.
+We can now consume the [action](/docs/api/action) within our components, whilst making sure that we use the typed `useStoreActions` that we exported from our [store](/docs/api/store).
 
 ```typescript
 import { useStoreActions } from './my-store'; // 👈 import typed hook
@@ -55,8 +55,6 @@ function AddTodo() {
   //                                  map the addTodo action 👇
   const addTodo = useStoreActions(actions => actions.todos.addTodo);
 
-  // The below are the standard React hooks we are using to manage the form
-  // state and the button onClick callback
   const [text, setText] = useState('');
   const onButtonClick = useCallback(() => {
     addTodo(text); // 👈 dispatch our action with the text describing the todo

website/docs/docs/typescript-tutorial/adding-typed-listeners.md

@@ -0,0 +1,58 @@
+# Adding typed listeners
+
+In the previous section we extended our [thunk](/docs/api/thunk) implementation so that it would create an audit log entry every time a todo was saved. This isn't the best design as the todos model shouldn't have to know about the audit model.
+
+An alternative, cleaner approach, would be for the audit model to respond to the `addTodo` action, logging accordingly. We can achieve this via an [action](/docs/api/action) configured as a listener. Let's refactor our implementation to do this.
+
+Firstly, we will add a new [action](/docs/api/action) to the interface definition for our audit model. This [action](/docs/api/action) will be used as the listener.
+
+```typescript
+interface AuditModel {
+  log: string[];
+  addLog: Action<AuditModel, string>;
+  onTodoAdded: Action<AuditModel, string>; // 👈 new action which will be used
+                                           //     as a listener
+}
+```
+
+Now we will implement the [action](/docs/api/action), configuring to to listen to the `addTodo` [action](/docs/api/action).
+
+```typescript
+import todos from './todos-model';
+
+const auditModel: AuditModel = {
+  logs: [],
+  addLog: action((state, payload) => {
+    state.logs.push(payload)
+  }),
+  onTodoAdded: action(
+    (state, payload) => {
+      state.push(`Added todo: "${payload}"`);
+    },
+    { listenTo: todos.addTodo } // 👈 binding the action to listen to.
+  )
+};
+```
+
+Now every time the `addTodo` [action](/docs/api/action) is fired our `onTodoAdded` listening [action](/docs/api/action) will fire and add an audit log.  
+
+Remember, our listening [action](/docs/api/action) will receive the same payload as the target [action](/docs/api/action). Therefore we need to ensure that the payload types will match across the listener and target. If they do not match a Typescript error will occur warning you of this fact.
+
+***TODO: Screenshot of error for mistmatching payload***
+
+We can now remove the call to the audit model within our `saveTodo` thunk.
+
+```typescript
+const todosModel: TodosModel = {
+  items: [],
+  addTodo: action((state, payload) => {
+    state.items.push(payload);
+  }),
+  saveTodo: thunk(async (actions, payload, { injections }) => {
+    const { todosService } = injections;
+    await todosService.save(payload);
+    actions.addTodo(payload);
+    getStoreActions().audit.addLog(payload);  // 👈 remove this line
+  })
+};
+```

website/docs/docs/typescript-tutorial/adding-typed-thunks.md

@@ -1,6 +1,6 @@
 # Adding typed thunks
 
-In order to declare a [thunk](/docs/api/thunk) Easy Peasy exports a `Thunk` type. The full typing definition for the `Thunk` type is:
+Easy Peasy exports a `Thunk` type, allowing you to declare a [thunk](/docs/api/thunk) against your model interface. The full typing definition for the `Thunk` type is:
 
 ```typescript
 type Thunk<
@@ -12,11 +12,13 @@ type Thunk<
 >
 ```
 
-As you can see it accepts 5 type parameters. That may seem like a lot, but in most implementations you will likely only need to provide 2 of them. I've tried to order them so that they most frequently used type parameters are defined first. The type parameters can be described as follows.
+As you can see it accepts 5 type parameters, all of them optional. This may seem like a lot of type parameters, but in most cases you will likely only need to provide 2 of them. We have tried to order the type parameters from the most to the least frequently used, based on our experience with [thunks](/docs/api/thunk). 
+
+The type parameters can be described as follows.
 
 - `Model`
 
-  The model against which the [thunk](/docs/api/thunk) is being bound. This allows us to ensure the the `actions` that are exposed to our [thunk](/docs/api/thunk) are correctly typed.
+  The model against which the [thunk](/docs/api/thunk) is being bound. This allows us to ensure the the `actions` argument that is provided to our [thunks](/docs/api/thunk) are correctly typed.
 
 - `Payload`
 
@@ -41,5 +43,60 @@ As you can see it accepts 5 type parameters. That may seem like a lot, but in mo
 Let's define a thunk that will allow us to save a todo by posting to an HTTP endpoint.
 
 ```typescript
-TODO
-```
+import { Thunk } from 'easy-peasy';
+
+export interface TodosModel {
+  items: string[];
+  addTodo: Action<TodosModel, string>; 
+  saveTodo: Thunk<TodosModel, string>; // 👈 declaring our thunk
+}
+```
+
+As you can see our `Thunk` is operating against the `TodosModel` and it expects a payload of `string`.
+
+We can now implement this action against our model.
+
+```typescript
+import { thunk } from 'easy-peasy';
+
+const todosModel: TodosModel = {
+  items: [],
+  addTodo: action((state, payload) => {
+    state.items.push(payload);
+  }),
+  saveTodo: thunk(async (actions, payload) => {
+    await todosService.save(payload); // imagine calling an HTTP service
+    actions.addTodo(payload);
+  })
+};
+```
+
+You will have noted that Typescript was providing us with the typing information and assertions whilst we implemented our [thunk](/docs/api/thunk).
+
+***TODO: Screenshot of typing information on thunk implementation***
+
+We can now consume the [thunk](/docs/api/thunk) within our component, making sure we use the typed version of `useStoreActions` that we exported from our store. We will refactor our component from earlier.
+
+```typescript
+import { useStoreActions } from './my-store'; // 👈 import typed hook
+
+function AddTodo() {
+  //                                  map the saveTodo thunk 👇
+  const saveTodo = useStoreActions(actions => actions.todos.saveTodo);
+
+  const [text, setText] = useState('');
+  const onButtonClick = useCallback(() => {
+    saveTodo(text) // 👈 dispatch our thunk with the text describing the todo
+      .then(() => setText('')); // then chain off the promise returned by the thunk
+  }, [addTodo, setText, text]);
+
+  return (
+    <>
+      <input text={text} onChange={e => setText(e.target.value)} type="text />
+      <button onClick={onButtonClick}>Add Todo</button>
+    </>
+  );
+}
+```
+
+***TODO: Screenshot of typing information on thunk dispatch***

website/docs/docs/typescript-tutorial/create-your-store.md

@@ -1,8 +1,10 @@
 # Create your store
 
-The heart of the Typescript integration with Easy Peasy are the typing definitions you provide for your model. From this Easy Peasy will be able to provide you with typing information, code completion, and assertions across the rest of its APIs.
+The heart of the Typescript integration with Easy Peasy are the typing definitions you define to represent your [store's](/docs/api/store) model. This typing information can then be used by the various Easy Peasy APIs to provide you with assertions, code completions, etc.
 
-Our model will consist of two slices; todos and an audit log. For now we will only define the state within our model, no actions etc.
+For this tutorial we will create a model consisting of two slices; todos and an audit log. 
+
+We will start by defining the state for our model - without actions/thunks/etc.
 
 ```typescript
 // The interface representing our Todos model
@@ -22,18 +24,18 @@ interface StoreModel {
 }
 ```
 
-Using our model interface we can create our initial model implementation.
+Using our model interfaces we can create our model implementation.
 
 ```typescript
-const todos: TodosModel = {
+const todosModel: TodosModel = {
   items: []
 };
 
-const audit: AuditModel = {
+const auditModel: AuditModel = {
   logs: []
 };
 
-const model: StoreModel = {
+const storeModel: StoreModel = {
   todos,
   audit
 }
@@ -43,7 +45,7 @@ Good ol' Typescript will make sure that we implement the model in full.
 
 ***TODO: Screenshot of validation against model***
 
-You can organise your interfaces and model implementation as you please. My personal preference is to split them out by slice, for example.
+You can organise your model interfaces and implementations as you please. My personal preference is to split them out into seperate files based on slice/feature.
 
 ```typescript
 // todos.ts
@@ -52,17 +54,19 @@ export interface TodosModel {
   items: Todo[];
 }
 
-const todos: TodosModel = {
+const todosModel: TodosModel = {
   items: []
 };
 
-export default todos;
+export default todosModel;
 ```
 
 Now that we have our model defined we can pass it to [createStore](/docs/api/create-store) in order to create our [store](/docs/api/store).
 
 ```typescript
-const store = createStore(model);
+import storeModel from './model';
+
+const store = createStore(storeModel);
 ```
 
 The [store](/docs/api/store) that is returned will be fully typed. If you try to use the [store's](/docs/api/store) APIs you will note the typing information and code completion being offered by your IDE.

website/docs/docs/typescript-tutorial/typed-hooks.md

@@ -1,14 +1,20 @@
 # Using typed hooks
 
-For convenience we bind the hooks to your create [store](/docs/api/store) instances. This is especially useful in the context of Typescript because all the typing information of your model will be automatically baked into these hooks. We therefore recommend that you export these hooks of your store so that you can easily import and use them within your components.
+For convenience we bind the Easy Peasy's hooks against a [store](/docs/api/store) instance. 
+
+If you were to use the hooks imported directly from the Easy Peasy library, e.g. `import { useStoreActions } from 'easy-peasy';`, you would have to provide the model interface that represents your store every time you used them.
+
+By binding the hooks against a [store](/docs/api/store) instance we provide a convenient mechanism for you to avoid have to do this. 
+
+We recommend that you extract these typed hooks off your [store](/docs/api/store) instance, and export them so that you can easily use them in your components.
 
 ```typescript
 // my-store.ts
 
 import { createStore } from 'easy-peasy';
-import model from './model';
+import storeModel from './model';
 
-const store = createStore(model);
+const store = createStore(storeModel);
 
 // 👇export the typed hooks
 export const useStoreActions = store.useStoreActions;
@@ -18,7 +24,7 @@ export const useStoreState = store.useStoreState;
 export default store;
 ```
 
-You could then import them into your components, and receive the benefit of all the model typing being available.
+We can now import the typed hooks into a component.
 
 ```typescript
 import { useStoreState } from './my-store'; // 👈 import the typed hook

website/docs/docs/typescript-tutorial/typing-thunk-against-the-store.md

@@ -0,0 +1,63 @@
+# Exposing entire store to our thunk
+
+We will now extend our [thunk](/docs/api/thunk) so that it is able to get the state/actions for the entire [store](/docs/api/store), after which we will update our [thunk](/docs/api/thunk) implementation so that it will create an audit log entry every time a todo is saved.
+
+Firstly, let's ensure that our audit model has an [action](/docs/api/action) on it which allows us to create a new log entry.
+
+```typescript
+interface AuditModel {
+  log: string[];
+  addLog: Action<AuditModel, string>;
+}
+
+const audit: AuditModel = {
+  logs: [],
+  addLog: action((state, payload) => {
+    state.logs.push(payload)
+  })
+};
+```
+
+Now let's update our [thunk](/docs/api/thunk) configuration so that it is aware of the typings that represent our entire [store](/docs/api/store).
+
+```typescript
+import { StoreModel } from './model';
+//          👆 import the interface that represents our store model
+//              don't worry about circular references, this is allowed
+
+export interface TodosModel {
+  items: string[];
+  addTodo: Action<TodosModel, string>; 
+  saveTodo: Thunk<
+    TodosModel, 
+    string, 
+    StoreInjections,
+    StoreModel // 👈 provide the store model interface
+  >; 
+}
+```
+
+We can now refactor our [thunk](/docs/api/thunk) implementation to make use of the `getStoreActions` helper that is provided to it.
+
+```typescript
+const todosModel: TodosModel = {
+  items: [],
+  addTodo: action((state, payload) => {
+    state.items.push(payload);
+  }),
+  saveTodo: thunk(async (actions, payload, { injections, getStoreActions }) => {
+    const { todosService } = injections;
+    await todosService.save(payload);
+    actions.addTodo(payload);
+    getStoreActions().audit.addLog(payload); // 👈 accessing global actions
+  })
+};
+```
+
+As you can see above we were able to get full type information against the `getStoreActions` helper, allowing us to add a log entry. It is important to note that the `getStoreState` helper would work equally as well.
+
+```typescript
+thunk(async (actions, payload, { getStoreState }) => {
+  console.log(getStoreState().audit.logs);
+})
+```