@powerhousedao/academy 3.3.0-dev.5 → 3.3.0-dev.6

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 3.3.0-dev.6 (2025-07-10)
+
+### 🚀 Features
+
+- **codegen:** support loading migration typescript file ([d3cc1957b](https://github.com/powerhouse-inc/powerhouse/commit/d3cc1957b))
+
+### 🩹 Fixes
+
+- **academy:** build ([88681db3d](https://github.com/powerhouse-inc/powerhouse/commit/88681db3d))
+- **codegen,ph-cli:** make schema-file optional and updated generate help text ([adad303a8](https://github.com/powerhouse-inc/powerhouse/commit/adad303a8))
+
+### ❤️ Thank You
+
+- acaldas
+- Frank
+
 ## 3.3.0-dev.5 (2025-07-09)
 
 This was a version bump only for @powerhousedao/academy to align it with other projects, there were no code changes.

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

@@ -0,0 +1,169 @@
+# 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
+
+  ..... 
+

package/docs/academy/04-APIReferences/00-PowerhouseCLI.md

@@ -378,6 +378,10 @@ Options:
                         
   -d, --drive-editor <name> Generate a drive editor with the specified name.
 
+  --migration-file <path> Path to the migration file when running 'ph generate
+    
+  --schema-file <path> Path to the output file. Defaults to 'schema.ts' at the same directory of the migration file.
+
 Examples:
   $ ph generate                                                     # Generate code using defaults
   $ ph generate my-document-model.zip                               # Generate from a specific model zip file
@@ -388,6 +392,7 @@ Examples:
   $ ph generate --drive-editor custom-drive-explorer                # Generate a custom drive editor
   $ ph generate -s MySubgraph                                       # Generate with a specific subgraph
   $ ph generate --skip-format                                       # Generate without formatting
+  $ ph generate --migration-file ./migrations.ts                    # Generate types for an Operational Processor
 ```
 
 ## Inspect

package/package.json

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