@powerhousedao/academy 5.0.0-staging.2 → 5.0.0-staging.20

package/docs/academy/04-APIReferences/04-RelationalDatabase.md

@@ -7,8 +7,9 @@ This page covers the relational database tools available in Powerhouse applicati
 The relational database layer gives you powerful tools to work with data in your Powerhouse applications. You get type-safe queries, real-time updates, and a simple API that feels familiar to React developers.
 
 **Key Benefits:**
+
 - **Type-safe queries** with full TypeScript support
-- **Live query capabilities** with real-time updates  
+- **Live query capabilities** with real-time updates
 - **Automatic optimization** to prevent infinite re-renders
 - **Simple API** that abstracts away complexity
 - **Smart memorization** for parameters and queries
@@ -39,8 +40,8 @@ type MyDatabase = {
 ### Step 2: Create a typed query hook
 
 ```typescript
-import { createProcessorQuery } from '@powerhousedao/reactor-browser/relational';
-import { MyProcessor } from './processors/my-processor';
+import { createProcessorQuery } from "@powerhousedao/reactor-browser/relational";
+import { MyProcessor } from "./processors/my-processor";
 
 // Create a typed query hook for your processor
 const useTypedQuery = createProcessorQuery(MyProcessor);
@@ -51,8 +52,8 @@ const useTypedQuery = createProcessorQuery(MyProcessor);
 ```typescript
 // Simple query - no parameters needed
 export function useUserList(driveId: string) {
-  return useTypedQuery(driveId, db => {
-    return db.selectFrom('users').selectAll().compile();
+  return useTypedQuery(driveId, (db) => {
+    return db.selectFrom("users").selectAll().compile();
   });
 }
 
@@ -62,12 +63,12 @@ export function useUserById(driveId: string, userId: number) {
     driveId,
     (db, params) => {
       return db
-        .selectFrom('users')
+        .selectFrom("users")
         .selectAll()
-        .where('id', '=', params.userId)
+        .where("id", "=", params.userId)
         .compile();
     },
-    { userId }
+    { userId },
   );
 }
 ```
@@ -107,8 +108,8 @@ function UserList({ driveId }: { driveId: string }) {
 
 ```typescript
 function createProcessorQuery<Schema>(
-  ProcessorClass: RelationalDbProcessorClass<Schema>
-): TypedQueryHook<Schema>
+  ProcessorClass: RelationalDbProcessorClass<Schema>,
+): TypedQueryHook<Schema>;
 ```
 
 ### Description
@@ -118,8 +119,8 @@ Creates a typed query hook factory for a specific processor class. This is the m
 ### Usage Example
 
 ```typescript
-import { createProcessorQuery } from '@powerhousedao/reactor-browser/relational';
-import { MyProcessor } from './processors/my-processor';
+import { createProcessorQuery } from "@powerhousedao/reactor-browser/relational";
+import { MyProcessor } from "./processors/my-processor";
 
 // Create a typed query hook for your processor
 const useTypedQuery = createProcessorQuery(MyProcessor);
@@ -127,7 +128,7 @@ const useTypedQuery = createProcessorQuery(MyProcessor);
 // Use it to create specific query hooks
 export const useUsers = (driveId: string) => {
   return useTypedQuery(driveId, (db) => {
-    return db.selectFrom('users').selectAll().compile();
+    return db.selectFrom("users").selectAll().compile();
   });
 };
 
@@ -137,12 +138,12 @@ export const useUsersByStatus = (driveId: string, status: string) => {
     driveId,
     (db, params) => {
       return db
-        .selectFrom('users')
+        .selectFrom("users")
         .selectAll()
-        .where('status', '=', params.status)
+        .where("status", "=", params.status)
         .compile();
     },
-    { status }
+    { status },
   );
 };
 ```
@@ -150,6 +151,7 @@ export const useUsersByStatus = (driveId: string, status: string) => {
 ### Parameters
 
 The returned hook accepts:
+
 - `driveId`: The ID of the drive
 - `queryCallback`: Function that receives the database instance and optional parameters
 - `parameters`: Optional parameters for the query
@@ -158,9 +160,9 @@ The returned hook accepts:
 
 ```typescript
 {
-  isLoading: boolean;      // True while loading or retrying
-  error: Error | null;     // Any error that occurred
-  result: LiveQueryResults<T> | null;  // Query results with live updates
+  isLoading: boolean; // True while loading or retrying
+  error: Error | null; // Any error that occurred
+  result: LiveQueryResults<T> | null; // Query results with live updates
 }
 ```
 
@@ -181,7 +183,7 @@ The returned hook accepts:
 ### Hook Name and Signature
 
 ```typescript
-function useRelationalDb<Schema>(): IRelationalDb<Schema>
+function useRelationalDb<Schema>(): IRelationalDb<Schema>;
 ```
 
 ### Description
@@ -195,20 +197,20 @@ import { useRelationalDb } from '@powerhousedao/reactor-browser/relational';
 
 function DatabaseOperations() {
   const { db, isLoading, error } = useRelationalDb<MyDatabase>();
-  
+
   const createUser = async (name: string, email: string) => {
     if (!db) return;
-    
+
     // Direct database operations
     await db
       .insertInto('users')
       .values({ name, email })
       .execute();
   };
-  
+
   if (isLoading) return <div>Database initializing...</div>;
   if (error) return <div>Database error: {error.message}</div>;
-  
+
   return (
     <button onClick={() => createUser('John', 'john@example.com')}>
       Create User
@@ -225,9 +227,9 @@ function DatabaseOperations() {
 
 ```typescript
 {
-  db: EnhancedKysely<Schema> | null;    // Enhanced Kysely instance with live capabilities
-  isLoading: boolean;                   // True while database is initializing
-  error: Error | null;                  // Any initialization error
+  db: EnhancedKysely<Schema> | null; // Enhanced Kysely instance with live capabilities
+  isLoading: boolean; // True while database is initializing
+  error: Error | null; // Any initialization error
 }
 ```
 
@@ -254,9 +256,12 @@ function DatabaseOperations() {
 
 ```typescript
 function useRelationalQuery<Schema, T, TParams>(
-  queryCallback: (db: EnhancedKysely<Schema>, parameters?: TParams) => QueryCallbackReturnType,
-  parameters?: TParams
-): QueryResult<T>
+  queryCallback: (
+    db: EnhancedKysely<Schema>,
+    parameters?: TParams,
+  ) => QueryCallbackReturnType,
+  parameters?: TParams,
+): QueryResult<T>;
 ```
 
 ### Description
@@ -277,10 +282,10 @@ function UserCount() {
         .compile();
     }
   );
-  
+
   if (isLoading) return <div>Loading...</div>;
   if (error) return <div>Error: {error.message}</div>;
-  
+
   return <div>User count: {result?.rows[0]?.count ?? 0}</div>;
 }
 ```
@@ -294,9 +299,9 @@ function UserCount() {
 
 ```typescript
 {
-  result: LiveQueryResults<T> | null;  // Live query results
-  isLoading: boolean;                  // Combined loading state
-  error: Error | null;                 // Any error that occurred
+  result: LiveQueryResults<T> | null; // Live query results
+  isLoading: boolean; // Combined loading state
+  error: Error | null; // Any error that occurred
 }
 ```
 
@@ -330,25 +335,25 @@ The `createProcessorQuery` hook automatically handles parameter changes and memo
 
 ```typescript
 function useSearchResults() {
-  const [searchTerm, setSearchTerm] = useState('');
-  const [category, setCategory] = useState('all');
+  const [searchTerm, setSearchTerm] = useState("");
+  const [category, setCategory] = useState("all");
 
   // Query automatically updates when searchTerm or category changes
   const result = useTypedQuery(
     (db, params) => {
-      let query = db.selectFrom('products').selectAll();
-      
+      let query = db.selectFrom("products").selectAll();
+
       if (params.searchTerm) {
-        query = query.where('name', 'like', `%${params.searchTerm}%`);
+        query = query.where("name", "like", `%${params.searchTerm}%`);
       }
-      
-      if (params.category !== 'all') {
-        query = query.where('category', '=', params.category);
+
+      if (params.category !== "all") {
+        query = query.where("category", "=", params.category);
       }
-      
+
       return query.compile();
     },
-    { searchTerm, category }
+    { searchTerm, category },
   );
 
   return { result, setSearchTerm, setCategory };
@@ -390,7 +395,7 @@ function useCustomUserStats() {
         LEFT JOIN posts p ON u.id = p.author_id 
         GROUP BY u.id, u.name
         ORDER BY post_count DESC
-      `
+      `,
     };
   });
 }
@@ -407,10 +412,10 @@ function useUserPostsByDateRange(startDate: string, endDate: string) {
           WHERE p.created_at BETWEEN $1 AND $2
           ORDER BY p.created_at DESC
         `,
-        parameters: [params.startDate, params.endDate]
+        parameters: [params.startDate, params.endDate],
       };
     },
-    { startDate, endDate }
+    { startDate, endDate },
   );
 }
 ```
@@ -438,16 +443,16 @@ Use Kysely's join capabilities within your query callbacks:
 
 ```typescript
 function useUsersWithPosts() {
-  return useTypedQuery(db => {
+  return useTypedQuery((db) => {
     return db
-      .selectFrom('users')
-      .leftJoin('posts', 'users.id', 'posts.author_id')
+      .selectFrom("users")
+      .leftJoin("posts", "users.id", "posts.author_id")
       .select([
-        'users.id',
-        'users.name',
-        'users.email',
-        'posts.title as post_title',
-        'posts.content as post_content'
+        "users.id",
+        "users.name",
+        "users.email",
+        "posts.title as post_title",
+        "posts.content as post_content",
       ])
       .compile();
   });
@@ -458,21 +463,21 @@ function useUserDashboardData(userId: number) {
   return useTypedQuery(
     (db, params) => {
       return db
-        .selectFrom('users')
-        .leftJoin('posts', 'users.id', 'posts.author_id')
-        .leftJoin('comments', 'posts.id', 'comments.post_id')
+        .selectFrom("users")
+        .leftJoin("posts", "users.id", "posts.author_id")
+        .leftJoin("comments", "posts.id", "comments.post_id")
         .select([
-          'users.id',
-          'users.name',
-          'users.email',
-          db.fn.count('posts.id').as('post_count'),
-          db.fn.count('comments.id').as('comment_count')
+          "users.id",
+          "users.name",
+          "users.email",
+          db.fn.count("posts.id").as("post_count"),
+          db.fn.count("comments.id").as("comment_count"),
         ])
-        .where('users.id', '=', params.userId)
-        .groupBy(['users.id', 'users.name', 'users.email'])
+        .where("users.id", "=", params.userId)
+        .groupBy(["users.id", "users.name", "users.email"])
         .compile();
     },
-    { userId }
+    { userId },
   );
 }
 ```
@@ -533,39 +538,32 @@ Create focused, reusable hooks for different data access patterns:
 ```typescript
 // ✅ Good - Focused, reusable hooks
 export function useUsers() {
-  return useTypedQuery(db => 
-    db.selectFrom('users').selectAll().compile()
-  );
+  return useTypedQuery((db) => db.selectFrom("users").selectAll().compile());
 }
 
 export function useUserById(id: number) {
   return useTypedQuery(
-    (db, params) => db
-      .selectFrom('users')
-      .selectAll()
-      .where('id', '=', params.id)
-      .compile(),
-    { id }
+    (db, params) =>
+      db.selectFrom("users").selectAll().where("id", "=", params.id).compile(),
+    { id },
   );
 }
 
 export function useActiveUsers() {
-  return useTypedQuery(db => 
-    db.selectFrom('users')
-      .selectAll()
-      .where('active', '=', true)
-      .compile()
+  return useTypedQuery((db) =>
+    db.selectFrom("users").selectAll().where("active", "=", true).compile(),
   );
 }
 
 // ❌ Avoid - Too generic or complex
 export function useEverything() {
-  return useTypedQuery(db => 
-    db.selectFrom('users')
-      .leftJoin('posts', 'users.id', 'posts.author_id')
-      .leftJoin('comments', 'posts.id', 'comments.post_id')
+  return useTypedQuery((db) =>
+    db
+      .selectFrom("users")
+      .leftJoin("posts", "users.id", "posts.author_id")
+      .leftJoin("comments", "posts.id", "comments.post_id")
       .selectAll() // Too much data
-      .compile()
+      .compile(),
   );
 }
 ```
@@ -600,7 +598,7 @@ function UserList() {
 // ❌ Avoid - Missing error handling
 function BadUserList() {
   const { result } = useUsers();
-  
+
   return (
     <ul>
       {result?.rows.map(user => (
@@ -625,32 +623,35 @@ function BadUserList() {
 ```typescript
 // ✅ Good - Focused query
 function useUserNames() {
-  return useTypedQuery(db => 
-    db.selectFrom('users')
-      .select(['id', 'name'])  // Only what you need
-      .compile()
+  return useTypedQuery((db) =>
+    db
+      .selectFrom("users")
+      .select(["id", "name"]) // Only what you need
+      .compile(),
   );
 }
 
 // ✅ Good - Stable parameters
 function useUsersByStatus(status: string) {
   return useTypedQuery(
-    (db, params) => db
-      .selectFrom('users')
-      .selectAll()
-      .where('status', '=', params.status)
-      .compile(),
-    { status } // Simple, stable parameter
+    (db, params) =>
+      db
+        .selectFrom("users")
+        .selectAll()
+        .where("status", "=", params.status)
+        .compile(),
+    { status }, // Simple, stable parameter
   );
 }
 
 // ❌ Avoid - Unnecessary data
 function useEverythingAboutUsers() {
-  return useTypedQuery(db => 
-    db.selectFrom('users')
-      .leftJoin('posts', 'users.id', 'posts.author_id')
+  return useTypedQuery((db) =>
+    db
+      .selectFrom("users")
+      .leftJoin("posts", "users.id", "posts.author_id")
       .selectAll() // Too much data
-      .compile()
+      .compile(),
   );
 }
 ```
@@ -665,9 +666,11 @@ function useEverythingAboutUsers() {
 <summary>My query results aren't updating when I expect them to</summary>
 
 ### Problem
+
 Your query results don't update when you expect them to, even though you've changed parameters.
 
 ### Solution
+
 Check that your parameters are actually changing in content, not just reference:
 
 ```typescript
@@ -690,6 +693,7 @@ const result = useTypedQuery(
 ```
 
 ### Debugging Tips
+
 - Log your parameters to see if they're actually changing
 - Check the `isLoading` state to see if queries are re-running
 - Use React DevTools to inspect hook state changes
@@ -702,27 +706,29 @@ const result = useTypedQuery(
 <summary>Getting TypeScript errors with my queries</summary>
 
 ### Problem
+
 TypeScript is showing errors about query return types or database schema.
 
 ### Solution
+
 Make sure your callback returns the correct type:
 
 ```typescript
 // ✅ Good - Returns QueryCallbackReturnType
-const result = useTypedQuery(db => {
-  return db.selectFrom('users').selectAll().compile(); // Has sql property
+const result = useTypedQuery((db) => {
+  return db.selectFrom("users").selectAll().compile(); // Has sql property
 });
 
 // ❌ Error - Missing .compile()
-const result = useTypedQuery(db => {
-  return db.selectFrom('users').selectAll(); // No sql property
+const result = useTypedQuery((db) => {
+  return db.selectFrom("users").selectAll(); // No sql property
 });
 
 // ✅ Good - Raw SQL format
 const result = useTypedQuery(() => {
   return {
-    sql: 'SELECT * FROM users',
-    parameters: []
+    sql: "SELECT * FROM users",
+    parameters: [],
   };
 });
 ```
@@ -735,9 +741,11 @@ const result = useTypedQuery(() => {
 <summary>My queries are running too frequently or causing lag</summary>
 
 ### Problem
+
 Your queries are running more often than expected, causing performance issues.
 
 ### Solution
+
 Check for unstable parameters or overly complex queries:
 
 ```typescript
@@ -745,7 +753,7 @@ Check for unstable parameters or overly complex queries:
 function BadComponent({ user }) {
   const result = useTypedQuery(
     (db, params) => /* query */,
-    { 
+    {
       filter: { status: 'active', dept: user.department } // New object each render
     }
   );
@@ -757,7 +765,7 @@ function GoodComponent({ user }) {
     status: 'active',
     dept: user.department
   }), [user.department]);
-  
+
   const result = useTypedQuery(
     (db, params) => /* query */,
     { filter }
@@ -768,9 +776,9 @@ function GoodComponent({ user }) {
 function BetterComponent({ user }) {
   const result = useTypedQuery(
     (db, params) => /* query */,
-    { 
-      status: 'active', 
-      dept: user.department 
+    {
+      status: 'active',
+      dept: user.department
     }
   );
 }
@@ -789,4 +797,4 @@ function BetterComponent({ user }) {
 
 - [`useDocuments`](/academy/APIReferences/ReactHooks#usedocuments) - Working with Powerhouse documents
 - [`useDrives`](/academy/APIReferences/ReactHooks#usedrives) - Managing document drives
-- [`useSelectedDocument`](/academy/APIReferences/ReactHooks#useselecteddocument) - Document selection state 
+- [`useSelectedDocument`](/academy/APIReferences/ReactHooks#useselecteddocument) - Document selection state