@cfast/db 0.4.1 → 0.6.0

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
+};

package/dist/types-FUFR36h1.d.ts

@@ -0,0 +1,221 @@
+import { Grant, DrizzleTable, PermissionDescriptor } from '@cfast/permissions';
+import { Table, TablesRelationalConfig, ExtractTablesWithRelations, TableRelationalConfig, BuildQueryResult } from 'drizzle-orm';
+
+/**
+ * Augments a row type with a `_can` object containing per-action booleans.
+ *
+ * Every query result from `findMany` / `findFirst` includes `_can` when the
+ * `Db` was created with grants and a user. Each CRUD action maps to `true`
+ * (permitted for this row), `false` (denied), or a row-dependent boolean
+ * when the grant has a `where` clause.
+ */
+type WithCan<T> = T & {
+    _can: Record<string, boolean>;
+};
+type InferRow<TTable> = TTable extends {
+    $inferSelect: infer R;
+} ? R : Record<string, unknown>;
+/** @internal */
+type FindTableKeyByName<TSchema extends TablesRelationalConfig, TTableName extends string> = {
+    [K in keyof TSchema]: TSchema[K]["dbName"] extends TTableName ? K : never;
+}[keyof TSchema];
+/** @internal */
+type LookupTableConfig<TFullSchema extends Record<string, unknown>, TTable> = TTable extends Table<infer TTableConfig> ? FindTableKeyByName<ExtractTablesWithRelations<TFullSchema>, TTableConfig["name"]> extends infer TKey extends keyof ExtractTablesWithRelations<TFullSchema> ? ExtractTablesWithRelations<TFullSchema>[TKey] : never : never;
+type InferQueryResult<TFullSchema extends Record<string, unknown>, TTable, TConfig> = [TFullSchema] extends [Record<string, never>] ? InferRow<TTable> : LookupTableConfig<TFullSchema, TTable> extends infer TTableConfig extends TableRelationalConfig ? BuildQueryResult<ExtractTablesWithRelations<TFullSchema>, TTableConfig, TConfig extends Record<string, unknown> ? TConfig : true> : InferRow<TTable>;
+type Operation<TResult> = {
+    permissions: PermissionDescriptor[];
+    run: (params?: Record<string, unknown>) => Promise<TResult>;
+};
+type CacheBackend = "cache-api" | "kv";
+type CacheConfig = {
+    backend: CacheBackend;
+    kv?: KVNamespace;
+    ttl?: string;
+    staleWhileRevalidate?: string;
+    exclude?: string[];
+    onHit?: (key: string, table: string) => void;
+    onMiss?: (key: string, table: string) => void;
+    onInvalidate?: (tables: string[]) => void;
+};
+type QueryCacheOptions = false | {
+    ttl?: string;
+    staleWhileRevalidate?: string;
+    tags?: string[];
+};
+type DbConfig<TSchema extends Record<string, unknown> = Record<string, unknown>> = {
+    d1: D1Database;
+    schema: TSchema;
+    grants: Grant[];
+    user: {
+        id: string;
+    } | null;
+    cache?: CacheConfig | false;
+};
+type FindManyOptions = {
+    columns?: Record<string, boolean>;
+    where?: unknown;
+    orderBy?: unknown;
+    limit?: number;
+    offset?: number;
+    with?: Record<string, unknown>;
+    cache?: QueryCacheOptions;
+};
+type FindFirstOptions = Omit<FindManyOptions, "limit" | "offset">;
+type CursorParams = {
+    type: "cursor";
+    cursor: string | null;
+    limit: number;
+};
+type OffsetParams = {
+    type: "offset";
+    page: number;
+    limit: number;
+};
+type PaginateParams = CursorParams | OffsetParams;
+type CursorPage<T> = {
+    items: T[];
+    nextCursor: string | null;
+};
+type OffsetPage<T> = {
+    items: T[];
+    total: number;
+    page: number;
+    totalPages: number;
+};
+type PaginateOptions = {
+    columns?: Record<string, boolean>;
+    where?: unknown;
+    orderBy?: unknown;
+    cursorColumns?: unknown[];
+    orderDirection?: "asc" | "desc";
+    with?: Record<string, unknown>;
+    cache?: QueryCacheOptions;
+};
+type TransactionResult<T> = {
+    result: T;
+    meta: {
+        changes: number;
+        writeResults: D1Result[];
+    };
+};
+type Tx<TSchema extends Record<string, unknown> = Record<string, never>> = {
+    query: <TTable extends DrizzleTable>(table: TTable) => QueryBuilder<TTable, TSchema>;
+    insert: <TTable extends DrizzleTable>(table: TTable) => InsertBuilder<TTable>;
+    update: <TTable extends DrizzleTable>(table: TTable) => UpdateBuilder<TTable>;
+    delete: <TTable extends DrizzleTable>(table: TTable) => DeleteBuilder<TTable>;
+    transaction: <T>(callback: (tx: Tx<TSchema>) => Promise<T>) => Promise<T>;
+};
+type Db<TSchema extends Record<string, unknown> = Record<string, never>> = {
+    query: <TTable extends DrizzleTable>(table: TTable) => QueryBuilder<TTable, TSchema>;
+    insert: <TTable extends DrizzleTable>(table: TTable) => InsertBuilder<TTable>;
+    update: <TTable extends DrizzleTable>(table: TTable) => UpdateBuilder<TTable>;
+    delete: <TTable extends DrizzleTable>(table: TTable) => DeleteBuilder<TTable>;
+    unsafe: () => Db<TSchema>;
+    batch: (operations: Operation<unknown>[]) => Operation<unknown[]>;
+    /**
+     * Runs a callback inside a transaction with atomic commit-or-rollback semantics.
+     *
+     * All writes (`tx.insert`/`tx.update`/`tx.delete`) recorded inside the callback
+     * are deferred and flushed together as a single atomic `db.batch([...])` when
+     * the callback returns successfully. If the callback throws, pending writes are
+     * discarded and the error is re-thrown — nothing reaches D1.
+     *
+     * Reads (`tx.query(...)`) execute eagerly so the caller can branch on their
+     * results. **D1 does not provide snapshot isolation across async code**, so
+     * reads inside a transaction can see concurrent writes. For concurrency-safe
+     * read-modify-write (e.g. stock decrement), combine the transaction with a
+     * relative SQL update and a WHERE guard:
+     *
+     * ```ts
+     * await db.transaction(async (tx) => {
+     *   // The WHERE guard ensures the decrement only applies when stock is
+     *   // still >= qty at commit time. Two concurrent transactions cannot
+     *   // both oversell because D1's atomic batch re-evaluates the WHERE.
+     *   await tx.update(products)
+     *     .set({ stock: sql`stock - ${qty}` })
+     *     .where(and(eq(products.id, pid), gte(products.stock, qty)))
+     *     .run();
+     *   return tx.insert(orders).values({ productId: pid, qty }).returning().run();
+     * });
+     * ```
+     *
+     * Nested `db.transaction()` calls inside the callback are flattened into the
+     * parent's pending queue so everything still commits atomically.
+     *
+     * @typeParam T - The return type of the callback.
+     * @param callback - The transaction body. Receives a `tx` handle with
+     *   `query`/`insert`/`update`/`delete` methods (no `unsafe`, `batch`, or
+     *   `cache` — those are intentionally off-limits inside a transaction).
+     * @returns A {@link TransactionResult} containing the callback's return value
+     *   and transaction metadata (`meta.changes`, `meta.writeResults`), or rejects
+     *   with whatever the callback threw (after rolling back pending writes).
+     */
+    transaction: <T>(callback: (tx: Tx<TSchema>) => Promise<T>) => Promise<TransactionResult<T>>;
+    /** Cache control methods for manual invalidation. */
+    cache: {
+        /** Invalidate cached queries by tag names and/or table names. */
+        invalidate: (options: {
+            /** Tag names to invalidate (from {@link QueryCacheOptions} `tags`). */
+            tags?: string[];
+            /** Table names to invalidate (bumps their version counters). */
+            tables?: string[];
+        }) => Promise<void>;
+    };
+    /**
+     * Clears the per-instance `with` lookup cache so that the next query
+     * re-runs every grant lookup function.
+     *
+     * In production this is rarely needed because each request gets a fresh
+     * `Db` via `createDb()`. In tests that reuse a single `Db` across grant
+     * mutations (e.g. inserting a new friendship and then querying recipes),
+     * call this after the mutation to avoid stale lookup results.
+     *
+     * For finer-grained control, wrap each logical request in
+     * {@link runWithLookupCache} instead -- that scopes the cache via
+     * `AsyncLocalStorage` so it is automatically discarded at scope exit.
+     *
+     * @example
+     * ```ts
+     * const db = createDb({ ... });
+     * await db.query(recipes).findMany().run(); // populates lookup cache
+     * await db.insert(friendGrants).values({ ... }).run(); // adds new grant
+     * db.clearLookupCache(); // drop stale lookups
+     * await db.query(recipes).findMany().run(); // sees new grant
+     * ```
+     */
+    clearLookupCache: () => void;
+    /**
+     * The Drizzle schema this Db was created with. Exposed for the seed engine
+     * so `seed(db)` can introspect tables without a separate schema import.
+     * @internal
+     */
+    readonly _schema: Record<string, unknown>;
+};
+type QueryBuilder<TTable extends DrizzleTable = DrizzleTable, TSchema extends Record<string, unknown> = Record<string, never>> = {
+    findMany: <TConfig extends FindManyOptions = Record<string, never>, TRow = InferQueryResult<TSchema, TTable, TConfig>>(options?: TConfig) => Operation<WithCan<TRow>[]>;
+    findFirst: <TConfig extends FindFirstOptions = Record<string, never>, TRow = InferQueryResult<TSchema, TTable, TConfig>>(options?: TConfig) => Operation<WithCan<TRow> | undefined>;
+    paginate: <TRow = InferRow<TTable>>(params: CursorParams | OffsetParams, options?: PaginateOptions) => Operation<CursorPage<TRow>> | Operation<OffsetPage<TRow>>;
+};
+type InsertBuilder<TTable extends DrizzleTable = DrizzleTable> = {
+    values: (values: Record<string, unknown>) => InsertReturningBuilder<TTable>;
+};
+type InsertReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
+    returning: () => Operation<InferRow<TTable>>;
+};
+type UpdateBuilder<TTable extends DrizzleTable = DrizzleTable> = {
+    set: (values: Record<string, unknown>) => UpdateWhereBuilder<TTable>;
+};
+type UpdateWhereBuilder<TTable extends DrizzleTable = DrizzleTable> = {
+    where: (condition: unknown) => UpdateReturningBuilder<TTable>;
+};
+type UpdateReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
+    returning: () => Operation<InferRow<TTable>>;
+};
+type DeleteBuilder<TTable extends DrizzleTable = DrizzleTable> = {
+    where: (condition: unknown) => DeleteReturningBuilder<TTable>;
+};
+type DeleteReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
+    returning: () => Operation<InferRow<TTable>>;
+};
+
+export type { CursorParams as C, DbConfig as D, FindFirstOptions as F, InferQueryResult as I, Operation as O, PaginateOptions as P, QueryBuilder as Q, TransactionResult as T, UpdateBuilder as U, WithCan as W, Db as a, OffsetParams as b, CacheBackend as c, CacheConfig as d, CursorPage as e, DeleteBuilder as f, DeleteReturningBuilder as g, FindManyOptions as h, InferRow as i, InsertBuilder as j, InsertReturningBuilder as k, OffsetPage as l, PaginateParams as m, QueryCacheOptions as n, Tx as o, UpdateReturningBuilder as p, UpdateWhereBuilder as q };