@onreza/sqlx-js 0.7.0 → 0.9.0

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

@@ -0,0 +1,38 @@
+import type { QueryExecutionMode } from "../query.js";
+export type QueriesPhase = "config" | "scan" | "cache" | "embed";
+export declare class QueriesError extends Error {
+    readonly phase: QueriesPhase;
+    readonly file?: string | undefined;
+    readonly line?: number | undefined;
+    readonly column?: number | undefined;
+    constructor(phase: QueriesPhase, message: string, file?: string | undefined, line?: number | undefined, column?: number | undefined, options?: {
+        cause?: unknown;
+    });
+}
+export type QueryInventoryItem = {
+    queryId: string;
+    queryNames: string[];
+    query: string;
+    cardinalities: QueryExecutionMode[];
+    sqlFilePaths: string[];
+    callSites: {
+        file: string;
+        line: number;
+        column: number;
+    }[];
+    cacheStatus: "current" | "stale" | "missing";
+};
+export type QueryInventory = {
+    formatVersion: 1;
+    ok: true;
+    queries: QueryInventoryItem[];
+    orphanedCacheIds: string[];
+};
+export declare function buildQueryInventory(root: string, cacheDir: string): Promise<QueryInventory>;
+export declare function emitEmbeddedSqlModule(path: string, inventory: QueryInventory): void;
+export declare function runQueries(options: {
+    root: string;
+    cacheDir: string;
+    json?: boolean;
+    embedPath?: string;
+}): Promise<void>;

package/dist/src/commands/queries.js

@@ -0,0 +1,143 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, relative } from "node:path";
+import { Cache, CacheManifestStaleError, readCacheManifest } from "../cache.js";
+import { loadConfig, prepareConfigHash } from "../config.js";
+import { queryId } from "../query-id.js";
+import { ScanError, scanProject } from "../scan/scanner.js";
+export class QueriesError extends Error {
+    phase;
+    file;
+    line;
+    column;
+    constructor(phase, message, file, line, column, options) {
+        super(message, options);
+        this.phase = phase;
+        this.file = file;
+        this.line = line;
+        this.column = column;
+        this.name = "QueriesError";
+    }
+}
+function queriesError(phase, error) {
+    if (error instanceof QueriesError)
+        return error;
+    if (error instanceof ScanError) {
+        return new QueriesError(phase, error.message, error.file, error.line, error.column, { cause: error });
+    }
+    return new QueriesError(phase, error instanceof Error ? error.message : String(error), undefined, undefined, undefined, { cause: error });
+}
+export async function buildQueryInventory(root, cacheDir) {
+    let config;
+    try {
+        config = await loadConfig(root);
+    }
+    catch (error) {
+        throw queriesError("config", error);
+    }
+    let sites;
+    try {
+        sites = scanProject(root, config.scan);
+    }
+    catch (error) {
+        throw queriesError("scan", error);
+    }
+    const cache = new Cache(cacheDir);
+    let manifestCurrent = false;
+    try {
+        const manifest = readCacheManifest(cacheDir);
+        manifestCurrent = manifest?.configHash === prepareConfigHash(config);
+    }
+    catch (error) {
+        if (!(error instanceof CacheManifestStaleError)) {
+            throw queriesError("cache", error);
+        }
+        manifestCurrent = false;
+    }
+    let cacheIds;
+    try {
+        cacheIds = cache.list().map(({ fp }) => fp);
+    }
+    catch (error) {
+        throw queriesError("cache", error);
+    }
+    const cached = new Set(cacheIds);
+    const grouped = new Map();
+    for (const site of sites) {
+        const id = queryId(site.query);
+        const group = grouped.get(id) ?? [];
+        group.push(site);
+        grouped.set(id, group);
+    }
+    const queries = [...grouped.entries()].map(([id, group]) => {
+        return {
+            queryId: id,
+            queryNames: [...new Set(group.flatMap((site) => site.queryName ? [site.queryName] : []))].sort(),
+            query: group[0].query,
+            cardinalities: [...new Set(group.map((site) => site.cardinality ?? "many"))].sort(),
+            sqlFilePaths: [...new Set(group.flatMap((site) => site.sqlFilePath ? [site.sqlFilePath] : []))].sort(),
+            callSites: group
+                .map(({ file, line, column }) => ({ file, line, column }))
+                .sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column),
+            cacheStatus: !cached.has(id) ? "missing" : manifestCurrent ? "current" : "stale",
+        };
+    }).sort((a, b) => a.queryId.localeCompare(b.queryId));
+    const active = new Set(queries.map((query) => query.queryId));
+    const orphanedCacheIds = cacheIds.filter((fp) => !active.has(fp)).sort();
+    return { formatVersion: 1, ok: true, queries, orphanedCacheIds };
+}
+export function emitEmbeddedSqlModule(path, inventory) {
+    const sqlFiles = Object.fromEntries(inventory.queries
+        .flatMap((query) => query.sqlFilePaths.map((file) => [file, query.query]))
+        .sort(([a], [b]) => a.localeCompare(b)));
+    const content = [
+        "// AUTO-GENERATED by sqlx-js. Do not edit.",
+        "// Run `sqlx-js queries --embed <path>` to regenerate.",
+        "",
+        `export const sqlxJsEmbeddedSql = ${JSON.stringify(sqlFiles, null, 2)} as const;`,
+        "",
+    ].join("\n");
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, content);
+    try {
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw error;
+    }
+}
+export async function runQueries(options) {
+    const inventory = await buildQueryInventory(options.root, options.cacheDir);
+    if (options.embedPath) {
+        try {
+            emitEmbeddedSqlModule(options.embedPath, inventory);
+        }
+        catch (error) {
+            throw queriesError("embed", error);
+        }
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            ...inventory,
+            ...(options.embedPath ? { embeddedModule: relative(options.root, options.embedPath).replace(/\\/g, "/") } : {}),
+        }, null, 2));
+        return;
+    }
+    for (const query of inventory.queries) {
+        const names = query.queryNames.length > 0 ? ` ${query.queryNames.join(",")}` : "";
+        console.log(`${query.queryId}${names} ${query.cardinalities.join(",")} ${query.cacheStatus}`);
+        for (const site of query.callSites)
+            console.log(`  ${site.file}:${site.line}:${site.column}`);
+    }
+    if (inventory.queries.length === 0)
+        console.log("no sqlx-js queries found");
+    if (inventory.orphanedCacheIds.length > 0)
+        console.log(`orphaned cache: ${inventory.orphanedCacheIds.join(", ")}`);
+    if (options.embedPath)
+        console.log(`embedded SQL module: ${relative(options.root, options.embedPath).replace(/\\/g, "/")}`);
+}

package/dist/src/config.d.ts

@@ -5,7 +5,11 @@ export type ScanConfig = {
 };
 export type SqlxJsConfig = {
     jsonbTypes?: Record<string, string>;
+    columnTypes?: Record<string, string>;
     customTypes?: Record<string, string>;
+    functionCatalog?: false | {
+        includeExtensionOwned?: boolean;
+    };
     scan?: ScanConfig;
     schema?: {
         provider?: "builtin" | "pgschema";
@@ -32,3 +36,4 @@ export declare function runtimeVersion(): {
 export declare function nativeTypeScriptEnabled(): boolean | string;
 export declare function envFilePath(root: string): string;
 export declare function lookupJsonbType(cfg: SqlxJsConfig, schema: string, table: string, column: string): string | undefined;
+export declare function lookupColumnType(cfg: SqlxJsConfig, schema: string, table: string, column: string): string | undefined;

package/dist/src/config.js

@@ -65,8 +65,27 @@ function validateConfig(value, path) {
     const config = value;
     if (config.jsonbTypes !== undefined)
         validateStringRecord(config.jsonbTypes, "jsonbTypes", path);
+    if (config.columnTypes !== undefined)
+        validateStringRecord(config.columnTypes, "columnTypes", path);
     if (config.customTypes !== undefined)
         validateStringRecord(config.customTypes, "customTypes", path);
+    if (config.jsonbTypes && config.columnTypes) {
+        const jsonKeys = Object.keys(config.jsonbTypes);
+        const columnKeys = Object.keys(config.columnTypes);
+        const conflicts = jsonKeys.filter((jsonKey) => columnKeys.some((columnKey) => jsonKey === columnKey || jsonKey.endsWith(`.${columnKey}`) || columnKey.endsWith(`.${jsonKey}`)));
+        if (conflicts.length > 0) {
+            throw new Error(`sqlx-js: ${path} maps the same column in jsonbTypes and columnTypes: ${conflicts.join(", ")}`);
+        }
+    }
+    if (config.functionCatalog !== undefined && config.functionCatalog !== false) {
+        if (!config.functionCatalog || typeof config.functionCatalog !== "object" || Array.isArray(config.functionCatalog)) {
+            throw new Error(`sqlx-js: ${path} functionCatalog must be false or an object`);
+        }
+        const functionCatalog = config.functionCatalog;
+        if (functionCatalog.includeExtensionOwned !== undefined && typeof functionCatalog.includeExtensionOwned !== "boolean") {
+            throw new Error(`sqlx-js: ${path} functionCatalog.includeExtensionOwned must be a boolean`);
+        }
+    }
     if (config.scan !== undefined) {
         if (!config.scan || typeof config.scan !== "object" || Array.isArray(config.scan)) {
             throw new Error(`sqlx-js: ${path} scan must be an object`);
@@ -100,7 +119,11 @@ function validateConfig(value, path) {
 export function prepareConfigHash(cfg) {
     const value = stableValue({
         jsonbTypes: cfg.jsonbTypes ?? {},
+        columnTypes: cfg.columnTypes ?? {},
         customTypes: cfg.customTypes ?? {},
+        functionCatalog: cfg.functionCatalog === false
+            ? false
+            : { includeExtensionOwned: cfg.functionCatalog?.includeExtensionOwned === true },
     });
     return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
 }
@@ -159,3 +182,9 @@ export function lookupJsonbType(cfg, schema, table, column) {
     return (types[`${schema}.${table}.${column}`] ??
         types[`${table}.${column}`]);
 }
+export function lookupColumnType(cfg, schema, table, column) {
+    const types = cfg.columnTypes;
+    if (!types)
+        return undefined;
+    return types[`${schema}.${table}.${column}`] ?? types[`${table}.${column}`];
+}

package/dist/src/index.d.ts

@@ -1,5 +1,6 @@
 import * as rt from "./postgres-runtime.js";
 import type { Typed as TypedFor, TypedFile as TypedFileFor, TypedSql as TypedSqlFor } from "./typed.js";
+import type { QueryParamsFor, QueryResultFor, QueryRowFor } from "./query.js";
 export interface KnownQueries {
 }
 export interface KnownFileQueries {
@@ -22,9 +23,9 @@ export { defineConfig } from "./config.js";
 export type { ScanConfig, SqlxJsConfig } from "./config.js";
 export type { SslMode, ConnConfig } from "./pg/wire.js";
 export { PgError, ConnectionLostError } from "./pg/wire.js";
-export { NoRowsError, TooManyRowsError } from "./runtime.js";
+export { NoRowsError, TooManyRowsError, SQLSTATE, isPgError } from "./runtime.js";
 export type { TransactionOptions, MigrateOptions, OnQueryEvent, OnQueryHook, OnQueryHookError } from "./runtime.js";
-export type { ExecuteResult, JsonParameter, PgArrayParameter } from "./runtime.js";
+export type { ExecuteResult, JsonParameter, PgArrayParameter, JsonCompatible, KnownSqlState } from "./runtime.js";
 export type { PostgresClient, PostgresOptions, CreateClientOptions } from "./postgres-runtime.js";
 export type TypedFile = TypedFileFor<KnownFileQueries>;
 export type TypedSql = TypedSqlFor<KnownQueries, KnownFileQueries>;
@@ -44,6 +45,13 @@ export type SqlClient<Registry extends QueryRegistry = DefaultQueryRegistry> = {
     client: import("./postgres-runtime.js").PostgresClient;
     close: () => Promise<void>;
 };
+export type SqlExecutor<Registry extends QueryRegistry = DefaultQueryRegistry> = TypedSqlFor<Registry["queries"], Registry["fileQueries"]>;
+export type QueryParams<Definition, Registry extends QueryRegistry = DefaultQueryRegistry> = QueryParamsFor<Definition, Registry>;
+export type QueryRow<Definition, Registry extends QueryRegistry = DefaultQueryRegistry> = QueryRowFor<Definition, Registry>;
+export type QueryResult<Definition, Registry extends QueryRegistry = DefaultQueryRegistry> = QueryResultFor<Definition, Registry>;
+export type { QueryDefinition, QueryExecutionMode } from "./query.js";
+export { defineQuery } from "./query.js";
+export { queryId } from "./query-id.js";
 export declare const sql: Typed;
 export type Unsafe = (query: string, ...params: unknown[]) => Promise<Record<string, unknown>[]>;
 export declare const unsafe: Unsafe;

package/dist/src/index.js

@@ -1,7 +1,9 @@
 import * as rt from "./postgres-runtime.js";
 export { defineConfig } from "./config.js";
 export { PgError, ConnectionLostError } from "./pg/wire.js";
-export { NoRowsError, TooManyRowsError } from "./runtime.js";
+export { NoRowsError, TooManyRowsError, SQLSTATE, isPgError } from "./runtime.js";
+export { defineQuery } from "./query.js";
+export { queryId } from "./query-id.js";
 export const sql = rt.sql;
 export const unsafe = rt.unsafe;
 export const getClient = rt.getClient;

package/dist/src/pg/functions.d.ts

@@ -1,4 +1,6 @@
 import type { FunctionEntry } from "../function-cache.js";
 import { type PgClient } from "./wire.js";
 import { SchemaCache } from "./schema.js";
-export declare function introspectFunctions(client: PgClient, schema: SchemaCache): Promise<FunctionEntry[]>;
+export declare function introspectFunctions(client: PgClient, schema: SchemaCache, options?: {
+    includeExtensionOwned?: boolean;
+}): Promise<FunctionEntry[]>;

package/dist/src/pg/functions.js

@@ -2,8 +2,8 @@ import { decodeText } from "./wire.js";
 const JSON_OIDS = new Set([114, 3802]);
 const JSON_ARRAY_OIDS = new Set([199, 3807]);
 const JSON_INPUT = 'import("@onreza/sqlx-js").JsonInput';
-export async function introspectFunctions(client, schema) {
-    const rows = await loadFunctionRows(client);
+export async function introspectFunctions(client, schema, options = {}) {
+    const rows = await loadFunctionRows(client, options.includeExtensionOwned === true);
     const typeOids = new Set();
     for (const row of rows) {
         typeOids.add(row.returnOid);
@@ -15,7 +15,7 @@ export async function introspectFunctions(client, schema) {
     await schema.loadCustomTypes([...typeOids]);
     return rows.map((row) => toEntry(row, schema)).sort((a, b) => a.signature.localeCompare(b.signature));
 }
-async function loadFunctionRows(client) {
+async function loadFunctionRows(client, includeExtensionOwned) {
     const result = await client.simpleQueryAll(`
     SELECT
       n.nspname,
@@ -36,6 +36,14 @@ async function loadFunctionRows(client) {
     FROM pg_proc p
     JOIN pg_namespace n ON n.oid = p.pronamespace
     WHERE ${userSchemaFilter("n")}
+      ${includeExtensionOwned ? "" : `AND NOT EXISTS (
+        SELECT 1
+        FROM pg_depend d
+        WHERE d.classid = 'pg_proc'::regclass
+          AND d.objid = p.oid
+          AND d.refclassid = 'pg_extension'::regclass
+          AND d.deptype = 'e'
+      )`}
     ORDER BY n.nspname, p.proname, pg_get_function_identity_arguments(p.oid)
   `);
     return result.rows.map((row) => ({

package/dist/src/postgres-runtime.d.ts

@@ -10,6 +10,7 @@ export type CreateClientOptions = PostgresOptions & {
     statementTimeoutMs?: number;
     fileRoot?: string;
     reloadSqlFiles?: boolean;
+    sqlFiles?: Readonly<Record<string, string>>;
 };
 export declare function createClient(url?: string | undefined, options?: CreateClientOptions): PostgresClient;
 export declare function getClient(): PostgresClient;
@@ -19,6 +20,7 @@ export declare function setClient(client: PostgresClient, options?: {
     prepare?: boolean;
     fileRoot?: string;
     reloadSqlFiles?: boolean;
+    sqlFiles?: Readonly<Record<string, string>>;
 }): void;
 export declare function close(): Promise<void>;
 export declare function createSqlClient(url?: string | undefined, options?: CreateClientOptions): {

package/dist/src/postgres-runtime.js

@@ -13,13 +13,15 @@ class PostgresRuntimeClient {
     prepare;
     fileRoot;
     reloadSqlFiles;
-    constructor(client, onQuery, onQueryHookError, prepare = true, fileRoot = resolvedFileRoot(), reloadSqlFiles = false) {
+    sqlFiles;
+    constructor(client, onQuery, onQueryHookError, prepare = true, fileRoot = resolvedFileRoot(), reloadSqlFiles = false, sqlFiles) {
         this.client = client;
         this.onQuery = onQuery;
         this.onQueryHookError = onQueryHookError;
         this.prepare = prepare;
         this.fileRoot = fileRoot;
         this.reloadSqlFiles = reloadSqlFiles;
+        this.sqlFiles = sqlFiles;
     }
     async query(query, params) {
         return await this.client.unsafe(query, params, { prepare: this.prepare });
@@ -43,7 +45,7 @@ class PostgresRuntimeClient {
         if (!("begin" in this.client))
             throw new Error("sqlx-js.transaction: nested transactions are not supported");
         return await this.client.begin(async (tx) => {
-            return await fn(new PostgresRuntimeClient(tx, this.onQuery, this.onQueryHookError, this.prepare, this.fileRoot, this.reloadSqlFiles));
+            return await fn(new PostgresRuntimeClient(tx, this.onQuery, this.onQueryHookError, this.prepare, this.fileRoot, this.reloadSqlFiles, this.sqlFiles));
         });
     }
     async close() {
@@ -162,7 +164,7 @@ function installJsonArrayCodecs(client) {
 export function createClient(url = process.env.DATABASE_URL, options = {}) {
     if (!url)
         throw new Error("sqlx-js: DATABASE_URL is not set");
-    const { onQuery, onQueryHookError, statementTimeoutMs, fileRoot, reloadSqlFiles, ...pgOptions } = options;
+    const { onQuery, onQueryHookError, statementTimeoutMs, fileRoot, reloadSqlFiles, sqlFiles, ...pgOptions } = options;
     const connection = statementTimeoutMs !== undefined
         ? { ...(pgOptions.connection ?? {}), statement_timeout: statementTimeoutMs }
         : pgOptions.connection;
@@ -177,13 +179,14 @@ export function createClient(url = process.env.DATABASE_URL, options = {}) {
         prepare: pgOptions.prepare ?? true,
         fileRoot: resolvedFileRoot(fileRoot),
         reloadSqlFiles: reloadSqlFiles ?? false,
+        sqlFiles,
     };
     return client;
 }
 function createDefaultClient() {
     const client = createClient();
     const attached = client[HOOKS];
-    return new PostgresRuntimeClient(client, attached.onQuery, attached.onQueryHookError, attached.prepare, attached.fileRoot, attached.reloadSqlFiles);
+    return new PostgresRuntimeClient(client, attached.onQuery, attached.onQueryHookError, attached.prepare, attached.fileRoot, attached.reloadSqlFiles, attached.sqlFiles);
 }
 function getRuntimeClient() {
     defaultClient ??= createDefaultClient();
@@ -195,7 +198,7 @@ export function getClient() {
 export function setClient(client, options) {
     installJsonArrayCodecs(client);
     const attached = client[HOOKS];
-    defaultClient = new PostgresRuntimeClient(client, options?.onQuery ?? attached?.onQuery, options?.onQueryHookError ?? attached?.onQueryHookError, options?.prepare ?? attached?.prepare ?? client.options?.prepare ?? true, resolvedFileRoot(options?.fileRoot ?? attached?.fileRoot), options?.reloadSqlFiles ?? attached?.reloadSqlFiles ?? false);
+    defaultClient = new PostgresRuntimeClient(client, options?.onQuery ?? attached?.onQuery, options?.onQueryHookError ?? attached?.onQueryHookError, options?.prepare ?? attached?.prepare ?? client.options?.prepare ?? true, resolvedFileRoot(options?.fileRoot ?? attached?.fileRoot), options?.reloadSqlFiles ?? attached?.reloadSqlFiles ?? false, options?.sqlFiles ?? attached?.sqlFiles);
 }
 export async function close() {
     if (defaultClient) {
@@ -206,7 +209,7 @@ export async function close() {
 export function createSqlClient(url = process.env.DATABASE_URL, options = {}) {
     const client = createClient(url, options);
     const attached = client[HOOKS];
-    const runtimeClient = new PostgresRuntimeClient(client, attached.onQuery, attached.onQueryHookError, attached.prepare, attached.fileRoot, attached.reloadSqlFiles);
+    const runtimeClient = new PostgresRuntimeClient(client, attached.onQuery, attached.onQueryHookError, attached.prepare, attached.fileRoot, attached.reloadSqlFiles, attached.sqlFiles);
     const runtime = createSqlRuntime(() => runtimeClient);
     return {
         ...runtime,

package/dist/src/query-id.d.ts

@@ -0,0 +1 @@
+export declare function queryId(query: string): string;

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,53 @@
+import type { ExecuteResult } from "./runtime.js";
+import type { TypedSql } 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 QueryEntry = {
+    params: unknown;
+    row: unknown;
+};
+type ParamsOf<T> = T extends {
+    params: infer P;
+} ? P extends readonly unknown[] ? P : [P] : never[];
+type RowOf<T> = T extends {
+    row: infer R;
+} ? R : never;
+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<Queries extends Record<Query, QueryEntry>, FileQueries>(executor: TypedSql<Queries, FileQueries>, ...params: ParamsOf<Queries[Query]>): Promise<QueryModeResult<Mode, RowOf<Queries[Query]>>>;
+};
+type DefinitionQuery<Definition> = Definition extends QueryDefinition<infer Query, QueryExecutionMode> ? Query : never;
+type DefinitionMode<Definition> = Definition extends QueryDefinition<string, infer Mode> ? Mode : never;
+type RegistryQuery<Definition, Registry extends {
+    queries: object;
+}> = DefinitionQuery<Definition> extends keyof Registry["queries"] ? Registry["queries"][DefinitionQuery<Definition>] : never;
+export type QueryParamsFor<Definition, Registry extends {
+    queries: object;
+}> = RegistryQuery<Definition, Registry> extends {
+    params: infer Params;
+} ? Params : never;
+export type QueryRowFor<Definition, Registry extends {
+    queries: object;
+}> = RowOf<RegistryQuery<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";