@powerhousedao/academy 5.1.0-staging.0 → 5.1.0

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

@@ -10,9 +10,9 @@ Reducers are the core logic units of your document model. They are the functions
 
 Before diving into the specifics of writing reducers, let's recall the preceding steps:
 
-1.  **State Schema Definition**: You designed the GraphQL `type` definitions for your document's data structure (e.g., `TodoListState`, `TodoItem`).
+1.  **State Schema Definition**: You designed the GraphQL `type` definitions for your document's data structure (e.g., `ToDoListState`, `ToDoItem`).
 2.  **Document Operation Specification**: You defined the GraphQL `input` types that specify the parameters for each allowed modification to your document (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`). These were then associated with named operations (e.g., `ADD_TODO_ITEM`) in the Connect application.
-3.  **Code Generation**: You used `ph generate <YourModelName.phd>` to create the necessary TypeScript types, action creators, and, crucially, the skeleton file for your reducers (typically `document-models/<your-model-name>/src/reducers/todos.ts`).
+3.  **Code Generation**: You used `ph generate <YourModelName.phdm.zip>` to create the necessary TypeScript types, action creators, and, crucially, the skeleton file for your reducers (typically `document-models/<YourModelName>/src/reducers/<your-model-name>.ts`).
 
 This generated reducer file is our starting point. It will contain function stubs or an object structure expecting your reducer implementations, all typed according to your schema.
 
@@ -27,7 +27,7 @@ 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., `{ text: 'Buy groceries' }` for `AddTodoItemInput`).
+  - 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:
@@ -39,211 +39,204 @@ Let's break down its components and principles:
 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.
-    
-    :::tip Powerhouse uses Immer.js
-    Powerhouse uses **Immer.js** under the hood, which means you can write code that _looks like_ it's mutating the state directly (e.g., `state.items.push(...)`), but Immer ensures it results in an immutable update. This gives you the best of both worlds: readable code and immutable state.
-    :::
+    - 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.
 
 4.  **Delegation to specific operation handlers**:
-    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/todo-list/src/reducers/todos.ts`, you'll find an object structure like this:
+    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 type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
+    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 todoListTodosOperations: TodoListTodosOperations = {
-      addTodoItemOperation(state, action) {
+    export const reducer: ToDoListToDoListOperations = {
+      addTodoItemOperation(state: ToDoListState, action, dispatch) {
         // Your logic for ADD_TODO_ITEM
+        // ...
+        return newState;
       },
-      updateTodoItemOperation(state, action) {
+      updateTodoItemOperation(state: ToDoListState, action, dispatch) {
         // Your logic for UPDATE_TODO_ITEM
+        // ...
+        return newState;
       },
-      deleteTodoItemOperation(state, action) {
+      deleteTodoItemOperation(state: ToDoListState, action, dispatch) {
         // Your logic for DELETE_TODO_ITEM
+        // ...
+        return newState;
       },
+      // ... other operations
     };
     ```
 
-    The `TodoListTodosOperations` type 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 `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.
 
-## Implementing reducer logic: A practical guide
+    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.
 
-Let's use our familiar `TodoList` example to illustrate common patterns. 
+## Implementing reducer logic: A practical guide
 
-### Basic implementation (matching Get Started)
+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.
 
-The basic implementation matches what you built in the Get Started tutorial:
+Our `ToDoListState` now looks like this:
 
 ```typescript
-import { generateId } from "document-model/core";
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-
-export const todoListTodosOperations: TodoListTodosOperations = {
-  addTodoItemOperation(state, action) {
-    // Generate a unique ID for the new todo item
-    const id = generateId();
-    
-    // Add the new item to the state (Immer handles immutability)
-    state.items.push({ ...action.input, id, checked: false });
-  },
-  
-  updateTodoItemOperation(state, action) {
-    // Find the item to update by its ID
-    const item = state.items.find((item) => item.id === action.input.id);
-    
-    // Return early if item not found
-    if (!item) return;
-    
-    // Update only the fields that are provided (partial update)
-    item.text = action.input.text ?? item.text;
-    item.checked = action.input.checked ?? item.checked;
-  },
-  
-  deleteTodoItemOperation(state, action) {
-    // Filter out the item with the matching ID
-    state.items = state.items.filter((item) => item.id !== action.input.id);
-  },
-};
-```
-
-:::info Key Pattern: ID Generation
-Notice that `addTodoItemOperation` uses `generateId()` from `document-model/core` to create a unique ID. This is the recommended pattern — the ID is generated in the reducer, not passed from the UI. This ensures consistent, unique IDs across all operations.
-:::
-
-### Advanced implementation (with statistics tracking)
-
-:::info Advanced Feature
-This section extends the basic reducers with statistics tracking, matching the advanced schema from the previous section. This demonstrates how to update computed/derived state alongside your primary data.
-:::
-
-For the advanced version with `stats`, we need to update the statistics whenever items are added, updated, or deleted:
+interface ToDoItem {
+  id: string;
+  text: string;
+  checked: boolean;
+}
 
-```typescript
-import { generateId } from "document-model/core";
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-
-export const todoListTodosOperations: TodoListTodosOperations = {
-  addTodoItemOperation(state, action) {
-    // Generate a unique ID for the new todo item
-    const id = generateId();
-    
-    // Update statistics
-    state.stats.total += 1;
-    state.stats.unchecked += 1;
+interface ToDoListStats {
+  total: number;
+  checked: number;
+  unchecked: number;
+}
 
-    // Add the new item to the state
-    state.items.push({
-      id,
-      text: action.input.text,
-      checked: false, // New items always start as unchecked
-    });
-  },
+interface ToDoListState {
+  items: ToDoItem[];
+  stats: ToDoListStats;
+}
+```
 
-  updateTodoItemOperation(state, action) {
-    // Find the specific item we want to update
-    const item = state.items.find((item) => item.id === action.input.id);
+And our action creators (from `../../gen/creators` or `../../gen/operations.js`) provide actions like:
 
-    if (!item) {
-      throw new Error(`Item with id ${action.input.id} not found`);
-    }
+- `actions.addTodoItem({ id: 'some-id', text: 'New Task' })`
+- `actions.updateTodoItem({ id: 'item-id', text: 'Updated Task Text', checked: true })`
+- `actions.deleteTodoItem({ id: 'item-id' })`
 
-    // Update text if provided
-    if (action.input.text !== undefined) {
-      item.text = action.input.text;
-    }
+### 1. Adding an item (e.g., `addTodoItemOperation`)
 
-    // Handle checked status changes and update stats
-    if (action.input.checked !== undefined && action.input.checked !== item.checked) {
-      if (action.input.checked) {
-        state.stats.unchecked -= 1;
-        state.stats.checked += 1;
-      } else {
-        state.stats.unchecked += 1;
-        state.stats.checked -= 1;
-      }
-      item.checked = action.input.checked;
-    }
-  },
+To add a new item to the `items` array immutably:
 
-  deleteTodoItemOperation(state, action) {
-    // Find the item to determine its checked status for stats
-    const item = state.items.find((item) => item.id === action.input.id);
+```typescript
+addTodoItemOperation(state: ToDoListState, action: /* AddTodoItemActionType */ any, dispatch) {
+  const newItem: ToDoItem = {
+    id: action.input.id,
+    text: action.input.text,
+    checked: false, // New items default to unchecked
+  };
+
+  // Return a new state object
+  return {
+    ...state, // Copy all existing properties from the current state
+    items: [...state.items, newItem], // Create a new items array: spread existing items, add the new one
+  };
+}
+```
 
-    if (item) {
-      // Update statistics
-      state.stats.total -= 1;
-      if (item.checked) {
-        state.stats.checked -= 1;
-      } else {
-        state.stats.unchecked -= 1;
-      }
-    }
+**Explanation**:
 
-    // Remove the item from the list
-    state.items = state.items.filter((item) => item.id !== action.input.id);
-  },
-};
-```
+- 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`.
 
-### Common patterns explained
+### 2. Updating an item (e.g., `updateTodoItemOperation`)
 
-#### 1. Adding an item
+To update an existing item in the `items` array immutably:
 
 ```typescript
-addTodoItemOperation(state, action) {
-  const id = generateId();  // Generate unique ID
-  state.items.push({ ...action.input, id, checked: false });
+updateTodoItemOperation(state: ToDoListState, action: /* UpdateTodoItemActionType */ any, dispatch) {
+  const { id, text, checked } = action.input;
+
+  // Return a new state object
+  return {
+    ...state,
+    items: state.items.map(item => {
+      if (item.id === id) {
+        // This is the item to update. Return a *new* item object.
+        return {
+          ...item, // Copy existing properties of the item
+          // Update only fields that are provided in the action input
+          ...(text !== undefined && { text: text }),
+          ...(checked !== undefined && { checked: checked }),
+        };
+      }
+      // This is not the item we're looking for, return it unchanged.
+      return item;
+    }),
+  };
 }
 ```
 
-- We use `generateId()` to create a unique identifier
-- We spread `action.input` to get the text, add the generated ID and default `checked: false`
-- With Immer, this "mutation" is actually immutable
+**Explanation**:
 
-#### 2. Updating an item
+- 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
-updateTodoItemOperation(state, action) {
-  const item = state.items.find((item) => item.id === action.input.id);
-  if (!item) return;
-  
-  item.text = action.input.text ?? item.text;
-  item.checked = action.input.checked ?? item.checked;
+// Inside updateTodoItemOperation, before returning:
+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.`);
+  // Option 2: Return current state (no change)
+  // return state;
 }
+// ... proceed with map
 ```
 
-- We find the item by ID
-- We use nullish coalescing (`??`) to only update fields that were provided
-- This allows partial updates (e.g., just changing `checked` without touching `text`)
+### 3. Deleting an item (e.g., `deleteTodoItemOperation`)
 
-#### 3. Deleting an item
+To remove an item from the `items` array immutably:
 
 ```typescript
-deleteTodoItemOperation(state, action) {
-  state.items = state.items.filter((item) => item.id !== action.input.id);
+deleteTodoItemOperation(state: ToDoListState, action: /* DeleteTodoItemActionType */ any, dispatch) {
+  const { id } = action.input;
+
+  // Return a new state object
+  return {
+    ...state,
+    items: state.items.filter(item => item.id !== id), // Create a new array excluding the item to delete
+  };
 }
 ```
 
-- We use `filter` to create a new array without the deleted item
-- Immer handles making this immutable
+**Explanation**:
+
+- 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
 
-As highlighted in [Using the Document Model Generator](04-UseTheDocumentModelGenerator.md), `ph generate` produces TypeScript types for your state (e.g., `TodoListState`, `TodoItem`) and the inputs for your operations (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`).
+As highlighted in [Using the Document Model Generator](04-UseTheDocumentModelGenerator.md), `ph generate` produces TypeScript types for your state (e.g., `ToDoListState`, `ToDoItem`) and the inputs for your operations (e.g., `AddTodoItemInput`, `UpdateTodoItemInput`).
 
 **Always use these generated types in your reducer implementations!**
 
 ```typescript
-import { generateId } from "document-model/core";
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-
-export const todoListTodosOperations: TodoListTodosOperations = {
-  addTodoItemOperation(state, action) {
-    // TypeScript knows action.input has { text: string }
-    const id = generateId();
-    state.items.push({ id, text: action.input.text, checked: false });
+import {
+  ToDoListState,
+  AddTodoItemInput, // Generated input type
+  // ... other types
+} 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.
+// For example:
+// interface AddTodoItemAction {
+//   type: 'ADD_TODO_ITEM'; // Or the specific string constant used by the action creator
+//   input: AddTodoItemInput;
+// }
+
+export const reducer: ToDoListToDoListOperations = {
+  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,
+      text: action.input.text,
+      checked: false,
+    };
+    return {
+      ...state,
+      items: [...state.items, newItem],
+    };
   },
   // ... other reducers
 };
@@ -255,99 +248,101 @@ Using these types provides:
 - **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
+## Practical implementation: Writing the `ToDoList` reducers
 
-Now that you understand the principles, let's put them into practice by implementing the reducers for our `TodoList` document model.
+Now that you understand the principles, let's put them into practice by implementing the reducers for our `ToDoList` document model.
 
 <details>
-<summary>Tutorial: Implementing the TodoList reducers</summary>
+<summary>Tutorial: Implementing the ToDoList reducers</summary>
 
-This tutorial assumes you have followed the steps in the previous chapters, especially using `ph generate TodoList.phd` to scaffold your document model's code.
+This tutorial assumes you have followed the steps in the previous chapters, especially using `ph generate ToDoList.phdm.zip` to scaffold your document model's code.
 
 ### Implement the operation reducers
 
-Navigate to `document-models/todo-list/src/reducers/todos.ts`. The generator will have created a skeleton file. Replace its contents with the following logic.
-
-**Basic version (without stats):**
-
-```typescript
-import { generateId } from "document-model/core";
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-
-export const todoListTodosOperations: TodoListTodosOperations = {
-  addTodoItemOperation(state, action) {
-    const id = generateId();
-    state.items.push({ ...action.input, id, checked: false });
-  },
-  
-  updateTodoItemOperation(state, action) {
-    const item = state.items.find((item) => item.id === action.input.id);
-    if (!item) return;
-    
-    item.text = action.input.text ?? item.text;
-    item.checked = action.input.checked ?? item.checked;
-  },
-  
-  deleteTodoItemOperation(state, action) {
-    state.items = state.items.filter((item) => item.id !== action.input.id);
-  },
-};
-```
-
-**Advanced version (with stats):**
+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 { generateId } from "document-model/core";
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-
-export const todoListTodosOperations: TodoListTodosOperations = {
-  addTodoItemOperation(state, action) {
-    const id = generateId();
-    
+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,
+      id: action.input.id,
       text: action.input.text,
-      checked: false,
+      checked: false, // New items always start as unchecked.
     });
   },
 
-  updateTodoItemOperation(state, action) {
+  // 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`);
     }
 
-    if (action.input.text !== undefined) {
+    // 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;
     }
 
-    if (action.input.checked !== undefined && action.input.checked !== item.checked) {
-      if (action.input.checked) {
-        state.stats.unchecked -= 1;
-        state.stats.checked += 1;
-      } else {
-        state.stats.unchecked += 1;
-        state.stats.checked -= 1;
-      }
+    // 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;
     }
   },
 
-  deleteTodoItemOperation(state, action) {
+  // 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);
 
-    if (item) {
-      state.stats.total -= 1;
-      if (item.checked) {
-        state.stats.checked -= 1;
-      } else {
-        state.stats.unchecked -= 1;
-      }
+    // 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);
   },
 };