@onreza/sqlx-js 0.6.0 → 0.8.0

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));
@@ -257,9 +263,9 @@ async function runRawQuery(client, query, params) {
     const start = performance.now();
     try {
         const result = await client.query(query, encoded);
-        onQuery({
-            query,
-            params,
+        notifyQuery(client, {
+            query: observedQuery,
+            params: observedParams,
             durationMs: performance.now() - start,
             rowCount: result.count ?? result.length,
         });
@@ -267,10 +273,29 @@ async function runRawQuery(client, query, params) {
     }
     catch (e) {
         const error = toPgError(e) ?? e;
-        onQuery({ query, params, durationMs: performance.now() - start, error });
+        notifyQuery(client, { query: observedQuery, params: observedParams, durationMs: performance.now() - start, error });
         throw error;
     }
 }
+function notifyQuery(client, event) {
+    try {
+        const pending = client.onQuery?.(event);
+        if (pending)
+            void pending.catch((error) => notifyQueryHookError(client, error, event));
+    }
+    catch (error) {
+        notifyQueryHookError(client, error, event);
+    }
+}
+function notifyQueryHookError(client, error, event) {
+    try {
+        const pending = client.onQueryHookError?.(error, event);
+        if (pending)
+            void pending.catch(() => { });
+    }
+    catch {
+    }
+}
 async function runQuery(client, query, params) {
     return renameRows(await runRawQuery(client, query, params));
 }
@@ -298,7 +323,7 @@ async function runOptional(client, query, params) {
     throw new TooManyRowsError(rows.length, "0 or 1");
 }
 const sqlFileCache = new Map();
-function loadSqlFile(path, fileRoot = process.env.SQLX_JS_FILE_ROOT ?? process.cwd()) {
+function loadSqlFile(path, fileRoot = process.env.SQLX_JS_FILE_ROOT ?? process.cwd(), reload = false) {
     const root = resolve(fileRoot);
     if (isAbsolute(path)) {
         throw new Error(`sqlx-js.sql.file: path must be relative to fileRoot: ${path}`);
@@ -309,8 +334,10 @@ function loadSqlFile(path, fileRoot = process.env.SQLX_JS_FILE_ROOT ?? process.c
         throw new Error(`sqlx-js.sql.file: path escapes fileRoot: ${path}`);
     }
     try {
-        const st = statSync(full);
         const cached = sqlFileCache.get(full);
+        if (cached && !reload)
+            return cached.content;
+        const st = statSync(full);
         if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) {
             return cached.content;
         }
@@ -442,16 +469,16 @@ function makeBoundCallable(client) {
         return runQuery(client, query, params);
     });
     const file = (async (path, ...params) => {
-        return runQuery(client, loadSqlFile(path, client.fileRoot), params);
+        return runQuery(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
     });
     file.one = (async (path, ...params) => {
-        return runOne(client, loadSqlFile(path, client.fileRoot), params);
+        return runOne(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
     });
     file.optional = (async (path, ...params) => {
-        return runOptional(client, loadSqlFile(path, client.fileRoot), params);
+        return runOptional(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
     });
     file.execute = (async (path, ...params) => {
-        return runExecute(client, loadSqlFile(path, client.fileRoot), params);
+        return runExecute(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
     });
     fn.file = file;
     fn.one = (async (query, ...params) => {
@@ -486,19 +513,19 @@ export function createSqlRuntime(getClient) {
     });
     const rootFile = (async (path, ...params) => {
         const client = getClient();
-        return runQuery(client, loadSqlFile(path, client.fileRoot), params);
+        return runQuery(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
     });
     rootFile.one = (async (path, ...params) => {
         const client = getClient();
-        return runOne(client, loadSqlFile(path, client.fileRoot), params);
+        return runOne(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
     });
     rootFile.optional = (async (path, ...params) => {
         const client = getClient();
-        return runOptional(client, loadSqlFile(path, client.fileRoot), params);
+        return runOptional(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
     });
     rootFile.execute = (async (path, ...params) => {
         const client = getClient();
-        return runExecute(client, loadSqlFile(path, client.fileRoot), params);
+        return runExecute(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
     });
     root.file = rootFile;
     root.one = (async (query, ...params) => {

package/dist/src/scan/scanner.js

@@ -1,6 +1,7 @@
 import ts from "typescript";
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { extname, isAbsolute, join, relative, resolve } from "node:path";
+import { rewriteNamedParameters } from "../sql-params.js";
 export class ScanError extends Error {
     file;
     line;
@@ -76,7 +77,7 @@ function classifyCallee(callee, scope) {
     const methodName = callee.name.text;
     if (ts.isIdentifier(callee.expression)) {
         const id = callee.expression.text;
-        if (scope.namespaces.has(id)) {
+        if (scope.namespaces.has(id) || scope.clients.has(id)) {
             if (methodName === "sql")
                 return { kind: "inline" };
             return null;
@@ -95,8 +96,9 @@ function classifyCallee(callee, scope) {
         const mid = callee.expression;
         if (!ts.isIdentifier(mid.name))
             return null;
-        // ns.sql.X(...) chains
-        if (ts.isIdentifier(mid.expression) && scope.namespaces.has(mid.expression.text)) {
+        // ns.sql.X(...) and client.sql.X(...) chains
+        if (ts.isIdentifier(mid.expression) &&
+            (scope.namespaces.has(mid.expression.text) || scope.clients.has(mid.expression.text))) {
             if (mid.name.text !== "sql")
                 return null;
             if (methodName === "one" || methodName === "optional" || methodName === "execute")
@@ -118,11 +120,11 @@ function classifyCallee(callee, scope) {
                 return { kind: "file" };
             return null;
         }
-        // ns.sql.file.X(...) chains
+        // ns.sql.file.X(...) and client.sql.file.X(...) chains
         if (ts.isPropertyAccessExpression(mid.expression) &&
             ts.isIdentifier(mid.expression.expression) &&
             ts.isIdentifier(mid.expression.name) &&
-            scope.namespaces.has(mid.expression.expression.text) &&
+            (scope.namespaces.has(mid.expression.expression.text) || scope.clients.has(mid.expression.expression.text)) &&
             mid.expression.name.text === "sql" &&
             mid.name.text === "file" &&
             (methodName === "one" || methodName === "optional" || methodName === "execute")) {
@@ -133,9 +135,18 @@ function classifyCallee(callee, scope) {
 }
 export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
     const text = readFileSync(absPath, "utf8");
-    const source = ts.createSourceFile(absPath, text, ts.ScriptTarget.ESNext, false, ts.ScriptKind.TSX);
+    const source = ts.createSourceFile(absPath, text, ts.ScriptTarget.ESNext, false, scriptKind(absPath));
+    const parseDiagnostics = source.parseDiagnostics ?? [];
+    const parseError = parseDiagnostics.find((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    if (parseError) {
+        const start = parseError.start ?? 0;
+        const { line, character } = source.getLineAndCharacterOfPosition(start);
+        const file = relative(root, absPath).replace(/\\/g, "/");
+        throw new ScanError(file, line + 1, character + 1, ts.flattenDiagnosticMessageText(parseError.messageText, "\n"));
+    }
     const importedAliases = new Set();
     const importedNamespaces = new Set();
+    const importedClientFactories = new Set();
     for (const stmt of source.statements) {
         if (!ts.isImportDeclaration(stmt))
             continue;
@@ -158,23 +169,35 @@ export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
                 const orig = (elem.propertyName ?? elem.name).text;
                 if (orig === "sql")
                     importedAliases.add(elem.name.text);
+                if (orig === "createSqlClient")
+                    importedClientFactories.add(elem.name.text);
             }
         }
     }
-    if (importedAliases.size === 0 && importedNamespaces.size === 0)
+    if (importedAliases.size === 0 && importedNamespaces.size === 0 && importedClientFactories.size === 0)
         return [];
     const out = [];
     const here = (node) => {
         const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
         return { line: line + 1, column: character + 1 };
     };
-    const fileRel = relative(root, absPath);
+    const fileRel = relative(root, absPath).replace(/\\/g, "/");
     const recordInline = (first, args) => {
         if (!ts.isStringLiteralLike(first)) {
             const pos = here(first);
             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,
@@ -207,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,
@@ -233,6 +266,8 @@ export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
         let changed = false;
         const nextSql = new Set(scope.sqlAliases);
         const nextNs = new Set(scope.namespaces);
+        const nextFactories = new Set(scope.clientFactories);
+        const nextClients = new Set(scope.clients);
         for (const binding of bindings) {
             for (const a of scope.sqlAliases) {
                 if (bindingDeclares(binding, a)) {
@@ -246,8 +281,44 @@ export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
                     changed = true;
                 }
             }
+            for (const a of scope.clientFactories) {
+                if (bindingDeclares(binding, a)) {
+                    nextFactories.delete(a);
+                    changed = true;
+                }
+            }
+            for (const a of scope.clients) {
+                if (bindingDeclares(binding, a)) {
+                    nextClients.delete(a);
+                    changed = true;
+                }
+            }
         }
-        return changed ? { sqlAliases: nextSql, namespaces: nextNs } : scope;
+        return changed
+            ? { sqlAliases: nextSql, namespaces: nextNs, clientFactories: nextFactories, clients: nextClients }
+            : scope;
+    };
+    const isClientFactoryCall = (initializer, scope) => {
+        if (!initializer || !ts.isCallExpression(initializer))
+            return false;
+        const callee = initializer.expression;
+        if (ts.isIdentifier(callee))
+            return scope.clientFactories.has(callee.text);
+        return ts.isPropertyAccessExpression(callee) &&
+            ts.isIdentifier(callee.expression) &&
+            scope.namespaces.has(callee.expression.text) &&
+            callee.name.text === "createSqlClient";
+    };
+    const scopeWithClientDeclarations = (scope, declarations) => {
+        const nextClients = new Set(scope.clients);
+        let changed = false;
+        for (const declaration of declarations) {
+            if (!ts.isIdentifier(declaration.name) || !isClientFactoryCall(declaration.initializer, scope))
+                continue;
+            nextClients.add(declaration.name.text);
+            changed = true;
+        }
+        return changed ? { ...scope, clients: nextClients } : scope;
     };
     const visit = (node, scope) => {
         if (ts.isCallExpression(node)) {
@@ -262,7 +333,7 @@ export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
                         if (param && ts.isIdentifier(param.name)) {
                             innerSql.add(param.name.text);
                         }
-                        visit(fn.body, { sqlAliases: innerSql, namespaces: shadowed.namespaces });
+                        visit(fn.body, { ...shadowed, sqlAliases: innerSql });
                         return;
                     }
                 }
@@ -283,7 +354,11 @@ export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
             const stmts = node.statements;
             for (const stmt of stmts) {
                 if (ts.isVariableStatement(stmt)) {
-                    current = scopeWithoutBindingShadows(current, stmt.declarationList.declarations.map((d) => d.name));
+                    const declarations = stmt.declarationList.declarations;
+                    current = scopeWithoutBindingShadows(current, declarations.map((d) => d.name));
+                    visit(stmt, current);
+                    current = scopeWithClientDeclarations(current, declarations);
+                    continue;
                 }
                 else if (ts.isFunctionDeclaration(stmt) && stmt.name) {
                     current = scopeWithoutBindingShadows(current, [stmt.name]);
@@ -320,9 +395,22 @@ export function scanFile(absPath, root, modules = DEFAULT_SQLX_MODULES) {
         }
         ts.forEachChild(node, (child) => visit(child, scope));
     };
-    visit(source, { sqlAliases: importedAliases, namespaces: importedNamespaces });
+    visit(source, {
+        sqlAliases: importedAliases,
+        namespaces: importedNamespaces,
+        clientFactories: importedClientFactories,
+        clients: new Set(),
+    });
     return out;
 }
+function scriptKind(path) {
+    switch (extname(path).toLowerCase()) {
+        case ".tsx": return ts.ScriptKind.TSX;
+        case ".mts":
+        case ".cts":
+        default: return ts.ScriptKind.TS;
+    }
+}
 export function scanProject(root, scan = {}) {
     const files = findSourceFiles(root, scan);
     const out = [];

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.6.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"