@bockit/sequel 0.0.0-stage → 0.1.0

package/dist/generate/pg-dump.d.ts

@@ -0,0 +1,8 @@
+export declare function pgDumpMajor(versionOutput: string): number | null;
+export declare function checkPgDump(serverMajor: number, pgDump?: string): Promise<void>;
+export declare function serverMajor(databaseUrl: string): Promise<number>;
+export declare function dumpSchema(databaseUrl: string, file: string, pgDump?: string): Promise<void>;
+export declare function withoutPassword(databaseUrl: string): {
+    url: string;
+    password: string | undefined;
+};

package/dist/generate/pg-dump.js

@@ -0,0 +1,66 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import pg from 'pg';
+import { SequelError } from '../errors.js';
+const run = promisify(execFile);
+// The major version in `pg_dump --version`, such as 18 from `pg_dump (PostgreSQL) 18.6`.
+export function pgDumpMajor(versionOutput) {
+    const match = /\(PostgreSQL\)\s+(\d+)/.exec(versionOutput) ?? /\b(\d+)(?:\.\d+)?\b/.exec(versionOutput);
+    return match?.[1] === undefined ? null : Number(match[1]);
+}
+// TECH-SPEC §1: `pg_dump` must be on PATH, at the server's major version or newer.
+export async function checkPgDump(serverMajor, pgDump = 'pg_dump') {
+    let stdout;
+    try {
+        ;
+        ({ stdout } = await run(pgDump, ['--version']));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new SequelError(`pg_dump was not found on PATH. sequel needs it to read the test database's schema. Install the Postgres ${serverMajor} client tools, or newer, and put pg_dump on PATH.`);
+        }
+        throw error;
+    }
+    const major = pgDumpMajor(stdout);
+    if (major === null) {
+        throw new SequelError(`Could not read pg_dump's version from "${stdout.trim()}". Check that pg_dump on PATH is Postgres's.`);
+    }
+    if (major < serverMajor) {
+        throw new SequelError(`pg_dump on PATH is version ${major}, but the test database's server is Postgres ${serverMajor}. Install pg_dump ${serverMajor} or newer and put it first on PATH.`);
+    }
+}
+export async function serverMajor(databaseUrl) {
+    const client = new pg.Client({ connectionString: databaseUrl });
+    await client.connect();
+    try {
+        const result = await client.query('SHOW server_version_num');
+        return Math.floor(Number(result.rows[0]?.server_version_num) / 10_000);
+    }
+    finally {
+        await client.end();
+    }
+}
+// TECH-SPEC §9: `pg_dump --schema-only --no-owner --no-privileges` of the test database into
+// `file`. The password travels in `PGPASSWORD`, so `ps` never shows it.
+export async function dumpSchema(databaseUrl, file, pgDump = 'pg_dump') {
+    await checkPgDump(await serverMajor(databaseUrl), pgDump);
+    const { url, password } = withoutPassword(databaseUrl);
+    const env = { ...process.env };
+    if (password !== undefined)
+        env.PGPASSWORD = password;
+    try {
+        await run(pgDump, ['--schema-only', '--no-owner', '--no-privileges', '--file', file, '--dbname', url], { env, maxBuffer: 64 * 1024 * 1024 });
+    }
+    catch (error) {
+        const stderr = String(error.stderr ?? '').trim();
+        throw new SequelError(`pg_dump could not dump the test database's schema: ${stderr || error.message}`);
+    }
+}
+export function withoutPassword(databaseUrl) {
+    const parsed = new URL(databaseUrl);
+    if (parsed.password === '')
+        return { url: databaseUrl, password: undefined };
+    const password = decodeURIComponent(parsed.password);
+    parsed.password = '';
+    return { url: parsed.toString(), password };
+}

package/dist/generate/plugin-wrapper.d.ts

@@ -0,0 +1,3 @@
+export declare function generatorEntry(): string;
+export declare function writePluginWrapper(dir: string, node?: string, entry?: string): Promise<string>;
+export declare function shellQuote(value: string): string;

package/dist/generate/plugin-wrapper.js

@@ -0,0 +1,20 @@
+import { chmod, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The generator's entry: `main.ts` from source, `main.js` from the published `dist/`.
+export function generatorEntry() {
+    const here = fileURLToPath(import.meta.url);
+    return path.join(path.dirname(here), '..', 'generator', `main${path.extname(here)}`);
+}
+// sqlc runs a process plugin with no `PATH`, so `#!/usr/bin/env node` can't start. Each run
+// writes a `#!/bin/sh` wrapper that `exec`s this Node on the generator's entry (TECH-SPEC §9,
+// R1), and points the plugin's `cmd` at it.
+export async function writePluginWrapper(dir, node = process.execPath, entry = generatorEntry()) {
+    const file = path.join(dir, 'sequel-generator.sh');
+    await writeFile(file, `#!/bin/sh\nexec ${shellQuote(node)} ${shellQuote(entry)} "$@"\n`);
+    await chmod(file, 0o755);
+    return file;
+}
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}

package/dist/generate/sqlc.d.ts

@@ -0,0 +1,27 @@
+import type { BigintMode } from '../config/define-config.ts';
+export type Block = {
+    queries: string;
+    out: string;
+};
+export declare const DATABASE_URL_VARIABLE = "SEQUEL_SQLC_DATABASE_URL";
+export declare function pluginName(index: number): string;
+export declare function sqlcConfig(options: {
+    configDir: string;
+    schema: string;
+    blocks: Block[];
+    wrapper: string;
+    bigint: BigintMode;
+}): object;
+export declare function writeSqlcConfig(file: string, config: object): Promise<void>;
+export type SqlcRun = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function runSqlc(sqlc: string, command: 'generate' | 'diff', configFile: string, databaseUrl: string): Promise<SqlcRun>;
+export declare function readFailures(output: string, options: {
+    configDir: string;
+    blocks: Block[];
+    root: string;
+}): string[];
+export declare function nameLine(file: string, query: string): number | undefined;

package/dist/generate/sqlc.js

@@ -0,0 +1,113 @@
+import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+// sqlc reads the test database's URL from this variable, through `${…}` in `database.uri`,
+// so the URL, and any password in it, is never written to disk.
+export const DATABASE_URL_VARIABLE = 'SEQUEL_SQLC_DATABASE_URL';
+// The plugin entry for block `i`. sqlc heads each block's failures with
+// `# package <plugin>`, so a plugin per block tells failures apart by folder.
+export function pluginName(index) {
+    return `sequel-${index}`;
+}
+// TECH-SPEC §9: sqlc's config, one `sql` block per folder of query files, typed by the
+// database analyzer against the test database. sqlc joins every path onto the config's own
+// folder, even an absolute one, so paths are written relative to `configDir`.
+export function sqlcConfig(options) {
+    const relative = (to) => path.relative(options.configDir, to) || '.';
+    return {
+        version: '2',
+        plugins: options.blocks.map((_, i) => ({
+            name: pluginName(i),
+            process: { cmd: options.wrapper, format: 'json' },
+        })),
+        sql: options.blocks.map((block, i) => ({
+            engine: 'postgresql',
+            schema: relative(options.schema),
+            queries: relative(block.queries),
+            database: { uri: `\${${DATABASE_URL_VARIABLE}}` },
+            analyzer: { database: true },
+            codegen: [
+                { plugin: pluginName(i), out: relative(block.out), options: { bigint: options.bigint } },
+            ],
+        })),
+    };
+}
+export async function writeSqlcConfig(file, config) {
+    await writeFile(file, `${JSON.stringify(config, null, 2)}\n`);
+}
+// Runs `sqlc generate` or `sqlc diff` on a config, with the test database's URL in the
+// environment.
+export function runSqlc(sqlc, command, configFile, databaseUrl) {
+    return new Promise((resolve, reject) => {
+        execFile(sqlc, [command, '-f', configFile], {
+            cwd: path.dirname(configFile),
+            env: { ...process.env, [DATABASE_URL_VARIABLE]: databaseUrl },
+            maxBuffer: 64 * 1024 * 1024,
+        }, (error, stdout, stderr) => {
+            if (error !== null && typeof error.code !== 'number') {
+                reject(error);
+                return;
+            }
+            resolve({ exitCode: error === null ? 0 : error.code, stdout, stderr });
+        });
+    });
+}
+const PLUGIN_PREFIX = 'error generating code: process: error running command ';
+// Turns sqlc's failure output into one line per failure, each naming its file, relative to
+// `root`, and line. sqlc's own errors carry `path:line:col`. The generator's carry only
+// `<file>: <query>`, so the line is that of the query's `-- name:` comment (R57).
+export function readFailures(output, options) {
+    const failures = [];
+    let block;
+    for (const raw of output.split('\n')) {
+        const header = /^# package (.*)$/.exec(raw);
+        if (header !== null) {
+            block = options.blocks.find((_, i) => pluginName(i) === header[1]);
+            continue;
+        }
+        const line = raw.startsWith(PLUGIN_PREFIX) ? raw.slice(PLUGIN_PREFIX.length) : raw;
+        if (line.trim() === '')
+            continue;
+        const own = /^(.+?\.sql):(\d+):(\d+): (.*)$/.exec(line);
+        if (own !== null) {
+            const [, file = '', row, column, message] = own;
+            const shown = path.relative(options.root, path.resolve(options.configDir, file));
+            failures.push(`${shown}:${row}:${column}: ${message}`);
+            continue;
+        }
+        const fileOnly = /^([^:]+): (query file name must end in \.sql)$/.exec(line);
+        if (fileOnly !== null && block !== undefined) {
+            const shown = path.relative(options.root, path.join(block.queries, fileOnly[1] ?? ''));
+            failures.push(`${shown}: ${fileOnly[2]}`);
+            continue;
+        }
+        const generator = /^([^:]+\.sql): ([^\s:]+): (.*)$/.exec(line);
+        if (generator !== null && block !== undefined) {
+            const [, file = '', query = '', message] = generator;
+            const full = path.join(block.queries, file);
+            const lineNumber = nameLine(full, query);
+            const shown = path.relative(options.root, full);
+            failures.push(`${shown}${lineNumber === undefined ? '' : `:${lineNumber}`}: ${query}: ${message}`);
+            continue;
+        }
+        failures.push(line);
+    }
+    return failures;
+}
+// The 1-based line of `-- name: <query>` in `file`.
+export function nameLine(file, query) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const pattern = new RegExp(`^\\s*--\\s*name:\\s*${escapeRegExp(query)}(\\s|$)`);
+    const index = text.split('\n').findIndex((line) => pattern.test(line));
+    return index === -1 ? undefined : index + 1;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/generate/watch.d.ts

@@ -0,0 +1,16 @@
+export declare function createRerunScheduler(options: {
+    run: () => Promise<void>;
+    onError: (error: unknown) => void;
+    debounceMs?: number;
+}): {
+    trigger: () => void;
+    settled(): Promise<void>;
+    stop(): void;
+};
+export declare function watchAndRerun(options: {
+    folders: string[];
+    run: () => Promise<void>;
+    onError: (error: unknown) => void;
+    signal: AbortSignal;
+    debounceMs?: number;
+}): Promise<void>;

package/dist/generate/watch.js

@@ -0,0 +1,73 @@
+import { existsSync, watch } from 'node:fs';
+// TECH-SPEC §9's watch: reruns are debounced, and never overlap. A change during a run
+// schedules one more run after it.
+export function createRerunScheduler(options) {
+    const debounceMs = options.debounceMs ?? 200;
+    let timer;
+    let running;
+    let again = false;
+    const fire = async () => {
+        if (running !== undefined) {
+            again = true;
+            return;
+        }
+        running = (async () => {
+            try {
+                await options.run();
+            }
+            catch (error) {
+                options.onError(error);
+            }
+        })();
+        await running;
+        running = undefined;
+        if (again) {
+            again = false;
+            trigger();
+        }
+    };
+    const trigger = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => void fire(), debounceMs);
+    };
+    return {
+        trigger,
+        // Resolves once nothing is scheduled or running.
+        async settled() {
+            while (running !== undefined || again)
+                await (running ?? Promise.resolve());
+        },
+        stop() {
+            clearTimeout(timer);
+        },
+    };
+}
+// Runs once, then again whenever a `.sql` file under the folders changes, until `signal`
+// aborts. Only `.sql` changes count, so the modules a run writes don't trigger another.
+export async function watchAndRerun(options) {
+    const scheduler = createRerunScheduler(options);
+    try {
+        await options.run();
+    }
+    catch (error) {
+        options.onError(error);
+    }
+    const watchers = [];
+    for (const folder of options.folders) {
+        if (!existsSync(folder))
+            continue;
+        watchers.push(watch(folder, { recursive: true }, (_event, filename) => {
+            if (filename !== null && filename.endsWith('.sql'))
+                scheduler.trigger();
+        }));
+    }
+    await new Promise((resolve) => {
+        if (options.signal.aborted)
+            resolve();
+        options.signal.addEventListener('abort', () => resolve(), { once: true });
+    });
+    scheduler.stop();
+    for (const watcher of watchers)
+        watcher.close();
+    await scheduler.settled();
+}

package/dist/generator/generate.d.ts

@@ -0,0 +1,21 @@
+import type { Catalog, GenerateRequest, Options, Query } from './request.ts';
+export type OutputFile = {
+    name: string;
+    contents: string;
+};
+export type GenerateResult = {
+    ok: true;
+    files: OutputFile[];
+} | {
+    ok: false;
+    failures: string[];
+};
+export declare function readOptions(encoded: string): {
+    options: Options;
+    failures: string[];
+};
+export declare function generate(request: GenerateRequest): GenerateResult;
+export declare function correctNullability(query: Pick<Query, 'text' | 'columns'>, catalog: Catalog | null): {
+    notNull: boolean;
+    elementsNotNull: boolean;
+}[];