@bockit/sequel 0.0.0-stage → 0.2.0

package/dist/config/load-config.js

@@ -0,0 +1,34 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SequelError } from '../errors.js';
+import { resolveConfig } from './resolve-config.js';
+export const CONFIG_FILE = 'sequel.config.ts';
+// Loads `sequel.config.ts` from `cwd`, or the file `--config` names, by dynamic import under
+// Node's type stripping, then validates it and resolves its paths.
+export async function loadConfig(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const file = path.resolve(cwd, options.config ?? CONFIG_FILE);
+    if (!existsSync(file)) {
+        throw new SequelError(options.config === undefined
+            ? `No ${CONFIG_FILE} in ${cwd}. Create one that default-exports \`defineConfig({ … })\`, or pass --config <file>.`
+            : `The config file ${file}, named by --config, does not exist.`);
+    }
+    let module;
+    try {
+        module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SequelError(`${file} failed to load: ${reason}\nIt runs under Node's type stripping, so it may use only erasable TypeScript syntax.`);
+    }
+    return resolveConfig(module.default, file);
+}

package/dist/config/resolve-config.d.ts

@@ -0,0 +1,35 @@
+import type { BigintMode } from './define-config.ts';
+export type DatabaseRole = 'target' | 'test' | 'shadow';
+export type ResolvedConfig = {
+    configFile: string;
+    root: string;
+    schema: string;
+    migrations: string;
+    queries: string[];
+    snapshot: string;
+    databases: Record<DatabaseRole, string | undefined>;
+    timeouts: {
+        lockMs: number;
+        statementMs: number;
+    };
+    lint: {
+        cutover: string | undefined;
+    };
+    types: {
+        bigint: BigintMode;
+    };
+    externalMigrations: boolean;
+};
+export declare const DEFAULTS: {
+    readonly schema: 'prisma';
+    readonly migrations: 'prisma/migrations';
+    readonly queries: readonly ['src/**/queries'];
+    readonly snapshotFile: 'snapshot.sql';
+    readonly timeouts: {
+        readonly lockMs: 5000;
+        readonly statementMs: 60000;
+    };
+    readonly bigint: 'string';
+};
+export declare function resolveConfig(value: unknown, configFile: string): ResolvedConfig;
+export declare function requireDatabase(config: ResolvedConfig, role: DatabaseRole): string;

package/dist/config/resolve-config.js

@@ -0,0 +1,159 @@
+import path from 'node:path';
+import { SequelError } from '../errors.js';
+export const DEFAULTS = {
+    schema: 'prisma',
+    migrations: 'prisma/migrations',
+    queries: ['src/**/queries'],
+    snapshotFile: 'snapshot.sql',
+    timeouts: { lockMs: 5_000, statementMs: 60_000 },
+    bigint: 'string',
+};
+const KEYS = {
+    '': [
+        'schema',
+        'migrations',
+        'queries',
+        'snapshot',
+        'databases',
+        'timeouts',
+        'lint',
+        'types',
+        'externalMigrations',
+    ],
+    databases: ['target', 'test', 'shadow'],
+    timeouts: ['lockMs', 'statementMs'],
+    lint: ['cutover'],
+    types: ['bigint'],
+};
+const BIGINT_MODES = ['string', 'number', 'bigint'];
+const IDENTITY = /^\d{14}_[a-z0-9_]+$/;
+// Validates a loaded config and applies the defaults. `configFile` is absolute, and every
+// path in the config resolves against its folder.
+export function resolveConfig(value, configFile) {
+    const file = path.basename(configFile);
+    const fail = (key, problem) => {
+        throw new SequelError(`${file}: \`${key}\` ${problem}`);
+    };
+    const config = section(value, '', file, fail);
+    const databases = section(config.databases, 'databases', file, fail);
+    const timeouts = section(config.timeouts, 'timeouts', file, fail);
+    const lint = section(config.lint, 'lint', file, fail);
+    const types = section(config.types, 'types', file, fail);
+    const root = path.dirname(configFile);
+    const resolve = (relative) => path.resolve(root, relative);
+    const schema = resolve(pathValue(config.schema, 'schema', fail) ?? DEFAULTS.schema);
+    const migrations = resolve(pathValue(config.migrations, 'migrations', fail) ?? DEFAULTS.migrations);
+    const snapshotPath = pathValue(config.snapshot, 'snapshot', fail);
+    const snapshot = snapshotPath ? resolve(snapshotPath) : path.join(schema, DEFAULTS.snapshotFile);
+    const queryGlobs = config.queries === undefined ? DEFAULTS.queries : config.queries;
+    const queryList = typeof queryGlobs === 'string' ? [queryGlobs] : queryGlobs;
+    if (!Array.isArray(queryList) || queryList.length === 0) {
+        fail('queries', 'must be a glob or a non-empty list of globs, such as `src/**/queries`.');
+    }
+    const queries = queryList.map((glob, i) => resolve(pathValue(glob, `queries[${i}]`, fail)));
+    const resolvedDatabases = {
+        target: connection(databases.target, 'target', fail),
+        test: connection(databases.test, 'test', fail),
+        shadow: connection(databases.shadow, 'shadow', fail),
+    };
+    if (resolvedDatabases.shadow !== undefined) {
+        const name = databaseName(resolvedDatabases.shadow);
+        if (!name.endsWith('_shadow')) {
+            fail('databases.shadow', `names the database \`${name}\`, but a shadow database's name must end in \`_shadow\`, because sequel wipes it at each use. Point it at a database such as \`${name || 'app'}_shadow\`.`);
+        }
+    }
+    const cutover = lint.cutover;
+    if (cutover !== undefined && (typeof cutover !== 'string' || !IDENTITY.test(cutover))) {
+        fail('lint.cutover', 'must be a migration identity, `<YYYYMMDDHHMMSS>_<name>`: the file name of the newest migration not to lint, without `.sql`.');
+    }
+    const bigint = types.bigint ?? DEFAULTS.bigint;
+    if (!BIGINT_MODES.includes(bigint)) {
+        fail('types.bigint', `must be one of ${BIGINT_MODES.map((m) => `'${m}'`).join(', ')}.`);
+    }
+    const external = config.externalMigrations ?? false;
+    if (typeof external !== 'boolean') {
+        fail('externalMigrations', 'must be `true` or `false`: `true` when another tool manages the schema and migrations.');
+    }
+    return {
+        configFile,
+        root,
+        schema,
+        migrations,
+        queries,
+        snapshot,
+        databases: resolvedDatabases,
+        timeouts: {
+            lockMs: milliseconds(timeouts.lockMs, 'timeouts.lockMs', fail) ?? DEFAULTS.timeouts.lockMs,
+            statementMs: milliseconds(timeouts.statementMs, 'timeouts.statementMs', fail) ??
+                DEFAULTS.timeouts.statementMs,
+        },
+        lint: { cutover: cutover },
+        types: { bigint: bigint },
+        externalMigrations: external,
+    };
+}
+// Returns the connection string for a database a command needs, or explains how to set it.
+export function requireDatabase(config, role) {
+    const url = config.databases[role];
+    if (url === undefined) {
+        throw new SequelError(`${path.basename(config.configFile)}: \`databases.${role}\` is not set. Set the environment variable the config reads it from.`);
+    }
+    return url;
+}
+function section(value, key, file, fail) {
+    if (value === undefined && key !== '')
+        return {};
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        if (key === '') {
+            throw new SequelError(`${file} must default-export its config: \`export default defineConfig({ … })\`.`);
+        }
+        fail(key, 'must be an object.');
+    }
+    const record = value;
+    const known = KEYS[key] ?? [];
+    for (const name of Object.keys(record).sort()) {
+        if (!known.includes(name)) {
+            const full = key ? `${key}.${name}` : name;
+            fail(full, `is not a config key. Known keys${key ? ` of \`${key}\`` : ''}: ${known.join(', ')}.`);
+        }
+    }
+    return record;
+}
+function pathValue(value, key, fail) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '')
+        fail(key, 'must be a non-empty path.');
+    return value;
+}
+function connection(value, role, fail) {
+    // An unset environment variable reads as undefined, or as '' in some shells and CI systems.
+    if (value === undefined || value === '')
+        return undefined;
+    const key = `databases.${role}`;
+    if (typeof value !== 'string')
+        fail(key, 'must be a connection string.');
+    const url = value;
+    let protocol;
+    try {
+        protocol = new URL(url).protocol;
+    }
+    catch {
+        return fail(key, 'is not a valid connection URL, such as `postgres://user@host:5432/db`.');
+    }
+    if (protocol !== 'postgres:' && protocol !== 'postgresql:') {
+        fail(key, 'must be a `postgres://` or `postgresql://` URL.');
+    }
+    return url;
+}
+function databaseName(url) {
+    return decodeURIComponent(new URL(url).pathname.replace(/^\//, ''));
+}
+function milliseconds(value, key, fail) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        fail(key, 'must be a positive whole number of milliseconds.');
+    }
+    return value;
+}

package/dist/db/connection.d.ts

@@ -0,0 +1,6 @@
+import pg from 'pg';
+export declare function withClient<T>(url: string, fn: (client: pg.Client) => Promise<T>): Promise<T>;
+export declare function databaseName(url: string): string;
+export declare function withDatabaseName(url: string, name: string): string;
+export declare function quoteIdent(name: string): string;
+export declare function redactUrl(url: string): string;

package/dist/db/connection.js

@@ -0,0 +1,38 @@
+import pg from 'pg';
+// Runs `fn` with one connection to `url`, and always closes it.
+export async function withClient(url, fn) {
+    const client = new pg.Client({ connectionString: url });
+    await client.connect();
+    try {
+        return await fn(client);
+    }
+    finally {
+        await client.end().catch(() => { });
+    }
+}
+// The database a connection URL names, such as `app_test` in `postgres://host/app_test`.
+export function databaseName(url) {
+    return decodeURIComponent(new URL(url).pathname.replace(/^\//, ''));
+}
+// The same server and credentials, connecting to another database.
+export function withDatabaseName(url, name) {
+    const parsed = new URL(url);
+    parsed.pathname = `/${encodeURIComponent(name)}`;
+    return parsed.toString();
+}
+// A Postgres identifier, quoted, for the statements that can't take parameters.
+export function quoteIdent(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+// The URL with any password replaced, for messages.
+export function redactUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.password !== '')
+            parsed.password = '***';
+        return parsed.toString();
+    }
+    catch {
+        return '<invalid URL>';
+    }
+}

package/dist/db/shadow.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedConfig } from '../config/resolve-config.ts';
+export declare function assertShadowName(name: string): void;
+export type ShadowOptions = {
+    fixedUrl: string;
+} | {
+    testUrl: string;
+};
+export declare function shadowOptions(config: ResolvedConfig): ShadowOptions;
+export declare function withShadowDatabase<T>(options: ShadowOptions, fn: (url: string) => Promise<T>): Promise<T>;
+export declare function dropShadowDatabase(serverUrl: string, name: string): Promise<void>;
+export declare function wipeShadowDatabase(url: string): Promise<void>;

package/dist/db/shadow.js

@@ -0,0 +1,68 @@
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { SequelError } from '../errors.js';
+import { databaseName, quoteIdent, redactUrl, withClient, withDatabaseName } from './connection.js';
+// TECH-SPEC §8: every code path that wipes or drops a database checks its name first.
+export function assertShadowName(name) {
+    if (!name.endsWith('_shadow')) {
+        throw new SequelError(`Refusing to wipe the database \`${name}\`: sequel only wipes shadow databases, whose names end in \`_shadow\`.`);
+    }
+}
+// Where a command's shadow database comes from: the fixed one if the config names it, else one
+// of its own on the test database's server.
+export function shadowOptions(config) {
+    const { shadow, test } = config.databases;
+    if (shadow !== undefined)
+        return { fixedUrl: shadow };
+    if (test !== undefined)
+        return { testUrl: test };
+    throw new SequelError(`${path.basename(config.configFile)}: sequel needs a shadow database, and neither \`databases.test\` nor \`databases.shadow\` is set. Set \`databases.test\`, and sequel creates one on its server for each run, or set \`databases.shadow\` to a database whose name ends in \`_shadow\`.`);
+}
+// Runs `fn` with an empty shadow database. By default it is a new `sequel_<random>_shadow` on
+// the test database's server, dropped afterwards, even on failure or interruption.
+export async function withShadowDatabase(options, fn) {
+    if ('fixedUrl' in options) {
+        await wipeShadowDatabase(options.fixedUrl);
+        return fn(options.fixedUrl);
+    }
+    const name = `sequel_${randomBytes(6).toString('hex')}_shadow`;
+    try {
+        await withClient(options.testUrl, (client) => client.query(`CREATE DATABASE ${quoteIdent(name)}`));
+    }
+    catch (error) {
+        throw new SequelError(`Could not create a shadow database on the test database's server (${redactUrl(options.testUrl)}): ${error.message}\nThe test database's role needs CREATEDB. Where it can't have it, set \`databases.shadow\` to a fixed database whose name ends in \`_shadow\`.`);
+    }
+    const drop = () => dropShadowDatabase(options.testUrl, name);
+    const onSignal = (signal) => {
+        void drop().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        return await fn(withDatabaseName(options.testUrl, name));
+    }
+    finally {
+        process.off('SIGINT', onSignal);
+        process.off('SIGTERM', onSignal);
+        await drop();
+    }
+}
+// Drops a shadow database through a connection to another database on its server.
+export async function dropShadowDatabase(serverUrl, name) {
+    assertShadowName(name);
+    await withClient(serverUrl, (client) => client.query(`DROP DATABASE IF EXISTS ${quoteIdent(name)} WITH (FORCE)`));
+}
+// Empties a fixed shadow database in place, for a role that can't create databases: every
+// schema but Postgres's own is dropped, extensions with it, and `public` is recreated.
+export async function wipeShadowDatabase(url) {
+    assertShadowName(databaseName(url));
+    await withClient(url, async (client) => {
+        const { rows } = await client.query(`SELECT nspname FROM pg_namespace
+       WHERE nspname NOT LIKE 'pg\\_%' AND nspname <> 'information_schema'
+       ORDER BY nspname`);
+        for (const { nspname } of rows) {
+            await client.query(`DROP SCHEMA ${quoteIdent(nspname)} CASCADE`);
+        }
+        await client.query('CREATE SCHEMA public');
+    });
+}

package/dist/engine/client.d.ts

@@ -0,0 +1,24 @@
+export type EngineCall<T> = {
+    result: T;
+    printed: string[];
+};
+export type Engine = {
+    request<T>(method: string, params: unknown): Promise<EngineCall<T>>;
+    close(): Promise<void>;
+};
+export declare class EngineError extends Error {
+    name: string;
+    readonly code: number;
+    readonly data: {
+        error_code?: string;
+        message?: string;
+        is_panic?: boolean;
+    } | undefined;
+    constructor(code: number, message: string, data: EngineError['data']);
+}
+export declare function startSchemaEngine(binary: string, cwd: string): Engine;
+export declare function startEngine(options: {
+    command: string;
+    args: string[];
+    cwd: string;
+}): Engine;

package/dist/engine/client.js

@@ -0,0 +1,123 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+// A JSON-RPC error from the engine. `data` carries the engine's own error, such as
+// `{ error_code: 'P1003', message: 'Database … does not exist' }`.
+export class EngineError extends Error {
+    name = 'EngineError';
+    code;
+    data;
+    constructor(code, message, data) {
+        super(data?.message ?? message);
+        this.code = code;
+        this.data = data;
+    }
+}
+// Spawns the native schema engine. The 7.x engine won't start without `--datasource`; the
+// connection travels in each request, so the flag is always `{}`, and `ps` never shows a URL.
+export function startSchemaEngine(binary, cwd) {
+    return startEngine({ command: binary, args: ['--datasource', '{}'], cwd });
+}
+export function startEngine(options) {
+    const child = spawn(options.command, options.args, {
+        cwd: options.cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stderr = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+        stderr += chunk;
+    });
+    // A write after the engine has gone fails here, and the call is rejected by `gone` instead.
+    child.stdin.on('error', () => { });
+    let nextId = 1;
+    let current;
+    let ended;
+    const send = (message) => child.stdin.write(`${JSON.stringify(message)}\n`);
+    const gone = (reason) => {
+        if (ended !== undefined)
+            return;
+        ended = new Error(`The schema engine ${reason}.${stderr.trim() === '' ? '' : `\nIts stderr:\n${stderr.trim()}`}`);
+        current?.reject(ended);
+        current = undefined;
+    };
+    child.on('error', (error) => gone(`could not run: ${error.message}`));
+    child.on('exit', (code, signal) => gone(`exited${signal ? ` on ${signal}` : ` with code ${code}`}`));
+    const lines = createInterface({ input: child.stdout });
+    lines.on('close', () => gone('closed its output'));
+    lines.on('line', (line) => {
+        if (line.trim() === '')
+            return;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            stderr += `${line}\n`;
+            return;
+        }
+        if (typeof message.method === 'string') {
+            // A request from the engine. A notification, with no id, needs no answer.
+            if (message.id === undefined || message.id === null)
+                return;
+            if (message.method === 'print') {
+                if (typeof message.params?.content === 'string') {
+                    current?.printed.push(message.params.content);
+                }
+                send({ id: message.id, jsonrpc: '2.0', result: {} });
+            }
+            else {
+                send({
+                    id: message.id,
+                    jsonrpc: '2.0',
+                    error: { code: -32601, message: `sequel does not handle ${message.method}` },
+                });
+            }
+            return;
+        }
+        if (current !== undefined && message.id === current.id)
+            current.resolve(message);
+    });
+    let queue = Promise.resolve();
+    const call = (method, params) => new Promise((resolve, reject) => {
+        if (ended !== undefined) {
+            reject(ended);
+            return;
+        }
+        const id = nextId++;
+        const printed = [];
+        current = {
+            id,
+            printed,
+            resolve: (message) => {
+                current = undefined;
+                if (message.error !== undefined) {
+                    const { code, message: text, data } = message.error;
+                    reject(new EngineError(code, text, data));
+                }
+                else {
+                    resolve({ result: message.result, printed });
+                }
+            },
+            reject,
+        };
+        send({ jsonrpc: '2.0', id, method, params });
+    });
+    return {
+        request(method, params) {
+            const next = queue.then(() => call(method, params));
+            queue = next.catch(() => { });
+            return next;
+        },
+        async close() {
+            ended ??= new Error('The schema engine was closed.');
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            const exited = new Promise((resolve) => child.once('exit', () => resolve()));
+            child.stdin.end();
+            const timer = setTimeout(() => child.kill('SIGKILL'), 2_000);
+            child.kill('SIGTERM');
+            await exited;
+            clearTimeout(timer);
+        },
+    };
+}

package/dist/engine/diff.d.ts

@@ -0,0 +1,12 @@
+import type { SchemaFile } from '../schema/schema.ts';
+import { type Engine } from './client.ts';
+export type DiffResult = {
+    changed: boolean;
+    sql: string;
+};
+export type DiffFrom = {
+    url: string;
+    historySchema: string;
+} | 'empty';
+export declare function diffToSchema(engine: Engine, from: DiffFrom, files: SchemaFile[]): Promise<DiffResult>;
+export declare function engineUrl(url: string): string;

package/dist/engine/diff.js

@@ -0,0 +1,51 @@
+import pg from 'pg';
+import { databaseName, redactUrl } from '../db/connection.js';
+import { SequelError } from '../errors.js';
+import { HISTORY_TABLE } from '../migrate/history.js';
+import { EngineError } from './client.js';
+// TECH-SPEC §7: the engine's `diff`, from a database (a shadow with the migrations replayed
+// into it), or from nothing, to the schema folder.
+export async function diffToSchema(engine, from, files) {
+    const params = {
+        from: from === 'empty' ? { tag: 'empty' } : { tag: 'url', url: engineUrl(from.url) },
+        to: {
+            tag: 'schemaDatamodel',
+            files: files.map((file) => ({ path: file.relative, content: file.content })),
+        },
+        script: true,
+        exitCode: true,
+        filters: {
+            // The engine ignores only `_prisma_migrations`, so it would drop sequel's history as drift.
+            externalTables: from === 'empty' ? [] : [`${from.historySchema}.${HISTORY_TABLE}`],
+            externalEnums: [],
+        },
+    };
+    try {
+        const { result, printed } = await engine.request('diff', params);
+        return {
+            changed: result.exitCode === 2,
+            sql: printed.map((content) => `${content}\n`).join(''),
+        };
+    }
+    catch (error) {
+        const source = from === 'empty' ? 'an empty database' : databaseName(from.url);
+        if (error instanceof EngineError) {
+            const code = error.data?.error_code;
+            throw new SequelError(`The schema engine could not diff ${source} against the schema folder: ${code === undefined ? '' : `${code}: `}${error.message}`);
+        }
+        throw new SequelError(`The schema engine failed while diffing ${source} against the schema folder: ${error.message}`);
+    }
+}
+// The engine doesn't default the user as `pg` does, so a URL without one gets `pg`'s default,
+// such as the OS user, before the engine sees it.
+export function engineUrl(url) {
+    const parsed = new URL(url);
+    if (parsed.username === '') {
+        const user = process.env.PGUSER || pg.defaults.user;
+        if (user === undefined || user === '') {
+            throw new SequelError(`${redactUrl(url)} names no user, and there is no default to fill in. Put the user in the URL.`);
+        }
+        parsed.username = encodeURIComponent(user);
+    }
+    return parsed.toString();
+}

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class SequelError extends Error {
+    name: string;
+}

package/dist/errors.js

@@ -0,0 +1,5 @@
+// An expected failure: the CLI prints its message, with no stack, and exits 1.
+// The message names the file, query or statement, and what to do about it.
+export class SequelError extends Error {
+    name = 'SequelError';
+}

package/dist/extras/snapshot.d.ts

@@ -0,0 +1,3 @@
+import type pg from 'pg';
+export declare function readExtrasSnapshot(url: string): Promise<string>;
+export declare function extrasSnapshot(client: pg.Client): Promise<string>;