@powerhousedao/academy 5.1.0-dev.0 → 5.1.0-dev.10

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.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`).
+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`).
 
 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., `{ id: '1', 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., `{ 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,204 +39,211 @@ 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. We'll explore techniques for immutability shortly.
+    - 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.
+    :::
 
 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/to-do-list/src/reducers/to-do-list.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/todo-list/src/reducers/todos.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 type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
 
-    export const reducer: ToDoListToDoListOperations = {
-      addTodoItemOperation(state: ToDoListState, action, dispatch) {
+    export const todoListTodosOperations: TodoListTodosOperations = {
+      addTodoItemOperation(state, action) {
         // Your logic for ADD_TODO_ITEM
-        // ...
-        return newState;
       },
-      updateTodoItemOperation(state: ToDoListState, action, dispatch) {
+      updateTodoItemOperation(state, action) {
         // Your logic for UPDATE_TODO_ITEM
-        // ...
-        return newState;
       },
-      deleteTodoItemOperation(state: ToDoListState, action, dispatch) {
+      deleteTodoItemOperation(state, action) {
         // Your logic for DELETE_TODO_ITEM
-        // ...
-        return newState;
       },
-      // ... 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.
+    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.
 
 ## Implementing reducer logic: A practical guide
 
-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.
+Let's use our familiar `TodoList` example to illustrate common patterns. 
 
-Our `ToDoListState` now looks like this:
+### Basic implementation (matching Get Started)
 
-```typescript
-interface ToDoItem {
-  id: string;
-  text: string;
-  checked: boolean;
-}
-
-interface ToDoListStats {
-  total: number;
-  checked: number;
-  unchecked: number;
-}
+The basic implementation matches what you built in the Get Started tutorial:
 
-interface ToDoListState {
-  items: ToDoItem[];
-  stats: ToDoListStats;
-}
+```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);
+  },
+};
 ```
 
-And our action creators (from `../../gen/creators` or `../../gen/operations.js`) provide actions like:
+:::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.
+:::
 
-- `actions.addTodoItem({ id: 'some-id', text: 'New Task' })`
-- `actions.updateTodoItem({ id: 'item-id', text: 'Updated Task Text', checked: true })`
-- `actions.deleteTodoItem({ id: 'item-id' })`
+### Advanced implementation (with statistics tracking)
 
-### 1. Adding an item (e.g., `addTodoItemOperation`)
+:::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.
+:::
 
-To add a new item to the `items` array immutably:
+For the advanced version with `stats`, we need to update the statistics whenever items are added, updated, or deleted:
 
 ```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
-  };
-}
-```
+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;
 
-**Explanation**:
+    // Add the new item to the state
+    state.items.push({
+      id,
+      text: action.input.text,
+      checked: false, // New items always start as unchecked
+    });
+  },
 
-- 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`.
+  updateTodoItemOperation(state, action) {
+    // Find the specific item we want to update
+    const item = state.items.find((item) => item.id === action.input.id);
 
-### 2. Updating an item (e.g., `updateTodoItemOperation`)
+    if (!item) {
+      throw new Error(`Item with id ${action.input.id} not found`);
+    }
 
-To update an existing item in the `items` array immutably:
+    // Update text if provided
+    if (action.input.text !== undefined) {
+      item.text = action.input.text;
+    }
 
-```typescript
-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 }),
-        };
+    // 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;
       }
-      // This is not the item we're looking for, return it unchanged.
-      return item;
-    }),
-  };
-}
-```
+      item.checked = action.input.checked;
+    }
+  },
+
+  deleteTodoItemOperation(state, action) {
+    // Find the item to determine its checked status for stats
+    const item = state.items.find((item) => item.id === action.input.id);
+
+    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 `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.
+### Common patterns explained
 
-**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:
+#### 1. Adding an item
 
 ```typescript
-// 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;
+addTodoItemOperation(state, action) {
+  const id = generateId();  // Generate unique ID
+  state.items.push({ ...action.input, id, checked: false });
 }
-// ... proceed with map
 ```
 
-### 3. Deleting an item (e.g., `deleteTodoItemOperation`)
+- 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
 
-To remove an item from the `items` array immutably:
+#### 2. Updating an item
 
 ```typescript
-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
-  };
+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;
 }
 ```
 
-**Explanation**:
+- 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
+
+```typescript
+deleteTodoItemOperation(state, action) {
+  state.items = state.items.filter((item) => item.id !== action.input.id);
+}
+```
 
-- We use the `filter` array method, which returns a _new_ array containing only the elements for which the callback function returns `true`.
+- We use `filter` to create a new array without the deleted item
+- Immer handles making this immutable
 
 ## 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 {
-  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],
-    };
+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 });
   },
   // ... other reducers
 };
@@ -248,101 +255,99 @@ 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.phdm.zip` to scaffold your document model's code.
+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.
 
 ### Implement the operation reducers
 
-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.
+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):**
 
 ```typescript
-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.
+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.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,
+      id,
       text: action.input.text,
-      checked: false, // New items always start as unchecked.
+      checked: false,
     });
   },
 
-  // 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.
+  updateTodoItemOperation(state, action) {
     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) {
+    if (action.input.text !== undefined) {
       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;
+    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;
     }
   },
 
-  // 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.
+  deleteTodoItemOperation(state, action) {
     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;
+    if (item) {
+      state.stats.total -= 1;
+      if (item.checked) {
+        state.stats.checked -= 1;
+      } else {
+        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);
   },
 };