@onreza/sqlx-js 0.4.0 → 0.5.0

package/dist/src/cache.js

@@ -1,6 +1,13 @@
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "node:fs";
 import { join } from "node:path";
+import { isBuiltinOid } from "./pg/oids.js";
+export const CACHE_FORMAT_VERSION = 2;
+export const GENERATOR_REVISION = 3;
+export const CACHE_MANIFEST_FILE = "cache-manifest.json";
+export function portableCacheOid(oid) {
+    return isBuiltinOid(oid) ? oid : 0;
+}
 export function fingerprint(query) {
     const norm = normalizeForFingerprint(query);
     return createHash("sha256").update(norm).digest("hex").slice(0, 16);
@@ -202,11 +209,35 @@ export class Cache {
             throw err;
         }
     }
+    replaceAll(entries, prune = true) {
+        this.ensure();
+        const staged = [];
+        try {
+            for (const { fp, entry } of entries) {
+                const final = join(this.dir, `${fp}.json`);
+                const tmp = `${final}.tmp-${randomBytes(4).toString("hex")}`;
+                writeFileSync(tmp, JSON.stringify(entry, null, 2));
+                staged.push({ fp, tmp, final });
+            }
+            for (const item of staged)
+                renameSync(item.tmp, item.final);
+        }
+        catch (err) {
+            for (const item of staged) {
+                try {
+                    unlinkSync(item.tmp);
+                }
+                catch { }
+            }
+            throw err;
+        }
+        return prune ? this.prune(staged.map((item) => item.fp)) : [];
+    }
     list() {
         if (!existsSync(this.dir))
             return [];
         return readdirSync(this.dir)
-            .filter((f) => f.endsWith(".json") && !f.includes(".tmp-"))
+            .filter((f) => f !== CACHE_MANIFEST_FILE && f.endsWith(".json") && !f.includes(".tmp-"))
             .map((f) => {
             const fp = f.replace(/\.json$/, "");
             return { fp, entry: assertEntryShape(fp, parseEntryJson(join(this.dir, f))) };
@@ -229,3 +260,54 @@ export class Cache {
         return removed;
     }
 }
+export function cacheManifestPath(cacheDir) {
+    return join(cacheDir, CACHE_MANIFEST_FILE);
+}
+export function writeCacheManifest(cacheDir, configHash) {
+    if (!existsSync(cacheDir))
+        mkdirSync(cacheDir, { recursive: true });
+    const path = cacheManifestPath(cacheDir);
+    const tmp = `${path}.tmp-${randomBytes(4).toString("hex")}`;
+    const manifest = {
+        cacheFormat: CACHE_FORMAT_VERSION,
+        generatorRevision: GENERATOR_REVISION,
+        configHash,
+    };
+    writeFileSync(tmp, JSON.stringify(manifest, null, 2) + "\n");
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+}
+export function readCacheManifest(cacheDir) {
+    const path = cacheManifestPath(cacheDir);
+    if (!existsSync(path))
+        return null;
+    const raw = parseEntryJson(path);
+    if (!raw || typeof raw !== "object") {
+        throw new Error(`sqlx-js: cache manifest is malformed: ${path}`);
+    }
+    const value = raw;
+    if (value.cacheFormat !== CACHE_FORMAT_VERSION ||
+        value.generatorRevision !== GENERATOR_REVISION ||
+        typeof value.configHash !== "string") {
+        throw new Error(`sqlx-js: cache manifest is stale: ${path}. Run \`sqlx-js prepare\`.`);
+    }
+    return value;
+}
+export function assertCacheManifest(cacheDir, configHash) {
+    const manifest = readCacheManifest(cacheDir);
+    if (!manifest) {
+        throw new Error(`sqlx-js: cache manifest is missing. Run \`sqlx-js prepare\` to regenerate the cache.`);
+    }
+    if (manifest.configHash !== configHash) {
+        throw new Error("sqlx-js: cache was generated with a different jsonbTypes/customTypes config. Run `sqlx-js prepare`.");
+    }
+    return manifest;
+}

package/dist/src/codegen.js

@@ -1,4 +1,5 @@
-import { writeFileSync, mkdirSync } from "node:fs";
+import { writeFileSync, mkdirSync, renameSync, unlinkSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { dirname } from "node:path";
 import { effectiveNullable } from "./cache.js";
 function entrySignature(e) {
@@ -25,7 +26,18 @@ export function emitDts(outPath, entries, functions = []) {
     emitModule(lines, "@onreza/sqlx-js", entries, functions);
     lines.push("");
     lines.push("export {};");
-    writeFileSync(outPath, lines.join("\n") + "\n");
+    const tmp = `${outPath}.tmp-${randomBytes(4).toString("hex")}`;
+    writeFileSync(tmp, lines.join("\n") + "\n");
+    try {
+        renameSync(tmp, outPath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
 }
 function emitModule(lines, moduleName, entries, functions) {
     lines.push(`declare module ${JSON.stringify(moduleName)} {`);

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

@@ -0,0 +1,16 @@
+export type DoctorCheck = {
+    name: string;
+    status: "ok" | "warning" | "error";
+    message: string;
+    details?: Record<string, unknown>;
+};
+export type DoctorOptions = {
+    root: string;
+    databaseUrl: string;
+    cacheDir: string;
+    dtsPath: string;
+    json?: boolean;
+    envError?: string;
+};
+export declare function inspectDoctor(opts: DoctorOptions): Promise<DoctorCheck[]>;
+export declare function runDoctor(opts: DoctorOptions): Promise<void>;

package/dist/src/commands/doctor.js

@@ -0,0 +1,196 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import ts from "typescript";
+import { assertCacheManifest } from "../cache.js";
+import { assertSupportedRuntime, envFilePath, loadConfigInfo, nativeTypeScriptEnabled, prepareConfigHash, runtimeVersion, } from "../config.js";
+import { decodeText, parseDatabaseUrl, PgClient } from "../pg/wire.js";
+import { probePgschema } from "./pgschema.js";
+function decodeBoolean(value) {
+    const text = decodeText(value ?? null);
+    return text === "t" || text === "true" || text === "1";
+}
+function tsconfigIncludes(root, file) {
+    const path = join(root, "tsconfig.json");
+    if (!existsSync(path))
+        return { ok: false, message: `tsconfig.json not found at ${path}` };
+    const target = resolve(file);
+    const visited = new Set();
+    const visit = (configPath) => {
+        const resolvedConfig = resolve(configPath);
+        if (visited.has(resolvedConfig))
+            return { included: false };
+        visited.add(resolvedConfig);
+        const read = ts.readConfigFile(resolvedConfig, ts.sys.readFile);
+        if (read.error) {
+            return { included: false, error: ts.flattenDiagnosticMessageText(read.error.messageText, "\n") };
+        }
+        const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, resolve(resolvedConfig, ".."), undefined, resolvedConfig);
+        if (parsed.errors.length > 0) {
+            return {
+                included: false,
+                error: parsed.errors.map((error) => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("; "),
+            };
+        }
+        if (parsed.fileNames.some((name) => resolve(name) === target))
+            return { included: true };
+        for (const reference of parsed.projectReferences ?? []) {
+            const result = visit(ts.resolveProjectReferencePath(reference));
+            if (result.included || result.error)
+                return result;
+        }
+        return { included: false };
+    };
+    const result = visit(path);
+    if (result.error)
+        return { ok: false, message: result.error };
+    const included = result.included;
+    return included
+        ? { ok: true, message: `${file} is included by tsconfig.json` }
+        : { ok: false, message: `${file} is not included by tsconfig.json` };
+}
+export async function inspectDoctor(opts) {
+    const checks = [];
+    const runtime = runtimeVersion();
+    try {
+        assertSupportedRuntime();
+        checks.push({
+            name: "runtime",
+            status: "ok",
+            message: `${runtime.runtime} ${runtime.version} satisfies the supported baseline`,
+        });
+    }
+    catch (e) {
+        checks.push({ name: "runtime", status: "error", message: e.message });
+    }
+    let config = {};
+    let configLoaded = true;
+    try {
+        const info = await loadConfigInfo(opts.root);
+        config = info.config;
+        const nativeTs = nativeTypeScriptEnabled();
+        if (info.path && /\.m?ts$/.test(info.path) && nativeTs === false) {
+            checks.push({ name: "config", status: "error", message: "native TypeScript execution is disabled" });
+        }
+        else {
+            checks.push({
+                name: "config",
+                status: "ok",
+                message: info.path ? `loaded ${info.path}` : "no config file; defaults are active",
+            });
+        }
+    }
+    catch (e) {
+        configLoaded = false;
+        checks.push({ name: "config", status: "error", message: e.message });
+    }
+    const envPath = envFilePath(opts.root);
+    checks.push(opts.envError
+        ? { name: "env", status: "error", message: opts.envError }
+        : existsSync(envPath) && !opts.databaseUrl
+            ? { name: "env", status: "error", message: `${envPath} exists but DATABASE_URL is missing` }
+            : existsSync(envPath)
+                ? { name: "env", status: "ok", message: `loaded environment file ${envPath}` }
+                : opts.databaseUrl
+                    ? { name: "env", status: "ok", message: "DATABASE_URL is provided by the process environment" }
+                    : { name: "env", status: "error", message: `DATABASE_URL is missing and ${envPath} does not exist` });
+    if (!configLoaded) {
+        checks.push({ name: "cache", status: "warning", message: "cache config-hash check skipped because config failed to load" });
+    }
+    else {
+        try {
+            assertCacheManifest(opts.cacheDir, prepareConfigHash(config));
+            checks.push({ name: "cache", status: "ok", message: "cache manifest and config hash are current" });
+        }
+        catch (e) {
+            checks.push({ name: "cache", status: "error", message: e.message });
+        }
+    }
+    const tsconfig = tsconfigIncludes(opts.root, opts.dtsPath);
+    checks.push({
+        name: "tsconfig",
+        status: tsconfig.ok ? "ok" : "error",
+        message: tsconfig.message,
+    });
+    if (!opts.databaseUrl) {
+        checks.push({ name: "database", status: "error", message: "DATABASE_URL is required for the database check" });
+    }
+    else {
+        const client = new PgClient(parseDatabaseUrl(opts.databaseUrl));
+        try {
+            await client.connect();
+            await client.describe("SELECT 1");
+            const result = await client.simpleQueryAll(`
+        SELECT current_setting('server_version'), current_user, current_database(),
+          (SELECT (rolcreatedb OR rolsuper)::text FROM pg_roles WHERE rolname = current_user),
+          COALESCE(has_schema_privilege(current_user, current_schema(), 'USAGE'), false)::text
+      `);
+            const row = result.rows[0];
+            const canCreateDatabase = decodeBoolean(row[3]);
+            const hasSchemaUsage = decodeBoolean(row[4]);
+            const shadowDatabaseUrl = process.env.SHADOW_DATABASE_URL;
+            const shadowAdminDatabaseUrl = process.env.SHADOW_ADMIN_DATABASE_URL;
+            const hasShadowFallback = Boolean(shadowDatabaseUrl || shadowAdminDatabaseUrl);
+            const needsShadowCreate = config.schema?.provider !== "pgschema";
+            checks.push({
+                name: "database",
+                status: "ok",
+                message: `connected to ${decodeText(row[2])} as ${decodeText(row[1])}`,
+                details: {
+                    serverVersion: decodeText(row[0]),
+                    describe: true,
+                    schemaUsage: hasSchemaUsage,
+                },
+            });
+            checks.push({
+                name: "permissions",
+                status: hasSchemaUsage && (!needsShadowCreate || canCreateDatabase || hasShadowFallback) ? "ok" : "warning",
+                message: !hasSchemaUsage
+                    ? "current user lacks USAGE on the current schema"
+                    : !needsShadowCreate
+                        ? "current user can use the current schema; pgschema does not require shadow-database creation"
+                        : canCreateDatabase
+                            ? "current user can use the current schema and create shadow databases"
+                            : hasShadowFallback
+                                ? "current user cannot create databases; a shadow database fallback is configured"
+                                : "current user cannot create shadow databases; configure SHADOW_ADMIN_DATABASE_URL or SHADOW_DATABASE_URL",
+                details: {
+                    schemaUsage: hasSchemaUsage,
+                    createDatabase: canCreateDatabase,
+                    shadowDatabaseConfigured: Boolean(shadowDatabaseUrl),
+                    shadowAdminConfigured: Boolean(shadowAdminDatabaseUrl),
+                },
+            });
+        }
+        catch (e) {
+            checks.push({ name: "database", status: "error", message: e.message });
+        }
+        finally {
+            await client.end().catch(() => { });
+        }
+    }
+    if (!configLoaded) {
+        checks.push({ name: "pgschema", status: "warning", message: "schema-provider check skipped because config failed to load" });
+    }
+    else if (config.schema?.provider === "pgschema") {
+        const probe = probePgschema(opts.root, config);
+        checks.push({ name: "pgschema", status: probe.ok ? "ok" : "error", message: probe.message });
+    }
+    else {
+        checks.push({ name: "pgschema", status: "ok", message: "built-in migration provider is active" });
+    }
+    return checks;
+}
+export async function runDoctor(opts) {
+    const checks = await inspectDoctor(opts);
+    const ok = checks.every((check) => check.status !== "error");
+    if (opts.json) {
+        console.log(JSON.stringify({ formatVersion: 1, ok, checks }, null, 2));
+    }
+    else {
+        for (const check of checks) {
+            console.log(`${check.status.padEnd(7)} ${check.name}: ${check.message}`);
+        }
+    }
+    if (!ok)
+        process.exitCode = 1;
+}

package/dist/src/commands/init.js

@@ -1,21 +1,19 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-const CONFIG_TEMPLATE = `import type { SqlxJsConfig } from "@onreza/sqlx-js";
+const CONFIG_TEMPLATE = `import { defineConfig } from "@onreza/sqlx-js";
 
-const config: SqlxJsConfig = {
+export default defineConfig({
   // Map jsonb columns/params to TypeScript types declared in a .d.ts, e.g.
   //   "users.settings": "SqlxJsJson.UserSettings",
   jsonbTypes: {},
   // Map PostgreSQL type names to TypeScript types, e.g.
   //   geometry: "GeoJSON.Geometry",
   customTypes: {},
-};
-
-export default config;
+});
 `;
-const PGSCHEMA_CONFIG_TEMPLATE = `import type { SqlxJsConfig } from "@onreza/sqlx-js";
+const PGSCHEMA_CONFIG_TEMPLATE = `import { defineConfig } from "@onreza/sqlx-js";
 
-const config: SqlxJsConfig = {
+export default defineConfig({
   schema: {
     provider: "pgschema",
     file: "schema.sql",
@@ -23,9 +21,7 @@ const config: SqlxJsConfig = {
   },
   jsonbTypes: {},
   customTypes: {},
-};
-
-export default config;
+});
 `;
 const ENV_TEMPLATE = `# Connection string used by sqlx-js prepare/migrate and the runtime.
 DATABASE_URL=postgres://user:password@localhost:5432/your_db

package/dist/src/commands/migrate.js

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { PgClient, parseDatabaseUrl, decodeText } from "../pg/wire.js";
-import { openSession, prepareOnce } from "./prepare.js";
+import { openSession, prepareOnce, verifyPrepareArtifacts } from "./prepare.js";
 import { introspectConnected, schemaSnapshotEqual, } from "../schema-snapshot.js";
 const SQUASH_PREFIX = "-- sqlx-js-squash:";
 export const DEFAULT_MIGRATE_LOCK_KEY = 18750938867203960n;
@@ -512,31 +512,16 @@ async function prepareWorkflowArtifacts(opts, databaseUrl) {
     }
 }
 async function prepareInTemporaryArtifacts(opts, databaseUrl) {
-    const tmp = mkdtempSync(join(tmpdir(), "sqlx-js-verify-"));
-    const cacheDir = join(tmp, "cache");
-    const dtsPath = join(tmp, "sqlx-js-env.d.ts");
-    const prepareOpts = {
+    const verification = await verifyPrepareArtifacts({
         root: opts.root,
         databaseUrl,
-        cacheDir,
-        dtsPath,
+        cacheDir: opts.cacheDir,
+        dtsPath: opts.dtsPath,
         check: false,
+        verify: true,
         prune: true,
-    };
-    const session = await openSession(prepareOpts);
-    try {
-        const r = await prepareOnce(prepareOpts, session);
-        if (r.failures > 0) {
-            console.error(`\n${r.failures} query/queries failed to prepare`);
-            return false;
-        }
-        console.log(`shadow: prepared ${r.entries} unique query/queries`);
-        return true;
-    }
-    finally {
-        await session.client.end();
-        rmSync(tmp, { recursive: true, force: true });
-    }
+    });
+    return verification.ok;
 }
 function effectiveSquashReplacements(all) {
     const covered = squashCoveredVersions(all);

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

@@ -19,7 +19,13 @@ export type PgschemaInstallOptions = {
     baseUrl?: string;
     log?: (msg: string) => void;
 };
+export type PgschemaProbe = {
+    ok: boolean;
+    command?: string;
+    message: string;
+};
 export declare function resolvePgschemaAsset(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): PgschemaAsset;
 export declare function managedPgschemaPath(root: string, asset?: PgschemaAsset): string;
+export declare function probePgschema(root: string, config: SqlxJsConfig): PgschemaProbe;
 export declare function runPgschemaInstall(opts: PgschemaInstallOptions): Promise<void>;
 export declare function runPgschemaCommand(opts: PgschemaCommandOptions): void;

package/dist/src/commands/pgschema.js

@@ -73,6 +73,36 @@ function commandName(root, config) {
         return managed;
     return "pgschema";
 }
+export function probePgschema(root, config) {
+    try {
+        const schema = pgschemaConfig(config);
+        const command = commandName(root, schema);
+        const child = spawnSync(command, ["--help"], {
+            encoding: "utf8",
+            env: process.env,
+            timeout: 5_000,
+        });
+        if (child.error) {
+            const code = child.error.code;
+            return {
+                ok: false,
+                command,
+                message: code === "ENOENT"
+                    ? installHint(command)
+                    : code === "ETIMEDOUT"
+                        ? `${command} --help timed out after 5000ms`
+                        : child.error.message,
+            };
+        }
+        if (child.status !== 0) {
+            return { ok: false, command, message: `${command} --help exited with ${child.status}` };
+        }
+        return { ok: true, command, message: `pgschema is available: ${command}` };
+    }
+    catch (e) {
+        return { ok: false, message: e.message };
+    }
+}
 function schemaFile(root, config) {
     return resolve(root, config.file ?? "schema.sql");
 }

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

@@ -7,8 +7,42 @@ export type PrepareOptions = {
     cacheDir: string;
     dtsPath: string;
     check: boolean;
+    verify?: boolean;
+    json?: boolean;
     prune?: boolean;
 };
+export type PrepareDiagnosticPhase = "config" | "connect" | "shadow" | "scan" | "describe" | "introspect" | "analyze" | "param-map" | "cache" | "verify";
+export declare class PrepareFatalError extends Error {
+    readonly phase: PrepareDiagnosticPhase;
+    readonly file?: string;
+    readonly line?: number;
+    readonly column?: number;
+    constructor(phase: PrepareDiagnosticPhase, message: string, location?: {
+        file?: string;
+        line?: number;
+        column?: number;
+    }, options?: ErrorOptions);
+}
+export type PrepareDiagnostic = {
+    severity: "error" | "warning";
+    phase: PrepareDiagnosticPhase;
+    message: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    query?: string;
+    code?: string;
+    position?: number;
+    hint?: string;
+};
+export type PrepareResult = {
+    sites: number;
+    entries: number;
+    failures: number;
+    pruned: number;
+    functions: number;
+    diagnostics: PrepareDiagnostic[];
+};
 export type PrepareSession = {
     client: PgClient;
     schema: SchemaCache;
@@ -28,11 +62,11 @@ export declare function describeAll(cfg: ConnConfig, sessionClient: PgClient, qu
     fp: string;
     query: string;
 }[], concurrency: number): Promise<Map<string, DescribeOutcome>>;
-export declare function prepareOnce(opts: PrepareOptions, session: PrepareSession, log?: (msg: string) => void, err?: (msg: string) => void, concurrency?: number): Promise<{
-    entries: number;
-    failures: number;
-    pruned: number;
-    functions: number;
-}>;
+export declare function prepareOnce(opts: PrepareOptions, session: PrepareSession, log?: (msg: string) => void, err?: (msg: string) => void, concurrency?: number): Promise<PrepareResult>;
 export declare function runPrepare(opts: PrepareOptions): Promise<void>;
+export declare function verifyPrepareArtifacts(opts: PrepareOptions, log?: (msg: string) => void, err?: (msg: string) => void): Promise<{
+    ok: boolean;
+    result: PrepareResult;
+    changed: string[];
+}>;
 export {};