@onreza/sqlx-js 0.8.0 → 0.9.1

package/dist/src/query-id.js

@@ -0,0 +1,61 @@
+import { createHash } from "node:crypto";
+import { isEscapeStringPrefix, isIdentifierContinuation, readBlockComment, readDollarQuoted, readLineComment, readQuotedIdentifier, readSingleQuoted, } from "./sql-lex.js";
+export function queryId(query) {
+    return createHash("sha256").update(normalizeQuery(query)).digest("hex").slice(0, 16);
+}
+function normalizeQuery(query) {
+    let out = "";
+    let pendingSpace = false;
+    let i = 0;
+    const emit = (text) => {
+        if (pendingSpace && out.length > 0)
+            out += " ";
+        out += text;
+        pendingSpace = false;
+    };
+    const markSpace = () => {
+        if (out.length > 0)
+            pendingSpace = true;
+    };
+    while (i < query.length) {
+        const ch = query[i];
+        if (/\s/.test(ch)) {
+            markSpace();
+            i++;
+            continue;
+        }
+        if (ch === "-" && query[i + 1] === "-") {
+            i = readLineComment(query, i);
+            markSpace();
+            continue;
+        }
+        if (ch === "/" && query[i + 1] === "*") {
+            i = readBlockComment(query, i);
+            markSpace();
+            continue;
+        }
+        if (ch === "'") {
+            const next = readSingleQuoted(query, i, isEscapeStringPrefix(query, i));
+            emit(query.slice(i, next));
+            i = next;
+            continue;
+        }
+        if (ch === "\"") {
+            const next = readQuotedIdentifier(query, i);
+            emit(query.slice(i, next));
+            i = next;
+            continue;
+        }
+        if (ch === "$") {
+            const next = i === 0 || !isIdentifierContinuation(query[i - 1]) ? readDollarQuoted(query, i) : null;
+            if (next !== null) {
+                emit(query.slice(i, next));
+                i = next;
+                continue;
+            }
+        }
+        emit(ch);
+        i++;
+    }
+    return out;
+}

package/dist/src/query.d.ts

@@ -0,0 +1,62 @@
+import type { ExecuteResult } from "./runtime.js";
+import type { TypedSqlForRegistry } from "./typed.js";
+export type QueryExecutionMode = "many" | "one" | "optional" | "execute";
+export type QueryExecutionMetadata = {
+    queryId: string;
+    queryName?: string;
+};
+export declare const QUERY_EXECUTOR: unique symbol;
+export type QueryExecutorMethod = (mode: QueryExecutionMode, query: string, params: unknown[], metadata: QueryExecutionMetadata) => Promise<unknown>;
+type NamedQueryEntry = {
+    params: Record<string, unknown>;
+    row: unknown;
+};
+type PositionalQueryEntry = {
+    params: readonly unknown[];
+    row: unknown;
+};
+type QueryModeResult<Mode extends QueryExecutionMode, Row> = Mode extends "many" ? Row[] : Mode extends "one" ? Row : Mode extends "optional" ? Row | null : ExecuteResult;
+export type QueryDefinition<Query extends string = string, Mode extends QueryExecutionMode = QueryExecutionMode> = {
+    readonly query: Query;
+    readonly mode: Mode;
+    readonly queryId: string;
+    readonly queryName?: string;
+    run<Registry extends {
+        queries: Record<Query, NamedQueryEntry>;
+        fileQueries: object;
+    }>(executor: TypedSqlForRegistry<Registry>, params: RegistryParams<Query, Registry>): Promise<QueryResultFor<QueryDefinition<Query, Mode>, Registry>>;
+    run<Registry extends {
+        queries: Record<Query, PositionalQueryEntry>;
+        fileQueries: object;
+    }>(executor: TypedSqlForRegistry<Registry>, ...params: RegistryParams<Query, Registry> & readonly unknown[]): Promise<QueryResultFor<QueryDefinition<Query, Mode>, Registry>>;
+};
+type DefinitionQuery<Definition> = Definition extends QueryDefinition<infer Query, QueryExecutionMode> ? Query : never;
+type DefinitionMode<Definition> = Definition extends QueryDefinition<string, infer Mode> ? Mode : never;
+type RegistryQuery<Query extends string, Registry extends {
+    queries: object;
+}> = Registry["queries"][Query & keyof Registry["queries"]];
+type RegistryParams<Query extends string, Registry extends {
+    queries: object;
+}> = RegistryQuery<Query, Registry>["params" & keyof RegistryQuery<Query, Registry>];
+type RegistryRow<Query extends string, Registry extends {
+    queries: object;
+}> = RegistryQuery<Query, Registry>["row" & keyof RegistryQuery<Query, Registry>];
+export type QueryParamsFor<Definition, Registry extends {
+    queries: object;
+}> = RegistryParams<DefinitionQuery<Definition>, Registry>;
+export type QueryRowFor<Definition, Registry extends {
+    queries: object;
+}> = RegistryRow<DefinitionQuery<Definition>, Registry>;
+export type QueryResultFor<Definition, Registry extends {
+    queries: object;
+}> = QueryModeResult<DefinitionMode<Definition>, QueryRowFor<Definition, Registry>>;
+type DefineQueryMethod<Mode extends QueryExecutionMode> = {
+    <const Query extends string>(query: Query): QueryDefinition<Query, Mode>;
+    <const Query extends string>(name: string, query: Query): QueryDefinition<Query, Mode>;
+};
+export declare const defineQuery: DefineQueryMethod<"many"> & {
+    one: DefineQueryMethod<"one">;
+    optional: DefineQueryMethod<"optional">;
+    execute: DefineQueryMethod<"execute">;
+};
+export {};

package/dist/src/query.js

@@ -0,0 +1,38 @@
+import { queryId } from "./query-id.js";
+export const QUERY_EXECUTOR = Symbol.for("@onreza/sqlx-js.query-executor");
+function definitionMethod(mode) {
+    return ((nameOrQuery, maybeQuery) => {
+        const query = maybeQuery ?? nameOrQuery;
+        const name = maybeQuery === undefined ? undefined : nameOrQuery;
+        if (name !== undefined && name.trim() === "") {
+            throw new Error("sqlx-js.defineQuery: query name must not be empty");
+        }
+        const metadata = {
+            queryId: queryId(query),
+            ...(name ? { queryName: name } : {}),
+        };
+        return Object.freeze({
+            query,
+            mode,
+            queryId: metadata.queryId,
+            ...(name ? { queryName: name } : {}),
+            async run(executor, ...params) {
+                const execute = executor[QUERY_EXECUTOR];
+                if (execute)
+                    return await execute(mode, query, params, metadata);
+                if (mode === "one")
+                    return await executor.one(query, ...params);
+                if (mode === "optional")
+                    return await executor.optional(query, ...params);
+                if (mode === "execute")
+                    return await executor.execute(query, ...params);
+                return await executor(query, ...params);
+            },
+        });
+    });
+}
+export const defineQuery = Object.assign(definitionMethod("many"), {
+    one: definitionMethod("one"),
+    optional: definitionMethod("optional"),
+    execute: definitionMethod("execute"),
+});

package/dist/src/runtime.d.ts

@@ -1,5 +1,8 @@
 import { PgError } from "./pg/wire.js";
+import { QUERY_EXECUTOR, type QueryExecutorMethod } from "./query.js";
 export type OnQueryEvent = {
+    queryId: string;
+    queryName?: string;
     query: string;
     params: unknown[];
     durationMs: number;
@@ -21,6 +24,7 @@ export type RuntimeClient = {
     onQueryHookError?: OnQueryHookError;
     fileRoot?: string;
     reloadSqlFiles?: boolean;
+    sqlFiles?: Readonly<Record<string, string>>;
 };
 type AnyFn = (...args: unknown[]) => Promise<unknown[]>;
 type AnyOneFn = (...args: unknown[]) => Promise<unknown>;
@@ -28,7 +32,7 @@ type AnyOptionalFn = (...args: unknown[]) => Promise<unknown | null>;
 type AnyExecuteFn = (...args: unknown[]) => Promise<ExecuteResult>;
 type IdentifierFn = (...parts: string[]) => string;
 declare const PARAMETER_KIND: unique symbol;
-export type JsonParameter<T = JsonInputValue> = {
+export type JsonParameter<T = unknown> = {
     readonly [PARAMETER_KIND]: "json";
     readonly value: T;
 };
@@ -42,11 +46,17 @@ export type JsonInputObject = {
     readonly [key: string]: JsonInputValue | undefined;
 };
 export type JsonInputArray = readonly JsonInputValue[];
+type NonJsonValue = bigint | symbol | Date | Uint8Array | ((...args: never[]) => unknown);
+export type JsonCompatible<T> = T extends JsonPrimitive ? T : T extends NonJsonValue ? never : T extends readonly unknown[] ? T extends JsonInputArray ? T : {
+    readonly [K in keyof T]: JsonCompatible<T[K]>;
+} : T extends object ? Extract<keyof T, symbol> extends never ? T extends JsonInputObject ? T : {
+    readonly [K in keyof T]: undefined extends T[K] ? JsonCompatible<Exclude<T[K], undefined>> | undefined : JsonCompatible<T[K]>;
+} : never : never;
 export type ExecuteResult = {
     rowCount: number;
     command: string;
 };
-export declare function json<T extends JsonInputValue>(value: T): JsonParameter<T>;
+export declare function json<T>(value: T & JsonCompatible<T>): JsonParameter<T>;
 export declare function array<T>(value: readonly (T | null)[]): PgArrayParameter<T>;
 export declare function parameterKind(value: unknown): "json" | "array" | undefined;
 declare function renameRows(rows: unknown[]): unknown[];
@@ -63,6 +73,19 @@ export declare class TooManyRowsError extends Error {
     constructor(actual: number, expected?: "1" | "0 or 1");
 }
 export declare function toPgError(e: unknown): PgError | null;
+export declare const SQLSTATE: {
+    readonly notNullViolation: "23502";
+    readonly foreignKeyViolation: "23503";
+    readonly uniqueViolation: "23505";
+    readonly checkViolation: "23514";
+    readonly serializationFailure: "40001";
+    readonly deadlockDetected: "40P01";
+};
+export type KnownSqlState = (typeof SQLSTATE)[keyof typeof SQLSTATE];
+export declare function isPgError(error: unknown): error is PgError;
+export declare function isPgError<const Code extends string>(error: unknown, code: Code): error is PgError & {
+    readonly code: Code;
+};
 export declare const _internal: {
     renameRows: typeof renameRows;
     encodeParam: typeof encodeParam;
@@ -74,7 +97,7 @@ export declare const _internal: {
     parameterKind: typeof parameterKind;
     toPgError: typeof toPgError;
 };
-declare function loadSqlFile(path: string, fileRoot?: string, reload?: boolean): string;
+declare function loadSqlFile(path: string, fileRoot?: string, reload?: boolean, embedded?: Readonly<Record<string, string>>): string;
 export declare function clearSqlFileCache(): void;
 declare function clearIdentifierCache(): void;
 export declare function id(...parts: string[]): string;
@@ -91,6 +114,7 @@ type SqlCallable = AnyFn & {
     id: IdentifierFn;
     json: typeof json;
     array: typeof array;
+    [QUERY_EXECUTOR]: QueryExecutorMethod;
 };
 export type TransactionOptions = {
     isolation?: "read uncommitted" | "read committed" | "repeatable read" | "serializable";

package/dist/src/runtime.js

@@ -3,6 +3,8 @@ 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";
+import { queryId } from "./query-id.js";
+import { QUERY_EXECUTOR, } from "./query.js";
 const PARAMETER_KIND = Symbol("sqlx-js.parameter");
 export function json(value) {
     return { [PARAMETER_KIND]: "json", value };
@@ -176,7 +178,7 @@ export class TooManyRowsError extends Error {
 }
 // SQLSTATE is exactly five characters from [0-9A-Z]; lowercase or other shapes
 // are never valid, so transport codes like "EPIPE" must not match on shape alone.
-const SQLSTATE = /^[0-9A-Z]{5}$/;
+const SQLSTATE_PATTERN = /^[0-9A-Z]{5}$/;
 function firstString(...candidates) {
     for (const value of candidates) {
         if (typeof value === "string" && value.length > 0)
@@ -200,7 +202,7 @@ export function toPgError(e) {
     // and system errors (EPIPE, ECONNREFUSED, CONNECTION_ENDED) carry neither, so
     // they pass through untouched instead of masquerading as a PgError.
     const isDatabaseError = o.name === "PostgresError" ||
-        (code !== undefined && SQLSTATE.test(code) && severity !== undefined);
+        (code !== undefined && SQLSTATE_PATTERN.test(code) && severity !== undefined);
     if (!isDatabaseError)
         return null;
     const fields = {};
@@ -231,6 +233,17 @@ export function toPgError(e) {
         fields.s = schema;
     return new PgError(fields, { cause: e });
 }
+export const SQLSTATE = {
+    notNullViolation: "23502",
+    foreignKeyViolation: "23503",
+    uniqueViolation: "23505",
+    checkViolation: "23514",
+    serializationFailure: "40001",
+    deadlockDetected: "40P01",
+};
+export function isPgError(error, code) {
+    return error instanceof PgError && (code === undefined || error.code === code);
+}
 export const _internal = {
     renameRows,
     encodeParam,
@@ -242,7 +255,21 @@ export const _internal = {
     parameterKind,
     toPgError,
 };
-async function runRawQuery(client, query, params) {
+const runtimeQueryIds = new Map();
+const MAX_RUNTIME_QUERY_IDS = 1024;
+function observedMetadata(query, metadata) {
+    if (metadata)
+        return metadata;
+    let id = runtimeQueryIds.get(query);
+    if (!id) {
+        id = queryId(query);
+        if (runtimeQueryIds.size >= MAX_RUNTIME_QUERY_IDS)
+            runtimeQueryIds.clear();
+        runtimeQueryIds.set(query, id);
+    }
+    return { queryId: id };
+}
+async function runRawQuery(client, query, params, metadata) {
     const observedQuery = query;
     const observedParams = params;
     const bound = bindNamedParameters(rewriteNamedParameters(query), params);
@@ -260,10 +287,12 @@ async function runRawQuery(client, query, params) {
             throw toPgError(e) ?? e;
         }
     }
+    const observed = observedMetadata(observedQuery, metadata);
     const start = performance.now();
     try {
         const result = await client.query(query, encoded);
         notifyQuery(client, {
+            ...observed,
             query: observedQuery,
             params: observedParams,
             durationMs: performance.now() - start,
@@ -273,7 +302,7 @@ async function runRawQuery(client, query, params) {
     }
     catch (e) {
         const error = toPgError(e) ?? e;
-        notifyQuery(client, { query: observedQuery, params: observedParams, durationMs: performance.now() - start, error });
+        notifyQuery(client, { ...observed, query: observedQuery, params: observedParams, durationMs: performance.now() - start, error });
         throw error;
     }
 }
@@ -296,26 +325,26 @@ function notifyQueryHookError(client, error, event) {
     catch {
     }
 }
-async function runQuery(client, query, params) {
-    return renameRows(await runRawQuery(client, query, params));
+async function runQuery(client, query, params, metadata) {
+    return renameRows(await runRawQuery(client, query, params, metadata));
 }
-async function runExecute(client, query, params) {
-    const result = await runRawQuery(client, query, params);
+async function runExecute(client, query, params, metadata) {
+    const result = await runRawQuery(client, query, params, metadata);
     return {
         rowCount: result.count ?? result.length,
         command: result.command ?? "",
     };
 }
-async function runOne(client, query, params) {
-    const rows = await runQuery(client, query, params);
+async function runOne(client, query, params, metadata) {
+    const rows = await runQuery(client, query, params, metadata);
     if (rows.length === 1)
         return rows[0];
     if (rows.length === 0)
         throw new NoRowsError();
     throw new TooManyRowsError(rows.length, "1");
 }
-async function runOptional(client, query, params) {
-    const rows = await runQuery(client, query, params);
+async function runOptional(client, query, params, metadata) {
+    const rows = await runQuery(client, query, params, metadata);
     if (rows.length === 0)
         return null;
     if (rows.length === 1)
@@ -323,7 +352,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(), reload = false) {
+function loadSqlFile(path, fileRoot = process.env.SQLX_JS_FILE_ROOT ?? process.cwd(), reload = false, embedded) {
     const root = resolve(fileRoot);
     if (isAbsolute(path)) {
         throw new Error(`sqlx-js.sql.file: path must be relative to fileRoot: ${path}`);
@@ -333,6 +362,8 @@ function loadSqlFile(path, fileRoot = process.env.SQLX_JS_FILE_ROOT ?? process.c
     if (rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(rel)) {
         throw new Error(`sqlx-js.sql.file: path escapes fileRoot: ${path}`);
     }
+    if (embedded && Object.hasOwn(embedded, path))
+        return embedded[path];
     try {
         const cached = sqlFileCache.get(full);
         if (cached && !reload)
@@ -464,21 +495,30 @@ export function id(...parts) {
     }
     return parts.map(quoteIdentifier).join(".");
 }
+function executeDefinedQuery(client, mode, query, params, metadata) {
+    if (mode === "one")
+        return runOne(client, query, params, metadata);
+    if (mode === "optional")
+        return runOptional(client, query, params, metadata);
+    if (mode === "execute")
+        return runExecute(client, query, params, metadata);
+    return runQuery(client, query, params, metadata);
+}
 function makeBoundCallable(client) {
     const fn = (async (query, ...params) => {
         return runQuery(client, query, params);
     });
     const file = (async (path, ...params) => {
-        return runQuery(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
+        return runQuery(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles, client.sqlFiles), params);
     });
     file.one = (async (path, ...params) => {
-        return runOne(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
+        return runOne(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles, client.sqlFiles), params);
     });
     file.optional = (async (path, ...params) => {
-        return runOptional(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
+        return runOptional(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles, client.sqlFiles), params);
     });
     file.execute = (async (path, ...params) => {
-        return runExecute(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
+        return runExecute(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles, client.sqlFiles), params);
     });
     fn.file = file;
     fn.one = (async (query, ...params) => {
@@ -493,6 +533,9 @@ function makeBoundCallable(client) {
     fn.id = id;
     fn.json = json;
     fn.array = array;
+    fn[QUERY_EXECUTOR] = (mode, query, params, metadata) => {
+        return executeDefinedQuery(client, mode, query, params, metadata);
+    };
     return fn;
 }
 function buildSetTransaction(opts) {
@@ -513,19 +556,19 @@ export function createSqlRuntime(getClient) {
     });
     const rootFile = (async (path, ...params) => {
         const client = getClient();
-        return runQuery(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
+        return runQuery(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles, client.sqlFiles), params);
     });
     rootFile.one = (async (path, ...params) => {
         const client = getClient();
-        return runOne(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
+        return runOne(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles, client.sqlFiles), params);
     });
     rootFile.optional = (async (path, ...params) => {
         const client = getClient();
-        return runOptional(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
+        return runOptional(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles, client.sqlFiles), params);
     });
     rootFile.execute = (async (path, ...params) => {
         const client = getClient();
-        return runExecute(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles), params);
+        return runExecute(client, loadSqlFile(path, client.fileRoot, client.reloadSqlFiles, client.sqlFiles), params);
     });
     root.file = rootFile;
     root.one = (async (query, ...params) => {
@@ -540,6 +583,9 @@ export function createSqlRuntime(getClient) {
     root.id = id;
     root.json = json;
     root.array = array;
+    root[QUERY_EXECUTOR] = (mode, query, params, metadata) => {
+        return executeDefinedQuery(getClient(), mode, query, params, metadata);
+    };
     root.transaction = (async (fnOrOpts, maybeFn) => {
         const c = getClient();
         let opts = {};

package/dist/src/scan/scanner.d.ts

@@ -6,6 +6,8 @@ export type QueryCallSite = {
     query: string;
     paramCount: number;
     kind: "inline" | "file";
+    cardinality?: "many" | "one" | "optional" | "execute";
+    queryName?: string;
     sqlFilePath?: string;
 };
 export declare class ScanError extends Error {