sqlstack 1.0.18 → 1.0.20

package/readme.md

@@ -2,19 +2,31 @@
 
 **SQL-first data access for Node.js and TypeScript.**
 
-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.
+Write real SQL next to your code, and use small, composable decorators to bind, execute, and shape results—without ORM complexity. If you already like dropping down to “raw queries”, this is for you.
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start (5 minutes)](#quick-start-5-minutes)
+- [Writing and Extending SQL](#writing-and-extending-sql)
+- [Configuration](#configuration)
+- [SQL Parameters](#sql-parameters)
+- [How It Works](#how-it-works)
+- [Result Types](#result-types)
+- [Error Handling](#error-handling)
+- [Inline SQL](#inline-sql)
+- [Advanced: Direct Database Access](#advanced-direct-database-access)
+- [Database Support](#database-support)
+- [Philosophy](#philosophy)
+- [Contributing](#contributing)
+- [License](#license)
 
-## Key Features
+## Install
 
-- **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.
+### Prerequisites
 
-## Install
+- Node.js 18+ (or a modern LTS runtime).
+- Works with both TypeScript and JavaScript; examples use TypeScript syntax.
 
 ```bash
 npm install sqlstack
@@ -34,6 +46,14 @@ npm install better-sqlite3 # SQLite
 
 ## Quick Start (5 minutes)
 
+At a high level, you:
+
+- Register one or more database connections with `SqlStackDB`.
+- Write normal classes with methods, decorate them with `@QueryBinder` and `@Query`.
+- Put SQL in `.sql` files next to those classes.
+
+When you call a decorated method, sqlstack loads the SQL, binds parameters from your method arguments, executes it via the selected adapter, then optionally shapes and validates the results via decorators.
+
 ### 1. Register Your Database
 
 Create a `boot.ts` (or similar) file at your app's entry point:
@@ -53,13 +73,15 @@ Load this file once during app startup.
 ### 2. Create a Repository Class
 
 ```ts
-// users/index.ts
+// src/users/index.ts
 import { QueryBinder, Query, SqlStackError } from "sqlstack";
 
 @QueryBinder() // looks for .sql files in the same folder by default
-export class UsersRepo {
+export class UsersRepository {
   @Query()
-  async findByEmail(_a: { email: string }): Promise<User[]> {
+  async findByEmail(params: { email: string }): Promise<User[]> {
+    // Implementation bodies are never called; this method exists
+    // only to define the TypeScript signature for @Query.
     throw new SqlStackError("replaced by @Query");
   }
 }
@@ -85,36 +107,220 @@ WHERE email = :email;
 ### 4. Use Your Repository
 
 ```ts
-const repo = new UsersRepo();
+const repo = new UsersRepository();
 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.
 
----
+You can then add more methods on the same repository that use sqlstack’s SQL helpers:
 
-## How It Works
+```ts
+@QueryBinder()
+export class UsersRepository {
+  @Query()
+  async findByEmail(params: { email: string }): Promise<User[]> {
+    throw new SqlStackError("replaced by @Query");
+  }
 
-### Execution Pipeline
+  @Query()
+  async updateProfile(params: { id: string; name?: string; status?: string }): Promise<WriteResult> {
+    throw new SqlStackError("replaced by @Query");
+  }
 
-sqlstack executes decorators in a **fixed, internal order** regardless of how you stack them:
+  @Query()
+  async createUser(params: { id: string; email: string; name?: string }): Promise<WriteResult> {
+    throw new SqlStackError("replaced by @Query");
+  }
 
+  @Query()
+  async search(filters: { name?: string; status?: string }): Promise<User[]> {
+    throw new SqlStackError("replaced by @Query");
+  }
+}
 ```
-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)
+
+**users/updateProfile.sql** — partial update with `:update`:
+
+```sql
+UPDATE users
+  :update(name, status, updated_at = now())
+WHERE id = :id;
+```
+
+**users/createUser.sql** — partial insert with `:insert`:
+
+```sql
+INSERT INTO users :insert(id, email, name, status = 'active');
 ```
 
-You can list decorators in any order; they always execute in this pipeline. See [docs/decorators.md](docs/decorators.md) for details.
+**users/search.sql** — dynamic filters with `:filter`:
+
+```sql
+SELECT id, email, name, status
+FROM users
+WHERE :filter(name, status);
+```
+
+As your needs grow, you evolve the SQL in these files (and use helpers like `:update`, `:insert`, and `:filter`) while keeping the TypeScript method interfaces—and all call sites—unchanged.
+
+### 5. Go Further with SQL Helpers
+
+Once you’re comfortable with basic `.sql` files, you can start using:
+
+- `:insert(...)` to build column lists and `VALUES` from your named parameters.
+- `:update(...)` to generate `SET` clauses for partial updates.
+- `:filter(...)` to build dynamic `WHERE` / `HAVING` conditions from whichever filters are defined.
+
+These helpers expand into plain SQL; the full behavior and examples are covered in the **Writing and Extending SQL** section below.
+
+## Writing and Extending SQL
+
+sqlstack is **SQL-first**: you write normal SQL, and sqlstack gives you a few helpers to make it easier to evolve queries over time without changing your method interface.
+
+### Plain SQL in Files
+
+Start with regular SQL in `.sql` files:
+
+```sql
+-- users/findByEmail.sql
+SELECT id, email, name, status
+FROM users
+WHERE email = :email;
+```
+
+Later, you can refactor this query (add joins, filters, or switch to a CTE) without changing the TypeScript method that calls it, as long as the returned columns still match your declared return type.
+
+### Extending SQL with Helpers
+
+sqlstack adds a small set of macros that expand into standard SQL, so you keep full control. They are designed to feel like “obvious SQL you would have written by hand.”
+
+#### `:insert(...)`
+
+```sql
+-- posts/createPost.sql
+INSERT INTO posts :insert(id, author_id, title, body, status = 'published');
+```
+
+```ts
+await repo.createPost({
+  id: 'post_1',
+  author_id: 'user_1',
+  title: 'Hello world',
+  body: 'First post!',
+  // status: undefined → defaults to 'published' from SQL literal
+});
+```
+
+```sql
+-- expands to
+INSERT INTO posts (id, author_id, title, body, status)
+VALUES (?, ?, ?, ?, 'published');
+```
+
+**Additional behaviors and rules**
+
+- Columns whose values are `undefined` are skipped; at least one non-literal column must be defined or a literal must be present.
+- Pure literal expressions (e.g. `created_at = now()`) are allowed and included even with no params.
+- `null` values are allowed and are bound as `NULL`.
+- Column order in the generated `INSERT` follows the order listed in `:insert(...)`, regardless of object key order.
+- `:insert()` only works with **named parameters**; using positional args throws.
+
+#### `:batch_insert(...)`
+
+Use `:batch_insert(...)` to build an efficient multi-row `VALUES` clause from one or more array arguments (plus optional scalars):
+
+```sql
+-- comments/createComments.sql
+INSERT INTO comments (post_id, author_id, body)
+:batch_insert(post_id, comment.author_id, comment.body);
+```
+
+```ts
+await repo.createComments({
+  post_id: 'post_1',
+  comment: [
+    { author_id: 'user_1', body: 'Nice post!' },
+    { author_id: 'user_2', body: 'Subscribed.' },
+  ],
+});
+```
+
+```sql
+-- expands (MySQL/SQLite)
+INSERT INTO comments (post_id, author_id, body)
+VALUES (?, ?, ?), (?, ?, ?);
+
+-- expands (Postgres)
+INSERT INTO comments (post_id, author_id, body)
+VALUES ($1, $2, $3), ($4, $5, $6);
+```
+
+- At least one argument must resolve to an array; all array arguments must have the same length and be non-empty.
+- Arguments can be scalars (reused for every row) or dot-paths into nested objects/arrays (e.g. `comment.body`, `root.ids`).
+- `:batch_insert()` only works with **named parameters**, not positional ones.
+
+#### `:update(...)`
+
+```sql
+-- posts/updatePost.sql
+UPDATE posts
+  :update(updated_at = now(), title, body)
+WHERE id = :id;
+```
+
+```ts
+await repo.updatePost({
+  id: 'post_1',
+  title: 'Updated title',
+  // body: undefined → not updated
+});
+```
+
+```sql
+-- expands to
+UPDATE posts
+SET updated_at = now(), title = ?
+WHERE id = ?;
+```
+
+#### `:filter(...)`
+
+```sql
+-- users/search.sql
+SELECT id, email, name, status
+FROM users
+WHERE :filter(
+  name,              -- name = ?
+  age >= :min_age,   -- age >= ?
+  status = 'active', -- literal
+  name LIKE :search, -- name LIKE ?
+  id IN (:ids)       -- id IN (?, ?, ?)
+);
+```
+
+```ts
+await repo.search({
+  name: "Alice",
+  min_age: 18,
+  search: "%ali%",
+  ids: [1, 2, 3],
+});
+```
+
+```sql
+-- expands to
+SELECT id, email, name, status
+FROM users
+WHERE name = ?
+  AND age >= ?
+  AND status = 'active'
+  AND name LIKE ?
+  AND id IN (?, ?, ?);
+```
+
+You can gradually adopt these helpers as your queries become more dynamic; they never hide the SQL that is ultimately sent to the database, they just generate the repetitive parts.
 
 ### Validation Controls
 
@@ -126,6 +332,35 @@ Validation (via `@ValidateResult`) is **enabled by default**. Control it with en
 
 ---
 
+## How It Works
+
+### Execution Pipeline
+
+When you invoke a decorated method, sqlstack:
+
+- Merges any default values into your arguments.
+- Loads SQL (from a file or inline), binds placeholders, and executes it via the chosen adapter.
+- If the adapter returned rows (a SELECT/WITH), it shapes and optionally validates those rows.
+- If the adapter returned a write result (INSERT/UPDATE/DELETE/DDL), it returns that result object as-is.
+
+Decorators run in a **fixed, internal order** regardless of how you stack them:
+
+```
+1. @Defaults        (fill in missing parameter values)
+   ↓
+2. @Query           (execute the SQL)
+   ↓
+3. @Single/@Only/@Exist/@None  (shape the results)
+   ↓
+4. @ValidateResult  (validate against JSON Schema)
+   ↓
+5. @Transform       (map flat rows to nested objects)
+```
+
+You can list decorators in any order; they always execute in this pipeline. See docs/decorators.md for details.
+
+---
+
 ## Configuration
 
 ### Register Databases
@@ -262,321 +497,6 @@ await repo.listByIds({ ids });
 - `null` → SQL `NULL`
 - `undefined` → throws an error; always provide a value or omit the parameter
 
-### :update() Syntax for Partial Updates
-
-The `:update()` syntax simplifies UPDATE statements by automatically generating SET clauses. It supports both parameterized columns and literal SQL expressions, making partial updates easy without needing `COALESCE` or `IFNULL`.
-
-**Key Features:**
-- Automatically generates `SET` keyword (don't write it yourself)
-- Literal expressions: `col = datetime('now')` → always included
-- Parameterized columns: `col` → only included if defined in args
-- Mixed usage: combine literals and parameterized columns
-
-**Basic Usage:**
-
-```sql
--- updateInvoice.sql
-UPDATE invoices
-  :update(invoice_date, due_date, subtotal_cents)
-WHERE id = :id
-```
-
-```ts
-await repo.updateInvoice({ 
-  invoice_date: '2024-01-01', 
-  id: 1 
-});
-// Generates: UPDATE invoices SET invoice_date = ? WHERE id = ?
-// due_date and subtotal_cents are skipped (undefined)
-```
-
-**Literal SQL Expressions:**
-
-Use `=` to include literal SQL expressions that are always included:
-
-```sql
-UPDATE invoices
-  :update(updated_at = datetime('now'), invoice_date, due_date)
-      WHERE id = :id
-```
-
-```ts
-await repo.updateInvoice({ 
-  invoice_date: '2024-01-01', 
-  id: 1 
-});
-// Generates: UPDATE invoices SET updated_at = datetime('now'), invoice_date = ? WHERE id = ?
-```
-
-**Mixed Literal and Parameterized:**
-
-```sql
-UPDATE invoices
-  :update(
-    updated_at = datetime('now'),
-    invoice_date,
-    due_date,
-    status = 'active'
-  )
-WHERE id = :id
-```
-
-```ts
-await repo.updateInvoice({ 
-  invoice_date: '2024-01-01', 
-  due_date: '2024-01-15',
-  id: 1 
-});
-// Generates: UPDATE invoices SET updated_at = datetime('now'), invoice_date = ?, due_date = ?, status = 'active' WHERE id = ?
-```
-
-**Notes:**
-- `:update()` only works with named parameters (not positional)
-- Literal expressions are always included
-- Parameterized columns are only included if defined and not `undefined`
-- If all parameterized columns are undefined (and no literals), throws an error
-- Case-insensitive: `:update`, `:UPDATE`, `:Update` all work
-
-### :insert() Syntax for INSERT Statements
-
-The `:insert()` syntax simplifies INSERT statements by automatically generating both the column list and VALUES clause. It supports both parameterized columns and literal SQL expressions, making INSERT statements much more concise.
-
-**Key Features:**
-- Automatically generates column list `(col1, col2, ...)` and VALUES clause `VALUES (?, ?, ...)`
-- Literal expressions: `col = datetime('now')` → column name and literal value included
-- Parameterized columns: `col` → only included if defined in args
-- Mixed usage: combine literals and parameterized columns
-
-**Basic Usage:**
-
-```sql
--- createInvoice.sql
-INSERT INTO invoices :insert(case_id, invoice_number, invoice_date, due_date)
-```
-
-```ts
-await repo.createInvoice({ 
-  case_id: 1,
-  invoice_number: 'INV-001', 
-  invoice_date: '2024-01-01',
-  due_date: '2024-01-15'
-});
-// Generates: INSERT INTO invoices (case_id, invoice_number, invoice_date, due_date) VALUES (?, ?, ?, ?)
-// Params: [1, 'INV-001', '2024-01-01', '2024-01-15']
-```
-
-**With Undefined Columns:**
-
-```sql
-INSERT INTO invoices :insert(case_id, invoice_number, invoice_date, due_date)
-```
-
-```ts
-await repo.createInvoice({ 
-  case_id: 1,
-  invoice_number: 'INV-001'
-});
-// Generates: INSERT INTO invoices (case_id, invoice_number) VALUES (?, ?)
-// invoice_date and due_date are skipped (undefined)
-```
-
-**Literal SQL Expressions:**
-
-Use `=` to include literal SQL expressions that are always included:
-
-```sql
-INSERT INTO invoices :insert(created_at = datetime('now'), case_id, invoice_number)
-```
-
-```ts
-await repo.createInvoice({ 
-  case_id: 1,
-  invoice_number: 'INV-001'
-});
-// Generates: INSERT INTO invoices (created_at, case_id, invoice_number) VALUES (datetime('now'), ?, ?)
-// Params: [1, 'INV-001']
-```
-
-**Mixed Literal and Parameterized:**
-
-```sql
-INSERT INTO invoices :insert(
-  created_at = datetime('now'),
-  case_id,
-  invoice_number,
-  status = 'draft'
-)
-```
-
-```ts
-await repo.createInvoice({ 
-  case_id: 1,
-  invoice_number: 'INV-001'
-});
-// Generates: INSERT INTO invoices (created_at, case_id, invoice_number, status) VALUES (datetime('now'), ?, ?, 'draft')
-// Params: [1, 'INV-001']
-```
-
-**Notes:**
-- `:insert()` only works with named parameters (not positional)
-- Literal expressions are always included (both column name and value)
-- Parameterized columns are only included if defined and not `undefined`
-- If all parameterized columns are undefined (and no literals), throws an error
-- Case-insensitive: `:insert`, `:INSERT`, `:Insert` all work
-
-### :filter() Syntax for WHERE/HAVING Clauses
-
-The `:filter()` syntax simplifies WHERE and HAVING clauses by automatically generating conditions. It supports simple column names (equality), literal comparisons, and parameterized comparisons, making dynamic filtering much easier.
-
-**Key Features:**
-- Simple column names → equality: `name` → `name = ?`
-- Literal comparisons → included as-is: `age > 30` → `age > 30`
-- Parameterized comparisons → bind parameters: `age > :min_age` → `age > ?`
-- Mixed usage: combine all three types
-- Works in both WHERE and HAVING clauses
-- Conditions are joined with `AND`
-
-**Basic Usage:**
-
-```sql
--- findUsers.sql
-SELECT * FROM users WHERE :filter(name, age)
-```
-
-```ts
-await repo.findUsers({ name: 'John', age: 30 });
-// Generates: SELECT * FROM users WHERE name = ? AND age = ?
-// Params: ['John', 30]
-```
-
-**With Some Undefined Columns:**
-
-```sql
-SELECT * FROM users WHERE :filter(name, age, status)
-```
-
-```ts
-await repo.findUsers({ name: 'John' });
-// Generates: SELECT * FROM users WHERE name = ?
-// age and status are skipped (undefined)
-```
-
-**Literal Comparisons:**
-
-```sql
-SELECT * FROM users WHERE :filter(age > 30, status = 'active')
-```
-
-```ts
-await repo.findUsers({});
-// Generates: SELECT * FROM users WHERE age > 30 AND status = 'active'
-// Params: []
-```
-
-**Parameterized Comparisons:**
-
-```sql
-SELECT * FROM users WHERE :filter(age > :min_age, name LIKE :search)
-```
-
-```ts
-await repo.findUsers({ min_age: 30, search: '%John%' });
-// Generates: SELECT * FROM users WHERE age > ? AND name LIKE ?
-// Params: [30, '%John%']
-```
-
-**Mixed Usage:**
-
-```sql
-SELECT * FROM users WHERE :filter(name, age > :min_age, status = 'active')
-```
-
-```ts
-await repo.findUsers({ name: 'John', min_age: 30 });
-// Generates: SELECT * FROM users WHERE name = ? AND age > ? AND status = 'active'
-// Params: ['John', 30]
-```
-
-**With Array Parameters (IN clause):**
-
-```sql
-SELECT * FROM users WHERE :filter(id IN (:ids))
-```
-
-```ts
-await repo.findUsers({ ids: [1, 2, 3] });
-// Generates: SELECT * FROM users WHERE id IN (?, ?, ?)
-// Params: [1, 2, 3]
-```
-
-**With :or() Expansion:**
-
-The `:or()` syntax expands array parameters into multiple OR conditions:
-
-```sql
-SELECT * FROM users WHERE :filter(name = :or(:names), age > :min_age)
-```
-
-```ts
-await repo.findUsers({ names: ['John', 'Jane', 'Bob'], min_age: 30 });
-// Generates: SELECT * FROM users WHERE (name = ? OR name = ? OR name = ?) AND age > ?
-// Params: ['John', 'Jane', 'Bob', 30]
-```
-
-**Complex :or() Usage:**
-
-```sql
-SELECT * FROM users WHERE :filter(
-  (name = :or(:names)),
-  age > :min_age,
-  status = 'active',
-  (department = :or(:depts) OR role = :or(:roles))
-)
-```
-
-```ts
-await repo.findUsers({ 
-  names: ['John', 'Jane'], 
-  min_age: 25, 
-  depts: ['Engineering'], 
-  roles: ['Manager'] 
-});
-// Generates: SELECT * FROM users WHERE (name = ? OR name = ?) AND age > ? AND status = 'active' AND (department = ? OR role = ?)
-// Params: ['John', 'Jane', 25, 'Engineering', 'Manager']
-```
-
-**HAVING Clause:**
-
-```sql
-SELECT department, COUNT(*) as count 
-FROM employees 
-GROUP BY department 
-HAVING :filter(count > :min_count, department = 'Sales')
-```
-
-```ts
-await repo.findDepartments({ min_count: 10 });
-// Generates: SELECT department, COUNT(*) as count FROM employees GROUP BY department HAVING count > ? AND department = 'Sales'
-// Params: [10]
-```
-
-**Supported Operators:**
-
-- Comparison: `=`, `!=`, `<>`, `>`, `<`, `>=`, `<=`
-- Pattern matching: `LIKE`
-- Membership: `IN`
-- Range: `BETWEEN`
-- Null checks: `IS NULL`, `IS NOT NULL`
-
-**Notes:**
-- `:filter()` only works with named parameters (not positional)
-- Literal expressions are always included
-- Parameterized conditions are only included if the parameter is defined and not `undefined`
-- If all parameterized conditions are undefined (and no literals), throws an error
-- Case-insensitive: `:filter`, `:FILTER`, `:Filter` all work
-- `:or()` expands arrays into multiple OR conditions
-- Operators inside string literals are not treated as operators (e.g., `name = 'value > test'`)
-
 ## SQL File Resolution
 
 The `@Query()` decorator locates `.sql` files using a simple, predictable rule. See [docs/file_resolution.md](docs/file_resolution.md) for complete details.
@@ -665,7 +585,7 @@ import { QueryBinder, Page, Query, SqlStackError } from "sqlstack";
 class UsersRepo {
   @Page(10) // limit = 10, pages 1-based
   @Query()
-  async listUsers(_a: { page?: number; status?: string }): Promise<User[]> {
+  async listUsers(params: { status?: string; page?: number }): Promise<User[]> {
     throw new SqlStackError();
   }
 }
@@ -688,10 +608,10 @@ 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:
+**Trailing options (multiple parameters):** When your method has more than one parameter, pass `{ page: N }` as the last argument:
 ```ts
-await repo.list({ user_id: 1 }, { page: 2 });        // named
-await repo.list(userId, { page: 2 });                // positional
+await repo.list({ user_id: 1 }, { page: 2 }); // named-style params + trailing options
+await repo.list(userId, { page: 2 });         // positional id + trailing options
 ```
 
 ### Result Shape Decorators
@@ -773,11 +693,9 @@ Example schema:
 }
 ```
 
-Validation is **enabled by default**; control with `SQLSTACK_ENABLE_VALIDATION` and `SQLSTACK_DISABLE_VALIDATION` environment variables.
-
 ### `@Transform`
 
-Map flat SQL rows to nested objects using a nesting spec:
+Use `DTO()` with `@Transform` to turn flat joined rows into nested objects, automatically deduplicating parents and children.
 
 ```ts
 import { DTO, Transform, Query, QueryBinder } from 'sqlstack';
@@ -817,20 +735,60 @@ class Repo {
 }
 ```
 
-**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.
+Given flat rows like:
+
+```ts
+[
+  { group_id: 'g1', group_name: 'Chest', muscle_id: 'm1', muscle_name: 'Pecs',    exercise_id: 'e1', exercise_name: 'Bench'   },
+  { group_id: 'g1', group_name: 'Chest', muscle_id: 'm1', muscle_name: 'Pecs',    exercise_id: 'e2', exercise_name: 'Incline' },
+  { group_id: 'g1', group_name: 'Chest', muscle_id: 'm2', muscle_name: 'Delts',   exercise_id: 'e3', exercise_name: 'Raise'   },
+]
+```
+
+the transform returns:
+
+```ts
+[
+  {
+    id: 'g1',
+    name: 'Chest',
+    muscles: [
+      {
+        id: 'm1',
+        name: 'Pecs',
+        exercises: [
+          { id: 'e1', name: 'Bench' },
+          { id: 'e2', name: 'Incline' },
+        ],
+      },
+      {
+        id: 'm2',
+        name: 'Delts',
+        exercises: [
+          { id: 'e3', name: 'Raise' },
+        ],
+      },
+    ],
+  },
+];
+```
+
+**Direct mapping with dot paths**
 
-Example with direct mapping:
 ```ts
 // Row: { id: '1', muscle: 'biceps', group: 'arms' }
 const toSimple = DTO({ id: 'id', name: 'muscle', 'group.name': 'group' } as any, { single: true });
 // Result: { id: '1', name: 'biceps', group: { name: 'arms' } }
 ```
 
+**More behaviors**
+
+- If you omit `id` at a level, DTO uses all mapped fields there as a composite identity to dedupe children.
+- Child branches where all identifying columns are `NULL` are skipped (common with LEFT JOINs).
+- Ordering of children follows your SQL `ORDER BY`; sort in SQL, not in the DTO.
+
+See `docs/DTO.md` for a full guide with more patterns and edge cases.
+
 ---
 
 ## Result Types
@@ -893,6 +851,16 @@ type PostgresWriteResult = WriteResult & {
 };
 ```
 
+### Evolving Queries Without Breaking Callers
+
+Your method signature is the contract; the SQL is an implementation detail.
+
+- Call sites depend only on the TypeScript interface (`args` and return type), not on the shape of the underlying SQL file.
+- You can freely refactor a `.sql` file to add joins, filters, or pagination, or switch from a simple query to a CTE, without touching call sites—as long as the returned columns still match your declared return type (and any validation schema).
+- Decorators like `@Transform` make it easy to map new or reorganized SQL results back into the same nested DTO shape, so you can take advantage of more advanced SQL while keeping your public interface stable.
+
+This lets you start with very simple queries and incrementally adopt more complex SQL over time, with TypeScript and optional JSON Schema validation guarding the boundary.
+
 ---
 
 ## Error Handling
@@ -993,7 +961,7 @@ The placeholder style is inferred from the selected database. Override per-metho
 
 **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.
+**Decorators as metadata:** Decorators (`@Defaults`, `@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.