sqlstack 3.3.0 → 3.5.0

package/readme.md

@@ -16,6 +16,7 @@ Write real SQL next to your code, and use small, composable decorators to bind,
 - [Error Handling](#error-handling)
 - [Transactions](#transactions)
 - [Inline SQL](#inline-sql)
+- [Choosing the Database at Call Time](#choosing-the-database-at-call-time)
 - [Advanced: Direct Database Access](#advanced-direct-database-access)
 - [Database Support](#database-support)
 - [Philosophy](#philosophy)
@@ -78,15 +79,16 @@ Load this file once during app startup.
 
 ```ts
 // src/users/index.ts
-import { QueryBinder, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Query, run } from "sqlstack";
 
 @QueryBinder() // looks for .sql files in the same folder by default
 export class UsersRepository {
   @Query()
   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");
+    // run() executes this method's SQL (findByEmail.sql) with the method's
+    // arguments; the result type is inferred from the declared return type.
+    // Code before/after `await run()` runs normally (logging, try/catch, ...).
+    return run();
   }
 }
 ```
@@ -116,7 +118,7 @@ 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.
+That's it! The `@Query` decorator wraps the method; the body's `return run()` loads and executes the SQL and returns the shaped results. (Older code whose body is a placeholder `throw` still works — the wrapper falls back to running the SQL — but `return run()` is the supported form.)
 
 You can then add more methods on the same repository that use sqlstack’s SQL helpers:
 
@@ -125,22 +127,22 @@ You can then add more methods on the same repository that use sqlstack’s SQL h
 export class UsersRepository {
   @Query()
   async findByEmail(params: { email: string }): Promise<User[]> {
-    throw new SqlStackError("replaced by @Query");
+    return run();
   }
 
   @Query()
   async updateProfile(params: { id: string; name?: string; status?: string }): Promise<WriteResult> {
-    throw new SqlStackError("replaced by @Query");
+    return run();
   }
 
   @Query()
   async createUser(params: { id: string; email: string; name?: string }): Promise<WriteResult> {
-    throw new SqlStackError("replaced by @Query");
+    return run();
   }
 
   @Query()
   async search(filters: { name?: string; status?: string }): Promise<User[]> {
-    throw new SqlStackError("replaced by @Query");
+    return run();
   }
 }
 ```
@@ -407,13 +409,13 @@ SqlStackDB.register('sqlite-existing', createSqliteDb(sqlite));
 Use `@QueryBinder({ db: "name" })` to set a default database for all methods in a class:
 
 ```ts
-import { QueryBinder, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Query, run } from "sqlstack";
 
 @QueryBinder({ db: "analytics" }) // all methods use "analytics"
 export class ReportsRepo {
   @Query()
   async topPages(_a: { since: string }): Promise<Row[]> {
-    throw new SqlStackError("replaced");
+    return run();
   }
 }
 ```
@@ -427,12 +429,12 @@ Use `@Query({ db: "name" })` to override the class default for a specific method
 export class MixedRepo {
   @Query() // uses "primary"
   async dailySummary(_a: { date: string }): Promise<Row[]> {
-    throw new SqlStackError("replaced");
+    return run();
   }
 
   @Query({ db: "analytics" }) // override to use "analytics"
   async topPages(_a: { since: string }): Promise<Row[]> {
-    throw new SqlStackError("replaced");
+    return run();
   }
 }
 ```
@@ -514,7 +516,7 @@ No argument to `@Query()` → looks in the same folder as the class file:
 class UsersRepo {
   @Query()
   async findByEmail(_a: { email: string }): Promise<User[]> {
-    throw new Error();
+    return run();
   }
 }
 ```
@@ -560,14 +562,14 @@ Use decorators to add behavior to your methods. They compose freely and always e
 Provide default parameter values:
 
 ```ts
-import { QueryBinder, Defaults, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Defaults, Query, run } from "sqlstack";
 
 @QueryBinder()
 class UsersRepo {
   @Defaults({ status: "active", limit: 10 })
   @Query()
   async listUsers(_a: { status?: string; limit?: number }): Promise<User[]> {
-    throw new SqlStackError();
+    return run();
   }
 }
 ```
@@ -583,14 +585,14 @@ await repo.listUsers({ status: "inactive" }); // { status: "inactive", limit: 10
 Add pagination with `:offset` and `:limit` parameters. Pages are 1-based by default:
 
 ```ts
-import { QueryBinder, Page, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Page, Query, run } from "sqlstack";
 
 @QueryBinder()
 class UsersRepo {
   @Page(10) // limit = 10, pages 1-based
   @Query()
   async listUsers(params: { status?: string; page?: number }): Promise<User[]> {
-    throw new SqlStackError();
+    return run();
   }
 }
 ```
@@ -623,7 +625,7 @@ await repo.list(userId, { page: 2 });         // positional id + trailing option
 Shape single-query results without parameters:
 
 ```ts
-import { QueryBinder, Single, Only, Exist, None, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, Single, Only, Exist, None, Query, run } from "sqlstack";
 
 @QueryBinder()
 class UsersRepo {
@@ -631,28 +633,28 @@ class UsersRepo {
   @Single
   @Query()
   async firstOrNull(_a: { email: string }): Promise<User | null> {
-    throw new SqlStackError();
+    return run();
   }
 
   // @Only → require exactly one row; throw if 0 or >1
   @Only
   @Query()
   async exactlyOne(_a: { id: string }): Promise<User> {
-    throw new SqlStackError();
+    return run();
   }
 
   // @Exist → require at least one row; return first row; throw if none
   @Exist
   @Query()
   async requireOne(_a: { email: string }): Promise<User> {
-    throw new SqlStackError();
+    return run();
   }
 
   // @None → require zero rows; return null; throw if any rows
   @None
   @Query()
   async ensureNone(_a: { status: string }): Promise<null> {
-    throw new SqlStackError();
+    return run();
   }
 }
 ```
@@ -670,7 +672,7 @@ Validate query results against a JSON Schema:
 
 ```ts
 import schema from "./user.row.schema.json" assert { type: "json" };
-import { QueryBinder, ValidateResult, Single, Query, SqlStackError } from "sqlstack";
+import { QueryBinder, ValidateResult, Single, Query, run } from "sqlstack";
 
 @QueryBinder()
 class UsersRepo {
@@ -678,7 +680,7 @@ class UsersRepo {
   @Single
   @Query()
   async findByEmail(_a: { email: string }): Promise<User | null> {
-    throw new SqlStackError();
+    return run();
   }
 }
 ```
@@ -735,7 +737,7 @@ class Repo {
     WHERE g.id = :id
     ORDER BY m.name, e.name
   ` })
-  async getGroup(_a: { id: string }): Promise<any | null> { throw new Error('replaced'); }
+  async getGroup(_a: { id: string }): Promise<any | null> { return run(); }
 }
 ```
 
@@ -806,13 +808,13 @@ Returns an array of rows, which can be shaped via decorators:
 class Repo {
   @Query()
   async allUsers(): Promise<User[]> {
-    throw new Error();
+    return run();
   }
 
   @Single
   @Query()
   async firstUser(): Promise<User | null> {
-    throw new Error();
+    return run();
   }
 }
 ```
@@ -867,16 +869,18 @@ This lets you start with very simple queries and incrementally adopt more comple
 
 ## Error Handling
 
-sqlstack provides a base error class and specific error types. Import and catch as needed:
+sqlstack throws; it does not return result objects. Its errors extend `SqlStackError` (with one historical exception, noted below). Import and catch as needed:
 
 ```ts
-import { SqlStackError } from "sqlstack";
+import { SqlStackError, DatabaseError } 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) {
+  if (err instanceof DatabaseError) {
+    console.log("statement failed:", err.sql, err.code, err.cause);
+  } else 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");
@@ -891,11 +895,15 @@ try {
 ```
 
 Available error classes:
-- `SqlStackError` — base class for all sqlstack errors
+- `SqlStackError` — base class for all sqlstack errors (also used for usage errors such as calling `run()` outside a `@Query` method)
+- `DatabaseError` — a statement failed. `.sql` holds the statement (with placeholders), `.cause` holds the original error (the driver's error, or the macro/binding/name-resolution error), and `.code` copies the cause's string driver code (`SQLITE_CONSTRAINT_UNIQUE`, `23505`, `ER_DUP_ENTRY`, ...) when present
 - `ExactlyOneRowError` — thrown by `@Only` when row count ≠ 1
 - `NoRowsError` — thrown by `@Exist` when no rows found
+- `RowsExistError` — thrown by `@None` when rows exist
+- `ExpectedRowsError` — a shape decorator was applied to a statement that produced no result set
 - `ValidationError` — thrown by `@ValidateResult` on schema mismatch
-- Database driver errors — pass through unchanged
+
+**The error contract.** Driver errors never pass through raw: they are always wrapped in `DatabaseError` with the original in `.cause`. Parameter-binding errors such as `Missing named parameter :email` are a `DatabaseError` with the original in `.cause` in every `run(...)` form, including the zero-argument `run()`. For the `run(...)` forms that take arguments (`run(query)`, `run(db, query)`, `run(db, params)`), *every* failure before result shaping — macro errors from an `` sql`...` `` fragment, parameter-binding errors, an unknown database name — is a `DatabaseError` with the original in `.cause`; invalid arguments are `SqlStackError`. Errors thrown by your own code — the method body or a `@Transform` function — propagate unchanged.
 
 ---
 
@@ -929,7 +937,7 @@ Queries in `@Query` decorated methods automatically participate in the active tr
 class UsersRepo {
   @Query({ sql: 'INSERT INTO users (email, name) VALUES (:email, :name)' })
   async insert(data: { email: string; name: string }): Promise<WriteResult> {
-    throw new Error("replaced by @Query");
+    return run();
   }
 }
 
@@ -937,7 +945,7 @@ class UsersRepo {
 class ProfilesRepo {
   @Query({ sql: 'INSERT INTO profiles (user_id, bio) VALUES (:userId, :bio)' })
   async insert(data: { userId: string; bio: string }): Promise<WriteResult> {
-    throw new Error("replaced by @Query");
+    return run();
   }
 }
 ```
@@ -1184,7 +1192,7 @@ async createUser() {
 
 ## Inline SQL
 
-For simple or dynamic queries, use `@Query({ sql: "..." })` with inline SQL:
+For simple queries, use `@Query({ sql: "..." })` with inline SQL:
 
 ```ts
 @QueryBinder()
@@ -1195,18 +1203,99 @@ class Repo {
     WHERE email = :email
   ` })
   async findByEmail(_a: { email: string }): Promise<User[]> {
-    throw new Error("replaced");
+    return run();
   }
 }
 ```
 
 sqlstack applies the same parameter binding and result shaping as file-based SQL.
 
+For SQL built in code, pass an `` sql`...` `` fragment to `run`. The fragment replaces the method's SQL file; its `${}` values are the bound parameters (the method's own arguments are not auto-bound). The database still comes from `@Query({ db })` / `@QueryBinder({ db })` / the default, the active transaction is joined, and the shape/transform/validation decorators still apply:
+
+```ts
+import { QueryBinder, Query, Single, run, sql } from "sqlstack";
+
+@QueryBinder()
+class Repo {
+  @Single
+  @Query()
+  async findByEmail(email: string): Promise<User | null> {
+    return run(sql`SELECT id, email, name FROM users WHERE email = ${email}`);
+  }
+}
+```
+
+SQL is never accepted as a plain string — always build it with the `sql` tag, and pass the fragment itself (not its `.toSQL()` output) so `run` can bind it for the target dialect.
+
+> **Deprecated:** a `@Query` body that *returns* an `` sql`...` `` fragment (instead of `` return run(sql`...`) ``) still executes, but only type-checks with an `as any`-style cast. It emits a one-time `DeprecationWarning` (`SQLSTACK_FRAGMENT_BODY`) per method and will be removed in the next major version.
+
+---
+
+## Choosing the Database at Call Time
+
+When the database handle is only known at runtime (per-tenant or per-thread databases, a handle passed into a repository method), pass it to `run` as the first argument. The handle is anything with `query(sql, params)` — a sqlstack `Database` from `createPgDb` / `createMysqlDb` / `createSqliteDb`, or your application's own wrapper — or the name of a registered database. sqlstack never opens databases by path.
+
+### `run(db, query)` — anywhere
+
+```ts
+import { run, sql } from "sqlstack";
+
+const rows = await run<ImportRow[]>(accountsDb, sql`
+  SELECT 1 AS present FROM data_root_imports
+  WHERE data_root = ${dataRoot} AND kind = ${kind}
+  LIMIT 1
+`);
+
+await run(accountsDb, sql`INSERT INTO data_root_imports :insert(${{ data_root: dataRoot, kind }})`);
+```
+
+Outside a `@Query` method this returns the raw result: a rows array for statements that produce a result set, `{ rowsAffected, lastInsertId? }` otherwise. Without an explicit type argument the result is `unknown`, never `any`. Inside a `@Query` method, `` return run(db, sql`...`) `` runs the fragment on `db` and applies the method's shape/transform/validation decorators; the result type is inferred from the method's declared return type.
+
+### `run(db, params)` — inside a `@Query` method
+
+Runs the method's own SQL (its `.sql` file or inline `@Query({ sql })`) against `db`, binding `params` — an object for `:named` placeholders, an array for `:arg1, :arg2, ...`. In this form the method's raw arguments are **not** auto-bound; `params` is the whole binding input. `@Defaults`, `@Page`, shaping, transform, and validation still apply.
+
+```ts
+@QueryBinder()
+class AccountsRepo {
+  @Single
+  @Query() // AccountsRepo/findByEmail.sql: SELECT * FROM accounts WHERE email = :email
+  async findByEmail(db: Database, params: { email: string }): Promise<Account | null> {
+    return run(db, params);
+  }
+}
+```
+
+The SQL file is located through the same resolver as `run()` (under an active IoC environment that means the root's registered `SqlStack`). Calling `run(db, params)` outside a `@Query` method throws `SqlStackError` — there is no SQL to run.
+
+### The forms at a glance
+
+| Call | Where | SQL | Database | Binding |
+|---|---|---|---|---|
+| `run()` | `@Query` body | method's file / inline SQL | decorator context | method arguments |
+| `run(query)` | `@Query` body | the fragment | decorator context | fragment values |
+| `run(db, query)` | anywhere | the fragment | `db` | fragment values |
+| `run(db, params)` | `@Query` body | method's file / inline SQL | `db` | `params` only |
+
+Type rules (enforced by the overloads, and mirrored at runtime for untyped callers): SQL strings are rejected, `.toSQL()` output (`{ sql, params }`) is rejected, the first argument must be a handle or a name, and params must be an object or array. All forms follow the [error contract](#error-handling): failures surface as `DatabaseError` with the original error in `.cause`.
+
+### Dialects
+
+`run` binds fragments for the target database: `$1, $2, ...` for Postgres, `?` for MySQL and SQLite (including inside `:insert`, `:update`, `:filter`, and `:batch_insert`). The dialect comes from the handle's `dialect` property and defaults to `sqlite` when the handle has none. `fragment.toSQL()` itself is unchanged and always emits `?`.
+
+### Transactions
+
+A database passed to `run` joins an active transaction (from `@transaction` / `withTransaction`) that was opened **on that same database**: by name, or — for a handle — when it is the very `Database` object registered under the transaction's name. A handle that is not registered with sqlstack (for example an application-owned SQLite connection) never joins a sqlstack transaction; manage its transactions with your driver.
+
+### Inside `@Query`, all `run` calls belong to the method
+
+`run` finds the enclosing `@Query` invocation through async context. Any `run(...)` executed while a `@Query` method body is running — including inside helper functions the body awaits — is treated as that method's query and gets its shape/transform/validation decorators. Keep `run(db, query)` calls meant to return raw results out of `@Query` bodies.
+
 ---
 
 ## Advanced: Direct Database Access
 
-Every `Database` instance exposes the underlying driver via `.conn`, so you can drop down to raw queries when needed:
+For SQL that should stay typed and dialect-safe, prefer `` run(db, sql`...`) `` (see [Choosing the Database at Call Time](#choosing-the-database-at-call-time)). Every `Database` instance also exposes the underlying driver via `.conn`, so you can drop down to raw driver calls when needed:
 
 ```ts
 import { SqlStackDB } from 'sqlstack/registry';
@@ -1238,7 +1327,7 @@ More adapters are planned.
 
 ### Dialect Inference
 
-The placeholder style is inferred from the selected database. Override per-method with `@Query({ dialect: "pg" })` if needed.
+The placeholder style is inferred from the selected database. Override per-method with `@Query({ dialect: "postgres" })` if needed.
 
 ---