@schemavaults/dbh 0.10.2 → 0.11.1

package/README.md

@@ -20,7 +20,7 @@ Ensure that you have both `postgres` and a `postgres-ws-proxy` containers runnin
 
 You'll likely want to replace the `build:` sections for the services in the e2e test example `.yml` file with `image:`. For example, use `image: postgres:17.7` for the `postgres` service. For the proxy, you can pull the docker image from `ghcr.io/schemavaults/dbh/postgres-ws-proxy`; use the version number equal to your `@schemavaults/dbh` npm package installation:
 ```md
-# NPM Package: @schemavaults/dbh@0.10.2 => ghcr.io/schemavaults/dbh/postgres-ws-proxy:0.10.2
+# NPM Package: @schemavaults/dbh@0.11.1 => ghcr.io/schemavaults/dbh/postgres-ws-proxy:0.11.1
 ```
 
 ### In your application server code
@@ -40,6 +40,20 @@ npx @schemavaults/dbh --help
 # or `bun run cli --help` if you have the dbh source repository as your working directory
 ```
 
+#### Validate the shape of a migrations directory
+```bash
+# assert the migrations directory is well-formed:
+#  - non-empty
+#  - every file is prefixed with a 5-digit migration number (e.g. 00000-my-migration.ts)
+#  - every module exports an up() and down() function
+#  - there are no duplicate migration numbers (branch collisions, e.g. 00040-a.ts and 00040-b.ts)
+# exits 0 when the directory is valid, non-zero otherwise.
+bunx @schemavaults/dbh validate-migration-directory ./src/db/migrations
+
+# treat duplicate migration numbers as warnings instead of errors (still exits 0)
+bunx @schemavaults/dbh validate-migration-directory ./src/db/migrations --duplicates-as-warnings
+```
+
 #### Build example database migrations with the CLI
 ```bash
 mkdir ./tests/tmp

package/dist/utils/validateMigrationDirectory.d.ts

@@ -0,0 +1,35 @@
+export type MigrationValidationLevel = "error" | "warning";
+export interface MigrationValidationIssue {
+    level: MigrationValidationLevel;
+    message: string;
+    /** The offending file name (relative to the migration directory), if any. */
+    file?: string;
+}
+export interface ValidateMigrationDirectoryOptions {
+    /**
+     * When true, duplicate migration numbers are reported as warnings instead of
+     * errors (they will not, on their own, cause validation to fail).
+     * @default false
+     */
+    duplicatesAsWarnings?: boolean;
+}
+export interface ValidateMigrationDirectoryResult {
+    /** True when there are no `error`-level issues. */
+    ok: boolean;
+    /** The absolute path that was validated. */
+    directory: string;
+    /** The migration file names that were considered (relative to `directory`). */
+    migrationFiles: string[];
+    issues: MigrationValidationIssue[];
+}
+/**
+ * Validates the shape of an opinionated Kysely migrations directory.
+ *
+ * Asserts that the directory:
+ *  - exists and is non-empty,
+ *  - contains only files prefixed with a 5-digit migration number,
+ *  - has no duplicate migration numbers (branch collisions), and
+ *  - exports an `up()` and `down()` function from every migration module.
+ */
+export declare function validateMigrationDirectory(directory: string, options?: ValidateMigrationDirectoryOptions): Promise<ValidateMigrationDirectoryResult>;
+export default validateMigrationDirectory;

package/dist/utils/validateMigrationDirectory.js

@@ -0,0 +1,157 @@
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+/**
+ * Extensions that are treated as migration modules. `.d.ts` declaration files
+ * are explicitly ignored (handled separately below).
+ */
+const MIGRATION_FILE_EXTENSIONS = [
+    ".ts",
+    ".mts",
+    ".cts",
+    ".js",
+    ".mjs",
+    ".cjs",
+];
+/** Migration file names must begin with exactly 5 digits (e.g. 00000-foo.ts). */
+const MIGRATION_PREFIX_REGEX = /^(\d{5})(?:\D|$)/;
+function isMigrationFile(fileName) {
+    if (fileName.startsWith(".")) {
+        // Ignore hidden/dotfiles.
+        return false;
+    }
+    if (fileName.endsWith(".d.ts")) {
+        // Ignore TypeScript declaration files.
+        return false;
+    }
+    return MIGRATION_FILE_EXTENSIONS.some((ext) => fileName.endsWith(ext));
+}
+/**
+ * Validates the shape of an opinionated Kysely migrations directory.
+ *
+ * Asserts that the directory:
+ *  - exists and is non-empty,
+ *  - contains only files prefixed with a 5-digit migration number,
+ *  - has no duplicate migration numbers (branch collisions), and
+ *  - exports an `up()` and `down()` function from every migration module.
+ */
+export async function validateMigrationDirectory(directory, options = {}) {
+    const { duplicatesAsWarnings = false } = options;
+    const resolved = path.resolve(directory);
+    const issues = [];
+    if (!fs.existsSync(resolved)) {
+        return {
+            ok: false,
+            directory: resolved,
+            migrationFiles: [],
+            issues: [
+                {
+                    level: "error",
+                    message: `Migration directory does not exist: ${resolved}`,
+                },
+            ],
+        };
+    }
+    const stat = fs.statSync(resolved);
+    if (!stat.isDirectory()) {
+        return {
+            ok: false,
+            directory: resolved,
+            migrationFiles: [],
+            issues: [
+                {
+                    level: "error",
+                    message: `Migration path is not a directory: ${resolved}`,
+                },
+            ],
+        };
+    }
+    const entries = fs.readdirSync(resolved, { withFileTypes: true });
+    const migrationFiles = entries
+        .filter((entry) => entry.isFile() && isMigrationFile(entry.name))
+        .map((entry) => entry.name)
+        .sort();
+    // 1) Directory must be non-empty.
+    if (migrationFiles.length === 0) {
+        issues.push({
+            level: "error",
+            message: `Migration directory is empty (no migration files found): ${resolved}`,
+        });
+        return {
+            ok: false,
+            directory: resolved,
+            migrationFiles,
+            issues,
+        };
+    }
+    // 2) Every file must be prefixed with a 5-digit migration number.
+    // Track which numbers map to which files for duplicate detection.
+    const numberToFiles = new Map();
+    for (const file of migrationFiles) {
+        const match = MIGRATION_PREFIX_REGEX.exec(file);
+        if (!match) {
+            issues.push({
+                level: "error",
+                file,
+                message: `File is not prefixed with a 5-digit migration number (e.g. 00000-my-migration.ts): ${file}`,
+            });
+            continue;
+        }
+        const number = match[1];
+        const existing = numberToFiles.get(number);
+        if (existing) {
+            existing.push(file);
+        }
+        else {
+            numberToFiles.set(number, [file]);
+        }
+    }
+    // 3) No duplicate migration numbers (collisions across branches).
+    for (const [number, files] of numberToFiles) {
+        if (files.length > 1) {
+            issues.push({
+                level: duplicatesAsWarnings ? "warning" : "error",
+                message: `Duplicate migration number '${number}' used by ${files.length} files: ${files.join(", ")}`,
+            });
+        }
+    }
+    // 4) Every module must export an up() and down() function.
+    for (const file of migrationFiles) {
+        const fullPath = path.join(resolved, file);
+        let mod;
+        try {
+            mod = (await import(pathToFileURL(fullPath).href));
+        }
+        catch (error) {
+            issues.push({
+                level: "error",
+                file,
+                message: `Failed to import migration module '${file}': ${error instanceof Error ? error.message : String(error)}`,
+            });
+            continue;
+        }
+        if (typeof mod.up !== "function") {
+            issues.push({
+                level: "error",
+                file,
+                message: `Migration '${file}' does not export an up() function`,
+            });
+        }
+        if (typeof mod.down !== "function") {
+            issues.push({
+                level: "error",
+                file,
+                message: `Migration '${file}' does not export a down() function`,
+            });
+        }
+    }
+    const ok = !issues.some((issue) => issue.level === "error");
+    return {
+        ok,
+        directory: resolved,
+        migrationFiles,
+        issues,
+    };
+}
+export default validateMigrationDirectory;
+//# sourceMappingURL=validateMigrationDirectory.js.map

package/dist/utils/validateMigrationDirectory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateMigrationDirectory.js","sourceRoot":"","sources":["../../src/utils/validateMigrationDirectory.ts"],"names":[],"mappings":"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"}