Add docs for rowsRead and rowsWritten

Author: G4brym

docs/databases/d1.md

@@ -166,3 +166,64 @@ export default {
 In this example, we create an array of `Query` objects using `getQueryAll()` from individual `insert` operations and then execute them all in a single batch using `qb.batchExecute()`. This is more efficient than executing each insert query separately.
 
 **Note:** Batch operations in D1 have limitations. Refer to the Cloudflare D1 documentation for details on batch operation constraints.
+
+## Execution Metrics
+
+When you execute a query with `D1QB`, the returned result object contains metrics about the database operation. This includes `rowsRead` and `rowsWritten`, which provide insight into the impact of your query.
+
+-   `rowsRead`: The number of rows read from the database to execute the query.
+-   `rowsWritten`: The number of rows written (inserted, updated, or deleted) to the database.
+
+These metrics can be useful for monitoring and optimizing your database queries.
+
+**Example: Accessing Execution Metrics**
+
+```typescript
+import { D1QB } from 'workers-qb';
+
+export interface Env {
+  DB: D1Database;
+}
+
+type User = {
+  id: number;
+  name: string;
+};
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionCountext): Promise<Response> {
+    const qb = new D1QB(env.DB);
+
+    // Example of an insert operation
+    const insertResult = await qb.insert<User>({
+      tableName: 'users',
+      data: { name: 'John Doe' },
+      returning: ['id', 'name'],
+    }).execute();
+
+    console.log(`Rows written: ${insertResult.rowsWritten}`); // e.g., "Rows written: 1"
+
+    // Example of a select operation
+    const selectResult = await qb.fetchAll<User>({
+      tableName: 'users',
+    }).execute();
+
+    console.log(`Rows read: ${selectResult.rowsRead}`); // e.g., "Rows read: 5"
+
+    return Response.json({
+      insertedUser: insertResult.results,
+      allUsers: selectResult.results,
+      metrics: {
+        insert: {
+          rowsWritten: insertResult.rowsWritten,
+          rowsRead: insertResult.rowsRead,
+        },
+        select: {
+          rowsWritten: selectResult.rowsWritten,
+          rowsRead: selectResult.rowsRead,
+        },
+      },
+    });
+  },
+};
+```

docs/databases/do.md

@@ -201,3 +201,66 @@ export class MyDurableObject extends DurableObject {
 In this example, `fetchAll` is called with `lazy: true` and the generic type specified as `<Item, true>`. The `execute()` method returns a result object where `results` is an `AsyncIterable<Item>`. You can then use an `for await...of` loop to iterate through the results asynchronously, processing items one by one as they are fetched from the database.
 
 **Note:** Lazy queries are particularly useful in Durable Objects to avoid blocking the event loop for extended periods when dealing with large datasets. However, keep in mind that each iteration still involves synchronous storage operations. Optimize your processing logic within the loop to maintain responsiveness.
+
+## Execution Metrics
+
+When you execute a query with `DOQB`, the returned result object contains metrics about the database operation. This includes `rowsRead` and `rowsWritten`, which provide insight into the impact of your query.
+
+-   `rowsRead`: The number of rows read from the database to execute the query.
+-   `rowsWritten`: The number of rows written (inserted, updated, or deleted) to the database.
+
+These metrics can be useful for monitoring and optimizing your database queries within your Durable Object.
+
+**Example: Accessing Execution Metrics**
+
+```typescript
+import { DOQB } from 'workers-qb';
+
+export class MyDurableObject extends DurableObject {
+  #qb: DOQB;
+
+  constructor(state: DurableObjectState, env: Env) {
+    super(state, env);
+    this.#qb = new DOQB(this.storage.sql);
+    // ... table creation ...
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    type Item = {
+      id: number;
+      name: string;
+    };
+
+    // Example of an insert operation
+    const insertResult = this.#qb.insert<Item>({
+      tableName: 'items',
+      data: { name: 'Durable Item' },
+      returning: ['id', 'name'],
+    }).execute();
+
+    console.log(`Rows written: ${insertResult.rowsWritten}`); // e.g., "Rows written: 1"
+
+    // Example of a select operation
+    const selectResult = this.#qb.fetchAll<Item>({
+      tableName: 'items',
+    }).execute();
+
+    console.log(`Rows read: ${selectResult.rowsRead}`); // e.g., "Rows read: 3"
+
+    return Response.json({
+      insertedItem: insertResult.results,
+      allItems: selectResult.results,
+      metrics: {
+        insert: {
+          rowsWritten: insertResult.rowsWritten,
+          rowsRead: insertResult.rowsRead,
+        },
+        select: {
+          rowsWritten: selectResult.rowsWritten,
+          rowsRead: selectResult.rowsRead,
+        },
+      },
+    });
+  }
+}
+```

src/databases/d1.ts

@@ -4,9 +4,15 @@ import { D1Result, QueryBuilderOptions } from '../interfaces'
 import { MigrationOptions, asyncMigrationsBuilder } from '../migrations'
 import { Query } from '../tools'
 
+interface D1Database {
+  prepare: any
+  batch: any
+  exec: any
+}
+
 export class D1QB extends QueryBuilder<D1Result> {
   public db: any
-  constructor(db: any, options?: QueryBuilderOptions) {
+  constructor(db: D1Database, options?: QueryBuilderOptions) {
     super(options)
     this.db = db
   }

src/databases/do.ts

@@ -5,7 +5,7 @@ import { syncLoggerWrapper } from '../logger'
 import { MigrationOptions, syncMigrationsBuilder } from '../migrations'
 import { Query } from '../tools'
 
-export interface SqlStorage {
+interface SqlStorage {
   exec: any
   prepare: any
   Cursor: any

tests/unit/batch.test.ts

@@ -17,6 +17,9 @@ describe('Batch Builder', () => {
       batch: (stmts: any) => {
         return Promise.resolve(stmts.map((stmt: any) => stmt.all()))
       },
+      exec: () => {
+        throw new Error('not implemented')
+      },
     }
 
     const qb = new D1QB(dbMock)