@onreza/sqlx-js 0.0.0

package/dist/bin/sqlx-js.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runPrepare } from "../src/commands/prepare.js";
+import { runWatch } from "../src/commands/watch.js";
+import { migrateRun, migrateInfo, migrateRevert, migrateAdd } from "../src/commands/migrate.js";
+import { applyShadowMigrations, runSchemaCheck, runSchemaDump } from "../src/commands/schema.js";
+function packageVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const path of [join(here, "../package.json"), join(here, "../../package.json")]) {
+        if (!existsSync(path))
+            continue;
+        const pkg = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof pkg.version === "string")
+            return pkg.version;
+    }
+    throw new Error("sqlx-js: cannot locate package.json for version");
+}
+const VERSION = packageVersion();
+function help() {
+    console.error(`sqlx-js — compile-time-checked SQL for TypeScript + Postgres (v${VERSION})
+
+usage:
+  sqlx-js prepare [--check | --watch] [--root <dir>] [--dts <path>] [--no-prune] [--shadow-url <url>]
+  sqlx-js migrate run [--lock-timeout <ms>] | info | revert [--lock-timeout <ms>] | add <name>
+  sqlx-js schema dump | check [--schema <path>] [--manifest <path>] [--no-manifest] [--shadow-url <url>]
+  sqlx-js --version
+
+env:
+  DATABASE_URL=postgres://...  (supports ?sslmode=require|verify-ca|verify-full)
+  SHADOW_DATABASE_URL=postgres://...  (optional throwaway DB for prepare/schema checks)
+
+flags:
+  --root <dir>             scan root (default: cwd)
+  --dts <path>             declarations output (default: <root>/sqlx-js-env.d.ts)
+  --check                  offline mode: validate cache vs sources, no DB
+  --watch                  re-prepare on file change (persistent PG connection)
+  --no-prune               keep orphaned cache entries (default: remove)
+  --migrations <dir>       migrations directory (default: <root>/migrations)
+  --lock-timeout <ms>      advisory-lock acquisition timeout for migrate run/revert
+  --shadow-url <url>       apply migrations to this DB, then prepare/introspect against it
+  --schema <path>          schema snapshot path (default: <root>/.sqlx-js/schema/schema.json)
+  --manifest <path>        LLM schema manifest path (default: <root>/.sqlx-js/schema/schema.md)
+  --no-manifest            skip writing the LLM schema manifest during schema dump
+`);
+    process.exit(2);
+}
+function arg(name, def) {
+    const argv = process.argv;
+    const eq = `${name}=`;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === name)
+            return argv[i + 1] ?? def;
+        if (a.startsWith(eq))
+            return a.slice(eq.length);
+    }
+    return def;
+}
+function flag(name) {
+    for (const a of process.argv) {
+        if (a === name)
+            return true;
+    }
+    return false;
+}
+const cmd = process.argv[2];
+if (cmd === "--version" || cmd === "-v") {
+    console.log(VERSION);
+    process.exit(0);
+}
+if (cmd === "--help" || cmd === "-h" || !cmd) {
+    help();
+}
+const root = resolve(arg("--root", process.cwd()));
+const databaseUrl = process.env.DATABASE_URL ?? "";
+const shadowUrlArg = arg("--shadow-url");
+const shadowUrl = shadowUrlArg ?? process.env.SHADOW_DATABASE_URL;
+const cacheDir = join(root, ".sqlx-js");
+const dtsArg = arg("--dts");
+const dtsPath = dtsArg ? resolve(dtsArg) : join(root, "sqlx-js-env.d.ts");
+const migrationsDir = join(root, arg("--migrations", "migrations"));
+const schemaArg = arg("--schema");
+const schemaPath = schemaArg ? resolve(schemaArg) : join(root, ".sqlx-js/schema/schema.json");
+const manifestArg = arg("--manifest");
+const manifestPath = manifestArg ? resolve(manifestArg) : join(root, ".sqlx-js/schema/schema.md");
+if (cmd === "prepare") {
+    if (flag("--check") && shadowUrlArg) {
+        console.error("--shadow-url cannot be used with prepare --check; use live prepare or schema check --shadow-url");
+        process.exit(2);
+    }
+    const prepareShadowUrl = flag("--check") ? undefined : shadowUrl;
+    const prepareDatabaseUrl = prepareShadowUrl ?? databaseUrl;
+    if (!flag("--check") && !prepareDatabaseUrl) {
+        console.error("DATABASE_URL is required for prepare (use --check for offline)");
+        process.exit(2);
+    }
+    const opts = {
+        root,
+        databaseUrl: prepareDatabaseUrl,
+        cacheDir,
+        dtsPath,
+        check: flag("--check"),
+        prune: !flag("--no-prune"),
+    };
+    if (flag("--watch")) {
+        if (flag("--check")) {
+            console.error("--watch and --check are mutually exclusive");
+            process.exit(2);
+        }
+        await runWatch({
+            ...opts,
+            ...(prepareShadowUrl
+                ? {
+                    beforePrepare: async () => {
+                        const result = await applyShadowMigrations(prepareShadowUrl, migrationsDir);
+                        return { resetSession: result.applied > 0 };
+                    },
+                }
+                : {}),
+        });
+    }
+    else {
+        if (prepareShadowUrl)
+            await applyShadowMigrations(prepareShadowUrl, migrationsDir);
+        await runPrepare(opts);
+    }
+}
+else if (cmd === "schema") {
+    const sub = process.argv[3];
+    const schemaDatabaseUrl = shadowUrl ?? databaseUrl;
+    if (!schemaDatabaseUrl) {
+        console.error("DATABASE_URL is required for schema commands (or pass --shadow-url)");
+        process.exit(2);
+    }
+    const opts = {
+        databaseUrl,
+        snapshotPath: schemaPath,
+        manifestPath,
+        writeManifest: !flag("--no-manifest"),
+        shadowUrl,
+        migrationsDir,
+    };
+    if (sub === "dump")
+        await runSchemaDump(opts);
+    else if (sub === "check")
+        await runSchemaCheck(opts);
+    else
+        help();
+}
+else if (cmd === "migrate") {
+    const sub = process.argv[3];
+    if (!databaseUrl && sub !== "add") {
+        console.error("DATABASE_URL is required");
+        process.exit(2);
+    }
+    const tRaw = arg("--lock-timeout");
+    const lockTimeoutMs = tRaw ? Number(tRaw) : undefined;
+    if (sub === "run") {
+        await migrateRun({ databaseUrl, migrationsDir, lockTimeoutMs });
+    }
+    else if (sub === "info")
+        await migrateInfo({ databaseUrl, migrationsDir });
+    else if (sub === "revert")
+        await migrateRevert({ databaseUrl, migrationsDir, lockTimeoutMs });
+    else if (sub === "add") {
+        const name = process.argv[4];
+        if (!name) {
+            console.error("migrate add: name required");
+            process.exit(2);
+        }
+        migrateAdd({ databaseUrl, migrationsDir, name });
+    }
+    else
+        help();
+}
+else {
+    help();
+}

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

@@ -0,0 +1,7 @@
+import { SQL } from "bun";
+export type BunClient = SQL;
+export declare function getClient(): BunClient;
+export declare function setClient(client: BunClient): void;
+export declare function close(): Promise<void>;
+export declare const sql: import("./runtime.js").SqlRoot;
+export declare const unsafe: (query: string, ...params: unknown[]) => Promise<Record<string, unknown>[]>;

package/dist/src/bun-runtime.js

@@ -0,0 +1,45 @@
+import { SQL } from "bun";
+import { createSqlRuntime } from "./runtime.js";
+class BunRuntimeClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async query(query, params) {
+        return await this.client.unsafe(query, params);
+    }
+    async transaction(fn) {
+        return await this.client.begin(async (tx) => {
+            return await fn(new BunRuntimeClient(tx));
+        });
+    }
+    async close() {
+        await this.client.close();
+    }
+}
+let defaultClient = null;
+function createDefaultClient() {
+    const url = process.env.DATABASE_URL;
+    if (!url)
+        throw new Error("sqlx-js: DATABASE_URL is not set");
+    return new BunRuntimeClient(new SQL({ url, bigint: true }));
+}
+function getRuntimeClient() {
+    defaultClient ??= createDefaultClient();
+    return defaultClient;
+}
+export function getClient() {
+    return getRuntimeClient().client;
+}
+export function setClient(client) {
+    defaultClient = new BunRuntimeClient(client);
+}
+export async function close() {
+    if (defaultClient) {
+        await defaultClient.close();
+        defaultClient = null;
+    }
+}
+const runtime = createSqlRuntime(getRuntimeClient);
+export const sql = runtime.sql;
+export const unsafe = runtime.unsafe;

package/dist/src/bun.d.ts

@@ -0,0 +1,22 @@
+import * as rt from "./bun-runtime.js";
+import type { Typed as TypedFor, TypedFile as TypedFileFor, TypedSql as TypedSqlFor } from "./typed.js";
+export interface KnownQueries {
+}
+export interface KnownFileQueries {
+}
+export type { 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 type { TransactionOptions, MigrateOptions } from "./runtime.js";
+export type { BunClient } from "./bun-runtime.js";
+export type TypedFile = TypedFileFor<KnownFileQueries>;
+export type TypedSql = TypedSqlFor<KnownQueries, KnownFileQueries>;
+export type Typed = TypedFor<KnownQueries, KnownFileQueries, import("./runtime.js").TransactionOptions>;
+export declare const sql: Typed;
+export type Unsafe = (query: string, ...params: unknown[]) => Promise<Record<string, unknown>[]>;
+export declare const unsafe: Unsafe;
+export declare const getClient: typeof rt.getClient;
+export declare const setClient: typeof rt.setClient;
+export declare const close: typeof rt.close;
+export { migrate, clearSqlFileCache, encodePgArrayLiteral, id } from "./runtime.js";

package/dist/src/bun.js

@@ -0,0 +1,9 @@
+import * as rt from "./bun-runtime.js";
+export { PgError, ConnectionLostError } from "./pg/wire.js";
+export { NoRowsError, TooManyRowsError } from "./runtime.js";
+export const sql = rt.sql;
+export const unsafe = rt.unsafe;
+export const getClient = rt.getClient;
+export const setClient = rt.setClient;
+export const close = rt.close;
+export { migrate, clearSqlFileCache, encodePgArrayLiteral, id } from "./runtime.js";

package/dist/src/cache.d.ts

@@ -0,0 +1,36 @@
+export type CacheColumn = {
+    name: string;
+    typeOid: number;
+    tsType: string;
+    nullable: boolean;
+    override?: "non-null" | "nullable";
+};
+export type CacheEntry = {
+    query: string;
+    paramOids: number[];
+    paramTsTypes: string[];
+    paramNullable?: boolean[];
+    columns: CacheColumn[];
+    hasResultSet: boolean;
+    hasInline?: boolean;
+    filePaths?: string[];
+    degraded?: {
+        reason: string;
+    };
+};
+export declare function fingerprint(query: string): string;
+export declare function effectiveNullable(c: CacheColumn): boolean;
+export declare class Cache {
+    private dir;
+    constructor(dir: string);
+    ensure(): void;
+    has(fp: string): boolean;
+    read(fp: string): CacheEntry | null;
+    write(fp: string, entry: CacheEntry): void;
+    list(): {
+        fp: string;
+        entry: CacheEntry;
+    }[];
+    remove(fp: string): void;
+    prune(keep: Iterable<string>): string[];
+}

package/dist/src/cache.js

@@ -0,0 +1,104 @@
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from "node:fs";
+import { join } from "node:path";
+export function fingerprint(query) {
+    const norm = query.replace(/\s+/g, " ").trim();
+    return createHash("sha256").update(norm).digest("hex").slice(0, 16);
+}
+export function effectiveNullable(c) {
+    if (c.override === "non-null")
+        return false;
+    if (c.override === "nullable")
+        return true;
+    return c.nullable;
+}
+function parseEntryJson(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        throw new Error(`sqlx-js: cannot read cache entry ${path}: ${err.message}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`sqlx-js: cache entry ${path} is not valid JSON: ${err.message}`);
+    }
+}
+function assertEntryShape(fp, raw) {
+    if (!raw || typeof raw !== "object" || !Array.isArray(raw.columns)) {
+        throw new Error(`sqlx-js: cache entry ${fp}.json is malformed`);
+    }
+    const cols = raw.columns;
+    if (cols.length > 0) {
+        const c = cols[0];
+        if ("forceNonNull" in c || "forceNullable" in c) {
+            throw new Error(`sqlx-js: cache entry ${fp}.json uses an older schema ` +
+                `(columns.forceNonNull/forceNullable). Re-run \`sqlx-js prepare\` to regenerate.`);
+        }
+    }
+    return raw;
+}
+export class Cache {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    ensure() {
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+    }
+    has(fp) {
+        return existsSync(join(this.dir, `${fp}.json`));
+    }
+    read(fp) {
+        const p = join(this.dir, `${fp}.json`);
+        if (!existsSync(p))
+            return null;
+        return assertEntryShape(fp, parseEntryJson(p));
+    }
+    write(fp, entry) {
+        this.ensure();
+        const final = join(this.dir, `${fp}.json`);
+        const tmp = `${final}.tmp-${randomBytes(4).toString("hex")}`;
+        writeFileSync(tmp, JSON.stringify(entry, null, 2));
+        try {
+            renameSync(tmp, final);
+        }
+        catch (err) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch { }
+            throw err;
+        }
+    }
+    list() {
+        if (!existsSync(this.dir))
+            return [];
+        return readdirSync(this.dir)
+            .filter((f) => f.endsWith(".json") && !f.includes(".tmp-"))
+            .map((f) => {
+            const fp = f.replace(/\.json$/, "");
+            return { fp, entry: assertEntryShape(fp, parseEntryJson(join(this.dir, f))) };
+        });
+    }
+    remove(fp) {
+        const p = join(this.dir, `${fp}.json`);
+        if (existsSync(p))
+            unlinkSync(p);
+    }
+    prune(keep) {
+        const keepSet = new Set(keep);
+        const removed = [];
+        for (const { fp } of this.list()) {
+            if (!keepSet.has(fp)) {
+                this.remove(fp);
+                removed.push(fp);
+            }
+        }
+        return removed;
+    }
+}

package/dist/src/codegen.d.ts

@@ -0,0 +1,2 @@
+import { type CacheEntry } from "./cache.js";
+export declare function emitDts(outPath: string, entries: CacheEntry[]): void;

package/dist/src/codegen.js

@@ -0,0 +1,74 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { effectiveNullable } from "./cache.js";
+function entrySignature(e) {
+    const paramTypes = e.paramTsTypes.map((t, i) => {
+        const nullable = e.paramNullable?.[i] === true;
+        return nullable ? `${t} | null` : t;
+    });
+    const params = paramTypes.length === 0 ? "[]" : `[${paramTypes.join(", ")}]`;
+    if (!e.hasResultSet)
+        return { params, row: "never" };
+    const cols = e.columns.map((c) => {
+        const nullable = effectiveNullable(c);
+        const t = nullable ? `${c.tsType} | null` : c.tsType;
+        return `${JSON.stringify(c.name)}: ${t}`;
+    });
+    return { params, row: `{ ${cols.join("; ")} }` };
+}
+export function emitDts(outPath, entries) {
+    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);
+    lines.push("");
+    emitModule(lines, "@onreza/sqlx-js/bun", entries);
+    lines.push("");
+    lines.push("export {};");
+    writeFileSync(outPath, lines.join("\n") + "\n");
+}
+function emitModule(lines, moduleName, entries) {
+    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))
+            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} };`);
+    }
+    lines.push("  }");
+    lines.push("");
+    lines.push("  interface KnownFileQueries {");
+    const filePairs = [];
+    for (const e of entries) {
+        if (!e.filePaths || e.filePaths.length === 0)
+            continue;
+        for (const p of e.filePaths)
+            filePairs.push({ path: p, entry: e });
+    }
+    const filePathsSeen = new Set();
+    for (const { path, entry } of filePairs.slice().sort((a, b) => a.path.localeCompare(b.path))) {
+        if (filePathsSeen.has(path))
+            continue;
+        filePathsSeen.add(path);
+        const { params, row } = entrySignature(entry);
+        if (entry.degraded)
+            lines.push(`    /** Nullability inference degraded: ${entry.degraded.reason}. */`);
+        lines.push(`    ${JSON.stringify(path)}: { params: ${params}; row: ${row} };`);
+    }
+    lines.push("  }");
+    lines.push("}");
+}

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

@@ -0,0 +1,63 @@
+import { PgClient } from "../pg/wire.js";
+export type MigrateOptions = {
+    databaseUrl: string;
+    migrationsDir: string;
+};
+export declare const DEFAULT_MIGRATE_LOCK_KEY = 18750938867203960n;
+export declare function ensureTable(c: PgClient): Promise<void>;
+export declare function listApplied(c: PgClient): Promise<Map<number, {
+    name: string;
+    hash: string;
+}>>;
+export type ApplyOutcome = {
+    kind: "applied";
+    version: number;
+    name: string;
+} | {
+    kind: "tampered";
+    version: number;
+    name: string;
+    applied: string;
+    current: string;
+} | {
+    kind: "failed";
+    version: number;
+    name: string;
+    error: string;
+};
+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 migrateRun(opts: MigrateOptions & {
+    lockKey?: number | bigint;
+    lockTimeoutMs?: number;
+}): Promise<void>;
+export declare function migrateInfo(opts: MigrateOptions): Promise<void>;
+export type RevertOutcome = {
+    kind: "noop";
+} | {
+    kind: "no-down";
+    version: number;
+    name: string;
+} | {
+    kind: "reverted";
+    version: number;
+    name: string;
+} | {
+    kind: "failed";
+    version: number;
+    name: string;
+    error: string;
+};
+export declare function revertLast(c: PgClient, migrationsDir: string): Promise<RevertOutcome>;
+export declare function migrateRevert(opts: MigrateOptions & {
+    lockKey?: number | bigint;
+    lockTimeoutMs?: number;
+}): Promise<void>;
+export declare function migrateAdd(opts: MigrateOptions & {
+    name: string;
+}): void;