Improve documentation and update VitePress config

This commit includes the following changes:

- Updated VitePress configuration to render outlines for h2 and h3 headings.
- Removed references to subqueries within other queries from `docs/advanced-queries.md` as this feature is not currently supported.
- Reviewed and made minor improvements to all documentation files, including:
    - Clarifying explanations and code examples.
    - Fixing typos and ensuring consistency.
    - Improving the structure and readability of examples, particularly in `docs/databases/do.md`.

Author: google-labs-jules[bot]

docs/.vitepress/config.mts

@@ -9,6 +9,7 @@ export default defineConfig({
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     logo: 'https://raw.githubusercontent.com/G4brym/workers-qb/refs/heads/main/docs/assets/logo-icon.png',
+    outline: [2, 3],
     nav: [
       {text: 'Home', link: '/'},
       {text: 'Docs', link: '/introduction'}

docs/advanced-queries.md

@@ -87,39 +87,6 @@ const userProductCombinations = await qb.fetchAll<UserAndProduct>({
 console.log('User and product combinations:', userProductCombinations.results);
 ```
 
-### JOIN with Subqueries
-
-You can also use subqueries as tables in your JOIN clauses.
-
-```typescript
-import { D1QB } from 'workers-qb';
-
-// ... (D1QB initialization) ...
-
-type UserWithOrderCount = {
-  userName: string;
-  orderCount: number;
-};
-
-const usersWithOrderCounts = await qb.fetchAll<UserWithOrderCount>({
-  tableName: 'users',
-  fields: ['users.name AS userName', 'orderCounts.count AS orderCount'],
-  join: {
-    type: 'LEFT',
-    table: qb.select('orders') // Subquery using select builder
-      .fields('user_id, COUNT(*) AS count')
-      .groupBy('user_id')
-      .getQueryAll(), // Get the Query object from SelectBuilder
-    alias: 'orderCounts',
-    on: 'users.id = orderCounts.user_id',
-  },
-}).execute();
-
-console.log('Users with order counts:', usersWithOrderCounts.results);
-```
-
-In this example, a subquery is built using `qb.select('orders')...getQueryAll()` to calculate the order count for each user. This subquery is then joined with the `users` table.
-
 ## Modular Select Queries
 
 `workers-qb` provides a modular `select()` builder for constructing SELECT queries in a chainable and readable manner.
@@ -179,7 +146,7 @@ console.log('Users info:', usersInfo.results);
 
 The `SelectBuilder` provides methods to execute the built query and retrieve results:
 
-*   `.execute()`: Executes the query and returns `ArrayResult` or `OneResult` based on the query configuration (implicitly calls `fetchAll` or `fetchOne` based on limit, etc. - in this case `fetchAll`).
+*   `.execute()`: Executes the query and returns `ArrayResult` or `OneResult` based on the nature of the constructed query (e.g., if `.limit(1)` is used, it might behave like `fetchOne`).
 *   `.all()`: Explicitly executes as `fetchAll` and returns `ArrayResult`.
 *   `.one()`: Explicitly executes as `fetchOne` and returns `OneResult`.
 *   `.count()`: Executes a `COUNT(*)` query based on the current builder configuration (ignoring fields, limit, offset, orderBy) and returns `CountResult`.
@@ -258,11 +225,6 @@ import { D1QB } from 'workers-qb';
 
 // ... (D1QB initialization) ...
 
-const usersInRoles = await qb.fetchAll({
-  tableName: 'users',
-  where: qb.select('roles').fields('id').where('is_admin = ?', true).getQueryAll(), // Subquery to get admin role IDs
-}).execute() // Error! 'where' option should be 'whereIn' for IN clause
-
 const usersInSpecificRoles = await qb.select('users')
   .whereIn('role_id', [1, 2, 3]) // Filter users with role_id in [1, 2, 3]
   .execute();
@@ -276,8 +238,6 @@ const usersInSpecificRolesMultipleColumns = await qb.select('users')
 console.log('Users in specific role and department combinations:', usersInSpecificRolesMultipleColumns.results);
 ```
 
-**Important:**  Note the corrected example using `whereIn` method on the `SelectBuilder` for IN clauses, instead of trying to put a subquery directly into the `where` option, which is not intended for `IN` clause subqueries in this builder's API design.
-
 ## Group By and Having
 
 ### Group By Clause

docs/basic-queries.md

@@ -74,7 +74,7 @@ export default {
 Use the `createTable` method to define and create a new table. You need to specify the `tableName` and the `schema` as a string defining the table columns and their types.
 
 ```typescript
-import { D1QB } from 'workers-qb';
+import { D1QB, Raw } from 'workers-qb';
 
 // ... (D1QB initialization) ...
 
@@ -254,7 +254,7 @@ console.log('Insert attempted, row replaced if email exists.');
 For more complex conflict resolution, you can perform an UPSERT operation, updating specific columns if a conflict occurs. Use `onConflict` with an object to define the columns causing conflict, the data to update, and optional `where` conditions for the update.
 
 ```typescript
-import { D1QB } from 'workers-qb';
+import { D1QB, Raw } from 'workers-qb'; // Ensure Raw is imported here
 
 // ... (D1QB initialization) ...
 
@@ -413,13 +413,13 @@ import { D1QB } from 'workers-qb';
 
 // ... (D1QB initialization) ...
 
-type UpdatedUser = {
+type User = { // Assuming User type includes id, name, email
   id: number;
   name: string;
   email: string;
 };
 
-const updatedUser = await qb.update<UpdatedUser>({
+const updatedUser = await qb.update<User>({
   tableName: 'users',
   data: {
     name: 'Corrected John Doe',
@@ -488,13 +488,13 @@ import { D1QB } from 'workers-qb';
 
 // ... (D1QB initialization) ...
 
-type DeletedUser = {
+type User = { // Assuming User type includes id, name, email
   id: number;
   name: string;
   email: string;
 };
 
-const deletedUser = await qb.delete<DeletedUser>({
+const deletedUser = await qb.delete<User>({
   tableName: 'users',
   where: {
     conditions: 'id = ?',

docs/databases/byodb.md

@@ -99,10 +99,10 @@ export class SQLiteQB extends QueryBuilder<SQLiteResultWrapper, false> { // Sync
 
 **To create a production-ready adapter for your database:**
 
-1.  **Choose a suitable database client library** for your target database in JavaScript/TypeScript (if one exists for Cloudflare Workers environment).
-2.  **Study the documentation of your chosen database and its client library.**
-3.  **Implement `execute`, `batchExecute`, and `lazyExecute` methods** in your custom QueryBuilder class, handling connection, query execution, parameter binding, error handling, and result formatting according to your database's specifics.
-4.  **Consider adding migration support** by extending or adapting `syncMigrationsBuilder` or `asyncMigrationsBuilder` if needed.
-5.  **Thoroughly test your custom adapter** with various query types and scenarios.
+1.  **Choose a suitable database client library** for your target database in JavaScript/TypeScript (if one exists for the Cloudflare Workers environment).
+2.  **Study the documentation of your chosen database and its client library** thoroughly.
+3.  **Implement `execute`, `batchExecute` (if applicable), and `lazyExecute` (if applicable) methods** in your custom `QueryBuilder` class. This involves handling connections, query execution, parameter binding, error management, and transforming results into the `workers-qb` expected formats.
+4.  **Consider adding migration support** by extending or adapting `syncMigrationsBuilder` or `asyncMigrationsBuilder` if your database requires schema management.
+5.  **Thoroughly test your custom adapter** with a comprehensive suite of query types and edge cases.
 
 By creating custom database adapters, you can extend the reach of `workers-qb` to support a wide variety of SQL and SQL-like databases in your Cloudflare Worker projects.

docs/databases/do.md

@@ -27,18 +27,47 @@ Within your Durable Object class, you can access the `DurableObjectStorage` inst
 ```typescript
 import { DOQB } from 'workers-qb';
 
+// Define Env if it's used for configuration, otherwise it might not be needed for basic DOQB
+export interface Env {
+  // Example: You might have environment variables here for other purposes
+}
+
 export class MyDurableObject extends DurableObject {
+  #qb: DOQB; // Make qb a class member
+
   constructor(state: DurableObjectState, env: Env) {
     super(state, env);
-    // ... other initialization ...
+    this.#qb = new DOQB(this.storage.sql); // Initialize DOQB with DurableObjectStorage
+
+    // It's common to run schema migrations or table creations in the constructor,
+    // wrapped in blockConcurrencyWhile to ensure they complete before other operations.
+    this.ctx.blockConcurrencyWhile(async () => {
+      await this.initializeDB();
+    });
+  }
+
+  async initializeDB() {
+    // Example: Create table if it doesn't exist
+    // Note: .execute() is synchronous for DOQB, but blockConcurrencyWhile expects a Promise
+    this.#qb.createTable({
+        tableName: 'items', // Example table
+        ifNotExists: true,
+        schema: `
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            value TEXT
+        `
+    }).execute();
   }
 
   async fetch(request: Request): Promise<Response> {
-    const qb = new DOQB(this.storage.sql); // Initialize DOQB with DurableObjectStorage
+    // Now use this.#qb for queries
+    // ... your queries using this.#qb ...
 
-    // ... your queries using qb ...
+    // Example: Fetching an item (replace with actual logic)
+    const items = this.#qb.fetchAll({ tableName: 'items' }).execute();
 
-    return new Response("Durable Object queries executed");
+    return new Response(`Durable Object queries executed. Items count: ${items.results?.length}`);
   }
 }
 ```
@@ -56,20 +85,32 @@ All basic and advanced query operations described in [Basic Queries](../basic-qu
 ```typescript
 import { DOQB } from 'workers-qb';
 
+// Define Env if it's used for configuration
+export interface Env { /* ... */ }
+
 export class MyDurableObject extends DurableObject {
-  async fetch(request: Request): Promise<Response> {
-    const qb = new DOQB(this.storage.sql);
+  #qb: DOQB;
 
-    // Create table (if not exists) - typically in Durable Object's constructor or first fetch
-    qb.createTable({
-        tableName: 'items',
-        ifNotExists: true,
-        schema: `
-            id INTEGER PRIMARY KEY AUTOINCREMENT,
-            name TEXT NOT NULL,
-            value TEXT
-        `
-    }).execute();
+  constructor(state: DurableObjectState, env: Env) {
+    super(state, env);
+    this.#qb = new DOQB(this.storage.sql);
+
+    this.ctx.blockConcurrencyWhile(async () => {
+      // Create table (if not exists) - good practice in constructor
+      this.#qb.createTable({
+          tableName: 'items',
+          ifNotExists: true,
+          schema: `
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              name TEXT NOT NULL,
+              value TEXT
+          `
+      }).execute(); // Synchronous execute for DOQB
+    });
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    // qb is now this.#qb
 
     type Item = {
       id: number;
@@ -78,7 +119,7 @@ export class MyDurableObject extends DurableObject {
     };
 
     // Insert an item
-    const insertedItem = qb.insert<Item>({
+    const insertedItem = this.#qb.insert<Item>({
       tableName: 'items',
       data: {
         name: 'Example Item',
@@ -90,7 +131,7 @@ export class MyDurableObject extends DurableObject {
     console.log('Inserted item:', insertedItem.results);
 
     // Fetch all items
-    const allItems = qb.fetchAll<Item>({
+    const allItems = this.#qb.fetchAll<Item>({
       tableName: 'items',
     }).execute();
 
@@ -113,9 +154,20 @@ export class MyDurableObject extends DurableObject {
 ```typescript
 import { DOQB } from 'workers-qb';
 
+// Define Env if it's used for configuration
+export interface Env { /* ... */ }
+
 export class MyDurableObject extends DurableObject {
+  #qb: DOQB;
+
+  constructor(state: DurableObjectState, env: Env) {
+    super(state, env);
+    this.#qb = new DOQB(this.storage.sql);
+    // Assuming table 'items' is created in constructor as shown in the previous example
+  }
+
   async fetch(request: Request): Promise<Response> {
-    const qb = new DOQB(this.storage.sql);
+    // qb is now this.#qb
 
     type Item = {
       id: number;
@@ -124,7 +176,7 @@ export class MyDurableObject extends DurableObject {
     };
 
     // Lazy fetch all items
-    const lazyItemsResult = await qb.fetchAll<Item, true>({ // Note: <Item, true> for lazy fetch
+    const lazyItemsResult = await this.#qb.fetchAll<Item, true>({ // Note: <Item, true> for lazy fetch
       tableName: 'items',
       lazy: true, // Explicitly set lazy: true
     }).execute();

docs/databases/postgresql.md

@@ -163,7 +163,7 @@ While `workers-qb` core doesn't provide a dedicated transaction management API,
 **Example (Conceptual - Transaction Handling Outside `workers-qb` API):**
 
 ```typescript
-import { PGQB } from 'workers-qb';
+import { PGQB, Raw } from 'workers-qb'; // Added Raw import
 import { Client } from 'pg';
 
 export interface Env {

docs/introduction.md

@@ -20,8 +20,7 @@
   *   Bulk inserts
   *   JOIN queries
   *   Modular SELECT query building
-  *   ON CONFLICT handling (for inserts and updates)
-  *   UPSERT support
+  *   ON CONFLICT handling (e.g., IGNORE, REPLACE, UPSERT)
 
 ## Supported Databases
 
@@ -88,7 +87,7 @@ This code snippet demonstrates:
 Explore the comprehensive documentation to learn more about `workers-qb`:
 
 *   **[Basic Queries](basic-queries.md):** Learn the fundamentals of creating, reading, updating, and deleting data.
-*   **[Advanced Queries](advanced-queries.md):** Dive into more complex query structures, including joins, subqueries, and conditional logic.
+*   **[Advanced Queries](advanced-queries.md):** Dive into more complex query structures, including joins and conditional logic.
 *   **[Migrations](migrations.md):** Discover how to manage your database schema using migrations.
 *   **[Type Checking](type-check.md):** Understand how to leverage TypeScript for type-safe database interactions.
 *   **[Database-Specific Guides](databases/d1.md):** Find detailed guides and examples for each supported database.

docs/migrations.md

@@ -13,15 +13,17 @@ Database migrations are scripts that define changes to your database schema. Eac
 
 ## Creating Migration Files
 
-Each migration is defined as an object with a `name` and `sql` property. The `name` should be a unique identifier for the migration. The `sql` property contains the SQL statements to be executed.
+Each migration is defined as an object with a `name` and `sql` property. The `name` should be a unique identifier for the migration (e.g., `YYYYMMDDHHMMSS_descriptive_name` or a sequential number like `0001_descriptive_name`). The `sql` property contains the SQL statements to be executed.
+
+You can organize your migration files as you see fit. For example, you might have one `.ts` file per migration object, or a single file that exports an array of all migration objects.
 
 **Example Migration Structure (in code):**
 
 ```typescript
-// Optinally you can type the migrations with Migration
+// Optionally you can type the migrations with Migration
 import { type Migration } from 'workers-qb';
 
-// migrations/0001_create_users_table.ts (if using separate files)
+// Example: migrations/0001_create_users_table.ts (if using separate files)
 export const createUsersTableMigration = {
     name: '0001_create_users_table',
     sql: `
@@ -88,12 +90,14 @@ export class MyDurableObject extends DurableObject {
 
     this.#qb = new DOQB(this.ctx.storage.sql);
     void this.ctx.blockConcurrencyWhile(async () => {
+      // Assuming 'migrations' is an array of Migration objects defined elsewhere
       const migrationBuilder = this.#qb.migrations({ migrations });
-      migrationBuilder.apply();
+      await migrationBuilder.apply(); // Ensure apply is awaited
     });
   }
 
   async getUsers(): Promise<Array<object>> {
+    // Example method, ensure migrations are applied before accessing tables
     return this.#qb.select('users').all().results
   }
 }
@@ -108,6 +112,7 @@ You can check the status of your migrations using the `getApplied()` and `getUna
 ```typescript
 import { D1QB } from 'workers-qb';
 // ...
+// Assuming 'env' and 'migrations' are defined as in previous examples
 const qb = new D1QB(env.DB);
 const migrationBuilder = qb.migrations({ migrations });
 const appliedMigrations = await migrationBuilder.getApplied();
@@ -119,6 +124,7 @@ const appliedMigrations = await migrationBuilder.getApplied();
 ```typescript
 import { D1QB } from 'workers-qb';
 // ...
+// Assuming 'env' and 'migrations' are defined as in previous examples
 const qb = new D1QB(env.DB);
 const migrationBuilder = qb.migrations({ migrations });
 const unappliedMigrations = await migrationBuilder.getUnapplied();

docs/type-check.md

@@ -27,7 +27,7 @@ You can also leverage type checking when using `insert` and `update` queries, es
 **Example: Type Checking with `insert` and `returning`**
 
 ```typescript
-import { D1QB, Raw } from 'workers-qb';
+import { D1QB } from 'workers-qb'; // Raw removed as it's not used in this specific example
 
 // ... (D1QB initialization and User type definition from previous examples) ...