@cfast/db 0.5.0 → 0.7.0

package/dist/seed.d.ts

@@ -0,0 +1,328 @@
+import { DrizzleTable } from '@cfast/permissions';
+import { a as Db, i as InferRow } from './types-FUFR36h1.js';
+import { Column } from 'drizzle-orm';
+import { SQLiteColumnBuilderBase, SQLiteTableExtraConfigValue } from 'drizzle-orm/sqlite-core';
+import { BuildColumns } from 'drizzle-orm/column-builder';
+import { SQLiteTableWithColumns } from 'drizzle-orm/sqlite-core/table';
+
+/**
+ * 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;
+};
+/**
+ * Stores column-level seed functions keyed by the column builder's `config`
+ * object. Drizzle shares the same `config` reference between the builder
+ * (what the user passes to `sqliteTable(...)`) and the built column (what
+ * `getTableColumns()` returns), so we can look up the seed fn from either
+ * side. This avoids the builder-vs-column identity mismatch.
+ *
+ * Exported so the `.seed()` prototype patches in `seed.ts` can write to
+ * the same registries. Application code should use `.seed()` or
+ * `seedConfig()`/`tableSeed()` rather than accessing these directly.
+ */
+declare const columnSeedMap: WeakMap<object, ColumnSeedFn>;
+declare const tableSeedMap: WeakMap<object, TableSeedConfig>;
+/**
+ * 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.
+ *
+ * @deprecated Use the `.seed()` method on column builders instead:
+ * ```ts
+ * text("title").seed(f => f.lorem.sentence())
+ * ```
+ *
+ * @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.
+ *
+ * @deprecated Use `table()` from `@cfast/db/seed` with `.seed()` instead:
+ * ```ts
+ * import { table } from "@cfast/db/seed";
+ * const posts = table("posts", { ... }).seed({ count: 5, per: users });
+ * ```
+ *
+ * @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;
+
+declare module "drizzle-orm/sqlite-core" {
+    interface SQLiteColumnBuilder<T, TRuntimeConfig, TTypeConfig, TExtraConfig> {
+        /**
+         * Attaches a seed generator function to this column.
+         *
+         * @example
+         * ```ts
+         * title: text("title").seed(f => f.lorem.sentence()),
+         * ```
+         */
+        seed(fn: ColumnSeedFn): this;
+    }
+}
+
+/**
+ * Type representing a Drizzle table with an added `.seed()` method.
+ * The `.seed()` method returns the same table reference for chaining.
+ */
+type SeedableTable<T> = T & {
+    seed(config: TableSeedConfig): SeedableTable<T>;
+};
+/**
+ * Creates a SQLite table with a `.seed()` method for configuring
+ * seed generation. Drop-in replacement for `sqliteTable()` from
+ * `drizzle-orm/sqlite-core`.
+ *
+ * @example
+ * ```ts
+ * import { table } from "@cfast/db/seed";
+ *
+ * const posts = table("posts", {
+ *   title: text("title").seed(f => f.lorem.sentence()),
+ *   authorId: text("author_id").references(() => users.id),
+ * }).seed({ count: 5, per: users });
+ * ```
+ */
+declare function table<TTableName extends string, TColumnsMap extends Record<string, SQLiteColumnBuilderBase>>(name: TTableName, columns: TColumnsMap, extraConfig?: (self: BuildColumns<TTableName, TColumnsMap, "sqlite">) => SQLiteTableExtraConfigValue[]): SeedableTable<SQLiteTableWithColumns<{
+    name: TTableName;
+    schema: undefined;
+    columns: BuildColumns<TTableName, TColumnsMap, "sqlite">;
+    dialect: "sqlite";
+}>>;
+
+/**
+ * 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 SeedableTable, type TableSeedConfig, columnSeedMap, createSeedEngine, createSingleTableSeed, defineSeed, extractForeignKeys, findPrimaryKeyColumn, isTable, seed, seedConfig, table, tableSeed, tableSeedMap, topologicalSort };