@cfast/db 0.4.1 → 0.6.0

package/dist/index.js

@@ -1,9 +1,10 @@
 // src/create-db.ts
-import { drizzle as drizzle3 } from "drizzle-orm/d1";
+import { drizzle as drizzle4 } from "drizzle-orm/d1";
 
 // src/query-builder.ts
-import { count } from "drizzle-orm";
+import { count, sql, or as drizzleOr } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/d1";
+import { getGrantedActions } from "@cfast/permissions";
 
 // src/permissions.ts
 import {
@@ -220,6 +221,53 @@ function getTableKey(schema, table) {
 function getQueryTable(db, key) {
   return db.query[key];
 }
+var CAN_PREFIX = "_can_";
+async function buildCanExtras(config, grantedActions, queriedAction) {
+  const extras = {};
+  for (const ga of grantedActions) {
+    const alias = `${CAN_PREFIX}${ga.action}`;
+    if (ga.action === queriedAction) {
+      extras[alias] = sql`1`.as(alias);
+      continue;
+    }
+    if (ga.unrestricted) {
+      extras[alias] = sql`1`.as(alias);
+      continue;
+    }
+    const needsLookupDb = ga.grants.some((g) => g.with !== void 0);
+    const lookupDb = needsLookupDb ? config.getLookupDb() : void 0;
+    const lookupSets = await Promise.all(
+      ga.grants.map((g) => resolveGrantLookups(g, config.user, lookupDb, config.lookupCache))
+    );
+    const columns = config.table;
+    const clauses = ga.grants.map(
+      (g, i) => g.where ? g.where(columns, config.user, lookupSets[i]) : void 0
+    ).filter((c) => c !== void 0);
+    if (clauses.length === 0) {
+      extras[alias] = sql`1`.as(alias);
+      continue;
+    }
+    const combined = clauses.length === 1 ? clauses[0] : drizzleOr(...clauses);
+    extras[alias] = sql`CASE WHEN ${combined} THEN 1 ELSE 0 END`.as(alias);
+  }
+  return extras;
+}
+function attachCan(row, grantedActions) {
+  const can = {};
+  const grantedSet = new Set(grantedActions.map((ga) => ga.action));
+  const allActions = ["read", "create", "update", "delete"];
+  for (const action of allActions) {
+    const key = `${CAN_PREFIX}${action}`;
+    if (key in row) {
+      can[action] = row[key] === 1 || row[key] === true;
+      delete row[key];
+    } else if (!grantedSet.has(action)) {
+      can[action] = false;
+    }
+  }
+  row._can = can;
+  return row;
+}
 function buildQueryOperation(config, db, tableKey, method, options) {
   const permissions = makePermissions(config.unsafe, "read", config.table);
   return {
@@ -244,8 +292,32 @@ function buildQueryOperation(config, db, tableKey, method, options) {
         queryOptions.where = combinedWhere;
       }
       delete queryOptions.cache;
+      const grantedActions = !config.unsafe && config.user ? getGrantedActions(config.grants, config.table) : [];
+      if (grantedActions.length > 0) {
+        const canExtras = await buildCanExtras(config, grantedActions, "read");
+        const userExtras = queryOptions.extras;
+        queryOptions.extras = userExtras ? { ...userExtras, ...canExtras } : canExtras;
+      }
       const queryTable = getQueryTable(db, tableKey);
       const result = await queryTable[method](queryOptions);
+      if (grantedActions.length > 0) {
+        if (method === "findFirst" && result != null) {
+          attachCan(result, grantedActions);
+        } else if (method === "findMany" && Array.isArray(result)) {
+          for (const row of result) {
+            attachCan(row, grantedActions);
+          }
+        }
+      } else if (!config.unsafe && config.user) {
+        const emptyCan = { read: false, create: false, update: false, delete: false };
+        if (method === "findFirst" && result != null) {
+          result._can = { ...emptyCan };
+        } else if (method === "findMany" && Array.isArray(result)) {
+          for (const row of result) {
+            row._can = { ...emptyCan };
+          }
+        }
+      }
       return method === "findFirst" ? result ?? void 0 : result;
     }
   };
@@ -583,8 +655,8 @@ function createCacheManager(config) {
   const defaultTtl = config.ttl ?? "60s";
   const excludedTables = new Set(config.exclude ?? []);
   return {
-    generateKey(sql, role, tableVersion) {
-      return `cfast:${role}:v${tableVersion}:${simpleHash(sql)}`;
+    generateKey(sql2, role, tableVersion) {
+      return `cfast:${role}:v${tableVersion}:${simpleHash(sql2)}`;
     },
     getTableVersion(table) {
       return tableVersions.get(table) ?? 0;
@@ -675,6 +747,7 @@ function createCacheManager(config) {
 }
 
 // src/transaction.ts
+import { drizzle as drizzle3 } from "drizzle-orm/d1";
 var TransactionError = class extends Error {
   constructor(message) {
     super(message);
@@ -684,14 +757,10 @@ var TransactionError = class extends Error {
 function wrapWriteOperation(ctx, op) {
   const record = (toQueue) => {
     if (ctx.closed) {
-      throw new TransactionError(
-        "Cannot run an operation after the transaction has committed or aborted."
-      );
+      throw new TransactionError("Cannot run an operation after the transaction has committed or aborted.");
     }
     if (ctx.aborted) {
-      throw new TransactionError(
-        "Transaction has been aborted; no further operations may run."
-      );
+      throw new TransactionError("Transaction has been aborted; no further operations may run.");
     }
     ctx.pending.push({ op: toQueue });
   };
@@ -718,9 +787,7 @@ function wrapWriteOperation(ctx, op) {
 }
 function createTxHandle(db, ctx) {
   return {
-    query: (table) => {
-      return db.query(table);
-    },
+    query: (table) => db.query(table),
     insert: (table) => {
       const realBuilder = db.insert(table);
       return {
@@ -753,13 +820,11 @@ function createTxHandle(db, ctx) {
         }
       };
     },
-    transaction: (callback) => {
-      return runTransaction(db, callback, ctx);
-    }
+    transaction: (callback) => runTransaction(db, callback, ctx)
   };
 }
-async function flushWrites(db, pending) {
-  if (pending.length === 0) return;
+async function flushWritesDirect(config, isUnsafe, pending) {
+  if (pending.length === 0) return { changes: 0, writeResults: [] };
   const ops = pending.map((p) => p.op);
   for (const op of ops) {
     if (getBatchable(op) === void 0) {
@@ -768,24 +833,39 @@ async function flushWrites(db, pending) {
       );
     }
   }
-  await db.batch(ops).run({});
+  const allPermissions = deduplicateDescriptors(ops.flatMap((op) => op.permissions));
+  if (!isUnsafe) {
+    checkOperationPermissions(config.grants, allPermissions);
+  }
+  const batchables = ops.map((op) => getBatchable(op));
+  await Promise.all(batchables.map((b) => b.prepare?.() ?? Promise.resolve()));
+  const sharedDb = drizzle3(config.d1, { schema: config.schema });
+  const items = batchables.map((b) => b.build(sharedDb));
+  const batchResults = await sharedDb.batch(
+    items
+  );
+  const writeResults = batchResults.map((r) => {
+    if (r && typeof r === "object" && "meta" in r) {
+      return r;
+    }
+    return { results: [], success: true, meta: { changes: 0 } };
+  });
+  const changes = writeResults.reduce(
+    (sum, r) => sum + (r?.meta?.changes ?? 0),
+    0
+  );
+  return { changes, writeResults };
 }
-async function runTransaction(db, callback, parentCtx) {
-  if (parentCtx) {
+async function runTransaction(db, callback, parentCtxOrConfig, isUnsafe) {
+  if (parentCtxOrConfig && "pending" in parentCtxOrConfig) {
+    const parentCtx = parentCtxOrConfig;
     if (parentCtx.closed || parentCtx.aborted) {
-      throw new TransactionError(
-        "Cannot start a nested transaction: parent has already committed or aborted."
-      );
+      throw new TransactionError("Cannot start a nested transaction: parent has already committed or aborted.");
     }
-    const nestedTx = createTxHandle(db, parentCtx);
-    return callback(nestedTx);
+    return callback(createTxHandle(db, parentCtx));
   }
-  const ctx = {
-    pending: [],
-    closed: false,
-    aborted: false,
-    nested: false
-  };
+  const config = parentCtxOrConfig;
+  const ctx = { pending: [], closed: false, aborted: false, nested: false };
   const tx = createTxHandle(db, ctx);
   let result;
   try {
@@ -796,15 +876,21 @@ async function runTransaction(db, callback, parentCtx) {
     ctx.pending.length = 0;
     throw err;
   }
+  let flushResult;
   try {
-    await flushWrites(db, ctx.pending);
+    if (config) {
+      flushResult = await flushWritesDirect(config, isUnsafe ?? false, ctx.pending);
+    } else {
+      if (ctx.pending.length > 0) await db.batch(ctx.pending.map((p) => p.op)).run({});
+      flushResult = { changes: 0, writeResults: [] };
+    }
     ctx.closed = true;
   } catch (err) {
     ctx.aborted = true;
     ctx.closed = true;
     throw err;
   }
-  return result;
+  return { result, meta: { changes: flushResult.changes, writeResults: flushResult.writeResults } };
 }
 
 // src/create-db.ts
@@ -895,7 +981,7 @@ function buildDb(config, isUnsafe, lookupCache) {
           const batchables = operations.map((op) => getBatchable(op));
           const everyOpBatchable = batchables.every((b) => b !== void 0);
           if (everyOpBatchable) {
-            const sharedDb = drizzle3(config.d1, { schema: config.schema });
+            const sharedDb = drizzle4(config.d1, { schema: config.schema });
             await Promise.all(
               batchables.map((b) => b.prepare?.() ?? Promise.resolve())
             );
@@ -921,7 +1007,7 @@ function buildDb(config, isUnsafe, lookupCache) {
       };
     },
     transaction(callback) {
-      return runTransaction(db, callback);
+      return runTransaction(db, callback, { d1: config.d1, schema: config.schema, grants: config.grants }, isUnsafe);
     },
     cache: {
       async invalidate(options) {
@@ -938,7 +1024,8 @@ function buildDb(config, isUnsafe, lookupCache) {
     },
     clearLookupCache() {
       lookupCache.clear();
-    }
+    },
+    _schema: config.schema
   };
   return db;
 }
@@ -1054,7 +1141,7 @@ function createTrackingDb(real, perms) {
         insert: trackingDb.insert,
         update: trackingDb.update,
         delete: trackingDb.delete,
-        transaction: (cb) => trackingDb.transaction(cb)
+        transaction: (cb) => trackingDb.transaction(cb).then((txr) => txr.result)
       };
       try {
         await callback(trackingTx);
@@ -1063,7 +1150,8 @@ function createTrackingDb(real, perms) {
       return createSentinel();
     },
     cache: real.cache,
-    clearLookupCache: () => real.clearLookupCache()
+    clearLookupCache: () => real.clearLookupCache(),
+    _schema: real._schema
   };
   return trackingDb;
 }
@@ -1095,31 +1183,25 @@ function composeSequentialCallback(db, callback) {
   };
 }
 
-// src/seed.ts
-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({});
-        }
-      }
+// src/json.ts
+function toJSON(value) {
+  return convertDates(value);
+}
+function convertDates(value) {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    return value.map(convertDates);
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = convertDates(val);
     }
-  };
+    return result;
+  }
+  return value;
 }
 export {
   TransactionError,
@@ -1129,8 +1211,8 @@ export {
   createAppDb,
   createDb,
   createLookupCache,
-  defineSeed,
   parseCursorParams,
   parseOffsetParams,
-  runWithLookupCache
+  runWithLookupCache,
+  toJSON
 };

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