@onreza/sqlx-js 0.6.0 → 0.7.0

package/README.md

@@ -43,7 +43,7 @@ const rows = await sql(
 - **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.
-- **Watch mode**: debounced re-prepare with a warm `PgClient` + `SchemaCache` on source/SQL changes and scanner/config graph updates.
+- **Incremental watch mode**: debounced re-prepare with a warm `PgClient` + `SchemaCache`; source/SQL edits only rescan affected files and re-describe changed fingerprints, while config/tsconfig/schema changes trigger a full rebuild.
 - **Cache pruning** removes orphaned entries automatically (toggleable with `--no-prune`).
 - **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.
@@ -324,6 +324,25 @@ import { createClient, setClient } from "@onreza/sqlx-js";
 setClient(createClient(process.env.DATABASE_URL));
 ```
 
+For dependency injection, read replicas, tests, or several independent pools in one process, create a scoped runtime instead of replacing the global client:
+
+```ts
+import { createSqlClient } from "@onreza/sqlx-js";
+import type { SqlxJsGeneratedRegistry } from "./sqlx-js-env";
+
+const primary = createSqlClient<SqlxJsGeneratedRegistry>(process.env.DATABASE_URL);
+const replica = createSqlClient<SqlxJsGeneratedRegistry>(process.env.REPLICA_DATABASE_URL);
+
+await primary.sql(`INSERT INTO audit_log (message) VALUES ($1)`, "created");
+const rows = await replica.sql(`SELECT id, message FROM audit_log ORDER BY id DESC`);
+
+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.
+
+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:
 
 ```ts
@@ -333,6 +352,9 @@ setClient(createClient(process.env.DATABASE_URL, {
   statementTimeoutMs: 5000,
   // Base directory for root-relative sql.file(...) calls.
   fileRoot: import.meta.dirname,
+  // 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,
   // Honored for every unsafe call. Set false for PgBouncer transaction mode
   // unless protocol-level prepared statements are configured there.
   prepare: false,
@@ -341,14 +363,15 @@ setClient(createClient(process.env.DATABASE_URL, {
     if (error) logger.error({ query, error });        // database errors are PgError
     else if (durationMs > 200) logger.warn({ slow: query, 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. 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. 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.
 
 ### `clearSqlFileCache()`
 
-Drops the in-memory cache used by `sql.file(...)`. The cache invalidates automatically on file mtime change, so this is rarely needed manually.
+Drops the in-memory cache used by `sql.file(...)`. Files are immutable after their first read by default, avoiding a synchronous `stat` call for every query. Call this after a development-time file change or set `reloadSqlFiles: true` on the client to restore mtime-based reloading.
 
 ### Typed errors
 
@@ -390,26 +413,28 @@ sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]
 sqlx-js doctor [--root <dir>] [--dts <path>] [--json]
 sqlx-js db install | check [--root <dir>]
 sqlx-js db plan | apply [--root <dir>] [-- <pgschema args>]
-sqlx-js prepare [--check | --verify | --watch] [--json] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
+sqlx-js prepare [--check | --offline | --verify | --watch] [--json | --jsonl] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
 sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | verify [--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>]
 sqlx-js --version | --help
 ```
 
-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.
+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, rescans only affected source files, and reuses cached metadata for unchanged fingerprints. Config, tsconfig, and applied shadow-migration changes invalidate the incremental state and perform a full prepare.
 
 | Flag                  | Meaning                                                                              |
 |-----------------------|--------------------------------------------------------------------------------------|
-| `--check`             | Offline: verify every scanned query is present in cache, no database required.       |
+| `--check`             | Read-only offline verification of the active query cache, function catalog, and generated declaration. |
+| `--offline`           | Regenerate `sqlx-js-env.d.ts` from committed cache without a database.                |
 | `--verify`            | Prepare against the live/shadow schema and compare generated artifacts without writing. |
 | `--watch`             | Persistent connection, re-prepare on file change.                                    |
 | `--root <dir>`        | Source/cache/migrations root (default: cwd).                                         |
 | `--dts <path>`        | Root-relative declarations output (default: `<root>/sqlx-js-env.d.ts`).             |
-| `--no-prune`          | Keep orphaned cache entries instead of removing them.                                |
+| `--no-prune`          | Keep orphaned cache entries; they do not invalidate a later `--check`.                |
 | `--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. |
+| `--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.           |
 | `--lock-timeout <ms>` | Advisory-lock acquisition timeout for `migrate run` / `revert` / `dev` / `verify` / `squash`. |
@@ -424,9 +449,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 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.
 
-`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).
+`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`.
 
 ### Development and deployment flows
 
@@ -664,7 +689,7 @@ Commit the generated `sqlx-js-env.d.ts` and the `.sqlx-js/` cache directory to y
 - run: sqlx-js db install
 - run: sqlx-js db plan -- --output-json plan.json
 - run: sqlx-js prepare --verify --strict-inference # live/shadow comparison with complete inference
-- run: sqlx-js prepare --check   # offline cache/version/config consistency
+- run: sqlx-js prepare --check   # read-only offline cache/declaration consistency
 - run: sqlx-js doctor --json     # runtime/config/DB/cache/tsconfig preflight
 - run: sqlx-js schema check      # fails if the committed schema snapshot is stale
 - run: tsc --noEmit               # fails if types are stale
@@ -672,7 +697,7 @@ Commit the generated `sqlx-js-env.d.ts` and the `.sqlx-js/` cache directory to y
 - run: bun run build              # emits publishable JS + declarations under dist/
 ```
 
-The `migrate verify` step needs `DATABASE_URL` credentials that can either create a temporary database or use `--shadow-admin-url` / `--shadow-url`. It does not write `.sqlx-js/` or `sqlx-js-env.d.ts`. For pgschema projects, `sqlx-js db plan` checks the desired `schema.sql` against the target database and leaves application query typing to `prepare`. The `prepare --check` step then runs without a database; your committed offline cache is the source of truth. Add `prepare --verify` when CI has a canonical database/shadow schema and must prove byte-for-byte artifact freshness. `schema check` intentionally uses a live database because it verifies the committed schema contract against PostgreSQL.
+The `migrate verify` step needs `DATABASE_URL` credentials that can either create a temporary database or use `--shadow-admin-url` / `--shadow-url`. It does not write `.sqlx-js/` or `sqlx-js-env.d.ts`. For pgschema projects, `sqlx-js db plan` checks the desired `schema.sql` against the target database and leaves application query typing to `prepare`. `prepare --check` is read-only and fails when either the committed cache or declaration is stale. Use `prepare --offline` when a developer intentionally needs to restore the declaration from a valid committed cache. Add `prepare --verify` when CI has a canonical database/shadow schema and must prove byte-for-byte artifact freshness. `schema check` intentionally uses a live database because it verifies the committed schema contract against PostgreSQL.
 
 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.
 
@@ -699,7 +724,7 @@ Releases are automated via `release-please`: pushes to `main` accumulate into a
 - 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.
 - Result columns must have unique names because Postgres.js returns object rows. Alias join projections such as `users.id AS user_id, posts.id AS post_id`; `prepare` rejects duplicate output names before generating declarations.
 - 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`).
+- 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.
 
@@ -707,7 +732,7 @@ See [ROADMAP.md](./ROADMAP.md) for what's planned.
 
 ## Upgrading
 
-### Cache and parameter contract change (pre-1.0)
+### 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.
 
@@ -715,6 +740,10 @@ Generated JSON and PostgreSQL array parameters now require `sql.json(...)` and `
 
 CI (`prepare --check`) will also fail loudly until the cache is regenerated; this is intentional so a stale schema can't silently emit incorrect `.d.ts`.
 
+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.
+
+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
 
 MIT.

package/ROADMAP.md

@@ -6,12 +6,12 @@ Items already shipped live in the [README](./README.md) feature list; this file
 
 | Feature | ROI | Notes |
 |---------|-----|-------|
-| pgschema integration hardening | 8 | Basic `init --schema-provider pgschema` plus managed `sqlx-js db install/check/plan/apply` exists. Continue with better docs, CI examples, schema snapshot handoff, and migration guidance for projects that outgrow built-in migrations. |
+| 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. |
 | 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. |
 | 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. |
-| LSP server | 6 | Realtime diagnostics, hover with column types, autocomplete on schema names. Versioned `prepare --json` plus `sqlx-js-diagnostics` already cover GitHub annotations and editor problem matchers; a full server still needs separate VS Code / Neovim clients. |
+| LSP server | 5 | Realtime hover and schema autocomplete. Versioned batch JSON, incremental `prepare --watch --jsonl`, and `sqlx-js-diagnostics` already provide the transport for editor problems; a full server still needs separate VS Code / Neovim clients. |
 | Schema-aware `jsonb` runtime validation | 5 | Optional opt-in: pass a Zod / Valibot / ArkType schema, validate rows on read. Currently we are compile-time-only by design. |
 | MySQL backend | 5 | Some runtime clients support it, but MySQL has no `Describe Statement` equivalent. Would need a real SQL parser pass + `INFORMATION_SCHEMA` introspection. |
 | SQLite backend | 4 | SQLite's column types are dynamic. Would require running `EXPLAIN` and a heuristic mapper, or schema-driven inference per-statement. |

package/dist/bin/sqlx-js.js

@@ -24,7 +24,7 @@ usage:
   sqlx-js doctor [--root <dir>] [--dts <path>] [--json]
   sqlx-js db install | check [--root <dir>]
   sqlx-js db plan | apply [--root <dir>] [-- <pgschema args>]
-  sqlx-js prepare [--check | --verify | --watch] [--json] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
+  sqlx-js prepare [--check | --offline | --verify | --watch] [--json | --jsonl] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
   sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | verify [--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>]
@@ -32,20 +32,22 @@ usage:
   sqlx-js-diagnostics github|unix < prepare-diagnostics.json
 
 env:
-  DATABASE_URL=postgres://...  (supports sslmode, cert paths, application_name, connect_timeout, statement_timeout)
+  DATABASE_URL=postgres://...  (supports sslmode, cert paths, application_name, options, 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: verify scanned queries exist in cache, no DB
+  --check                  read-only offline verification of cache and declarations
+  --offline                regenerate declarations from committed cache, no DB
   --verify                 prepare against DB/shadow and compare committed generated artifacts
   --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 prepare and migration inspection/dry-run commands
+  --jsonl                  streaming machine-readable output for prepare --watch
   --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
@@ -61,7 +63,7 @@ flags:
     init: `usage: sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]`,
     doctor: `usage: sqlx-js doctor [--root <dir>] [--dts <path>] [--json]`,
     db: `usage: sqlx-js db install | check [--root <dir>] | plan | apply [--root <dir>] [-- <pgschema args>]`,
-    prepare: `usage: sqlx-js prepare [--check | --verify | --watch] [--json] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]`,
+    prepare: `usage: sqlx-js prepare [--check | --offline | --verify | --watch] [--json | --jsonl] [--strict-inference] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]`,
     migrate: `usage: sqlx-js migrate dev [--shadow-admin-url <url> | --shadow-url <url>] [--lock-timeout <ms>] [--strict-inference] | verify [--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>]`,
 };
@@ -112,9 +114,11 @@ function optionsFor(command, subcommand) {
             ...ROOT_OPTIONS,
             dts: { type: "string" },
             check: { type: "boolean" },
+            offline: { type: "boolean" },
             verify: { type: "boolean" },
             watch: { type: "boolean" },
             json: { type: "boolean" },
+            jsonl: { type: "boolean" },
             "no-prune": { type: "boolean" },
             "shadow-url": { type: "string" },
             migrations: { type: "string" },
@@ -273,7 +277,7 @@ let envError;
 const needsEnvironment = cmd === "doctor" ||
     cmd === "schema" ||
     (cmd === "db" && (positionals[0] === "plan" || positionals[0] === "apply")) ||
-    (cmd === "prepare" && !flag("--check")) ||
+    (cmd === "prepare" && !flag("--check") && !flag("--offline")) ||
     (cmd === "migrate" && !["add", "check", "archive"].includes(positionals[0]));
 if (needsEnvironment) {
     try {
@@ -343,12 +347,22 @@ else if (cmd === "db") {
 else if (cmd === "prepare") {
     const { PrepareFatalError, runPrepare } = await import("../src/commands/prepare.js");
     const prepareCheck = flag("--check");
+    const prepareOffline = flag("--offline");
     const prepareVerify = flag("--verify");
     const prepareWatch = flag("--watch");
     const prepareJson = flag("--json");
-    const prepareMode = prepareVerify ? "verify" : prepareCheck ? "check" : "prepare";
+    const prepareJsonl = flag("--jsonl");
+    const prepareMode = prepareVerify ? "verify" : prepareCheck ? "check" : prepareOffline ? "offline" : "prepare";
     const failPrepare = (message, phase, exitCode = 2, location = {}) => {
-        if (prepareJson) {
+        if (prepareJsonl) {
+            console.log(JSON.stringify({
+                formatVersion: 1,
+                event: "error",
+                timestamp: new Date().toISOString(),
+                diagnostic: { severity: "error", phase, message, ...location },
+            }));
+        }
+        else if (prepareJson) {
             console.log(JSON.stringify({
                 formatVersion: 1,
                 ok: false,
@@ -366,22 +380,28 @@ else if (cmd === "prepare") {
         }
         process.exit(exitCode);
     };
-    if ([prepareCheck, prepareVerify, prepareWatch].filter(Boolean).length > 1) {
-        failPrepare("--check, --verify, and --watch are mutually exclusive", "config");
+    if ([prepareCheck, prepareOffline, prepareVerify, prepareWatch].filter(Boolean).length > 1) {
+        failPrepare("--check, --offline, --verify, and --watch are mutually exclusive", "config");
     }
-    if (prepareCheck && shadowUrlArg) {
-        failPrepare("--shadow-url cannot be used with prepare --check; use live prepare or schema check --shadow-url", "config");
+    if ((prepareCheck || prepareOffline) && shadowUrlArg) {
+        failPrepare("--shadow-url cannot be used with offline prepare modes; use live prepare or schema check --shadow-url", "config");
     }
     if (prepareWatch && prepareJson) {
         failPrepare("--watch and --json are mutually exclusive", "config");
     }
-    if ((prepareCheck || prepareVerify) && flag("--no-prune")) {
-        failPrepare("--no-prune is only supported by prepare and prepare --watch", "config");
+    if (prepareJson && prepareJsonl) {
+        failPrepare("--json and --jsonl are mutually exclusive", "config");
+    }
+    if (prepareJsonl && !prepareWatch) {
+        failPrepare("--jsonl is only supported by prepare --watch", "config");
+    }
+    if ((prepareCheck || prepareOffline || prepareVerify) && flag("--no-prune")) {
+        failPrepare("--no-prune is only supported by live prepare and prepare --watch", "config");
     }
-    const prepareShadowUrl = prepareCheck ? undefined : shadowUrl;
+    const prepareShadowUrl = prepareCheck || prepareOffline ? undefined : shadowUrl;
     const prepareDatabaseUrl = prepareShadowUrl ?? databaseUrl;
-    if (!prepareCheck && !prepareDatabaseUrl) {
-        failPrepare("DATABASE_URL is required for prepare (use --check for offline)", "connect");
+    if (!prepareCheck && !prepareOffline && !prepareDatabaseUrl) {
+        failPrepare("DATABASE_URL is required for prepare (use --check or --offline without a database)", "connect");
     }
     const opts = {
         root,
@@ -389,6 +409,7 @@ else if (cmd === "prepare") {
         cacheDir,
         dtsPath,
         check: prepareCheck,
+        offline: prepareOffline,
         verify: prepareVerify,
         json: prepareJson,
         prune: !flag("--no-prune"),
@@ -401,6 +422,7 @@ else if (cmd === "prepare") {
         const { runWatch } = await import("../src/commands/watch.js");
         await runWatch({
             ...opts,
+            jsonl: prepareJsonl,
             ...(prepareShadowUrl
                 ? {
                     beforePrepare: async () => {

package/dist/src/cache.d.ts

@@ -1,5 +1,5 @@
 export declare const CACHE_FORMAT_VERSION = 2;
-export declare const GENERATOR_REVISION = 3;
+export declare const GENERATOR_REVISION = 4;
 export declare const CACHE_MANIFEST_FILE = "cache-manifest.json";
 export type CacheManifest = {
     cacheFormat: typeof CACHE_FORMAT_VERSION;

package/dist/src/cache.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlink
 import { join } from "node:path";
 import { isBuiltinOid } from "./pg/oids.js";
 export const CACHE_FORMAT_VERSION = 2;
-export const GENERATOR_REVISION = 3;
+export const GENERATOR_REVISION = 4;
 export const CACHE_MANIFEST_FILE = "cache-manifest.json";
 export function portableCacheOid(oid) {
     return isBuiltinOid(oid) ? oid : 0;

package/dist/src/codegen.js

@@ -23,7 +23,9 @@ export function emitDts(outPath, entries, functions = []) {
     lines.push("// AUTO-GENERATED by sqlx-js. Do not edit.");
     lines.push("// Run `sqlx-js prepare` to regenerate.");
     lines.push("");
-    emitModule(lines, "@onreza/sqlx-js", entries, functions);
+    emitRegistry(lines, entries, functions);
+    lines.push("");
+    emitModuleAugmentation(lines, "@onreza/sqlx-js");
     lines.push("");
     lines.push("export {};");
     const tmp = `${outPath}.tmp-${randomBytes(4).toString("hex")}`;
@@ -39,9 +41,8 @@ export function emitDts(outPath, entries, functions = []) {
         throw err;
     }
 }
-function emitModule(lines, moduleName, entries, functions) {
-    lines.push(`declare module ${JSON.stringify(moduleName)} {`);
-    lines.push("  interface KnownQueries {");
+function emitRegistry(lines, entries, functions) {
+    lines.push("export interface SqlxJsGeneratedQueries {");
     const inlineSeen = new Set();
     const inlinePairs = [];
     for (const e of entries) {
@@ -58,12 +59,12 @@ function emitModule(lines, moduleName, entries, functions) {
         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(`  /** 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("}");
     lines.push("");
-    lines.push("  interface KnownFileQueries {");
+    lines.push("export interface SqlxJsGeneratedFileQueries {");
     const filePairs = [];
     for (const e of entries) {
         if (!e.filePaths || e.filePaths.length === 0)
@@ -78,21 +79,33 @@ function emitModule(lines, moduleName, entries, functions) {
         filePathsSeen.add(path);
         const { params, row } = entrySignature(entry);
         if (entry.degraded)
-            lines.push(`    /** Nullability inference degraded: ${entry.degraded.reason}. */`);
-        lines.push(`    ${JSON.stringify(path)}: { params: ${params}; row: ${row} };`);
+            lines.push(`  /** Nullability inference degraded: ${entry.degraded.reason}. */`);
+        lines.push(`  ${JSON.stringify(path)}: { params: ${params}; row: ${row} };`);
     }
-    lines.push("  }");
+    lines.push("}");
     lines.push("");
-    lines.push("  interface KnownFunctions {");
+    lines.push("export interface SqlxJsGeneratedFunctions {");
     const functionSeen = new Set();
     for (const fn of functions.slice().sort((a, b) => a.signature.localeCompare(b.signature))) {
         if (functionSeen.has(fn.signature))
             continue;
         functionSeen.add(fn.signature);
         const params = inputParams(fn);
-        lines.push(`    ${JSON.stringify(fn.signature)}: { kind: ${JSON.stringify(fn.kind)}; params: ${params}; returns: ${fn.returns}; returnsSet: ${fn.returnsSet} };`);
+        lines.push(`  ${JSON.stringify(fn.signature)}: { kind: ${JSON.stringify(fn.kind)}; params: ${params}; returns: ${fn.returns}; returnsSet: ${fn.returnsSet} };`);
     }
-    lines.push("  }");
+    lines.push("}");
+    lines.push("");
+    lines.push("export interface SqlxJsGeneratedRegistry {");
+    lines.push("  queries: SqlxJsGeneratedQueries;");
+    lines.push("  fileQueries: SqlxJsGeneratedFileQueries;");
+    lines.push("  functions: SqlxJsGeneratedFunctions;");
+    lines.push("}");
+}
+function emitModuleAugmentation(lines, moduleName) {
+    lines.push(`declare module ${JSON.stringify(moduleName)} {`);
+    lines.push("  interface KnownQueries extends SqlxJsGeneratedQueries {}");
+    lines.push("  interface KnownFileQueries extends SqlxJsGeneratedFileQueries {}");
+    lines.push("  interface KnownFunctions extends SqlxJsGeneratedFunctions {}");
     lines.push("}");
 }
 function inputParams(fn) {

package/dist/src/commands/init.js

@@ -36,10 +36,19 @@ const PGSCHEMA_TEMPLATE = `-- Desired PostgreSQL schema managed by pgschema.
 const DTS_TEMPLATE = `// AUTO-GENERATED by sqlx-js. Do not edit.
 // Run \`sqlx-js prepare\` to regenerate.
 
+export interface SqlxJsGeneratedQueries {}
+export interface SqlxJsGeneratedFileQueries {}
+export interface SqlxJsGeneratedFunctions {}
+export interface SqlxJsGeneratedRegistry {
+  queries: SqlxJsGeneratedQueries;
+  fileQueries: SqlxJsGeneratedFileQueries;
+  functions: SqlxJsGeneratedFunctions;
+}
+
 declare module "@onreza/sqlx-js" {
-  interface KnownQueries {}
-  interface KnownFileQueries {}
-  interface KnownFunctions {}
+  interface KnownQueries extends SqlxJsGeneratedQueries {}
+  interface KnownFileQueries extends SqlxJsGeneratedFileQueries {}
+  interface KnownFunctions extends SqlxJsGeneratedFunctions {}
 }
 
 export {};
@@ -132,6 +141,7 @@ export function runInit(opts) {
         const defaults = {
             "sqlx:prepare": "sqlx-js prepare",
             "sqlx:check": "sqlx-js prepare --check",
+            "sqlx:offline": "sqlx-js prepare --offline",
             "sqlx:verify": "sqlx-js prepare --verify --strict-inference",
         };
         let changed = false;

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

@@ -1,5 +1,6 @@
 import { PgClient, type ConnConfig, type FieldDescription } from "../pg/wire.js";
 import { SchemaCache } from "../pg/schema.js";
+import { type QueryCallSite } from "../scan/scanner.js";
 import { type SqlxJsConfig } from "../config.js";
 export type PrepareOptions = {
     root: string;
@@ -7,6 +8,7 @@ export type PrepareOptions = {
     cacheDir: string;
     dtsPath: string;
     check: boolean;
+    offline?: boolean;
     verify?: boolean;
     json?: boolean;
     prune?: boolean;
@@ -49,6 +51,11 @@ export type PrepareSession = {
     schema: SchemaCache;
     userCfg: SqlxJsConfig;
 };
+export type PrepareIncrementalInput = {
+    sites?: QueryCallSite[];
+    reuseCacheFps?: ReadonlySet<string>;
+    reuseFunctions?: boolean;
+};
 export declare function openSession(opts: PrepareOptions): Promise<PrepareSession>;
 type DescribeOutcome = {
     ok: true;
@@ -63,7 +70,7 @@ export declare function describeAll(cfg: ConnConfig, sessionClient: PgClient, qu
     fp: string;
     query: string;
 }[], concurrency: number): Promise<Map<string, DescribeOutcome>>;
-export declare function prepareOnce(opts: PrepareOptions, session: PrepareSession, log?: (msg: string) => void, err?: (msg: string) => void, concurrency?: number): Promise<PrepareResult>;
+export declare function prepareOnce(opts: PrepareOptions, session: PrepareSession, log?: (msg: string) => void, err?: (msg: string) => void, concurrency?: number, input?: PrepareIncrementalInput): Promise<PrepareResult>;
 export declare function runPrepare(opts: PrepareOptions): Promise<void>;
 export declare function verifyPrepareArtifacts(opts: PrepareOptions, log?: (msg: string) => void, err?: (msg: string) => void): Promise<{
     ok: boolean;