Updated documentation

Author: cblanquera

.gitignore

@@ -133,4 +133,7 @@ packages/*/tests/database
 
 yarn.lock
 cjs/
-esm/
+esm/
+
+# AI
+.clinerules

README.md

@@ -8,119 +8,232 @@
 
 Super lightweight generic typed SQL query builder, SQL dialects and composite engine. Schema builder, but no ORM. Bring your own database library.
 
- - Node MySQL2
- - Better SQLite3
- - Node PostGres (pg)
- - PGLite
- - CockroachDB
- - NeonDB
- - Vercel Postgres
+## What is Inquire?
 
-## Install
+Inquire is a powerful yet lightweight SQL query builder that provides a unified interface for working with multiple database engines. Unlike traditional ORMs, Inquire focuses on query building and execution while letting you bring your own database connection library. This approach gives you the flexibility to use your preferred database driver while benefiting from a consistent, type-safe query building experience.
+
+## Key Features
+
+- **🪶 Lightweight**: No ORM overhead - just pure query building
+- **🔧 Generic Typed**: Full TypeScript support with generic types for enhanced type safety
+- **🗄️ Multi-Database**: Same expressive query builder pattern for all SQL engines
+- **🔄 Unified Interface**: Consistent API across different database engines
+- **📝 Schema Builder**: Create and modify database schemas programmatically
+- **🔗 Template Strings**: Support for type-safe template string query building
+- **⚡ Transaction Support**: Common transaction pattern across all engines
+- **🎯 Dialect Agnostic**: Query builders work with any supported SQL dialect
+
+## Supported Databases
+
+Inquire supports a wide range of database engines through dedicated connection packages:
+
+- **MySQL** - via `@stackpress/inquire-mysql2` (Node MySQL2)
+- **PostgreSQL** - via `@stackpress/inquire-pg` (Node PostGres pg)
+- **SQLite** - via `@stackpress/inquire-sqlite3` (Better SQLite3)
+- **PGLite** - via `@stackpress/inquire-pglite` (PGLite)
+- **CockroachDB** - Compatible with PostgreSQL adapter
+- **NeonDB** - Compatible with PostgreSQL adapter
+- **Vercel Postgres** - Compatible with PostgreSQL adapter
+- **Supabase** - Compatible with PostgreSQL adapter
+
+## Installation
+
+Install the core library:
 
 ```bash
-$ npm i @stackpress/inquire
+npm install @stackpress/inquire
 ```
 
-## MySQL Connection
+Then install the appropriate database adapter:
+
+```bash
+# For MySQL
+npm install @stackpress/inquire-mysql2 mysql2
+
+# For PostgreSQL
+npm install @stackpress/inquire-pg pg
+
+# For SQLite
+npm install @stackpress/inquire-sqlite3 better-sqlite3
+
+# For PGLite
+npm install @stackpress/inquire-pglite @electric-sql/pglite
+```
 
-```js
+## Quick Start
+
+### MySQL Connection
+
+```typescript
 import mysql from 'mysql2/promise';
 import connect from '@stackpress/inquire-mysql2';
 
-//this is the raw resource, anything you want
+// Create the raw database connection
 const resource = await mysql.createConnection({
   host: 'localhost',
   user: 'root',
   database: 'inquire',
 });
-//this maps the resource to the engine
+
+// Map the resource to the Inquire engine
 const engine = connect(resource);
 ```
 
-## PostGreSQL Connection
+### PostgreSQL Connection
 
-```js
+```typescript
 import { Client, Pool } from 'pg';
 import connect from '@stackpress/inquire-pg';
 
-//this is the raw resource, anything you want
-const connection = usePool 
-  ? await (async () => {
-    const pool = new Pool({
-      database: 'inquire',
-      user: 'postgres'
-    });
-    return await pool.connect();
-  })() 
-  : await (async () => {
-    const resource = new Client({
-      database: 'inquire',
-      user: 'postgres'
-    });
-    await resource.connect();
-    return resource;
-  })();
-
-//this maps the resource to the engine
-const engine = connect(connection);
+// Using a Pool
+const pool = new Pool({
+  database: 'inquire',
+  user: 'postgres'
+});
+const connection = await pool.connect();
+
+// Or using a Client
+const client = new Client({
+  database: 'inquire',
+  user: 'postgres'
+});
+await client.connect();
+
+// Map the resource to the Inquire engine
+const engine = connect(connection); // or connect(client)
 ```
 
-## SQLite Connection
+### SQLite Connection
 
-```js
+```typescript
 import sqlite from 'better-sqlite3';
 import connect from '@stackpress/inquire-sqlite3';
 
-//this is the raw resource, anything you want
+// Create the raw database connection
 const resource = sqlite(':memory:');
-//this maps the resource to the engine
+
+// Map the resource to the Inquire engine
 const engine = connect(resource);
 ```
 
-## Usage
+## Basic Usage
+
+Once you have an engine instance, you can start building and executing queries:
 
-```js
-const create = engine.create('profile')
-  .addField('id', { type: 'INTEGER' })
+```typescript
+// Create a table
+await engine.create('users')
+  .addField('id', { type: 'INTEGER', autoIncrement: true })
   .addField('name', { type: 'VARCHAR', length: 255 })
+  .addField('email', { type: 'VARCHAR', length: 255 })
   .addPrimaryKey('id');
-console.log(create.query());
-console.log(await create);
-
-const insert = engine
-  .insert('profile')
-  .values({ id: '1', name: 'John Doe' });
-console.log(insert.query());
-console.log(JSON.stringify(await insert, null, 2));
-
-const select = engine.select('*').from('profile');
-console.log(select.query());
-console.log(JSON.stringify(await select, null, 2));
-
-const update = engine
-  .update('profile')
-  .set({ name: 'Jane Doe' })
-  .where('id = ?', [ '1' ]);
-console.log(update.query());
-console.log(JSON.stringify(await update, null, 2));
-console.log(JSON.stringify(await select, null, 2));
-
-const remove = engine
-  .delete('profile')
-  .where('id = ?', [ '1' ]);
-console.log(remove.query());
-console.log(JSON.stringify(await remove, null, 2));
-console.log(JSON.stringify(await select, null, 2));
-
-if (usePool && connection instanceof Client === false) {
-  connection.release();
-}
-
-if (connection instanceof Client) {
-  await connection.end();
-}
+
+// Insert data
+await engine
+  .insert('users')
+  .values({ name: 'John Doe', email: 'john@example.com' });
+
+// Select data
+const users = await engine
+  .select('*')
+  .from('users')
+  .where('name = ?', ['John Doe']);
+
+console.log(users);
+
+// Update data
+await engine
+  .update('users')
+  .set({ email: 'john.doe@example.com' })
+  .where('id = ?', [1]);
+
+// Delete data
+await engine
+  .delete('users')
+  .where('id = ?', [1]);
 ```
 
-See [examples](https://github.com/stackpress/inquire/tree/main/examples)
-for other ways to use.
+## Query Builders
+
+Inquire provides comprehensive query builders for all common SQL operations:
+
+- **[Create](./docs/builders/Create.md)** - Create tables and schemas
+- **[Alter](./docs/builders/Alter.md)** - Modify existing tables
+- **[Select](./docs/builders/Select.md)** - Query data with joins, conditions, and aggregations
+- **[Insert](./docs/builders/Insert.md)** - Insert single or multiple records
+- **[Update](./docs/builders/Update.md)** - Update existing records
+- **[Delete](./docs/builders/Delete.md)** - Delete records with conditions
+
+## Template String Queries
+
+For complex queries, you can use type-safe template strings:
+
+```typescript
+type User = {
+  id: number;
+  name: string;
+  email: string;
+};
+
+const userId = 123;
+const results = await engine.sql<User>`
+  SELECT u.*, p.title 
+  FROM users u 
+  LEFT JOIN posts p ON u.id = p.user_id 
+  WHERE u.id = ${userId}
+`;
+// results is typed as User[]
+```
+
+## Transactions
+
+Execute multiple queries in a transaction:
+
+```typescript
+const result = await engine.transaction(async (trx) => {
+  await trx.insert('users').values({ name: 'Alice' });
+  await trx.insert('posts').values({ title: 'Hello World', user_id: 1 });
+  return 'success';
+});
+```
+
+## Type Safety
+
+Inquire is designed with TypeScript in mind, providing full type safety:
+
+```typescript
+type User = {
+  id: number;
+  name: string;
+  email: string;
+};
+
+// Type-safe queries
+const users = await engine.select<User>('*').from('users');
+// users is now typed as User[]
+
+const user = await engine.select<User>('*')
+  .from('users')
+  .where('id = ?', [1])
+  .limit(1);
+// user is typed as User[]
+```
+
+## API Documentation
+
+For detailed API documentation, see:
+
+- **[Engine](./docs/Engine.md)** - Core engine class and methods
+- **[Connection Classes](./docs/Connections.md)** - Database-specific connection implementations
+- **[Query Builders](./docs/builders/README.md)** - Detailed documentation for all query builders
+- **[SQL Dialects](./docs/dialects/README.md)** - Detailed documentation for all SQL dialects
+- **[Examples](./docs/Examples.md)** - Comprehensive usage examples
+
+## Examples
+
+Check out the [examples directory](./examples) for complete working examples with different database engines:
+
+- [MySQL Example](./examples/with-mysql2)
+- [PostgreSQL Example](./examples/with-pg)
+- [SQLite Example](./examples/with-sqlite3)
+- [PGLite Example](./examples/with-pglite)

context7.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://context7.com/schema/context7.json",
+  "projectTitle": "Inquire",
+  "description": "Super lightweight generic typed SQL query builder, SQL dialects and composite engine.",
+  "folders": [],
+  "excludeFolders": [],
+  "excludeFiles": [ "Context.md" ],
+  "rules": [],
+  "previousVersions": []
+}