@onreza/sqlx-js 0.2.0 → 0.3.0

package/README.md

@@ -2,9 +2,9 @@
 
 Compile-time-checked raw SQL for TypeScript + PostgreSQL. Inspired by Rust's [sqlx](https://github.com/launchbadge/sqlx).
 
-You write plain SQL strings. A `prepare` step validates them against your database via the PostgreSQL wire protocol and generates a TypeScript declaration file. Wrong column names, mismatched parameter types, stale queries after a migration — all become compile errors.
+You write plain SQL strings. A `prepare` step validates them against your database via the PostgreSQL wire protocol and generates a TypeScript declaration file. Wrong column names and stale queries fail during `prepare`; mismatched parameter types and row usage become TypeScript errors.
 
-The runtime uses [Postgres.js](https://github.com/porsager/postgres), so both the runtime and the CLI work on **Node ≥ 18, Bun, and Deno** — the CLI ships a `#!/usr/bin/env node` shebang and uses no runtime-specific APIs.
+The runtime uses [Postgres.js](https://github.com/porsager/postgres) through a single adapter instead of a Bun-specific client. The published CLI is a **Node ≥ 18** binary (`#!/usr/bin/env node`) and can also be run through Bun's npm tooling.
 
 ```ts
 import { sql } from "@onreza/sqlx-js";
@@ -24,11 +24,11 @@ const rows = await sql(
 - **Precise nullability inference** through `libpg-query`: `JOIN` direction (LEFT/RIGHT/FULL), inner `JOIN ... ON` predicates, DML `RETURNING`, `COALESCE`, `CASE`, `COUNT`, expression propagation. Parameters become `T | null` when wrapped in `COALESCE`/`NULLIF`/`IS [NOT] NULL`/`IS [NOT] DISTINCT FROM`, or when bound to a nullable column in `INSERT`/`UPDATE`.
 - **WHERE narrowing**: `IS NOT NULL`, equality chains, `IN`, `LIKE`, `BETWEEN` make columns non-null. Tracks `AND`/`OR` semantics.
 - **PostgreSQL enums** generated as TypeScript literal unions (read + write side).
-- **Schema-aware `jsonb`** via a `SqlxJsJson` global namespace and a config-driven column → type mapping. Works for both result columns and `INSERT`/`UPDATE`/`WHERE` parameters.
+- **Schema-aware `jsonb`** via a `SqlxJsJson` global namespace and a config-driven column → type mapping. Works for both result columns and `INSERT`/`UPDATE`/`WHERE` parameters. Unmapped `json`/`jsonb` falls back to `JsonValue` for rows and `JsonInput` for parameters instead of `unknown`.
 - **Extension types out of the box**: `pgvector` (`vector`, `halfvec`, `sparsevec`), `hstore`, `citext`, `ltree`/`lquery`/`ltxtquery`. Add your own through `customTypes` config.
 - **Domains** resolve to their base TypeScript type (`CREATE DOMAIN email AS text` → `string`), including domains over extension types or other domains.
 - **Wide built-in type coverage**: numeric, text, date/time, UUID, json/jsonb, network (inet/cidr/macaddr/macaddr8), bit strings, ranges/multiranges, geometric, money, tsvector/tsquery, xml — and the matching array variants.
-- **External SQL files** via `sql.file("queries/foo.sql", ...)` — typed exactly like inline queries. Watch mode re-prepares on `.sql` edits too.
+- **External SQL files** via `sql.file("queries/foo.sql", ...)` — prepared and typed through `KnownFileQueries`. Watch mode re-prepares on `.sql` edits too.
 - **One-row helpers**: `sql.one(...)`, `sql.optional(...)`, `sql.file.one(...)`, `sql.file.optional(...)`, and the same chain on the `tx` callback — friendly with `noUncheckedIndexedAccess: true`. The scanner walks all of them.
 - **Array params** for `text[]`, `int[]`, etc. are auto-serialised to PostgreSQL array literals (`{a,b,c}`) at runtime — no more `string_to_array` workaround.
 - **Typed transactions** via `sql.transaction(async tx => …)` — the `tx` callback parameter is recognized by the scanner, so queries inside the block keep full type checking.
@@ -40,8 +40,8 @@ const rows = await sql(
 - **Schema snapshot + LLM manifest** via `schema dump` / `schema check`: tables, columns, constraints, indexes, types, and function/procedure metadata are introspected from PostgreSQL.
 - **Shadow database validation** via `migrate dev` / `migrate verify`: auto-create a disposable shadow DB, apply migrations, validate SQL, and drop it afterwards.
 - **Safe identifier quoting** via `sql.id(...)`, backed by the committed schema snapshot whitelist.
-- **Cross-runtime**: one Postgres.js-backed runtime that works on Node, Bun, and Deno — no runtime-specific adapter to choose.
-- **Watch mode**: ~15ms incremental re-prepare on file change.
+- **Single runtime adapter**: Postgres.js backs the runtime on Node/Bun-compatible environments — no Bun.SQL-specific adapter to choose.
+- **Watch mode**: debounced re-prepare with a warm `PgClient` + `SchemaCache` on `.ts` / `.tsx` / `.mts` / `.cts` / `.sql` changes.
 - **Cache pruning** removes orphaned entries automatically (toggleable with `--no-prune`).
 
 ## Install
@@ -73,7 +73,7 @@ DATABASE_URL=postgres://user:password@localhost:5432/your_db
 # DATABASE_URL=postgres://user:password@db.example.com:5432/your_db?sslmode=require
 ```
 
-Supported `sslmode` values: `disable`, `prefer` (default — try TLS, fall back to plaintext), `require` (TLS or fail), `verify-ca`, `verify-full`. For a private/self-signed CA, point `sslrootcert` (and optionally `sslcert` / `sslkey` for client certs) at PEM files: `?sslmode=verify-full&sslrootcert=/etc/ssl/ca.pem`. `application_name`, `connect_timeout`, and `statement_timeout` (milliseconds) are also honored when provided as URL parameters.
+Supported `sslmode` values: `disable`, `prefer` (default — try TLS, fall back to plaintext), `require` (TLS or fail), `verify-ca`, `verify-full`. For a private/self-signed CA, point `sslrootcert` (and optionally `sslcert` / `sslkey` for client certs) at PEM files: `?sslmode=verify-full&sslrootcert=/etc/ssl/ca.pem`. `application_name`, `connect_timeout` (seconds), and `statement_timeout` (milliseconds) are also honored when provided as URL parameters.
 
 ### 2. Create a migration
 
@@ -81,7 +81,7 @@ Supported `sslmode` values: `disable`, `prefer` (default — try TLS, fall back
 npx @onreza/sqlx-js migrate add init
 ```
 
-Edit the created file (`migrations/0001_init.up.sql`):
+The command creates matching `.up.sql` and `.down.sql` stubs. Edit the `.up.sql` file (`migrations/0001_init.up.sql`):
 
 ```sql
 CREATE TABLE users (
@@ -99,7 +99,7 @@ During local development, validate the migration and regenerate query artifacts
 npx @onreza/sqlx-js migrate dev
 ```
 
-`migrate dev` does not touch your application database. It creates a temporary shadow database using `DATABASE_URL` credentials, applies migrations from scratch, validates that the latest non-squash `.down.sql` restores the schema, prepares SQL queries against the resulting schema, writes `.sqlx-js/` and `sqlx-js-env.d.ts`, then drops the shadow database.
+`migrate dev` does not touch your application database. It creates a temporary shadow database using `DATABASE_URL` credentials, applies migrations from scratch, validates that the latest migration's `.down.sql` restores the previous schema (squash baselines may omit `.down.sql`), prepares SQL queries against the resulting schema, writes `.sqlx-js/` and `sqlx-js-env.d.ts`, then drops the shadow database.
 
 When you want to update your local application database, run:
 
@@ -152,7 +152,7 @@ Unknown queries, wrong parameter types, and dynamic strings are compile errors.
 
 ### `sql.file(path, ...params)`
 
-Load SQL from an external file. The path is resolved against the source file at scan time (so `prepare` can read it), and against `process.cwd()` at runtime (so the running process can read it). Both must point at the same content.
+Load SQL from an external file. At prepare time the scanner reads the path relative to the source file. The generated `KnownFileQueries` key is the resolved SQL file path relative to `--root`; at runtime `sql.file(...)` reads the string argument relative to `process.cwd()`.
 
 ```ts
 // queries/top_admins.sql
@@ -165,7 +165,7 @@ const admins = await sql.file("queries/top_admins.sql", "admin", 5);
 // admins: { id: bigint; name: string }[]
 ```
 
-File-backed queries are emitted into a separate `KnownFileQueries` interface; the path becomes the type key.
+File-backed queries are emitted into a separate `KnownFileQueries` interface. Because the type key is the root-relative resolved SQL file path, keep file-backed call sites under a convention where that key matches the runtime string literal; the example keeps those call sites at the project root. Nested source-relative file paths are a current limitation.
 
 ### `sql.one(query, ...params)` and `sql.optional(query, ...params)`
 
@@ -240,7 +240,7 @@ const orderBy = sql.id("users", "created_at");
 await unsafe(`SELECT id, email FROM ${sql.id("users")} ORDER BY ${orderBy} DESC`);
 ```
 
-The default snapshot path is `.sqlx-js/schema/schema.json`. Override it at runtime with `SQLX_JS_SCHEMA_PATH`. Pass schema-qualified identifiers as separate segments: `sql.id("public", "users")`, not `sql.id("public.users")`.
+The default snapshot path is `.sqlx-js/schema/schema.json`. Override it at runtime with `SQLX_JS_SCHEMA_PATH`. `sql.id(...)` accepts one to three identifier segments. Pass schema-qualified identifiers as separate segments: `sql.id("public", "users")`, not `sql.id("public.users")`.
 
 ### `migrate(options)`
 
@@ -286,13 +286,13 @@ setClient(createClient(process.env.DATABASE_URL, {
   statementTimeoutMs: 5000,
   // Fires after every query/transaction statement, success or failure.
   onQuery: ({ query, params, durationMs, rowCount, error }) => {
-    if (error) logger.error({ query, error });        // error is a PgError
+    if (error) logger.error({ query, error });        // database errors are PgError
     else if (durationMs > 200) logger.warn({ slow: query, durationMs, rowCount });
   },
 }));
 ```
 
-The `onQuery` hook works on any runtime (Node/Bun/Deno) and is the integration point for metrics, tracing, and slow-query logging — sqlx-js does not log queries itself. The event carries the raw `params`, which may contain personal or sensitive data — don't log them blindly; redact or omit `params` in shared sinks.
+The `onQuery` hook is the integration point for metrics, tracing, and slow-query logging — sqlx-js does not log queries itself. The event carries the raw `params`, which may contain personal or sensitive data — don't log them blindly; redact or omit `params` in shared sinks. Database errors are normalized to `PgError`; transport and non-database errors pass through unchanged.
 
 ### `clearSqlFileCache()`
 
@@ -313,7 +313,7 @@ try {
 }
 ```
 
-`sql.one` throws `NoRowsError` on 0 rows and `TooManyRowsError` (with `.actual`) on >1. Any database error raised by the runtime — whatever the adapter — is normalized into a `PgError`, so `e instanceof PgError` works the same in `prepare`, `migrate`, and ordinary `sql(...)` calls. `PgError` exposes `.code`, `.position`, `.hint`, `.detail`, `.severity`, `.schema`, `.table`, `.column`, `.constraint`, and the original driver error on `.cause`. Non-database failures (e.g. a dropped connection) are rethrown unchanged.
+`sql.one` throws `NoRowsError` on 0 rows and `TooManyRowsError` (with `.actual`) on >1. Any database error raised by the default runtime is normalized into a `PgError`, so `e instanceof PgError` works the same in `prepare`, `migrate`, and ordinary `sql(...)` calls. `PgError` exposes `.code`, `.position`, `.hint`, `.detail`, `.severity`, `.schema`, `.table`, `.column`, `.constraint`, and the original driver error on `.cause`. Non-database failures (e.g. a dropped connection) are rethrown unchanged.
 
 ### Transactions with options
 
@@ -336,16 +336,16 @@ In addition to `import { sql } from "@onreza/sqlx-js"`, the scanner recognises `
 ```
 sqlx-js init [--root <dir>]
 sqlx-js prepare [--check | --watch] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
-sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] | verify [--shadow-admin-url <url> | --shadow-url <url>] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] | archive list | archive restore <name> [--force] [--migrations <dir>]
+sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | verify [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] [--pg-dump <path>] [--lock-timeout <ms>] | archive list | archive restore <name> [--force]
 sqlx-js schema dump | check [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
 sqlx-js --version | --help
 ```
 
-`prepare` describes queries across a small connection pool (default 8, override with `SQLX_JS_PREPARE_CONCURRENCY`) for faster cold runs on large projects.
+Regular `prepare` describes queries across a small connection pool (default 8, override with `SQLX_JS_PREPARE_CONCURRENCY`) for faster cold runs on large projects. Watch mode keeps one session warm and reuses it between debounced changes.
 
 | Flag                  | Meaning                                                                              |
 |-----------------------|--------------------------------------------------------------------------------------|
-| `--check`             | Offline: verify cache matches sources, no database required.                         |
+| `--check`             | Offline: verify every scanned query is present in cache, no database required.       |
 | `--watch`             | Persistent connection, re-prepare on file change.                                    |
 | `--root <dir>`        | Source/cache/migrations root (default: cwd).                                         |
 | `--dts <path>`        | Declarations output (default: `<root>/sqlx-js-env.d.ts`).                           |
@@ -354,7 +354,7 @@ sqlx-js --version | --help
 | `--dry-run`           | For `migrate run` / `migrate revert`: validate without applying to the target DB.   |
 | `--json`              | Machine-readable output for `migrate info/check` and migration dry-runs.            |
 | `--force`             | For `migrate archive restore`: allow overwriting existing migration files.           |
-| `--lock-timeout <ms>` | Advisory-lock acquisition timeout for `migrate run` / `migrate revert`.              |
+| `--lock-timeout <ms>` | Advisory-lock acquisition timeout for `migrate run` / `revert` / `dev` / `verify` / `squash`. |
 | `--shadow-url <url>`  | Use an existing disposable shadow DB instead of auto-creating one.                   |
 | `--shadow-admin-url <url>` | Admin/maintenance DB URL used to auto-create shadow DBs.                       |
 | `--replace`           | For `migrate squash`: archive replaced migration files after writing the baseline.   |
@@ -363,9 +363,9 @@ sqlx-js --version | --help
 | `--manifest <path>`   | LLM schema manifest path (default: `<root>/.sqlx-js/schema/schema.md`).             |
 | `--no-manifest`       | Skip writing the LLM schema manifest during `schema dump`.                           |
 
-All flags accept both `--flag value` and `--flag=value` forms.
+Flags that take a value accept both `--flag value` and `--flag=value` forms.
 
-`DATABASE_URL` must be set for any command that touches the application database or auto-creates a shadow database. `SHADOW_ADMIN_DATABASE_URL` can point at a maintenance/admin database when the application user cannot `CREATE DATABASE`; `SHADOW_DATABASE_URL` can point at a pre-created disposable shadow database. Supported URL search params: `sslmode`, `application_name`, `connect_timeout`.
+`DATABASE_URL` must be set for any command that touches the application database or auto-creates a shadow database. `SHADOW_ADMIN_DATABASE_URL` can point at a maintenance/admin database when the application user cannot `CREATE DATABASE`; `SHADOW_DATABASE_URL` can point at a pre-created disposable shadow database. The internal wire client understands `sslmode`, `sslrootcert`, `sslcert`, `sslkey`, `application_name`, `connect_timeout` (seconds), and `statement_timeout` (milliseconds).
 
 ### Development and deployment flows
 
@@ -377,7 +377,7 @@ sqlx-js migrate add add_users
 sqlx-js migrate dev
 ```
 
-`migrate dev` creates a disposable shadow database, applies all migrations from scratch, validates that the latest non-squash `.down.sql` restores the schema, prepares project SQL against the shadow schema, writes `.sqlx-js/` plus `sqlx-js-env.d.ts`, and drops the shadow database. This means you can keep editing a local WIP migration before it is merged. You do not need to drop your application database or create a new migration for every local edit.
+`migrate dev` creates a disposable shadow database, applies all migrations from scratch, validates that the latest migration's `.down.sql` restores the previous schema (squash baselines may omit `.down.sql`), prepares project SQL against the shadow schema, writes `.sqlx-js/` plus `sqlx-js-env.d.ts`, and drops the shadow database. This means you can keep editing a local WIP migration before it is merged. You do not need to drop your application database or create a new migration for every local edit.
 
 Use `migrate verify` in PR/CI before merge:
 
@@ -428,7 +428,7 @@ On an empty database, the baseline runs as ordinary schema SQL. On an already-mi
 - `.sqlx-js/schema/schema.json` — machine-readable contract for runtime identifier whitelisting and CI drift checks.
 - `.sqlx-js/schema/schema.md` — compact LLM-facing manifest with tables, columns, constraints, indexes, types, and functions.
 
-`schema check` re-introspects the database and fails if the committed snapshot is stale. With `--shadow-url`, both `prepare` and `schema dump/check` first apply pending migrations to the shadow database, then use that database as the source of truth. In watch mode, pending shadow migrations are checked before every re-prepare; when a migration is applied, the prepare session is reopened so schema metadata is not reused across DDL changes.
+`schema check` re-introspects the database and fails if the committed snapshot is stale. With `--shadow-url`, both `prepare` and `schema dump/check` first apply pending migrations to the shadow database, then use that database as the source of truth. Unlike `migrate dev` / `verify` / `squash`, these commands do not clear an explicit shadow database first. In watch mode, pending shadow migrations are checked before every re-prepare; when a migration is applied, the prepare session is reopened so schema metadata is not reused across DDL changes.
 
 ### Error output
 
@@ -477,7 +477,7 @@ declare global {
 export {};
 ```
 
-After re-running `prepare`, every `jsonb` column or parameter declared in `jsonbTypes` is checked against the corresponding TypeScript type.
+After re-running `prepare`, every `jsonb` column or parameter declared in `jsonbTypes` is checked against the corresponding TypeScript type. Columns without a custom mapping use `JsonValue` for result rows and `JsonInput` for parameters, both exported by `@onreza/sqlx-js`, so non-JSON inputs such as `Date`, functions, and `bigint` are rejected by TypeScript while plain JSON objects, arrays, strings, numbers, booleans, and nested JSON `null` values are accepted. Top-level SQL `null` is added separately as `| null` only when the mapped database parameter is nullable.
 
 ### Extension types and `customTypes`
 
@@ -494,7 +494,7 @@ sqlx-js ships with a built-in registry that resolves popular PostgreSQL extensio
 | `lquery`          | `string`                           | ltree             |
 | `ltxtquery`       | `string`                           | ltree             |
 
-Add or override mappings via `customTypes` in `sqlx-js.config.ts`. Keys are `pg_type.typname` values (the bare type name; namespacing isn't required):
+Add or override mappings via `customTypes` in `sqlx-js.config.ts`. Keys are `pg_type.typname` values (the bare type name). The registry is global by type name, so two schemas with the same `typname` cannot be mapped differently:
 
 ```ts
 import type { SqlxJsConfig } from "@onreza/sqlx-js";
@@ -561,14 +561,16 @@ Releases are automated via `release-please`: pushes to `main` accumulate into a
 `sqlx-js` is a young library. Known gaps:
 
 - PostgreSQL only (no MySQL or SQLite).
+- The scanner only follows direct named imports and namespace imports from `@onreza/sqlx-js`; it does not follow re-exports, dynamic aliases, or tagged-template calls.
 - `INSERT INTO t VALUES (...)` without an explicit column list isn't parameter-mapped.
 - `SELECT *` falls back to conservative nullability.
+- Statements without a row description, such as `UPDATE ...` without `RETURNING`, are emitted with `row: never`, so the public return type is `Promise<never[]>`.
 - Nested CTE references (CTE-`b` referencing CTE-`a` in the same `WITH`) and `WITH RECURSIVE` are not analysed transitively — at worst this produces extra `T | null`. Use `AS "id!"` overrides if needed.
 - Column names whose **real** name (not an alias) ends with `!` or `?` are not supported — the runtime strips those suffixes assuming an override. Use `AS "alias"` if you have such a column.
 - Migrations run inside `BEGIN/COMMIT`. DDL that disallows transactions (`CREATE INDEX CONCURRENTLY`, `VACUUM`, `REINDEX CONCURRENTLY`, …) will fail; split such operations into separate migrations executed outside the runner.
 - The **internal** wire client (used by `migrate run`, `prepare`, and the runtime `migrate()` helper) reads `sslmode`, `sslrootcert`/`sslcert`/`sslkey`, `application_name`, `connect_timeout`, and `statement_timeout` from `DATABASE_URL`. The default runtime `sql()` path delegates connection handling to Postgres.js; configure TLS, pooling, and timeouts through the `DATABASE_URL` and `createClient(...)` options it understands (`statementTimeoutMs` is a convenience that maps to a per-connection `statement_timeout`).
 - `connect_timeout` bounds the entire internal-client connect, including the TLS handshake and SCRAM authentication.
-- `sql.file(path)` path is matched literally between scan time and runtime — they must agree on the working directory. Document a convention for your team (e.g. always run from the repo root).
+- `sql.file(path)` has a path-key mismatch to be aware of: prepare resolves the file relative to the source file, codegen keys it by root-relative resolved path, and runtime reads the literal path relative to `process.cwd()`. Keep a project convention and verify with `tsc` after `prepare`.
 
 See [ROADMAP.md](./ROADMAP.md) for what's planned.
 

package/dist/bin/sqlx-js.js

@@ -25,26 +25,26 @@ function help() {
 usage:
   sqlx-js init [--root <dir>]
   sqlx-js prepare [--check | --watch] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
-  sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] | verify [--shadow-admin-url <url> | --shadow-url <url>] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] | archive list | archive restore <name> [--force]
+  sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | verify [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | run [--dry-run] [--json] [--lock-timeout <ms>] | info [--json] | check [--json] | revert [--dry-run] [--json] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] | add <name> | squash <name> [--shadow-admin-url <url> | --shadow-url <url>] [--replace] [--pg-dump <path>] [--lock-timeout <ms>] | archive list | archive restore <name> [--force]
   sqlx-js schema dump | check [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
   sqlx-js --version
 
 env:
-  DATABASE_URL=postgres://...  (supports ?sslmode=require|verify-ca|verify-full)
+  DATABASE_URL=postgres://...  (supports sslmode, cert paths, application_name, connect_timeout, statement_timeout)
   SHADOW_DATABASE_URL=postgres://...  (optional pre-created disposable shadow DB)
   SHADOW_ADMIN_DATABASE_URL=postgres://...  (optional admin URL for auto-created shadow DBs)
 
 flags:
   --root <dir>             scan root (default: cwd)
   --dts <path>             declarations output (default: <root>/sqlx-js-env.d.ts)
-  --check                  offline mode: validate cache vs sources, no DB
+  --check                  offline mode: verify scanned queries exist in cache, no DB
   --watch                  re-prepare on file change (persistent PG connection)
   --no-prune               keep orphaned cache entries (default: remove)
   --migrations <dir>       migrations directory (default: <root>/migrations)
   --dry-run                validate and print migrate run/revert plan without applying migrations
   --json                   machine-readable output for migrate info/check and migrate run/revert --dry-run
   --force                  allow archive restore to overwrite existing migration files
-  --lock-timeout <ms>      advisory-lock acquisition timeout for migrate run/revert
+  --lock-timeout <ms>      advisory-lock acquisition timeout for migrate run/revert/dev/verify/squash
   --shadow-url <url>       use an existing disposable shadow DB instead of auto-creating one
   --shadow-admin-url <url> admin/maintenance DB URL used to auto-create shadow DBs
   --replace                archive replaced migrations after migrate squash writes the baseline

package/dist/src/cache.d.ts

@@ -7,6 +7,7 @@ export type CacheColumn = {
 };
 export type CacheEntry = {
     query: string;
+    inlineQueries?: string[];
     paramOids: number[];
     paramTsTypes: string[];
     paramNullable?: boolean[];

package/dist/src/cache.js

@@ -2,9 +2,136 @@ import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "node:fs";
 import { join } from "node:path";
 export function fingerprint(query) {
-    const norm = query.replace(/\s+/g, " ").trim();
+    const norm = normalizeForFingerprint(query);
     return createHash("sha256").update(norm).digest("hex").slice(0, 16);
 }
+function normalizeForFingerprint(query) {
+    let out = "";
+    let pendingSpace = false;
+    let i = 0;
+    const emit = (text) => {
+        if (pendingSpace && out.length > 0)
+            out += " ";
+        out += text;
+        pendingSpace = false;
+    };
+    const markSpace = () => {
+        if (out.length > 0)
+            pendingSpace = true;
+    };
+    while (i < query.length) {
+        const ch = query[i];
+        if (/\s/.test(ch)) {
+            markSpace();
+            i++;
+            continue;
+        }
+        if (ch === "-" && query[i + 1] === "-") {
+            i = readLineComment(query, i);
+            markSpace();
+            continue;
+        }
+        if (ch === "/" && query[i + 1] === "*") {
+            i = readBlockComment(query, i);
+            markSpace();
+            continue;
+        }
+        if (ch === "'") {
+            const next = readSingleQuoted(query, i, isEscapeStringPrefix(query, i));
+            emit(query.slice(i, next));
+            i = next;
+            continue;
+        }
+        if (ch === "\"") {
+            const next = readQuotedIdentifier(query, i);
+            emit(query.slice(i, next));
+            i = next;
+            continue;
+        }
+        if (ch === "$") {
+            const next = readDollarQuoted(query, i);
+            if (next !== null) {
+                emit(query.slice(i, next));
+                i = next;
+                continue;
+            }
+        }
+        emit(ch);
+        i++;
+    }
+    return out;
+}
+function readSingleQuoted(query, start, escapeBackslash) {
+    let i = start + 1;
+    while (i < query.length) {
+        const ch = query[i];
+        if (escapeBackslash && ch === "\\") {
+            i += 2;
+            continue;
+        }
+        if (ch === "'") {
+            if (query[i + 1] === "'") {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        i++;
+    }
+    return query.length;
+}
+function readQuotedIdentifier(query, start) {
+    let i = start + 1;
+    while (i < query.length) {
+        if (query[i] === "\"") {
+            if (query[i + 1] === "\"") {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        i++;
+    }
+    return query.length;
+}
+function readDollarQuoted(query, start) {
+    let tagEnd = start + 1;
+    while (tagEnd < query.length && /[A-Za-z0-9_]/.test(query[tagEnd]))
+        tagEnd++;
+    if (query[tagEnd] !== "$")
+        return null;
+    const tag = query.slice(start, tagEnd + 1);
+    const end = query.indexOf(tag, tagEnd + 1);
+    return end === -1 ? query.length : end + tag.length;
+}
+function readLineComment(query, start) {
+    const end = query.indexOf("\n", start + 2);
+    return end === -1 ? query.length : end + 1;
+}
+function readBlockComment(query, start) {
+    let depth = 1;
+    let i = start + 2;
+    while (i < query.length && depth > 0) {
+        if (query[i] === "/" && query[i + 1] === "*") {
+            depth++;
+            i += 2;
+            continue;
+        }
+        if (query[i] === "*" && query[i + 1] === "/") {
+            depth--;
+            i += 2;
+            continue;
+        }
+        i++;
+    }
+    return i;
+}
+function isEscapeStringPrefix(query, quoteIndex) {
+    if (quoteIndex === 0 || query[quoteIndex - 1]?.toLowerCase() !== "e")
+        return false;
+    const beforePrefix = query[quoteIndex - 2];
+    return beforePrefix === undefined || !/[A-Za-z0-9_$]/.test(beforePrefix);
+}
 export function effectiveNullable(c) {
     if (c.override === "non-null")
         return false;

package/dist/src/codegen.js

@@ -31,21 +31,23 @@ function emitModule(lines, moduleName, entries) {
     lines.push(`declare module ${JSON.stringify(moduleName)} {`);
     lines.push("  interface KnownQueries {");
     const inlineSeen = new Set();
-    const inlineEntries = entries.filter((e) => {
-        if (e.hasInline === true)
-            return true;
-        if (e.hasInline === false)
-            return false;
-        return !e.filePaths || e.filePaths.length === 0;
-    });
-    for (const e of inlineEntries.slice().sort((a, b) => a.query.localeCompare(b.query))) {
-        if (inlineSeen.has(e.query))
+    const inlinePairs = [];
+    for (const e of entries) {
+        const emitInline = e.hasInline === true || (e.hasInline !== false && (!e.filePaths || e.filePaths.length === 0));
+        if (!emitInline)
+            continue;
+        const queries = e.inlineQueries && e.inlineQueries.length > 0 ? e.inlineQueries : [e.query];
+        for (const query of queries)
+            inlinePairs.push({ query, entry: e });
+    }
+    for (const { query, entry } of inlinePairs.slice().sort((a, b) => a.query.localeCompare(b.query))) {
+        if (inlineSeen.has(query))
             continue;
-        inlineSeen.add(e.query);
-        const { params, row } = entrySignature(e);
-        if (e.degraded)
-            lines.push(`    /** Nullability inference degraded: ${e.degraded.reason}. All result columns conservatively typed as nullable. */`);
-        lines.push(`    ${JSON.stringify(e.query)}: { params: ${params}; row: ${row} };`);
+        inlineSeen.add(query);
+        const { params, row } = entrySignature(entry);
+        if (entry.degraded)
+            lines.push(`    /** Nullability inference degraded: ${entry.degraded.reason}. All result columns conservatively typed as nullable. */`);
+        lines.push(`    ${JSON.stringify(query)}: { params: ${params}; row: ${row} };`);
     }
     lines.push("  }");
     lines.push("");

package/dist/src/commands/prepare.js

@@ -10,6 +10,7 @@ import { buildParamMap } from "../pg/param-map.js";
 import { mergeExtensionTypes } from "../pg/extensions.js";
 const JSON_OIDS = new Set([114, 3802]);
 const JSON_ARRAY_OIDS = new Set([199, 3807]);
+const JSON_INPUT = 'import("@onreza/sqlx-js").JsonInput';
 function enumUnion(values) {
     if (values.length === 0)
         return "never";
@@ -56,13 +57,28 @@ function resolveParamTs(paramIndex, paramOid, paramMap, schema, cfg) {
     if (JSON_OIDS.has(paramOid) || JSON_ARRAY_OIDS.has(paramOid)) {
         const target = paramMap.get(paramIndex);
         if (target) {
-            const decl = lookupJsonbType(cfg, target.schema ?? "public", target.table, target.column);
+            const column = resolveTargetColumn(target, schema);
+            const decl = column ? lookupJsonbType(cfg, target.schema ?? "public", target.table, column) : undefined;
             if (decl)
                 return JSON_ARRAY_OIDS.has(paramOid) ? `(${decl})[]` : decl;
         }
+        return JSON_ARRAY_OIDS.has(paramOid) ? `(${JSON_INPUT})[]` : JSON_INPUT;
     }
     return resolveTs(paramOid, (oid) => schema.customType(oid));
 }
+function resolveTargetColumn(target, schema) {
+    if (target.column)
+        return target.column;
+    if (target.columnIndex === undefined)
+        return undefined;
+    const oid = schema.resolveTable(target.schema, target.table);
+    if (oid === undefined)
+        return undefined;
+    const cols = schema.columnsOf(oid);
+    if (!cols)
+        return undefined;
+    return [...cols.values()].sort((a, b) => a.attnum - b.attnum)[target.columnIndex - 1]?.name;
+}
 function resolveParamNullable(paramIndex, pm, schema) {
     if (pm.forceNullable.has(paramIndex))
         return true;
@@ -73,7 +89,10 @@ function resolveParamNullable(paramIndex, pm, schema) {
         const oid = schema.resolveTable(t.schema, t.table);
         if (oid === undefined)
             return false;
-        const col = schema.columnsOf(oid)?.get(t.column);
+        const column = resolveTargetColumn(t, schema);
+        if (!column)
+            return false;
+        const col = schema.columnsOf(oid)?.get(column);
         if (!col)
             return false;
         return !col.notNull;
@@ -100,6 +119,15 @@ function snippet(query, max = 80) {
     const oneLine = query.replace(/\s+/g, " ").trim();
     return oneLine.length > max ? oneLine.slice(0, max) + "…" : oneLine;
 }
+function siteUsage(sites) {
+    const inlineQueries = Array.from(new Set(sites.filter((s) => s.kind !== "file").map((s) => s.query))).sort();
+    const filePaths = Array.from(new Set(sites.filter((s) => s.kind === "file").map((s) => s.sqlFilePath).filter(Boolean))).sort();
+    return {
+        hasInline: inlineQueries.length > 0,
+        ...(inlineQueries.length > 0 ? { inlineQueries } : {}),
+        ...(filePaths.length > 0 ? { filePaths } : {}),
+    };
+}
 export async function openSession(opts) {
     const userCfg = await loadConfig(opts.root);
     const cfg = parseDatabaseUrl(opts.databaseUrl);
@@ -284,13 +312,9 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
             forceNullable: new Set(),
             dmlBound: new Set(),
         };
-        const fileSites = r.sites.filter((s) => s.kind === "file");
-        const hasInline = r.sites.some((s) => s.kind !== "file");
-        const filePaths = fileSites.length > 0
-            ? Array.from(new Set(fileSites.map((s) => s.sqlFilePath))).sort()
-            : undefined;
         const entry = {
             query: r.query,
+            ...siteUsage(r.sites),
             paramOids: r.paramOids,
             paramTsTypes: r.paramOids.map((o, idx) => resolveParamTs(idx + 1, o, pm.targets, schema, userCfg)),
             paramNullable: r.paramOids.map((_o, idx) => resolveParamNullable(idx + 1, pm, schema)),
@@ -306,8 +330,6 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
                 };
             }),
             hasResultSet: r.fields.length > 0,
-            hasInline,
-            ...(filePaths ? { filePaths } : {}),
             ...(analysis.degraded ? { degraded: analysis.degraded } : {}),
         };
         cache.write(r.fp, entry);
@@ -351,7 +373,10 @@ export async function runPrepare(opts) {
             console.error(`\nsqlx-js prepare --check: ${stale} stale/missing entries. Run \`sqlx-js prepare\` against a live DB.`);
             process.exit(1);
         }
-        const entries = [...unique.values()].map((u) => cache.read(u.fp)).filter(Boolean);
+        const entries = [...unique.values()].map((u) => {
+            const entry = cache.read(u.fp);
+            return entry ? { ...entry, ...siteUsage(u.sites) } : null;
+        }).filter((e) => e !== null);
         emitDts(opts.dtsPath, entries);
         console.log(`ok — ${entries.length} unique queries, types regenerated`);
         return;

package/dist/src/index.d.ts

@@ -4,6 +4,18 @@ export interface KnownQueries {
 }
 export interface KnownFileQueries {
 }
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export type JsonArray = readonly JsonValue[];
+export type JsonInput = string | number | boolean | JsonInputObject | JsonInputArray;
+export type JsonInputValue = JsonPrimitive | JsonInputObject | JsonInputArray;
+export type JsonInputObject = {
+    readonly [key: string]: JsonInputValue | undefined;
+};
+export type JsonInputArray = readonly JsonInputValue[];
 export type { SqlxJsConfig } from "./config.js";
 export type { SslMode, ConnConfig } from "./pg/wire.js";
 export { PgError, ConnectionLostError } from "./pg/wire.js";

package/dist/src/pg/oids.js

@@ -1,3 +1,4 @@
+const JSON_VALUE = 'import("@onreza/sqlx-js").JsonValue';
 const SCALAR = {
     16: { ts: "boolean" },
     17: { ts: "Uint8Array" },
@@ -11,7 +12,7 @@ const SCALAR = {
     27: { ts: "string" },
     28: { ts: "string" },
     29: { ts: "string" },
-    114: { ts: "unknown" },
+    114: { ts: JSON_VALUE },
     142: { ts: "string" },
     600: { ts: "string" },
     601: { ts: "string" },
@@ -44,7 +45,7 @@ const SCALAR = {
     3220: { ts: "string" },
     3614: { ts: "string" },
     3615: { ts: "string" },
-    3802: { ts: "unknown" },
+    3802: { ts: JSON_VALUE },
     3904: { ts: "string" },
     3906: { ts: "string" },
     3908: { ts: "string" },

package/dist/src/pg/param-map.d.ts

@@ -1,7 +1,8 @@
 export type ParamTarget = {
     schema?: string;
     table: string;
-    column: string;
+    column?: string;
+    columnIndex?: number;
 };
 export type ParamMap = Map<number, ParamTarget>;
 export type ParamMapResult = {

package/dist/src/pg/param-map.js

@@ -12,9 +12,9 @@ export async function buildParamMap(sql) {
     else if (stmt.UpdateStmt)
         walkUpdate(stmt.UpdateStmt, targets, dmlBound);
     else if (stmt.SelectStmt)
-        walkWhere(stmt.SelectStmt.whereClause, defaultRel(stmt.SelectStmt), targets);
+        walkSelect(stmt.SelectStmt, targets, dmlBound);
     else if (stmt.DeleteStmt)
-        walkWhere(stmt.DeleteStmt.whereClause, relOf(stmt.DeleteStmt.relation), targets);
+        walkDelete(stmt.DeleteStmt, targets, dmlBound);
     walkForceNullable(stmt, false, forceNullable);
     return { targets, forceNullable, dmlBound };
 }
@@ -22,6 +22,7 @@ function walkInsert(ins, map, dmlBound) {
     const rel = relOf(ins.relation);
     if (!rel)
         return;
+    const scope = scopeFromRelationNode(ins.relation, rel);
     const cols = (ins.cols ?? [])
         .map((c) => c?.ResTarget?.name)
         .filter((n) => typeof n === "string");
@@ -29,82 +30,162 @@ function walkInsert(ins, map, dmlBound) {
     for (const row of valuesLists) {
         const items = row?.List?.items ?? [];
         for (let i = 0; i < items.length; i++) {
-            const colName = cols[i];
-            if (!colName)
-                continue;
             const pn = paramNumber(items[i]);
             if (pn !== null) {
-                map.set(pn, { ...rel, column: colName });
-                dmlBound.add(pn);
+                bindParam(map, dmlBound, pn, insertTarget(rel, cols, i), true);
             }
         }
     }
-    if (ins.returningList) {
-        for (const rt of ins.returningList) {
-            collectFromExpr(rt?.ResTarget?.val, rel, map);
+    const select = ins.selectStmt?.SelectStmt;
+    if (select && !select.valuesLists && Array.isArray(select.targetList)) {
+        for (let i = 0; i < select.targetList.length; i++) {
+            const pn = paramNumber(select.targetList[i]?.ResTarget?.val);
+            if (pn !== null) {
+                bindParam(map, dmlBound, pn, insertTarget(rel, cols, i), true);
+            }
         }
+        walkSelect(select, map, dmlBound);
     }
-    walkWhere(ins.whereClause, rel, map);
+    if (ins.returningList)
+        walkExpr(ins.returningList, scope, map, dmlBound);
+    walkOnConflict(ins.onConflictClause, rel, scope, map, dmlBound);
+    walkExpr(ins.whereClause, scope, map, dmlBound);
+}
+function walkOnConflict(conflict, rel, scope, map, dmlBound) {
+    if (!conflict || conflict.action !== "ONCONFLICT_UPDATE")
+        return;
+    for (const rt of conflict.targetList ?? []) {
+        const colName = rt?.ResTarget?.name;
+        if (typeof colName !== "string")
+            continue;
+        const pn = paramNumber(rt.ResTarget.val);
+        if (pn !== null) {
+            bindParam(map, dmlBound, pn, { ...rel, column: colName }, true);
+        }
+    }
+    walkExpr(conflict.whereClause, scope, map, dmlBound);
 }
 function walkUpdate(upd, map, dmlBound) {
     const rel = relOf(upd.relation);
     if (!rel)
         return;
+    const scope = scopeFromRelationNode(upd.relation, rel);
+    addRangeVars(upd.fromClause ?? [], scope);
     for (const rt of upd.targetList ?? []) {
         const colName = rt?.ResTarget?.name;
         if (typeof colName !== "string")
             continue;
         const pn = paramNumber(rt.ResTarget.val);
         if (pn !== null) {
-            map.set(pn, { ...rel, column: colName });
-            dmlBound.add(pn);
+            bindParam(map, dmlBound, pn, { ...rel, column: colName }, true);
         }
     }
-    walkWhere(upd.whereClause, rel, map);
+    walkExpr(upd.whereClause, scope, map, dmlBound);
 }
-function walkWhere(node, defaultRel, map) {
-    if (!node || !defaultRel)
+function walkDelete(del, map, dmlBound) {
+    const rel = relOf(del.relation);
+    if (!rel)
         return;
+    const scope = scopeFromRelationNode(del.relation, rel);
+    addRangeVars(del.usingClause ?? [], scope);
+    walkExpr(del.whereClause, scope, map, dmlBound);
+}
+function walkSelect(select, map, dmlBound) {
+    const scope = scopeFromSelect(select);
+    walkJoinQuals(select.fromClause ?? [], scope, map, dmlBound);
+    walkExpr(select.whereClause, scope, map, dmlBound);
+}
+function walkExpr(node, scope, map, dmlBound) {
+    if (!node)
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walkExpr(item, scope, map, dmlBound);
+        return;
+    }
     if (node.BoolExpr) {
         for (const a of node.BoolExpr.args ?? [])
-            walkWhere(a, defaultRel, map);
+            walkExpr(a, scope, map, dmlBound);
         return;
     }
     if (node.A_Expr) {
-        collectFromExpr(node, defaultRel, map);
+        collectFromExpr(node, scope, map, dmlBound);
+        walkExpr(node.A_Expr.lexpr, scope, map, dmlBound);
+        walkExpr(node.A_Expr.rexpr, scope, map, dmlBound);
+        return;
+    }
+    if (node.TypeCast) {
+        walkExpr(node.TypeCast.arg, scope, map, dmlBound);
+        return;
+    }
+    if (node.NullTest) {
+        walkExpr(node.NullTest.arg, scope, map, dmlBound);
+        return;
+    }
+    if (node.CoalesceExpr) {
+        walkExpr(node.CoalesceExpr.args ?? [], scope, map, dmlBound);
+        return;
+    }
+    if (node.FuncCall) {
+        walkExpr(node.FuncCall.args ?? [], scope, map, dmlBound);
+        return;
+    }
+    if (node.CaseExpr) {
+        walkExpr(node.CaseExpr.arg, scope, map, dmlBound);
+        walkExpr(node.CaseExpr.args ?? [], scope, map, dmlBound);
+        walkExpr(node.CaseExpr.defresult, scope, map, dmlBound);
+        return;
+    }
+    if (node.CaseWhen) {
+        walkExpr(node.CaseWhen.expr, scope, map, dmlBound);
+        walkExpr(node.CaseWhen.result, scope, map, dmlBound);
+        return;
+    }
+    if (node.SubLink) {
+        const sub = node.SubLink.subselect?.SelectStmt;
+        if (sub)
+            walkSelect(sub, map, dmlBound);
+        walkExpr(node.SubLink.testexpr, scope, map, dmlBound);
         return;
     }
 }
-function collectFromExpr(node, defaultRel, map) {
-    if (!node || !defaultRel)
+function collectFromExpr(node, scope, map, dmlBound) {
+    if (!node)
         return;
     if (node.A_Expr) {
         const e = node.A_Expr;
         const opName = e.name?.[0]?.String?.sval;
         if (e.kind === "AEXPR_OP" && opName === "=") {
-            tryBind(e.lexpr, e.rexpr, defaultRel, map);
-            tryBind(e.rexpr, e.lexpr, defaultRel, map);
+            tryBind(e.lexpr, e.rexpr, scope, map, dmlBound);
+            tryBind(e.rexpr, e.lexpr, scope, map, dmlBound);
         }
         if (e.kind === "AEXPR_IN") {
-            const colName = colNameOf(e.lexpr);
-            if (colName) {
-                const list = Array.isArray(e.rexpr) ? e.rexpr : [];
+            const target = targetOfColumnRef(e.lexpr, scope);
+            if (target) {
+                const list = Array.isArray(e.rexpr) ? e.rexpr : e.rexpr?.List?.items ?? [];
                 for (const item of list) {
                     const pn = paramNumber(item);
                     if (pn !== null)
-                        map.set(pn, { ...defaultRel, column: colName });
+                        bindParam(map, dmlBound, pn, target, false);
                 }
             }
         }
     }
 }
-function tryBind(colSide, valSide, defaultRel, map) {
-    const colName = colNameOf(colSide);
+function tryBind(colSide, valSide, scope, map, dmlBound) {
+    const target = targetOfColumnRef(colSide, scope);
     const pn = paramNumber(valSide);
-    if (colName !== null && pn !== null)
-        map.set(pn, { ...defaultRel, column: colName });
+    if (target && pn !== null)
+        bindParam(map, dmlBound, pn, target, false);
 }
-function colNameOf(node) {
+function bindParam(map, dmlBound, pn, target, dml) {
+    if (!dml && dmlBound.has(pn))
+        return;
+    map.set(pn, target);
+    if (dml)
+        dmlBound.add(pn);
+}
+function stringFields(node) {
     if (!node?.ColumnRef)
         return null;
     const fields = node.ColumnRef.fields;
@@ -112,7 +193,25 @@ function colNameOf(node) {
         return null;
     if (fields.some((f) => f.A_Star !== undefined))
         return null;
-    return fields[fields.length - 1]?.String?.sval ?? null;
+    const out = fields.map((f) => f.String?.sval);
+    return out.every((s) => typeof s === "string") ? out : null;
+}
+function targetOfColumnRef(node, scope) {
+    const fields = stringFields(node);
+    if (!fields)
+        return null;
+    const column = fields[fields.length - 1];
+    if (fields.length === 1) {
+        return scope.defaultRel ? { ...scope.defaultRel, column } : null;
+    }
+    if (fields.length === 2) {
+        const qualifier = fields[0];
+        const rel = scope.aliases.get(qualifier) ?? scope.relations.find((r) => r.table === qualifier);
+        return rel ? { ...rel, column } : { table: qualifier, column };
+    }
+    const table = fields[fields.length - 2];
+    const schema = fields[fields.length - 3];
+    return { schema, table, column };
 }
 function paramNumber(node) {
     if (node?.ParamRef && typeof node.ParamRef.number === "number")
@@ -129,14 +228,56 @@ function relOf(relation) {
         return null;
     return { schema: relation.schemaname || undefined, table: name };
 }
-function defaultRel(select) {
-    const from = select?.fromClause;
-    if (!Array.isArray(from) || from.length !== 1)
-        return null;
-    const node = from[0];
-    if (node?.RangeVar)
-        return relOf(node.RangeVar);
-    return null;
+function insertTarget(rel, cols, index) {
+    const column = cols[index];
+    return column ? { ...rel, column } : { ...rel, columnIndex: index + 1 };
+}
+function scopeFromSelect(select) {
+    const scope = scopeFromRelations([], null);
+    addRangeVars(select?.fromClause ?? [], scope);
+    if (scope.relations.length === 1)
+        scope.defaultRel = scope.relations[0];
+    return scope;
+}
+function scopeFromRelations(relations, defaultRel) {
+    const scope = { aliases: new Map(), relations: [], defaultRel };
+    for (const rel of relations)
+        addRelation(scope, rel, rel.table);
+    return scope;
+}
+function scopeFromRelationNode(relation, rel) {
+    const scope = scopeFromRelations([rel], rel);
+    const alias = relation?.alias?.aliasname;
+    if (typeof alias === "string")
+        scope.aliases.set(alias, rel);
+    return scope;
+}
+function addRelation(scope, rel, alias) {
+    scope.relations.push(rel);
+    scope.aliases.set(alias, rel);
+}
+function addRangeVars(nodes, scope) {
+    for (const node of nodes) {
+        if (node?.RangeVar) {
+            const rel = relOf(node.RangeVar);
+            if (!rel)
+                continue;
+            const alias = node.RangeVar.alias?.aliasname ?? rel.table;
+            addRelation(scope, rel, alias);
+            continue;
+        }
+        if (node?.JoinExpr) {
+            addRangeVars([node.JoinExpr.larg, node.JoinExpr.rarg], scope);
+        }
+    }
+}
+function walkJoinQuals(nodes, scope, map, dmlBound) {
+    for (const node of nodes) {
+        if (!node?.JoinExpr)
+            continue;
+        walkExpr(node.JoinExpr.quals, scope, map, dmlBound);
+        walkJoinQuals([node.JoinExpr.larg, node.JoinExpr.rarg], scope, map, dmlBound);
+    }
 }
 function walkForceNullable(node, forceContext, out) {
     if (node === null || node === undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onreza/sqlx-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Compile-time-checked raw SQL for TypeScript + PostgreSQL. Inspired by sqlx.",
   "license": "MIT",
   "type": "module",