@powerhousedao/academy 2.5.0-dev.3 → 2.5.0-dev.30

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/02-SpecifyTheStateSchema.md

@@ -21,6 +21,8 @@ GraphQL has a set of built-in **scalar types**:
 *   `Boolean`: `true` or `false`.
 *   `ID`: A unique identifier, often used as a key for a field. It is serialized in the same way as a String; however, it is not intended to be human-readable.
 
+In addition to these standard types, the Powerhouse Document-Engineering system introduces custom scalars that are linked to reusable front-end components. These scalars are tailored for the web3 ecosystem and will be explored in the Component Library section of the documentation.
+
 ### Lists and Non-Null
 You can modify types using lists and non-null indicators:
 *   **Lists**: To indicate that a field will return a list of a certain type, you wrap the type in square brackets, e.g., `[ToDoItem!]!`. This means the field `items` in `ToDoListState` will be a list of `ToDoItem` objects.
@@ -29,6 +31,7 @@ You can modify types using lists and non-null indicators:
 ## Example: ToDoList State Schema
 
 Let's revisit the `ToDoList` example from the "Define the ToDoList document specification" tutorial.
+Only this time, we'll also add a 'Stats' type. Since we want to keep track of the number of completed To-Do's.
 
 ```graphql
 # The state of our ToDoList
@@ -42,6 +45,12 @@ type ToDoItem {
   text: String!
   checked: Boolean!
 }
+# The statistics on our to-do's
+type ToDoListStats {
+  total: Int!
+  checked: Int!
+  unchecked: Int!
+}
 ```
 
 ### Breakdown:
@@ -57,6 +66,11 @@ type ToDoItem {
     *   `text: String!`: The textual description of the to-do item. It cannot be null, ensuring every to-do has a description.
     *   `checked: Boolean!`: Indicates whether the to-do item is completed. It defaults to a boolean value (true or false) and cannot be null.
 
+*   **`ToDoListStats` type**: This type holds the summary statistics for the to-do list.
+    *   `total: Int!`: The total count of all to-do items. This field must be an integer and cannot be null.
+    *   `checked: Int!`: The number of to-do items that are marked as completed. This must be an integer and cannot be null.
+    *   `unchecked: Int!`: The number of to-do items that are still pending. This also must be an integer and cannot be null.
+
 ## Best Practices for Designing Your State Schema
 
 1.  **Start Simple, Iterate**: Begin with the core entities and properties. You can always expand and refine your schema as your understanding of the document's requirements grows.
@@ -70,3 +84,62 @@ type ToDoItem {
 6.  **Root State Type**: It's a common pattern to have a single root type for your document state (e.g., `ToDoListState`). This provides a clear entry point for accessing all document data.
 
 By carefully defining your state schema, you lay a solid foundation for your Powerhouse document model, making it robust, maintainable, and easy to work with. The schema dictates not only how data is stored but also how it can be queried and mutated through operations, which will be covered in the next section.
+
+## Practical Implementation: Defining the State Schema in Connect
+
+Now that you understand the concepts behind the state schema, let's put it into practice. This section will guide you through creating a document model specification for the advanced ToDoList example discussed above.
+
+<details>
+<summary>Tutorial: The State Schema Specification</summary> 
+
+### Prerequisites
+
+-   You have a Powerhouse project set up. If not, please follow the [Create a new Powerhouse Project](../../GetStarted/CreateNewPowerhouseProject) tutorial.
+-   Connect Studio is running. If not, navigate to your project directory in the terminal and run `ph connect`.
+
+### Steps
+
+1.  **Create a New Document Model**:
+    -   With Connect Studio open in your browser, navigate into your local drive.
+    -   At the bottom of the page in the 'New Document' section, click the `DocumentModel` button to create a new document model specification.
+
+2.  **Define Document Metadata**:
+    -   **Name**: Give your document model a descriptive name, for example, `ToDoList`. **Pay close attention to capitalization, as it influences our code.**
+    -   **Document Type**: In the 'Document Type' field, enter a unique identifier for this document type, for instance, `powerhouse/todolist`.
+
+3.  **Specify the State Schema**:
+    -   In the code editor provided, you'll see a template for a GraphQL schema.
+    -   Replace the entire content of the editor with the advanced `ToDoList` schema we've designed in this chapter:
+
+    ```graphql
+    # The state of our ToDoList
+    type ToDoListState {
+      items: [ToDoItem!]!
+    }
+
+    # A single to-do item
+    type ToDoItem {
+      id: ID!
+      text: String!
+      checked: Boolean!
+    }
+    # The statistics on our to-do's
+    type ToDoListStats {
+      total: Int!
+      checked: Int!
+      unchecked: Int!
+    }
+    ```
+
+4.  **Sync Schema and View Initial State**:
+    -   After pasting the schema, click the **'Sync with schema'** button.
+    -   This action processes your schema and generates an initial JSON state for your document model based on the `ToDoListState` type. You can view this initial state, which helps you verify that your schema is structured correctly.
+
+    For now, you can ignore the "Modules & Operations" section. We will define and implement the operations that modify this state in the upcoming sections of this Mastery Track.
+
+By completing these steps, you have successfully specified the data structure for the advanced ToDoList document model. The next step is to define the operations that will allow users to interact with and change this state.
+
+</details>
+
+For a complete, working example, you can always refer to the [Example ToDoList 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/03-SpecifyDocumentOperations.md

@@ -16,10 +16,9 @@ Each operation acts as a command that, when applied, transitions the document fr
 
 ## Connecting Operations to the Schema
 
-In the "Define ToDoList Document Model" guide, we used GraphQL `input` types to define the structure of the data required for each operation. Let's revisit that:
+In the "Define ToDoList Document Model" chapter in the "Get Started" guide, we used GraphQL `input` types to define the structure of the data required for each operation. Let's revisit that:
 
 ```graphql
-# From 02-DefineToDoListDocumentModel.md
 # Defines a GraphQL input type for adding a new to-do item
 input AddTodoItemInput {
   id: ID!
@@ -96,7 +95,6 @@ The generated code from `ph generate` (as seen in `03-ImplementOperationReducers
 For example, the `ToDoListToDoListOperations` type generated by Powerhouse will expect methods corresponding to `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`.
 
 ```typescript
-// From 03-ImplementOperationReducers.md
 import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js';
 
 export const reducer: ToDoListToDoListOperations = {
@@ -112,8 +110,65 @@ export const reducer: ToDoListToDoListOperations = {
 };
 ```
 
+## Practical Implementation: Defining Operations in Connect
+
+Now that you understand the theory, let's walk through the practical steps of defining these operations for our `ToDoList` document model within the Powerhouse Connect application.
+
+<details>
+<summary>Tutorial: Specifying ToDoList Operations</summary>
+
+Assuming you have already defined the state schema for the `ToDoList` as covered in the previous section, follow these steps to add the operations:
+
+1.  **Create a Module for Operations:**
+    Below the schema editor in Connect, find the input field labeled `Add module`. Modules help organize your operations.
+    *   Type `to_do_list` into the field and press Enter.
+
+2.  **Add the `ADD_TODO_ITEM` Operation:**
+    A new field, `Add operation`, will appear under your new module.
+    *   Type `ADD_TODO_ITEM` into this field and press Enter.
+    *   An editor will appear for the operation's input type. You need to define the data required for this operation. Paste the following GraphQL `input` definition into the editor:
+
+    ```graphql
+    # Defines a GraphQL input type for adding a new to-do item
+    input AddTodoItemInput {
+      id: ID!
+      text: String!
+    }
+    ```
+
+3.  **Add the `UPDATE_TODO_ITEM` Operation:**
+    *   In the `Add operation` field again, type `UPDATE_TODO_ITEM` and press Enter.
+    *   Paste the corresponding `input` definition into its editor:
+
+    ```graphql
+    # Defines a GraphQL input type for updating a to-do item
+    input UpdateTodoItemInput {
+      id: ID!
+      text: String
+      checked: Boolean
+    }
+    ```
+
+4.  **Add the `DELETE_TODO_ITEM` Operation:**
+    *   Finally, type `DELETE_TODO_ITEM` in the `Add operation` field and press Enter.
+    *   Paste its `input` definition:
+
+    ```graphql
+    # Defines a GraphQL input type for deleting a to-do item
+    input DeleteTodoItemInput {
+      id: ID!
+    }
+    ```
+
+5.  **Review and Export:**
+    After adding all three operations, your document model specification in Connect is complete for now. You can see how each operation (`ADD_TODO_ITEM`, etc.) is now explicitly linked to an input type that defines its payload.
+
+    The next step in a real project would be to click the `Export` button to save this specification file. In the next chapter, we will see how this exported file is used to generate code for our reducers.
+
+</details>
+
 ## Conclusion
 
-Specifying document operations is a foundational step in building robust and predictable document models in Powerhouse. By clearly defining the "what" (the operation and its input) before implementing the "how" (the reducer logic), you create a clear contract for state transitions. This approach enhances type safety, testability, and the overall maintainability of your document model.
+Specifying document operations is a foundational step in building robust and predictable document models in Powerhouse. By clearly defining the **"what" (the operation and its input)** before implementing the **"how" (the reducer logic)**, you create a clear contract for state transitions. This approach enhances type safety, testability, and the overall maintainability of your document model.
 
 In the next section, we will dive deeper into the implementation of the reducer functions for these specified operations.

package/docs/academy/02-MasteryTrack/02-DocumentModelCreation/04-UseTheDocumentModelGenerator.md

@@ -90,22 +90,42 @@ Leveraging the `ph generate` command offers numerous advantages:
 5.  **Alignment with Powerhouse Ecosystem:** The generated code is designed to integrate seamlessly with other parts of the Powerhouse ecosystem, such as the reducer execution engine and UI components.
 6.  **Single Source of Truth:** Ensures that your codebase (especially types and action creators) stays synchronized with the document model specification defined in Connect. If the specification changes, regenerating the model will update these components accordingly.
 
-## Example Workflow Snippet
+## Practical Implementation: Generating the `ToDoList` Model
 
-Let's assume you have defined a `ProjectTask` document model and exported `ProjectTask.phdm.zip`.
+Now that you understand what the Document Model Generator does, let's walk through the practical steps of using it with our `ToDoList` example.
 
-1.  **Navigate to your Powerhouse project root in the terminal.**
-2.  **Run the generator:**
+<details>
+<summary>Tutorial: Generating the ToDoList Document Model</summary>
+
+This tutorial assumes you have completed the previous steps in this Mastery Track, where you defined the state schema and operations for the `ToDoList` model in Connect and exported it.
+
+### Prerequisites
+
+*   **`ToDoList.phdm.zip` file**: You must have the document model specification file exported from Connect. If you do not have this file, please revisit the previous sections on specifying the state schema and operations.
+
+### Steps
+
+1.  **Place the Specification File in Your Project**:
+    *   Navigate to the root directory of your Powerhouse project.
+    *   Move or copy your `ToDoList.phdm.zip` file into this directory.
+
+2.  **Run the Generator Command**:
+    *   Open your terminal in the root directory of your Powerhouse project.
+    *   Execute the `ph generate` command, pointing to your specification file:
     ```bash
-    ph generate ProjectTask.phdm.zip
+    ph generate ToDoList.phdm.zip
     ```
-3.  **Explore the generated files:**
-    You would now find a new directory `document-models/project-task/` containing:
-    *   `project-task/spec.json`
-    *   `project-task/schema.graphql`
-    *   `project-task/gen/types.ts` (with `ProjectTaskState`, `AssignUserInput`, etc.)
-    *   `project-task/gen/operations.ts` (with `creators.assignUser(...)`, `creators.completeTask(...)`, etc.)
-    *   `project-task/src/reducers/project-task.ts` (with empty functions like `assignUserOperation`, `completeTaskOperation` awaiting your implementation).
+
+3.  **Explore the Generated Files**:
+    *   After the command completes successfully, you will find a new directory: `document-models/to-do-list/`.
+    *   Take a moment to explore its contents, which will match the structure described earlier in this document:
+        *   `spec.json` and `schema.graphql`: The definition of your model.
+        *   `gen/`: Type-safe, generated code including `types.ts`, `operations.ts`, etc.
+        *   `src/`: The skeleton for your implementation, most importantly `src/reducers/to-do-list.ts`, which will contain empty functions for `addTodoItemOperation`, `updateTodoItemOperation`, and `deleteTodoItemOperation`, ready for you to implement.
+
+With these files generated, you have successfully scaffolded your document model. The project is now set up for you to implement the core business logic.
+
+</details>
 
 ## Next Steps
 

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

@@ -47,7 +47,6 @@ 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
-    // Example structure from 01-GetStarted/03-ImplementOperationReducers.md
     import { ToDoListToDoListOperations } from '../../gen/to-do-list/operations.js'; // Generated type for operations
     import { ToDoListState } from '../../gen/types.js'; // Generated type for state
 
@@ -76,9 +75,9 @@ Let's break down its components and principles:
 
 ## Implementing Reducer Logic: A Practical Guide
 
-Let's use our familiar `ToDoList` example (as detailed in `01-GetStarted/03-ImplementOperationReducers.md`) to illustrate common patterns.
+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.
 
-Assume our `ToDoListState` is:
+Our `ToDoListState` now looks like this:
 ```typescript
 interface ToDoItem {
   id: string;
@@ -86,8 +85,15 @@ interface ToDoItem {
   checked: boolean;
 }
 
+interface ToDoListStats {
+  total: number;
+  checked: number;
+  unchecked: number;
+}
+
 interface ToDoListState {
   items: ToDoItem[];
+  stats: ToDoListStats;
 }
 ```
 
@@ -226,46 +232,105 @@ Using these types provides:
 *   **Autocompletion and IntelliSense**: Improved developer experience in your IDE.
 *   **Clearer code**: Types serve as documentation for the expected data structures.
 
-## Testing Your 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.
+
+<details>
+<summary>Tutorial: Implementing the ToDoList Reducers</summary>
 
-Reducers, being pure functions, are inherently easy to test. For each reducer:
-1.  Set up an initial state.
-2.  Create an action object (ideally using the generated action creators from `../../gen/creators.js` or `../../gen/operations.js`).
-3.  Call the reducer function with the initial state and the action.
-4.  Assert that the returned new state is what you expect it to be.
-5.  Crucially, also assert that the *original* state object was not modified.
+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.
 
-The `01-GetStarted/03-ImplementOperationReducers.md` document provides excellent examples of reducer tests:
+### 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.
 
 ```typescript
-// Example from 01-GetStarted/03-ImplementOperationReducers.md (simplified)
-import utils from '../../gen/utils'; // For createDocument
-import { reducer } from '../../gen/reducer'; // The combined reducer
-import * as creators from '../../gen/creators'; // Action creators
-import { ToDoListDocument, ToDoListState } from '../../gen/types';
-
-describe('Todolist Operations', () => {
-  let document: ToDoListDocument; // Assuming ToDoListDocument wraps ToDoListState
-
-  beforeEach(() => {
-    document = utils.createDocument(); // Gets initial state
-  });
-
-  it('should handle addTodoItem operation', () => {
-    const input = { id: '1', text: 'Buy milk' };
-    const action = creators.addTodoItem(input); // Use action creator
-
-    // Assuming your main reducer takes the whole document and action
-    const updatedDocument = reducer(document, action);
-
-    expect(updatedDocument.state.global.items).toHaveLength(1);
-    expect(updatedDocument.state.global.items[0].text).toBe('Buy milk');
-    // Also check that document.state.global.items is different from updatedDocument.state.global.items (immutability)
-  });
-});
+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);
+    },
+};
 ```
 
-The generator typically creates a test file skeleton (e.g., `document-models/<YourModelName>/src/reducers/tests/<your-model-name>.test.ts`) to get you started. **Thoroughly testing your reducers is paramount for a robust document model.**
+</details>
 
 ## Reducers and the Event Sourcing Model
 
@@ -279,4 +344,4 @@ This is why purity and immutability are so critical:
 
 Implementing document reducers is where you breathe life into your document model's specification. By adhering to the principles of purity and immutability, and by leveraging the type safety provided by Powerhouse's code generation, you can build predictable, testable, and maintainable business logic. These reducers form the immutable backbone of your document's state management, perfectly aligning with the event sourcing architecture that underpins Powerhouse.
 
-With your reducers implemented and tested, your document model is now functionally complete from a data manipulation perspective. The next stages often involve building user interfaces or integrations that interact with this model by dispatching the operations you've now so carefully implemented.
+With your reducers implemented, your document model is now functionally complete from a data manipulation perspective. The next chapter covers how to write tests for this logic to ensure its correctness and reliability.