@cfast/db 0.4.1 → 0.6.0

package/llms.txt

@@ -47,8 +47,8 @@ type Operation<TResult> = {
 ### Reads
 
 ```typescript
-db.query(table).findMany(options?): Operation<Row[]>
-db.query(table).findFirst(options?): Operation<Row | undefined>
+db.query(table).findMany(options?): Operation<WithCan<Row>[]>
+db.query(table).findFirst(options?): Operation<WithCan<Row> | undefined>
 db.query(table).paginate(params, options?): Operation<CursorPage<Row> | OffsetPage<Row>>
 ```
 
@@ -58,34 +58,78 @@ IntelliSense on `(row) => row.title` without any cast.
 FindManyOptions: `{ columns?, where?, orderBy?, limit?, offset?, with?, cache? }`
 FindFirstOptions: same without `limit`/`offset`.
 
-#### Relations escape hatch (#158)
+#### Auto-inferred `.with()` relations (#240)
 
 When you pass `with: { relation: true }`, Drizzle's relational query builder
-embeds the joined rows into the result. `@cfast/db` cannot statically infer
-that shape from the `Record<string, unknown>` schema we accept on `createDb`,
-so the default row type does not include the relation. Override the row type
-via the `findMany`/`findFirst`/`paginate` generic to claim the shape you know
-the query will produce, instead of `as any`-casting the result downstream:
+embeds the joined rows into the result. As of `@cfast/db@0.5`, the result
+type is **automatically inferred** from the schema -- no type cast needed.
+`createDb` captures the full schema type via a generic, and `findMany`/
+`findFirst` thread the `with` config through Drizzle's `BuildQueryResult`
+to compute the exact result shape including nested relations.
 
 ```typescript
-type RecipeWithIngredients = Recipe & { ingredients: Ingredient[] };
+import { createDb } from "@cfast/db";
+import * as schema from "./schema";   // includes relations()
+
+const db = createDb({ d1, schema, grants, user });
 
+// Auto-inferred -- no cast, no manual generic
 const recipes = await db
-  .query(recipesTable)
-  .findMany<RecipeWithIngredients>({ with: { ingredients: true } })
+  .query(schema.recipesTable)
+  .findMany({ with: { ingredients: true } })
+  .run();
+// recipes is { id: string; title: string; ingredients: Ingredient[] }[]
+
+// Nested relations work too
+const plan = await db
+  .query(schema.mealPlans)
+  .findFirst({
+    with: { entries: { with: { recipe: { with: { ingredients: true } } } } },
+  })
   .run();
-// recipes is RecipeWithIngredients[], no cast needed.
+// plan.entries[0].recipe.ingredients is fully typed
+```
+
+**Manual override:** pass `<TConfig, TRow>` to override when needed:
 
-const recipe = await db
+```typescript
+type Custom = Recipe & { ingredients: Ingredient[] };
+const recipes = await db
   .query(recipesTable)
-  .findFirst<RecipeWithIngredients>({
-    where: eq(recipesTable.id, id),
+  .findMany<{ with: { ingredients: true } }, Custom>({
     with: { ingredients: true },
   })
   .run();
-// recipe is RecipeWithIngredients | undefined.
 ```
 
+#### Row-level `_can` annotations (#270)
+
+Every `findMany` and `findFirst` result includes a `_can` object with per-action
+booleans, evaluated from the user's grants at query time. No opt-in required --
+permissions are first-class on every row.
+
+```typescript
+const comments = await db.query(commentsTable).findMany().run();
+// comments[0]._can -> { read: true, create: true, update: true, delete: false }
+
+// Type: WithCan<Comment>[] -- each row has _can: Record<string, boolean>
+type WithCan<T> = T & { _can: Record<string, boolean> };
+```
+
+How `_can` is computed for each CRUD action:
+- **Unrestricted grant** (no `where` clause): `_can.action = true` for every row (literal `1` in SQL, no CASE needed).
+- **Restricted grant** (has `where` clause): `_can.action` varies per row via a SQL `CASE WHEN <condition> THEN 1 ELSE 0 END` computed column.
+- **No grant**: `_can.action = false` for every row.
+- **`manage` grant**: expands to all four CRUD actions (`read`, `create`, `update`, `delete`).
+
+The `read` action is always `true` on returned rows because the permission WHERE
+clause already filters out rows the user cannot read.
+
+`_can` is **not** added in `unsafe()` mode or when `user` is `null`.
+
+Performance: adds N computed columns per query (where N = distinct granted CRUD
+actions, typically 3-5). Unrestricted grants are free (literal `1`).
+
 ### Writes
 
 ```typescript
@@ -223,7 +267,7 @@ sequential execution (and loses the atomicity guarantee). For pure compose
 workflows that need atomicity, build the underlying ops with `db.insert/update/
 delete` directly and pass them straight to `db.batch([...])`.
 
-### db.transaction(async tx => ...): Promise<T>
+### db.transaction(async tx => ...): Promise<TransactionResult<T>>
 
 Runs a callback inside a transaction. Writes (`tx.insert`, `tx.update`,
 `tx.delete`) are **recorded** as the callback runs and flushed together as a
@@ -231,6 +275,14 @@ single atomic `db.batch([...])` when the callback returns successfully. If the
 callback throws, the pending writes are discarded and the error is re-thrown —
 nothing reaches D1.
 
+Returns a `TransactionResult<T>` with:
+- `result: T` — the callback's return value
+- `meta.changes: number` — total rows affected across all writes
+- `meta.writeResults: D1Result[]` — per-statement D1 results
+
+Use `meta.changes` to detect whether a WHERE-guarded UPDATE actually matched
+any rows (the "out of stock" signal) without falling back to raw SQL.
+
 Use `db.transaction` whenever the set of writes depends on logic inside the
 callback (read-modify-write, conditional inserts, state machines):
 
@@ -238,11 +290,7 @@ callback (read-modify-write, conditional inserts, state machines):
 import { and, eq, gte, sql } from "drizzle-orm";
 
 // Oversell-safe checkout: atomic + guarded against concurrent decrements.
-const order = await db.transaction(async (tx) => {
-  // Reads execute eagerly against the underlying db. They see whatever is
-  // committed right now — D1 does NOT provide snapshot isolation across
-  // async code, so another request can modify the row between read and
-  // write. The WHERE guard on the update is what keeps us concurrency-safe.
+const { result: order, meta } = await db.transaction(async (tx) => {
   const product = await tx.query(products).findFirst({
     where: eq(products.id, pid),
   }).run();
@@ -250,24 +298,22 @@ const order = await db.transaction(async (tx) => {
     throw new Error("out of stock"); // rolls back, nothing is written
   }
 
-  // Guarded decrement: relative SQL + WHERE stock >= qty. The guard is
-  // re-evaluated by D1 at commit time, so two concurrent transactions
-  // cannot BOTH decrement past zero. Either one succeeds and the other
-  // is a no-op (0 rows matched), or the application-level check above
-  // rejects the second one first.
+  // Guarded decrement: relative SQL + WHERE stock >= qty.
   await tx.update(products)
     .set({ stock: sql`stock - ${qty}` })
     .where(and(eq(products.id, pid), gte(products.stock, qty)))
     .run();
 
-  // Generate the order id client-side so we don't need `.returning()`
-  // inside the transaction (see "Returning inside a transaction" below).
   const orderId = crypto.randomUUID();
   await tx.insert(orders).values({ id: orderId, productId: pid, qty }).run();
 
-  // Whatever the callback returns becomes the transaction's return value.
   return { orderId, productId: pid, qty };
 });
+
+// Check if the guarded decrement actually matched any rows.
+if (meta.changes === 0) {
+  throw new Error("out of stock — concurrent decrement won");
+}
 ```
 
 **`tx` is a `Pick<Db, "query" | "insert" | "update" | "delete">`** plus a
@@ -385,19 +431,36 @@ cache: {
 Per-query: `db.query(t).findMany({ cache: false })` or `{ cache: { ttl: "5m", tags: ["posts"] } }`.
 Manual invalidation: `await db.cache.invalidate({ tags: ["posts"], tables: ["posts"] })`.
 
-### defineSeed
+### One-liner seed
 
-`defineSeed({ entries })` is the canonical way to seed a local D1 database.
-Accepts an ordered list of `{ table, rows }` entries — put parent tables
-before child tables to respect FK ordering. `seed.run(db)` hops through
-`db.unsafe()` internally so seeds never need their own grants. Empty `rows`
-arrays are skipped, so placeholder entries are safe.
+All seed functionality lives under the `@cfast/db/seed` entrypoint, which
+bundles `@faker-js/faker` so you never install or import it yourself. The
+simplest API is a one-liner:
 
 ```typescript
-import { createDb, defineSeed } from "@cfast/db";
+import { seed } from "@cfast/db/seed";
+import { createDb } from "@cfast/db";
 import * as schema from "~/db/schema";
 
-const seed = defineSeed({
+const db = createDb({ d1, schema, grants: [], user: null });
+await seed(db);
+```
+
+`seed(db)` introspects the schema from the Db instance, topologically sorts
+tables, generates realistic data via faker, and inserts it through
+`db.unsafe()`. Pass `{ transcript: "./seed.sql" }` as the second argument
+to also write the INSERT statements to a file.
+
+### defineSeed (static fixtures)
+
+For hand-authored fixture data (not generated), use `defineSeed`:
+
+```typescript
+import { defineSeed } from "@cfast/db/seed";
+import { createDb } from "@cfast/db";
+import * as schema from "~/db/schema";
+
+const mySeed = defineSeed({
   entries: [
     { table: schema.users, rows: [{ id: "u-1", email: "ada@example.com", name: "Ada" }] },
     { table: schema.posts, rows: [{ id: "p-1", title: "Hello", authorId: "u-1" }] },
@@ -405,14 +468,95 @@ const seed = defineSeed({
 });
 
 const db = createDb({ d1, schema, grants: [], user: null });
-await seed.run(db);
+await mySeed.run(db);
+```
+
+### Schema-driven seed generation (createSeedEngine)
+
+`createSeedEngine(schema)` introspects Drizzle schema metadata to
+auto-generate realistic test data using the bundled faker. Handles FK
+resolution, topological ordering, `per` relational generation,
+many-to-many deduplication, and auth table detection.
+
+#### Column-level seed overrides
+
+`seedConfig(column, fn)` attaches a custom generator to a column:
+
+```typescript
+import { seedConfig, tableSeed } from "@cfast/db/seed";
+
+const posts = sqliteTable("posts", {
+  id: text("id").primaryKey(),
+  title: seedConfig(text("title").notNull(), f => f.lorem.sentence()),
+  content: seedConfig(text("content"), f => f.lorem.paragraphs(3)),
+  authorId: text("author_id").references(() => users.id),
+});
+```
+
+Fields without `seedConfig()` are auto-inferred from column type:
+- `text` -> `faker.lorem.words()`
+- `integer`/`real` -> `faker.number.int()`/`faker.number.float()`
+- `timestamp` -> `faker.date.recent()`
+- `boolean` -> `faker.datatype.boolean()`
+- FK (`.references()`) -> random existing row from referenced table
+- Primary key -> auto-generated UUID
+- Nullable -> occasionally `null` (~10%)
+- Columns with `$defaultFn` or static defaults are skipped
+
+#### Table-level seed config
+
+`tableSeed(table, { count, per })` sets the row count and optional
+per-parent relationship:
+
+```typescript
+const users = tableSeed(sqliteTable("users", { ... }), { count: 10 });
+const posts = tableSeed(sqliteTable("posts", { ... }), { count: 5, per: users });
+// -> 5 per user = 50 total. authorId auto-filled with parent user's id.
+```
+
+#### Seed context (ctx)
+
+Column-level seed functions receive `(faker, ctx)` where `ctx` provides:
+
+- `ctx.parent` -- the parent row (from `per`), `undefined` for root tables
+- `ctx.ref(table)` -- pick a random existing row from any table
+- `ctx.index` -- zero-based position within current batch
+- `ctx.all(table)` -- all generated rows for a table
+
+```typescript
+authorId: seedConfig(text("author_id").references(() => users.id),
+  (faker, ctx) => ctx.parent?.id), // inherit from parent
+role: seedConfig(text("role"),
+  (f, ctx) => ctx.index === 0 ? "admin" : f.helpers.arrayElement(["member", "viewer"])),
 ```
 
-Multi-row entries are flushed via `db.batch([...])` (atomic per table);
-single-row entries skip the batch path so Drizzle's non-empty tuple
-invariant holds. Use this from `scripts/seed.ts` and run it via
-`pnpm db:seed:local` (the scaffolded `create-cfast` package ships this
-script and command out of the box).
+#### Runtime API
+
+```typescript
+import { createSeedEngine, createSingleTableSeed } from "@cfast/db/seed";
+
+// Seed all tables from schema config
+const engine = createSeedEngine(schema);
+const generated = await engine.run(db);
+
+// Also write SQL transcript
+await engine.run(db, { transcript: "./seed.sql" });
+
+// Single-table override
+const singleTable = createSingleTableSeed(schema, posts, 5);
+await singleTable.run(db);
+```
+
+#### Many-to-many deduplication
+
+Tables with 2+ FK columns are auto-detected as join tables.
+Duplicate composite key combinations are silently skipped.
+
+#### Auth integration
+
+Tables named "users" get special handling: the first 5 rows use
+`admin@example.com`, `user@example.com`, etc., and names use
+`faker.person.fullName()`.
 
 ## Usage Examples
 
@@ -631,6 +775,30 @@ export default defineConfig({
 });
 ```
 
+### toJSON(value): DateToString<T>
+
+Recursively converts `Date` fields to ISO 8601 strings for JSON serialization.
+React Router loaders must return JSON-serializable data; `toJSON()` makes the
+Date-to-string conversion explicit so every loader doesn't need manual
+`.toISOString()` calls.
+
+```typescript
+import { toJSON } from "@cfast/db";
+
+export async function loader({ context }) {
+  const db = createDb({ ... });
+  const posts = await db.query(postsTable).findMany().run();
+  // Date fields (createdAt, updatedAt, etc.) become ISO strings automatically.
+  return { posts: toJSON(posts) };
+}
+```
+
+The return type `DateToString<T>` maps every `Date` property to `string` at the
+type level, so the client sees accurate types without manual casting.
+
+Works on plain objects, arrays, nested structures, and single Date values.
+Non-Date primitives pass through unchanged.
+
 ## Common Mistakes
 
 - **Forgetting `.run()`** -- Operations are lazy. `db.query(t).findMany()` returns an Operation, not results. You must call `.run()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/db",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Permission-aware Drizzle queries for Cloudflare D1",
   "keywords": [
     "cfast",
@@ -23,6 +23,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./seed": {
+      "import": "./dist/seed.js",
+      "types": "./dist/seed.d.ts"
     }
   },
   "files": [
@@ -33,6 +37,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@faker-js/faker": "^9.0.0"
+  },
   "peerDependencies": {
     "@cfast/permissions": ">=0.3.0 <0.6.0",
     "drizzle-orm": ">=0.35"
@@ -51,11 +58,11 @@
     "tsup": "^8",
     "typescript": "^5.7",
     "vitest": "^4.1.0",
-    "@cfast/permissions": "0.5.1"
+    "@cfast/permissions": "0.6.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "build": "tsup src/index.ts src/seed.ts --format esm --dts",
+    "dev": "tsup src/index.ts src/seed.ts --format esm --dts --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "test": "vitest run"