@onreza/sqlx-js 0.7.0 → 0.8.0

package/README.md

@@ -53,11 +53,13 @@ const rows = await sql(
 
 ```bash
 npm install @onreza/sqlx-js
+npm install --save-dev typescript
 # or
 bun add @onreza/sqlx-js
+bun add --dev typescript
 ```
 
-Node.js 24 or newer is required. Bun users need Bun 1.3 or newer.
+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.
 
 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.
 
@@ -112,6 +114,20 @@ CREATE TABLE users (
 );
 ```
 
+For queries with several values, named parameters keep the SQL and arguments aligned:
+
+```ts
+const rows = await sql(
+  `SELECT id, name
+   FROM users
+   WHERE email = $email OR recovery_email = $email
+   LIMIT $limit`,
+  { email: "user@example.com", limit: 10 },
+);
+```
+
+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.
+
 During local development, validate the migration and regenerate query artifacts against a disposable shadow database:
 
 ```bash
@@ -411,10 +427,11 @@ In addition to `import { sql } from "@onreza/sqlx-js"`, the scanner recognises `
 ```
 sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]
 sqlx-js doctor [--root <dir>] [--dts <path>] [--json]
+sqlx-js ci [--root <dir>] [--dts <path>] [--schema <path>] [--json] [--shadow-url <url>] [--shadow-admin-url <url>]
 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 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 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>]
 sqlx-js --version | --help
@@ -680,6 +697,14 @@ The runtime strips the `!`/`?` suffix from column keys so the row shape stays cl
 
 ## CI workflow
 
+The shortest production gate is provider-aware:
+
+```bash
+sqlx-js ci
+```
+
+For the built-in migration provider it runs shadow migration verification with strict inference, followed by the read-only offline artifact check. For pgschema it checks the configured provider, fails when the desired schema produces an unapplied plan, performs live `prepare --verify --strict-inference`, and then verifies committed artifacts offline. If a committed schema snapshot exists, both flows also run `schema check`. `--json` returns a versioned per-step report suitable for CI systems.
+
 Commit the generated `sqlx-js-env.d.ts` and the `.sqlx-js/` cache directory to your repo. In CI:
 
 ```yaml

package/ROADMAP.md

@@ -7,11 +7,12 @@ Items already shipped live in the [README](./README.md) feature list; this file
 | Feature | ROI | Notes |
 |---------|-----|-------|
 | 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. |
 | 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 | 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. |
+| 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. |
 | 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. |
@@ -21,6 +22,6 @@ Items already shipped live in the [README](./README.md) feature list; this file
 
 ## Long-term
 
-- Full LSP with schema-driven autocomplete.
+- Editor clients or a full LSP only after repeated consumer demand demonstrates that the separate maintenance and release lifecycle will pay for itself.
 - Hooks for ORM-like helpers that build on top of the typed `sql()` primitive (joins, paginated queries, etc.) without becoming an ORM.
 - Optional binary protocol support in the underlying wire client for measurable perf gain on large result sets.

package/dist/bin/sqlx-js.js

@@ -22,10 +22,11 @@ const HELP = {
 usage:
   sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]
   sqlx-js doctor [--root <dir>] [--dts <path>] [--json]
+  sqlx-js ci [--root <dir>] [--dts <path>] [--schema <path>] [--json] [--shadow-url <url>] [--shadow-admin-url <url>]
   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 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 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>]
   sqlx-js --version
@@ -62,9 +63,10 @@ flags:
 `,
     init: `usage: sqlx-js init [--root <dir>] [--schema-provider builtin|pgschema]`,
     doctor: `usage: sqlx-js doctor [--root <dir>] [--dts <path>] [--json]`,
+    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>]`,
-    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]`,
+    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>]`,
 };
 function printHelp(scope, error = false) {
@@ -84,7 +86,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", "db", "prepare", "migrate", "schema"]);
+const scopes = new Set(["init", "doctor", "ci", "db", "prepare", "migrate", "schema"]);
 if (cmd === "--version" || cmd === "-v") {
     console.log(VERSION);
     process.exit(0);
@@ -107,6 +109,16 @@ function optionsFor(command, subcommand) {
         return { ...ROOT_OPTIONS, "schema-provider": { type: "string" } };
     if (command === "doctor")
         return { ...ROOT_OPTIONS, dts: { type: "string" }, json: { type: "boolean" } };
+    if (command === "ci")
+        return {
+            ...ROOT_OPTIONS,
+            json: { type: "boolean" },
+            dts: { type: "string" },
+            schema: { type: "string" },
+            migrations: { type: "string" },
+            "shadow-url": { type: "string" },
+            "shadow-admin-url": { type: "string" },
+        };
     if (command === "db")
         return ROOT_OPTIONS;
     if (command === "prepare") {
@@ -145,6 +157,7 @@ function optionsFor(command, subcommand) {
     if (subcommand === "dev") {
         return {
             ...common,
+            dts: { type: "string" },
             "shadow-admin-url": { type: "string" },
             "shadow-url": { type: "string" },
             "lock-timeout": { type: "string" },
@@ -155,6 +168,7 @@ function optionsFor(command, subcommand) {
     if (subcommand === "verify") {
         return {
             ...common,
+            dts: { type: "string" },
             "shadow-admin-url": { type: "string" },
             "shadow-url": { type: "string" },
             "lock-timeout": { type: "string" },
@@ -214,7 +228,7 @@ function requirePositionals(min, max, label) {
     }
 }
 function validateInvocation() {
-    if (cmd === "init" || cmd === "doctor" || cmd === "prepare") {
+    if (cmd === "init" || cmd === "doctor" || cmd === "ci" || cmd === "prepare") {
         requirePositionals(0, 0, cmd);
         return;
     }
@@ -264,17 +278,55 @@ function validateInvocation() {
 }
 validateInvocation();
 const root = resolve(arg("--root", process.cwd()));
+function failCiPreflight(message) {
+    if (cmd === "ci" && flag("--json")) {
+        console.log(JSON.stringify({
+            formatVersion: 1,
+            ok: false,
+            results: [{ name: "preflight", ok: false, durationMs: 0, exitCode: 2, stderr: message }],
+        }, null, 2));
+    }
+    else {
+        console.error(message);
+    }
+    process.exit(2);
+}
 if (cmd !== "doctor") {
     try {
         assertSupportedRuntime();
     }
     catch (e) {
-        console.error(e.message);
+        failCiPreflight(e.message);
+    }
+}
+const needsTypeScript = cmd === "doctor" ||
+    cmd === "ci" ||
+    cmd === "prepare" ||
+    (cmd === "migrate" && (positionals[0] === "dev" || positionals[0] === "verify"));
+if (needsTypeScript) {
+    try {
+        import.meta.resolve("typescript");
+    }
+    catch {
+        const message = "sqlx-js: TypeScript is required for source scanning. Install it with `npm install --save-dev typescript` or `bun add --dev typescript`.";
+        if (cmd === "doctor" && flag("--json")) {
+            console.log(JSON.stringify({
+                formatVersion: 1,
+                ok: false,
+                checks: [{ name: "typescript", status: "error", message }],
+            }, null, 2));
+        }
+        else {
+            if (cmd === "ci")
+                failCiPreflight(message);
+            console.error(message);
+        }
         process.exit(2);
     }
 }
 let envError;
 const needsEnvironment = cmd === "doctor" ||
+    cmd === "ci" ||
     cmd === "schema" ||
     (cmd === "db" && (positionals[0] === "plan" || positionals[0] === "apply")) ||
     (cmd === "prepare" && !flag("--check") && !flag("--offline")) ||
@@ -286,8 +338,7 @@ if (needsEnvironment) {
     catch (e) {
         envError = e.message;
         if (cmd !== "doctor") {
-            console.error(envError);
-            process.exit(2);
+            failCiPreflight(envError);
         }
     }
 }
@@ -316,6 +367,28 @@ else if (cmd === "doctor") {
     const { runDoctor } = await import("../src/commands/doctor.js");
     await runDoctor({ root, databaseUrl, cacheDir, dtsPath, json: flag("--json"), envError });
 }
+else if (cmd === "ci") {
+    const { runCi } = await import("../src/commands/ci.js");
+    let config;
+    try {
+        config = await loadConfig(root);
+    }
+    catch (error) {
+        failCiPreflight(error.message);
+    }
+    runCi({
+        executable: process.execPath,
+        cliPath: fileURLToPath(import.meta.url),
+        root,
+        config,
+        schemaPath,
+        json: flag("--json"),
+        shadowUrl,
+        shadowAdminUrl,
+        migrationsDir: arg("--migrations"),
+        dtsPath: dtsArg ? dtsPath : undefined,
+    });
+}
 else if (cmd === "db") {
     const { runPgschemaCommand, runPgschemaInstall } = await import("../src/commands/pgschema.js");
     const sub = positionals[0];

package/dist/src/cache.d.ts

@@ -1,5 +1,5 @@
-export declare const CACHE_FORMAT_VERSION = 2;
-export declare const GENERATOR_REVISION = 4;
+export declare const CACHE_FORMAT_VERSION = 3;
+export declare const GENERATOR_REVISION = 5;
 export declare const CACHE_MANIFEST_FILE = "cache-manifest.json";
 export type CacheManifest = {
     cacheFormat: typeof CACHE_FORMAT_VERSION;
@@ -19,6 +19,7 @@ export type CacheEntry = {
     paramOids: number[];
     paramTsTypes: string[];
     paramNullable?: boolean[];
+    paramNames?: string[];
     columns: CacheColumn[];
     hasResultSet: boolean;
     hasInline?: boolean;

package/dist/src/cache.js

@@ -2,8 +2,10 @@ import { createHash, 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";
-export const CACHE_FORMAT_VERSION = 2;
-export const GENERATOR_REVISION = 4;
+import { isEscapeStringPrefix, isIdentifierContinuation, readBlockComment, readDollarQuoted, readLineComment, readQuotedIdentifier, readSingleQuoted, } from "./sql-lex.js";
+import { rewriteNamedParameters } from "./sql-params.js";
+export const CACHE_FORMAT_VERSION = 3;
+export const GENERATOR_REVISION = 5;
 export const CACHE_MANIFEST_FILE = "cache-manifest.json";
 export function portableCacheOid(oid) {
     return isBuiltinOid(oid) ? oid : 0;
@@ -56,7 +58,7 @@ function normalizeForFingerprint(query) {
             continue;
         }
         if (ch === "$") {
-            const next = readDollarQuoted(query, i);
+            const next = i === 0 || !isIdentifierContinuation(query[i - 1]) ? readDollarQuoted(query, i) : null;
             if (next !== null) {
                 emit(query.slice(i, next));
                 i = next;
@@ -68,77 +70,6 @@ function normalizeForFingerprint(query) {
     }
     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;
@@ -166,6 +97,27 @@ function assertEntryShape(fp, raw) {
         throw new Error(`sqlx-js: cache entry ${fp}.json is malformed`);
     }
     const cols = raw.columns;
+    const entry = raw;
+    let expectedNames;
+    try {
+        if (typeof entry.query !== "string")
+            throw new Error("query must be a string");
+        expectedNames = rewriteNamedParameters(entry.query).names;
+    }
+    catch {
+        throw new Error(`sqlx-js: cache entry ${fp}.json has malformed named parameter metadata. Run \`sqlx-js prepare\`.`);
+    }
+    if (entry.paramNames !== undefined || expectedNames.length > 0) {
+        if (!Array.isArray(entry.paramNames) ||
+            !entry.paramNames.every((name) => typeof name === "string") ||
+            !Array.isArray(entry.paramTsTypes) ||
+            entry.paramNames.length !== entry.paramTsTypes.length ||
+            new Set(entry.paramNames).size !== entry.paramNames.length ||
+            entry.paramNames.length !== expectedNames.length ||
+            entry.paramNames.some((name, index) => name !== expectedNames[index])) {
+            throw new Error(`sqlx-js: cache entry ${fp}.json has malformed named parameter metadata. Run \`sqlx-js prepare\`.`);
+        }
+    }
     if (cols.length > 0) {
         const c = cols[0];
         if ("forceNonNull" in c || "forceNullable" in c) {

package/dist/src/codegen.js

@@ -7,7 +7,9 @@ function entrySignature(e) {
         const nullable = e.paramNullable?.[i] === true;
         return nullable ? `${t} | null` : t;
     });
-    const params = paramTypes.length === 0 ? "[]" : `[${paramTypes.join(", ")}]`;
+    const params = e.paramNames && e.paramNames.length > 0
+        ? `{ ${e.paramNames.map((name, index) => `${JSON.stringify(name)}: ${paramTypes[index]}`).join("; ")} }`
+        : paramTypes.length === 0 ? "[]" : `[${paramTypes.join(", ")}]`;
     if (!e.hasResultSet)
         return { params, row: "never" };
     const cols = e.columns.map((c) => {

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

@@ -0,0 +1,28 @@
+import type { SqlxJsConfig } from "../config.js";
+export type CiStep = {
+    name: string;
+    args: string[];
+    check?: "pgschema-plan";
+};
+export type CiStepResult = {
+    name: string;
+    ok: boolean;
+    durationMs: number;
+    exitCode: number;
+    stderr?: string;
+};
+export type CiOptions = {
+    executable: string;
+    cliPath: string;
+    root: string;
+    config: SqlxJsConfig;
+    schemaPath: string;
+    json?: boolean;
+    shadowUrl?: string;
+    shadowAdminUrl?: string;
+    migrationsDir?: string;
+    dtsPath?: string;
+};
+export declare function buildCiSteps(opts: Pick<CiOptions, "config" | "root" | "schemaPath" | "shadowUrl" | "shadowAdminUrl" | "migrationsDir" | "dtsPath">): CiStep[];
+export declare function assertPgschemaPlanClean(path: string): void;
+export declare function runCi(opts: CiOptions): void;

package/dist/src/commands/ci.js

@@ -0,0 +1,103 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const PLAN_PATH = "{sqlx-js-ci-plan}";
+export function buildCiSteps(opts) {
+    const root = ["--root", opts.root];
+    const shadow = opts.shadowUrl ? ["--shadow-url", opts.shadowUrl] : [];
+    const shadowAdmin = opts.shadowAdminUrl ? ["--shadow-admin-url", opts.shadowAdminUrl] : [];
+    const migrations = opts.migrationsDir ? ["--migrations", opts.migrationsDir] : [];
+    const dts = opts.dtsPath ? ["--dts", opts.dtsPath] : [];
+    const steps = opts.config.schema?.provider === "pgschema"
+        ? [
+            { name: "pgschema", args: ["db", "check", ...root] },
+            {
+                name: "pgschema-plan",
+                args: ["db", "plan", ...root, "--", "--output-json", PLAN_PATH, "--no-color"],
+                check: "pgschema-plan",
+            },
+            { name: "prepare-live", args: ["prepare", "--verify", "--strict-inference", ...shadow, ...dts, ...root] },
+        ]
+        : [{
+                name: "migrations",
+                args: ["migrate", "verify", "--strict-inference", ...shadow, ...shadowAdmin, ...migrations, ...dts, ...root],
+            }];
+    steps.push({ name: "prepare-offline", args: ["prepare", "--check", "--strict-inference", ...dts, ...root] });
+    if (existsSync(opts.schemaPath)) {
+        steps.push({ name: "schema", args: ["schema", "check", ...shadow, "--schema", opts.schemaPath, ...migrations, ...root] });
+    }
+    return steps;
+}
+export function assertPgschemaPlanClean(path) {
+    const plan = JSON.parse(readFileSync(path, "utf8"));
+    if (plan.groups === null)
+        return;
+    if (!Array.isArray(plan.groups))
+        throw new Error("plan JSON does not contain groups as an array or null");
+    if (plan.groups.length > 0)
+        throw new Error(`pgschema plan contains ${plan.groups.length} unapplied change group(s)`);
+}
+export function runCi(opts) {
+    const results = [];
+    const temp = mkdtempSync(join(tmpdir(), "sqlx-js-ci-"));
+    try {
+        for (const step of buildCiSteps(opts)) {
+            if (!opts.json)
+                console.log(`ci: ${step.name}`);
+            const started = performance.now();
+            const planPath = join(temp, "pgschema-plan.json");
+            const args = step.args.map((arg) => arg === PLAN_PATH ? planPath : arg);
+            const result = spawnSync(opts.executable, [opts.cliPath, ...args], {
+                encoding: "utf8",
+                env: process.env,
+                stdio: opts.json ? ["ignore", "ignore", "pipe"] : "inherit",
+                maxBuffer: 4 * 1024 * 1024,
+            });
+            let exitCode = result.status ?? 1;
+            let checkError;
+            if (exitCode === 0 && step.check === "pgschema-plan") {
+                try {
+                    assertPgschemaPlanClean(planPath);
+                }
+                catch (error) {
+                    checkError = error.message.startsWith("pgschema plan contains")
+                        ? error.message
+                        : `cannot verify pgschema plan: ${error.message}`;
+                    exitCode = 1;
+                }
+            }
+            if (result.error) {
+                checkError = result.error.message;
+                exitCode = 1;
+            }
+            else if (result.signal) {
+                checkError = `terminated by signal ${result.signal}`;
+                exitCode = 1;
+            }
+            if (checkError && !opts.json)
+                console.error(`ci: ${step.name}: ${checkError}`);
+            results.push({
+                name: step.name,
+                ok: exitCode === 0,
+                durationMs: Math.round(performance.now() - started),
+                exitCode,
+                ...(opts.json && exitCode !== 0 && (checkError || result.stderr)
+                    ? { stderr: [result.stderr?.trim(), checkError].filter(Boolean).join("\n") }
+                    : {}),
+            });
+            if (exitCode !== 0)
+                break;
+        }
+    }
+    finally {
+        rmSync(temp, { recursive: true, force: true });
+    }
+    const ok = results.length > 0 && results.every((result) => result.ok);
+    if (opts.json)
+        console.log(JSON.stringify({ formatVersion: 1, ok, results }, null, 2));
+    else if (ok)
+        console.log(`ci: ok — ${results.length} check(s) passed`);
+    if (!ok)
+        process.exitCode = 1;
+}

package/dist/src/commands/init.js

@@ -143,6 +143,7 @@ export function runInit(opts) {
             "sqlx:check": "sqlx-js prepare --check",
             "sqlx:offline": "sqlx-js prepare --offline",
             "sqlx:verify": "sqlx-js prepare --verify --strict-inference",
+            "sqlx:ci": "sqlx-js ci",
         };
         let changed = false;
         for (const [name, command] of Object.entries(defaults)) {

package/dist/src/commands/prepare.js

@@ -15,6 +15,7 @@ import { buildParamMap } from "../pg/param-map.js";
 import { mergeExtensionTypes } from "../pg/extensions.js";
 import { compareArtifacts } from "../artifacts.js";
 import { containsUnknownType } from "../type-inspection.js";
+import { originalPosition, rewriteNamedParameters } from "../sql-params.js";
 const JSON_OIDS = new Set([114, 3802]);
 const JSON_ARRAY_OIDS = new Set([199, 3807]);
 const JSON_INPUT_VALUE = 'import("@onreza/sqlx-js").JsonInputValue';
@@ -207,8 +208,9 @@ function inferenceIssues(entry) {
     if (entry.degraded)
         issues.push(`nullability inference degraded: ${entry.degraded.reason}`);
     entry.paramTsTypes.forEach((type, index) => {
+        const parameter = entry.paramNames?.[index] ? `$${entry.paramNames[index]}` : `$${index + 1}`;
         if (containsUnknownType(type))
-            issues.push(`parameter $${index + 1} resolved to ${type}`);
+            issues.push(`parameter ${parameter} resolved to ${type}`);
     });
     for (const column of entry.columns) {
         if (containsUnknownType(column.tsType)) {
@@ -225,7 +227,7 @@ function inferenceDiagnostics(entry, site, strict) {
         file: site.file,
         line: site.line,
         column: site.column,
-        query: entry.query,
+        query: site.query,
     }));
 }
 export async function openSession(opts) {
@@ -326,12 +328,13 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
     let failures = 0;
     const unique = new Map();
     for (const s of sites) {
+        const rewritten = rewriteNamedParameters(s.query);
         const fp = fingerprint(s.query);
         const existing = unique.get(fp);
         if (existing)
             existing.sites.push(s);
         else
-            unique.set(fp, { fp, query: s.query, sites: [s] });
+            unique.set(fp, { fp, query: rewritten.query, paramNames: rewritten.names, sites: [s] });
     }
     const raw = [];
     const reusedEntries = [];
@@ -372,18 +375,19 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
                     file: site.file,
                     line: site.line,
                     column: site.column,
-                    query,
+                    query: site.query,
                 });
                 err(`  ✗ ${formatSite(site)} — ${message}`);
-                err(`      query: ${snippet(query)}`);
+                err(`      query: ${snippet(site.query)}`);
                 continue;
             }
-            raw.push({ fp, query, sites: ss, paramOids: outcome.paramOids, fields: outcome.fields });
+            raw.push({ fp, query, sites: ss, paramOids: outcome.paramOids, fields: outcome.fields, paramNames: toPrepare.get(fp).paramNames });
             continue;
         }
         failures++;
         const e = outcome.error;
         if (e instanceof PgError) {
+            const position = e.position ? originalPosition(rewriteNamedParameters(site.query), e.position) : undefined;
             diagnostics.push({
                 severity: "error",
                 phase: "describe",
@@ -391,21 +395,21 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
                 file: site.file,
                 line: site.line,
                 column: site.column,
-                query,
+                query: site.query,
                 ...(e.code ? { code: e.code } : {}),
-                ...(e.position ? { position: e.position } : {}),
+                ...(position ? { position } : {}),
                 ...(e.hint ? { hint: e.hint } : {}),
             });
             const extras = [];
-            if (e.position)
-                extras.push(`pos ${e.position}`);
+            if (position)
+                extras.push(`pos ${position}`);
             if (e.code)
                 extras.push(`code ${e.code}`);
             const tail = extras.length > 0 ? ` (${extras.join(", ")})` : "";
             err(`  ✗ ${formatSite(site)} — describe failed: ${e.message}${tail}`);
             if (e.hint)
                 err(`      hint: ${e.hint}`);
-            err(`      query: ${snippet(query)}`);
+            err(`      query: ${snippet(site.query)}`);
         }
         else {
             diagnostics.push({
@@ -415,10 +419,10 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
                 file: site.file,
                 line: site.line,
                 column: site.column,
-                query,
+                query: site.query,
             });
             err(`  ✗ ${formatSite(site)} — describe failed: ${e.message}`);
-            err(`      query: ${snippet(query)}`);
+            err(`      query: ${snippet(site.query)}`);
         }
     }
     const allAttrRefs = [];
@@ -456,10 +460,10 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
                 file: site.file,
                 line: site.line,
                 column: site.column,
-                query: r.query,
+                query: site.query,
             });
             err(`  ✗ ${formatSite(site)} — analyze failed: ${e.message}`);
-            err(`      query: ${snippet(r.query)}`);
+            err(`      query: ${snippet(site.query)}`);
             continue;
         }
         try {
@@ -475,10 +479,10 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
                 file: site.file,
                 line: site.line,
                 column: site.column,
-                query: r.query,
+                query: site.query,
             });
             err(`  ✗ ${formatSite(site)} — paramMap failed: ${e.message}`);
-            err(`      query: ${snippet(r.query)}`);
+            err(`      query: ${snippet(site.query)}`);
         }
     }
     const dmlTablesToLoad = new Map();
@@ -534,11 +538,12 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
             dmlBound: new Set(),
         };
         const entry = {
-            query: r.query,
+            query: r.sites[0].query,
             ...siteUsage(r.sites),
             paramOids: r.paramOids.map(portableCacheOid),
             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)),
+            ...(r.paramNames.length > 0 ? { paramNames: r.paramNames } : {}),
             columns: r.fields.map((f, i) => {
                 const parsed = parseColumnOverride(f.name);
                 const treatAsOverride = parsed.override !== undefined && isAliasOrExpression(f, schema);

package/dist/src/runtime.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { PgClient, parseDatabaseUrl, PgError } from "./pg/wire.js";
 import { applyPending, acquireMigrateLock, releaseMigrateLock, DEFAULT_MIGRATE_LOCK_KEY } from "./migration-core.js";
+import { bindNamedParameters, rewriteNamedParameters } from "./sql-params.js";
 const PARAMETER_KIND = Symbol("sqlx-js.parameter");
 export function json(value) {
     return { [PARAMETER_KIND]: "json", value };
@@ -242,6 +243,11 @@ export const _internal = {
     toPgError,
 };
 async function runRawQuery(client, query, params) {
+    const observedQuery = query;
+    const observedParams = params;
+    const bound = bindNamedParameters(rewriteNamedParameters(query), params);
+    query = bound.query;
+    params = bound.params;
     const encoded = params.length === 0
         ? params
         : params.map((p) => client.transformParam ? client.transformParam(p) : encodeParam(p));
@@ -258,8 +264,8 @@ async function runRawQuery(client, query, params) {
     try {
         const result = await client.query(query, encoded);
         notifyQuery(client, {
-            query,
-            params,
+            query: observedQuery,
+            params: observedParams,
             durationMs: performance.now() - start,
             rowCount: result.count ?? result.length,
         });
@@ -267,7 +273,7 @@ async function runRawQuery(client, query, params) {
     }
     catch (e) {
         const error = toPgError(e) ?? e;
-        notifyQuery(client, { query, params, durationMs: performance.now() - start, error });
+        notifyQuery(client, { query: observedQuery, params: observedParams, durationMs: performance.now() - start, error });
         throw error;
     }
 }

package/dist/src/scan/scanner.js

@@ -1,6 +1,7 @@
 import ts from "typescript";
 import { existsSync, readFileSync } from "node:fs";
 import { extname, isAbsolute, join, relative, resolve } from "node:path";
+import { rewriteNamedParameters } from "../sql-params.js";
 export class ScanError extends Error {
     file;
     line;
@@ -187,6 +188,16 @@ export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
             throw new ScanError(fileRel, pos.line, pos.column, "sql() requires a string literal as first argument");
         }
         const pos = here(first);
+        let named;
+        try {
+            named = rewriteNamedParameters(first.text).names;
+        }
+        catch (error) {
+            throw new ScanError(fileRel, pos.line, pos.column, error.message.replace(/^sqlx-js: /, ""));
+        }
+        if (named.length > 0 && args.length !== 2) {
+            throw new ScanError(fileRel, pos.line, pos.column, "a query with named parameters requires exactly one parameter object");
+        }
         out.push({
             file: fileRel,
             line: pos.line,
@@ -219,6 +230,16 @@ export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
         }
         const query = readFileSync(abs, "utf8");
         const pos = here(first);
+        let named;
+        try {
+            named = rewriteNamedParameters(query).names;
+        }
+        catch (error) {
+            throw new ScanError(fileRel, pos.line, pos.column, error.message.replace(/^sqlx-js: /, ""));
+        }
+        if (named.length > 0 && args.length !== 2) {
+            throw new ScanError(fileRel, pos.line, pos.column, "a SQL file with named parameters requires exactly one parameter object");
+        }
         out.push({
             file: fileRel,
             line: pos.line,

package/dist/src/sql-lex.d.ts

@@ -0,0 +1,7 @@
+export declare function isIdentifierContinuation(value: string): boolean;
+export declare function isEscapeStringPrefix(query: string, quote: number): boolean;
+export declare function readSingleQuoted(query: string, start: number, escapeBackslash: boolean): number;
+export declare function readQuotedIdentifier(query: string, start: number): number;
+export declare function readDollarQuoted(query: string, start: number): number | null;
+export declare function readLineComment(query: string, start: number): number;
+export declare function readBlockComment(query: string, start: number): number;

package/dist/src/sql-lex.js

@@ -0,0 +1,76 @@
+export function isIdentifierContinuation(value) {
+    return /[A-Za-z0-9_$\u0080-\uFFFF]/.test(value);
+}
+export function isEscapeStringPrefix(query, quote) {
+    const prefix = query[quote - 1];
+    if (prefix !== "e" && prefix !== "E")
+        return false;
+    const before = query[quote - 2];
+    return before === undefined || !isIdentifierContinuation(before);
+}
+export function readSingleQuoted(query, start, escapeBackslash) {
+    let i = start + 1;
+    while (i < query.length) {
+        if (escapeBackslash && query[i] === "\\") {
+            i += 2;
+            continue;
+        }
+        if (query[i] === "'") {
+            if (query[i + 1] === "'") {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        i++;
+    }
+    return query.length;
+}
+export 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;
+}
+export function readDollarQuoted(query, start) {
+    let end = start + 1;
+    if (query[end] !== "$" && !/[A-Za-z_\u0080-\uFFFF]/.test(query[end]))
+        return null;
+    while (end < query.length && /[A-Za-z0-9_\u0080-\uFFFF]/.test(query[end]))
+        end++;
+    if (query[end] !== "$")
+        return null;
+    const tag = query.slice(start, end + 1);
+    const close = query.indexOf(tag, end + 1);
+    return close === -1 ? query.length : close + tag.length;
+}
+export function readLineComment(query, start) {
+    const end = query.indexOf("\n", start + 2);
+    return end === -1 ? query.length : end + 1;
+}
+export 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;
+}

package/dist/src/sql-params.d.ts

@@ -0,0 +1,11 @@
+export type RewrittenSql = {
+    query: string;
+    names: string[];
+    positionMap: number[];
+};
+export declare function rewriteNamedParameters(query: string): RewrittenSql;
+export declare function bindNamedParameters(rewritten: RewrittenSql, args: readonly unknown[]): {
+    query: string;
+    params: unknown[];
+};
+export declare function originalPosition(rewritten: RewrittenSql, oneBasedPosition: number): number;

package/dist/src/sql-params.js

@@ -0,0 +1,101 @@
+import { isEscapeStringPrefix, isIdentifierContinuation, readBlockComment, readDollarQuoted, readLineComment, readQuotedIdentifier, readSingleQuoted, } from "./sql-lex.js";
+export function rewriteNamedParameters(query) {
+    let out = "";
+    let i = 0;
+    let positional = false;
+    const names = [];
+    const indexes = new Map();
+    const positionMap = [];
+    const append = (text, sourceStart) => {
+        out += text;
+        for (let offset = 0; offset < text.length; offset++)
+            positionMap.push(sourceStart + offset);
+    };
+    while (i < query.length) {
+        const start = i;
+        const ch = query[i];
+        if (ch === "-" && query[i + 1] === "-") {
+            i = readLineComment(query, i);
+            append(query.slice(start, i), start);
+            continue;
+        }
+        if (ch === "/" && query[i + 1] === "*") {
+            i = readBlockComment(query, i);
+            append(query.slice(start, i), start);
+            continue;
+        }
+        if (ch === "'") {
+            i = readSingleQuoted(query, i, isEscapeStringPrefix(query, i));
+            append(query.slice(start, i), start);
+            continue;
+        }
+        if (ch === '"') {
+            i = readQuotedIdentifier(query, i);
+            append(query.slice(start, i), start);
+            continue;
+        }
+        if (ch === "$") {
+            if (i > 0 && isIdentifierContinuation(query[i - 1])) {
+                append(ch, i);
+                i++;
+                continue;
+            }
+            const quotedEnd = readDollarQuoted(query, i);
+            if (quotedEnd !== null) {
+                i = quotedEnd;
+                append(query.slice(start, i), start);
+                continue;
+            }
+            const positionalMatch = /^\$[1-9][0-9]*/.exec(query.slice(i));
+            if (positionalMatch) {
+                positional = true;
+                i += positionalMatch[0].length;
+                append(positionalMatch[0], start);
+                continue;
+            }
+            const namedMatch = /^\$([A-Za-z_][A-Za-z0-9_]*)/.exec(query.slice(i));
+            if (namedMatch) {
+                const name = namedMatch[1];
+                let index = indexes.get(name);
+                if (index === undefined) {
+                    names.push(name);
+                    index = names.length;
+                    indexes.set(name, index);
+                }
+                const replacement = `$${index}`;
+                append(replacement, start);
+                i += namedMatch[0].length;
+                continue;
+            }
+        }
+        append(ch, i);
+        i++;
+    }
+    if (positional && names.length > 0) {
+        throw new Error("sqlx-js: named and positional parameters cannot be mixed in one query");
+    }
+    positionMap.push(query.length);
+    return { query: out, names, positionMap };
+}
+export function bindNamedParameters(rewritten, args) {
+    if (rewritten.names.length === 0)
+        return { query: rewritten.query, params: [...args] };
+    if (args.length !== 1 || args[0] === null || typeof args[0] !== "object" || Array.isArray(args[0])) {
+        throw new Error("sqlx-js: a query with named parameters requires exactly one parameter object");
+    }
+    const values = args[0];
+    const missing = rewritten.names.filter((name) => !Object.hasOwn(values, name));
+    const expected = new Set(rewritten.names);
+    const extra = Object.keys(values).filter((name) => !expected.has(name));
+    if (missing.length > 0)
+        throw new Error(`sqlx-js: missing named parameter(s): ${missing.join(", ")}`);
+    if (extra.length > 0)
+        throw new Error(`sqlx-js: unknown named parameter(s): ${extra.join(", ")}`);
+    return { query: rewritten.query, params: rewritten.names.map((name) => values[name]) };
+}
+export function originalPosition(rewritten, oneBasedPosition) {
+    const position = Number(oneBasedPosition);
+    if (!Number.isInteger(position) || position < 1)
+        return oneBasedPosition;
+    return (rewritten.positionMap[position - 1] ?? position - 1) + 1;
+}

package/dist/src/typed.d.ts

@@ -1,6 +1,6 @@
 type ParamsOf<T> = T extends {
-    params: infer P extends readonly unknown[];
-} ? P : never[];
+    params: infer P;
+} ? P extends readonly unknown[] ? P : [P] : never[];
 type RowOf<T> = T extends {
     row: infer R;
 } ? R : never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onreza/sqlx-js",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Compile-time-checked raw SQL for TypeScript + PostgreSQL. Inspired by sqlx.",
   "license": "MIT",
   "type": "module",
@@ -66,6 +66,11 @@
   "peerDependencies": {
     "typescript": ">=5.4"
   },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "libpg-query": "^17.7.3",
     "postgres": "^3.4.9"