@cfast/db 0.5.0 → 0.7.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>>
 ```
 
@@ -102,6 +102,34 @@ const recipes = await db
   .run();
 ```
 
+#### 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
@@ -403,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
+
+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 { seed } from "@cfast/db/seed";
+import { createDb } from "@cfast/db";
+import * as schema from "~/db/schema";
+
+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({ 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.
+### defineSeed (static fixtures)
+
+For hand-authored fixture data (not generated), use `defineSeed`:
 
 ```typescript
-import { createDb, defineSeed } from "@cfast/db";
+import { defineSeed } from "@cfast/db/seed";
+import { createDb } from "@cfast/db";
 import * as schema from "~/db/schema";
 
-const seed = defineSeed({
+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" }] },
@@ -423,14 +468,116 @@ 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()` method
+
+Chain `.seed(fn)` on any column builder to attach a custom generator:
+
+```typescript
+import { table } from "@cfast/db/seed";
+import { text, integer, real } from "drizzle-orm/sqlite-core";
+
+const posts = table("posts", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull().seed(f => f.lorem.sentence()),
+  content: text("content").seed(f => f.lorem.paragraphs(3)),
+  authorId: text("author_id").references(() => users.id),
+}).seed({ count: 10 });
 ```
 
-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).
+Fields without `.seed()` 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()` method
+
+Chain `.seed({ count, per })` on a table created with `table()` to set
+the row count and optional per-parent relationship:
+
+```typescript
+import { table } from "@cfast/db/seed";
+
+const users = table("users", { ... }).seed({ count: 10 });
+const posts = table("posts", { ... }).seed({ count: 5, per: users });
+// -> 5 per user = 50 total. authorId auto-filled with parent user's id.
+```
+
+`table()` is a drop-in replacement for `sqliteTable()` from
+`drizzle-orm/sqlite-core` that adds the `.seed()` method. The returned
+table is a standard Drizzle table in every way.
+
+#### Deprecated wrapper functions
+
+The older `seedConfig()` and `tableSeed()` wrapper functions still work
+and write to the same internal registries. They are interchangeable with
+the `.seed()` methods but considered deprecated:
+
+```typescript
+// Deprecated -- prefer .seed() method API above
+import { seedConfig, tableSeed } from "@cfast/db/seed";
+const posts = tableSeed(sqliteTable("posts", {
+  title: seedConfig(text("title"), f => f.lorem.sentence()),
+}), { count: 5 });
+```
+
+#### 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: text("author_id").references(() => users.id)
+  .seed((faker, ctx) => ctx.parent?.id), // inherit from parent
+role: text("role")
+  .seed((f, ctx) => ctx.index === 0 ? "admin" : f.helpers.arrayElement(["member", "viewer"])),
+```
+
+#### 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/db",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Permission-aware Drizzle queries for Cloudflare D1",
   "keywords": [
     "cfast",
@@ -23,16 +23,26 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./seed": {
+      "import": "./dist/seed.js",
+      "types": "./dist/seed.d.ts"
     }
   },
   "files": [
     "dist",
     "llms.txt"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/seed.js",
+    "./src/seed.ts"
+  ],
   "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 +61,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"