@schemavaults/dbh 0.10.1 → 0.11.0

package/.claude/skills/database-migrations/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: database-migrations
+description: Authoring, building, validating, and running PostgreSQL database migrations with the @schemavaults/dbh package. Use when a project depends on @schemavaults/dbh and you are creating or editing Kysely migration files, setting up a migrations/ directory, or when the user mentions migrations, up()/down(), schema changes, or the dbh CLI's migrate / build-db-migrations / validate-migration-directory commands.
+---
+
+# Database Migrations with @schemavaults/dbh
+
+`@schemavaults/dbh` provides [Kysely](https://kysely.dev/) migrations for
+PostgreSQL, applied through the `dbh` CLI. Migrations are opinionated: every file
+is a numbered module that exports an `up()` and a `down()` function. TypeScript
+source migrations are **built** to JavaScript first, then **applied** with the
+CLI.
+
+Invoke the CLI with your package runner. Use **`bunx @schemavaults/dbh`** for
+**validating and building** migrations — `build-db-migrations` uses Bun's
+bundler and requires Bun anyway. Use **`npx @schemavaults/dbh`** for **running /
+applying** migrations (`migrate` and `reverse`): most PostgreSQL drivers are
+built for Node.js rather than Bun, so apply migrations on the Node runtime.
+
+## One-time setup (for consumers)
+
+Migrations import the `sql` template tag from `@/sql` rather than directly from
+the package. This indirection is required by the build step (see the note under
+"Building migrations"), so configure it once:
+
+1. **Create a local `sql` module** somewhere in your source tree, e.g.
+   `./src/db/sql.ts`, that re-exports the tag from the package:
+
+   ```ts
+   // src/db/sql.ts
+   export { sql, sql as default } from "@schemavaults/dbh/sql";
+   export type * from "@schemavaults/dbh/sql";
+   ```
+
+2. **Configure the `@/sql` path alias** in your `tsconfig.json` so migration
+   sources typecheck and resolve:
+
+   ```jsonc
+   {
+     "compilerOptions": {
+       "baseUrl": ".",
+       "paths": {
+         "@/sql": ["./src/db/sql.ts"]
+       }
+     }
+   }
+   ```
+
+3. **Create a migrations directory**, e.g. `./src/db/migrations/`, and add your
+   numbered migration files there.
+
+## Migration file format
+
+Each migration is a single file in your migrations directory. The rules are:
+
+1. **The directory is non-empty.**
+2. **Each file name is prefixed with a 5-digit migration number**, followed by a
+   short kebab-case description, e.g. `00000-template-migration.ts`,
+   `00001-create-users-table.ts`. The number defines apply order.
+3. **Each module exports an `up(db)` and a `down(db)` function.** `up()` applies
+   the change; `down()` must reverse it exactly so migrations can be rolled back.
+4. **Migration numbers are unique** — never reuse a number. If two branches both
+   add `00040-*.ts`, that collision must be resolved by renumbering one of them
+   before merge.
+
+Both `up` and `down` receive a `Kysely<any>` instance and return a `Promise`.
+Import the `Kysely` type from the package: `import type { Kysely } from "@schemavaults/dbh"`.
+
+### Example: using the `Kysely<any>` query builder
+
+Prefer the typed query builder for schema operations:
+
+```ts
+// 00001-create-users-table.ts
+import type { Kysely } from "@schemavaults/dbh";
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable("users")
+    .addColumn("user_id", "uuid", (col) => col.primaryKey())
+    .addColumn("email", "text", (col) => col.notNull().unique())
+    .addColumn("created_at", "bigint", (col) => col.notNull())
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable("users").execute();
+}
+```
+
+### Example: using the `sql` template tag
+
+For statements the builder can't express (or raw DDL), import `sql` from
+`@/sql` (your local module from setup, which re-exports Kysely's `sql` tag) and
+call `.execute(db)`:
+
+```ts
+// 00002-create-squirrels-table.ts
+import type { Kysely } from "@schemavaults/dbh";
+import { sql } from "@/sql";
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await sql`
+    CREATE TABLE IF NOT EXISTS EXAMPLE_SQUIRRELS (
+      squirrel_id UUID PRIMARY KEY,
+      squirrel_name TEXT NOT NULL,
+      created_at BIGINT NOT NULL
+    );
+  `.execute(db);
+
+  // Always interpolate values via ${...}; the sql tag parameterizes them.
+  await sql`CREATE INDEX squirrels_name_idx ON EXAMPLE_SQUIRRELS (squirrel_name);`.execute(
+    db,
+  );
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await sql`DROP TABLE IF EXISTS EXAMPLE_SQUIRRELS;`.execute(db);
+}
+```
+
+> Important: migration files must **always** import `sql` from `@/sql`, never
+> directly from `@schemavaults/dbh/sql`. The `build-db-migrations` step rewrites
+> the literal `@/sql` import specifier to a relative path pointing at the built,
+> standalone `sql.js`, so the import must be written exactly as `@/sql` for the
+> build to work. (This is why the one-time setup configures the `@/sql` alias.)
+
+### Empty template migration
+
+A no-op migration is valid (useful as a starting template):
+
+```ts
+// 00000-template-migration.ts
+import type { Kysely } from "@schemavaults/dbh";
+
+export async function up(
+  db: Kysely<any>, // eslint-disable-line @typescript-eslint/no-unused-vars
+): Promise<void> {}
+
+export async function down(
+  db: Kysely<any>, // eslint-disable-line @typescript-eslint/no-unused-vars
+): Promise<void> {}
+```
+
+## Validating migrations
+
+Before building or applying, assert your source migrations directory is
+well-formed. The `validate-migration-directory` command checks all four rules
+above and exits `0` when valid, non-zero otherwise (good for CI / pre-commit):
+
+```bash
+bunx @schemavaults/dbh validate-migration-directory ./src/db/migrations
+```
+
+It reports each problem with an `[ERROR]`/`[WARN]` prefix:
+- empty directory,
+- a file missing the 5-digit prefix,
+- a module missing `up()` or `down()`,
+- duplicate migration numbers (branch collisions).
+
+Treat duplicate numbers as warnings (non-fatal) with `--duplicates-as-warnings`.
+
+## Building migrations
+
+TypeScript migrations must be compiled to JavaScript before they're applied
+(the `migrate` step runs on Node and imports `.js`). The `build-db-migrations`
+command uses Bun's bundler and also builds the standalone `sql` module the
+migrations depend on. Point `--sql-module` at the local `sql.ts` you created
+during setup:
+
+```bash
+bunx @schemavaults/dbh build-db-migrations ./src/db/migrations \
+  --outdir ./dist/migrations \
+  --sql-module ./src/db/sql.ts \
+  --sql-outdir ./dist
+```
+
+Key options:
+- `<migrations-src>` — directory of `.ts` migration sources (positional).
+- `--outdir <dir>` — where compiled `.js` migrations are written (required).
+- `--sql-module <path>` — path to your local `sql.ts` module to build alongside (required).
+- `--sql-outdir <dir>` — where the built `sql.js` goes (defaults to the parent of `--outdir`).
+- `--external <pkg...>` — packages to keep external (default: `@schemavaults/dbh`, `kysely`).
+
+`build-db-migrations` requires `bun` to be installed and on the PATH.
+
+## Running migrations
+
+Apply built migrations with `migrate`, and roll back with `reverse`. Both take
+the **built** migration folder and require an `--environment`; credentials come
+from `process.env` (or an `--env-file`). Run these with **`npx`** (Node.js):
+most PostgreSQL drivers target Node rather than Bun.
+
+```bash
+# Apply all pending migrations (to latest):
+npx @schemavaults/dbh migrate ./dist/migrations --environment production --env-file ./.env.production
+
+# Apply up to a specific version (the migration name w/o extension):
+npx @schemavaults/dbh migrate ./dist/migrations 00001-create-users-table --environment staging
+
+# Roll back down to a target version:
+npx @schemavaults/dbh reverse ./dist/migrations 00000-template-migration --environment staging
+```
+
+Options for `migrate` / `reverse`:
+- `<folder>` — path to the built migration folder (positional).
+- `[version]` / `<version>` — target migration name; `migrate` defaults to latest, `reverse` requires it.
+- `-e, --environment <env>` — `development | test | staging | production` (required).
+- `--ws-proxy-url <url>` — custom Neon-compatible WebSocket proxy URL.
+- `--env-file <path>` — load DB credentials from a `.env` file first.
+
+Each result line prints as `[Up|Down] <migrationName>: <Success|Error|NotExecuted>`.
+
+### Programmatic API
+
+The same operations are available from `@schemavaults/dbh/migrate` for tests or
+custom scripts, using the adapter's Kysely instance:
+
+```ts
+import { migrate, reverse } from "@schemavaults/dbh/migrate";
+
+await migrate({ db: adapter.db, migrationFolder, version /* optional */ });
+await reverse({ db: adapter.db, migrationFolder, version });
+```
+
+## Typical end-to-end flow
+
+```bash
+# 1. Validate the source migrations directory.
+bunx @schemavaults/dbh validate-migration-directory ./src/db/migrations
+
+# 2. Build .ts migrations (+ sql module) to .js.
+bunx @schemavaults/dbh build-db-migrations ./src/db/migrations \
+  --outdir ./dist/migrations --sql-module ./src/db/sql.ts --sql-outdir ./dist
+
+# 3. Apply the built migrations (npx / Node.js — pg drivers target Node).
+npx @schemavaults/dbh migrate ./dist/migrations --environment production --env-file ./.env.production
+```
+
+## Required environment variables (for migrate/reverse)
+
+`POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_URL`, `POSTGRES_HOST`,
+`POSTGRES_PORT`, `POSTGRES_DATABASE` (and optional `POSTGRES_URL_NON_POOLING`).
+Set `SCHEMAVAULTS_DBH_DEBUG=true` for verbose debug logging.

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.1 => ghcr.io/schemavaults/dbh/postgres-ws-proxy:0.10.1
+# NPM Package: @schemavaults/dbh@0.11.0 => ghcr.io/schemavaults/dbh/postgres-ws-proxy:0.11.0
 ```
 
 ### 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/adapters/abstract-schemavaults-dbh-adapter.d.ts

@@ -1,6 +1,6 @@
-import type { BaseInitializablePostgresDatabaseCredentials, PostgresDatabaseCredentials } from "../types/PostgresDatabaseCredentials";
-import { IDatabaseHandler } from "../types/IDatabaseHandler";
-import { type SchemaVaultsAppEnvironment } from "../types/SchemaVaultsAppEnvironment";
+import type { BaseInitializablePostgresDatabaseCredentials, PostgresDatabaseCredentials } from "../types/PostgresDatabaseCredentials.js";
+import { IDatabaseHandler } from "../types/IDatabaseHandler.js";
+import { type SchemaVaultsAppEnvironment } from "../types/SchemaVaultsAppEnvironment.js";
 import type { Dialect } from "kysely";
 import { Kysely } from "kysely";
 export interface IAbstractSchemaVaultsDbhAdapterConstructorOpts {

package/dist/adapters/abstract-schemavaults-dbh-adapter.js

@@ -1,7 +1,7 @@
-import { isValidAppEnvironment, } from "../types/SchemaVaultsAppEnvironment";
-import isDbhInDebugMode from "../utils/isDbhInDebugMode";
-import parseDatabaseCredentials from "../utils/parseDatabaseCredentials";
-import parseDatabaseCredentialsFromEnv from "../utils/parseDatabaseCredentialsFromEnv";
+import { isValidAppEnvironment, } from "../types/SchemaVaultsAppEnvironment.js";
+import isDbhInDebugMode from "../utils/isDbhInDebugMode.js";
+import parseDatabaseCredentials from "../utils/parseDatabaseCredentials.js";
+import parseDatabaseCredentialsFromEnv from "../utils/parseDatabaseCredentialsFromEnv.js";
 import { Kysely } from "kysely";
 export default class AbstractSchemaVaultsDbhAdapter {
     credentials;

package/dist/adapters/schemavaults-postgres-adapter.d.ts

@@ -1,6 +1,6 @@
-import type { IDatabaseHandler } from "../types/IDatabaseHandler";
-import type { IAbstractSchemaVaultsDbhAdapterConstructorOpts } from "../adapters/abstract-schemavaults-dbh-adapter";
-import AbstractSchemaVaultsDbhAdapter from "../adapters/abstract-schemavaults-dbh-adapter";
+import type { IDatabaseHandler } from "../types/IDatabaseHandler.js";
+import type { IAbstractSchemaVaultsDbhAdapterConstructorOpts } from "../adapters/abstract-schemavaults-dbh-adapter.js";
+import AbstractSchemaVaultsDbhAdapter from "../adapters/abstract-schemavaults-dbh-adapter.js";
 import { type Dialect } from "kysely";
 export interface ISchemaVaultsPostgresAdapterConstructorOpts extends IAbstractSchemaVaultsDbhAdapterConstructorOpts {
 }

package/dist/adapters/schemavaults-postgres-adapter.js

@@ -1,7 +1,7 @@
 // schemavaults-postgres-adapter.ts
 // This file sets up kysely to connect to postgres
-import parsePort from "../utils/parsePort";
-import AbstractSchemaVaultsDbhAdapter from "../adapters/abstract-schemavaults-dbh-adapter";
+import parsePort from "../utils/parsePort.js";
+import AbstractSchemaVaultsDbhAdapter from "../adapters/abstract-schemavaults-dbh-adapter.js";
 import { PostgresDialect, } from "kysely";
 import { Pool } from "pg";
 export class SchemaVaultsPostgresAdapter extends AbstractSchemaVaultsDbhAdapter {

package/dist/adapters/schemavaults-postgres-neon-proxy-adapter.d.ts

@@ -1,7 +1,7 @@
-import { type WsProxyUrlGenerator } from "../utils/getPostgresNeonWsProxyUrl";
-import type { IDatabaseHandler } from "../types/IDatabaseHandler";
-import type { IAbstractSchemaVaultsDbhAdapterConstructorOpts } from "../adapters/abstract-schemavaults-dbh-adapter";
-import AbstractSchemaVaultsDbhAdapter from "../adapters/abstract-schemavaults-dbh-adapter";
+import { type WsProxyUrlGenerator } from "../utils/getPostgresNeonWsProxyUrl.js";
+import type { IDatabaseHandler } from "../types/IDatabaseHandler.js";
+import type { IAbstractSchemaVaultsDbhAdapterConstructorOpts } from "../adapters/abstract-schemavaults-dbh-adapter.js";
+import AbstractSchemaVaultsDbhAdapter from "../adapters/abstract-schemavaults-dbh-adapter.js";
 import type { Dialect } from "kysely";
 export interface ISchemaVaultsPostgresNeonProxyAdapterConstructorOpts extends IAbstractSchemaVaultsDbhAdapterConstructorOpts {
     /**
@@ -15,4 +15,4 @@ export declare class SchemaVaultsPostgresNeonProxyAdapter<KyselyTablesType exten
     constructor(opts: ISchemaVaultsPostgresNeonProxyAdapterConstructorOpts);
 }
 export default SchemaVaultsPostgresNeonProxyAdapter;
-export type { WsProxyUrlGenerator, IGetPostgresNeonWsProxyUrlOpts, } from "../utils/getPostgresNeonWsProxyUrl";
+export type { WsProxyUrlGenerator, IGetPostgresNeonWsProxyUrlOpts, } from "../utils/getPostgresNeonWsProxyUrl.js";

package/dist/adapters/schemavaults-postgres-neon-proxy-adapter.js

@@ -2,9 +2,9 @@
 // This file sets up kysely to connect to postgres via a Neon websocket proxy
 // (allows database usage from a serverless/edge environment)
 import { NeonDialect } from "kysely-neon";
-import getPostgresNeonWsProxyUrl from "../utils/getPostgresNeonWsProxyUrl";
-import parsePort from "../utils/parsePort";
-import AbstractSchemaVaultsDbhAdapter from "../adapters/abstract-schemavaults-dbh-adapter";
+import getPostgresNeonWsProxyUrl from "../utils/getPostgresNeonWsProxyUrl.js";
+import parsePort from "../utils/parsePort.js";
+import AbstractSchemaVaultsDbhAdapter from "../adapters/abstract-schemavaults-dbh-adapter.js";
 export class SchemaVaultsPostgresNeonProxyAdapter extends AbstractSchemaVaultsDbhAdapter {
     initializeDbDialect(opts) {
         const debug = this.debug;

package/dist/create-dbh.d.ts

@@ -1,5 +1,5 @@
-import type { SchemaVaultsPostgresAdapter, ISchemaVaultsPostgresAdapterConstructorOpts } from "./adapters/schemavaults-postgres-adapter";
-import type { SchemaVaultsPostgresNeonProxyAdapter, ISchemaVaultsPostgresNeonProxyAdapterConstructorOpts } from "./adapters/schemavaults-postgres-neon-proxy-adapter";
+import type { SchemaVaultsPostgresAdapter, ISchemaVaultsPostgresAdapterConstructorOpts } from "./adapters/schemavaults-postgres-adapter.js";
+import type { SchemaVaultsPostgresNeonProxyAdapter, ISchemaVaultsPostgresNeonProxyAdapterConstructorOpts } from "./adapters/schemavaults-postgres-neon-proxy-adapter.js";
 /**
  * Asynchronously construct a SchemaVaults database handler for the given
  * adapter type, dynamically importing only the adapter that was requested.

package/dist/create-dbh.js

@@ -1,7 +1,7 @@
 // create-dbh.ts
 const ADAPTER_MAP = {
-    postgres: async () => await import("./adapters/schemavaults-postgres-adapter").then((mod) => mod.SchemaVaultsPostgresAdapter),
-    "postgres-neon-proxy": async () => await import("./adapters/schemavaults-postgres-neon-proxy-adapter").then((mod) => mod.SchemaVaultsPostgresNeonProxyAdapter),
+    postgres: async () => await import("./adapters/schemavaults-postgres-adapter.js").then((mod) => mod.SchemaVaultsPostgresAdapter),
+    "postgres-neon-proxy": async () => await import("./adapters/schemavaults-postgres-neon-proxy-adapter.js").then((mod) => mod.SchemaVaultsPostgresNeonProxyAdapter),
 };
 export default async function createDbh(adapter_type, opts) {
     if (typeof adapter_type !== "string") {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { default as default, default as createDbh } from "./create-dbh";
-export { SchemaVaultsPostgresNeonProxyAdapter } from "./adapters/schemavaults-postgres-neon-proxy-adapter";
-export type { WsProxyUrlGenerator, IGetPostgresNeonWsProxyUrlOpts, } from "./adapters/schemavaults-postgres-neon-proxy-adapter";
-export { SchemaVaultsPostgresAdapter } from "./adapters/schemavaults-postgres-adapter";
-export { sql } from "./sql";
+export { default as default, default as createDbh } from "./create-dbh.js";
+export { SchemaVaultsPostgresNeonProxyAdapter } from "./adapters/schemavaults-postgres-neon-proxy-adapter.js";
+export type { WsProxyUrlGenerator, IGetPostgresNeonWsProxyUrlOpts, } from "./adapters/schemavaults-postgres-neon-proxy-adapter.js";
+export { SchemaVaultsPostgresAdapter } from "./adapters/schemavaults-postgres-adapter.js";
+export { sql } from "./sql.js";
 export type * from "kysely";

package/dist/index.js

@@ -1,9 +1,9 @@
 // index.ts
-export { default as default, default as createDbh } from "./create-dbh";
+export { default as default, default as createDbh } from "./create-dbh.js";
 // Postgres Neon Proxy Adapter (for use in serverless environments)
-export { SchemaVaultsPostgresNeonProxyAdapter } from "./adapters/schemavaults-postgres-neon-proxy-adapter";
+export { SchemaVaultsPostgresNeonProxyAdapter } from "./adapters/schemavaults-postgres-neon-proxy-adapter.js";
 // Postgres Adapter (for use in standard Node.js environments)
-export { SchemaVaultsPostgresAdapter } from "./adapters/schemavaults-postgres-adapter";
+export { SchemaVaultsPostgresAdapter } from "./adapters/schemavaults-postgres-adapter.js";
 // Kysely SQL builder + types
-export { sql } from "./sql";
+export { sql } from "./sql.js";
 //# sourceMappingURL=index.js.map

package/dist/utils/buildPostgresUrl.d.ts

@@ -1,3 +1,3 @@
-import type { BaseInitializablePostgresDatabaseCredentials } from "../types/PostgresDatabaseCredentials";
+import type { BaseInitializablePostgresDatabaseCredentials } from "../types/PostgresDatabaseCredentials.js";
 declare function buildPostgresUrl(opts: Pick<BaseInitializablePostgresDatabaseCredentials, "POSTGRES_HOST" | "POSTGRES_PORT" | "POSTGRES_USER" | "POSTGRES_PASSWORD" | "POSTGRES_DATABASE">): string;
 export default buildPostgresUrl;

package/dist/utils/getAppEnvironment.d.ts

@@ -1,3 +1,3 @@
-import { type SchemaVaultsAppEnvironment } from "../types/SchemaVaultsAppEnvironment";
+import { type SchemaVaultsAppEnvironment } from "../types/SchemaVaultsAppEnvironment.js";
 export declare function getAppEnvironment(): SchemaVaultsAppEnvironment;
 export default getAppEnvironment;

package/dist/utils/getAppEnvironment.js

@@ -1,4 +1,4 @@
-import { isValidAppEnvironment, } from "../types/SchemaVaultsAppEnvironment";
+import { isValidAppEnvironment, } from "../types/SchemaVaultsAppEnvironment.js";
 export function getAppEnvironment() {
     const env = process.env["SCHEMAVAULTS_APP_ENVIRONMENT"];
     if (isValidAppEnvironment(env)) {

package/dist/utils/getPostgresNeonWsProxyUrl.d.ts

@@ -1,4 +1,4 @@
-import { type SchemaVaultsAppEnvironment } from "../types/SchemaVaultsAppEnvironment";
+import { type SchemaVaultsAppEnvironment } from "../types/SchemaVaultsAppEnvironment.js";
 export interface IGetPostgresNeonWsProxyUrlOpts {
     pg_host: string;
     environment: SchemaVaultsAppEnvironment;

package/dist/utils/getPostgresNeonWsProxyUrl.js

@@ -1,4 +1,4 @@
-import { isValidAppEnvironment, } from "../types/SchemaVaultsAppEnvironment";
+import { isValidAppEnvironment, } from "../types/SchemaVaultsAppEnvironment.js";
 export function getPostgresNeonWsProxyUrl({ pg_host, environment, ...opts }) {
     const debug = opts.debug ?? false;
     if (debug) {

package/dist/utils/isDbhInDebugMode.d.ts

@@ -1,4 +1,4 @@
-import type { SchemaVaultsAppEnvironment } from "../types/SchemaVaultsAppEnvironment";
+import type { SchemaVaultsAppEnvironment } from "../types/SchemaVaultsAppEnvironment.js";
 declare global {
     namespace NodeJS {
         interface ProcessEnv {

package/dist/utils/parseDatabaseCredentials.d.ts

@@ -1,3 +1,3 @@
-import type { BaseInitializablePostgresDatabaseCredentials, PostgresDatabaseCredentials } from "../types/PostgresDatabaseCredentials";
+import type { BaseInitializablePostgresDatabaseCredentials, PostgresDatabaseCredentials } from "../types/PostgresDatabaseCredentials.js";
 declare function parseDatabaseCredentials(minimum_credentials: Record<string, boolean | string | number | undefined> | BaseInitializablePostgresDatabaseCredentials, debug?: boolean): PostgresDatabaseCredentials;
 export default parseDatabaseCredentials;

package/dist/utils/parseDatabaseCredentials.js

@@ -1,5 +1,5 @@
-import maybeStripQuotes from "../utils/maybeStripQuotes";
-import buildPostgresUrl from "./buildPostgresUrl";
+import maybeStripQuotes from "../utils/maybeStripQuotes.js";
+import buildPostgresUrl from "./buildPostgresUrl.js";
 function parseDatabaseCredentials(minimum_credentials, debug = false) {
     if (typeof minimum_credentials !== "object") {
         throw new Error("Did not receive an object to parse database credentials from!");

package/dist/utils/parseDatabaseCredentialsFromEnv.d.ts

@@ -1,3 +1,3 @@
-import type { PostgresDatabaseCredentials } from "../types/PostgresDatabaseCredentials";
+import type { PostgresDatabaseCredentials } from "../types/PostgresDatabaseCredentials.js";
 export declare function parseDatabaseCredentialsFromEnv(env: Record<string, string | undefined>, debug?: boolean): PostgresDatabaseCredentials;
 export default parseDatabaseCredentialsFromEnv;

package/dist/utils/parseDatabaseCredentialsFromEnv.js

@@ -1,4 +1,4 @@
-import parseDatabaseCredentials from "./parseDatabaseCredentials";
+import parseDatabaseCredentials from "./parseDatabaseCredentials.js";
 export function parseDatabaseCredentialsFromEnv(env, debug = false) {
     return parseDatabaseCredentials(env, debug);
 }

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;