@onreza/sqlx-js 0.2.0 → 0.4.0

package/dist/src/codegen.js

@@ -16,36 +16,38 @@ function entrySignature(e) {
     });
     return { params, row: `{ ${cols.join("; ")} }` };
 }
-export function emitDts(outPath, entries) {
+export function emitDts(outPath, entries, functions = []) {
     mkdirSync(dirname(outPath), { recursive: true });
     const lines = [];
     lines.push("// AUTO-GENERATED by sqlx-js. Do not edit.");
     lines.push("// Run `sqlx-js prepare` to regenerate.");
     lines.push("");
-    emitModule(lines, "@onreza/sqlx-js", entries);
+    emitModule(lines, "@onreza/sqlx-js", entries, functions);
     lines.push("");
     lines.push("export {};");
     writeFileSync(outPath, lines.join("\n") + "\n");
 }
-function emitModule(lines, moduleName, entries) {
+function emitModule(lines, moduleName, entries, functions) {
     lines.push(`declare module ${JSON.stringify(moduleName)} {`);
     lines.push("  interface KnownQueries {");
     const inlineSeen = new Set();
-    const inlineEntries = entries.filter((e) => {
-        if (e.hasInline === true)
-            return true;
-        if (e.hasInline === false)
-            return false;
-        return !e.filePaths || e.filePaths.length === 0;
-    });
-    for (const e of inlineEntries.slice().sort((a, b) => a.query.localeCompare(b.query))) {
-        if (inlineSeen.has(e.query))
+    const inlinePairs = [];
+    for (const e of entries) {
+        const emitInline = e.hasInline === true || (e.hasInline !== false && (!e.filePaths || e.filePaths.length === 0));
+        if (!emitInline)
+            continue;
+        const queries = e.inlineQueries && e.inlineQueries.length > 0 ? e.inlineQueries : [e.query];
+        for (const query of queries)
+            inlinePairs.push({ query, entry: e });
+    }
+    for (const { query, entry } of inlinePairs.slice().sort((a, b) => a.query.localeCompare(b.query))) {
+        if (inlineSeen.has(query))
             continue;
-        inlineSeen.add(e.query);
-        const { params, row } = entrySignature(e);
-        if (e.degraded)
-            lines.push(`    /** Nullability inference degraded: ${e.degraded.reason}. All result columns conservatively typed as nullable. */`);
-        lines.push(`    ${JSON.stringify(e.query)}: { params: ${params}; row: ${row} };`);
+        inlineSeen.add(query);
+        const { params, row } = entrySignature(entry);
+        if (entry.degraded)
+            lines.push(`    /** Nullability inference degraded: ${entry.degraded.reason}. All result columns conservatively typed as nullable. */`);
+        lines.push(`    ${JSON.stringify(query)}: { params: ${params}; row: ${row} };`);
     }
     lines.push("  }");
     lines.push("");
@@ -68,5 +70,22 @@ function emitModule(lines, moduleName, entries) {
         lines.push(`    ${JSON.stringify(path)}: { params: ${params}; row: ${row} };`);
     }
     lines.push("  }");
+    lines.push("");
+    lines.push("  interface KnownFunctions {");
+    const functionSeen = new Set();
+    for (const fn of functions.slice().sort((a, b) => a.signature.localeCompare(b.signature))) {
+        if (functionSeen.has(fn.signature))
+            continue;
+        functionSeen.add(fn.signature);
+        const params = inputParams(fn);
+        lines.push(`    ${JSON.stringify(fn.signature)}: { kind: ${JSON.stringify(fn.kind)}; params: ${params}; returns: ${fn.returns}; returnsSet: ${fn.returnsSet} };`);
+    }
+    lines.push("  }");
     lines.push("}");
 }
+function inputParams(fn) {
+    const params = fn.params
+        .filter((p) => p.mode === "in" || p.mode === "inout" || p.mode === "variadic")
+        .map((p) => p.tsType);
+    return params.length === 0 ? "[]" : `[${params.join(", ")}]`;
+}

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

@@ -1,5 +1,6 @@
 export type InitOptions = {
     root: string;
+    schemaProvider?: "builtin" | "pgschema";
     log?: (msg: string) => void;
 };
 export declare function runInit(opts: InitOptions): void;

package/dist/src/commands/init.js

@@ -11,6 +11,20 @@ const config: SqlxJsConfig = {
   customTypes: {},
 };
 
+export default config;
+`;
+const PGSCHEMA_CONFIG_TEMPLATE = `import type { SqlxJsConfig } from "@onreza/sqlx-js";
+
+const config: SqlxJsConfig = {
+  schema: {
+    provider: "pgschema",
+    file: "schema.sql",
+    schemas: ["public"],
+  },
+  jsonbTypes: {},
+  customTypes: {},
+};
+
 export default config;
 `;
 const ENV_TEMPLATE = `# Connection string used by sqlx-js prepare/migrate and the runtime.
@@ -18,6 +32,11 @@ DATABASE_URL=postgres://user:password@localhost:5432/your_db
 # Managed Postgres with TLS:
 # DATABASE_URL=postgres://user:password@db.example.com:5432/your_db?sslmode=verify-full
 `;
+const PGSCHEMA_TEMPLATE = `-- Desired PostgreSQL schema managed by pgschema.
+-- Edit this file, then run:
+--   sqlx-js db plan -- --output-json plan.json
+--   sqlx-js db apply -- --auto-approve
+`;
 export function runInit(opts) {
     const log = opts.log ?? console.log;
     const created = [];
@@ -41,8 +60,12 @@ export function runInit(opts) {
         mkdirSync(full, { recursive: true });
         created.push(`${rel}/`);
     };
-    ensureFile("sqlx-js.config.ts", CONFIG_TEMPLATE);
-    ensureDir("migrations");
+    const schemaProvider = opts.schemaProvider ?? "builtin";
+    ensureFile("sqlx-js.config.ts", schemaProvider === "pgschema" ? PGSCHEMA_CONFIG_TEMPLATE : CONFIG_TEMPLATE);
+    if (schemaProvider === "pgschema")
+        ensureFile("schema.sql", PGSCHEMA_TEMPLATE);
+    else
+        ensureDir("migrations");
     ensureFile(".env.example", ENV_TEMPLATE);
     for (const f of created)
         log(`created ${f}`);
@@ -51,7 +74,15 @@ export function runInit(opts) {
     log("");
     log("Next steps:");
     log("  1. Set DATABASE_URL (see .env.example).");
-    log("  2. Add a migration:  sqlx-js migrate add init");
-    log("  3. Make sure tsconfig.json \"include\" covers sqlx-js-env.d.ts.");
-    log("  4. Develop locally:  sqlx-js migrate dev");
+    if (schemaProvider === "pgschema") {
+        log("  2. Install managed pgschema:  sqlx-js db install");
+        log("  3. Verify it:  sqlx-js db check");
+        log("  4. Edit schema.sql, then review:  sqlx-js db plan");
+        log("  5. After applying schema changes, run:  sqlx-js prepare");
+    }
+    else {
+        log("  2. Add a migration:  sqlx-js migrate add init");
+        log("  3. Make sure tsconfig.json \"include\" covers sqlx-js-env.d.ts.");
+        log("  4. Develop locally:  sqlx-js migrate dev");
+    }
 }

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

@@ -0,0 +1,25 @@
+import type { SqlxJsConfig } from "../config.js";
+export type PgschemaSubcommand = "check" | "plan" | "apply";
+export declare const PGSCHEMA_VERSION = "1.12.0";
+export type PgschemaAsset = {
+    key: string;
+    name: string;
+    sha256: string;
+};
+export type PgschemaCommandOptions = {
+    root: string;
+    databaseUrl: string;
+    config: SqlxJsConfig;
+    subcommand: PgschemaSubcommand;
+    passthrough?: string[];
+};
+export type PgschemaInstallOptions = {
+    root: string;
+    asset?: PgschemaAsset;
+    baseUrl?: string;
+    log?: (msg: string) => void;
+};
+export declare function resolvePgschemaAsset(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): PgschemaAsset;
+export declare function managedPgschemaPath(root: string, asset?: PgschemaAsset): string;
+export declare function runPgschemaInstall(opts: PgschemaInstallOptions): Promise<void>;
+export declare function runPgschemaCommand(opts: PgschemaCommandOptions): void;

package/dist/src/commands/pgschema.js

@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseDatabaseUrl } from "../pg/wire.js";
+export const PGSCHEMA_VERSION = "1.12.0";
+const PGSCHEMA_BASE_URL = `https://github.com/pgplex/pgschema/releases/download/v${PGSCHEMA_VERSION}`;
+const WINDOWS_UNSUPPORTED = "sqlx-js db: pgschema is not supported on Windows. Run sqlx-js under WSL/Linux/macOS or use the built-in sqlx-js migrate workflow.";
+const PGSCHEMA_ASSETS = {
+    "darwin:x64": {
+        key: "darwin-amd64",
+        name: `pgschema-${PGSCHEMA_VERSION}-darwin-amd64`,
+        sha256: "c64b2ac24c4246344908910e892c4123be282bbb449f0b535079ff41d0f47c8f",
+    },
+    "darwin:arm64": {
+        key: "darwin-arm64",
+        name: `pgschema-${PGSCHEMA_VERSION}-darwin-arm64`,
+        sha256: "f01ea488f21700752d5747bc013c406daa583a68b631739f33af430d5d3ec449",
+    },
+    "linux:x64": {
+        key: "linux-amd64",
+        name: `pgschema-${PGSCHEMA_VERSION}-linux-amd64`,
+        sha256: "12610adf748b0dafe4e488ee7e9e68e6ffbef1f4e0f038dda36cf0138eede598",
+    },
+    "linux:arm64": {
+        key: "linux-arm64",
+        name: `pgschema-${PGSCHEMA_VERSION}-linux-arm64`,
+        sha256: "58ec57023954a0239cf9d607c4e5432da6dd0b279399d1c318204120619a221d",
+    },
+};
+export function resolvePgschemaAsset(platform = process.platform, arch = process.arch) {
+    if (platform === "win32")
+        throw new Error(WINDOWS_UNSUPPORTED);
+    const asset = PGSCHEMA_ASSETS[`${platform}:${arch}`];
+    if (!asset)
+        throw new Error(`sqlx-js db install: unsupported platform ${platform}/${arch}`);
+    return asset;
+}
+function pgschemaConfig(config) {
+    if (config.schema?.provider !== "pgschema") {
+        throw new Error("sqlx-js db: set schema.provider = \"pgschema\" in sqlx-js.config.ts");
+    }
+    return config.schema;
+}
+export function managedPgschemaPath(root, asset = resolvePgschemaAsset()) {
+    return join(root, "node_modules/.cache/sqlx-js/pgschema", `v${PGSCHEMA_VERSION}`, asset.key, "pgschema");
+}
+function maybeManagedPgschemaPath(root) {
+    try {
+        const asset = resolvePgschemaAsset();
+        const managed = managedPgschemaPath(root, asset);
+        if (!existsSync(managed))
+            return undefined;
+        if (sha256(readFileSync(managed)) !== asset.sha256) {
+            throw new Error(`sqlx-js db: managed pgschema checksum mismatch at ${managed}. Run sqlx-js db install.`);
+        }
+        chmodSync(managed, 0o755);
+        return managed;
+    }
+    catch (e) {
+        if (e.message.includes("checksum mismatch"))
+            throw e;
+        return undefined;
+    }
+}
+function commandName(root, config) {
+    if (process.platform === "win32")
+        throw new Error(WINDOWS_UNSUPPORTED);
+    if (config.command)
+        return config.command;
+    const managed = maybeManagedPgschemaPath(root);
+    if (managed && existsSync(managed))
+        return managed;
+    return "pgschema";
+}
+function schemaFile(root, config) {
+    return resolve(root, config.file ?? "schema.sql");
+}
+function appliesPlan(subcommand, passthrough) {
+    return subcommand === "apply" && (passthrough ?? []).some((arg) => arg === "--plan" || arg.startsWith("--plan="));
+}
+function installHint(command) {
+    return `sqlx-js db: ${command} was not found. Run sqlx-js db install or set schema.command in sqlx-js.config.ts.`;
+}
+function run(command, args, env) {
+    const child = spawnSync(command, args, { encoding: "utf8", env, stdio: "inherit" });
+    if (child.error) {
+        const code = child.error.code;
+        if (code === "ENOENT")
+            throw new Error(installHint(command));
+        throw child.error;
+    }
+    if (child.signal)
+        throw new Error(`sqlx-js db: ${command} terminated by signal ${child.signal}`);
+    if (child.status && child.status !== 0)
+        process.exit(child.status);
+}
+function pgschemaEnv(db) {
+    return {
+        ...process.env,
+        ...(db.password ? { PGPASSWORD: db.password } : {}),
+        ...(db.sslmode ? { PGSSLMODE: db.sslmode } : {}),
+        ...(db.sslRootCert ? { PGSSLROOTCERT: db.sslRootCert } : {}),
+        ...(db.sslCert ? { PGSSLCERT: db.sslCert } : {}),
+        ...(db.sslKey ? { PGSSLKEY: db.sslKey } : {}),
+    };
+}
+function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+export async function runPgschemaInstall(opts) {
+    const asset = opts.asset ?? resolvePgschemaAsset();
+    const baseUrl = opts.baseUrl ?? PGSCHEMA_BASE_URL;
+    const log = opts.log ?? console.log;
+    const target = managedPgschemaPath(opts.root, asset);
+    if (existsSync(target) && sha256(readFileSync(target)) === asset.sha256) {
+        chmodSync(target, 0o755);
+        log(`pgschema v${PGSCHEMA_VERSION} already installed at ${target}`);
+        return;
+    }
+    const url = `${baseUrl.replace(/\/$/, "")}/${asset.name}`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`sqlx-js db install: failed to download pgschema v${PGSCHEMA_VERSION}: HTTP ${response.status}`);
+    }
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const actual = sha256(bytes);
+    if (actual !== asset.sha256) {
+        throw new Error(`sqlx-js db install: checksum mismatch for ${asset.name}`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        writeFileSync(tmp, bytes, { mode: 0o755 });
+        chmodSync(tmp, 0o755);
+        renameSync(tmp, target);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw e;
+    }
+    writeFileSync(`${target}.json`, JSON.stringify({ version: PGSCHEMA_VERSION, asset: asset.name, sha256: asset.sha256 }, null, 2) + "\n");
+    log(`installed pgschema v${PGSCHEMA_VERSION} to ${target}`);
+}
+export function runPgschemaCommand(opts) {
+    const config = pgschemaConfig(opts.config);
+    const command = commandName(opts.root, config);
+    if (opts.subcommand === "check") {
+        run(command, ["--help"], process.env);
+        return;
+    }
+    if (!opts.databaseUrl)
+        throw new Error("DATABASE_URL is required for sqlx-js db commands");
+    const file = appliesPlan(opts.subcommand, opts.passthrough) ? undefined : schemaFile(opts.root, config);
+    if (file && !existsSync(file))
+        throw new Error(`sqlx-js db: schema file not found: ${file}`);
+    const db = parseDatabaseUrl(opts.databaseUrl);
+    const schemas = pgschemaSchemas(config);
+    const args = [
+        opts.subcommand,
+        "--host", db.host,
+        "--port", String(db.port),
+        "--db", db.database,
+        "--user", db.user,
+    ];
+    if (file)
+        args.push("--file", file);
+    args.push("--schema", schemas[0]);
+    args.push(...opts.passthrough ?? []);
+    run(command, args, pgschemaEnv(db));
+}
+function pgschemaSchemas(config) {
+    const schemas = config.schemas?.length ? config.schemas : ["public"];
+    if (schemas.length > 1) {
+        throw new Error("sqlx-js db: pgschema 1.12.0 supports exactly one --schema value; split plan/apply per schema or use a single schema in sqlx-js.config.ts");
+    }
+    return schemas;
+}

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

@@ -32,6 +32,7 @@ export declare function prepareOnce(opts: PrepareOptions, session: PrepareSessio
     entries: number;
     failures: number;
     pruned: number;
+    functions: number;
 }>;
 export declare function runPrepare(opts: PrepareOptions): Promise<void>;
 export {};

package/dist/src/commands/prepare.js

@@ -6,10 +6,13 @@ import { scanProject } from "../scan/scanner.js";
 import { Cache, fingerprint, effectiveNullable } from "../cache.js";
 import { emitDts } from "../codegen.js";
 import { loadConfig, lookupJsonbType } from "../config.js";
+import { readFunctionCache, writeFunctionCache } from "../function-cache.js";
+import { introspectFunctions } from "../pg/functions.js";
 import { buildParamMap } from "../pg/param-map.js";
 import { mergeExtensionTypes } from "../pg/extensions.js";
 const JSON_OIDS = new Set([114, 3802]);
 const JSON_ARRAY_OIDS = new Set([199, 3807]);
+const JSON_INPUT = 'import("@onreza/sqlx-js").JsonInput';
 function enumUnion(values) {
     if (values.length === 0)
         return "never";
@@ -56,13 +59,28 @@ function resolveParamTs(paramIndex, paramOid, paramMap, schema, cfg) {
     if (JSON_OIDS.has(paramOid) || JSON_ARRAY_OIDS.has(paramOid)) {
         const target = paramMap.get(paramIndex);
         if (target) {
-            const decl = lookupJsonbType(cfg, target.schema ?? "public", target.table, target.column);
+            const column = resolveTargetColumn(target, schema);
+            const decl = column ? lookupJsonbType(cfg, target.schema ?? "public", target.table, column) : undefined;
             if (decl)
                 return JSON_ARRAY_OIDS.has(paramOid) ? `(${decl})[]` : decl;
         }
+        return JSON_ARRAY_OIDS.has(paramOid) ? `(${JSON_INPUT})[]` : JSON_INPUT;
     }
     return resolveTs(paramOid, (oid) => schema.customType(oid));
 }
+function resolveTargetColumn(target, schema) {
+    if (target.column)
+        return target.column;
+    if (target.columnIndex === undefined)
+        return undefined;
+    const oid = schema.resolveTable(target.schema, target.table);
+    if (oid === undefined)
+        return undefined;
+    const cols = schema.columnsOf(oid);
+    if (!cols)
+        return undefined;
+    return [...cols.values()].sort((a, b) => a.attnum - b.attnum)[target.columnIndex - 1]?.name;
+}
 function resolveParamNullable(paramIndex, pm, schema) {
     if (pm.forceNullable.has(paramIndex))
         return true;
@@ -73,7 +91,10 @@ function resolveParamNullable(paramIndex, pm, schema) {
         const oid = schema.resolveTable(t.schema, t.table);
         if (oid === undefined)
             return false;
-        const col = schema.columnsOf(oid)?.get(t.column);
+        const column = resolveTargetColumn(t, schema);
+        if (!column)
+            return false;
+        const col = schema.columnsOf(oid)?.get(column);
         if (!col)
             return false;
         return !col.notNull;
@@ -100,6 +121,15 @@ function snippet(query, max = 80) {
     const oneLine = query.replace(/\s+/g, " ").trim();
     return oneLine.length > max ? oneLine.slice(0, max) + "…" : oneLine;
 }
+function siteUsage(sites) {
+    const inlineQueries = Array.from(new Set(sites.filter((s) => s.kind !== "file").map((s) => s.query))).sort();
+    const filePaths = Array.from(new Set(sites.filter((s) => s.kind === "file").map((s) => s.sqlFilePath).filter(Boolean))).sort();
+    return {
+        hasInline: inlineQueries.length > 0,
+        ...(inlineQueries.length > 0 ? { inlineQueries } : {}),
+        ...(filePaths.length > 0 ? { filePaths } : {}),
+    };
+}
 export async function openSession(opts) {
     const userCfg = await loadConfig(opts.root);
     const cfg = parseDatabaseUrl(opts.databaseUrl);
@@ -284,13 +314,9 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
             forceNullable: new Set(),
             dmlBound: new Set(),
         };
-        const fileSites = r.sites.filter((s) => s.kind === "file");
-        const hasInline = r.sites.some((s) => s.kind !== "file");
-        const filePaths = fileSites.length > 0
-            ? Array.from(new Set(fileSites.map((s) => s.sqlFilePath))).sort()
-            : undefined;
         const entry = {
             query: r.query,
+            ...siteUsage(r.sites),
             paramOids: r.paramOids,
             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)),
@@ -306,8 +332,6 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
                 };
             }),
             hasResultSet: r.fields.length > 0,
-            hasInline,
-            ...(filePaths ? { filePaths } : {}),
             ...(analysis.degraded ? { degraded: analysis.degraded } : {}),
         };
         cache.write(r.fp, entry);
@@ -322,8 +346,13 @@ export async function prepareOnce(opts, session, log = console.log, err = consol
         if (pruned > 0)
             log(`pruned ${pruned} orphaned cache entry/entries`);
     }
-    emitDts(opts.dtsPath, entries);
-    return { entries: entries.length, failures, pruned };
+    let functions = [];
+    if (failures === 0) {
+        functions = await introspectFunctions(client, schema);
+        writeFunctionCache(opts.cacheDir, functions);
+    }
+    emitDts(opts.dtsPath, entries, functions);
+    return { entries: entries.length, failures, pruned, functions: functions.length };
 }
 export async function runPrepare(opts) {
     if (opts.check) {
@@ -351,9 +380,13 @@ export async function runPrepare(opts) {
             console.error(`\nsqlx-js prepare --check: ${stale} stale/missing entries. Run \`sqlx-js prepare\` against a live DB.`);
             process.exit(1);
         }
-        const entries = [...unique.values()].map((u) => cache.read(u.fp)).filter(Boolean);
-        emitDts(opts.dtsPath, entries);
-        console.log(`ok — ${entries.length} unique queries, types regenerated`);
+        const entries = [...unique.values()].map((u) => {
+            const entry = cache.read(u.fp);
+            return entry ? { ...entry, ...siteUsage(u.sites) } : null;
+        }).filter((e) => e !== null);
+        const functions = readFunctionCache(opts.cacheDir);
+        emitDts(opts.dtsPath, entries, functions);
+        console.log(`ok — ${entries.length} unique queries, ${functions.length} function(s), types regenerated`);
         return;
     }
     const session = await openSession(opts);
@@ -364,7 +397,7 @@ export async function runPrepare(opts) {
             await session.client.end();
             process.exit(1);
         }
-        console.log(`\nprepared ${r.entries} unique query/queries → ${opts.dtsPath}`);
+        console.log(`\nprepared ${r.entries} unique query/queries, ${r.functions} function(s) → ${opts.dtsPath}`);
     }
     finally {
         await session.client.end();

package/dist/src/config.d.ts

@@ -1,6 +1,12 @@
 export type SqlxJsConfig = {
     jsonbTypes?: Record<string, string>;
     customTypes?: Record<string, string>;
+    schema?: {
+        provider?: "builtin" | "pgschema";
+        file?: string;
+        schemas?: string[];
+        command?: string;
+    };
 };
 export declare function loadConfig(root: string): Promise<SqlxJsConfig>;
 export declare function lookupJsonbType(cfg: SqlxJsConfig, schema: string, table: string, column: string): string | undefined;

package/dist/src/function-cache.d.ts

@@ -0,0 +1,18 @@
+export type FunctionKind = "function" | "procedure" | "aggregate" | "window";
+export type FunctionParamMode = "in" | "out" | "inout" | "variadic" | "table";
+export type FunctionParamEntry = {
+    mode: FunctionParamMode;
+    tsType: string;
+    name?: string;
+};
+export type FunctionEntry = {
+    schema: string;
+    name: string;
+    signature: string;
+    kind: FunctionKind;
+    params: FunctionParamEntry[];
+    returns: string;
+    returnsSet: boolean;
+};
+export declare function readFunctionCache(cacheDir: string): FunctionEntry[];
+export declare function writeFunctionCache(cacheDir: string, functions: FunctionEntry[]): void;

package/dist/src/function-cache.js

@@ -0,0 +1,38 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+function cachePath(cacheDir) {
+    return join(cacheDir, "functions", "functions.json");
+}
+function parseFunctionCache(raw) {
+    if (!raw || typeof raw !== "object")
+        return [];
+    const obj = raw;
+    if (obj.version !== 1 || !Array.isArray(obj.functions))
+        return [];
+    return obj.functions;
+}
+export function readFunctionCache(cacheDir) {
+    const path = cachePath(cacheDir);
+    if (!existsSync(path))
+        return [];
+    const text = readFileSync(path, "utf8");
+    return parseFunctionCache(JSON.parse(text));
+}
+export function writeFunctionCache(cacheDir, functions) {
+    const path = cachePath(cacheDir);
+    mkdirSync(dirname(path), { recursive: true });
+    const payload = { version: 1, functions };
+    const tmp = `${path}.tmp-${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, JSON.stringify(payload, null, 2));
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+}

package/dist/src/index.d.ts

@@ -4,6 +4,20 @@ export interface KnownQueries {
 }
 export interface KnownFileQueries {
 }
+export interface KnownFunctions {
+}
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export type JsonArray = readonly JsonValue[];
+export type JsonInput = string | number | boolean | JsonInputObject | JsonInputArray;
+export type JsonInputValue = JsonPrimitive | JsonInputObject | JsonInputArray;
+export type JsonInputObject = {
+    readonly [key: string]: JsonInputValue | undefined;
+};
+export type JsonInputArray = readonly JsonInputValue[];
 export type { SqlxJsConfig } from "./config.js";
 export type { SslMode, ConnConfig } from "./pg/wire.js";
 export { PgError, ConnectionLostError } from "./pg/wire.js";

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

@@ -0,0 +1,4 @@
+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[]>;