@cfast/db 0.3.0 → 0.4.1

package/llms.txt

@@ -11,7 +11,7 @@ Use `@cfast/db` whenever you need to read or write a D1 database in a cfast app.
 - **Operations are lazy.** Every `db.query/insert/update/delete` call returns an `Operation<TResult>` with `.permissions` (inspectable immediately) and `.run(params)` (executes with permission checks). Nothing touches D1 until you call `.run()`.
 - **Permission checks are structural.** `.run()` always checks the user's grants before executing SQL. Row-level WHERE clauses from grants are injected automatically.
 - **Cross-table grants run prerequisite lookups.** When a grant declares a `with` map (see `@cfast/permissions`), `@cfast/db` resolves those lookups against an unsafe-mode handle **before** running the main query, caches the results for the lifetime of the per-request `Db`, and threads them into the `where` clause as its third argument. A single lookup runs at most once per request even across many queries.
-- **One Db per request.** `createDb()` captures the user at creation time. Never share a `Db` across requests. The per-request grant lookup cache lives on the `Db` instance, so creating a fresh one each request gives every request a fresh cache.
+- **One Db per request.** `createDb()` captures the user at creation time. Never share a `Db` across requests. The per-request grant lookup cache defaults to a cache owned by the `Db` instance, so creating a fresh one each request gives every request a fresh cache. If you must reuse a single `Db` across logical requests (typically tests or long-lived workers) wrap each request in `runWithLookupCache()` to get a fresh ALS-scoped cache per logical request.
 - **`db.unsafe()` is the only escape hatch.** Returns a `Db` that skips all permission checks. Greppable via `git grep '.unsafe()'`. The unsafe sibling shares the per-request lookup cache so lookups dispatched through it (the `LookupDb` passed to grant `with` functions) never duplicate work.
 
 ## API Reference
@@ -47,14 +47,45 @@ type Operation<TResult> = {
 ### Reads
 
 ```typescript
-db.query(table).findMany(options?): Operation<unknown[]>
-db.query(table).findFirst(options?): Operation<unknown | undefined>
-db.query(table).paginate(params, options?): Operation<CursorPage | OffsetPage>
+db.query(table).findMany(options?): Operation<Row[]>
+db.query(table).findFirst(options?): Operation<Row | undefined>
+db.query(table).paginate(params, options?): Operation<CursorPage<Row> | OffsetPage<Row>>
 ```
 
+`Row` is inferred from the table via `InferRow<typeof table>` -- callers get
+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)
+
+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:
+
+```typescript
+type RecipeWithIngredients = Recipe & { ingredients: Ingredient[] };
+
+const recipes = await db
+  .query(recipesTable)
+  .findMany<RecipeWithIngredients>({ with: { ingredients: true } })
+  .run();
+// recipes is RecipeWithIngredients[], no cast needed.
+
+const recipe = await db
+  .query(recipesTable)
+  .findFirst<RecipeWithIngredients>({
+    where: eq(recipesTable.id, id),
+    with: { ingredients: true },
+  })
+  .run();
+// recipe is RecipeWithIngredients | undefined.
+```
+
 ### Writes
 
 ```typescript
@@ -85,6 +116,20 @@ await db.delete(cards).where(eq(cards.id, id)).run();
 
 ### compose(operations, executor): Operation<TResult>
 
+> ⚠️ **Footgun warning (#182):** the `executor` callback receives one `run`
+> function per entry in `operations`, **in array order**. TypeScript cannot
+> enforce that the parameter names line up, so a callback like
+> `(runUpdate, runVersion) => ...` that gets reordered or shadowed by an
+> outer-scope variable will silently invoke the wrong sub-operation. Prefer
+> `composeSequentialCallback(db, async tx => ...)` for any workflow with data
+> dependencies — it binds by name via the normal db builders. Use `compose()`
+> only when you genuinely need to interleave non-db logic between sub-ops.
+>
+> As a runtime safety net, `compose()` throws at construction time when the
+> executor's parameter count doesn't match the operations array length (so
+> `compose([a, b], (runA) => ...)` fails loudly instead of silently dropping
+> `runB`). Use `(...runs) => ...` or `() => ...` to opt out of the check.
+
 ```typescript
 import { compose } from "@cfast/db";
 
@@ -154,13 +199,12 @@ every operation was produced by `db.insert/update/delete`: the batch is sent to
 D1's native `batch()` API, which executes the statements as a single transaction
 and rolls everything back if any statement fails.
 
-Use this whenever you need transactional safety -- for example, decrementing
-stock across multiple products during checkout, or inserting an order plus its
-line items together:
+Use `db.batch` for a **static, pre-known list** of writes — the shape of the
+list doesn't depend on anything read from the database:
 
 ```typescript
-// Atomic checkout: stock decrements + order creation either all succeed or
-// all roll back. Permissions for every sub-op are checked upfront.
+// Static batch: the list of ops is known upfront. Permissions for every
+// sub-op are checked before the first statement runs.
 await db.batch([
   db.update(products).set({ stock: sql`stock - 1` }).where(eq(products.id, id1)),
   db.update(products).set({ stock: sql`stock - 1` }).where(eq(products.id, id2)),
@@ -168,8 +212,10 @@ await db.batch([
 ]).run();
 ```
 
-Permission checks happen **before** any SQL is issued. If the user lacks any
-required grant, the batch throws and zero statements run.
+**Reads happen before writes begin**, so `db.batch` is NOT safe for
+read-modify-write: a read issued inside a batch cannot influence a later
+statement in the same batch. For "read row, decide, write" logic, use
+`db.transaction(async tx => ...)` below.
 
 Operations produced by `compose()`/`composeSequential()` executors don't carry
 the batchable hook; mixing them into `db.batch([...])` causes a fallback to
@@ -177,6 +223,131 @@ 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>
+
+Runs a callback inside a transaction. Writes (`tx.insert`, `tx.update`,
+`tx.delete`) are **recorded** as the callback runs and flushed together as a
+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.
+
+Use `db.transaction` whenever the set of writes depends on logic inside the
+callback (read-modify-write, conditional inserts, state machines):
+
+```typescript
+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 product = await tx.query(products).findFirst({
+    where: eq(products.id, pid),
+  }).run();
+  if (!product || product.stock < qty) {
+    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.
+  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 };
+});
+```
+
+**`tx` is a `Pick<Db, "query" | "insert" | "update" | "delete">`** plus a
+`transaction` method for nesting. It intentionally does NOT expose `unsafe`,
+`batch`, or `cache`:
+
+- `unsafe()` would bypass permission checks mid-tx. Use
+  `db.unsafe().transaction(...)` on the outer handle if you need system-level
+  writes in a transaction.
+- `batch()` inside a transaction is redundant — everything in the tx already
+  commits as one batch.
+- `cache` invalidation is driven by the commit at the end of the transaction,
+  not per-sub-op.
+
+**Permissions:** every recorded write has its permissions checked **upfront**
+at flush time via the underlying `db.batch()`. If any op lacks a grant, the
+entire transaction fails before any SQL is issued.
+
+**Nested transactions** are flattened into the parent's pending queue, so
+`tx.transaction(async inner => ...)` still commits in the same single batch
+as the outer. Any error thrown in the inner callback aborts the entire
+outer transaction. This means helpers that always use `tx.transaction(...)`
+to "own" a transaction scope compose naturally — they run as-is when called
+inside an outer tx and start their own when called standalone.
+
+#### Returning inside a transaction
+
+`tx.insert(...).returning().run()` inside a transaction callback resolves to
+`undefined`. The row cannot be surfaced to the caller because the batch is
+only flushed **after** the callback returns — awaiting a returning promise
+inside the callback would deadlock the flush. Work around this in one of
+three ways:
+
+1. **Generate ids client-side** (`crypto.randomUUID()`) and pass them into the
+   insert. The callback already knows the id without needing `.returning()`.
+2. **Query the row after the transaction commits** with a regular
+   `db.query(...)` outside the `db.transaction(...)` call.
+3. **Use `db.batch([...])` instead** if the read-after-write you want is
+   actually just "grab the inserted row for logging" — batch results include
+   every op's output in the same array.
+
+#### Reads inside a transaction
+
+Reads (`tx.query(...).findFirst().run()` etc.) execute eagerly against the
+underlying db at the moment they're called. They see whatever is committed
+right now and are **not** isolated from concurrent transactions. Do not rely
+on a read's value alone to gate a write — combine the read with a relative
+SQL update and a WHERE guard so the guard is re-evaluated at commit time.
+
+#### Pattern: cheap single-row oversell guard without a transaction
+
+For a single-row counter-decrement you don't even need a transaction. Use
+relative SQL with a WHERE guard and inspect the affected-rows count — this
+is ~one round trip instead of two and needs no pending-queue bookkeeping:
+
+```typescript
+const result = await db.unsafe().d1.prepare(
+  "UPDATE products SET stock = stock - ? WHERE id = ? AND stock >= ?",
+).bind(qty, pid, qty).run();
+
+if (result.meta.changes === 0) {
+  throw new Error("out of stock");
+}
+```
+
+Use `db.transaction` when you need **multiple** writes to commit atomically,
+or when you need read-modify-write across more than one row.
+
+### batch vs. transaction at a glance
+
+| Use case | `db.batch([...])` | `db.transaction(async tx => ...)` |
+|---|---|---|
+| Static list of writes | Yes (preferred) | Works but heavier |
+| Shape of writes depends on logic | No — list must be static | Yes |
+| Read a row, decide, then write | **No** — not concurrency-safe | Yes (combine with WHERE guard) |
+| Conditional inserts / state machines | No | Yes |
+| Returning the inserted row | Yes (batch result array) | Resolves to `undefined` inside the callback — generate ids client-side |
+| Atomic (all-or-nothing) | Yes | Yes |
+| Concurrency safety | Guard writes with WHERE clauses | Guard writes with WHERE clauses (reads are NOT isolated) |
+
 ### db.unsafe(): Db
 
 Returns a new Db that skips permission checks. Use for cron jobs, migrations, system tasks.
@@ -214,6 +385,35 @@ 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
+
+`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.
+
+```typescript
+import { createDb, defineSeed } 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" }] },
+    { table: schema.posts, rows: [{ id: "p-1", title: "Hello", authorId: "u-1" }] },
+  ],
+});
+
+const db = createDb({ d1, schema, grants: [], user: null });
+await seed.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).
+
 ## Usage Examples
 
 ### Standard loader pattern
@@ -299,6 +499,60 @@ export async function loader({ context, request }) {
 }
 ```
 
+### Reusing a Db across logical requests (tests, long-lived workers)
+
+`createDb()` always works and you should keep the "one Db per request" default. If
+you need to reuse a single `Db` across multiple logical requests (commonly in
+tests that insert new grants mid-run and expect subsequent queries to see them)
+wrap each logical request in `runWithLookupCache()`:
+
+```typescript
+import { createDb, runWithLookupCache } from "@cfast/db";
+
+// Shared Db reused across the whole test file.
+const db = createDb({ d1, schema, grants, user, cache: false });
+
+test("new grants become visible to subsequent queries", async () => {
+  await runWithLookupCache(async () => {
+    await db.insert(friendGrants).values({ grantee: "u1", target: "u2" }).run();
+    // The next query starts in the same scope, so it sees a *fresh* cache
+    // and re-runs the `with` lookup with the updated grant row.
+  });
+
+  await runWithLookupCache(async () => {
+    const visible = await db.query(recipes).findMany().run();
+    expect(visible).toContainEqual(expect.objectContaining({ authorId: "u2" }));
+  });
+});
+```
+
+`runWithLookupCache(fn, cache?)` establishes an `AsyncLocalStorage` scope;
+every `@cfast/db` operation inside `fn` (and any promises it starts) will
+prefer the scoped cache over the `Db`-owned fallback. Pass an explicit
+`LookupCache` instance as the second argument if you want to share a cache
+across multiple sibling `runWithLookupCache` calls.
+
+### db.clearLookupCache(): void
+
+Clears the per-instance cross-table `with` lookup cache on the `Db` instance. This is the imperative counterpart to `runWithLookupCache()` -- instead of scoping a fresh cache via ALS, it resets the instance-owned cache in place.
+
+The primary use case is tests that reuse a single `Db` across grant inserts. After modifying grants, call `db.clearLookupCache()` so subsequent queries re-run `with` lookups against the updated data:
+
+```typescript
+const db = createDb({ d1, schema, grants, user, cache: false });
+
+// Insert a new friend-grant.
+await db.unsafe().insert(friendGrants).values({ grantee: "u1", target: "u2" }).run();
+
+// Without this, the next query would use the stale cached lookup.
+db.clearLookupCache();
+
+const visible = await db.query(recipes).findMany().run();
+expect(visible).toContainEqual(expect.objectContaining({ authorId: "u2" }));
+```
+
+Prefer `runWithLookupCache()` in production code (ALS-scoped, automatic cleanup). Use `clearLookupCache()` when you need a quick manual reset in tests or long-lived workers that don't use the ALS pattern.
+
 ## Integration
 
 - **@cfast/permissions** -- `grants` come from `resolveGrants(permissions, user.roles)`. Permission WHERE clauses are defined via `grant()` in your permissions config.
@@ -325,6 +579,58 @@ export const folders = sqliteTable("folders", {
 
 Use `AnyPgColumn` / `AnyMySqlColumn` for other dialects. The same pattern applies to any self-reference (comment threads, org charts, category trees).
 
+## Testing
+
+### `node:sqlite` with vitest 4 + Node 22+
+
+Vitest 4 auto-externalises modules from Node's `builtinModules` list, but
+`node:sqlite` is still flagged as experimental and is **not** included in that
+list. The first time a test imports it (directly, or transitively via a local
+in-memory D1 stand-in), Vite tries to bundle it and crashes with:
+
+```
+Cannot bundle Node.js built-in 'node:sqlite'
+```
+
+Explicitly externalise the module in your `vitest.config.ts`:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    // Prevent vitest from trying to bundle experimental Node builtins.
+    server: {
+      deps: {
+        external: [/^node:sqlite$/],
+      },
+    },
+  },
+});
+```
+
+If you need more than one experimental builtin (e.g. `node:test` helpers),
+add each as a separate regex in the `external` array.
+
+### Long cold-import times
+
+When a test suite uses `@cfast/admin`, vitest's first import of
+`~/admin.server` can take several seconds even with the server-only entry
+(`@cfast/admin/server`), because drizzle-orm's SQLite core is large. If the
+default 5s test timeout trips during initial discovery, bump it explicitly
+for admin-using suites:
+
+```ts
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    testTimeout: 30000,
+  },
+});
+```
+
 ## 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.3.0",
+  "version": "0.4.1",
   "description": "Permission-aware Drizzle queries for Cloudflare D1",
   "keywords": [
     "cfast",
@@ -34,12 +34,13 @@
     "access": "public"
   },
   "peerDependencies": {
+    "@cfast/permissions": ">=0.3.0 <0.6.0",
     "drizzle-orm": ">=0.35"
   },
-  "dependencies": {
-    "@cfast/permissions": "0.3.0"
-  },
   "peerDependenciesMeta": {
+    "@cfast/permissions": {
+      "optional": false
+    },
     "@cloudflare/workers-types": {
       "optional": true
     }
@@ -49,7 +50,8 @@
     "drizzle-orm": "^0.45.1",
     "tsup": "^8",
     "typescript": "^5.7",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "@cfast/permissions": "0.5.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",