@deterministic-code/migraters 0.0.0-stage → 0.0.1

package/src/migrater.ts

@@ -0,0 +1,92 @@
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import type {
+  CreateArg,
+  CreateResponse,
+  DownArg,
+  IMigrater,
+  SetupArg,
+  UpArg,
+} from './abstractions/migrater.ts';
+import type { ISqlDialect } from './abstractions/sql-dialect.ts';
+import { isMigrationName, nextSequence, pad4 } from './create-sequence.ts';
+import { applyOneDown, applyOneUp, discoverMigrations } from './datasource-migrate.ts';
+import { defaultDialectFactory } from './infrastructure/default-factory.ts';
+import { fillTemplate, loadMessage, loadScaffold } from './infrastructure/message-templates.ts';
+
+const invalidNameTpl = await loadMessage('errors/invalid-name');
+
+export class Migrater implements IMigrater {
+  constructor(private readonly dialect: ISqlDialect) {}
+
+  get name(): string {
+    return this.dialect.name;
+  }
+
+  async setup({ connection, migrationsPath }: SetupArg): Promise<void> {
+    await this.dialect.prepareSetup(connection);
+    const client = await this.dialect.createClient(connection);
+    try {
+      await client.exec(this.dialect.migratesDdl);
+      await client.exec(this.dialect.migrateLogsDdl);
+      await mkdir(migrationsPath, { recursive: true });
+    } finally {
+      await client.close();
+    }
+  }
+
+  async up({ connection, migrationsPath, one = false }: UpArg): Promise<string[]> {
+    const client = await this.dialect.createClient(connection);
+    try {
+      const migrations = await discoverMigrations({
+        migratePath: migrationsPath,
+        dialect: this.dialect.name,
+      });
+      const applied: string[] = [];
+      for (;;) {
+        const result = await applyOneUp({ client, migrations });
+        if (!result.applied || result.name == null) break;
+        applied.push(result.name);
+        if (one) break;
+      }
+      return applied;
+    } finally {
+      await client.close();
+    }
+  }
+
+  async down({ connection, migrationsPath }: DownArg): Promise<string | null> {
+    const client = await this.dialect.createClient(connection);
+    try {
+      const migrations = await discoverMigrations({
+        migratePath: migrationsPath,
+        dialect: this.dialect.name,
+      });
+      const result = await applyOneDown({ client, migrations });
+      return result.rolledBack ? result.name : null;
+    } finally {
+      await client.close();
+    }
+  }
+
+  async create({ name, migrationsPath }: CreateArg): Promise<CreateResponse> {
+    if (!isMigrationName(name)) {
+      throw new Error(fillTemplate(invalidNameTpl, { name }));
+    }
+    await mkdir(migrationsPath, { recursive: true });
+    let entries: string[] = [];
+    try {
+      entries = await readdir(migrationsPath);
+    } catch (err) {
+      if (!(err instanceof Error && 'code' in err && err.code === 'ENOENT')) throw err;
+    }
+    const seq = pad4(nextSequence(entries));
+    const upName = `${seq}_${name}_up.sql`;
+    const downName = `${seq}_${name}_down.sql`;
+    await writeFile(`${migrationsPath}/${upName}`, await loadScaffold('up', { name }));
+    await writeFile(`${migrationsPath}/${downName}`, await loadScaffold('down', { name }));
+    return { upName, downName };
+  }
+}
+
+export const getMigrater = (provider: string): IMigrater =>
+  new Migrater(defaultDialectFactory.get(provider));

package/src/migration-client.ts

@@ -0,0 +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 };
+  };
+}
+
+/** 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;
+}

package/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/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/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/tsconfig.build.json

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

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.