@bockit/sequel 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { ensureBinary } from './binaries/ensure-binary.js';
+import { checkFailureMessage, runChecks } from './check.js';
+import { loadConfig } from './config/load-config.js';
+import { requireDatabase } from './config/resolve-config.js';
+import { SequelError } from './errors.js';
+import { readExtrasSnapshot } from './extras/snapshot.js';
+import { writeAtomically } from './files.js';
+import { generateModules } from './generate/generate-modules.js';
+import { findQueryFolders } from './generate/modules.js';
+import { watchAndRerun } from './generate/watch.js';
+import { databaseName } from './db/connection.js';
+import { adoptPrismaFiles, adoptPrismaHistory, PRISMA_LOCK_FILE } from './migrate/adopt-prisma.js';
+import { deployTo } from './migrate/deploy.js';
+import { findMigrations, readMigrationFile } from './migrate/files.js';
+import { lintFailureMessage, lintMigrations, migrationsToLint } from './migrate/lint.js';
+import { newMigration } from './migrate/new.js';
+import { assertValidSchema, formatSchemaFiles, readSchemaFiles, schemaWarnings, } from './schema/schema.js';
+import { unsupportedColumns } from './schema/unsupported.js';
+const OPTIONS = {
+    help: { type: 'boolean', short: 'h' },
+    config: { type: 'string', short: 'c' },
+    watch: { type: 'boolean' },
+    'allow-out-of-order': { type: 'boolean' },
+};
+async function validate(context) {
+    const config = await load(context);
+    const files = await readSchemaFiles(config.schema, config.root);
+    assertValidSchema(files, config.root);
+    for (const warning of schemaWarnings(files, config.root)) {
+        out(`${warning.shown}:${warning.line}: warning: ${warning.message}`);
+    }
+    out(`The schema is valid: ${plural(files.length, 'file')} in ${shown(config, config.schema)}.`);
+}
+async function format(context) {
+    const config = await load(context);
+    const changed = await formatSchemaFiles(await readSchemaFiles(config.schema, config.root), config.root);
+    for (const file of changed)
+        out(`Formatted ${shown(config, file)}`);
+    if (changed.length === 0)
+        out(`The schema is already formatted.`);
+}
+async function migrateNew(context) {
+    const config = await load(context);
+    const { file, findings } = await newMigration({ config, name: context.positionals[0] });
+    if (file === undefined) {
+        out('The migrations already match the schema: no migration written.');
+        return;
+    }
+    out(`Wrote ${shown(config, file)}`);
+    if (findings.length > 0) {
+        throw new SequelError(`${lintFailureMessage(findings)}\n${shown(config, file)} stays written: fix it before committing.`);
+    }
+    out('Lint: no findings.');
+}
+async function migrateLint(context) {
+    const config = await load(context);
+    const migrations = context.positionals.length > 0
+        ? await Promise.all(context.positionals.map(async (given) => {
+            const file = path.resolve(given);
+            if (!existsSync(file))
+                throw new SequelError(`${given} does not exist.`);
+            return readMigrationFile(file, config.root);
+        }))
+        : migrationsToLint(await findMigrations(config.migrations, { root: config.root }), config.lint.cutover);
+    // The index rule reads the schema folder; without one, it is skipped.
+    const schema = await readSchemaFiles(config.schema, config.root).catch((error) => {
+        if (error instanceof SequelError)
+            return undefined;
+        throw error;
+    });
+    const findings = await lintMigrations({
+        squawk: await ensureBinary('squawk'),
+        migrations,
+        root: config.root,
+        ...(schema === undefined ? {} : { unsupported: unsupportedColumns(schema) }),
+    });
+    if (findings.length > 0)
+        throw new SequelError(lintFailureMessage(findings));
+    out(`${plural(migrations.length, 'migration file')} linted: no findings.`);
+}
+async function migrateAdoptPrisma(context) {
+    const config = await load(context);
+    const url = requireDatabase(config, 'target');
+    const files = await adoptPrismaFiles(config.migrations, config.root);
+    for (const { from, to } of files.renamed) {
+        out(`Renamed ${shown(config, from)} to ${shown(config, to)}`);
+    }
+    if (files.lockRemoved) {
+        out(`Removed ${shown(config, path.join(config.migrations, PRISMA_LOCK_FILE))}`);
+    }
+    if (files.renamed.length > 0 || files.lockRemoved) {
+        out('Commit the renamed files. Their contents are unchanged, so their checksums still match.');
+    }
+    else {
+        out("Files: none in Prisma's layout, so nothing to rename.");
+    }
+    const migrations = await findMigrations(config.migrations, { root: config.root });
+    const history = await adoptPrismaHistory({ url, migrations });
+    const database = databaseName(url);
+    if (history.status === 'adopted') {
+        out(`History: created sequel_migrations on ${database} from ${plural(history.rows, 'applied Prisma migration')}. _prisma_migrations is left as it was.`);
+    }
+    else if (history.status === 'already-adopted') {
+        out(`History: ${database} already has sequel_migrations, so nothing to adopt.`);
+    }
+    else {
+        out(`History: ${database} has no Prisma history (_prisma_migrations), so nothing to adopt. \`sequel migrate deploy\` creates sequel's history.`);
+    }
+}
+async function migrateDeploy(context) {
+    const config = await load(context);
+    await deployTo(config, requireDatabase(config, 'target'), {
+        allowOutOfOrder: context.flags['allow-out-of-order'],
+        log: out,
+    });
+}
+async function generate(context) {
+    const config = await load(context);
+    const url = requireDatabase(config, 'test');
+    const once = async () => {
+        await deployTo(config, url, { log: out, quietWhenCurrent: true });
+        const folders = await findQueryFolders(config.queries);
+        const result = await generateModules({
+            sqlc: await ensureBinary('sqlc'),
+            databaseUrl: url,
+            folders,
+            bigint: config.types.bigint,
+            root: config.root,
+        });
+        for (const file of result.written)
+            out(`Wrote ${shown(config, file)}`);
+        for (const file of result.deleted)
+            out(`Deleted ${shown(config, file)}: its query file is gone`);
+        if (result.written.length === 0 && result.deleted.length === 0) {
+            out(`The generated modules are up to date (${plural(result.unchanged.length, 'module')}).`);
+        }
+    };
+    if (!context.flags.watch) {
+        await once();
+        return;
+    }
+    const stop = new AbortController();
+    process.once('SIGINT', () => stop.abort());
+    process.once('SIGTERM', () => stop.abort());
+    const folders = [...(await findQueryFolders(config.queries)), config.migrations];
+    await watchAndRerun({
+        folders,
+        run: once,
+        onError: (error) => process.stderr.write(`${describeError(error)}\n`),
+        signal: stop.signal,
+    });
+}
+async function extras(context) {
+    const config = await load(context);
+    const url = requireDatabase(config, 'test');
+    await deployTo(config, url, { log: out, quietWhenCurrent: true });
+    const next = await readExtrasSnapshot(url);
+    const current = await readFile(config.snapshot, 'utf8').catch(() => undefined);
+    if (current === next) {
+        out(`The extras snapshot is up to date: ${shown(config, config.snapshot)}`);
+        return;
+    }
+    await mkdir(path.dirname(config.snapshot), { recursive: true });
+    await writeAtomically(config.snapshot, next);
+    out(`Wrote ${shown(config, config.snapshot)}`);
+}
+async function check(context) {
+    const config = await load(context);
+    const failures = await runChecks(config, out);
+    if (failures.length > 0)
+        throw new SequelError(checkFailureMessage(failures));
+    out('All checks passed.');
+}
+function load(context) {
+    return loadConfig({ config: context.config });
+}
+function shown(config, file) {
+    return path.relative(config.root, file) || '.';
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+function out(message) {
+    process.stdout.write(`${message}\n`);
+}
+const COMMANDS = {
+    validate: {
+        usage: 'validate',
+        summary: 'Check the schema folder, printing each error with its file and line.',
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: validate,
+    },
+    format: {
+        usage: 'format',
+        summary: 'Format every file in the schema folder in place.',
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: format,
+    },
+    'migrate new': {
+        usage: 'migrate new <name>',
+        summary: 'Diff the migration history against the schema and write a new migration.',
+        flags: [],
+        args: { min: 1, max: 1 },
+        run: migrateNew,
+    },
+    'migrate lint': {
+        usage: 'migrate lint [file…]',
+        summary: 'Lint the files given, or every migration after the lint cut-over.',
+        flags: [],
+        args: { min: 0, max: Infinity },
+        run: migrateLint,
+    },
+    'migrate adopt-prisma': {
+        usage: 'migrate adopt-prisma',
+        summary: "Move from Prisma's migration files and history to sequel's.",
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: migrateAdoptPrisma,
+    },
+    'migrate deploy': {
+        usage: 'migrate deploy [--allow-out-of-order]',
+        summary: 'Apply pending migrations to the target database.',
+        flags: ['allow-out-of-order'],
+        args: { min: 0, max: 0 },
+        run: migrateDeploy,
+    },
+    generate: {
+        usage: 'generate [--watch]',
+        summary: 'Migrate the test database, then write a typed module beside each query file.',
+        flags: ['watch'],
+        args: { min: 0, max: 0 },
+        run: generate,
+    },
+    extras: {
+        usage: 'extras',
+        summary: 'Migrate the test database, then rewrite the extras snapshot.',
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: extras,
+    },
+    check: {
+        usage: 'check',
+        summary: 'Fail on stale generated code, drift, lint findings or a stale snapshot.',
+        flags: [],
+        args: { min: 0, max: 0 },
+        run: check,
+    },
+};
+function help() {
+    const width = Math.max(...Object.values(COMMANDS).map((command) => command.usage.length));
+    const lines = Object.values(COMMANDS).map((command) => `  ${command.usage.padEnd(width)}  ${command.summary}`);
+    return [
+        'Usage: sequel <command> [options]',
+        '',
+        'Commands:',
+        ...lines,
+        '',
+        'Options:',
+        `  ${'-c, --config <file>'.padEnd(width)}  The config file. Default: sequel.config.ts`,
+        `  ${'-h, --help'.padEnd(width)}  Show this help.`,
+        '',
+    ].join('\n');
+}
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        // parseArgs reports unknown and malformed options as TypeErrors with a clear message.
+        throw new SequelError(`${error.message}\nRun \`sequel --help\` for usage.`);
+    }
+    const { values, positionals } = parsed;
+    const [first, second] = positionals;
+    const name = first === 'migrate' && second !== undefined ? `migrate ${second}` : first;
+    if (values.help || name === undefined) {
+        process.stdout.write(help());
+        return;
+    }
+    const command = COMMANDS[name];
+    if (command === undefined) {
+        const hint = first === 'migrate'
+            ? 'migrate needs a subcommand: new, lint, adopt-prisma or deploy.'
+            : `Unknown command \`${first}\`.`;
+        throw new SequelError(`${hint}\nRun \`sequel --help\` for usage.`);
+    }
+    for (const flag of ['watch', 'allow-out-of-order']) {
+        if (values[flag] && !command.flags.includes(flag)) {
+            throw new SequelError(`\`sequel ${name}\` has no --${flag} option. Usage: sequel ${command.usage}`);
+        }
+    }
+    const args = positionals.slice(name.split(' ').length);
+    if (args.length < command.args.min || args.length > command.args.max) {
+        throw new SequelError(`Usage: sequel ${command.usage}`);
+    }
+    await command.run({
+        config: values.config,
+        positionals: args,
+        flags: {
+            watch: values.watch ?? false,
+            'allow-out-of-order': values['allow-out-of-order'] ?? false,
+        },
+    });
+}
+// An expected failure is its message alone; anything else keeps its stack.
+function describeError(error) {
+    if (error instanceof SequelError)
+        return error.message;
+    return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}
+try {
+    await main(process.argv.slice(2));
+}
+catch (error) {
+    process.stderr.write(`${describeError(error)}\n`);
+    process.exitCode = 1;
+}

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

@@ -0,0 +1,23 @@
+export type SequelConfig = {
+    schema?: string;
+    migrations?: string;
+    queries?: string | string[];
+    snapshot?: string;
+    databases?: {
+        target?: string | undefined;
+        test?: string | undefined;
+        shadow?: string | undefined;
+    };
+    timeouts?: {
+        lockMs?: number;
+        statementMs?: number;
+    };
+    lint?: {
+        cutover?: string;
+    };
+    types?: {
+        bigint?: BigintMode;
+    };
+};
+export type BigintMode = 'string' | 'number' | 'bigint';
+export declare function defineConfig(config: SequelConfig): SequelConfig;

package/dist/config/define-config.js

@@ -0,0 +1,4 @@
+// An identity function that exists for its types: `export default defineConfig({ … })`.
+export function defineConfig(config) {
+    return config;
+}

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

@@ -0,0 +1,6 @@
+import { type ResolvedConfig } from './resolve-config.ts';
+export declare const CONFIG_FILE = "sequel.config.ts";
+export declare function loadConfig(options?: {
+    config?: string;
+    cwd?: string;
+}): Promise<ResolvedConfig>;

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,34 @@
+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;
+    };
+};
+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,144 @@
+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'],
+    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(', ')}.`);
+    }
+    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 },
+    };
+}
+// 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>;