@cfast/db 0.5.0 → 0.6.0

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

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
 
-`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" }] },
@@ -423,14 +468,95 @@ const seed = defineSeed({
 });
 
 const db = createDb({ d1, schema, grants: [], user: null });
-await seed.run(db);
+await mySeed.run(db);
 ```
 
-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).
+### 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"])),
+```
+
+#### 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.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"