@powerhousedao/academy 5.0.0-staging.1 → 5.0.0-staging.11

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/05-ImplementDocumentReducers.md

@@ -4,7 +4,7 @@
 
 In our journey through Powerhouse Document Model creation, we've defined the "what" – the structure of our data ([State Schema](02-SpecifyTheStateSchema.md)) and the ways it can be changed ([Document Operations](03-SpecifyDocumentOperations.md)). We've also seen how the [Document Model Generator](04-UseTheDocumentModelGenerator.md) translates these specifications into a coded scaffold. Now, we arrive at the "how": implementing **Document Reducers**.
 
-Reducers are the core logic units of your document model. They are the functions that take the current state of your document and an operation (an "action"), and then determine the *new* state of the document. They are the embodiment of your business rules and the engine that drives state transitions in a predictable, auditable, and immutable way.
+Reducers are the core logic units of your document model. They are the functions that take the current state of your document and an operation (an "action"), and then determine the _new_ state of the document. They are the embodiment of your business rules and the engine that drives state transitions in a predictable, auditable, and immutable way.
 
 ## Recap: The journey to reducer implementation
 
@@ -24,22 +24,22 @@ In the context of Powerhouse and inspired by patterns like Redux, a reducer is a
 
 Let's break down its components and principles:
 
-*   **`currentState`**: This is the complete, current state of your document model instance before the operation is applied. It's crucial to treat this as **immutable**.
-*   **`action`**: This is an object describing the operation to be performed. It typically has:
-    *   A `type` property: A string identifying the operation (e.g., `'ADD_TODO_ITEM'`).
-    *   An `input` property (or similar, like `payload`): An object containing the data necessary for the operation, matching the GraphQL `input` type you defined (e.g., `{ id: '1', text: 'Buy groceries' }` for `AddTodoItemInput`).
-*   **`newState`**: The reducer must return a *new* state object representing the state after the operation has been applied. If the operation does not result in a state change, the reducer should return the `currentState` object itself.
+- **`currentState`**: This is the complete, current state of your document model instance before the operation is applied. It's crucial to treat this as **immutable**.
+- **`action`**: This is an object describing the operation to be performed. It typically has:
+  - A `type` property: A string identifying the operation (e.g., `'ADD_TODO_ITEM'`).
+  - An `input` property (or similar, like `payload`): An object containing the data necessary for the operation, matching the GraphQL `input` type you defined (e.g., `{ id: '1', text: 'Buy groceries' }` for `AddTodoItemInput`).
+- **`newState`**: The reducer must return a _new_ state object representing the state after the operation has been applied. If the operation does not result in a state change, the reducer should return the `currentState` object itself.
 
 ### Key principles guiding reducer implementation:
 
 1.  **Purity**:
-    *   **Deterministic**: Given the same `currentState` and `action`, a reducer must *always* produce the same `newState`.
-    *   **No Side Effects**: Reducers must not perform any side effects. This means no API calls, no direct DOM manipulation, no `Math.random()` (unless seeded deterministically for specific testing scenarios), and no modification of variables outside their own scope. Their sole job is to compute the next state.
+    - **Deterministic**: Given the same `currentState` and `action`, a reducer must _always_ produce the same `newState`.
+    - **No Side Effects**: Reducers must not perform any side effects. This means no API calls, no direct DOM manipulation, no `Math.random()` (unless seeded deterministically for specific testing scenarios), and no modification of variables outside their own scope. Their sole job is to compute the next state.
 
 2.  **Immutability**:
-    *   **Never Mutate `currentState`**: You must never directly modify the `currentState` object or any of its nested properties.
-    *   **Always Return a New Object for Changes**: If the state changes, you must create and return a brand new object. If the state does not change, you return the original `currentState` object.
-    *   This is fundamental to Powerhouse's event sourcing architecture, enabling time travel, efficient change detection, and a clear audit trail. We'll explore techniques for immutability shortly.
+    - **Never Mutate `currentState`**: You must never directly modify the `currentState` object or any of its nested properties.
+    - **Always Return a New Object for Changes**: If the state changes, you must create and return a brand new object. If the state does not change, you return the original `currentState` object.
+    - This is fundamental to Powerhouse's event sourcing architecture, enabling time travel, efficient change detection, and a clear audit trail. We'll explore techniques for immutability shortly.
 
 3.  **Single Source of Truth**: The document state managed by reducers is the single source of truth for that document instance. All UI rendering and data queries are derived from this state.
 
@@ -47,8 +47,8 @@ Let's break down its components and principles:
     While you can write one large reducer that uses a `switch` statement or `if/else if` blocks based on `action.type`, Powerhouse's generated code typically encourages a more modular approach. You'll often implement a separate function for each operation, which are then combined into a main reducer object or map. The `ph generate` command usually sets up this structure for you. For example, in your `document-models/to-do-list/src/reducers/to-do-list.ts`, you'll find an object structure like this:
 
     ```typescript
-    import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js'; // Generated type for operations
-    import { ToDoListState } from '../../gen/types.js'; // Generated type for state
+    import { ToDoListToDoListOperations } from "../../gen/to-do-list/operations.js"; // Generated type for operations
+    import { ToDoListState } from "../../gen/types.js"; // Generated type for state
 
     export const reducer: ToDoListToDoListOperations = {
       addTodoItemOperation(state: ToDoListState, action, dispatch) {
@@ -69,6 +69,7 @@ Let's break down its components and principles:
       // ... other operations
     };
     ```
+
     The `ToDoListToDoListOperations` type (or similar, depending on your model name) is generated by Powerhouse and ensures your reducer object correctly implements all defined operations. The `state` and `action` parameters within these methods will also be strongly typed based on your schema.
 
     The `dispatch` parameter is an advanced feature allowing a reducer to trigger subsequent operations. While powerful for complex workflows, it's often not needed for basic operations and can be ignored if unused.
@@ -78,6 +79,7 @@ Let's break down its components and principles:
 Let's use our familiar `ToDoList` example to illustrate common patterns. For this example, we'll assume our state schema has been updated to include a `stats` object to track the number of total, checked, and unchecked items.
 
 Our `ToDoListState` now looks like this:
+
 ```typescript
 interface ToDoItem {
   id: string;
@@ -98,9 +100,10 @@ interface ToDoListState {
 ```
 
 And our action creators (from `../../gen/creators` or `../../gen/operations.js`) provide actions like:
-*   `actions.addTodoItem({ id: 'some-id', text: 'New Task' })`
-*   `actions.updateTodoItem({ id: 'item-id', text: 'Updated Task Text', checked: true })`
-*   `actions.deleteTodoItem({ id: 'item-id' })`
+
+- `actions.addTodoItem({ id: 'some-id', text: 'New Task' })`
+- `actions.updateTodoItem({ id: 'item-id', text: 'Updated Task Text', checked: true })`
+- `actions.deleteTodoItem({ id: 'item-id' })`
 
 ### 1. Adding an item (e.g., `addTodoItemOperation`)
 
@@ -121,9 +124,11 @@ addTodoItemOperation(state: ToDoListState, action: /* AddTodoItemActionType */ a
   };
 }
 ```
+
 **Explanation**:
-*   We use the spread operator (`...state`) to copy top-level properties from the old state into the new state object.
-*   For the `items` array, we create a *new* array by spreading the existing `state.items` and then appending the `newItem`.
+
+- We use the spread operator (`...state`) to copy top-level properties from the old state into the new state object.
+- For the `items` array, we create a _new_ array by spreading the existing `state.items` and then appending the `newItem`.
 
 ### 2. Updating an item (e.g., `updateTodoItemOperation`)
 
@@ -152,16 +157,19 @@ updateTodoItemOperation(state: ToDoListState, action: /* UpdateTodoItemActionTyp
   };
 }
 ```
+
 **Explanation**:
-*   We use the `map` array method, which always returns a *new* array.
-*   For the item that matches `action.input.id`, we create a new item object using the spread operator (`...item`) and then overwrite the properties (`text`, `checked`) that are present in `action.input`.
-*   The conditional spread (`...(condition && { property: value })`) is a concise way to only include a property in the new object if its corresponding input value is provided. This elegantly handles partial updates.
-*   If an item doesn't match the ID, it's returned as is.
+
+- We use the `map` array method, which always returns a _new_ array.
+- For the item that matches `action.input.id`, we create a new item object using the spread operator (`...item`) and then overwrite the properties (`text`, `checked`) that are present in `action.input`.
+- The conditional spread (`...(condition && { property: value })`) is a concise way to only include a property in the new object if its corresponding input value is provided. This elegantly handles partial updates.
+- If an item doesn't match the ID, it's returned as is.
 
 **Error Handling Note**: In a real application, you might want to add a check to see if an item with `action.input.id` actually exists. If not, you could throw an error or handle it according to your application's requirements:
+
 ```typescript
 // Inside updateTodoItemOperation, before returning:
-const itemToUpdate = state.items.find(item => item.id === action.input.id);
+const itemToUpdate = state.items.find((item) => item.id === action.input.id);
 if (!itemToUpdate) {
   // Option 1: Throw an error (Powerhouse runtime might catch this)
   throw new Error(`Item with id ${action.input.id} not found.`);
@@ -186,8 +194,10 @@ deleteTodoItemOperation(state: ToDoListState, action: /* DeleteTodoItemActionTyp
   };
 }
 ```
+
 **Explanation**:
-*   We use the `filter` array method, which returns a *new* array containing only the elements for which the callback function returns `true`.
+
+- We use the `filter` array method, which returns a _new_ array containing only the elements for which the callback function returns `true`.
 
 ## Leveraging generated types
 
@@ -200,8 +210,8 @@ import {
   ToDoListState,
   AddTodoItemInput, // Generated input type
   // ... other types
-} from '../../gen/types.js';
-import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js'; // Generated operations type
+} from "../../gen/types.js";
+import { ToDoListToDoListOperations } from "../../gen/to-do-list/operations.js"; // Generated operations type
 
 // Define the type for the action more explicitly if needed, or rely on inferred types
 // from ToDoListToDoListOperations. For complex actions, defining specific action types can be beneficial.
@@ -212,7 +222,11 @@ import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
 // }
 
 export const reducer: ToDoListToDoListOperations = {
-  addTodoItemOperation(state: ToDoListState, action: { input: AddTodoItemInput /* plus type property */ }, dispatch) {
+  addTodoItemOperation(
+    state: ToDoListState,
+    action: { input: AddTodoItemInput /* plus type property */ },
+    dispatch,
+  ) {
     // Now 'action.input.text' and 'action.input.id' are type-checked
     const newItem = {
       id: action.input.id,
@@ -227,10 +241,12 @@ export const reducer: ToDoListToDoListOperations = {
   // ... other reducers
 };
 ```
+
 Using these types provides:
-*   **Compile-time safety**: Catch errors related to incorrect property names or data types before runtime.
-*   **Autocompletion and IntelliSense**: Improved developer experience in your IDE.
-*   **Clearer code**: Types serve as documentation for the expected data structures.
+
+- **Compile-time safety**: Catch errors related to incorrect property names or data types before runtime.
+- **Autocompletion and IntelliSense**: Improved developer experience in your IDE.
+- **Clearer code**: Types serve as documentation for the expected data structures.
 
 ## Practical implementation: Writing the `ToDoList` reducers
 
@@ -246,87 +262,89 @@ This tutorial assumes you have followed the steps in the previous chapters, espe
 Navigate to `document-models/to-do-list/src/reducers/to-do-list.ts`. The generator will have created a skeleton file. Replace its contents with the following logic.
 
 ```typescript
-import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
-import { ToDoListState } from '../../gen/types.js'; // Assuming this now includes the 'stats' object
+import { ToDoListToDoListOperations } from "../../gen/to-do-list/operations.js";
+import { ToDoListState } from "../../gen/types.js"; // Assuming this now includes the 'stats' object
 
 // REMARKS: This is our main reducer object. It implements all operations defined in the schema.
 // The ToDoListToDoListOperations type is auto-generated from our GraphQL specification and ensures type safety.
 export const reducer: ToDoListToDoListOperations = {
-    // REMARKS: The addTodoItemOperation adds a new item and updates our tracking statistics.
-    // - state: The current document state. Powerhouse uses a library like Immer.js,
-    //   so you can write code that looks like it's mutating the state directly.
-    //   Behind the scenes, Powerhouse ensures this results in an immutable update.
-    // - action: Contains the operation's 'type' and 'input' data from the client.
-    // - dispatch: A function to trigger subsequent operations (advanced, not used here).
-    addTodoItemOperation(state, action, dispatch) {
-        // REMARKS: We update our statistics for total and unchecked items.
-        state.stats.total += 1;
-        state.stats.unchecked += 1;
-
-        // REMARKS: We push the new to-do item into the items array.
-        // The data for the new item comes from the operation's input.
-        state.items.push({
-            id: action.input.id,
-            text: action.input.text,
-            checked: false, // New items always start as unchecked.
-        });
-    },
-
-    // REMARKS: The updateTodoItemOperation modifies an existing to-do item.
-    // It handles partial updates for text and checked status.
-    updateTodoItemOperation(state, action, dispatch) {
-        // REMARKS: First, we find the specific item we want to update using its ID.
-        const item = state.items.find(item => item.id === action.input.id);
-        
-        // REMARKS: It's good practice to handle cases where the item might not be found.
-        if (!item) {
-            throw new Error(`Item with id ${action.input.id} not found`);
-        }
-        
-        // REMARKS: We only update the text if it was provided in the input.
-        // This allows for partial updates (e.g., just checking an item without changing its text).
-        if (action.input.text) {
-            item.text = action.input.text;
-        }
-
-        // REMARKS: When the checked status changes, we also update our statistics.
-        // We check for `true` and `false` explicitly.
-        if (action.input.checked) { // This is true only if action.input.checked is true
-            // Note: This assumes the item was previously unchecked. For a more robust implementation,
-            // you could check `if (item.checked === false)` before updating stats to prevent inconsistencies.
-            state.stats.unchecked -= 1;
-            state.stats.checked += 1;
-            item.checked = action.input.checked;
-        }
-        if (action.input.checked === false) {
-            // Note: This assumes the item was previously checked.
-            state.stats.unchecked += 1;
-            state.stats.checked -= 1;
-            item.checked = action.input.checked;
-        }
-    },
-
-    // REMARKS: The deleteTodoItemOperation removes an item from the list.
-    deleteTodoItemOperation(state, action, dispatch) {
-        // REMARKS: Before removing the item, we find it to determine its checked status.
-        // This is necessary to correctly decrement our statistics.
-        const item = state.items.find(item => item.id === action.input.id);
-
-        // REMARKS: We always decrement the total count.
-        state.stats.total -= 1;
-
-        // REMARKS: We then decrement the 'checked' or 'unchecked' count based on the item's status.
-        if (item?.checked) { // This is shorthand for item?.checked === true
-            state.stats.checked -= 1;
-        }
-        if (item?.checked === false) {
-            state.stats.unchecked -= 1;
-        }
-
-        // REMARKS: Finally, we create a new 'items' array that excludes the deleted item.
-        // Assigning to 'state.items' is handled by Powerhouse to produce a new immutable state.
-        state.items = state.items.filter(item => item.id !== action.input.id);
-    },
+  // REMARKS: The addTodoItemOperation adds a new item and updates our tracking statistics.
+  // - state: The current document state. Powerhouse uses a library like Immer.js,
+  //   so you can write code that looks like it's mutating the state directly.
+  //   Behind the scenes, Powerhouse ensures this results in an immutable update.
+  // - action: Contains the operation's 'type' and 'input' data from the client.
+  // - dispatch: A function to trigger subsequent operations (advanced, not used here).
+  addTodoItemOperation(state, action, dispatch) {
+    // REMARKS: We update our statistics for total and unchecked items.
+    state.stats.total += 1;
+    state.stats.unchecked += 1;
+
+    // REMARKS: We push the new to-do item into the items array.
+    // The data for the new item comes from the operation's input.
+    state.items.push({
+      id: action.input.id,
+      text: action.input.text,
+      checked: false, // New items always start as unchecked.
+    });
+  },
+
+  // REMARKS: The updateTodoItemOperation modifies an existing to-do item.
+  // It handles partial updates for text and checked status.
+  updateTodoItemOperation(state, action, dispatch) {
+    // REMARKS: First, we find the specific item we want to update using its ID.
+    const item = state.items.find((item) => item.id === action.input.id);
+
+    // REMARKS: It's good practice to handle cases where the item might not be found.
+    if (!item) {
+      throw new Error(`Item with id ${action.input.id} not found`);
+    }
+
+    // REMARKS: We only update the text if it was provided in the input.
+    // This allows for partial updates (e.g., just checking an item without changing its text).
+    if (action.input.text) {
+      item.text = action.input.text;
+    }
+
+    // REMARKS: When the checked status changes, we also update our statistics.
+    // We check for `true` and `false` explicitly.
+    if (action.input.checked) {
+      // This is true only if action.input.checked is true
+      // Note: This assumes the item was previously unchecked. For a more robust implementation,
+      // you could check `if (item.checked === false)` before updating stats to prevent inconsistencies.
+      state.stats.unchecked -= 1;
+      state.stats.checked += 1;
+      item.checked = action.input.checked;
+    }
+    if (action.input.checked === false) {
+      // Note: This assumes the item was previously checked.
+      state.stats.unchecked += 1;
+      state.stats.checked -= 1;
+      item.checked = action.input.checked;
+    }
+  },
+
+  // REMARKS: The deleteTodoItemOperation removes an item from the list.
+  deleteTodoItemOperation(state, action, dispatch) {
+    // REMARKS: Before removing the item, we find it to determine its checked status.
+    // This is necessary to correctly decrement our statistics.
+    const item = state.items.find((item) => item.id === action.input.id);
+
+    // REMARKS: We always decrement the total count.
+    state.stats.total -= 1;
+
+    // REMARKS: We then decrement the 'checked' or 'unchecked' count based on the item's status.
+    if (item?.checked) {
+      // This is shorthand for item?.checked === true
+      state.stats.checked -= 1;
+    }
+    if (item?.checked === false) {
+      state.stats.unchecked -= 1;
+    }
+
+    // REMARKS: Finally, we create a new 'items' array that excludes the deleted item.
+    // Assigning to 'state.items' is handled by Powerhouse to produce a new immutable state.
+    state.items = state.items.filter((item) => item.id !== action.input.id);
+  },
 };
 ```
 
@@ -337,8 +355,9 @@ export const reducer: ToDoListToDoListOperations = {
 Every time a reducer processes an operation and returns a new state, Powerhouse records the original operation (the "event") in an append-only log associated with the document instance. The current state of the document is effectively a "fold" or "reduction" of all past events, applied sequentially by the reducers.
 
 This is why purity and immutability are so critical:
-*   **Purity** ensures that replaying the same sequence of events will always yield the exact same final state.
-*   **Immutability** ensures that each event clearly defines a discrete state transition, making it easy to audit changes and understand the document's history.
+
+- **Purity** ensures that replaying the same sequence of events will always yield the exact same final state.
+- **Immutability** ensures that each event clearly defines a discrete state transition, making it easy to audit changes and understand the document's history.
 
 ## Conclusion
 

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/06-ImplementDocumentModelTests.md

@@ -22,77 +22,85 @@ With the reducer logic in place, it's critical to test it. Navigate to the gener
 This suite tests each operation, verifying not only that the `items` array is correct, but also that our `stats` object is updated as expected and that the operation itself is recorded properly in the document's history.
 
 ```typescript
-import utils from '../../gen/utils.js';
-import { reducer } from '../../gen/reducer.js';
-import * as creators from '../../gen/creators.js';
-import { ToDoListDocument } from '../../gen/types.js';
-
-describe('Todolist Operations', () => {
-    let document: ToDoListDocument;
-
-    beforeEach(() => {
-        // REMARKS: We start with a fresh, empty document for each test.
-        // The `createDocument` utility initializes the state with an empty 'items' array
-        // and a 'stats' object with all counts set to 0.
-        document = utils.createDocument();
-    });
-
-    it('should handle addTodoItem operation', () => {
-        const input = { id: '1', text: 'Buy milk' };
-        
-        // REMARKS: We apply the 'addTodoItem' operation.
-        const updatedDocument = reducer(document, creators.addTodoItem(input));
-
-        // REMARKS: We verify the operation was recorded in the document's history.
-        // Powerhouse records every operation in an array.
-        expect(updatedDocument.operations.global).toHaveLength(1);
-        expect(updatedDocument.operations.global[0].type).toBe('ADD_TODO_ITEM');
-        // REMARKS: We also check that the input data and index are recorded correctly.
-        expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
-        expect(updatedDocument.operations.global[0].index).toEqual(0);
-
-        // REMARKS: Finally, we verify the state was updated according to our reducer logic.
-        expect(updatedDocument.state.global.items).toHaveLength(1);
-        expect(updatedDocument.state.global.stats.total).toBe(1);
-        expect(updatedDocument.state.global.stats.unchecked).toBe(1);
-    });
-
-    it('should handle updateTodoItem operation', () => {
-        // REMARKS: For an update, we first need to add an item.
-        const addInput = { id: '1', text: 'Buy milk' };
-        const updateInput = { id: '1', checked: true }; // We'll test checking the item.
-
-        // REMARKS: Operations are applied sequentially to build up document state.
-        const createdDocument = reducer(document, creators.addTodoItem(addInput));
-        const updatedDocument = reducer(createdDocument, creators.updateTodoItem(updateInput));
-
-        // REMARKS: Now we should have 2 operations in the history.
-        expect(updatedDocument.operations.global).toHaveLength(2);
-        expect(updatedDocument.operations.global[1].type).toBe('UPDATE_TODO_ITEM');
-        expect(updatedDocument.operations.global[1].input).toStrictEqual(updateInput);
-        
-        // REMARKS: We check that the state reflects the update, including our stats.
-        expect(updatedDocument.state.global.items[0].checked).toBe(true);
-        expect(updatedDocument.state.global.stats.total).toBe(1);
-        expect(updatedDocument.state.global.stats.unchecked).toBe(0);
-        expect(updatedDocument.state.global.stats.checked).toBe(1);
-    });
-
-    it('should handle deleteTodoItem operation', () => {
-        const addInput = { id: '1', text: 'Buy milk' };
-        const deleteInput = { id: '1' };
-
-        const createdDocument = reducer(document, creators.addTodoItem(addInput));
-        const updatedDocument = reducer(createdDocument, creators.deleteTodoItem(deleteInput));
-
-        // REMARKS: After deletion, we still have 2 operations in history,
-        // but the items array is now empty and the stats are back to zero.
-        expect(updatedDocument.operations.global).toHaveLength(2);
-        expect(updatedDocument.operations.global[1].type).toBe('DELETE_TODO_ITEM');
-        expect(updatedDocument.state.global.items).toHaveLength(0);
-        expect(updatedDocument.state.global.stats.total).toBe(0);
-        expect(updatedDocument.state.global.stats.unchecked).toBe(0);
-    });
+import utils from "../../gen/utils.js";
+import { reducer } from "../../gen/reducer.js";
+import * as creators from "../../gen/creators.js";
+import { ToDoListDocument } from "../../gen/types.js";
+
+describe("Todolist Operations", () => {
+  let document: ToDoListDocument;
+
+  beforeEach(() => {
+    // REMARKS: We start with a fresh, empty document for each test.
+    // The `createDocument` utility initializes the state with an empty 'items' array
+    // and a 'stats' object with all counts set to 0.
+    document = utils.createDocument();
+  });
+
+  it("should handle addTodoItem operation", () => {
+    const input = { id: "1", text: "Buy milk" };
+
+    // REMARKS: We apply the 'addTodoItem' operation.
+    const updatedDocument = reducer(document, creators.addTodoItem(input));
+
+    // REMARKS: We verify the operation was recorded in the document's history.
+    // Powerhouse records every operation in an array.
+    expect(updatedDocument.operations.global).toHaveLength(1);
+    expect(updatedDocument.operations.global[0].type).toBe("ADD_TODO_ITEM");
+    // REMARKS: We also check that the input data and index are recorded correctly.
+    expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[0].index).toEqual(0);
+
+    // REMARKS: Finally, we verify the state was updated according to our reducer logic.
+    expect(updatedDocument.state.global.items).toHaveLength(1);
+    expect(updatedDocument.state.global.stats.total).toBe(1);
+    expect(updatedDocument.state.global.stats.unchecked).toBe(1);
+  });
+
+  it("should handle updateTodoItem operation", () => {
+    // REMARKS: For an update, we first need to add an item.
+    const addInput = { id: "1", text: "Buy milk" };
+    const updateInput = { id: "1", checked: true }; // We'll test checking the item.
+
+    // REMARKS: Operations are applied sequentially to build up document state.
+    const createdDocument = reducer(document, creators.addTodoItem(addInput));
+    const updatedDocument = reducer(
+      createdDocument,
+      creators.updateTodoItem(updateInput),
+    );
+
+    // REMARKS: Now we should have 2 operations in the history.
+    expect(updatedDocument.operations.global).toHaveLength(2);
+    expect(updatedDocument.operations.global[1].type).toBe("UPDATE_TODO_ITEM");
+    expect(updatedDocument.operations.global[1].input).toStrictEqual(
+      updateInput,
+    );
+
+    // REMARKS: We check that the state reflects the update, including our stats.
+    expect(updatedDocument.state.global.items[0].checked).toBe(true);
+    expect(updatedDocument.state.global.stats.total).toBe(1);
+    expect(updatedDocument.state.global.stats.unchecked).toBe(0);
+    expect(updatedDocument.state.global.stats.checked).toBe(1);
+  });
+
+  it("should handle deleteTodoItem operation", () => {
+    const addInput = { id: "1", text: "Buy milk" };
+    const deleteInput = { id: "1" };
+
+    const createdDocument = reducer(document, creators.addTodoItem(addInput));
+    const updatedDocument = reducer(
+      createdDocument,
+      creators.deleteTodoItem(deleteInput),
+    );
+
+    // REMARKS: After deletion, we still have 2 operations in history,
+    // but the items array is now empty and the stats are back to zero.
+    expect(updatedDocument.operations.global).toHaveLength(2);
+    expect(updatedDocument.operations.global[1].type).toBe("DELETE_TODO_ITEM");
+    expect(updatedDocument.state.global.items).toHaveLength(0);
+    expect(updatedDocument.state.global.stats.total).toBe(0);
+    expect(updatedDocument.state.global.stats.unchecked).toBe(0);
+  });
 });
 ```
 
@@ -112,28 +120,29 @@ If all tests pass, you have successfully verified the core logic of your `To-do
 
 While the tutorial provides a concrete example, keep these general best practices in mind when writing your tests:
 
-*   **Isolate Tests**: Each `it` block should ideally test one specific aspect or scenario. `beforeEach` is crucial for resetting state between tests.
-*   **Descriptive Names**: Name your `describe` and `it` blocks clearly so they explain what's being tested.
-*   **AAA Pattern (Arrange, Act, Assert)**:
-    *   **Arrange**: Set up the initial state and any required test data (e.g., using `utils.createDocument()` and defining `input` objects).
-    *   **Act**: Execute the operation by calling the `reducer` with an action from a `creator`.
-    *   **Assert**: Check if the outcome is as expected using `expect()`.
-*   **Test Immutability**: A key assertion is to ensure the state is not mutated directly. You can check that a new array or object was created: `expect(newState.items).not.toBe(oldState.items);`.
-*   **Cover Edge Cases**: Test what happens when an operation receives invalid input (e.g., trying to update an item that doesn't exist). Your test should confirm the reducer either throws an error or returns the state unchanged, depending on your implementation.
-*   **Run Tests Frequently**: Integrate testing into your development workflow. Run tests after making changes to ensure you haven't broken anything. The `pnpm run test` command is your friend.
+- **Isolate Tests**: Each `it` block should ideally test one specific aspect or scenario. `beforeEach` is crucial for resetting state between tests.
+- **Descriptive Names**: Name your `describe` and `it` blocks clearly so they explain what's being tested.
+- **AAA Pattern (Arrange, Act, Assert)**:
+  - **Arrange**: Set up the initial state and any required test data (e.g., using `utils.createDocument()` and defining `input` objects).
+  - **Act**: Execute the operation by calling the `reducer` with an action from a `creator`.
+  - **Assert**: Check if the outcome is as expected using `expect()`.
+- **Test Immutability**: A key assertion is to ensure the state is not mutated directly. You can check that a new array or object was created: `expect(newState.items).not.toBe(oldState.items);`.
+- **Cover Edge Cases**: Test what happens when an operation receives invalid input (e.g., trying to update an item that doesn't exist). Your test should confirm the reducer either throws an error or returns the state unchanged, depending on your implementation.
+- **Run Tests Frequently**: Integrate testing into your development workflow. Run tests after making changes to ensure you haven't broken anything. The `pnpm run test` command is your friend.
 
 ## Conclusion: The payoff of diligent testing
 
 Implementing comprehensive tests for your document model reducers is an investment that pays dividends in the long run. It leads to:
 
-*   **Higher Quality Models**: More reliable and robust document models with fewer bugs.
-*   **Increased Confidence**: Ability to make changes and refactor code without fear of breaking existing functionality.
-*   **Easier Debugging**: When tests fail, they pinpoint the exact operation and scenario that's problematic.
-*   **Better Collaboration**: Tests clarify the intended behavior of the document model for all team members.
+- **Higher Quality Models**: More reliable and robust document models with fewer bugs.
+- **Increased Confidence**: Ability to make changes and refactor code without fear of breaking existing functionality.
+- **Easier Debugging**: When tests fail, they pinpoint the exact operation and scenario that's problematic.
+- **Better Collaboration**: Tests clarify the intended behavior of the document model for all team members.
 
 By following the tutorial and applying these best practices, you can build a strong suite of tests that safeguard the integrity and functionality of your document models. This diligence is a hallmark of a "Mastery Track" developer, ensuring that the solutions you build are not just functional but also stable, maintainable, and trustworthy.
 
 ## Up next
-In the next chapter of the Mastery Track - Building User Experiences you will learn how to implement an [editor](/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors) for your document model so you can see a simple user interface for the **To-do List** document model in action. 
 
-For a complete, working example, you can always have a look at the [Example To-do List Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.
+In the next chapter of the Mastery Track - Building User Experiences you will learn how to implement an [editor](/academy/MasteryTrack/BuildingUserExperiences/BuildingDocumentEditors) for your document model so you can see a simple user interface for the **To-do List** document model in action.
+
+For a complete, working example, you can always have a look at the [Example To-do List Repository](/academy/MasteryTrack/DocumentModelCreation/ExampleToDoListRepository) which contains the full implementation of the concepts discussed in this Mastery Track.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/07-ExampleToDoListRepository.md

@@ -16,12 +16,13 @@ Follow the steps in the "Mastery Track – Document Model Creation" chapters to
 
 ### Option 2: Clone and run the code locally
 
-The package includes:  
-- The Document Model  
-- Reducer Code  
-- Reducer Tests  
-- Editor Code  
-- Drive Explorer Code  
+The package includes:
+
+- The Document Model
+- Reducer Code
+- Reducer Tests
+- Editor Code
+- Drive Explorer Code
 
 You can clone the repository and run Connect Studio to see all the code in action:
 
@@ -36,6 +37,3 @@ Alternatively, you can install this package in a Powerhouse project or in your d
 ```bash
 ph install @powerhousedao/todo-demo-package
 ```
-
-
-

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/_category_.json

@@ -1,7 +1,7 @@
 {
-    "label": "Document Model Creation",
-    "link": {
-      "type": "doc",
-      "id": "academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel"
-    }
-  }
+  "label": "Document Model Creation",
+  "link": {
+    "type": "doc",
+    "id": "academy/MasteryTrack/DocumentModelCreation/WhatIsADocumentModel"
+  }
+}