pg-seed-kit 0.0.1

package/dist/cli/index.js

@@ -0,0 +1,143 @@
+import {
+  getSeederStatuses,
+  loadConfig,
+  resetSeeder,
+  runPendingSeeders,
+  runSeederByName
+} from "../chunk-KMXBCJZY.js";
+
+// src/cli/create.ts
+import fs from "fs";
+import path from "path";
+var TEMPLATE = `const seed = async (): Promise<void> => {
+  // TODO: implement this seeder.
+  // Keep it idempotent so re-runs are safe: check-before-insert,
+  // or \`INSERT ... ON CONFLICT DO NOTHING\`.
+};
+
+export default seed;
+`;
+function generateTimestamp() {
+  const now = /* @__PURE__ */ new Date();
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+async function createSeeder(name) {
+  const config = await loadConfig();
+  const timestamp = generateTimestamp();
+  const filename = `${timestamp}-${name}.seeder.ts`;
+  const filepath = path.join(config.seedersPath, filename);
+  if (!fs.existsSync(config.seedersPath)) {
+    fs.mkdirSync(config.seedersPath, { recursive: true });
+  }
+  fs.writeFileSync(filepath, TEMPLATE);
+  console.log(`Created: ${filepath}`);
+}
+
+// src/cli/commands.ts
+function printUsage() {
+  console.log("Usage:");
+  console.log("  pg-seed-kit create <name>   Create a new seeder file");
+  console.log("  pg-seed-kit status          List seeders and statuses");
+  console.log("  pg-seed-kit run [name]      Run pending seeders or one seeder");
+  console.log("  pg-seed-kit reset <name>    Mark a seeder as pending");
+  console.log("");
+  console.log("Connection: your config must export an async connect() that returns an adapter.");
+}
+async function withAdapter(action) {
+  const config = await loadConfig();
+  if (!config.connect) {
+    throw new Error(
+      "pg-seed-kit: this command needs a database connection. Export an async connect() from your config that returns an adapter."
+    );
+  }
+  const adapter = await config.connect();
+  try {
+    return await action({ adapter });
+  } finally {
+    await adapter.close?.();
+  }
+}
+function printStatuses(statuses) {
+  if (statuses.length === 0) {
+    console.log("No seeders found.");
+    return;
+  }
+  for (const status of statuses) {
+    const executedAt = status.executedAt ? ` ${status.executedAt.toISOString()}` : "";
+    const error = status.error ? ` - ${status.error}` : "";
+    console.log(`${status.status.padEnd(7)} ${status.name}${executedAt}${error}`);
+  }
+}
+function printRunResults(results) {
+  if (results.length === 0) {
+    console.log("No seeders found.");
+    return;
+  }
+  for (const result of results) {
+    const error = result.error ? ` - ${result.error}` : "";
+    console.log(`${result.status.padEnd(7)} ${result.name}${error}`);
+  }
+}
+async function runCli(args = process.argv.slice(2)) {
+  const command = args[0];
+  if (!command || command === "--help" || command === "-h") {
+    printUsage();
+    return command ? 0 : 1;
+  }
+  try {
+    switch (command) {
+      case "create": {
+        const name = args[1];
+        if (!name) {
+          console.error("Error: seeder name is required.");
+          console.error("Usage: pg-seed-kit create <name>");
+          return 1;
+        }
+        await createSeeder(name);
+        return 0;
+      }
+      case "status": {
+        await withAdapter(async (overrides) => {
+          const statuses = await getSeederStatuses(overrides);
+          printStatuses(statuses);
+        });
+        return 0;
+      }
+      case "run": {
+        let results = [];
+        const name = args[1];
+        await withAdapter(async (overrides) => {
+          results = name ? await runSeederByName(name, overrides) : await runPendingSeeders(overrides);
+          printRunResults(results);
+        });
+        return results.some((result) => result.status === "failed") ? 1 : 0;
+      }
+      case "reset": {
+        const name = args[1];
+        if (!name) {
+          console.error("Error: seeder name is required.");
+          console.error("Usage: pg-seed-kit reset <name>");
+          return 1;
+        }
+        await withAdapter(async (overrides) => {
+          await resetSeeder(name, overrides);
+          console.log(`Reset: ${name}`);
+        });
+        return 0;
+      }
+      default:
+        console.error(`Unknown command: "${command}"`);
+        printUsage();
+        return 1;
+    }
+  } catch (err) {
+    console.error(err?.message || String(err));
+    return 1;
+  }
+}
+
+// src/cli/index.ts
+runCli().then((exitCode) => {
+  process.exitCode = exitCode;
+});

package/dist/index.cjs

@@ -0,0 +1,286 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  getSeederStatuses: () => getSeederStatuses,
+  loadConfig: () => loadConfig,
+  resetSeeder: () => resetSeeder,
+  resolveSeedersPath: () => resolveSeedersPath,
+  runPendingSeeders: () => runPendingSeeders,
+  runSeederByName: () => runSeederByName
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/runner.ts
+var import_fs2 = __toESM(require("fs"), 1);
+var import_path2 = __toESM(require("path"), 1);
+var import_url2 = require("url");
+
+// src/dynamic-import.ts
+var dynamicImport = new Function("specifier", "return import(specifier);");
+
+// src/config.ts
+var import_fs = __toESM(require("fs"), 1);
+var import_path = __toESM(require("path"), 1);
+var import_url = require("url");
+var DEFAULT_TABLE_NAME = "seeders";
+var DEFAULT_FILE_PATTERN = /^\d{14}-.+\.seeder\.(ts|js|mjs|cjs)$/;
+var CONFIG_FILES = ["pg-seed-kit.config.js", "pg-seed-kit.config.cjs", "pg-seed-kit.config.mjs"];
+async function loadConfigFromFile(cwd) {
+  for (const filename of CONFIG_FILES) {
+    const filepath = import_path.default.resolve(cwd, filename);
+    if (import_fs.default.existsSync(filepath)) {
+      const loaded = await dynamicImport((0, import_url.pathToFileURL)(filepath).href);
+      return loaded.default ?? loaded;
+    }
+  }
+  const pkgPath = import_path.default.resolve(cwd, "package.json");
+  if (import_fs.default.existsSync(pkgPath)) {
+    const pkg = JSON.parse(import_fs.default.readFileSync(pkgPath, "utf-8"));
+    if (pkg["pg-seed-kit"]) {
+      return pkg["pg-seed-kit"];
+    }
+  }
+  return null;
+}
+function isResolver(value) {
+  return typeof value === "function";
+}
+async function loadConfig(overrides) {
+  const cwd = process.cwd();
+  const fileConfig = await loadConfigFromFile(cwd);
+  const merged = { ...fileConfig, ...overrides };
+  if (!merged.seedersPath) {
+    throw new Error(
+      'pg-seed-kit: "seedersPath" is required. Provide it via pg-seed-kit.config.js, package.json, or inline config.'
+    );
+  }
+  const rawPath = isResolver(merged.seedersPath) ? merged.seedersPath() : merged.seedersPath;
+  if (typeof rawPath !== "string" || rawPath.length === 0) {
+    throw new Error('pg-seed-kit: "seedersPath" must resolve to a non-empty string.');
+  }
+  const seedersPath = import_path.default.isAbsolute(rawPath) ? rawPath : import_path.default.resolve(cwd, rawPath);
+  return {
+    seedersPath,
+    tableName: merged.tableName ?? DEFAULT_TABLE_NAME,
+    filePattern: merged.filePattern ?? DEFAULT_FILE_PATTERN,
+    adapter: merged.adapter,
+    connect: merged.connect
+  };
+}
+function resolveSeedersPath(opts) {
+  return () => {
+    if (opts.srcWhen && opts.srcWhen()) return opts.src;
+    const argvFile = process.argv[1] || "";
+    if (/[\\/]dist[\\/]/.test(argvFile)) return opts.dist;
+    const isTsRuntime = /\.(ts|tsx)$/.test(argvFile) || Boolean(
+      process._preload_modules?.some(
+        (m) => /tsx|ts-node/.test(m)
+      )
+    ) || Boolean(process.env.TS_NODE_DEV) || Boolean(process.env.TSX);
+    return isTsRuntime ? opts.src : opts.dist;
+  };
+}
+
+// src/tracker.ts
+var ensuredTables = /* @__PURE__ */ new Set();
+function quoteIdentifier(name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(
+      `pg-seed-kit: invalid table name "${name}". Use only letters, digits, and underscores (must not start with a digit).`
+    );
+  }
+  return `"${name}"`;
+}
+function toRecord(row) {
+  return {
+    name: row.name,
+    executedAt: row.executed_at,
+    status: row.status,
+    error: row.error ?? void 0
+  };
+}
+async function ensureTable(adapter, tableName) {
+  if (ensuredTables.has(tableName)) return;
+  const table = quoteIdentifier(tableName);
+  await adapter.query(
+    `CREATE TABLE IF NOT EXISTS ${table} (
+       name TEXT PRIMARY KEY,
+       executed_at TIMESTAMPTZ NOT NULL,
+       status TEXT NOT NULL,
+       error TEXT
+     )`
+  );
+  ensuredTables.add(tableName);
+}
+async function getExecutedSeeders(adapter, tableName) {
+  const table = quoteIdentifier(tableName);
+  const rows = await adapter.query(
+    `SELECT name, executed_at, status, error FROM ${table} WHERE status = 'success'`
+  );
+  return rows.map(toRecord);
+}
+async function getAllTrackedSeeders(adapter, tableName) {
+  const table = quoteIdentifier(tableName);
+  const rows = await adapter.query(
+    `SELECT name, executed_at, status, error FROM ${table}`
+  );
+  return rows.map(toRecord);
+}
+async function upsertSeederRecord(adapter, tableName, record) {
+  const table = quoteIdentifier(tableName);
+  await adapter.query(
+    `INSERT INTO ${table} (name, executed_at, status, error)
+     VALUES ($1, $2, $3, $4)
+     ON CONFLICT (name) DO UPDATE
+       SET executed_at = EXCLUDED.executed_at,
+           status = EXCLUDED.status,
+           error = EXCLUDED.error`,
+    [record.name, record.executedAt, record.status, record.error ?? null]
+  );
+}
+async function deleteSeederRecord(adapter, tableName, name) {
+  const table = quoteIdentifier(tableName);
+  await adapter.query(`DELETE FROM ${table} WHERE name = $1`, [name]);
+}
+
+// src/runner.ts
+function requireAdapter(config) {
+  if (!config.adapter) {
+    throw new Error(
+      "pg-seed-kit: an adapter is required. Pass { adapter } to the runner, or expose one from your config (the CLI builds it via `connect`)."
+    );
+  }
+  return config.adapter;
+}
+function getSeederFiles(config) {
+  if (!import_fs2.default.existsSync(config.seedersPath)) {
+    return [];
+  }
+  return import_fs2.default.readdirSync(config.seedersPath).filter((f) => config.filePattern.test(f)).sort();
+}
+async function loadSeeder(name, filepath) {
+  const seederModule = await dynamicImport((0, import_url2.pathToFileURL)(filepath).href);
+  const seederFn = seederModule.default ?? seederModule;
+  if (typeof seederFn !== "function") {
+    throw new Error(`Seeder "${name}" does not export a function`);
+  }
+  return seederFn;
+}
+async function runSingleSeeder(adapter, name, filepath, tableName, results) {
+  try {
+    const seederFn = await loadSeeder(name, filepath);
+    await seederFn();
+    await upsertSeederRecord(adapter, tableName, {
+      name,
+      executedAt: /* @__PURE__ */ new Date(),
+      status: "success"
+    });
+    results.push({ name, status: "success" });
+    console.log(`[pg-seed-kit] "${name}" ran successfully`);
+  } catch (err) {
+    const errorMessage = err?.message || String(err);
+    await upsertSeederRecord(adapter, tableName, {
+      name,
+      executedAt: /* @__PURE__ */ new Date(),
+      status: "failed",
+      error: errorMessage
+    });
+    results.push({ name, status: "failed", error: errorMessage });
+    console.error(`[pg-seed-kit] "${name}" failed: ${errorMessage}`);
+  }
+}
+async function runPendingSeeders(overrides) {
+  const config = await loadConfig(overrides);
+  const adapter = requireAdapter(config);
+  await ensureTable(adapter, config.tableName);
+  const files = getSeederFiles(config);
+  const executed = await getExecutedSeeders(adapter, config.tableName);
+  const executedNames = new Set(executed.map((s) => s.name));
+  const results = [];
+  for (const file of files) {
+    const name = import_path2.default.basename(file, import_path2.default.extname(file));
+    if (executedNames.has(name)) {
+      results.push({ name, status: "skipped" });
+      continue;
+    }
+    const filepath = import_path2.default.join(config.seedersPath, file);
+    await runSingleSeeder(adapter, name, filepath, config.tableName, results);
+  }
+  return results;
+}
+async function runSeederByName(seederName, overrides) {
+  const config = await loadConfig(overrides);
+  const adapter = requireAdapter(config);
+  await ensureTable(adapter, config.tableName);
+  const files = getSeederFiles(config);
+  const file = files.find((f) => import_path2.default.basename(f, import_path2.default.extname(f)) === seederName);
+  if (!file) {
+    throw new Error(`Seeder "${seederName}" not found`);
+  }
+  const results = [];
+  const filepath = import_path2.default.join(config.seedersPath, file);
+  await runSingleSeeder(adapter, seederName, filepath, config.tableName, results);
+  return results;
+}
+async function getSeederStatuses(overrides) {
+  const config = await loadConfig(overrides);
+  const adapter = requireAdapter(config);
+  await ensureTable(adapter, config.tableName);
+  const files = getSeederFiles(config);
+  const tracked = await getAllTrackedSeeders(adapter, config.tableName);
+  const trackedMap = new Map(tracked.map((s) => [s.name, s]));
+  return files.map((f) => {
+    const name = import_path2.default.basename(f, import_path2.default.extname(f));
+    const record = trackedMap.get(name);
+    return {
+      name,
+      status: record?.status ?? "pending",
+      executedAt: record?.executedAt ?? null,
+      error: record?.error ?? null
+    };
+  });
+}
+async function resetSeeder(seederName, overrides) {
+  const config = await loadConfig(overrides);
+  const adapter = requireAdapter(config);
+  await ensureTable(adapter, config.tableName);
+  await deleteSeederRecord(adapter, config.tableName, seederName);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSeederStatuses,
+  loadConfig,
+  resetSeeder,
+  resolveSeedersPath,
+  runPendingSeeders,
+  runSeederByName
+});

package/dist/index.d.cts

@@ -0,0 +1,43 @@
+import { P as PgSeederConfig, S as SeederStatus, a as SeederRunResult, R as ResolvedPgSeederConfig, b as SeedersPathResolver } from './types-CCBHgrLA.cjs';
+export { A as Adapter } from './types-CCBHgrLA.cjs';
+
+declare function runPendingSeeders(overrides?: Partial<PgSeederConfig>): Promise<SeederRunResult[]>;
+declare function runSeederByName(seederName: string, overrides?: Partial<PgSeederConfig>): Promise<SeederRunResult[]>;
+declare function getSeederStatuses(overrides?: Partial<PgSeederConfig>): Promise<SeederStatus[]>;
+declare function resetSeeder(seederName: string, overrides?: Partial<PgSeederConfig>): Promise<void>;
+
+declare function loadConfig(overrides?: Partial<PgSeederConfig>): Promise<ResolvedPgSeederConfig>;
+/**
+ * Pick between a `src/` and `dist/` seeders directory based on the current
+ * runtime. Detection order:
+ *
+ * 1. If `srcWhen` returns `true`, use `src`.
+ * 2. Otherwise, if the entrypoint script lives inside a `dist` directory
+ *    (e.g. `node dist/...`), use `dist`.
+ * 3. Otherwise, if the entrypoint ends with `.ts`/`.tsx` or is loaded via
+ *    `tsx`/`ts-node`, use `src`.
+ * 4. Fall back to `dist`.
+ *
+ * Keeping seeders in the same module graph as the app avoids duplicate entity
+ * or model registration in TypeORM and Sequelize.
+ *
+ * @example
+ * // pg-seed-kit.config.js
+ * import path from 'path';
+ * import { resolveSeedersPath } from 'pg-seed-kit';
+ *
+ * export default {
+ *   seedersPath: resolveSeedersPath({
+ *     src: path.join(process.cwd(), 'src/db/seeders'),
+ *     dist: path.join(process.cwd(), 'dist/db/seeders'),
+ *   }),
+ * };
+ */
+declare function resolveSeedersPath(opts: {
+    src: string;
+    dist: string;
+    /** Optional override (e.g. read NODE_ENV). Returning `true` forces `src`. */
+    srcWhen?: () => boolean;
+}): SeedersPathResolver;
+
+export { PgSeederConfig, ResolvedPgSeederConfig, SeederRunResult, SeederStatus, SeedersPathResolver, getSeederStatuses, loadConfig, resetSeeder, resolveSeedersPath, runPendingSeeders, runSeederByName };

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { P as PgSeederConfig, S as SeederStatus, a as SeederRunResult, R as ResolvedPgSeederConfig, b as SeedersPathResolver } from './types-CCBHgrLA.js';
+export { A as Adapter } from './types-CCBHgrLA.js';
+
+declare function runPendingSeeders(overrides?: Partial<PgSeederConfig>): Promise<SeederRunResult[]>;
+declare function runSeederByName(seederName: string, overrides?: Partial<PgSeederConfig>): Promise<SeederRunResult[]>;
+declare function getSeederStatuses(overrides?: Partial<PgSeederConfig>): Promise<SeederStatus[]>;
+declare function resetSeeder(seederName: string, overrides?: Partial<PgSeederConfig>): Promise<void>;
+
+declare function loadConfig(overrides?: Partial<PgSeederConfig>): Promise<ResolvedPgSeederConfig>;
+/**
+ * Pick between a `src/` and `dist/` seeders directory based on the current
+ * runtime. Detection order:
+ *
+ * 1. If `srcWhen` returns `true`, use `src`.
+ * 2. Otherwise, if the entrypoint script lives inside a `dist` directory
+ *    (e.g. `node dist/...`), use `dist`.
+ * 3. Otherwise, if the entrypoint ends with `.ts`/`.tsx` or is loaded via
+ *    `tsx`/`ts-node`, use `src`.
+ * 4. Fall back to `dist`.
+ *
+ * Keeping seeders in the same module graph as the app avoids duplicate entity
+ * or model registration in TypeORM and Sequelize.
+ *
+ * @example
+ * // pg-seed-kit.config.js
+ * import path from 'path';
+ * import { resolveSeedersPath } from 'pg-seed-kit';
+ *
+ * export default {
+ *   seedersPath: resolveSeedersPath({
+ *     src: path.join(process.cwd(), 'src/db/seeders'),
+ *     dist: path.join(process.cwd(), 'dist/db/seeders'),
+ *   }),
+ * };
+ */
+declare function resolveSeedersPath(opts: {
+    src: string;
+    dist: string;
+    /** Optional override (e.g. read NODE_ENV). Returning `true` forces `src`. */
+    srcWhen?: () => boolean;
+}): SeedersPathResolver;
+
+export { PgSeederConfig, ResolvedPgSeederConfig, SeederRunResult, SeederStatus, SeedersPathResolver, getSeederStatuses, loadConfig, resetSeeder, resolveSeedersPath, runPendingSeeders, runSeederByName };

package/dist/index.js

@@ -0,0 +1,16 @@
+import {
+  getSeederStatuses,
+  loadConfig,
+  resetSeeder,
+  resolveSeedersPath,
+  runPendingSeeders,
+  runSeederByName
+} from "./chunk-KMXBCJZY.js";
+export {
+  getSeederStatuses,
+  loadConfig,
+  resetSeeder,
+  resolveSeedersPath,
+  runPendingSeeders,
+  runSeederByName
+};

package/dist/types-CCBHgrLA.d.cts

@@ -0,0 +1,57 @@
+/**
+ * The single abstraction the core depends on. An adapter exposes one method,
+ * `query`, that runs parameterized SQL (Postgres `$1`, `$2`, ... placeholders)
+ * against a live connection and returns the result rows.
+ *
+ * pg-seed-kit ships no database driver of its own: adapters are built on top of
+ * the connection your ORM already owns (see `pg-seed-kit/typeorm`,
+ * `pg-seed-kit/prisma`, and friends). The adapter is used only for the library's
+ * own tracking table; your seeders talk to the database through your ORM.
+ */
+interface Adapter {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Optional teardown, invoked by the CLI after a standalone run. */
+    close?(): Promise<void>;
+}
+/**
+ * `seedersPath` may be a static string or a function evaluated lazily when a
+ * runner is invoked. The function form lets consumers choose between a `src/`
+ * tree (loaded by tsx/ts-node in development) and a `dist/` tree (loaded by
+ * `node dist/...` in production), keeping seeders in the same module graph as
+ * the rest of the app.
+ */
+type SeedersPathResolver = () => string;
+interface PgSeederConfig {
+    seedersPath: string | SeedersPathResolver;
+    /** Table used to track seeder execution. Defaults to `seeders`. */
+    tableName?: string;
+    filePattern?: RegExp;
+    /** A live adapter. Provide this when calling the API from your running app. */
+    adapter?: Adapter;
+    /**
+     * Used by the CLI only: connects the ORM and returns an adapter. Lets the
+     * standalone CLI open a connection in its own process, then close it.
+     */
+    connect?: () => Promise<Adapter>;
+}
+/** Internal shape after `loadConfig` has resolved any function form. */
+interface ResolvedPgSeederConfig {
+    seedersPath: string;
+    tableName: string;
+    filePattern: RegExp;
+    adapter?: Adapter;
+    connect?: () => Promise<Adapter>;
+}
+interface SeederRunResult {
+    name: string;
+    status: 'success' | 'failed' | 'skipped';
+    error?: string;
+}
+interface SeederStatus {
+    name: string;
+    status: 'success' | 'failed' | 'pending';
+    executedAt: Date | null;
+    error: string | null;
+}
+
+export type { Adapter as A, PgSeederConfig as P, ResolvedPgSeederConfig as R, SeederStatus as S, SeederRunResult as a, SeedersPathResolver as b };

package/dist/types-CCBHgrLA.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The single abstraction the core depends on. An adapter exposes one method,
+ * `query`, that runs parameterized SQL (Postgres `$1`, `$2`, ... placeholders)
+ * against a live connection and returns the result rows.
+ *
+ * pg-seed-kit ships no database driver of its own: adapters are built on top of
+ * the connection your ORM already owns (see `pg-seed-kit/typeorm`,
+ * `pg-seed-kit/prisma`, and friends). The adapter is used only for the library's
+ * own tracking table; your seeders talk to the database through your ORM.
+ */
+interface Adapter {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Optional teardown, invoked by the CLI after a standalone run. */
+    close?(): Promise<void>;
+}
+/**
+ * `seedersPath` may be a static string or a function evaluated lazily when a
+ * runner is invoked. The function form lets consumers choose between a `src/`
+ * tree (loaded by tsx/ts-node in development) and a `dist/` tree (loaded by
+ * `node dist/...` in production), keeping seeders in the same module graph as
+ * the rest of the app.
+ */
+type SeedersPathResolver = () => string;
+interface PgSeederConfig {
+    seedersPath: string | SeedersPathResolver;
+    /** Table used to track seeder execution. Defaults to `seeders`. */
+    tableName?: string;
+    filePattern?: RegExp;
+    /** A live adapter. Provide this when calling the API from your running app. */
+    adapter?: Adapter;
+    /**
+     * Used by the CLI only: connects the ORM and returns an adapter. Lets the
+     * standalone CLI open a connection in its own process, then close it.
+     */
+    connect?: () => Promise<Adapter>;
+}
+/** Internal shape after `loadConfig` has resolved any function form. */
+interface ResolvedPgSeederConfig {
+    seedersPath: string;
+    tableName: string;
+    filePattern: RegExp;
+    adapter?: Adapter;
+    connect?: () => Promise<Adapter>;
+}
+interface SeederRunResult {
+    name: string;
+    status: 'success' | 'failed' | 'skipped';
+    error?: string;
+}
+interface SeederStatus {
+    name: string;
+    status: 'success' | 'failed' | 'pending';
+    executedAt: Date | null;
+    error: string | null;
+}
+
+export type { Adapter as A, PgSeederConfig as P, ResolvedPgSeederConfig as R, SeederStatus as S, SeederRunResult as a, SeedersPathResolver as b };