@powerhousedao/academy 5.1.0-staging.0 → 5.1.0

package/docs/academy/04-APIReferences/renown-sdk/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "Renown SDK",
-  "position": 6,
-  "link": {
-    "type": "generated-index",
-    "description": "Complete documentation for the Renown SDK - authentication and user profile management for React applications."
-  }
-}

package/docs/academy/10-TodoListTutorial/02-ImplementTodoListDocumentModelReducerOperationHandlers.md

@@ -1,171 +0,0 @@
-# Step 2 — Implement the `TodoList` document model reducer operation handlers
-
-## Adding the logic for handling operations with reducers
-
-Your document model update's the state of a given document by applying a set of append-only actions. Once these have been applied to the document, we call them operations.
-
-The document model does this with a reducer — a function which takes the existing state and a given action, and then returns the new state with the action applied.
-
-## What we have so far
-
-The operation handler logic for each module is found in `document-models/SOME-DOCUMENT-MODEL/src/reducers/SOME-MODULE-NAME.ts`.
-
-So for our todos module, we will implement our handler logic in `document-models/todo-list/src/reducers/todos.ts`
-
-When you generated your document model code, we created a boilerplate implementation of the reducer logic for each of the operations we defined in step 1. You will see that there are functions for handling each of the operations, but all they do is throw "not implemented" errors.
-
-```ts
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-
-export const todoListTodosOperations: TodoListTodosOperations = {
-  addTodoItemOperation(state, action) {
-    // TODO: Implement "addTodoItemOperation" reducer
-    throw new Error('Reducer "addTodoItemOperation" not yet implemented');
-  },
-  updateTodoItemOperation(state, action) {
-    // TODO: Implement "updateTodoItemOperation" reducer
-    throw new Error('Reducer "updateTodoItemOperation" not yet implemented');
-  },
-  deleteTodoItemOperation(state, action) {
-    // TODO: Implement "deleteTodoItemOperation" reducer
-    throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
-  },
-};
-```
-
-Let's add the handler logic for each operation in the same order we defined them in the previous step.
-
-To handle the `addTodoItemOperation`, all we need to do is create an `id` for our new operation, and then push an object with that `id` and the rest of the action input into the `items` array in our state.
-
-Update your `addTodoItemOperation` like so:
-
-```typescript
-import type { TodoListTodosOperations } from "todo-tutorial/document-models/todo-list";
-
-export const todoListTodosOperations: TodoListTodosOperations = {
-  // removed-start
-  addTodoItemOperation(state, action) {
-    // TODO: Implement "addTodoItemOperation" reducer
-    throw new Error('Reducer "addTodoItemOperation" not yet implemented');
-  },
-  // removed-end
-  // added-start
-  addTodoItemOperation(state, action) {
-    const id = generateId();
-    state.items.push({ ...action.input, id, checked: false });
-  },
-  // added-end
-  updateTodoItemOperation(state, action) {
-    // TODO: Implement "updateTodoItemOperation" reducer
-    throw new Error('Reducer "updateTodoItemOperation" not yet implemented');
-  },
-  deleteTodoItemOperation(state, action) {
-    // TODO: Implement "deleteTodoItemOperation" reducer
-    throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
-  },
-};
-```
-
-Under the hood, we use a library for making the functions always create and return new copies of the state, i.e. they are always _immutable_. This is why you don't actually have to return your new state, the newly created copy of the state is used automatically.
-
-The `updateTodoOperation` works in much the same way, except this time instead of creating a new `id`, we find the item in the items array which has the given id. Then we spread out the rest of the values we get from the action input, same as when creating.
-
-Update your `updateTodoOperation` to be like so:
-
-```typescript
-export const todoListTodosOperations: TodoListTodosOperations = {
-    addTodoItemOperation(state, action) {
-      const id = generateId();
-      state.items.push({ ...action.input, id, checked: false });
-    },
-    // removed-start
-    updateTodoItemOperation(state, action) {
-        // TODO: Implement "updateTodoItemOperation" reducer
-        throw new Error('Reducer "updateTodoItemOperation" not yet implemented');
-    },
-    // removed-end
-    // added-start
-    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;
-    },
-    // added-end
-    deleteTodoItemOperation(state, action) {
-        // TODO: Implement "deleteTodoItemOperation" reducer
-        throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
-    }
-};
-```
-
-The delete operation is the simplest of the three. All we need to do is filter the items array so that it no longer contains the item with the given id.
-
-```typescript
-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;
-  },
-  // removed-start
-  deleteTodoItemOperation(state, action) {
-    // TODO: Implement "deleteTodoItemOperation" reducer
-    throw new Error('Reducer "deleteTodoItemOperation" not yet implemented');
-  },
-  // removed-end
-  // added-start
-  deleteTodoItemOperation(state, action) {
-    state.items = state.items.filter((item) => item.id !== action.input.id);
-  },
-  // added-end
-};
-```
-
-With that all done, your final result should look like this:
-
-```ts
-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);
-  },
-};
-```
-
-## Check your work
-
-To make sure all works as expected, we should:
-
-- check types
-run: `pnpm tsc`
-
-- check linting
-run: `pnpm lint`
-
-- check tests
-run: `pnpm test`
-
-- make sure your code matches the code in the completed step branch
-run: `git diff your-branch-name step-2-complete-implemented-todo-list-document-model-reducer-operation-handlers`
-
-### Up next: tests for our new operation handlers
-
-Up next, you'll implement some custom tests to check the behavior of our new code.

package/docs/academy/10-TodoListTutorial/03-AddTestsForTodoListActions.md

@@ -1,462 +0,0 @@
-# Step 3 — Adding our own tests for the document model actions
-
-Similarly to the operation handler logic, when you add a new module to your document model, we generate some boilerplate tests for your code.
-
-Take a look in `document-models/todo-list/src/tests/todos.test.ts`
-
-You will see that we have some basic "sanity check" style tests for you already. These make sure that your operations are at least able to result in a valid document model state. You should copy these boilerplate checks in your other tests to ensure that your outputs are valid.
-
-```ts
-/**
- * This is a scaffold file meant for customization:
- * - change it by adding new tests or modifying the existing ones
- */
-
-import { describe, it, expect } from "vitest";
-import { generateMock } from "@powerhousedao/codegen";
-import {
-  reducer,
-  utils,
-  isTodoListDocument,
-  addTodoItem,
-  AddTodoItemInputSchema,
-  updateTodoItem,
-  UpdateTodoItemInputSchema,
-  deleteTodoItem,
-  DeleteTodoItemInputSchema,
-} from "todo-tutorial/document-models/todo-list";
-
-describe("Todos Operations", () => {
-  it("should handle addTodoItem operation", () => {
-    // the `createDocument` utility function from your document model creates
-    // an a new empty document, i.e. one with your default initial state
-    const document = utils.createDocument();
-
-    // the generate mock function takes one of your generated input schemas
-    // and creates an object populated with random values for each field
-    const input = generateMock(AddTodoItemInputSchema());
-
-    // we call your document model's reducer with the new document we just created
-    // and the action we want to test, `addTodoItem` in this case
-    // the reducer returns a new object, which is the document with the action applied
-    // if successful, there will be an operation which corresponds to this action
-    // in the updated document's operations list
-    const updatedDocument = reducer(document, addTodoItem(input));
-
-    // when you generate a document model, we give you some validation utilities like
-    // `isTodoListDocument` which confirms the document is of the correct form in a way
-    // that typescript recognizes
-    expect(isTodoListDocument(updatedDocument)).toBe(true);
-
-    // at the start a document will have 0 operations, so after applying this action
-    // there should now be one operation
-    expect(updatedDocument.operations.global).toHaveLength(1);
-
-    // the operation added to the list should correspond to the correct action type
-    expect(updatedDocument.operations.global[0].action.type).toBe(
-      "ADD_TODO_ITEM",
-    );
-
-    // the operation added should have used the correct input
-    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
-      input,
-    );
-
-    // the index of the operation should be 0, since it is the first and only operation
-    expect(updatedDocument.operations.global[0].index).toEqual(0);
-  });
-  it("should handle updateTodoItem operation", () => {
-    // ...
-  });
-  it("should handle deleteTodoItem operation", () => {
-    // ...
-  });
-});
-```
-
-Since testing the `addTodoItemOperation` is such a simple case, we have not added further testing here. You are welcome to add a more test cases for it if you want.
-
-## Tests for update operations
-
-### Test updating the todo item text
-
-Let's add some more sophisticated tests for our `updateTodoItem` operation. We want to know that we can update todos successfully, and that we we do so it only changes the values we want to change, while leaving the rest as is.
-
-Delete the existing "should handle updateTodoItem operation" test.
-
-```typescript
-// removed-start
-it("should handle updateTodoItem operation", () => {
-  const document = utils.createDocument();
-  const input = generateMock(UpdateTodoItemInputSchema());
-  const updatedDocument = reducer(document, updateTodoItem(input));
-  expect(isTodoListDocument(updatedDocument)).toBe(true);
-  expect(updatedDocument.operations.global).toHaveLength(1);
-  expect(updatedDocument.operations.global[0].action.type).toBe(
-    "UPDATE_TODO_ITEM",
-  );
-  expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
-    input,
-  );
-  expect(updatedDocument.operations.global[0].index).toEqual(0);
-});
-// removed-end
-```
-
-Let's test that the text of a todo item is updated correctly first. Put this code in the place where you just deleted the existing test case:
-
-```ts
-  it("should handle updateTodoItem operation to update text", () => {
-    // we need there to already be a todo item in the document, 
-    // since we want to test updating an existing document
-    const mockItem = generateMock(TodoItemSchema());
-
-    // we also need to generate a mock input for the update operation we are testing
-    const input: UpdateTodoItemInput = generateMock(
-      UpdateTodoItemInputSchema(),
-    );
-
-    // since the mocks are generated with random values, we need to set the `id` on our mock input 
-    // to match the `id` of the existing mock input
-    input.id = mockItem.id;
-
-    // we want to easily check if the item's text was updated to be our new value, 
-    // so we assign a variable and use that for the mock input's text field
-    const newText = "new text";
-    input.text = newText;
-
-    // we are only testing updating the text here, so we want the checked field on the input
-    // to be undefined, i.e. it should not change anything on the existing item
-    input.checked = undefined;
-
-    // we can pass a different initial state to the `createDocument` utility,
-    // so in this case we pass in an `items` array with our existing item already in it
-    const document = utils.createDocument({
-      global: {
-        items: [mockItem],
-      },
-    });
-
-    /* The following checks are copied from the boilerplate */
-
-    // create an updated document by applying the reducer with the action and input
-    const updatedDocument = reducer(document, updateTodoItem(input));
-
-    // use our validator to check that the document conforms to the document model schema
-    expect(isTodoListDocument(updatedDocument)).toBe(true);
-
-    // there should now be one operation in the operations list
-    expect(updatedDocument.operations.global).toHaveLength(1);
-
-    // the operation applied should correspond to an action of the correct type
-    expect(updatedDocument.operations.global[0].action.type).toBe(
-      "UPDATE_TODO_ITEM",
-    );
-
-    // the operation applied should have used the correct input
-    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
-      input,
-    );
-
-    // the operation applied should be the first operation in the list
-    expect(updatedDocument.operations.global[0].index).toEqual(0);
-
-    /* The following checks are unique to this test case */
-
-    // find the updated item in the items list by its `id`
-    const updatedItem = updatedDocument.state.global.items.find(
-      (item) => item.id === input.id,
-    );
-
-    // the item's text should now be updated to be our new text
-    expect(updatedItem?.text).toBe(newText);
-
-    // the item's `checked` field should be unchanged.
-    expect(updatedItem?.checked).toBe(mockItem.checked);
-  });
-```
-
-#### Check your work
-
-Running `pnpm tsc && pnpm lint && pnpm test` should pass
-
-### Test updating the todo item checked state
-
-Now let's do the same thing, but for the checked state of an item. This test is essentially just the same as the above, but we update the `checked` field while leaving the `text` field `undefined`.
-
-Add this code below the test case we just added:
-
-```ts
-  it("should handle updateTodoItem operation to update checked", () => {
-    // generate a mock existing item
-    const mockItem = generateMock(TodoItemSchema());
-
-    // generate a mock input
-    const input: UpdateTodoItemInput = generateMock(
-      UpdateTodoItemInputSchema(),
-    );
-
-    // set the mock input's `id` to the mock item's `id`
-    input.id = mockItem.id;
-    
-    // we want the new `checked` field value to be the opposite of the randomly generated value from the mock
-    const newChecked = !mockItem.checked;
-    input.checked = newChecked;
-
-    // leave the `text` field unchanged
-    input.text = undefined;
-
-    // create a document with the existing item in it
-    const document = utils.createDocument({
-      global: {
-        items: [mockItem],
-      },
-    });
-
-    // apply the reducer with the action and the mock input
-    const updatedDocument = reducer(document, updateTodoItem(input));
-
-    /* The following checks are copied from the boilerplate */
-
-    // validate your document
-    expect(isTodoListDocument(updatedDocument)).toBe(true);
-
-   // check your operations
-    expect(updatedDocument.operations.global).toHaveLength(1);
-
-    // check the operation's action type
-    expect(updatedDocument.operations.global[0].action.type).toBe(
-      "UPDATE_TODO_ITEM",
-    );
-
-    // check the operation's input
-    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
-      input,
-    );
-
-    // check the operation's index
-    expect(updatedDocument.operations.global[0].index).toEqual(0);
-
-    /* The following checks are unique to this test case */
-
-    // get the updated item by it's `id`
-    const updatedItem = updatedDocument.state.global.items.find(
-      (item) => item.id === input.id,
-    );
-
-    // the item's `text` field should remain unchanged
-    expect(updatedItem?.text).toBe(mockItem.text);
-
-    // the item's `checked` field should be updated to our new checked value
-    expect(updatedItem?.checked).toBe(newChecked);
-  });
-  ```
-
-#### Check your work
-
-Running `pnpm tsc && pnpm lint && pnpm test` should pass
-
-## Test for deleting todo items
-
-You will have seen that the tests for the `deleteTodoItem` operation passed, even though we didn't set up an existing item to delete. This is because the boilerplate just checks that the operation was applied with the correct inputs, which it technically was. Checking that it actually had the _result_ we want is our job.
-
-Update the `deleteTodoItem` operation test case to also create an existing item and then check that is was actually deleted:
-
-```typescript
-  it("should handle deleteTodoItem operation", () => {
-    // removed-start
-    const document = utils.createDocument();
-    const input = generateMock(DeleteTodoItemInputSchema());
-    // removed-end
-    // added-start
-    const mockItem = generateMock(TodoItemSchema());
-    const document = utils.createDocument({
-      global: {
-        items: [mockItem],
-      },
-    });
-    const input: DeleteTodoItemInput = generateMock(
-      DeleteTodoItemInputSchema(),
-    );
-    input.id = mockItem.id;
-    // added-end
-    const updatedDocument = reducer(document, deleteTodoItem(input));
-    expect(isTodoListDocument(updatedDocument)).toBe(true);
-
-    expect(updatedDocument.operations.global).toHaveLength(1);
-    expect(updatedDocument.operations.global[0].action.type).toBe(
-      "DELETE_TODO_ITEM",
-    );
-    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
-      input,
-    );
-    expect(updatedDocument.operations.global[0].index).toEqual(0);
-    // added-start
-    const updatedItems = updatedDocument.state.global.items;
-    expect(updatedItems).toHaveLength(0);
-    // added-end
-  });
-```
-
-#### Check your work
-
-Running `pnpm tsc && pnpm lint && pnpm test` should pass
-
-## Final result
-
-After these updates, your `document-models/todo-list/src/tests/todos.test.ts` file should look like this:
-
-```ts
-/**
- * This is a scaffold file meant for customization:
- * - change it by adding new tests or modifying the existing ones
- */
-
-import { describe, it, expect } from "vitest";
-import { generateMock } from "@powerhousedao/codegen";
-import type {
-  AddTodoItemInput,
-  DeleteTodoItemInput,
-  UpdateTodoItemInput,
-} from "todo-tutorial/document-models/todo-list";
-import {
-  reducer,
-  utils,
-  isTodoListDocument,
-  addTodoItem,
-  AddTodoItemInputSchema,
-  updateTodoItem,
-  UpdateTodoItemInputSchema,
-  deleteTodoItem,
-  DeleteTodoItemInputSchema,
-  TodoItemSchema,
-} from "todo-tutorial/document-models/todo-list";
-
-describe("Todos Operations", () => {
-  it("should handle addTodoItem operation", () => {
-    const document = utils.createDocument();
-    const input: AddTodoItemInput = generateMock(AddTodoItemInputSchema());
-
-    const updatedDocument = reducer(document, addTodoItem(input));
-    expect(isTodoListDocument(updatedDocument)).toBe(true);
-
-    expect(updatedDocument.operations.global).toHaveLength(1);
-    expect(updatedDocument.operations.global[0].action.type).toBe(
-      "ADD_TODO_ITEM",
-    );
-    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
-      input,
-    );
-    expect(updatedDocument.operations.global[0].index).toEqual(0);
-  });
-  it("should handle updateTodoItem operation to update text", () => {
-    const mockItem = generateMock(TodoItemSchema());
-    const input: UpdateTodoItemInput = generateMock(
-      UpdateTodoItemInputSchema(),
-    );
-    input.id = mockItem.id;
-    const newText = "new text";
-    input.text = newText;
-    input.checked = undefined;
-    const document = utils.createDocument({
-      global: {
-        items: [mockItem],
-      },
-    });
-
-    const updatedDocument = reducer(document, updateTodoItem(input));
-    expect(isTodoListDocument(updatedDocument)).toBe(true);
-
-    expect(updatedDocument.operations.global).toHaveLength(1);
-    expect(updatedDocument.operations.global[0].action.type).toBe(
-      "UPDATE_TODO_ITEM",
-    );
-    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
-      input,
-    );
-    expect(updatedDocument.operations.global[0].index).toEqual(0);
-    const updatedItem = updatedDocument.state.global.items.find(
-      (item) => item.id === input.id,
-    );
-    expect(updatedItem?.text).toBe(newText);
-    expect(updatedItem?.checked).toBe(mockItem.checked);
-  });
-  it("should handle updateTodoItem operation to update checked", () => {
-    const mockItem = generateMock(TodoItemSchema());
-    const input: UpdateTodoItemInput = generateMock(
-      UpdateTodoItemInputSchema(),
-    );
-    input.id = mockItem.id;
-    const newChecked = !mockItem.checked;
-    input.checked = newChecked;
-    input.text = undefined;
-    const document = utils.createDocument({
-      global: {
-        items: [mockItem],
-      },
-    });
-
-    const updatedDocument = reducer(document, updateTodoItem(input));
-    expect(isTodoListDocument(updatedDocument)).toBe(true);
-
-    expect(updatedDocument.operations.global).toHaveLength(1);
-    expect(updatedDocument.operations.global[0].action.type).toBe(
-      "UPDATE_TODO_ITEM",
-    );
-    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
-      input,
-    );
-    expect(updatedDocument.operations.global[0].index).toEqual(0);
-    const updatedItem = updatedDocument.state.global.items.find(
-      (item) => item.id === input.id,
-    );
-    expect(updatedItem?.text).toBe(mockItem.text);
-    expect(updatedItem?.checked).toBe(newChecked);
-  });
-  it("should handle deleteTodoItem operation", () => {
-    const mockItem = generateMock(TodoItemSchema());
-    const document = utils.createDocument({
-      global: {
-        items: [mockItem],
-      },
-    });
-    const input: DeleteTodoItemInput = generateMock(
-      DeleteTodoItemInputSchema(),
-    );
-    input.id = mockItem.id;
-    const updatedDocument = reducer(document, deleteTodoItem(input));
-    expect(isTodoListDocument(updatedDocument)).toBe(true);
-
-    expect(updatedDocument.operations.global).toHaveLength(1);
-    expect(updatedDocument.operations.global[0].action.type).toBe(
-      "DELETE_TODO_ITEM",
-    );
-    expect(updatedDocument.operations.global[0].action.input).toStrictEqual(
-      input,
-    );
-    expect(updatedDocument.operations.global[0].index).toEqual(0);
-    const updatedItems = updatedDocument.state.global.items;
-    expect(updatedItems).toHaveLength(0);
-  });
-});
-```
-
-## Check your work
-
-To make sure all works as expected, we should:
-
-- check types
-run: `pnpm tsc`
-
-- check linting
-run: `pnpm lint`
-
-- check tests
-run: `pnpm test`
-
-- make sure your code matches the code in the completed step branch
-run: `git diff your-branch-name step-3-complete-implemented-tests-for-todo-operations`
-
-### Up next: generating an editor for our `TodoList` documents
-
-Up next, we'll generate a boilerplate document editor for our `TodoList` documents.