@powerhousedao/academy 3.3.0-dev.10 → 3.3.0-dev.12

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 3.3.0-dev.12 (2025-07-17)
+
+### 🩹 Fixes
+
+- **document-drive:** use lowercase letters when hashing relational processor namespace ([87c7944d3](https://github.com/powerhouse-inc/powerhouse/commit/87c7944d3))
+
+### ❤️ Thank You
+
+- acaldas
+
+## 3.3.0-dev.11 (2025-07-16)
+
+This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.
+
 ## 3.3.0-dev.10 (2025-07-15)
 
 ### 🩹 Fixes

package/docs/academy/02-MasteryTrack/04-WorkWithData/07-OperationalDbProcessorTutorial/01-TodoList-example.md

@@ -0,0 +1,203 @@
+# Build a Todo-List processor
+
+1. Generate the processor
+2. Define your database schema
+3. Customize the processor to your needs
+4. Test your processor
+5. Use the operational store in Frontend and Subgraph
+
+
+## Generate the Processor
+
+In order to generate the processor you need to run the following command:
+```bash
+ph generate --processor todo-processor --processor-type relational-db --document-types powerhouse/todolist
+```
+
+With that command you create a processor named todo-processor which is of type relational db and listens on changes from documents of type powerhouse/todolist.
+
+## Define your database schema
+
+As next step we need to define the db schema in the `processors/todo-processor/migration.ts` file.
+
+The migration file has a up and a down function which gets called when either the processor was added or when the processor was removed.
+
+Below you can find the example of a todo table.
+
+```ts
+import { type IOperationalStore } from "document-drive/processors/types"
+
+export async function up(db: IOperationalStore): Promise<void> {
+  // Create table
+  await db.schema
+    .createTable("todo")
+    .addColumn("name", "varchar(255)")
+    .addColumn("completed", "boolean")
+    .addPrimaryKeyConstraint("todo_pkey", ["name"])
+    .ifNotExists()
+    .execute();
+
+  const tables = await db.introspection.getTables();
+  console.log(tables);
+}
+
+export async function down(db: IOperationalStore): Promise<void> {
+  // drop table
+  await db.schema.dropTable("todo").execute();
+}
+```
+
+## Generate Types
+
+After defining your db schema its important to generate the types for typescript. This allows to create type safety queries and make use of code completion in your IDE when writing database queries.
+
+Simply execute the following command. 
+
+```bash
+ph generate --migration-file processors/todo-indexer/migrations.js --schema-file processors/todo-indexer/schema.ts
+```
+
+Afterwards check your `processors/todo-processor/schema.ts` file.
+It will contain the types of your database.
+
+## Define the Filter
+
+Checkout the `processors/todo-processor/factory.ts`.
+
+Here you can define how the processor is being instantiated. In thise case it listens on powerhouse/todo-list document changes in the main branch and the global scope.
+
+```ts
+export const todoProcessorProcessorFactory =
+  (module: IProcessorHostModule) =>
+  async (driveId: string): Promise<ProcessorRecord[]> => {
+    // Create a namespace for the processor and the provided drive id
+    const namespace = TodoProcessorProcessor.getNamespace(driveId);
+
+    // Create a filter for the processor
+    const filter: OperationalProcessorFilter = {
+      branch: ["main"],
+      documentId: ["*"],
+      documentType: ["powerhouse/todo-list"],
+      scope: ["global"],
+    };
+
+    // Create a namespaced store for the processor
+    const store = await createNamespacedDb<TodoProcessorProcessor>(
+      namespace,
+      module.operationalStore,
+    );
+
+    // Create the processor
+    const processor = new TodoProcessorProcessor(namespace, filter, store);
+    return [
+      {
+        processor,
+        filter,
+      },
+    ];
+  };
+
+```
+
+## Customize the logic of the processor
+
+When you defined your db schema and the filter when your processor should receive processed operations its time to implement the actual logic.
+
+In the following you'll find an example where we store all the created and udpated todos in a table.
+
+```ts
+type DocumentType = ToDoListDocument;
+
+export class TodoIndexerProcessor extends OperationalProcessor<DB> {
+
+  static override getNamespace(driveId: string): string {
+    // Default namespace: `${this.name}_${driveId.replaceAll("-", "_")}`
+    return super.getNamespace(driveId);
+  }
+
+  override async initAndUpgrade(): Promise<void> {
+    await up(this.operationalStore as IOperationalStore);
+  }
+
+  override async onStrands(
+    strands: InternalTransmitterUpdate<DocumentType>[],
+  ): Promise<void> {
+    if (strands.length === 0) {
+      return;
+    }
+
+    for (const strand of strands) {
+      if (strand.operations.length === 0) {
+        continue;
+      }
+
+      for (const operation of strand.operations) {
+        await this.operationalStore
+          .insertInto("todo")
+          .values({
+            task: strand.documentId,
+            status: true,
+          })
+          .execute();
+      }
+    }
+  }
+
+  async onDisconnect() {}
+}
+
+```
+
+## Fetch Data through a Subgraph
+
+### Generate Subgraph
+
+Simply generate a new subgraph with:
+```bash
+ph generate --subgraph <subgraph-name>
+```
+
+### Fetch Data from Processor
+
+open ```./subgraphs/<subgraph-name>/index.ts```
+
+
+
+define the following:
+
+
+```ts
+resolvers = {
+    Query: {
+      todoList: {
+        resolve: async (parent, args, context, info) => {
+          const todoList = await TodoProcessor.query(
+              args.driveId ?? "powerhouse", 
+              this.operationalStore
+          )
+            .selectFrom("todo")
+            .selectAll()
+            .execute();
+          return todoList
+        },
+      },
+    },
+  };
+
+  typeDefs = gql`
+    type Query {
+      type Todo {
+        name: String!
+        completed: Boolean!
+      }
+
+      todoList(driveId: String): [Todo!]!
+    }
+  `;
+  ``` 
+
+
+  ### useOperationalStore Hook
+
+  ..... 
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/academy",
-  "version": "3.3.0-dev.10",
+  "version": "3.3.0-dev.12",
   "homepage": "https://powerhouse.academy",
   "repository": {
     "type": "git",

package/docs/academy/02-MasteryTrack/04-WorkWithData/07-OperationalDbProcessorTutorial/03-GenerateAnAnalyticsProcessor.md

@@ -1,169 +0,0 @@
-# Build a Todo-List processor
-
-1. Generate the processor
-2. Define your database schema
-3. Customize the processor to your needs
-4. Test your processor
-5. Use the operational store in Frontend and Subgraph
-
-
-## Generate the Processor
-
-In order to generate the processor you need to run the following command:
-```bash
-ph generate --processor todo-processor --processor-type operational --document-types powerhouse/todolist
-```
-
-## Define your database schema
-
-in the migrations.ts file in your processor directory you can find the up and down methods which are being executed when the processor gets installed or removed. 
-
-```ts
-import { type IOperationalStore } from "document-drive/processors/types"
-
-export async function up(db: IOperationalStore): Promise<void> {
-  // Create table
-  await db.schema
-    .createTable("todo")
-    .addColumn("name", "varchar(255)")
-    .addColumn("completed", "boolean")
-    .addPrimaryKeyConstraint("todo_pkey", ["name"])
-    .ifNotExists()
-    .execute();
-
-  const tables = await db.introspection.getTables();
-  console.log(tables);
-}
-
-export async function down(db: IOperationalStore): Promise<void> {
-  // drop table
-  await db.schema.dropTable("todo").execute();
-}
-```
-
-when you finished defining your database model you can generate the types for typescript from it with the following command: 
-
-```bash
-ph generate --migration-file processors/todo-indexer/migrations.js --schema-file processors/todo-indexer/schema.ts
-```
-
-
-## Customize the processor
-
-the index file contains the processor itsself with the default template:
-
-```ts
-import {
-  OperationalProcessor,
-  type OperationalProcessorFilter,
-} from "document-drive/processors/operational-processor";
-import { type InternalTransmitterUpdate } from "document-drive/server/listener/transmitter/internal";
-import { up } from "./migrations.js";
-import { type DB } from "./schema.js";
-import type { ToDoListDocument } from "../../document-models/to-do-list/index.js";
-
-type DocumentType = ToDoListDocument;
-
-export class TodoIndexerProcessor extends OperationalProcessor<DB> {
-  get filter(): OperationalProcessorFilter {
-    return {
-      branch: ["main"],
-      documentId: ["*"],
-      documentType: ["powerhouse/todolist"],
-      scope: ["global"],
-    };
-  }
-
-  async initAndUpgrade(): Promise<void> {
-    await up(this.operationalStore);
-  }
-
-  async onStrands(
-    strands: InternalTransmitterUpdate<DocumentType>[],
-  ): Promise<void> {
-    if (strands.length === 0) {
-      return;
-    }
-
-    for (const strand of strands) {
-      if (strand.operations.length === 0) {
-        continue;
-      }
-
-      for (const operation of strand.operations) {
-        console.log(">>> ", operation.type);
-        await this.operationalStore
-          .insertInto("todo")
-          .values({
-            task: strand.documentId,
-            status: true,
-          })
-          .execute();
-      }
-    }
-  }
-
-  async onDisconnect() {}
-}
-```
-
-As you can see you can define with the filter options when the processor is executed. 
-In this case the processor is called when an operation on a powerhouse/todolist document was processed.
-The operations and the corresponding states will be passed to the onStrands method.
-
-Furthermore the Processor contains an initAndUpgrade function which is called when the processor is being activated. Next to the init there is also an onDisconnect function which is called when the processor is beging removed. The template of the operational database processor contains the up method of the migrations.ts file. 
-
-Finally there is the onStrands method. Here you can update your operational database based upon your needs. 
-
-## test the processor
-
-.... todo
-
-## use the operational database
-
-### subgraph
-
-1. generate subgraph with
-
-```bash
-ph generate --subgraph <subgraph-name>
-```
-
-open ```./subgraphs/<subgraph-name>/index.ts```
-
-define the following:
-
-
-```
-resolvers = {
-    Query: {
-      todoList: {
-        resolve: async (parent, args, context, info) => {
-          const todoList = await this.operationalStore.selectFrom("todo").selectAll().execute();
-          return todoList
-        },
-      },
-    },
-  };
-
-  typeDefs = gql`
-    type Query {
-      type Todo {
-        name: String!
-        completed: Boolean!
-      }
-
-      todoList: [Todo!]!
-    }
-  `;
-  ``` 
-
-  you can simply do sql requests with the provided operationalstore in the class for example
-  ```ts
-  await this.operationalStore.selectFrom("todo").selectAll().execute();
-  ```
-
-  ### useOperationalStore Hook
-
-  ..... 
-