@cfast/db 0.5.0 → 0.6.0

package/dist/seed.d.ts

@@ -0,0 +1,258 @@
+import { DrizzleTable } from '@cfast/permissions';
+import { a as Db, i as InferRow } from './types-FUFR36h1.js';
+import { Column } from 'drizzle-orm';
+
+/**
+ * Schema-driven seed generator for `@cfast/db`.
+ *
+ * Introspects Drizzle schema metadata (column types, foreign keys, primary keys)
+ * to auto-generate realistic test data using the bundled `@faker-js/faker`.
+ * Supports:
+ *
+ * - Column-level `.seed()` overrides via `seedConfig()` wrapper
+ * - Table-level `.seed()` overrides via `tableSeed()` wrapper (count, per)
+ * - Automatic FK resolution from generated parent rows
+ * - `per` relational generation (N children per parent row)
+ * - `ctx` API for parent access, ref, index, and all
+ * - Topological sort for correct insert order
+ * - Many-to-many deduplication
+ * - Auth table detection for realistic emails
+ * - SQL transcript generation
+ *
+ * @module seed-generator
+ */
+
+type AnyColumn = Column<any, any, any>;
+/** Faker instance type -- matches `@faker-js/faker`'s default export. */
+type Faker = any;
+/**
+ * Context passed to column-level seed functions as the second argument.
+ */
+type SeedContext = {
+    /** The parent row when `per` is used on the table. `undefined` for root tables. */
+    parent: Record<string, unknown> | undefined;
+    /** Pick a random existing row from any table already seeded. */
+    ref: (table: DrizzleTable) => Record<string, unknown>;
+    /** Zero-based position within the current batch (per-parent or global). */
+    index: number;
+    /** All generated rows for the given table (available after that table is seeded). */
+    all: (table: DrizzleTable) => Record<string, unknown>[];
+};
+/** Column-level seed function. Receives faker instance and optional context. */
+type ColumnSeedFn = (faker: Faker, ctx: SeedContext) => unknown;
+/** Table-level seed config attached via `tableSeed()`. */
+type TableSeedConfig = {
+    /** Total count (or per-parent count when `per` is set). */
+    count: number;
+    /** Generate `count` rows per row in this parent table. */
+    per?: DrizzleTable;
+};
+/** Options for `db.seed().run()`. */
+type SeedRunOptions = {
+    /** If provided, write the equivalent SQL INSERT statements to this path. */
+    transcript?: string;
+};
+/**
+ * Attaches a seed generator function to a Drizzle column.
+ *
+ * The column object is returned unmodified so this can be used inline in
+ * schema definitions without breaking Drizzle types.
+ *
+ * @example
+ * ```ts
+ * const posts = sqliteTable("posts", {
+ *   title: seedConfig(text("title"), f => f.lorem.sentence()),
+ * });
+ * ```
+ */
+declare function seedConfig<T>(column: T, fn: ColumnSeedFn): T;
+/**
+ * Attaches table-level seed config (count, per) to a Drizzle table.
+ *
+ * @example
+ * ```ts
+ * const posts = tableSeed(
+ *   sqliteTable("posts", { ... }),
+ *   { count: 5, per: users },
+ * );
+ * ```
+ */
+declare function tableSeed<T extends DrizzleTable>(table: T, config: TableSeedConfig): T;
+/** FK info extracted from Drizzle's internal symbol. */
+type FkInfo = {
+    /** Column name in the current table (SQL name). */
+    columnName: string;
+    /** JS key of the column in the current table. */
+    columnKey: string;
+    /** Referenced table (Drizzle object). */
+    foreignTable: DrizzleTable;
+    /** Referenced column name (SQL name). */
+    foreignColumnName: string;
+};
+/** Extracts all inline foreign key definitions from a Drizzle table. */
+declare function extractForeignKeys(table: DrizzleTable): FkInfo[];
+/** Returns the JS key for the primary key column(s). Only supports single PK. */
+declare function findPrimaryKeyColumn(table: DrizzleTable): {
+    key: string;
+    column: AnyColumn;
+} | undefined;
+/**
+ * Topologically sorts tables so parents are seeded before children.
+ * Uses Kahn's algorithm. Respects both FK and `per` dependencies.
+ */
+declare function topologicalSort(tables: DrizzleTable[], fkMap: Map<DrizzleTable, FkInfo[]>): DrizzleTable[];
+/**
+ * Generates seed data for all tables in a schema using Drizzle column metadata
+ * and the bundled `@faker-js/faker` instance.
+ *
+ * @param schema - The full Drizzle schema (`import * as schema from "./schema"`).
+ * @returns An engine with `generate()` and `run(db)` methods.
+ */
+declare function createSeedEngine(schema: Record<string, unknown>): {
+    tables: object[];
+    fkMap: Map<object, FkInfo[]>;
+    /**
+     * Generate rows for all tables (or a subset).
+     * Returns a map of table -> rows[].
+     */
+    generate(tableOverrides?: Map<DrizzleTable, {
+        count: number;
+    }>): Map<DrizzleTable, Record<string, unknown>[]>;
+    /**
+     * Generate and insert seed data into the database.
+     */
+    run(db: Db, options?: SeedRunOptions & {
+        tableOverrides?: Map<DrizzleTable, {
+            count: number;
+        }>;
+    }): Promise<Map<DrizzleTable, Record<string, unknown>[]>>;
+};
+/**
+ * Creates a single-table seed generator for use with `db.query(table).seed(n)`.
+ */
+declare function createSingleTableSeed(schema: Record<string, unknown>, table: DrizzleTable, count: number): {
+    generate: () => Map<object, Record<string, unknown>[]>;
+    run: (db: Db, options?: SeedRunOptions) => Promise<Map<object, Record<string, unknown>[]>>;
+};
+/**
+ * Checks if a value is a Drizzle table by looking for the IsDrizzleTable symbol.
+ */
+declare function isTable(value: unknown): boolean;
+
+/**
+ * One-liner seed: introspects the schema from the `db` instance, generates
+ * realistic data via the bundled `@faker-js/faker`, and inserts it.
+ *
+ * @example
+ * ```ts
+ * import { seed } from "@cfast/db/seed";
+ * await seed(db);
+ * ```
+ *
+ * @param db - A {@link Db} instance created via `createDb()`.
+ * @param options - Optional {@link SeedRunOptions} (e.g. `{ transcript: "./seed.sql" }`).
+ */
+declare function seed(db: Db, options?: SeedRunOptions): Promise<void>;
+/**
+ * A single seed entry — every row in `rows` is inserted into `table` at seed
+ * time. Row shape is inferred from the Drizzle table so typos in column names
+ * are caught by `tsc` instead of failing at runtime when `INSERT` rejects
+ * the statement.
+ *
+ * @typeParam TTable - The Drizzle table reference (e.g. `typeof usersTable`).
+ */
+type SeedEntry<TTable extends DrizzleTable = DrizzleTable> = {
+    /**
+     * The Drizzle table to insert into. Must be imported from your schema
+     * (`import { users } from "~/db/schema"`) rather than passed as a string
+     * so the helper can infer row types and forward the reference to
+     * `db.insert()`.
+     */
+    table: TTable;
+    /**
+     * Rows to insert. The row shape is inferred from the table's
+     * `$inferSelect` — making a typo in a column name is a compile-time error.
+     *
+     * Entries are inserted in the order they appear, which lets you control
+     * foreign-key ordering just by ordering your `entries` array
+     * (`{ users }` before `{ posts }`, etc.).
+     */
+    rows: readonly InferRow<TTable>[];
+};
+/**
+ * Configuration passed to {@link defineSeed}.
+ */
+type SeedConfig = {
+    /**
+     * Ordered list of seed entries. Each entry is flushed as a batched insert
+     * in list order, so place parent tables (users, orgs) before child tables
+     * (posts, memberships) that reference them via foreign keys.
+     */
+    entries: readonly SeedEntry[];
+};
+/**
+ * The compiled seed returned by {@link defineSeed}.
+ *
+ * Holds a frozen copy of the entry list so runner callers can introspect
+ * what would be seeded, plus a `run(db)` method that actually executes the
+ * inserts against a real {@link Db} instance.
+ */
+type Seed = {
+    /** The frozen list of entries this seed will insert, in order. */
+    readonly entries: readonly SeedEntry[];
+    /**
+     * Executes every entry against the given {@link Db} in the order they were
+     * declared. Uses `db.unsafe()` internally so seed scripts don't need
+     * their own grants plumbing — seeding is a system task by definition.
+     *
+     * Entries with an empty `rows` array are skipped so callers can leave
+     * placeholder entries in the config without crashing the seed.
+     *
+     * @param db - A {@link Db} instance, typically created once at the top
+     *   of a `scripts/seed.ts` file via `createDb({...})`.
+     */
+    run: (db: Db) => Promise<void>;
+};
+/**
+ * Declares a database seed in a portable, type-safe way.
+ *
+ * The canonical replacement for hand-rolled `scripts/seed.ts` files that
+ * called `db.mutate("tablename")` (a method that never existed) or reached
+ * straight into raw Drizzle. Use the scaffolded `scripts/seed.ts` in a
+ * `create-cfast` project for a ready-made example.
+ *
+ * @example
+ * ```ts
+ * // scripts/seed.ts
+ * import { defineSeed, createDb } from "@cfast/db";
+ * import * as schema from "~/db/schema";
+ *
+ * const seed = defineSeed({
+ *   entries: [
+ *     {
+ *       table: schema.users,
+ *       rows: [
+ *         { id: "u-1", email: "ada@example.com", name: "Ada" },
+ *         { id: "u-2", email: "grace@example.com", name: "Grace" },
+ *       ],
+ *     },
+ *     {
+ *       table: schema.posts,
+ *       rows: [
+ *         { id: "p-1", authorId: "u-1", title: "Hello" },
+ *       ],
+ *     },
+ *   ],
+ * });
+ *
+ * // In a worker/runner that already has a real D1 binding:
+ * const db = createDb({ d1, schema, grants: [], user: null });
+ * await seed.run(db);
+ * ```
+ *
+ * @param config - The {@link SeedConfig} with the ordered list of entries.
+ * @returns A {@link Seed} with a `.run(db)` executor.
+ */
+declare function defineSeed(config: SeedConfig): Seed;
+
+export { type ColumnSeedFn, type Faker, type Seed, type SeedConfig, type SeedContext, type SeedEntry, type SeedRunOptions, type TableSeedConfig, createSeedEngine, createSingleTableSeed, defineSeed, extractForeignKeys, findPrimaryKeyColumn, isTable, seed, seedConfig, tableSeed, topologicalSort };

package/dist/seed.js

@@ -0,0 +1,378 @@
+// src/seed-generator.ts
+import { faker } from "@faker-js/faker";
+import { getTableColumns, getTableName } from "drizzle-orm";
+function asTable(t) {
+  return t;
+}
+var columnSeedMap = /* @__PURE__ */ new WeakMap();
+var tableSeedMap = /* @__PURE__ */ new WeakMap();
+function getColumnSeedFn(col) {
+  const config = col.config;
+  if (config) {
+    const fn = columnSeedMap.get(config);
+    if (fn) return fn;
+  }
+  return columnSeedMap.get(col);
+}
+function seedConfig(column, fn) {
+  const config = column.config;
+  if (config && typeof config === "object") {
+    columnSeedMap.set(config, fn);
+  }
+  columnSeedMap.set(column, fn);
+  return column;
+}
+function tableSeed(table, config) {
+  tableSeedMap.set(table, config);
+  return table;
+}
+function extractForeignKeys(table) {
+  const fkSymbol = Object.getOwnPropertySymbols(table).find(
+    (s) => s.toString().includes("InlineForeignKeys")
+  );
+  if (!fkSymbol) return [];
+  const fks = table[fkSymbol];
+  const columns = getTableColumns(asTable(table));
+  const sqlNameToKey = /* @__PURE__ */ new Map();
+  for (const [key, col] of Object.entries(columns)) {
+    sqlNameToKey.set(col.name, key);
+  }
+  const result = [];
+  for (const fk of fks) {
+    if (typeof fk?.reference !== "function") continue;
+    const ref = fk.reference();
+    if (!ref?.foreignTable || !ref.foreignColumns?.length || !ref.columns?.length) continue;
+    const colSqlName = ref.columns[0].name;
+    result.push({
+      columnName: colSqlName,
+      columnKey: sqlNameToKey.get(colSqlName) ?? colSqlName,
+      foreignTable: ref.foreignTable,
+      foreignColumnName: ref.foreignColumns[0].name
+    });
+  }
+  return result;
+}
+function findPrimaryKeyColumn(table) {
+  const columns = getTableColumns(asTable(table));
+  for (const [key, col] of Object.entries(columns)) {
+    if (col.primary) {
+      return { key, column: col };
+    }
+  }
+  return void 0;
+}
+function generateDefaultValue(col, isPk, isNullable) {
+  if (isPk) return faker.string.uuid();
+  if (isNullable && faker.number.int({ min: 0, max: 9 }) === 0) return null;
+  const { dataType, columnType } = col;
+  if (columnType === "SQLiteBoolean" || dataType === "boolean") {
+    return faker.datatype.boolean();
+  }
+  if (columnType === "SQLiteTimestamp" || dataType === "date") {
+    return faker.date.recent();
+  }
+  if (columnType === "SQLiteReal") {
+    return faker.number.float({ min: 0, max: 1e3, fractionDigits: 2 });
+  }
+  if (columnType === "SQLiteInteger" || dataType === "number") {
+    return faker.number.int({ min: 0, max: 1e4 });
+  }
+  if (columnType === "SQLiteText" || dataType === "string") {
+    return faker.lorem.words(3);
+  }
+  if (dataType === "buffer") {
+    return faker.string.alphanumeric(16);
+  }
+  return faker.lorem.words(2);
+}
+var AUTH_TABLE_NAME = "users";
+function isAuthUsersTable(table) {
+  return getTableName(asTable(table)) === AUTH_TABLE_NAME;
+}
+function generateAuthEmail(index) {
+  const roles = ["admin", "user", "editor", "viewer", "moderator"];
+  if (index < roles.length) {
+    return `${roles[index]}@example.com`;
+  }
+  return faker.internet.email().toLowerCase();
+}
+function topologicalSort(tables, fkMap) {
+  const tableSet = new Set(tables);
+  const inDegree = /* @__PURE__ */ new Map();
+  const dependents = /* @__PURE__ */ new Map();
+  for (const t of tables) {
+    if (!inDegree.has(t)) inDegree.set(t, 0);
+    if (!dependents.has(t)) dependents.set(t, /* @__PURE__ */ new Set());
+  }
+  for (const t of tables) {
+    const fks = fkMap.get(t) ?? [];
+    const deps = /* @__PURE__ */ new Set();
+    for (const fk of fks) {
+      if (tableSet.has(fk.foreignTable) && fk.foreignTable !== t) {
+        deps.add(fk.foreignTable);
+      }
+    }
+    const tConfig = tableSeedMap.get(t);
+    if (tConfig?.per && tableSet.has(tConfig.per) && tConfig.per !== t) {
+      deps.add(tConfig.per);
+    }
+    inDegree.set(t, deps.size);
+    for (const dep of deps) {
+      if (!dependents.has(dep)) dependents.set(dep, /* @__PURE__ */ new Set());
+      dependents.get(dep).add(t);
+    }
+  }
+  const queue = [];
+  for (const [t, deg] of inDegree) {
+    if (deg === 0) queue.push(t);
+  }
+  const sorted = [];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    sorted.push(current);
+    for (const dep of dependents.get(current) ?? []) {
+      const newDeg = (inDegree.get(dep) ?? 1) - 1;
+      inDegree.set(dep, newDeg);
+      if (newDeg === 0) queue.push(dep);
+    }
+  }
+  for (const t of tables) {
+    if (!sorted.includes(t)) sorted.push(t);
+  }
+  return sorted;
+}
+function getDeduplicationKeys(_table, fks) {
+  if (fks.length >= 2) {
+    return fks.map((f) => f.columnKey);
+  }
+  return null;
+}
+function createSeedEngine(schema) {
+  const tables = [];
+  for (const value of Object.values(schema)) {
+    if (isTable(value)) {
+      tables.push(value);
+    }
+  }
+  const fkMap = /* @__PURE__ */ new Map();
+  for (const table of tables) {
+    fkMap.set(table, extractForeignKeys(table));
+  }
+  const sorted = topologicalSort(tables, fkMap);
+  return {
+    tables: sorted,
+    fkMap,
+    /**
+     * Generate rows for all tables (or a subset).
+     * Returns a map of table -> rows[].
+     */
+    generate(tableOverrides) {
+      const generated = /* @__PURE__ */ new Map();
+      for (const table of sorted) {
+        const config = tableOverrides?.get(table) ?? tableSeedMap.get(table);
+        const fks = fkMap.get(table) ?? [];
+        const columns = getTableColumns(asTable(table));
+        const pk = findPrimaryKeyColumn(table);
+        const isAuth = isAuthUsersTable(table);
+        const dedupKeys = getDeduplicationKeys(table, fks);
+        const count = config?.count ?? 10;
+        const perTable = config?.per;
+        const parentRows = perTable ? generated.get(perTable) ?? [] : [void 0];
+        const allRows = [];
+        const seenCombos = /* @__PURE__ */ new Set();
+        let globalIndex = 0;
+        for (const parentRow of parentRows) {
+          for (let i = 0; i < count; i++) {
+            const ctx = {
+              parent: parentRow,
+              ref: (t) => {
+                const rows = generated.get(t);
+                if (!rows || rows.length === 0) {
+                  throw new Error(
+                    `seedConfig ctx.ref(${getTableName(asTable(t))}): no rows generated yet`
+                  );
+                }
+                return rows[faker.number.int({ min: 0, max: rows.length - 1 })];
+              },
+              index: i,
+              all: (t) => generated.get(t) ?? []
+            };
+            const row = {};
+            for (const [key, col] of Object.entries(columns)) {
+              const colObj = col;
+              const isPk = pk?.key === key;
+              const isNullable = !colObj.notNull;
+              const customSeedFn = getColumnSeedFn(colObj);
+              if (customSeedFn) {
+                row[key] = customSeedFn(faker, ctx);
+                continue;
+              }
+              const fk = fks.find((f) => f.columnKey === key);
+              if (fk) {
+                if (perTable && parentRow && getTableName(asTable(fk.foreignTable)) === getTableName(asTable(perTable))) {
+                  const foreignColumns = getTableColumns(asTable(fk.foreignTable));
+                  const foreignKey = Object.entries(foreignColumns).find(
+                    ([, c]) => c.name === fk.foreignColumnName
+                  );
+                  if (foreignKey) {
+                    row[key] = parentRow[foreignKey[0]];
+                    continue;
+                  }
+                }
+                const refRows = generated.get(fk.foreignTable);
+                if (refRows && refRows.length > 0) {
+                  const randomRef = refRows[faker.number.int({ min: 0, max: refRows.length - 1 })];
+                  const foreignColumns = getTableColumns(asTable(fk.foreignTable));
+                  const foreignKey = Object.entries(foreignColumns).find(
+                    ([, c]) => c.name === fk.foreignColumnName
+                  );
+                  if (foreignKey) {
+                    row[key] = randomRef[foreignKey[0]];
+                    continue;
+                  }
+                }
+              }
+              if (isAuth && key === "email") {
+                row[key] = generateAuthEmail(globalIndex);
+                continue;
+              }
+              if (isAuth && key === "name") {
+                row[key] = faker.person.fullName();
+                continue;
+              }
+              const colAny = colObj;
+              if (colAny.defaultFn || colAny.onUpdateFn) {
+                continue;
+              }
+              if (colAny.hasDefault && colAny.default !== void 0) {
+                continue;
+              }
+              row[key] = generateDefaultValue(colObj, isPk, isNullable);
+            }
+            if (dedupKeys) {
+              const comboKey = dedupKeys.map((k) => String(row[k])).join(":");
+              if (seenCombos.has(comboKey)) continue;
+              seenCombos.add(comboKey);
+            }
+            allRows.push(row);
+            globalIndex++;
+          }
+        }
+        generated.set(table, allRows);
+      }
+      return generated;
+    },
+    /**
+     * Generate and insert seed data into the database.
+     */
+    async run(db, options) {
+      const generated = this.generate(options?.tableOverrides);
+      const unsafeDb = db.unsafe();
+      const transcriptLines = [];
+      for (const table of sorted) {
+        const rows = generated.get(table);
+        if (!rows || rows.length === 0) continue;
+        const tableName = getTableName(asTable(table));
+        if (options?.transcript) {
+          for (const row of rows) {
+            const colNames = Object.keys(row);
+            const values = colNames.map((k) => {
+              const v = row[k];
+              if (v === null) return "NULL";
+              if (typeof v === "number" || typeof v === "boolean") return String(v);
+              if (v instanceof Date) return `'${v.toISOString()}'`;
+              return `'${String(v).replace(/'/g, "''")}'`;
+            });
+            transcriptLines.push(
+              `INSERT INTO "${tableName}" (${colNames.map((c) => `"${c}"`).join(", ")}) VALUES (${values.join(", ")});`
+            );
+          }
+        }
+        const ops = rows.map(
+          (row) => unsafeDb.insert(table).values(row)
+        );
+        if (ops.length === 1) {
+          await ops[0].run({});
+        } else {
+          await unsafeDb.batch(ops).run({});
+        }
+      }
+      if (options?.transcript && transcriptLines.length > 0) {
+        try {
+          const fs = await new Function(
+            'return import("node:fs/promises")'
+          )();
+          await fs.writeFile(
+            options.transcript,
+            transcriptLines.join("\n") + "\n",
+            "utf-8"
+          );
+        } catch {
+        }
+      }
+      return generated;
+    }
+  };
+}
+function createSingleTableSeed(schema, table, count) {
+  const engine = createSeedEngine(schema);
+  const overrides = /* @__PURE__ */ new Map();
+  overrides.set(table, { count });
+  for (const t of engine.tables) {
+    if (t !== table && !overrides.has(t)) {
+      overrides.set(t, { count: 0 });
+    }
+  }
+  return {
+    generate: () => engine.generate(overrides),
+    run: (db, options) => engine.run(db, { ...options, tableOverrides: overrides })
+  };
+}
+function isTable(value) {
+  if (!value || typeof value !== "object") return false;
+  const symbols = Object.getOwnPropertySymbols(value);
+  return symbols.some((s) => s.toString().includes("IsDrizzleTable"));
+}
+
+// src/seed.ts
+async function seed(db, options) {
+  const engine = createSeedEngine(db._schema);
+  await engine.run(db, options);
+}
+function defineSeed(config) {
+  const entries = Object.freeze(
+    config.entries.map((entry) => ({
+      table: entry.table,
+      rows: Object.freeze([...entry.rows])
+    }))
+  );
+  return {
+    entries,
+    async run(db) {
+      const unsafeDb = db.unsafe();
+      for (const entry of entries) {
+        if (entry.rows.length === 0) continue;
+        const ops = entry.rows.map(
+          (row) => unsafeDb.insert(entry.table).values(row)
+        );
+        if (ops.length === 1) {
+          await ops[0].run({});
+        } else {
+          await unsafeDb.batch(ops).run({});
+        }
+      }
+    }
+  };
+}
+export {
+  createSeedEngine,
+  createSingleTableSeed,
+  defineSeed,
+  extractForeignKeys,
+  findPrimaryKeyColumn,
+  isTable,
+  seed,
+  seedConfig,
+  tableSeed,
+  topologicalSort
+};