sqlstack 1.0.13 → 1.0.15

package/readme.md

@@ -1,16 +1,18 @@
 # sqlstack
 
-SQL-first data access for Node.js and TypeScript.
+**SQL-first data access for Node.js and TypeScript.**
 
-Write real SQL, keep it next to your code, and use small, composable decorators to add behavior like defaults, single-row results, and result validation — without ORM complexity.
+sqlstack lets you write real SQL, keep it organized next to your code, and use small, composable decorators to add behavior—all without ORM complexity. Think of it as a thin, decorator-powered layer on top of your database driver.
 
-- Real SQL in `.sql` files
-- TypeScript-first: declare args/return types yourself, or plug in validation/typegen
-- Composable decorators: `@Single`, `@Only`, `@Exist`, `@Defaults`, `@ValidateResult` (order-independent)
-- Minimal runtime: a thin executor layer on top of your DB driver
-- Works with Postgres, MySQL/MariaDB, SQLite (more adapters coming)
-- Structured errors via `SqlStackError` base class
- - Configurable connections via a simple registry (per-class and per-method)
+## Key Features
+
+- **Real SQL in `.sql` files**: No query builders. SQL is the source of truth.
+- **TypeScript-first**: Declare your own argument and return types; optional JSON Schema validation.
+- **Composable decorators**: `@Single`, `@Only`, `@Exist`, `@Defaults`, `@Page`, `@MissingAsNull`, `@ValidateResult`, `@Transform` (order-independent).
+- **Minimal runtime**: A thin executor layer on top of your DB driver (no ORM overhead).
+- **Multi-database support**: Postgres, MySQL/MariaDB, SQLite (more adapters planned).
+- **Structured errors**: Catch specific errors like `ExactlyOneRowError` and `ValidationError`.
+- **Simple configuration**: Register databases once at startup; set per-class and per-method overrides.
 
 ## Install
 
@@ -30,14 +32,107 @@ npm install mysql2         # MySQL / MariaDB
 npm install better-sqlite3 # SQLite
 ```
 
-## Configure Databases
+## Quick Start (5 minutes)
 
-Register your database connections once at application startup and set a default.
+### 1. Register Your Database
 
-boot.ts
+Create a `boot.ts` (or similar) file at your app's entry point:
+
+```ts
+// boot.ts
+import { SqlStackDB } from "sqlstack/registry";
+import { createPgDb } from "sqlstack/adapters";
+
+SqlStackDB
+  .register("primary", createPgDb(process.env.DATABASE_URL!))
+  .setDefault("primary");
+```
+
+Load this file once during app startup.
+
+### 2. Create a Repository Class
+
+```ts
+// users/index.ts
+import { QueryBinder, Query, SqlStackError } from "sqlstack";
+
+@QueryBinder() // looks for .sql files in the same folder by default
+export class UsersRepo {
+  @Query()
+  async findByEmail(_a: { email: string }): Promise<User[]> {
+    throw new SqlStackError("replaced by @Query");
+  }
+}
+```
+
+### 3. Create a `.sql` File
+
+Place the SQL file next to your class:
+
+```
+users/
+  index.ts
+  findByEmail.sql
+```
+
+**users/findByEmail.sql**
+```sql
+SELECT id, email, name, status, created_at
+FROM users
+WHERE email = :email;
+```
+
+### 4. Use Your Repository
+
+```ts
+const repo = new UsersRepo();
+const users = await repo.findByEmail({ email: "alice@example.com" });
+console.log(users); // User[]
+```
+
+That's it! The `@Query` decorator intercepts the method, loads and executes the SQL, and returns results.
+
+---
+
+## How It Works
+
+### Execution Pipeline
+
+sqlstack executes decorators in a **fixed, internal order** regardless of how you stack them:
+
+```
+1. @Defaults        (fill in missing parameter values)
+   ↓
+2. @MissingAsNull   (bind missing named parameters as NULL)
+   ↓
+3. @Query           (execute the SQL)
+   ↓
+4. @Single/@Only/@Exist/@None  (shape the results)
+   ↓
+5. @ValidateResult  (validate against JSON Schema)
+   ↓
+6. @Transform       (map flat rows to nested objects)
+```
+
+You can list decorators in any order; they always execute in this pipeline. See [docs/decorators.md](docs/decorators.md) for details.
+
+### Validation Controls
+
+Validation (via `@ValidateResult`) is **enabled by default**. Control it with environment variables:
+
+- `SQLSTACK_ENABLE_VALIDATION=true` → force validation ON
+- `SQLSTACK_DISABLE_VALIDATION=true` → force validation OFF
+- Otherwise → enabled
+
+---
+
+## Configuration
+
+### Register Databases
+
+Use `SqlStackDB.register(name, dbInstance)` to set up connections:
 
 ```ts
-// boot.ts — register your connections
 import { SqlStackDB } from "sqlstack/registry";
 import { createPgDb, createMysqlDb, createSqliteDb } from "sqlstack/adapters";
 
@@ -48,7 +143,7 @@ SqlStackDB
   .setDefault("primary");
 ```
 
-Adapters can receive either a connection string or an existing driver instance (pool/connection):
+Adapters accept either a connection string or an existing driver instance:
 
 ```ts
 import { Pool as PgPool } from 'pg';
@@ -68,14 +163,15 @@ const sqlite = new BetterSqlite3(':memory:');
 SqlStackDB.register('sqlite-existing', createSqliteDb(sqlite));
 ```
 
-Then, choose a database per repository (class-level default):
+### Set Database per Class
+
+Use `@QueryBinder({ db: "name" })` to set a default database for all methods in a class:
 
 ```ts
 import { QueryBinder, Query, SqlStackError } from "sqlstack";
 
-@QueryBinder({ db: "analytics" }) // class default
+@QueryBinder({ db: "analytics" }) // all methods use "analytics"
 export class ReportsRepo {
-  // Uses "analytics" unless overridden below
   @Query()
   async topPages(_a: { since: string }): Promise<Row[]> {
     throw new SqlStackError("replaced");
@@ -83,13 +179,11 @@ export class ReportsRepo {
 }
 ```
 
-Load `boot.ts` once during app startup (for example, in your server entry).
+### Override Database per Method
 
-Per-method override (use a different DB for a specific query):
+Use `@Query({ db: "name" })` to override the class default for a specific method:
 
 ```ts
-import { QueryBinder, Query, SqlStackError } from "sqlstack";
-
 @QueryBinder({ db: "primary" }) // default for this class
 export class MixedRepo {
   @Query() // uses "primary"
@@ -104,52 +198,15 @@ export class MixedRepo {
 }
 ```
 
-## Quick Start
-
-1) Create a repository class
-
-```ts
-import { QueryBinder, Query, SqlStackError } from "sqlstack";
-
-@QueryBinder() // looks for .sql files in the same folder by default
-export class UsersRepo {
-  @Query()
-  async findByEmail(_a: { email: string }): Promise<User[]> {
-    throw new SqlStackError("replaced by @Query");
-  }
-}
-```
-
-2) Add the SQL file next to your class
-
-```
-users/
-  index.ts
-  findByEmail.sql
-```
-
-findByEmail.sql
-
-```sql
-SELECT id, email, name, status, created_at
-FROM users
-WHERE email = :email;
-```
-
-3) Call your repository
-
-```ts
-const repo = new UsersRepo();
-const rows = await repo.findByEmail({ email: "alice@example.com" });
-```
+---
 
 ## SQL Parameters
 
-Write parameters directly in your `.sql` files and pass values from your method call.
+Pass parameters from your method call to the SQL using named or positional placeholders.
 
-### Named parameters
+### Named Parameters
 
-Use `:name` placeholders that map to properties of a single object argument.
+Use `:name` placeholders in SQL; pass an object from your method:
 
 ```sql
 -- findByEmail.sql
@@ -162,9 +219,9 @@ WHERE email = :email AND status = :status;
 await repo.findByEmail({ email: "alice@example.com", status: "active" });
 ```
 
-### Positional parameters
+### Positional Parameters
 
-Use `:arg1`, `:arg2`, … and pass values by position. Indexing starts at 1.
+Use `:arg1`, `:arg2`, etc. (1-based indexing); pass values by position:
 
 ```sql
 -- findById.sql
@@ -177,11 +234,11 @@ WHERE id = :arg1 AND org_id = :arg2;
 await repo.findById("user-123", "org-456");
 ```
 
-Use either named or positional parameters within a single query (do not mix both).
+**Do not mix named and positional parameters in a single query.**
 
-### Array parameters
+### Array Parameters
 
-Pass arrays to expand into `IN (...)` lists.
+Pass arrays to expand into `IN (...)` lists:
 
 ```sql
 -- listByIds.sql
@@ -194,28 +251,125 @@ WHERE id IN (:ids);
 await repo.listByIds({ ids: ["user-1", "user-2", "user-3"] });
 ```
 
-Note: For empty arrays, prefer an early return in your code (e.g., `if (!ids.length) return [];`) to avoid generating invalid SQL.
+**Tip:** For empty arrays, return early from your method to avoid invalid SQL:
+```ts
+if (!ids.length) return [];
+await repo.listByIds({ ids });
+```
+
+### Null and Undefined
+
+- `null` → SQL `NULL`
+- `undefined` → throws an error; always provide a value or omit the parameter
+
+### Automatic NULL Binding with `@MissingAsNull`
+
+By default, missing or undefined named parameters throw an error. Use `@MissingAsNull` to automatically bind missing parameters as `NULL` instead, enabling partial updates with `COALESCE`/`IFNULL`:
+
+```ts
+import { QueryBinder, MissingAsNull, Query, SqlStackError } from "sqlstack";
+
+@QueryBinder()
+class UsersRepo {
+  @MissingAsNull()
+  @Query({
+    sql: `
+      UPDATE users
+      SET name = COALESCE(:name, name),
+          email = COALESCE(:email, email),
+          status = COALESCE(:status, status)
+      WHERE id = :id
+    `
+  })
+  async updateUserPartial(_a: { id: string; name?: string; email?: string; status?: string }): Promise<any> {
+    throw new SqlStackError("replaced");
+  }
+}
+```
+
+Call with partial arguments:
+```ts
+await repo.updateUserPartial({ id: "u1", name: "Alice Updated" });
+// Only updates name; email and status keep their old values via COALESCE
+```
 
-### Null and undefined
+**Optional: Require Specific Parameters**
 
-- `null` maps to SQL `NULL`.
-- `undefined` is not allowed and will throw; provide a value or omit the parameter entirely.
+Use `@MissingAsNull({ require: ['id'] })` to mark certain parameters as required:
+
+```ts
+@MissingAsNull({ require: ['id'] })
+@Query({
+  sql: `UPDATE users SET name = COALESCE(:name, name) WHERE id = :id`
+})
+async updateUser(_a: { id: string; name?: string }): Promise<any> {
+  throw new SqlStackError("replaced");
+}
+```
+
+If `id` is missing or undefined, an error is thrown. Other parameters default to `NULL`.
+
+**Note:** `@MissingAsNull` only applies to named parameters. Positional parameters (`:arg1`, `:arg2`, etc.) ignore the decorator.
+
+---
 
 ## SQL File Resolution
 
-`@Query()` loads SQL from files based on a simple, predictable rule:
+The `@Query()` decorator locates `.sql` files using a simple, predictable rule. See [docs/file_resolution.md](docs/file_resolution.md) for complete details.
 
-- No argument: resolves from the declaring file’s folder.
-- File path: resolves from `dirname(filePath)`.
-- Folder path: resolves directly from that folder.
+### Default: Same Folder
 
-For each method name, sqlstack looks for `<method>.<dialect>.sql` first, then `<method>.sql`. Dialect suffixes: `.pg.sql`, `.mysql.sql`, `.sqlite.sql`. Resolution and file contents are cached. See docs/file_resolution.md for details.
+No argument to `@Query()` → looks in the same folder as the class file:
+
+```ts
+@QueryBinder()
+class UsersRepo {
+  @Query()
+  async findByEmail(_a: { email: string }): Promise<User[]> {
+    throw new Error();
+  }
+}
+```
+
+File structure:
+```
+users/
+  index.ts
+  findByEmail.sql
+```
+
+### Dialect-Specific Files
+
+sqlstack looks for `<method>.<dialect>.sql` first, then `<method>.sql`:
+
+```
+users/
+  findByEmail.pg.sql    ← Postgres
+  findByEmail.mysql.sql ← MySQL
+  findByEmail.sql       ← fallback (all dialects)
+```
+
+Dialect suffixes: `.pg.sql`, `.mysql.sql`, `.sqlite.sql`.
+
+### Explicit Path
+
+Pass a file or folder path to `@Query()`:
+
+```ts
+@Query(__filename)  // uses this file's directory
+@Query(__dirname)   // uses this folder
+@Query('./sql')     // uses ./sql folder relative to cwd
+```
+
+---
 
 ## Decorators
 
+Use decorators to add behavior to your methods. They compose freely and always execute in the same internal order.
+
 ### `@Defaults`
 
-Provide default parameter values.
+Provide default parameter values:
 
 ```ts
 import { QueryBinder, Defaults, Query, SqlStackError } from "sqlstack";
@@ -230,18 +384,22 @@ class UsersRepo {
 }
 ```
 
-- Calling `repo.listUsers({})` fills `{ status: "active", limit: 10 }`.
+Call with partial arguments:
+```ts
+await repo.listUsers({});  // { status: "active", limit: 10 }
+await repo.listUsers({ status: "inactive" }); // { status: "inactive", limit: 10 }
+```
 
 ### `@Page`
 
-Add pagination parameters `:offset` and `:limit` derived from a page size and a page number. Pages are 1-based by default.
+Add pagination with `:offset` and `:limit` parameters. Pages are 1-based by default:
 
 ```ts
 import { QueryBinder, Page, Query, SqlStackError } from "sqlstack";
 
 @QueryBinder()
 class UsersRepo {
-  @Page(10) // limit = 10, pages are 1-based
+  @Page(10) // limit = 10, pages 1-based
   @Query()
   async listUsers(_a: { page?: number; status?: string }): Promise<User[]> {
     throw new SqlStackError();
@@ -249,17 +407,32 @@ class UsersRepo {
 }
 ```
 
-- Use `:offset` and `:limit` in your SQL files.
-- The current page is read from `page` when passing a named object, or from a trailing options object as the last argument. This works for both named and positional styles:
-  - Named style: `list({ user_id: 1 })` or `list({ user_id: 1 }, { page: 2 })`.
-  - Positional style: `list(userId)` or `list(userId, { page: 2 })`.
-  Only the last argument is checked for `{ page }`.
-  If no page is provided, page defaults to 1 (or 0 when `zeroBase: true`).
-- Zero-based pages are supported with `@Page(10, { zeroBase: true })`.
+Use `:offset` and `:limit` in your SQL:
+
+```sql
+SELECT id, email, name, status
+FROM users
+WHERE status = :status
+ORDER BY created_at DESC
+LIMIT :limit OFFSET :offset;
+```
+
+Call with page:
+```ts
+await repo.listUsers({ status: "active", page: 2 }); // page 2 of 10 per page
+```
+
+**Zero-based pages:** Use `@Page(10, { zeroBase: true })`.
+
+**Trailing options:** Pass `{ page: N }` as the last argument for both named and positional styles:
+```ts
+await repo.list({ user_id: 1 }, { page: 2 });        // named
+await repo.list(userId, { page: 2 });                // positional
+```
 
-### Result shape decorators
+### Result Shape Decorators
 
-Choose a decorator to shape row results without parameters.
+Shape single-query results without parameters:
 
 ```ts
 import { QueryBinder, Single, Only, Exist, None, Query, SqlStackError } from "sqlstack";
@@ -296,9 +469,16 @@ class UsersRepo {
 }
 ```
 
+| Decorator | Input | Output | Throws if |
+|-----------|-------|--------|-----------|
+| `@Single` | `[Row, Row, ...]` | `Row \| null` | — (never) |
+| `@Only` | `[Row]` | `Row` | ≠ 1 row |
+| `@Exist` | `[Row, Row, ...]` | `Row` | 0 rows |
+| `@None` | `[]` | `null` | > 0 rows |
+
 ### `@ValidateResult`
 
-Validate query results with JSON Schema.
+Validate query results against a JSON Schema:
 
 ```ts
 import schema from "./user.row.schema.json" assert { type: "json" };
@@ -315,18 +495,7 @@ class UsersRepo {
 }
 ```
 
- 
-
-## Inline Builders
-
-Intentionally not included. sqlstack prioritizes explicit `.sql` files for clarity and control.
-
-## JSON Schema
-
-Add a JSON Schema file and attach it to a method with `@ValidateResult`.
-
-user.row.schema.json
-
+Example schema:
 ```json
 {
   "type": "object",
@@ -340,121 +509,11 @@ user.row.schema.json
 }
 ```
 
-Usage
+Validation is **enabled by default**; control with `SQLSTACK_ENABLE_VALIDATION` and `SQLSTACK_DISABLE_VALIDATION` environment variables.
 
-```ts
-import schema from "./user.row.schema.json" assert { type: "json" };
-import { QueryBinder, ValidateResult, Query } from "sqlstack";
+### `@Transform`
 
-@QueryBinder()
-class UsersRepo {
-  @ValidateResult(schema)
-  @Query()
-  async listUsers(): Promise<User[]> {
-    // executes and validates each row against the schema
-  }
-}
-```
-
-## Errors
-
-sqlstack provides a base error and specific error types you can import and catch.
-
-```ts
-import { SqlStackError } from "sqlstack";
-import { ExactlyOneRowError, NoRowsError, ValidationError } from "sqlstack/errors";
-
-try {
-  // call repository methods
-} catch (err) {
-  if (err instanceof ExactlyOneRowError) {
-    // @Only: expected exactly one row
-  }
-  if (err instanceof NoRowsError) {
-    // @Exist: expected at least one row
-  }
-  if (err instanceof ValidationError) {
-    // @ValidateResult: schema mismatch
-  }
-  if (err instanceof SqlStackError) {
-    // handle sqlstack-specific failures
-  }
-  throw err;
-}
-```
-
-
-## Philosophy
-
-- SQL-first: SQL is the source of truth. No hidden queries.
-- Decorators as metadata: `@Defaults`, `@Single`, `@Only`, `@Exist`, `@ValidateResult` add labels; execution order is fixed internally, so decorator order doesn’t matter.
-- Escape hatches: Use inline builders for simple CRUD; keep complex SQL in `.sql` files. You stay in control.
-
-### Execution Pipeline
-
-At runtime, decorators execute in a fixed, predictable order regardless of source order:
-
-1) Defaults → 2) Query → 3) Single/Only/Exist → 4) ValidateResult. See docs/decorators.md for the model and examples.
-
-### Validation Controls
-
-- Default: validation is enabled.
-- Env toggles (precedence):
-  - `SQLSTACK_ENABLE_VALIDATION` truthy → force ON (even in production)
-  - else if `SQLSTACK_DISABLE_VALIDATION` truthy → force OFF
-  - else → ON
-
-## Database Support
-
-- Postgres (`pg`)
-- MySQL / MariaDB (`mysql2`)
-- SQLite (`better-sqlite3`)
-
-More adapters are planned.
-
-### Dialect Inference
-
-The binder placeholder style is inferred from the selected database (method → class → registry default). Only override via `@Query({ dialect })` if you need to force a specific dialect.
-
-## License
-
-ISC
- 
-## Result Shape
-
-- SELECT and WITH CTE queries return an array of rows and can be shaped via decorators.
-- INSERT/UPDATE/DELETE return a common object: `{ rowsAffected: number, lastInsertId?: unknown }`.
-- Postgres-only: if a non-SELECT query includes `RETURNING`, the result also includes an optional `returning` array: `{ rowsAffected, returning: Row[] }`.
-
-### Examples
-
-```ts
-import type { WriteResult } from 'sqlstack';
-import { SqlStackDB } from 'sqlstack/registry';
-
-const db = SqlStackDB.get();
-
-// A write returns WriteResult
-const write: WriteResult = await db.query(
-  'UPDATE users SET status = ? WHERE id = ?',
-  ['inactive', 'u1']
-);
-console.log(write.rowsAffected);
-
-// Postgres with RETURNING returns WriteResult & { returning?: any[] }
-// (only has `returning` when RETURNING is present)
-const pgWrite = await db.query(
-  'INSERT INTO users(id,email) VALUES($1,$2) RETURNING id',
-  ['u9', 'nine@example.com']
-);
-if (!Array.isArray(pgWrite) && pgWrite.returning) {
-  console.log(pgWrite.returning[0].id);
-}
-```
-
-## DTO Helper
-
-Turn flat SQL rows into nested objects using a simple spec and the `@Transform` decorator.
+Map flat SQL rows to nested objects using a nesting spec:
 
 ```ts
 import { DTO, Transform, Query, QueryBinder } from 'sqlstack';
@@ -473,7 +532,7 @@ const toMuscleGroup = DTO(
       },
     },
   },
-  { single: true } // default returns an array; set { single: true } to return a single root (or null)
+  { single: true } // default: array; set to return a single root object or null
 );
 
 @QueryBinder()
@@ -494,34 +553,203 @@ class Repo {
 }
 ```
 
-You can also project flat columns into nested properties directly in the spec:
+**Features:**
+- Arbitrary depth: nest collections by adding objects under new keys.
+- Deduplication: nodes are de-duplicated by their `id` at each level.
+- Null-safe: branches with `NULL` child ids are skipped.
+- Order: sibling order follows your SQL `ORDER BY`.
+- Direct mapping: use `'target.path': 'source_column'` to populate nested properties from flat columns.
 
+Example with direct mapping:
 ```ts
-// If a row has: { id: '1', muscle: 'biceps', group: 'arms' }
+// Row: { id: '1', muscle: 'biceps', group: 'arms' }
 const toSimple = DTO({ id: 'id', name: 'muscle', 'group.name': 'group' } as any, { single: true });
-// Result root: { name: 'biceps', group: { name: 'arms' } }
+// Result: { id: '1', name: 'biceps', group: { name: 'arms' } }
 ```
 
-- Arbitrary depth: nest collections by adding objects under new keys.
-- Dedupe: nodes are de-duplicated by their `id` at each level.
-- Null-safe: branches with `NULL` child ids are skipped for that row.
-- Order: sibling order follows your SQL `ORDER BY`.
-- Mapping: put `'target.path': 'source_key'` entries directly in your spec to populate nested properties from flat columns.
+---
+
+## Result Types
+
+### SELECT / WITH CTE
+
+Returns an array of rows, which can be shaped via decorators:
+
+```ts
+@QueryBinder()
+class Repo {
+  @Query()
+  async allUsers(): Promise<User[]> {
+    throw new Error();
+  }
+
+  @Single
+  @Query()
+  async firstUser(): Promise<User | null> {
+    throw new Error();
+  }
+}
+```
+
+### INSERT / UPDATE / DELETE
+
+Returns a result object:
+
+```ts
+import type { WriteResult } from 'sqlstack';
+
+const result: WriteResult = await db.query(
+  'UPDATE users SET status = ? WHERE id = ?',
+  ['inactive', 'u1']
+);
+console.log(result.rowsAffected); // number
+```
+
+**Postgres with RETURNING:**
+
+```ts
+const pgResult = await db.query(
+  'INSERT INTO users(id, email) VALUES($1, $2) RETURNING id',
+  ['u9', 'nine@example.com']
+);
+if (pgResult.returning) {
+  console.log(pgResult.returning[0].id); // 'u9'
+}
+```
+
+Type definition:
+```ts
+type WriteResult = {
+  rowsAffected: number;
+  lastInsertId?: unknown;
+};
+
+type PostgresWriteResult = WriteResult & {
+  returning?: Row[];
+};
+```
+
+---
 
-## Underlying Connections
+## Error Handling
 
-Every `Database` exposes its driver via `conn` so you can drop down to the raw client when needed:
+sqlstack provides a base error class and specific error types. Import and catch as needed:
+
+```ts
+import { SqlStackError } from "sqlstack";
+import { ExactlyOneRowError, NoRowsError, ValidationError } from "sqlstack/errors";
+
+try {
+  const user = await repo.findByEmail({ email: "alice@example.com" });
+} catch (err) {
+  if (err instanceof ExactlyOneRowError) {
+    console.log("@Only: expected exactly one row, got a different number");
+  } else if (err instanceof NoRowsError) {
+    console.log("@Exist: expected at least one row, got none");
+  } else if (err instanceof ValidationError) {
+    console.log("@ValidateResult: row did not match schema");
+  } else if (err instanceof SqlStackError) {
+    console.log("Generic sqlstack error");
+  } else {
+    console.log("Unknown error:", err);
+  }
+}
+```
+
+Available error classes:
+- `SqlStackError` — base class for all sqlstack errors
+- `ExactlyOneRowError` — thrown by `@Only` when row count ≠ 1
+- `NoRowsError` — thrown by `@Exist` when no rows found
+- `ValidationError` — thrown by `@ValidateResult` on schema mismatch
+- Database driver errors — pass through unchanged
+
+---
+
+## Inline SQL
+
+For simple or dynamic queries, use `@Query({ sql: "..." })` with inline SQL:
+
+```ts
+@QueryBinder()
+class Repo {
+  @Query({ sql: `
+    SELECT id, email, name
+    FROM users
+    WHERE email = :email
+  ` })
+  async findByEmail(_a: { email: string }): Promise<User[]> {
+    throw new Error("replaced");
+  }
+}
+```
+
+sqlstack applies the same parameter binding and result shaping as file-based SQL.
+
+---
+
+## Advanced: Direct Database Access
+
+Every `Database` instance exposes the underlying driver via `.conn`, so you can drop down to raw queries when needed:
 
 ```ts
 import { SqlStackDB } from 'sqlstack/registry';
 
-const db = SqlStackDB.get();
+const db = SqlStackDB.get(); // get the default database
+
 // Driver shape depends on adapter:
 // - Postgres: pg.Pool
 // - MySQL: mysql2/promise Pool
-// - SQLite: better-sqlite3 Database or sqlite3.Database
+// - SQLite: better-sqlite3 Database
 const raw = db.conn;
 
-// close() only disposes connections created by the adapter itself.
-// If you supplied an existing connection/pool, close() is a no-op.
+// Execute raw queries (driver-specific)
+const result = await raw.query('SELECT 1');
+console.log(result);
 ```
+
+**Note:** `close()` only disposes connections created by the adapter. If you supplied an existing connection/pool, `close()` is a no-op.
+
+---
+
+## Database Support
+
+- **Postgres** — adapter: `createPgDb()`, driver: `pg`
+- **MySQL / MariaDB** — adapter: `createMysqlDb()`, driver: `mysql2/promise`
+- **SQLite** — adapter: `createSqliteDb()`, driver: `better-sqlite3`
+
+More adapters are planned.
+
+### Dialect Inference
+
+The placeholder style is inferred from the selected database. Override per-method with `@Query({ dialect: "pg" })` if needed.
+
+---
+
+## Philosophy
+
+**SQL-first:** SQL is the source of truth. No hidden queries.
+
+**Decorators as metadata:** Decorators (`@Defaults`, `@MissingAsNull`, `@Single`, `@Only`, `@Exist`, `@ValidateResult`, `@Transform`) are metadata labels. They always execute in a fixed internal order, so decorator order doesn't matter on your class.
+
+**Escape hatches:** Use inline SQL for simple queries; keep complex SQL in `.sql` files. You stay in control.
+
+---
+
+## Contributing
+
+Found a bug? Have a feature idea? Please open an [issue](https://github.com/anthropics/sqlstack/issues) or submit a [pull request](https://github.com/anthropics/sqlstack/pulls).
+
+### Development
+
+1. Clone the repository
+2. Install dependencies: `npm install`
+3. Run tests: `npm test`
+4. Build: `npm run build`
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) (if available) and [AGENTS.md](AGENTS.md) for detailed contributor guidance.
+
+---
+
+## License
+
+ISC