@cfast/db 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { DrizzleTable, PermissionDescriptor, Grant } from '@cfast/permissions';
+import { Grant, DrizzleTable, PermissionDescriptor } from '@cfast/permissions';
 
 /**
  * Extracts the row type from a Drizzle table reference.
@@ -33,7 +33,7 @@ type InferRow<TTable> = TTable extends {
  * // => [{ action: "read", table: "posts" }]
  *
  * // Execute with permission checks
- * const rows = await op.run({});
+ * const rows = await op.run();
  * ```
  */
 type Operation<TResult> = {
@@ -43,7 +43,8 @@ type Operation<TResult> = {
      * Checks permissions, applies permission WHERE clauses, executes the query via Drizzle,
      * and returns the result. Throws `ForbiddenError` if the user's role lacks a required grant.
      *
-     * @param params - Placeholder values for `sql.placeholder()` calls. Pass `{}` when no placeholders are used.
+     * @param params - Optional placeholder values for `sql.placeholder()` calls.
+     *   Omit when your query does not use placeholders — the default is `{}`.
      */
     run: (params?: Record<string, unknown>) => Promise<TResult>;
 };
@@ -222,7 +223,7 @@ type FindFirstOptions = Omit<FindManyOptions, "limit" | "offset">;
  * @example
  * ```ts
  * const params = parseCursorParams(request, { defaultLimit: 20 });
- * const page = await db.query(posts).paginate(params).run({});
+ * const page = await db.query(posts).paginate(params).run();
  * ```
  */
 type CursorParams = {
@@ -242,7 +243,7 @@ type CursorParams = {
  * @example
  * ```ts
  * const params = parseOffsetParams(request, { defaultLimit: 20 });
- * const page = await db.query(posts).paginate(params).run({});
+ * const page = await db.query(posts).paginate(params).run();
  * ```
  */
 type OffsetParams = {
@@ -271,7 +272,7 @@ type PaginateParams = CursorParams | OffsetParams;
  * ```ts
  * const page: CursorPage<Post> = await db.query(posts)
  *   .paginate({ type: "cursor", cursor: null, limit: 20 })
- *   .run({});
+ *   .run();
  *
  * if (page.nextCursor) {
  *   // Fetch next page with page.nextCursor
@@ -295,7 +296,7 @@ type CursorPage<T> = {
  * ```ts
  * const page: OffsetPage<Post> = await db.query(posts)
  *   .paginate({ type: "offset", page: 1, limit: 20 })
- *   .run({});
+ *   .run();
  *
  * console.log(`Page ${page.page} of ${page.totalPages} (${page.total} total)`);
  * ```
@@ -347,6 +348,54 @@ type PaginateOptions = {
     /** Per-query cache control. Pass `false` to skip caching, or an object to customize. */
     cache?: QueryCacheOptions;
 };
+/**
+ * The transaction handle passed to the `db.transaction()` callback.
+ *
+ * Exposes the read/write builder surface of {@link Db} but intentionally omits
+ * `unsafe`, `batch`, `transaction`, and `cache`. Those are off-limits inside a
+ * transaction:
+ *
+ * - `unsafe()` would let you bypass permissions mid-tx — if you need system
+ *   access, use `db.unsafe().transaction(...)` on the outer handle instead.
+ * - `batch()` / nested `transaction()` calls are flattened into the parent's
+ *   pending queue automatically, so the plain mutate methods are all you need.
+ * - `cache` invalidation is driven by the single commit at the end of the
+ *   transaction, not per-sub-op.
+ *
+ * Writes (`tx.insert` / `tx.update` / `tx.delete`) are recorded and flushed as
+ * an atomic batch when the callback returns. Reads (`tx.query`) execute
+ * eagerly so the caller can branch on their results.
+ */
+type Tx = {
+    /** Same as {@link Db.query}: reads execute eagerly against the underlying db. */
+    query: <TTable extends DrizzleTable>(table: TTable) => QueryBuilder<TTable>;
+    /**
+     * Same as {@link Db.insert}: the returned Operation's `.run()` records the
+     * insert into the transaction's pending queue. `.returning().run()` records
+     * the insert and returns a promise that resolves AFTER the batch flushes.
+     */
+    insert: <TTable extends DrizzleTable>(table: TTable) => InsertBuilder<TTable>;
+    /**
+     * Same as {@link Db.update}: the returned Operation's `.run()` records the
+     * update into the transaction's pending queue. Use relative SQL with a
+     * WHERE guard (e.g. `set({ stock: sql\`stock - ${qty}\` }).where(gte(...))`)
+     * for concurrency-safe read-modify-write.
+     */
+    update: <TTable extends DrizzleTable>(table: TTable) => UpdateBuilder<TTable>;
+    /** Same as {@link Db.delete}: records the delete into the transaction's pending queue. */
+    delete: <TTable extends DrizzleTable>(table: TTable) => DeleteBuilder<TTable>;
+    /**
+     * Nested transaction. Flattens into the parent's pending queue so every
+     * write still commits in a single atomic batch. The nested callback's
+     * return value is propagated as usual; any error thrown aborts the
+     * entire outer transaction.
+     *
+     * Use this when a helper function wants to "own" its own tx scope but
+     * the caller already started a transaction — the helper can call
+     * `tx.transaction(...)` unconditionally and Just Work.
+     */
+    transaction: <T>(callback: (tx: Tx) => Promise<T>) => Promise<T>;
+};
 /**
  * A permission-aware database instance bound to a specific user.
  *
@@ -357,13 +406,13 @@ type PaginateOptions = {
  * @example
  * ```ts
  * // Read
- * const posts = await db.query(postsTable).findMany().run({});
+ * const posts = await db.query(postsTable).findMany().run();
  *
  * // Write
- * await db.insert(postsTable).values({ title: "Hello" }).run({});
+ * await db.insert(postsTable).values({ title: "Hello" }).run();
  *
  * // Bypass permissions for system tasks
- * await db.unsafe().delete(sessionsTable).where(expired).run({});
+ * await db.unsafe().delete(sessionsTable).where(expired).run();
  * ```
  */
 type Db = {
@@ -405,6 +454,44 @@ type Db = {
      * compositions but loses the atomicity guarantee.
      */
     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 The value returned by the callback, or rejects with whatever the
+     *   callback threw (after rolling back pending writes).
+     */
+    transaction: <T>(callback: (tx: Tx) => Promise<T>) => Promise<T>;
     /** Cache control methods for manual invalidation. */
     cache: {
         /** Invalidate cached queries by tag names and/or table names. */
@@ -415,6 +502,29 @@ type Db = {
             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;
 };
 /**
  * Builder for read queries on a single table.
@@ -427,13 +537,13 @@ type Db = {
  * const builder = db.query(posts);
  *
  * // Fetch all visible posts
- * const all = await builder.findMany().run({});
+ * const all = await builder.findMany().run();
  *
  * // Fetch a single post
- * const post = await builder.findFirst({ where: eq(posts.id, id) }).run({});
+ * const post = await builder.findFirst({ where: eq(posts.id, id) }).run();
  *
  * // Paginate
- * const page = await builder.paginate(params, { orderBy: desc(posts.createdAt) }).run({});
+ * const page = await builder.paginate(params, { orderBy: desc(posts.createdAt) }).run();
  * ```
  */
 type QueryBuilder<TTable extends DrizzleTable = DrizzleTable> = {
@@ -442,20 +552,50 @@ type QueryBuilder<TTable extends DrizzleTable = DrizzleTable> = {
      *
      * The result is typed via `InferRow<TTable>`, so callers get IntelliSense on
      * `(row) => row.title` without any cast.
+     *
+     * **Relations escape hatch (#158):** when you pass `with: { relation: true }`,
+     * Drizzle's relational query builder embeds the joined rows into the result,
+     * but `@cfast/db` cannot statically infer that shape from the
+     * `Record<string, unknown>` schema we accept here. Override the row type via
+     * the optional `TRow` generic to claim the shape you know the query will
+     * produce, instead of having to `as any` the result downstream:
+     *
+     * ```ts
+     * type RecipeWithIngredients = Recipe & { ingredients: Ingredient[] };
+     * const recipes = await db
+     *   .query(recipesTable)
+     *   .findMany<RecipeWithIngredients>({ with: { ingredients: true } })
+     *   .run();
+     * // recipes is RecipeWithIngredients[], no cast needed
+     * ```
      */
-    findMany: (options?: FindManyOptions) => Operation<InferRow<TTable>[]>;
+    findMany: <TRow = InferRow<TTable>>(options?: FindManyOptions) => Operation<TRow[]>;
     /**
      * Returns an {@link Operation} that fetches the first matching row, or `undefined`
      * if none match. The row type is propagated from `TTable`.
+     *
+     * Same `TRow` generic escape hatch as {@link findMany} for `with`-relation
+     * shapes that the framework can't infer from the runtime-typed schema.
+     *
+     * ```ts
+     * type RecipeWithIngredients = Recipe & { ingredients: Ingredient[] };
+     * const recipe = await db
+     *   .query(recipesTable)
+     *   .findFirst<RecipeWithIngredients>({ where: eq(recipes.id, id), with: { ingredients: true } })
+     *   .run();
+     * // recipe is RecipeWithIngredients | undefined
+     * ```
      */
-    findFirst: (options?: FindFirstOptions) => Operation<InferRow<TTable> | undefined>;
+    findFirst: <TRow = InferRow<TTable>>(options?: FindFirstOptions) => Operation<TRow | undefined>;
     /**
      * Returns a paginated {@link Operation} using either cursor-based or offset-based strategy.
      *
      * The return type depends on the `params.type` discriminant: {@link CursorPage} for `"cursor"`,
-     * {@link OffsetPage} for `"offset"`. Each page's items are typed as `InferRow<TTable>`.
+     * {@link OffsetPage} for `"offset"`. Each page's items are typed as `InferRow<TTable>` by
+     * default; pass an explicit `TRow` to claim a wider shape (e.g. when using
+     * `with: { ... }` to embed related rows).
      */
-    paginate: (params: CursorParams | OffsetParams, options?: PaginateOptions) => Operation<CursorPage<InferRow<TTable>>> | Operation<OffsetPage<InferRow<TTable>>>;
+    paginate: <TRow = InferRow<TTable>>(params: CursorParams | OffsetParams, options?: PaginateOptions) => Operation<CursorPage<TRow>> | Operation<OffsetPage<TRow>>;
 };
 /**
  * Builder for insert operations on a single table.
@@ -466,13 +606,13 @@ type QueryBuilder<TTable extends DrizzleTable = DrizzleTable> = {
  * @example
  * ```ts
  * // Insert without returning
- * await db.insert(posts).values({ title: "Hello", authorId: user.id }).run({});
+ * await db.insert(posts).values({ title: "Hello", authorId: user.id }).run();
  *
  * // Insert with returning
  * const row = await db.insert(posts)
  *   .values({ title: "Hello", authorId: user.id })
  *   .returning()
- *   .run({});
+ *   .run();
  * ```
  */
 type InsertBuilder<TTable extends DrizzleTable = DrizzleTable> = {
@@ -500,7 +640,7 @@ type InsertReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operat
  * await db.update(posts)
  *   .set({ published: true })
  *   .where(eq(posts.id, "abc-123"))
- *   .run({});
+ *   .run();
  * ```
  */
 type UpdateBuilder<TTable extends DrizzleTable = DrizzleTable> = {
@@ -534,7 +674,7 @@ type UpdateReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operat
  *
  * @example
  * ```ts
- * await db.delete(posts).where(eq(posts.id, "abc-123")).run({});
+ * await db.delete(posts).where(eq(posts.id, "abc-123")).run();
  * ```
  */
 type DeleteBuilder<TTable extends DrizzleTable = DrizzleTable> = {
@@ -576,10 +716,102 @@ type DeleteReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operat
  * });
  *
  * // All operations check permissions at .run() time
- * const posts = await db.query(postsTable).findMany().run({});
+ * const posts = await db.query(postsTable).findMany().run();
  * ```
  */
 declare function createDb(config: DbConfig): Db;
+/**
+ * App-level db factory configuration. The "constants" — D1 binding,
+ * Drizzle schema, cache config — that don't change between requests.
+ *
+ * Returned by {@link createAppDb}, called per-request with the user's
+ * resolved grants and identity to produce a fresh permission-aware {@link Db}.
+ */
+type AppDbConfig = {
+    /**
+     * The Cloudflare D1 database binding. Pass either the binding directly
+     * (for tests, where the mock D1 is in scope at module load) or a
+     * `() => D1Database` getter (for Workers, where `env.DB` is only
+     * available per-request -- typical pattern: `() => env.get().DB`).
+     *
+     * The lazy form lets `createAppDb()` be called once at module-load time
+     * even though the binding itself isn't materialized until the first
+     * request, so the entire app shares a single factory definition.
+     */
+    d1: D1Database | (() => D1Database);
+    /**
+     * Drizzle schema. Same shape as {@link DbConfig.schema} -- pass
+     * `import * as schema from "./schema"`.
+     */
+    schema: Record<string, unknown>;
+    /**
+     * Cache configuration shared across every per-request `Db`. Defaults to
+     * `{ backend: "cache-api" }` to match `createDb`. Pass `false` to opt out.
+     */
+    cache?: DbConfig["cache"];
+};
+/**
+ * The per-request factory returned by {@link createAppDb}. Closes over the
+ * app-level config and accepts the request-scoped grants + user, returning a
+ * fresh permission-aware {@link Db}.
+ *
+ * Stable type so callers (e.g. `@cfast/admin`'s `createDbForAdmin`,
+ * `@cfast/core`'s `dbPlugin`, route loaders) can pass the factory around
+ * without re-deriving its signature.
+ */
+type AppDbFactory = (grants: Grant[], user: {
+    id: string;
+} | null) => Db;
+/**
+ * Consolidates the three near-identical `createDb` factories that every
+ * cfast app used to define (#149):
+ *
+ * - `app/cfast.server.ts` (`dbPlugin` setup)
+ * - `app/admin.server.ts` (`createDbForAdmin`)
+ * - any route handler that built `Db` ad-hoc from `env.DB`
+ *
+ * Splits the configuration into "app constants" (D1 binding, schema, cache)
+ * and "per-request inputs" (grants, user). The returned factory captures the
+ * constants once at module load and accepts the request-scoped inputs at
+ * call time.
+ *
+ * Use this whenever the same shape of `createDb({ d1, schema, grants, user, cache })`
+ * shows up in more than one file in your app. The factory is a stable
+ * `(grants, user) => Db` callable that plugs directly into:
+ *
+ * - `@cfast/core`'s db plugin: `setup(ctx) { return { client: appDb(ctx.auth.grants, ctx.auth.user) } }`
+ * - `@cfast/admin`'s `db: createDbForAdmin` config: `db: appDb`
+ * - any route handler: `const db = appDb(ctx.grants, ctx.user)`
+ *
+ * @example
+ * ```ts
+ * // app/db/factory.ts -- defined once
+ * import { createAppDb } from "@cfast/db";
+ * import * as schema from "./schema";
+ *
+ * export const appDb = createAppDb({
+ *   d1: env.get().DB,
+ *   schema,
+ *   cache: false,
+ * });
+ *
+ * // app/cfast.server.ts -- consume from the plugin
+ * const dbPlugin = definePlugin({
+ *   name: "db",
+ *   requires: [authPlugin],
+ *   setup(ctx) {
+ *     return { client: appDb(ctx.auth.grants, ctx.auth.user) };
+ *   },
+ * });
+ *
+ * // app/admin.server.ts -- consume from admin
+ * const adminConfig = {
+ *   db: appDb,    // (grants, user) => Db -- already the right shape
+ *   ...
+ * };
+ * ```
+ */
+declare function createAppDb(config: AppDbConfig): AppDbFactory;
 
 /**
  * A function that executes a single sub-operation within a {@link compose} executor.
@@ -596,10 +828,51 @@ type RunFn = (params?: Record<string, unknown>) => Promise<unknown>;
  * `.run()` still performs its own permission check when the executor calls it. This enables
  * data dependencies between operations (e.g., using an insert result's ID in an audit log).
  *
+ * ### ⚠️ Positional callback footgun
+ *
+ * The `executor` callback receives one `run` function per entry in `operations`,
+ * **in array order**. TypeScript cannot enforce that the parameter names line
+ * up with the operations they correspond to, so a callback that swaps
+ * `(runUpdate, runVersion)` for `(runVersion, runUpdate)` -- or that simply
+ * forgets a parameter -- silently invokes the wrong sub-operation. The wiki
+ * tracking issue (#182) was a real bug of this shape: a `runVersion` parameter
+ * shadowed an outer-scope variable and was never invoked.
+ *
+ * **Prefer {@link composeSequentialCallback} for any workflow with data
+ * dependencies.** It accepts an `async (db) => ...` callback that uses the
+ * normal db builders by reference, so the binding is by name (not by
+ * position) and there is no way to wire the wrong op to the wrong handler:
+ *
+ * ```ts
+ * // ✗ Footgun: parameter order must match array order, not type-checked.
+ * const op = compose(
+ *   [updatePost, bumpVersion],
+ *   async (runUpdate, runVersion) => {
+ *     await runUpdate(); // What if `runVersion` was renamed and never called?
+ *     await runVersion();
+ *   },
+ * );
+ *
+ * // ✓ Preferred: by-name binding via composeSequentialCallback.
+ * const op = composeSequentialCallback(db, async (tx) => {
+ *   await tx.update(posts).set({ ... }).where(...).run();
+ *   await tx.update(postVersions).set({ ... }).where(...).run();
+ * });
+ * ```
+ *
+ * Use `compose()` only when you genuinely need to interleave non-db logic
+ * between sub-operations and you have a small, fixed number of ops where the
+ * footgun is easy to read around. For everything else, reach for
+ * {@link composeSequential} (no callback at all) or
+ * {@link composeSequentialCallback} (by-name binding).
+ *
  * @typeParam TResult - The return type of the executor function.
  * @param operations - The operations to compose. Their permissions are merged and deduplicated.
  * @param executor - A function that receives a `run` function for each operation (in order).
  *   You control execution order, data flow between operations, and the return value.
+ *   **Must declare exactly one parameter per operation** -- TypeScript cannot enforce this,
+ *   but a regression test in this package asserts that swapping the count surfaces undefined
+ *   `run` calls at runtime.
  * @returns A single {@link Operation} with combined permissions.
  *
  * @example
@@ -609,8 +882,8 @@ type RunFn = (params?: Record<string, unknown>) => Promise<unknown>;
  * const publishWorkflow = compose(
  *   [updatePost, insertAuditLog],
  *   async (doUpdate, doAudit) => {
- *     const updated = await doUpdate({});
- *     await doAudit({});
+ *     const updated = await doUpdate();
+ *     await doAudit();
  *     return { published: true };
  *   },
  * );
@@ -620,7 +893,7 @@ type RunFn = (params?: Record<string, unknown>) => Promise<unknown>;
  * // => [{ action: "update", table: "posts" }, { action: "create", table: "audit_logs" }]
  *
  * // Execute all sub-operations
- * await publishWorkflow.run({});
+ * await publishWorkflow.run();
  * ```
  */
 declare function compose<TResult>(operations: Operation<unknown>[], executor: (...runs: RunFn[]) => TResult | Promise<TResult>): Operation<TResult>;
@@ -749,4 +1022,162 @@ declare function parseCursorParams(request: Request, options?: PaginationOptions
  */
 declare function parseOffsetParams(request: Request, options?: PaginationOptions): OffsetParams;
 
-export { type CacheBackend, type CacheConfig, type CursorPage, type CursorParams, type Db, type DbConfig, type DeleteBuilder, type DeleteReturningBuilder, type FindFirstOptions, type FindManyOptions, type InferRow, type InsertBuilder, type InsertReturningBuilder, type OffsetPage, type OffsetParams, type Operation, type PaginateOptions, type PaginateParams, type QueryBuilder, type QueryCacheOptions, type UpdateBuilder, type UpdateReturningBuilder, type UpdateWhereBuilder, compose, composeSequential, composeSequentialCallback, createDb, parseCursorParams, parseOffsetParams };
+/**
+ * Error thrown when a transaction is misused (e.g. an op is recorded after the
+ * transaction has already committed or aborted).
+ */
+declare class TransactionError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * A single seed entry — every row in `rows` is inserted into `table` at seed
+ * time. Row shape is inferred from the Drizzle table so typos in column names
+ * are caught by `tsc` instead of failing at runtime when `INSERT` rejects
+ * the statement.
+ *
+ * @typeParam TTable - The Drizzle table reference (e.g. `typeof usersTable`).
+ */
+type SeedEntry<TTable extends DrizzleTable = DrizzleTable> = {
+    /**
+     * The Drizzle table to insert into. Must be imported from your schema
+     * (`import { users } from "~/db/schema"`) rather than passed as a string
+     * so the helper can infer row types and forward the reference to
+     * `db.insert()`.
+     */
+    table: TTable;
+    /**
+     * Rows to insert. The row shape is inferred from the table's
+     * `$inferSelect` — making a typo in a column name is a compile-time error.
+     *
+     * Entries are inserted in the order they appear, which lets you control
+     * foreign-key ordering just by ordering your `entries` array
+     * (`{ users }` before `{ posts }`, etc.).
+     */
+    rows: readonly InferRow<TTable>[];
+};
+/**
+ * Configuration passed to {@link defineSeed}.
+ */
+type SeedConfig = {
+    /**
+     * Ordered list of seed entries. Each entry is flushed as a batched insert
+     * in list order, so place parent tables (users, orgs) before child tables
+     * (posts, memberships) that reference them via foreign keys.
+     */
+    entries: readonly SeedEntry[];
+};
+/**
+ * The compiled seed returned by {@link defineSeed}.
+ *
+ * Holds a frozen copy of the entry list so runner callers can introspect
+ * what would be seeded, plus a `run(db)` method that actually executes the
+ * inserts against a real {@link Db} instance.
+ */
+type Seed = {
+    /** The frozen list of entries this seed will insert, in order. */
+    readonly entries: readonly SeedEntry[];
+    /**
+     * Executes every entry against the given {@link Db} in the order they were
+     * declared. Uses `db.unsafe()` internally so seed scripts don't need
+     * their own grants plumbing — seeding is a system task by definition.
+     *
+     * Entries with an empty `rows` array are skipped so callers can leave
+     * placeholder entries in the config without crashing the seed.
+     *
+     * @param db - A {@link Db} instance, typically created once at the top
+     *   of a `scripts/seed.ts` file via `createDb({...})`.
+     */
+    run: (db: Db) => Promise<void>;
+};
+/**
+ * Declares a database seed in a portable, type-safe way.
+ *
+ * The canonical replacement for hand-rolled `scripts/seed.ts` files that
+ * called `db.mutate("tablename")` (a method that never existed) or reached
+ * straight into raw Drizzle. Use the scaffolded `scripts/seed.ts` in a
+ * `create-cfast` project for a ready-made example.
+ *
+ * @example
+ * ```ts
+ * // scripts/seed.ts
+ * import { defineSeed, createDb } 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" },
+ *         { id: "u-2", email: "grace@example.com", name: "Grace" },
+ *       ],
+ *     },
+ *     {
+ *       table: schema.posts,
+ *       rows: [
+ *         { id: "p-1", authorId: "u-1", title: "Hello" },
+ *       ],
+ *     },
+ *   ],
+ * });
+ *
+ * // In a worker/runner that already has a real D1 binding:
+ * const db = createDb({ d1, schema, grants: [], user: null });
+ * await seed.run(db);
+ * ```
+ *
+ * @param config - The {@link SeedConfig} with the ordered list of entries.
+ * @returns A {@link Seed} with a `.run(db)` executor.
+ */
+declare function defineSeed(config: SeedConfig): Seed;
+
+/**
+ * Per-request cache that holds the resolved `with` lookup map for each grant.
+ *
+ * Keyed by grant object identity so two queries that consult the same grant
+ * within a single request reuse the same lookup promise (each underlying
+ * `LookupFn` runs at most once).
+ *
+ * The cache's lifetime is tied to the surrounding async context rather than
+ * to any specific `Db` instance: `createDb()` calls transparently run inside
+ * an {@link AsyncLocalStorage} scope, and nested operations resolve their
+ * lookups through the active scope's cache. Tests (or anything sharing a
+ * single `Db` across logical requests) can scope an explicit cache via
+ * {@link runWithLookupCache}.
+ */
+type LookupCache = Map<Grant, Promise<Record<string, unknown>>>;
+/**
+ * Creates a fresh per-request lookup cache. Exposed for tests and for the
+ * `Db` wrapper that establishes the ALS scope; normal framework consumers
+ * should rely on {@link runWithLookupCache} or the automatic scope that
+ * `createDb()` sets up on every invocation.
+ */
+declare function createLookupCache(): LookupCache;
+/**
+ * Runs `fn` inside a fresh per-request lookup cache scope.
+ *
+ * Use this when you need to reuse a single `Db` across multiple logical
+ * requests (e.g. in tests that insert new grants mid-run) and want each
+ * logical request to see a clean cache. All nested `Db` operations inside
+ * `fn` (and any async work they start) share the same cache.
+ *
+ * @param fn - The callback to run inside the scope. Its return value is
+ *   forwarded back to the caller.
+ * @param cache - Optional pre-existing cache to install. Defaults to a fresh
+ *   empty cache.
+ *
+ * @example
+ * ```ts
+ * // Test setup reusing a single Db:
+ * const db = createDb({ ... });
+ *
+ * await runWithLookupCache(async () => {
+ *   await db.insert(friendGrants).values(...).run();
+ *   await db.query(posts).findMany().run(); // sees the new grant
+ * });
+ * ```
+ */
+declare function runWithLookupCache<T>(fn: () => T, cache?: LookupCache): T;
+
+export { type AppDbConfig, type AppDbFactory, type CacheBackend, type CacheConfig, type CursorPage, type CursorParams, type Db, type DbConfig, type DeleteBuilder, type DeleteReturningBuilder, type FindFirstOptions, type FindManyOptions, type InferRow, type InsertBuilder, type InsertReturningBuilder, type LookupCache, type OffsetPage, type OffsetParams, type Operation, type PaginateOptions, type PaginateParams, type QueryBuilder, type QueryCacheOptions, type Seed, type SeedConfig, type SeedEntry, TransactionError, type Tx, type UpdateBuilder, type UpdateReturningBuilder, type UpdateWhereBuilder, compose, composeSequential, composeSequentialCallback, createAppDb, createDb, createLookupCache, defineSeed, parseCursorParams, parseOffsetParams, runWithLookupCache };