@onreza/sqlx-js 0.4.0 → 0.6.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 { existsSync, mkdirSync, readFileSync, 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
@@ -37,10 +33,23 @@ const PGSCHEMA_TEMPLATE = `-- Desired PostgreSQL schema managed by pgschema.
 --   sqlx-js db plan -- --output-json plan.json
 --   sqlx-js db apply -- --auto-approve
 `;
+const DTS_TEMPLATE = `// AUTO-GENERATED by sqlx-js. Do not edit.
+// Run \`sqlx-js prepare\` to regenerate.
+
+declare module "@onreza/sqlx-js" {
+  interface KnownQueries {}
+  interface KnownFileQueries {}
+  interface KnownFunctions {}
+}
+
+export {};
+`;
 export function runInit(opts) {
     const log = opts.log ?? console.log;
     const created = [];
+    const updated = [];
     const skipped = [];
+    const notes = [];
     const ensureFile = (rel, content) => {
         const full = join(opts.root, rel);
         if (existsSync(full)) {
@@ -67,10 +76,81 @@ export function runInit(opts) {
     else
         ensureDir("migrations");
     ensureFile(".env.example", ENV_TEMPLATE);
+    ensureFile("sqlx-js-env.d.ts", DTS_TEMPLATE);
+    const updateJson = (rel, mutate) => {
+        const full = join(opts.root, rel);
+        if (!existsSync(full))
+            return;
+        const source = readFileSync(full, "utf8");
+        let value;
+        try {
+            value = JSON.parse(source);
+        }
+        catch {
+            notes.push(`${rel}: manual update required because the file is not strict JSON`);
+            return;
+        }
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return;
+        if (!mutate(value))
+            return;
+        const indent = source.match(/\n([ \t]+)"/)?.[1] ?? "  ";
+        writeFileSync(full, JSON.stringify(value, null, indent) + "\n");
+        updated.push(rel);
+    };
+    updateJson("tsconfig.json", (value) => {
+        const files = value.files;
+        if (files !== undefined && (!Array.isArray(files) || !files.every((item) => typeof item === "string"))) {
+            notes.push("tsconfig.json: manual update required because files is not an array of strings");
+            return false;
+        }
+        if (Array.isArray(files)) {
+            if (files.includes("sqlx-js-env.d.ts"))
+                return false;
+            files.push("sqlx-js-env.d.ts");
+            return true;
+        }
+        const include = value.include;
+        if (include !== undefined && (!Array.isArray(include) || !include.every((item) => typeof item === "string"))) {
+            notes.push("tsconfig.json: manual update required because include is not an array of strings");
+            return false;
+        }
+        if (Array.isArray(include)) {
+            if (include.includes("sqlx-js-env.d.ts"))
+                return false;
+            include.push("sqlx-js-env.d.ts");
+            return true;
+        }
+        return false;
+    });
+    updateJson("package.json", (value) => {
+        if (value.scripts !== undefined && (!value.scripts || typeof value.scripts !== "object" || Array.isArray(value.scripts))) {
+            notes.push("package.json: manual script update required because scripts is not an object");
+            return false;
+        }
+        const scripts = (value.scripts ??= {});
+        const defaults = {
+            "sqlx:prepare": "sqlx-js prepare",
+            "sqlx:check": "sqlx-js prepare --check",
+            "sqlx:verify": "sqlx-js prepare --verify --strict-inference",
+        };
+        let changed = false;
+        for (const [name, command] of Object.entries(defaults)) {
+            if (scripts[name] !== undefined)
+                continue;
+            scripts[name] = command;
+            changed = true;
+        }
+        return changed;
+    });
     for (const f of created)
         log(`created ${f}`);
+    for (const f of updated)
+        log(`updated ${f}`);
     for (const f of skipped)
         log(`exists  ${f} (left unchanged)`);
+    for (const note of notes)
+        log(`manual  ${note}`);
     log("");
     log("Next steps:");
     log("  1. Set DATABASE_URL (see .env.example).");
@@ -82,7 +162,7 @@ export function runInit(opts) {
     }
     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");
+        log("  3. Check the project setup:  sqlx-js doctor");
+        log("  4. Develop locally:  sqlx-js migrate dev --strict-inference");
     }
 }

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

@@ -1,4 +1,5 @@
 import { PgClient } from "../pg/wire.js";
+export * from "../migration-core.js";
 export type MigrateOptions = {
     databaseUrl: string;
     migrationsDir: string;
@@ -12,91 +13,7 @@ export type MigrationWorkflowOptions = MigrateOptions & {
     shadowAdminUrl?: string;
     lockKey?: number | bigint;
     lockTimeoutMs?: number;
-};
-export type MigrationStore = {
-    table: string;
-};
-export declare const DEFAULT_MIGRATE_LOCK_KEY = 18750938867203960n;
-export declare function ensureTable(c: PgClient): Promise<MigrationStore>;
-export declare function listApplied(c: PgClient, store?: MigrationStore): Promise<Map<number, {
-    name: string;
-    hash: string;
-}>>;
-export type ApplyOutcome = {
-    kind: "applied";
-    version: number;
-    name: string;
-} | {
-    kind: "adopted";
-    version: number;
-    name: string;
-    replaced: number;
-} | {
-    kind: "tampered";
-    version: number;
-    name: string;
-    applied: string;
-    current: string;
-} | {
-    kind: "failed";
-    version: number;
-    name: string;
-    error: string;
-};
-export type PlanOutcome = {
-    kind: "pending";
-    version: number;
-    name: string;
-} | {
-    kind: "adoptable";
-    version: number;
-    name: string;
-    replaced: number;
-} | {
-    kind: "tampered";
-    version: number;
-    name: string;
-    applied: string;
-    current: string;
-} | {
-    kind: "failed";
-    version: number;
-    name: string;
-    error: string;
-};
-export type MigrationPlanItem = {
-    kind: "apply";
-    version: number;
-    name: string;
-} | {
-    kind: "adopt";
-    version: number;
-    name: string;
-    replaced: number;
-};
-export type MigrationPlanDiagnostic = Extract<PlanOutcome, {
-    kind: "tampered" | "failed";
-}>;
-export type MigrationPlanSnapshot = {
-    ok: boolean;
-    pending: number;
-    adoptable: number;
-    tampered: number;
-    failed: number;
-    steps: MigrationPlanItem[];
-    diagnostics: MigrationPlanDiagnostic[];
-};
-export type MigrationInfoStatus = "applied" | "pending" | "adoptable" | "superseded" | "tampered" | "failed";
-export type MigrationInfoItem = {
-    version: number;
-    name: string;
-    status: MigrationInfoStatus;
-    detail?: string;
-};
-export type MigrationInfoSnapshot = {
-    historyTable: string | null;
-    summary: Record<MigrationInfoStatus, number>;
-    items: MigrationInfoItem[];
+    strictInference?: boolean;
 };
 export type MigrationArchive = {
     name: string;
@@ -151,22 +68,6 @@ export type RevertDryRunOutcome = {
     error: string;
 };
 export declare function checkMigrationFiles(migrationsDir: string): MigrationCheckReport;
-export declare function planPending(c: PgClient, migrationsDir: string, onEvent?: (e: PlanOutcome) => void): Promise<{
-    pending: number;
-    adoptable: number;
-    tampered: number;
-    failed: number;
-    steps: MigrationPlanItem[];
-}>;
-export declare function inspectMigrationPlan(c: PgClient, migrationsDir: string): Promise<MigrationPlanSnapshot>;
-export declare function inspectMigrations(c: PgClient, migrationsDir: string): Promise<MigrationInfoSnapshot>;
-export declare function applyPending(c: PgClient, migrationsDir: string, onEvent?: (e: ApplyOutcome) => void): Promise<{
-    applied: number;
-    tampered: number;
-    failed: number;
-}>;
-export declare function acquireMigrateLock(c: PgClient, lockKey?: number | bigint, timeoutMs?: number): Promise<void>;
-export declare function releaseMigrateLock(c: PgClient, lockKey?: number | bigint): Promise<void>;
 export declare function sanitizePgDumpSchema(sql: string): string;
 export declare function listMigrationArchives(migrationsDir: string): MigrationArchive[];
 export declare function restoreMigrationArchive(migrationsDir: string, archiveName: string, opts?: {