@cfast/db 0.3.0 → 0.4.0

package/dist/index.js

@@ -63,6 +63,7 @@ function checkOperationPermissions(grants, descriptors) {
 }
 
 // src/utils.ts
+import { AsyncLocalStorage } from "async_hooks";
 import { and, or } from "drizzle-orm";
 import { getTableName as getTableName2 } from "@cfast/permissions";
 function deduplicateDescriptors(descriptors) {
@@ -77,12 +78,20 @@ function deduplicateDescriptors(descriptors) {
   }
   return result;
 }
+var lookupCacheStorage = new AsyncLocalStorage();
 function createLookupCache() {
   return /* @__PURE__ */ new Map();
 }
+function runWithLookupCache(fn, cache = createLookupCache()) {
+  return lookupCacheStorage.run(cache, fn);
+}
+function getActiveLookupCache(fallback) {
+  return lookupCacheStorage.getStore() ?? fallback;
+}
 async function resolveGrantLookups(grant, user, lookupDb, cache) {
   if (!grant.with) return {};
-  const cached = cache.get(grant);
+  const activeCache = getActiveLookupCache(cache);
+  const cached = activeCache.get(grant);
   if (cached) return cached;
   const entries = Object.entries(grant.with);
   const promise = (async () => {
@@ -94,7 +103,7 @@ async function resolveGrantLookups(grant, user, lookupDb, cache) {
     );
     return resolved;
   })();
-  cache.set(grant, promise);
+  activeCache.set(grant, promise);
   return promise;
 }
 async function buildPermissionFilter(grants, action, table, user, unsafe, getLookupDb, cache) {
@@ -665,6 +674,139 @@ function createCacheManager(config) {
   };
 }
 
+// src/transaction.ts
+var TransactionError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TransactionError";
+  }
+};
+function wrapWriteOperation(ctx, op) {
+  const record = (toQueue) => {
+    if (ctx.closed) {
+      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."
+      );
+    }
+    ctx.pending.push({ op: toQueue });
+  };
+  const proxied = {
+    permissions: op.permissions,
+    async run() {
+      record(op);
+      return void 0;
+    }
+  };
+  if (typeof op.returning === "function") {
+    proxied.returning = () => {
+      const returningOp = op.returning();
+      return {
+        permissions: returningOp.permissions,
+        async run() {
+          record(returningOp);
+          return void 0;
+        }
+      };
+    };
+  }
+  return proxied;
+}
+function createTxHandle(db, ctx) {
+  return {
+    query: (table) => {
+      return db.query(table);
+    },
+    insert: (table) => {
+      const realBuilder = db.insert(table);
+      return {
+        values: (values) => {
+          const realOp = realBuilder.values(values);
+          return wrapWriteOperation(ctx, realOp);
+        }
+      };
+    },
+    update: (table) => {
+      const realBuilder = db.update(table);
+      return {
+        set: (values) => {
+          const realSet = realBuilder.set(values);
+          return {
+            where: (condition) => {
+              const realOp = realSet.where(condition);
+              return wrapWriteOperation(ctx, realOp);
+            }
+          };
+        }
+      };
+    },
+    delete: (table) => {
+      const realBuilder = db.delete(table);
+      return {
+        where: (condition) => {
+          const realOp = realBuilder.where(condition);
+          return wrapWriteOperation(ctx, realOp);
+        }
+      };
+    },
+    transaction: (callback) => {
+      return runTransaction(db, callback, ctx);
+    }
+  };
+}
+async function flushWrites(db, pending) {
+  if (pending.length === 0) return;
+  const ops = pending.map((p) => p.op);
+  for (const op of ops) {
+    if (getBatchable(op) === void 0) {
+      throw new TransactionError(
+        "Internal error: a pending transaction operation was not batchable. Transactions only accept operations produced by tx.insert/update/delete."
+      );
+    }
+  }
+  await db.batch(ops).run({});
+}
+async function runTransaction(db, callback, parentCtx) {
+  if (parentCtx) {
+    if (parentCtx.closed || parentCtx.aborted) {
+      throw new TransactionError(
+        "Cannot start a nested transaction: parent has already committed or aborted."
+      );
+    }
+    const nestedTx = createTxHandle(db, parentCtx);
+    return callback(nestedTx);
+  }
+  const ctx = {
+    pending: [],
+    closed: false,
+    aborted: false,
+    nested: false
+  };
+  const tx = createTxHandle(db, ctx);
+  let result;
+  try {
+    result = await callback(tx);
+  } catch (err) {
+    ctx.aborted = true;
+    ctx.closed = true;
+    ctx.pending.length = 0;
+    throw err;
+  }
+  try {
+    await flushWrites(db, ctx.pending);
+    ctx.closed = true;
+  } catch (err) {
+    ctx.aborted = true;
+    ctx.closed = true;
+    throw err;
+  }
+  return result;
+}
+
 // src/create-db.ts
 function createDb(config) {
   const lookupCache = createLookupCache();
@@ -744,11 +886,14 @@ function buildDb(config, isUnsafe, lookupCache) {
         permissions: allPermissions,
         async run(params) {
           const p = params ?? {};
+          if (operations.length === 0) {
+            return [];
+          }
           if (!isUnsafe) {
             checkOperationPermissions(config.grants, allPermissions);
           }
           const batchables = operations.map((op) => getBatchable(op));
-          const everyOpBatchable = operations.length > 0 && batchables.every((b) => b !== void 0);
+          const everyOpBatchable = batchables.every((b) => b !== void 0);
           if (everyOpBatchable) {
             const sharedDb = drizzle3(config.d1, { schema: config.schema });
             await Promise.all(
@@ -775,6 +920,9 @@ function buildDb(config, isUnsafe, lookupCache) {
         }
       };
     },
+    transaction(callback) {
+      return runTransaction(db, callback);
+    },
     cache: {
       async invalidate(options) {
         if (!cacheManager) return;
@@ -791,9 +939,25 @@ function buildDb(config, isUnsafe, lookupCache) {
   };
   return db;
 }
+function createAppDb(config) {
+  const { d1, schema, cache } = config;
+  const getD1 = typeof d1 === "function" ? d1 : () => d1;
+  return (grants, user) => createDb({
+    d1: getD1(),
+    schema,
+    grants,
+    user,
+    cache
+  });
+}
 
 // src/compose.ts
 function compose(operations, executor) {
+  if (executor.length > 0 && executor.length !== operations.length) {
+    throw new Error(
+      `compose(): executor declares ${executor.length} parameter(s) but ${operations.length} operation(s) were passed. Each operation must have a corresponding run-function parameter (in array order), otherwise sub-operations will silently go uninvoked. Prefer composeSequentialCallback() for by-name binding.`
+    );
+  }
   const allPermissions = deduplicateDescriptors(
     operations.flatMap((op) => op.permissions)
   );
@@ -864,7 +1028,7 @@ function wrapForTracking(target, perms) {
   });
 }
 function createTrackingDb(real, perms) {
-  return {
+  const trackingDb = {
     query: (table) => wrapForTracking(real.query(table), perms),
     insert: (table) => wrapForTracking(real.insert(table), perms),
     update: (table) => wrapForTracking(real.update(table), perms),
@@ -881,8 +1045,23 @@ function createTrackingDb(real, perms) {
         }
       };
     },
+    transaction: async (callback) => {
+      const trackingTx = {
+        query: trackingDb.query,
+        insert: trackingDb.insert,
+        update: trackingDb.update,
+        delete: trackingDb.delete,
+        transaction: (cb) => trackingDb.transaction(cb)
+      };
+      try {
+        await callback(trackingTx);
+      } catch {
+      }
+      return createSentinel();
+    },
     cache: real.cache
   };
+  return trackingDb;
 }
 function composeSequentialCallback(db, callback) {
   const collected = [];
@@ -911,11 +1090,43 @@ 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({});
+        }
+      }
+    }
+  };
+}
 export {
+  TransactionError,
   compose,
   composeSequential,
   composeSequentialCallback,
+  createAppDb,
   createDb,
+  createLookupCache,
+  defineSeed,
   parseCursorParams,
-  parseOffsetParams
+  parseOffsetParams,
+  runWithLookupCache
 };

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,39 @@ 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.
+
 ## Integration
 
 - **@cfast/permissions** -- `grants` come from `resolveGrants(permissions, user.roles)`. Permission WHERE clauses are defined via `grant()` in your permissions config.
@@ -325,6 +558,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()`.