@powerhousedao/academy 5.0.3 → 5.0.5

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

@@ -112,6 +112,12 @@ Now, run the tests from your project's root directory to verify your implementat
 pnpm run test
 ```
 
+Or with npm:
+
+```bash
+npm test
+```
+
 If all tests pass, you have successfully verified the core logic of your `To-do List` document model. This ensures that the reducers you wrote behave exactly as expected.
 
 </details>
@@ -128,7 +134,7 @@ While the tutorial provides a concrete example, keep these general best practice
   - **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.
+- **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` (or `npm test`) command is your friend.
 
 ## Conclusion: The payoff of diligent testing
 

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

@@ -2,16 +2,16 @@
 
 :::info
 
-The Todo-demo-package is maintained by the Powerhouse Team and serves as a reference for testing and introducing new features. It will be continuously updated alongside the accompanying documentation.
+The Todo-demo is maintained by the Powerhouse Team and serves as a reference for testing and introducing new features. It will be continuously updated alongside the accompanying documentation.
 
-https://github.com/powerhouse-inc/todo-demo-package
+https://github.com/powerhouse-inc/todo-demo
 :::
 
 There are several ways to explore this package:
 
-### Option 1: Rebuild the Todo-demo-package
+### Option 1: Rebuild the Todo-demo
 
-The Todo-demo-package and repository are your main reference points during the Mastery Track.  
+The Todo-demo and repository are your main reference points during the Mastery Track.  
 Follow the steps in the "Mastery Track – Document Model Creation" chapters to build along with the examples.
 
 ### Option 2: Clone and run the code locally
@@ -35,5 +35,5 @@ ph connect
 Alternatively, you can install this package in a Powerhouse project or in your deployed host apps:
 
 ```bash
-ph install @powerhousedao/todo-demo-package
+ph install @powerhousedao/todo-demo
 ```

package/docs/academy/03-ExampleUsecases/Chatroom/02-CreateNewPowerhouseProject.md

@@ -73,7 +73,10 @@ Watching local document editors at '/home/you/Powerhouse/ChatRoom/editors'...
 
 A new browser window will open and you will see the Connect application. If it doesn't open automatically, you can open it manually by navigating to `http://localhost:3000/` in your browser.
 
-Create a new document model by clicking on the `DocumentModel` button by the "New Document" section. The Gif below shows you where to click.
+If you don't have a local drive created yet, create one using the Generic Drive Explorer app.
+
+Open your Local Drive and create a new document model by clicking the `DocumentModel` button in the "New Document" section. The GIF below shows where to click.
+
 
 ![Create New Document Model](./images/ChatRoomConnectApp.gif)
 

package/docs/academy/03-ExampleUsecases/Chatroom/03-DefineChatroomDocumentModel.md

@@ -65,11 +65,17 @@ enum ReactionType {
 
 input AddMessageInput {
   messageId: OID! # ID of the message that is being added
-  sender: Sender! # ID of the user sending the message
+  sender: SenderInput! # ID of the user sending the message
   content: String! # Content of the message
   sentAt: DateTime!
 }
 
+input SenderInput {
+  id: ID! # Unique identifier for the sender
+  name: String
+  avatarUrl: URL # Allows us to pull the ENS and/or nft of the persons profile
+}
+
 input AddEmojiReactionInput {
   messageId: OID! # ID of the message to which the reaction is being added
   reactedBy: ID! # ID of the user adding the reaction
@@ -106,14 +112,14 @@ The steps below show you how to do this:
 
 3. In the code editor, you can see the SDL for the document model. Replace the existing SDL with the SDL defined in the [State Schema](#state-schema) section above. Only copy and paste the types, leaving the inputs for the next step. You can however already press 'Sync with schema' button to set the initial state of your document model based on your Schema Definition Language. Verify that your Global State Initial Value looks like this.
 
-```graphql
+```json
 {
   "id": "",
   "name": "",
-  "description": "",
-  "createdAt": "",
-  "createdBy": "",
-  "messages": ""
+  "description": null,
+  "createdAt": null,
+  "createdBy": null,
+  "messages": []
 }
 ```
 
@@ -123,11 +129,17 @@ The steps below show you how to do this:
 
 ```graphql
 input AddMessageInput {
-  messageId: OID! # ID of the message that is being added
-  sender: Sender! # ID of the user sending the message
-  content: String! # Content of the message
+  messageId: OID!
+  sender: SenderInput!
+  content: String!
   sentAt: DateTime!
 }
+
+input SenderInput {
+  id: ID! # Unique identifier for the sender
+  name: String
+  avatarUrl: URL # Allows us to pull the ENS and/or nft of the persons profile
+}
 ```
 
 7. Repeat step 6 for the other input operations based on the [Operations Schema](#operations-schema). If you noticed, you only need to add the name `(ADD_EMOJI_REACTION, EDIT_CHAT_NAME, etc)` of the operation without the `input` suffix. Then it will be generated once you press enter.

package/docs/academy/03-ExampleUsecases/Chatroom/04-ImplementOperationReducers.md

@@ -22,7 +22,7 @@ To write the opearation reducers of the `ChatRoom` document model, you need to g
 To do this, run the following command in the terminal:
 
 ```bash
-ph generate ChatRoom.phdm.zip
+ph generate ChatRoom.phdm.phd
 ```
 
 You will see that this action created a range of files for you. Before diving in we'll look at this simple schema to make you familiar with the structure you've defined in the document model once more. It shows how each type is connected to the next one.
@@ -47,97 +47,95 @@ Open the `general-operations.ts` file and you should see the code that needs to
  * - delete the file and run the code generator again to have it reset
  */
 
-import { ChatRoomAddMessageOperations } from "../../gen/add-message/operations";
-import { MessageContentCannotBeEmpty } from "../../gen/add-message/error";
-
-export const reducer: ChatRoomAddMessageOperations = {
-  addMessageOperation(state, action, dispatch) {
-    if (action.input.content === "") {
-      throw new MessageContentCannotBeEmpty(); // Your reducer exception is used here as a custom error.
-    }
-
-    state.messages.push({
-      id: action.input.messageId,
-      content: action.input.content,
-      sender: action.input.sender,
-      sentAt: action.input.sentAt,
-      reactions: [],
-    });
-  },
-  addEmojiReactionOperation(state, action, dispatch) {
-    const message = state.messages.find(
-      (message) => message.id === action.input.messageId, // the reducer checks the existence of the message you want to react to.
-    );
+import { MessageContentCannotBeEmpty } from "../../gen/general-operations/error.js";
+import type { ChatRoomGeneralOperationsOperations } from "chatroom/document-models/chat-room";
 
-    if (!message) {
-      throw new Error("Message not found");
-    }
+export const chatRoomGeneralOperationsOperations: ChatRoomGeneralOperationsOperations =
+  {
+    addMessageOperation(state, action) {
+      if (action.input.content === "") {
+        throw new MessageContentCannotBeEmpty();
+      }
 
-    const reactions = message.reactions || [];
+      const newMessage = {
+        id: action.input.messageId,
+        sender: {
+          id: action.input.sender.id,
+          name: action.input.sender.name || null,
+          avatarUrl: action.input.sender.avatarUrl || null,
+        },
+        content: action.input.content,
+        sentAt: action.input.sentAt,
+        reactions: [],
+      };
+
+      state.messages.push(newMessage);
+    },
+    addEmojiReactionOperation(state, action) {
+      const message = state.messages.find(
+        (m) => m.id === action.input.messageId,
+      );
+      if (!message) {
+        return state;
+      }
 
-    const existingReaction = reactions.find(
-      (reaction) => reaction.type === action.input.type,
-    );
+      if (!message.reactions) {
+        message.reactions = [];
+      }
 
-    if (existingReaction) {
-      // if the message reaction exists a new reactedBy gets added.
-      message.reactions = reactions.map((reaction) => {
-        if (reaction.type === action.input.type) {
-          return {
-            ...reaction,
-            reactedBy: [...reaction.reactedBy, action.input.reactedBy],
-          };
-        }
+      const existingReaction = message.reactions.find(
+        (r) => r.type === action.input.type,
+      );
 
-        return reaction;
-      });
-    } else {
-      message.reactions = [
-        ...reactions,
-        {
-          reactedBy: [action.input.reactedBy], // if the message reaction doesn't exist yet a new reaction gets created
+      if (existingReaction) {
+        if (!existingReaction.reactedBy.includes(action.input.reactedBy)) {
+          existingReaction.reactedBy.push(action.input.reactedBy);
+        }
+      } else {
+        message.reactions.push({
           type: action.input.type,
-        },
-      ];
-    }
+          reactedBy: [action.input.reactedBy],
+        });
+      }
+    },
+    removeEmojiReactionOperation(state, action) {
+      const message = state.messages.find(
+        (m) => m.id === action.input.messageId,
+      );
+      if (!message) {
+        return state;
+      }
 
-    state.messages = state.messages.map((_message) => {
-      // the state of the chatroom documents messages gets updated
-      if (_message.id === message.id) {
-        return message;
+      if (!message.reactions) {
+        return;
       }
 
-      return _message;
-    });
-  },
-  removeEmojiReactionOperation(state, action, dispatch) {
-    // To remove a reaction the address is removed from the reactedBy object in the reactions type.
-    state.messages = state.messages.map((message) => {
-      if (message.id === action.input.messageId) {
-        message.reactions = (message.reactions || []).map((reaction) => {
-          if (reaction.type === action.input.type) {
-            return {
-              ...reaction,
-              reactedBy: reaction.reactedBy.filter(
-                (reactedBy) => reactedBy !== action.input.senderId, // We're removing the sender of the reaction from the the reactedBy object
-              ),
-            };
-          }
-
-          return reaction;
-        });
+      const reactionIndex = message.reactions.findIndex(
+        (r) => r.type === action.input.type,
+      );
+      if (reactionIndex === -1) {
+        return;
       }
 
-      return message; // We're updating the document state with our changes
-    });
-  },
-  editChatNameOperation(state, action, dispatch) {
-    state.name = action.input.name || "";
-  },
-  editChatDescriptionOperation(state, action, dispatch) {
-    state.description = action.input.description || "";
-  },
-};
+      const reaction = message.reactions[reactionIndex];
+      const userIndex = reaction.reactedBy.indexOf(action.input.senderId);
+
+      if (userIndex !== -1) {
+        reaction.reactedBy.splice(userIndex, 1);
+
+        if (reaction.reactedBy.length === 0) {
+          message.reactions.splice(reactionIndex, 1);
+        }
+      }
+    },
+    editChatNameOperation(state, action) {
+      state.name = action.input.name || "";
+    },
+    editChatDescriptionOperation(state, action) {
+      state.description = action.input.description || "";
+    },
+  };
+
 ```
 
 ## Write the Operation Reducers Tests
@@ -156,34 +154,38 @@ Here are the tests for the five operations written in the reducers file.
  * - change it by adding new tests or modifying the existing ones
  */
 
-import { generateMock } from "@powerhousedao/codegen";
-import { utils as documentModelUtils } from "document-model/document";
-
-import utils from "../../gen/utils";
+import { describe, it, expect, beforeEach } from "vitest";
+import { generateId } from "document-model/core";
 import {
-  z,
+  reducer,
+  utils,
+  addMessage,
+  addEmojiReaction,
+  removeEmojiReaction,
+  editChatName,
+  editChatDescription,
+} from "../../gen/index.js";
+import type {
+  ChatRoomDocument,
   AddMessageInput,
   AddEmojiReactionInput,
   RemoveEmojiReactionInput,
   EditChatNameInput,
   EditChatDescriptionInput,
-} from "../../gen/schema";
-import { reducer } from "../../gen/reducer";
-import * as creators from "../../gen/add-message/creators";
-import { ChatRoomDocument } from "../../gen/types";
+} from "../../gen/types.js";
 
-describe("AddMessage Operations", () => {
+describe("GeneralOperations Operations", () => {
   let document: ChatRoomDocument;
 
   beforeEach(() => {
     document = utils.createDocument();
   });
 
-  const addMessage = (): [ChatRoomDocument, AddMessageInput] => {
-    // This is a helper function for our upcoming test
+  const addMessageHelper = (): [ChatRoomDocument, AddMessageInput] => {
+    // This is a helper function for our upcoming tests
     const input: AddMessageInput = {
       content: "Hello, World!",
-      messageId: documentModelUtils.hashKey(),
+      messageId: generateId(),
       sender: {
         id: "anon-user",
         name: null,
@@ -192,17 +194,21 @@ describe("AddMessage Operations", () => {
       sentAt: new Date().toISOString(),
     };
 
-    const updatedDocument = reducer(document, creators.addMessage(input));
+    const updatedDocument = reducer(document, addMessage(input));
 
     return [updatedDocument, input];
   };
 
   it("should handle addMessage operation", () => {
-    const [updatedDocument, input] = addMessage();
+    const [updatedDocument, input] = addMessageHelper();
 
     expect(updatedDocument.operations.global).toHaveLength(1); // We're validating that the message is being added to the operations history
-    expect(updatedDocument.operations.global[0].type).toBe("ADD_MESSAGE");
-    expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[0].action.type).toBe(
+      "ADD_MESSAGE",
+    );
+    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
+      input,
+    );
     expect(updatedDocument.operations.global[0].index).toEqual(0);
 
     expect(updatedDocument.state.global.messages).toHaveLength(1); // We're validating that the message is present in the message state of the document
@@ -217,7 +223,7 @@ describe("AddMessage Operations", () => {
 
   it("should handle addEmojiReaction operation", () => {
     // We're validating that we can react using an emoji with a helper function
-    const [doc, addMessageInput] = addMessage();
+    const [doc, addMessageInput] = addMessageHelper();
 
     let updatedDocument = doc;
 
@@ -229,14 +235,14 @@ describe("AddMessage Operations", () => {
 
     updatedDocument = reducer(
       updatedDocument,
-      creators.addEmojiReaction(addEmojiReactionInput),
+      addEmojiReaction(addEmojiReactionInput),
     );
 
     expect(updatedDocument.operations.global).toHaveLength(2); // We're validating that the emoji reaction is added to the operation history of the doc.
-    expect(updatedDocument.operations.global[1].type).toBe(
+    expect(updatedDocument.operations.global[1].action.type).toBe(
       "ADD_EMOJI_REACTION",
     );
-    expect(updatedDocument.operations.global[1].input).toStrictEqual(
+    expect(updatedDocument.operations.global[1].action.input).toStrictEqual(
       addEmojiReactionInput,
     );
     expect(updatedDocument.operations.global[1].index).toEqual(1);
@@ -251,28 +257,25 @@ describe("AddMessage Operations", () => {
   });
 
   it("should handle addEmojiReaction operation to a non existing message", () => {
-    // We're testing that an error is thrown when reacting to a non-existing message
+    // We're testing that the state doesn't change when reacting to a non-existing message
     const input: AddEmojiReactionInput = {
       messageId: "invalid-message-id",
       reactedBy: "anon-user",
       type: "THUMBS_UP",
     };
 
-    const updatedDocument = reducer(document, creators.addEmojiReaction(input));
+    const updatedDocument = reducer(document, addEmojiReaction(input));
 
     expect(updatedDocument.operations.global).toHaveLength(1);
-    expect(updatedDocument.operations.global[0].type).toBe(
+    expect(updatedDocument.operations.global[0].action.type).toBe(
       "ADD_EMOJI_REACTION",
     );
-    expect(updatedDocument.operations.global[0].error).toBe(
-      "Message not found",
-    );
     expect(updatedDocument.state.global.messages).toHaveLength(0);
   });
 
   it("should handle removeEmojiReaction operation", () => {
     // We're making use of a helper function to check if we can remove an EmojiReaction
-    const [doc, addMessageInput] = addMessage();
+    const [doc, addMessageInput] = addMessageHelper();
 
     let updatedDocument = doc;
 
@@ -284,7 +287,7 @@ describe("AddMessage Operations", () => {
 
     updatedDocument = reducer(
       updatedDocument,
-      creators.addEmojiReaction(addEmojiReactionInput),
+      addEmojiReaction(addEmojiReactionInput),
     );
 
     const input: RemoveEmojiReactionInput = {
@@ -294,22 +297,19 @@ describe("AddMessage Operations", () => {
       type: "THUMBS_UP",
     };
 
-    updatedDocument = reducer(
-      updatedDocument,
-      creators.removeEmojiReaction(input),
-    );
+    updatedDocument = reducer(updatedDocument, removeEmojiReaction(input));
 
     expect(updatedDocument.operations.global).toHaveLength(3); // We're validating that the operation was added to the operation history.
-    expect(updatedDocument.operations.global[2].type).toBe(
+    expect(updatedDocument.operations.global[2].action.type).toBe(
       "REMOVE_EMOJI_REACTION",
     );
-    expect(updatedDocument.operations.global[2].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[2].action.input).toStrictEqual(
+      input,
+    );
     expect(updatedDocument.operations.global[2].index).toEqual(2);
 
-    expect(updatedDocument.state.global.messages[0].reactions).toHaveLength(1); // The reaction should still exist but no-one should have reacted to it
-    expect(
-      updatedDocument.state.global.messages[0].reactions?.[0]?.reactedBy,
-    ).toHaveLength(0);
+    // When the last user removes their reaction, the entire reaction should be removed
+    expect(updatedDocument.state.global.messages[0].reactions).toHaveLength(0);
   });
 
   it("should handle editChatName operation", () => {
@@ -317,11 +317,15 @@ describe("AddMessage Operations", () => {
       name: "New Chat Name",
     };
 
-    const updatedDocument = reducer(document, creators.editChatName(input));
+    const updatedDocument = reducer(document, editChatName(input));
 
     expect(updatedDocument.operations.global).toHaveLength(1); // We're validating that the operation is added to the operations history
-    expect(updatedDocument.operations.global[0].type).toBe("EDIT_CHAT_NAME");
-    expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[0].action.type).toBe(
+      "EDIT_CHAT_NAME",
+    );
+    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
+      input,
+    );
     expect(updatedDocument.operations.global[0].index).toEqual(0);
 
     expect(updatedDocument.state.global.name).toBe(input.name);
@@ -332,16 +336,15 @@ describe("AddMessage Operations", () => {
       description: "New Chat Description",
     };
 
-    const updatedDocument = reducer(
-      document,
-      creators.editChatDescription(input),
-    );
+    const updatedDocument = reducer(document, editChatDescription(input));
 
     expect(updatedDocument.operations.global).toHaveLength(1); // We're validating that the operation is added to the operations history
-    expect(updatedDocument.operations.global[0].type).toBe(
+    expect(updatedDocument.operations.global[0].action.type).toBe(
       "EDIT_CHAT_DESCRIPTION",
     );
-    expect(updatedDocument.operations.global[0].input).toStrictEqual(input);
+    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
+      input,
+    );
     expect(updatedDocument.operations.global[0].index).toEqual(0);
 
     expect(updatedDocument.state.global.description).toBe(input.description);