@deterministic-code/migraters 0.0.2 → 0.0.4

package/{dist/migration-client.d.ts → typescript/src/migration-client.ts}

@@ -1,21 +1,21 @@
 export type MigrationRowValue = string | number | bigint | boolean | Date | null;
 export type MigrationRow = Record<string, MigrationRowValue>;
 export type MigrationSqlParam = string | number | bigint | boolean | Date | null;
+
 /** The subset of a better-sqlite3 Database that `insertLogStarted` reaches through `_raw` when a caller injects a synchronous handle. */
 export interface SqliteRawDatabase {
-    prepare(source: string): {
-        run(...params: MigrationSqlParam[]): {
-            lastInsertRowid: number | bigint;
-        };
-    };
+  prepare(source: string): {
+    run(...params: MigrationSqlParam[]): { lastInsertRowid: number | bigint };
+  };
 }
+
 /** Provider-agnostic migration client used by IMigrater.up, IMigrater.down, and IMigrater.setup. */
 export interface MigrationClient {
-    dialect: import('./sql.ts').SqlDialect;
-    exec(sql: string): Promise<void>;
-    query(sql: string, params?: MigrationSqlParam[]): Promise<MigrationRow[]>;
-    run(sql: string, params?: MigrationSqlParam[]): Promise<void>;
-    transaction<T>(fn: () => Promise<T>): Promise<T>;
-    close(): Promise<void>;
-    _raw?: SqliteRawDatabase;
+  dialect: import('./sql.ts').SqlDialect;
+  exec(sql: string): Promise<void>;
+  query(sql: string, params?: MigrationSqlParam[]): Promise<MigrationRow[]>;
+  run(sql: string, params?: MigrationSqlParam[]): Promise<void>;
+  transaction<T>(fn: () => Promise<T>): Promise<T>;
+  close(): Promise<void>;
+  _raw?: SqliteRawDatabase;
 }

package/typescript/src/path-exists.ts

@@ -0,0 +1,10 @@
+import { access } from 'node:fs/promises';
+
+export const pathExists = async (p: string): Promise<boolean> => {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+};

package/typescript/src/setup-sql.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { getMigrater } from './migrater.ts';
+import { defaultDialectFactory } from './infrastructure/default-factory.ts';
+
+describe('IMigrater setup bookkeeping', () => {
+  it('loads the shared DDL templates for every dialect', () => {
+    for (const dialect of defaultDialectFactory.all()) {
+      expect(dialect.migratesDdl).toMatch(/migrates/i);
+      expect(dialect.migrateLogsDdl).toMatch(/migrate_logs/i);
+    }
+  });
+
+  it('rejects an unknown dialect', () => {
+    expect(() => getMigrater('dbase')).toThrow(/Unknown SQL dialect/);
+  });
+});

package/typescript/src/sql.ts

@@ -0,0 +1,17 @@
+import { cliSpec } from './cli-spec.ts';
+
+export type SqlDialect = 'sqlite' | 'mysql' | 'postgres' | 'sqlserver' | 'oracle';
+
+const stripKey = (raw: string): string => raw.toLowerCase().replace(/[\s_\-]/g, '');
+
+export const normalizeDialect = (raw: string | null | undefined): SqlDialect | null => {
+  if (!raw) return null;
+  const key = stripKey(raw);
+  if ((cliSpec.providers as string[]).includes(key)) return key as SqlDialect;
+  for (const [alias, canonical] of Object.entries(cliSpec.provider_aliases ?? {})) {
+    if (stripKey(alias) === key) return canonical as SqlDialect;
+  }
+  return null;
+};
+
+export { pathExists } from './path-exists.ts';

package/typescript/tsconfig.build.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "skipLibCheck": true,
+    "noCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts", "dialects/*/src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "src/generate-help.ts", "dialects/**/*.test.ts"]
+}

package/dist/abstractions/migrater.d.ts

@@ -1,28 +0,0 @@
-export type SetupArg = {
-    connection: string;
-    migrationsPath: string;
-};
-export type UpArg = {
-    connection: string;
-    migrationsPath: string;
-    one?: boolean;
-};
-export type DownArg = {
-    connection: string;
-    migrationsPath: string;
-};
-export type CreateArg = {
-    name: string;
-    migrationsPath: string;
-};
-export type CreateResponse = {
-    upName: string;
-    downName: string;
-};
-export interface IMigrater {
-    readonly name: string;
-    setup(args: SetupArg): Promise<void>;
-    up(args: UpArg): Promise<string[]>;
-    down(args: DownArg): Promise<string | null>;
-    create(args: CreateArg): Promise<CreateResponse>;
-}

package/dist/abstractions/migrater.js

@@ -1 +0,0 @@
-export {};

package/dist/abstractions/sql-dialect-base.d.ts

@@ -1,16 +0,0 @@
-import type { SqlDialect } from '../sql.ts';
-import type { ISqlDialect } from './sql-dialect.ts';
-export declare abstract class SqlDialectBase implements ISqlDialect {
-    abstract readonly name: SqlDialect;
-    abstract readonly connectionEnvironmentVariables: readonly string[];
-    abstract readonly migratesDdl: string;
-    abstract readonly migrateLogsDdl: string;
-    readonly usesLastInsertRowid: boolean;
-    quoteIdent(ident: string): string;
-    nowExpr(): string;
-    limitClause(n: number): string;
-    translatePlaceholders(sql: string): string;
-    prerequisiteError(_connection: string): Promise<string | null>;
-    prepareSetup(_connection: string): Promise<void>;
-    abstract createClient(connection: string): Promise<import('../migration-client.ts').MigrationClient>;
-}

package/dist/abstractions/sql-dialect-base.js

@@ -1,19 +0,0 @@
-export class SqlDialectBase {
-    usesLastInsertRowid = false;
-    quoteIdent(ident) {
-        return `"${ident}"`;
-    }
-    nowExpr() {
-        return 'CURRENT_TIMESTAMP';
-    }
-    limitClause(n) {
-        return `LIMIT ${n}`;
-    }
-    translatePlaceholders(sql) {
-        return sql;
-    }
-    async prerequisiteError(_connection) {
-        return null;
-    }
-    async prepareSetup(_connection) { }
-}

package/dist/abstractions/sql-dialect-factory.d.ts

@@ -1,8 +0,0 @@
-import type { ISqlDialect } from './sql-dialect.ts';
-export declare class SqlDialectFactory {
-    private readonly byName;
-    constructor(dialects: readonly ISqlDialect[]);
-    tryGet(raw: string): ISqlDialect | undefined;
-    get(raw: string): ISqlDialect;
-    all(): readonly ISqlDialect[];
-}

package/dist/abstractions/sql-dialect-factory.js

@@ -1,22 +0,0 @@
-import { normalizeDialect } from "../sql.js";
-const VALID = 'sqlite, mysql, postgres, sqlserver, oracle';
-export class SqlDialectFactory {
-    byName;
-    constructor(dialects) {
-        this.byName = new Map(dialects.map((d) => [d.name, d]));
-    }
-    tryGet(raw) {
-        const key = normalizeDialect(raw);
-        return key ? this.byName.get(key) : undefined;
-    }
-    get(raw) {
-        const dialect = this.tryGet(raw);
-        if (!dialect) {
-            throw new Error(`Unknown SQL dialect "${raw}". Valid: ${VALID}.`);
-        }
-        return dialect;
-    }
-    all() {
-        return [...this.byName.values()];
-    }
-}

package/dist/abstractions/sql-dialect.d.ts

@@ -1,16 +0,0 @@
-import type { MigrationClient } from '../migration-client.ts';
-import type { SqlDialect } from '../sql.ts';
-export interface ISqlDialect {
-    readonly name: SqlDialect;
-    readonly connectionEnvironmentVariables: readonly string[];
-    readonly migratesDdl: string;
-    readonly migrateLogsDdl: string;
-    readonly usesLastInsertRowid: boolean;
-    quoteIdent(ident: string): string;
-    nowExpr(): string;
-    limitClause(n: number): string;
-    translatePlaceholders(sql: string): string;
-    prerequisiteError(connection: string): Promise<string | null>;
-    prepareSetup(connection: string): Promise<void>;
-    createClient(connection: string): Promise<MigrationClient>;
-}

package/dist/abstractions/sql-dialect.js

@@ -1 +0,0 @@
-export {};

package/dist/bin/migrate-create.js

@@ -1,71 +0,0 @@
-#!/usr/bin/env node
-// Scaffolds a new <NNNN>_<name>_{up,down}.sql pair in the migrations directory. Numbering is max(1-4-digit prefix in dir)+1; legacy timestamp prefixes are ignored.
-import { missingProviderMsg, requireDialect, takeFlag } from "../cli.js";
-import { isMigrationName } from "../create-sequence.js";
-import { fillTemplate, loadMessage } from "../infrastructure/message-templates.js";
-import { loadHelp, Migrater } from "../index.js";
-const [HELP_TEXT, unknownArgTpl, missingNameMsg, invalidNameTpl, createdTpl] = await Promise.all([
-    loadHelp('migrate-create'),
-    loadMessage('errors/unknown-arg'),
-    loadMessage('errors/missing-name'),
-    loadMessage('errors/invalid-name'),
-    loadMessage('status/created'),
-]);
-const parseArgs = (argv) => {
-    const args = { provider: null, name: null, migrationsPath: null };
-    const rest = argv.slice(2);
-    for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === '-h' || a === '--help') {
-            process.stderr.write(HELP_TEXT);
-            process.exit(0);
-        }
-        let taken;
-        if ((taken = takeFlag(rest, i, a, '--provider'))) {
-            args.provider = taken.value;
-            i = taken.next;
-        }
-        else if ((taken = takeFlag(rest, i, a, '--name'))) {
-            args.name = taken.value;
-            i = taken.next;
-        }
-        else if ((taken = takeFlag(rest, i, a, '--migrations-path')) ||
-            (taken = takeFlag(rest, i, a, '--migrate-path'))) {
-            args.migrationsPath = taken.value;
-            i = taken.next;
-        }
-        else {
-            process.stderr.write(fillTemplate(unknownArgTpl, { arg: a }));
-            process.exit(2);
-        }
-    }
-    return args;
-};
-const main = async () => {
-    const args = parseArgs(process.argv);
-    if (!args.provider) {
-        process.stderr.write(missingProviderMsg);
-        process.exit(2);
-    }
-    const dialect = requireDialect(args.provider);
-    if (!args.name) {
-        process.stderr.write(missingNameMsg);
-        process.exit(2);
-    }
-    if (!isMigrationName(args.name)) {
-        process.stderr.write(fillTemplate(invalidNameTpl, { name: args.name }));
-        process.exit(2);
-    }
-    const migrationsPath = args.migrationsPath ?? `./sql/${dialect.name}/migrations`;
-    const { upName, downName } = await new Migrater(dialect).create({
-        name: args.name,
-        migrationsPath,
-    });
-    process.stdout.write(fillTemplate(createdTpl, { file: upName }));
-    process.stdout.write(fillTemplate(createdTpl, { file: downName }));
-};
-main().catch((e) => {
-    const err = e;
-    process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
-    process.exit(1);
-});

package/dist/bin/migrate-down.js

@@ -1,135 +0,0 @@
-#!/usr/bin/env node
-// Rolls back the most recently applied migration (one step). DESTRUCTIVE: prints a random 4-letter uppercase confirmation token and refuses to proceed unless the user types it back on stdin. Pass --confirm <TOKEN> matching the printed token to bypass the interactive prompt (CI / scripted use).
-import { resolve } from 'node:path';
-import { createInterface } from 'node:readline/promises';
-import { missingProviderMsg, requireConnection, requireDialect, takeFlag } from "../cli.js";
-import { fillTemplate, loadMessage } from "../infrastructure/message-templates.js";
-import { loadHelp, Migrater } from "../index.js";
-const [HELP_TEXT, unknownArgTpl, destructiveHeaderTpl, confirmMismatchTpl, confirmTtyRequiredTpl, confirmPromptTpl, confirmTokenMismatchMsg, noRollbackMsg, rolledBackTpl,] = await Promise.all([
-    loadHelp('migrate-down'),
-    loadMessage('errors/unknown-arg'),
-    loadMessage('down/destructive-header'),
-    loadMessage('down/confirm-mismatch'),
-    loadMessage('down/confirm-tty-required'),
-    loadMessage('down/confirm-prompt'),
-    loadMessage('down/confirm-token-mismatch'),
-    loadMessage('status/no-rollback'),
-    loadMessage('status/rolled-back'),
-]);
-const parseArgs = (argv) => {
-    const args = {
-        provider: null,
-        migratePath: null,
-        migrateRoot: null,
-        connection: null,
-        confirm: null,
-    };
-    const rest = argv.slice(2);
-    for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === '-h' || a === '--help') {
-            process.stderr.write(HELP_TEXT);
-            process.exit(0);
-        }
-        let taken;
-        if ((taken = takeFlag(rest, i, a, '--provider'))) {
-            args.provider = taken.value;
-            i = taken.next;
-        }
-        else if ((taken = takeFlag(rest, i, a, '--migrations-path')) ||
-            (taken = takeFlag(rest, i, a, '--migrate-path'))) {
-            args.migratePath = taken.value;
-            i = taken.next;
-        }
-        else if ((taken = takeFlag(rest, i, a, '--migrations-root')) ||
-            (taken = takeFlag(rest, i, a, '--migrate-root'))) {
-            args.migrateRoot = taken.value;
-            i = taken.next;
-        }
-        else if ((taken = takeFlag(rest, i, a, '--connection'))) {
-            args.connection = taken.value;
-            i = taken.next;
-        }
-        else if ((taken = takeFlag(rest, i, a, '--confirm'))) {
-            args.confirm = taken.value;
-            i = taken.next;
-        }
-        else {
-            process.stderr.write(fillTemplate(unknownArgTpl, { arg: a }));
-            process.exit(2);
-        }
-    }
-    return args;
-};
-const resolveMigratePath = (args, dialect) => {
-    if (args.migratePath)
-        return args.migratePath;
-    const root = args.migrateRoot ?? 'sql';
-    return `${root}/${dialect}/migrations`;
-};
-const randomToken = () => {
-    const alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ';
-    const buf = new Uint8Array(4);
-    globalThis.crypto.getRandomValues(buf);
-    let out = '';
-    for (let i = 0; i < 4; i++)
-        out += alphabet[buf[i] % alphabet.length];
-    return out;
-};
-const promptConfirmation = async (token) => {
-    if (!process.stdin.isTTY) {
-        process.stderr.write(fillTemplate(confirmTtyRequiredTpl, { token }));
-        process.exit(2);
-    }
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    try {
-        const answer = await rl.question(fillTemplate(confirmPromptTpl, { token }));
-        return answer.trim() === token;
-    }
-    finally {
-        rl.close();
-    }
-};
-const main = async () => {
-    const args = parseArgs(process.argv);
-    if (!args.provider) {
-        process.stderr.write(missingProviderMsg);
-        process.exit(2);
-    }
-    const dialect = requireDialect(args.provider);
-    const connection = requireConnection(dialect, args.connection);
-    const missing = await dialect.prerequisiteError(connection);
-    if (missing !== null) {
-        process.stderr.write(`${missing}\n`);
-        process.exit(2);
-    }
-    const token = randomToken();
-    process.stderr.write(fillTemplate(destructiveHeaderTpl, { dialect: dialect.name, token }));
-    if (args.confirm !== null) {
-        if (args.confirm !== token) {
-            process.stderr.write(fillTemplate(confirmMismatchTpl, { supplied: args.confirm, token }));
-            process.exit(2);
-        }
-    }
-    else {
-        const ok = await promptConfirmation(token);
-        if (!ok) {
-            process.stderr.write(confirmTokenMismatchMsg);
-            process.exit(2);
-        }
-    }
-    const migratePath = resolve(resolveMigratePath(args, dialect.name));
-    const name = await new Migrater(dialect).down({
-        connection,
-        migrationsPath: migratePath,
-    });
-    if (name == null)
-        process.stdout.write(noRollbackMsg);
-    else
-        process.stdout.write(fillTemplate(rolledBackTpl, { name }));
-};
-main().catch((e) => {
-    const err = e;
-    process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
-    process.exit(1);
-});

package/dist/bin/migrate-init.js

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
-import { loadHelp } from "../help.js";
-import { loadSelectedPackages, resolveInitDialects } from "../init-select.js";
-const HELP_TEXT = await loadHelp('migrate-init');
-const takeFlag = (rest, i, arg, flag) => {
-    const eq = `${flag}=`;
-    if (arg === flag) {
-        const value = rest[i + 1];
-        if (value === undefined)
-            return undefined;
-        return { value, next: i + 1 };
-    }
-    if (arg.startsWith(eq))
-        return { value: arg.slice(eq.length), next: i };
-    return undefined;
-};
-const parseArgs = (argv) => {
-    const dialects = [];
-    let all = false;
-    const rest = argv.slice(2);
-    for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === '-h' || a === '--help') {
-            process.stderr.write(HELP_TEXT);
-            process.exit(0);
-        }
-        if (a === '--all') {
-            all = true;
-            continue;
-        }
-        const taken = takeFlag(rest, i, a, '--dialect');
-        if (taken) {
-            dialects.push(taken.value);
-            i = taken.next;
-            continue;
-        }
-        process.stderr.write(`unknown arg: ${a}\n`);
-        process.exit(2);
-    }
-    return { dialects, all };
-};
-const npmFlags = ['--no-audit', '--no-fund', '--loglevel=error'];
-const npm = (args) => {
-    const cmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-    const result = spawnSync(cmd, args, { stdio: 'inherit', cwd: process.cwd() });
-    if (result.status !== 0) {
-        process.exit(result.status ?? 1);
-    }
-};
-const main = async () => {
-    const args = parseArgs(process.argv);
-    let names;
-    try {
-        names = resolveInitDialects(args.dialects, args.all);
-    }
-    catch (e) {
-        const err = e;
-        process.stderr.write(`${err.message}\n`);
-        process.exit(2);
-    }
-    const selected = await loadSelectedPackages(names);
-    const specs = selected.packages.map((p) => `${p.name}@${p.version}`);
-    if (specs.length > 0) {
-        npm(['install', ...npmFlags, ...specs]);
-    }
-    const remove = selected.allDriverPackages.filter((name) => !selected.packages.some((p) => p.name === name));
-    if (remove.length > 0) {
-        npm(['uninstall', ...npmFlags, ...remove]);
-    }
-    process.stdout.write(`Enabled dialects: ${selected.names.join(', ')}\n`);
-};
-main().catch((e) => {
-    const err = e;
-    process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
-    process.exit(1);
-});

package/dist/bin/migrate-setup.js

@@ -1,87 +0,0 @@
-#!/usr/bin/env node
-// Idempotent migrate-setup — creates the migrates + migrate_logs tracking tables per dialect.
-import { missingProviderMsg, requireConnection, requireDialect, takeFlag } from "../cli.js";
-import { fillTemplate, loadMessage } from "../infrastructure/message-templates.js";
-import { loadHelp, Migrater } from "../index.js";
-const [HELP_TEXT, unknownArgTpl, setupCompleteTpl] = await Promise.all([
-    loadHelp('migrate-setup'),
-    loadMessage('errors/unknown-arg'),
-    loadMessage('setup-complete'),
-]);
-const parseArgs = (argv) => {
-    const args = {
-        provider: null,
-        connection: null,
-        migrationsPath: null,
-        andUp: false,
-    };
-    const rest = argv.slice(2);
-    for (let i = 0; i < rest.length; i++) {
-        const a = rest[i];
-        if (a === '-h' || a === '--help') {
-            process.stderr.write(HELP_TEXT);
-            process.exit(0);
-        }
-        if (a === '--and-up') {
-            args.andUp = true;
-            continue;
-        }
-        let taken;
-        if ((taken = takeFlag(rest, i, a, '--provider'))) {
-            args.provider = taken.value;
-            i = taken.next;
-        }
-        else if ((taken = takeFlag(rest, i, a, '--connection'))) {
-            args.connection = taken.value;
-            i = taken.next;
-        }
-        else if ((taken = takeFlag(rest, i, a, '--migrations-path')) ||
-            (taken = takeFlag(rest, i, a, '--migrate-path'))) {
-            args.migrationsPath = taken.value;
-            i = taken.next;
-        }
-        else {
-            process.stderr.write(fillTemplate(unknownArgTpl, { arg: a }));
-            process.exit(2);
-        }
-    }
-    return args;
-};
-const main = async () => {
-    const args = parseArgs(process.argv);
-    if (!args.provider) {
-        process.stderr.write(missingProviderMsg);
-        process.exit(2);
-    }
-    const dialect = requireDialect(args.provider);
-    const connection = requireConnection(dialect, args.connection);
-    const migrationsPath = args.migrationsPath ?? `./sql/${dialect.name}/migrations`;
-    const migrater = new Migrater(dialect);
-    await migrater.setup({ connection, migrationsPath });
-    process.stdout.write(fillTemplate(setupCompleteTpl, {
-        dialect: dialect.name,
-        migrationsPath,
-        createExample: `  migrate-create --provider ${dialect.name} --name add_users`,
-        upExample: `  migrate-up --provider ${dialect.name} --connection ${connection}`,
-    }));
-    if (args.andUp) {
-        const names = await migrater.up({ connection, migrationsPath });
-        const [noPendingMsg, noMorePendingMsg, appliedTpl] = await Promise.all([
-            loadMessage('status/no-pending'),
-            loadMessage('status/no-more-pending'),
-            loadMessage('status/applied'),
-        ]);
-        if (names.length === 0)
-            process.stdout.write(noPendingMsg);
-        else {
-            for (const name of names)
-                process.stdout.write(fillTemplate(appliedTpl, { name }));
-            process.stdout.write(noMorePendingMsg);
-        }
-    }
-};
-main().catch((e) => {
-    const err = e;
-    process.stderr.write(`${err?.stack ?? err?.message ?? String(e)}\n`);
-    process.exit(1);
-});