@onreza/sqlx-js 0.8.0 → 0.9.0

package/README.md

@@ -24,12 +24,13 @@ 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. Unmapped `json`/`jsonb` falls back to `JsonValue` for rows and `JsonInput` for parameters instead of `unknown`.
+- **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 an explicitly wrapped, structurally checked JSON parameter.
 - **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", ...)` — 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.
+- **Reusable query definitions** via `defineQuery`: declare one typed SQL contract and execute it through either a root client or transaction-scoped executor. `QueryParams`, `QueryRow`, and `QueryResult` expose its generated types without indexing a registry by SQL text.
 - **Unambiguous JSON and PostgreSQL array params** through `sql.json(...)` and `sql.array(...)`. Primitive JSON arrays cannot be silently encoded as PostgreSQL array literals.
 - **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.
 - **Sourcemap-accurate error reporting**: every prepare failure points to `file:line:column` of the originating `sql(...)` call site, with PG error code, position, and hint.
@@ -39,7 +40,7 @@ const rows = await sql(
 - **Optional pgschema workflow** via `init --schema-provider pgschema` and `sqlx-js db install|check|plan|apply` for PostgreSQL schema-as-code projects.
 - **Versioned offline cache** committed to your repo. `prepare --check` validates fingerprints, generator revision, and type-affecting config without a database; `prepare --verify` compares fresh live/shadow artifacts without writing.
 - **Schema snapshot + LLM manifest** via `schema dump` / `schema check`: tables, columns, constraints, indexes, types, and function/procedure metadata are introspected from PostgreSQL.
-- **Generated function catalog** via `KnownFunctions`: `prepare` records user-schema PostgreSQL functions/procedures from `pg_proc` with approximate parameter and return TypeScript types.
+- **Generated function catalog** via `KnownFunctions`: `prepare` records application-owned PostgreSQL functions/procedures from `pg_proc` with approximate parameter and return TypeScript types while excluding extension-owned internals by default.
 - **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.
 - **Single runtime adapter**: Postgres.js backs the runtime on Node/Bun-compatible environments — no Bun.SQL-specific adapter to choose.
@@ -48,6 +49,7 @@ const rows = await sql(
 - **Environment doctor** checks runtime versions, config loading, `.env`, database connectivity/permissions, cache metadata, tsconfig inclusion, and pgschema availability.
 - **Strict inference gate** promotes degraded nullability analysis and generated `unknown` query types to CI errors.
 - **GitHub/editor diagnostics adapter** converts versioned prepare JSON into workflow annotations or Unix problem-matcher output.
+- **Versioned query inventory** via `queries --json`, including stable query IDs, definition names, cardinality, call sites, SQL files, and cache state. The same command can emit a deterministic embedded-SQL module for bundled applications.
 
 ## Install
 
@@ -59,7 +61,7 @@ bun add @onreza/sqlx-js
 bun add --dev typescript
 ```
 
-Node.js 24 or newer is required. Bun users need Bun 1.3 or newer. TypeScript is an optional peer so production-only installs do not pull the compiler and its platform package into the application image; source scanning commands (`prepare`, `doctor`, `ci`, and migration development/verification) require it in development dependencies.
+Node.js 24 or newer is required. Bun users need Bun 1.3 or newer. TypeScript is an optional peer so production-only installs do not pull the compiler and its platform package into the application image; source scanning commands (`prepare`, `queries`, `doctor`, `ci`, and migration development/verification) require it in development dependencies.
 
 The package installs `sqlx-js` and `sqlx-js-diagnostics` binaries. The CLI examples below use `npx @onreza/sqlx-js`; `bunx @onreza/sqlx-js ...` works the same if your project uses Bun.
 
@@ -128,6 +130,8 @@ const rows = await sql(
 
 Named parameters use ASCII identifier names (`$user_id`), are numbered by first appearance before PostgreSQL sees the query, and repeated names reuse the same positional parameter. The generated object contract rejects missing, extra, and incorrectly typed properties. Named `$name` and positional `$1` parameters cannot be mixed in one query. Quoted strings, comments, dollar-quoted bodies, and `$` inside PostgreSQL identifiers are left unchanged. Positional parameters remain supported and are still the shortest form for simple queries.
 
+PostgreSQL describes an uncast `LIMIT $limit` or `OFFSET $offset` parameter as `int8`, so its TypeScript type is `bigint`. Use `LIMIT $limit::int` / `OFFSET $offset::int` when the application pagination API uses JavaScript `number` values.
+
 During local development, validate the migration and regenerate query artifacts against a disposable shadow database:
 
 ```bash
@@ -185,6 +189,39 @@ const rows = await sql(`SELECT id FROM users WHERE name = $1`, "alice");
 
 Unknown queries, wrong parameter types, and dynamic strings are compile errors. For genuinely dynamic SQL, use `unsafe`.
 
+### `defineQuery`
+
+Define a query once without closing over a global client, then run the same generated contract through a root or transaction executor:
+
+```ts
+import {
+  defineQuery,
+  sql,
+  type QueryParams,
+  type QueryResult,
+  type QueryRow,
+  type SqlExecutor,
+} from "@onreza/sqlx-js";
+
+export const findUser = defineQuery.optional(
+  "users.findById",
+  `SELECT id, email FROM users WHERE id = $id`,
+);
+
+type FindUserParams = QueryParams<typeof findUser>;
+type FindUserRow = QueryRow<typeof findUser>;
+type FindUserResult = QueryResult<typeof findUser>; // FindUserRow | null
+
+await findUser.run(sql, { id: userId });
+await sql.transaction((tx) => findUser.run(tx, { id: userId }));
+
+async function loadUser(executor: SqlExecutor, params: FindUserParams) {
+  return findUser.run(executor, params);
+}
+```
+
+The optional definition name is included in query observer and inventory metadata. The stable `queryId` is derived from the same lexical SQL fingerprint used by prepare/cache. `defineQuery.one`, `.optional`, and `.execute` mirror the cardinality contracts of the corresponding `sql` helpers.
+
 ### `sql.file(path, ...params)`
 
 Load SQL from an external file. The path is root-relative everywhere: prepare resolves it against `--root`, codegen keeps the exact string literal as the `KnownFileQueries` key, and runtime resolves it against `fileRoot` (default: `process.cwd()`). Absolute paths and paths escaping the root are rejected.
@@ -202,6 +239,20 @@ const admins = await sql.file("queries/top_admins.sql", "admin", 5);
 
 File-backed queries are emitted into a separate `KnownFileQueries` interface. A call from any nested source directory still uses the same project-root-relative literal.
 
+For a compiled or bundled application, emit a TypeScript asset module and pass it to the client:
+
+```bash
+sqlx-js queries --embed src/sqlx-js-files.generated.ts
+```
+
+```ts
+import { sqlxJsEmbeddedSql } from "./sqlx-js-files.generated";
+
+const db = createSqlClient(databaseUrl, { sqlFiles: sqlxJsEmbeddedSql });
+```
+
+Embedded entries take precedence over filesystem reads. The module contains only referenced external SQL files; inline SQL remains in application code.
+
 ### `sql.one(query, ...params)` and `sql.optional(query, ...params)`
 
 Convenience wrappers for single-row queries. `one` throws if the row count is not exactly 1; `optional` returns `null` for 0 rows and throws on more than 1. They keep working under `noUncheckedIndexedAccess: true` without `rows[0]!` patterns.
@@ -255,6 +306,8 @@ await sql(
 
 Generated parameter types require `PgArrayParameter<T>` or `JsonParameter<T>`, so mixing the two representations is a TypeScript error. A PostgreSQL `json[]` / `jsonb[]` composes both wrappers: the outer `sql.array(...)` selects the PostgreSQL array representation and each non-SQL-NULL element uses `sql.json(...)`. `sql.json(null)` represents JSON `null`; a bare `null` remains SQL `NULL` when the database parameter is nullable.
 
+`sql.json()` accepts ordinary structurally JSON-compatible interfaces and preserves their concrete type in `JsonParameter<T>`. It rejects known non-JSON values such as `Date`, `bigint`, functions, and `undefined` array elements. TypeScript is structurally typed, so it cannot identify every user-defined class solely because it was constructed with `new`; runtime JSON semantics still belong to `JSON.stringify`.
+
 Both helpers also work with `unsafe(...)`. `encodePgArrayLiteral(arr)` remains exported for code that explicitly needs a PostgreSQL array literal string.
 
 ### Parameter nullability
@@ -357,6 +410,8 @@ await Promise.all([primary.close(), replica.close()]);
 
 Each generated `sqlx-js-env.d.ts` exports its own `SqlxJsGeneratedRegistry`. Passing it to `createSqlClient<...>()` keeps a scoped client on that project's query contract even when a monorepo TypeScript program includes declarations for several databases. The global `sql` export remains available for the single-client convenience path.
 
+When a workspace package exports database source to other TypeScript programs, bind `SqlxJsGeneratedRegistry` at that package's client boundary. A consumer does not automatically include the database package's ambient `.d.ts`; exporting an unscoped client can therefore collapse its literal parameters to `never` outside the package.
+
 The scanner recognizes clients assigned directly from an imported `createSqlClient(...)` (including aliased and namespace imports), so `client.sql(...)`, its cardinality helpers, file queries, and transactions participate in `prepare` exactly like the global `sql` surface.
 
 `createClient(url, options)` accepts every Postgres.js option plus sqlx-js runtime options:
@@ -371,19 +426,22 @@ setClient(createClient(process.env.DATABASE_URL, {
   // Development-only: re-stat sql.file() files on every call. The default
   // immutable cache avoids synchronous filesystem work in the query hot path.
   reloadSqlFiles: true,
+  // Optional generated map from `sqlx-js queries --embed ...`. When present,
+  // sql.file() needs no runtime filesystem asset for those paths.
+  sqlFiles: sqlxJsEmbeddedSql,
   // Honored for every unsafe call. Set false for PgBouncer transaction mode
   // unless protocol-level prepared statements are configured there.
   prepare: false,
   // Fires after every query/transaction statement, success or failure.
-  onQuery: ({ query, params, durationMs, rowCount, error }) => {
-    if (error) logger.error({ query, error });        // database errors are PgError
-    else if (durationMs > 200) logger.warn({ slow: query, durationMs, rowCount });
+  onQuery: ({ queryId, queryName, query, params, durationMs, rowCount, error }) => {
+    if (error) logger.error({ queryId, queryName, query, error });
+    else if (durationMs > 200) logger.warn({ queryId, queryName, durationMs, rowCount });
   },
   onQueryHookError: (error) => logger.error({ error }, "query observer failed"),
 }));
 ```
 
-The `onQuery` hook is the integration point for metrics, tracing, and slow-query logging — sqlx-js does not log queries itself. It is a non-blocking observer: synchronous throws and asynchronous rejections preserve the database result/error and are passed to `onQueryHookError` when configured. 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.
+The `onQuery` hook is the integration point for metrics, tracing, and slow-query logging — sqlx-js does not log queries itself. `queryId` is the stable prepare/cache fingerprint and is suitable for metric labels; `queryName` is present for named `defineQuery` calls. The hook is a non-blocking observer: synchronous throws and asynchronous rejections preserve the database result/error and are passed to `onQueryHookError` when configured. 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()`
 
@@ -392,19 +450,19 @@ Drops the in-memory cache used by `sql.file(...)`. Files are immutable after the
 ### Typed errors
 
 ```ts
-import { NoRowsError, TooManyRowsError, PgError } from "@onreza/sqlx-js";
+import { NoRowsError, TooManyRowsError, SQLSTATE, isPgError } from "@onreza/sqlx-js";
 
 try {
   const u = await sql.one(`SELECT id FROM users WHERE id = $1`, 99);
 } catch (e) {
   if (e instanceof NoRowsError) return null;
   if (e instanceof TooManyRowsError) console.error("ambiguous query, got", e.actual);
-  if (e instanceof PgError) console.error("pg code:", e.code, "position:", e.position);
+  if (isPgError(e, SQLSTATE.uniqueViolation)) console.error("duplicate:", e.constraint);
   throw e;
 }
 ```
 
-`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.
+`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`; `isPgError(error, code?)` is the concise type guard for SQLSTATE handling. `SQLSTATE` contains the common unique, foreign-key, not-null, check, serialization, and deadlock codes. `PgError` exposes `.code`, `.position`, `.hint`, `.detail`, `.severity`, `.schema`, `.table`, `.column`, `.constraint`, and the original driver error on `.cause`. A zero-row update/delete is not a PostgreSQL error: use `sql.execute(...).rowCount`, `sql.optional`, or `sql.one` for that invariant. Non-database failures are rethrown unchanged.
 
 ### Transactions with options
 
@@ -431,6 +489,7 @@ sqlx-js ci [--root <dir>] [--dts <path>] [--schema <path>] [--json] [--shadow-ur
 sqlx-js db install | check [--root <dir>]
 sqlx-js db plan | apply [--root <dir>] [-- <pgschema args>]
 sqlx-js prepare [--check | --offline | --verify | --watch] [--json | --jsonl] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
+sqlx-js queries [--json] [--embed <path>] [--root <dir>]
 sqlx-js migrate dev [--dts <path>] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | verify [--dts <path>] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | 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 [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
 sqlx-js schema check [--schema <path>] [--shadow-url <url>]
@@ -451,6 +510,7 @@ Regular `prepare` describes queries across a small connection pool (default 8, o
 | `--migrations <dir>`  | Root-relative migrations directory (default: `<root>/migrations`).                   |
 | `--dry-run`           | For `migrate run` / `migrate revert`: validate without applying to the target DB.   |
 | `--json`              | Machine-readable prepare diagnostics, doctor output, migration inspection and dry-runs. |
+| `--embed <path>`      | For `queries`: write a deterministic TypeScript map of referenced external SQL files. |
 | `--jsonl`             | Versioned streaming events for `prepare --watch`.                                     |
 | `--strict-inference`  | Fail prepare/dev/verify when nullability degrades or a generated query type contains `unknown`. |
 | `--force`             | For `migrate archive restore`: allow overwriting existing migration files.           |
@@ -466,7 +526,9 @@ Regular `prepare` describes queries across a small connection pool (default 8, o
 
 Flags that take a value accept both `--flag value` and `--flag=value` forms.
 
-Prepare and doctor JSON use `formatVersion: 1`. Prepare diagnostics include a stable phase plus root-relative file, 1-based line/column, PostgreSQL code/position/hint when available, and the query text. Degraded inference and generated `unknown` types appear as warnings by default; `--strict-inference` promotes them to errors. This is intended for CI annotations and editor integrations; stdout contains one JSON document and human progress is suppressed. `prepare --watch --jsonl` emits one `start`, `diagnostic`, `prepared`, `error`, `watching`, or `stopping` event per line so an editor can consume diagnostics without waiting for the watch process to exit. Fatal `error` events include the same structured `diagnostic` object as CLI preflight failures, preserving the prepare phase and source location when available.
+Prepare and doctor JSON use `formatVersion: 1`. Prepare diagnostics include a stable phase plus root-relative file, 1-based line/column, query ID/name, PostgreSQL code/position/hint when available, and the query text. Degraded inference and generated `unknown` types appear as warnings by default; `--strict-inference` promotes them to errors. This is intended for CI annotations and editor integrations; stdout contains one JSON document and human progress is suppressed. `prepare --watch --jsonl` emits one `start`, `diagnostic`, `prepared`, `error`, `watching`, or `stopping` event per line so an editor can consume diagnostics without waiting for the watch process to exit. Fatal `error` events include the same structured `diagnostic` object as CLI preflight failures, preserving the prepare phase and source location when available.
+
+`queries --json` is database-free and read-only. It emits `formatVersion: 1` inventory entries with `queryId`, optional definition names, cardinalities, root-relative call sites, SQL file paths, and `current`/`stale`/`missing` cache status, plus orphaned cache IDs. Config, scan, cache, and embed failures use versioned structured diagnostics with source location when available. Adding `--embed` writes the external-SQL module only after a successful scan.
 
 `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`, `options` (PostgreSQL startup options such as `-c search_path=app,public`), `connect_timeout` (seconds), and `statement_timeout` (milliseconds). Unqualified relations are resolved using the prepare session's real `search_path`; they are not assumed to live in `public`.
 
@@ -619,6 +681,14 @@ export default defineConfig({
     "posts.meta":         "SqlxJsJson.PostMeta",
     "posts.attachments":  "SqlxJsJson.Attachment",
   },
+  // Explicit application-owned assertions for direct scalar columns only.
+  columnTypes: {
+    "analytics_event.action": "AnalyticsAction",
+  },
+  functionCatalog: {
+    // Extension-owned functions are excluded by default.
+    includeExtensionOwned: false,
+  },
 });
 ```
 
@@ -644,7 +714,17 @@ declare global {
 export {};
 ```
 
-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` inside `JsonParameter` for parameters, both exported by `@onreza/sqlx-js`. Pass JSON parameters through `sql.json(value)`: 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. A bare top-level `null` remains SQL `NULL` and is allowed only when the mapped database parameter is nullable; use `sql.json(null)` for JSON `null`.
+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 `JsonParameter<unknown>` for parameters: the existential parameter type accepts any wrapper already proven JSON-safe by `sql.json(value)` without requiring domain interfaces to declare a string index signature. 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. A bare top-level `null` remains SQL `NULL` and is allowed only when the mapped database parameter is nullable; use `sql.json(null)` for JSON `null`.
+
+### Direct scalar `columnTypes`
+
+`columnTypes` is an explicit application-owned type assertion for a direct scalar table column. It affects result fields that PostgreSQL attributes to that exact column and parameters that sqlx-js maps back to it through `INSERT`, `UPDATE`, `WHERE`, or `JOIN` analysis. It never changes arbitrary expressions such as `upper(action)`, and it does not apply to PostgreSQL/JSON array columns. Use a schema-qualified key when table names can collide. Mapping the same logical column through both `jsonbTypes` and `columnTypes` is rejected.
+
+This assertion does not validate stored values at runtime. Prefer a PostgreSQL enum/domain when the database truly owns a closed value set; use `columnTypes` when the database deliberately stores a broader scalar such as `text` and the application accepts responsibility for the narrower TypeScript contract.
+
+### Function catalog scope
+
+Application-owned functions and procedures from non-system schemas are generated into `KnownFunctions`. Objects owned by installed extensions are excluded through `pg_depend`, preventing extension internals from dominating committed artifacts. Set `functionCatalog.includeExtensionOwned: true` only when those approximate signatures are needed, or set `functionCatalog: false` to disable catalog generation entirely.
 
 ### Extension types and `customTypes`
 
@@ -726,6 +806,8 @@ The `migrate verify` step needs `DATABASE_URL` credentials that can either creat
 
 The managed pgschema binary is installed under `node_modules/.cache/sqlx-js/pgschema/`, not `.sqlx-js/`, so it is not part of the committed offline cache.
 
+Generated declarations and cache files should be excluded from formatters and linters. They remain included in `tsconfig.json` for type checking, but rules such as Biome's empty-interface or confusing-void checks are not meaningful for declaration-merging points and PostgreSQL procedure contracts.
+
 ## Contributing
 
 The project uses [conventional commits](https://www.conventionalcommits.org/), validated locally by `cocogitto` through `lefthook` hooks. Install both before contributing:
@@ -751,7 +833,7 @@ Releases are automated via `release-please`: pushes to `main` accumulate into a
 - 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`, `options`, `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.
-- Runtime `sql.file(path)` resolves against `fileRoot` while prepare resolves against `--root`. They are both root-relative, but applications started outside the project root must set `fileRoot` explicitly.
+- Runtime `sql.file(path)` resolves against `fileRoot` while prepare resolves against `--root`. They are both root-relative, but applications started outside the project root must set `fileRoot` explicitly or provide the generated `sqlFiles` map.
 
 See [ROADMAP.md](./ROADMAP.md) for what's planned.
 
@@ -759,7 +841,7 @@ See [ROADMAP.md](./ROADMAP.md) for what's planned.
 
 ### Cache, codegen, and parameter contract changes (pre-1.0)
 
-Generated cache now includes `.sqlx-js/cache-manifest.json` with an explicit cache format, generator revision, and hash of `jsonbTypes` / `customTypes`. Cache without this manifest is rejected. Delete `.sqlx-js/` and re-run `sqlx-js prepare` against your database — there is no data loss because the cache is generated.
+Generated cache includes `.sqlx-js/cache-manifest.json` with an explicit cache format, generator revision, and hash of type/function-catalog settings. Cache without this manifest is rejected. Delete `.sqlx-js/` and re-run `sqlx-js prepare` against your database — there is no data loss because the cache is generated.
 
 Generated JSON and PostgreSQL array parameters now require `sql.json(...)` and `sql.array(...)`. This removes the ambiguous runtime guess where a JavaScript array could mean either a PostgreSQL array or a JSON array. Replace raw array JSON params with `sql.json(value)` and PostgreSQL arrays with `sql.array(value)` before regenerating declarations.
 
@@ -767,6 +849,8 @@ CI (`prepare --check`) will also fail loudly until the cache is regenerated; thi
 
 Generator revision 4 changes the declaration layout so it exports `SqlxJsGeneratedRegistry` for scoped clients while continuing to augment the global `KnownQueries` convenience API. Re-run live `sqlx-js prepare` after upgrading. `prepare --check` is now strictly read-only; use `prepare --offline` when deliberate cache-to-declaration regeneration is required.
 
+Generator revision 6 adds `columnTypes` and function-catalog scope to the generated contract. Extension-owned functions are no longer emitted by default. Re-run live `sqlx-js prepare`; set `functionCatalog.includeExtensionOwned: true` only if application code intentionally indexes those signatures.
+
 Runtime observers and SQL-file caching are also stricter production boundaries. An exception from `onQuery` no longer replaces a successful query result; handle it through `onQueryHookError`. `sql.file()` no longer performs an mtime check on every call—use `reloadSqlFiles: true` during development or call `clearSqlFileCache()` explicitly after changing a file.
 
 ## License

package/ROADMAP.md

@@ -9,7 +9,7 @@ Items already shipped live in the [README](./README.md) feature list; this file
 | pgschema integration hardening | 6 | Managed install/check/plan/apply now has a real pinned-binary PostgreSQL E2E in CI. Continue with schema snapshot handoff and migration guidance for projects that outgrow built-in migrations. |
 | Separate runtime package | Deferred | The audited root import already excludes compile-time modules. Making TypeScript an optional peer reduced a clean production install from about 33 MB to 2.4 MB; a second public package and release boundary is not justified for the remaining analyzer dependency unless production consumers demonstrate measurable pressure. |
 | Built-in migration lifecycle maintenance | 5 | Keep `migrate run/dev/verify/revert/squash/archive` stable for simple projects and application startup, but avoid expanding it into a full PostgreSQL schema-as-code system. |
-| Prisma migration assistant | 7 | Import Prisma Migrate SQL history and Prisma TypedSQL/raw SQL into `sqlx-js`; classify Prisma Client CRUD/nested-write sites as assisted/manual instead of promising a fully automatic ORM rewrite. |
+| Prisma migration assistant | 7 | Import Prisma Migrate SQL history and Prisma TypedSQL/raw SQL into `sqlx-js`; classify Prisma Client CRUD/nested-write sites as assisted/manual instead of promising a fully automatic ORM rewrite. The shipped `queries --json` inventory covers sqlx-js definitions/call sites after conversion, not Prisma reference-graph discovery. |
 | Self-join precision (unqualified ColumnRef) | 4 | `SELECT name FROM users u1 JOIN users u2 ON ...` with unqualified `name` can't be attributed to a specific alias. PG would reject ambiguous unqualified refs anyway, but explicit aliasing currently has no narrowing benefit in self-joins. |
 | Tagged-template literal API (`` sql`SELECT ${x}` ``) | 8 | Restoring sqlx's inline-SQL aesthetic requires either a TS compiler plugin (`ts-patch`) or a Bun preload-time AST rewriter. TS itself hardcodes the first tag argument as `TemplateStringsArray` and refuses to narrow to literal tuples. Significant effort, large UX win. |
 | Editor integration / LSP | Deferred | Keep the versioned batch JSON, incremental `prepare --watch --jsonl`, and `sqlx-js-diagnostics` transport stable, but do not build or maintain a VS Code extension or full LSP until real consumer demand justifies the separate editor clients and release lifecycle. |

package/dist/bin/sqlx-js.js

@@ -26,6 +26,7 @@ usage:
   sqlx-js db install | check [--root <dir>]
   sqlx-js db plan | apply [--root <dir>] [-- <pgschema args>]
   sqlx-js prepare [--check | --offline | --verify | --watch] [--json | --jsonl] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
+  sqlx-js queries [--json] [--embed <path>] [--root <dir>]
   sqlx-js migrate dev [--dts <path>] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | verify [--dts <path>] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | 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 [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
   sqlx-js schema check [--schema <path>] [--shadow-url <url>]
@@ -49,6 +50,7 @@ flags:
   --dry-run                validate and print migrate run/revert plan without applying migrations
   --json                   machine-readable output for prepare and migration inspection/dry-run commands
   --jsonl                  streaming machine-readable output for prepare --watch
+  --embed <path>           emit a deterministic TypeScript map of referenced SQL files
   --strict-inference       fail when query inference degrades or emits unknown types
   --force                  allow archive restore to overwrite existing migration files
   --lock-timeout <ms>      advisory-lock acquisition timeout for migrate run/revert/dev/verify/squash
@@ -66,6 +68,7 @@ flags:
     ci: `usage: sqlx-js ci [--root <dir>] [--dts <path>] [--schema <path>] [--json] [--shadow-url <url>] [--shadow-admin-url <url>] [--migrations <dir>]`,
     db: `usage: sqlx-js db install | check [--root <dir>] | plan | apply [--root <dir>] [-- <pgschema args>]`,
     prepare: `usage: sqlx-js prepare [--check | --offline | --verify | --watch] [--json | --jsonl] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]`,
+    queries: `usage: sqlx-js queries [--json] [--embed <path>] [--root <dir>]`,
     migrate: `usage: sqlx-js migrate dev [--dts <path>] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | verify [--dts <path>] [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | 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]`,
     schema: `usage: sqlx-js schema dump [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>] | check [--schema <path>] [--shadow-url <url>]`,
 };
@@ -86,7 +89,7 @@ const passthroughIndex = rawArgv.indexOf("--");
 const cliArgv = passthroughIndex >= 0 ? rawArgv.slice(0, passthroughIndex) : rawArgv;
 const passthroughArgs = passthroughIndex >= 0 ? rawArgv.slice(passthroughIndex + 1) : [];
 const cmd = cliArgv[0];
-const scopes = new Set(["init", "doctor", "ci", "db", "prepare", "migrate", "schema"]);
+const scopes = new Set(["init", "doctor", "ci", "db", "prepare", "queries", "migrate", "schema"]);
 if (cmd === "--version" || cmd === "-v") {
     console.log(VERSION);
     process.exit(0);
@@ -137,6 +140,8 @@ function optionsFor(command, subcommand) {
             "strict-inference": { type: "boolean" },
         };
     }
+    if (command === "queries")
+        return { ...ROOT_OPTIONS, json: { type: "boolean" }, embed: { type: "string" } };
     if (command === "schema") {
         const common = {
             ...ROOT_OPTIONS,
@@ -228,7 +233,7 @@ function requirePositionals(min, max, label) {
     }
 }
 function validateInvocation() {
-    if (cmd === "init" || cmd === "doctor" || cmd === "ci" || cmd === "prepare") {
+    if (cmd === "init" || cmd === "doctor" || cmd === "ci" || cmd === "prepare" || cmd === "queries") {
         requirePositionals(0, 0, cmd);
         return;
     }
@@ -302,6 +307,7 @@ if (cmd !== "doctor") {
 const needsTypeScript = cmd === "doctor" ||
     cmd === "ci" ||
     cmd === "prepare" ||
+    cmd === "queries" ||
     (cmd === "migrate" && (positionals[0] === "dev" || positionals[0] === "verify"));
 if (needsTypeScript) {
     try {
@@ -531,6 +537,37 @@ else if (cmd === "prepare") {
         }
     }
 }
+else if (cmd === "queries") {
+    const { QueriesError, runQueries } = await import("../src/commands/queries.js");
+    const embed = arg("--embed");
+    try {
+        await runQueries({
+            root,
+            cacheDir,
+            json: flag("--json"),
+            embedPath: embed ? resolve(root, embed) : undefined,
+        });
+    }
+    catch (error) {
+        if (flag("--json")) {
+            const diagnostic = error instanceof QueriesError
+                ? {
+                    severity: "error",
+                    phase: error.phase,
+                    message: error.message,
+                    ...(error.file === undefined ? {} : { file: error.file }),
+                    ...(error.line === undefined ? {} : { line: error.line }),
+                    ...(error.column === undefined ? {} : { column: error.column }),
+                }
+                : { severity: "error", phase: "scan", message: error.message };
+            console.log(JSON.stringify({ formatVersion: 1, ok: false, diagnostics: [diagnostic] }, null, 2));
+        }
+        else {
+            console.error(error.message);
+        }
+        process.exit(2);
+    }
+}
 else if (cmd === "schema") {
     const { runSchemaCheck, runSchemaDump } = await import("../src/commands/schema.js");
     const sub = positionals[0];

package/dist/src/cache.d.ts

@@ -1,6 +1,9 @@
 export declare const CACHE_FORMAT_VERSION = 3;
-export declare const GENERATOR_REVISION = 5;
+export declare const GENERATOR_REVISION = 6;
 export declare const CACHE_MANIFEST_FILE = "cache-manifest.json";
+export declare class CacheManifestStaleError extends Error {
+    constructor(path: string);
+}
 export type CacheManifest = {
     cacheFormat: typeof CACHE_FORMAT_VERSION;
     generatorRevision: typeof GENERATOR_REVISION;

package/dist/src/cache.js

@@ -1,74 +1,23 @@
-import { createHash, randomBytes } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import { isBuiltinOid } from "./pg/oids.js";
-import { isEscapeStringPrefix, isIdentifierContinuation, readBlockComment, readDollarQuoted, readLineComment, readQuotedIdentifier, readSingleQuoted, } from "./sql-lex.js";
+import { queryId } from "./query-id.js";
 import { rewriteNamedParameters } from "./sql-params.js";
 export const CACHE_FORMAT_VERSION = 3;
-export const GENERATOR_REVISION = 5;
+export const GENERATOR_REVISION = 6;
 export const CACHE_MANIFEST_FILE = "cache-manifest.json";
+export class CacheManifestStaleError extends Error {
+    constructor(path) {
+        super(`sqlx-js: cache manifest is stale: ${path}. Run \`sqlx-js prepare\`.`);
+        this.name = "CacheManifestStaleError";
+    }
+}
 export function portableCacheOid(oid) {
     return isBuiltinOid(oid) ? oid : 0;
 }
 export function fingerprint(query) {
-    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 = i === 0 || !isIdentifierContinuation(query[i - 1]) ? readDollarQuoted(query, i) : null;
-            if (next !== null) {
-                emit(query.slice(i, next));
-                i = next;
-                continue;
-            }
-        }
-        emit(ch);
-        i++;
-    }
-    return out;
+    return queryId(query);
 }
 export function effectiveNullable(c) {
     if (c.override === "non-null")
@@ -249,7 +198,7 @@ export function readCacheManifest(cacheDir) {
     if (value.cacheFormat !== CACHE_FORMAT_VERSION ||
         value.generatorRevision !== GENERATOR_REVISION ||
         typeof value.configHash !== "string") {
-        throw new Error(`sqlx-js: cache manifest is stale: ${path}. Run \`sqlx-js prepare\`.`);
+        throw new CacheManifestStaleError(path);
     }
     return value;
 }
@@ -259,7 +208,7 @@ export function assertCacheManifest(cacheDir, configHash) {
         throw new Error(`sqlx-js: cache manifest is missing. Run \`sqlx-js prepare\` to regenerate the cache.`);
     }
     if (manifest.configHash !== configHash) {
-        throw new Error("sqlx-js: cache was generated with a different jsonbTypes/customTypes config. Run `sqlx-js prepare`.");
+        throw new Error("sqlx-js: cache was generated with a different jsonbTypes/customTypes config or other type/function catalog settings. Run `sqlx-js prepare`.");
     }
     return manifest;
 }

package/dist/src/commands/init.js

@@ -6,9 +6,14 @@ export default defineConfig({
   // Map jsonb columns/params to TypeScript types declared in a .d.ts, e.g.
   //   "users.settings": "SqlxJsJson.UserSettings",
   jsonbTypes: {},
+  // Assert narrower TypeScript types for direct scalar columns.
+  columnTypes: {},
   // Map PostgreSQL type names to TypeScript types, e.g.
   //   geometry: "GeoJSON.Geometry",
   customTypes: {},
+  // Extension-owned functions are excluded by default. Set false to disable
+  // the generated function catalog entirely.
+  functionCatalog: {},
 });
 `;
 const PGSCHEMA_CONFIG_TEMPLATE = `import { defineConfig } from "@onreza/sqlx-js";
@@ -20,7 +25,9 @@ export default defineConfig({
     schemas: ["public"],
   },
   jsonbTypes: {},
+  columnTypes: {},
   customTypes: {},
+  functionCatalog: {},
 });
 `;
 const ENV_TEMPLATE = `# Connection string used by sqlx-js prepare/migrate and the runtime.
@@ -144,6 +151,7 @@ export function runInit(opts) {
             "sqlx:offline": "sqlx-js prepare --offline",
             "sqlx:verify": "sqlx-js prepare --verify --strict-inference",
             "sqlx:ci": "sqlx-js ci",
+            "sqlx:queries": "sqlx-js queries --json",
         };
         let changed = false;
         for (const [name, command] of Object.entries(defaults)) {

package/dist/src/commands/prepare.d.ts

@@ -34,6 +34,8 @@ export type PrepareDiagnostic = {
     line?: number;
     column?: number;
     query?: string;
+    queryId?: string;
+    queryName?: string;
     code?: string;
     position?: number;
     hint?: string;