@cfast/db 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,458 +1,105 @@
 import { Grant, DrizzleTable, PermissionDescriptor } from '@cfast/permissions';
+import { Table, TablesRelationalConfig, ExtractTablesWithRelations, TableRelationalConfig, BuildQueryResult } from 'drizzle-orm';
 
-/**
- * Extracts the row type from a Drizzle table reference.
- *
- * Drizzle tables expose `$inferSelect` (the row shape returned by `SELECT *`).
- * `InferRow<typeof posts>` resolves to `{ id: string; title: string; ... }`.
- *
- * Falls back to `Record<string, unknown>` for opaque `DrizzleTable` references
- * (e.g. when callers do not specify a concrete table type generic).
- *
- * @typeParam TTable - The Drizzle table type (e.g. `typeof posts`).
- */
 type InferRow<TTable> = TTable extends {
     $inferSelect: infer R;
 } ? R : Record<string, unknown>;
-/**
- * A lazy, permission-aware database operation.
- *
- * Every method on {@link Db} returns an `Operation` instead of a promise. The operation
- * exposes its permission requirements via `.permissions` for inspection and executes with
- * full permission checking via `.run()`. This two-phase design enables UI adaptation,
- * upfront composition via {@link compose}, and introspection before any SQL is executed.
- *
- * @typeParam TResult - The type of the result returned by `.run()`.
- *
- * @example
- * ```ts
- * const op = db.query(posts).findMany();
- *
- * // Inspect permissions without executing
- * console.log(op.permissions);
- * // => [{ action: "read", table: "posts" }]
- *
- * // Execute with permission checks
- * const rows = await op.run();
- * ```
- */
+/** @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> = {
-    /** Structural permission requirements. Available immediately without execution. */
     permissions: PermissionDescriptor[];
-    /**
-     * 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 - 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>;
 };
-/**
- * Supported cache backend types for {@link CacheConfig}.
- *
- * - `"cache-api"` — Edge-local Cloudflare Cache API (~0ms latency, per-edge-node).
- * - `"kv"` — Global Cloudflare KV (10-50ms latency, eventually consistent).
- */
 type CacheBackend = "cache-api" | "kv";
-/**
- * Configuration for the database cache layer.
- *
- * Controls how query results are cached and invalidated. Mutations automatically
- * bump table version counters, causing subsequent reads to miss the cache.
- *
- * @example
- * ```ts
- * const db = createDb({
- *   d1: env.DB,
- *   schema,
- *   grants: resolvedGrants,
- *   user: currentUser,
- *   cache: {
- *     backend: "cache-api",
- *     ttl: "30s",
- *     staleWhileRevalidate: "5m",
- *     exclude: ["sessions"],
- *   },
- * });
- * ```
- */
 type CacheConfig = {
-    /** Which cache backend to use: edge-local Cache API or global KV. */
     backend: CacheBackend;
-    /** KV namespace binding. Required when {@link backend} is `"kv"`. */
     kv?: KVNamespace;
-    /** Default TTL for cached queries (e.g., `"30s"`, `"5m"`, `"1h"`). Defaults to `"60s"`. */
     ttl?: string;
-    /** Stale-while-revalidate window (e.g., `"5m"`). Serves stale data while revalidating in the background. */
     staleWhileRevalidate?: string;
-    /** Table names that should never be cached (e.g., `["sessions", "tokens"]`). */
     exclude?: string[];
-    /** Observability hook called on cache hits. */
     onHit?: (key: string, table: string) => void;
-    /** Observability hook called on cache misses. */
     onMiss?: (key: string, table: string) => void;
-    /** Observability hook called when tables are invalidated by mutations. */
     onInvalidate?: (tables: string[]) => void;
 };
-/**
- * Per-query cache control options.
- *
- * Pass `false` to skip caching for a specific query, or an options object to
- * override the default {@link CacheConfig} for that query.
- *
- * @example
- * ```ts
- * // Skip cache entirely
- * db.query(posts).findMany({ cache: false });
- *
- * // Custom TTL and tags
- * db.query(posts).findMany({ cache: { ttl: "5m", tags: ["user-posts"] } });
- * ```
- */
 type QueryCacheOptions = false | {
-    /** Override the default TTL for this query (e.g., `"5m"`, `"1h"`). */
     ttl?: string;
-    /** Override the default stale-while-revalidate window for this query. */
     staleWhileRevalidate?: string;
-    /** Tags for targeted manual invalidation via `db.cache.invalidate({ tags })`. */
     tags?: string[];
 };
-/**
- * Configuration for {@link createDb}.
- *
- * @example
- * ```ts
- * import { createDb } from "@cfast/db";
- * import * as schema from "./schema";
- *
- * const db = createDb({
- *   d1: env.DB,
- *   schema,
- *   grants: resolvedGrants,
- *   user: { id: "user-123" },
- *   cache: { backend: "cache-api" },
- * });
- * ```
- */
-type DbConfig = {
-    /** The Cloudflare D1 database binding from `env.DB`. */
+type DbConfig<TSchema extends Record<string, unknown> = Record<string, unknown>> = {
     d1: D1Database;
-    /**
-     * Drizzle schema object. Must be `import * as schema` so that keys match
-     * table variable names (required by Drizzle's relational query API).
-     *
-     * Typed as `Record<string, unknown>` so callers can pass `import * as schema`
-     * directly without casting -- Drizzle schemas typically include `Relations`
-     * exports alongside tables, and the `@cfast/db` runtime ignores any non-table
-     * entries when looking up tables by key.
-     */
-    schema: Record<string, unknown>;
-    /** Resolved permission grants for the current user's role, from `resolveGrants()`. */
+    schema: TSchema;
     grants: Grant[];
-    /**
-     * The current user, or `null` for anonymous access.
-     * When `null`, the `"anonymous"` role is used for permission checks.
-     */
     user: {
         id: string;
     } | null;
-    /** Cache configuration, or `false` to disable caching entirely. Defaults to `{ backend: "cache-api" }`. */
     cache?: CacheConfig | false;
 };
-/**
- * Options for `db.query(table).findMany()`.
- *
- * The `where` condition is AND'd with any permission-based WHERE clauses
- * resolved from the user's grants.
- *
- * @example
- * ```ts
- * import { eq, desc } from "drizzle-orm";
- *
- * db.query(posts).findMany({
- *   columns: { id: true, title: true },
- *   where: eq(posts.category, "tech"),
- *   orderBy: desc(posts.createdAt),
- *   limit: 10,
- *   offset: 20,
- *   with: { comments: true },
- *   cache: { ttl: "5m", tags: ["posts"] },
- * });
- * ```
- */
 type FindManyOptions = {
-    /** Column selection (e.g., `{ id: true, title: true }`). Omit to select all columns. */
     columns?: Record<string, boolean>;
-    /** User-supplied filter condition (AND'd with permission filters at `.run()` time). */
     where?: unknown;
-    /** Ordering expression (e.g., `desc(posts.createdAt)`). */
     orderBy?: unknown;
-    /** Maximum number of rows to return. */
     limit?: number;
-    /** Number of rows to skip (for offset-based pagination). */
     offset?: number;
-    /**
-     * Drizzle relational query includes (e.g., `{ comments: true }`).
-     *
-     * Note: Permission filters are only applied to the root table, not to joined relations.
-     */
     with?: Record<string, unknown>;
-    /** Per-query cache control. Pass `false` to skip caching, or an object to customize. */
     cache?: QueryCacheOptions;
 };
-/**
- * Options for `db.query(table).findFirst()`.
- *
- * Same as {@link FindManyOptions} without `limit`/`offset` (returns the first match or `undefined`).
- *
- * @example
- * ```ts
- * db.query(posts).findFirst({
- *   where: eq(posts.id, "abc-123"),
- * });
- * ```
- */
 type FindFirstOptions = Omit<FindManyOptions, "limit" | "offset">;
-/**
- * Parsed cursor-based pagination parameters from a request URL.
- *
- * Produced by {@link parseCursorParams}. Pass to `db.query(table).paginate()` for
- * keyset pagination that avoids the offset performance cliff on large datasets.
- *
- * @example
- * ```ts
- * const params = parseCursorParams(request, { defaultLimit: 20 });
- * const page = await db.query(posts).paginate(params).run();
- * ```
- */
 type CursorParams = {
-    /** Discriminant for cursor-based pagination. Always `"cursor"`. */
     type: "cursor";
-    /** The opaque cursor string from the previous page, or `null` for the first page. */
     cursor: string | null;
-    /** Maximum items per page (clamped between 1 and `maxLimit`). */
     limit: number;
 };
-/**
- * Parsed offset-based pagination parameters from a request URL.
- *
- * Produced by {@link parseOffsetParams}. Pass to `db.query(table).paginate()` for
- * traditional page-number-based pagination with total counts.
- *
- * @example
- * ```ts
- * const params = parseOffsetParams(request, { defaultLimit: 20 });
- * const page = await db.query(posts).paginate(params).run();
- * ```
- */
 type OffsetParams = {
-    /** Discriminant for offset-based pagination. Always `"offset"`. */
     type: "offset";
-    /** The 1-based page number. */
     page: number;
-    /** Maximum items per page (clamped between 1 and `maxLimit`). */
     limit: number;
 };
-/**
- * Union of cursor and offset pagination parameters.
- *
- * Use the `type` discriminant to determine which pagination strategy is in use.
- * Accepted by `db.query(table).paginate()`.
- */
 type PaginateParams = CursorParams | OffsetParams;
-/**
- * A page of results from cursor-based pagination.
- *
- * Use `nextCursor` to fetch the next page. When `nextCursor` is `null`, there are no more pages.
- *
- * @typeParam T - The row type.
- *
- * @example
- * ```ts
- * const page: CursorPage<Post> = await db.query(posts)
- *   .paginate({ type: "cursor", cursor: null, limit: 20 })
- *   .run();
- *
- * if (page.nextCursor) {
- *   // Fetch next page with page.nextCursor
- * }
- * ```
- */
 type CursorPage<T> = {
-    /** The items on this page. */
     items: T[];
-    /** Opaque cursor for the next page, or `null` if this is the last page. */
     nextCursor: string | null;
 };
-/**
- * A page of results from offset-based pagination.
- *
- * Includes total counts for rendering page navigation controls.
- *
- * @typeParam T - The row type.
- *
- * @example
- * ```ts
- * const page: OffsetPage<Post> = await db.query(posts)
- *   .paginate({ type: "offset", page: 1, limit: 20 })
- *   .run();
- *
- * console.log(`Page ${page.page} of ${page.totalPages} (${page.total} total)`);
- * ```
- */
 type OffsetPage<T> = {
-    /** The items on this page. */
     items: T[];
-    /** Total number of matching rows across all pages. */
     total: number;
-    /** The current 1-based page number. */
     page: number;
-    /** Total number of pages (computed as `Math.ceil(total / limit)`). */
     totalPages: number;
 };
-/**
- * Options for `db.query(table).paginate()`.
- *
- * Combines query filtering with pagination-specific settings. The actual pagination
- * strategy (cursor vs. offset) is determined by the {@link PaginateParams} passed
- * alongside these options.
- *
- * @example
- * ```ts
- * db.query(posts).paginate(params, {
- *   where: eq(posts.published, true),
- *   orderBy: desc(posts.createdAt),
- *   cursorColumns: [posts.createdAt, posts.id],
- *   orderDirection: "desc",
- * });
- * ```
- */
 type PaginateOptions = {
-    /** Column selection (e.g., `{ id: true, title: true }`). Omit to select all columns. */
     columns?: Record<string, boolean>;
-    /** User-supplied filter condition (AND'd with permission filters at `.run()` time). */
     where?: unknown;
-    /** Ordering expression for offset pagination. Ignored for cursor pagination (uses `cursorColumns` instead). */
     orderBy?: unknown;
-    /** Drizzle column references used for cursor-based ordering and comparison. */
     cursorColumns?: unknown[];
-    /** Sort direction for cursor pagination. Defaults to `"desc"`. */
     orderDirection?: "asc" | "desc";
-    /**
-     * Drizzle relational query includes (e.g., `{ comments: true }`).
-     *
-     * Note: Permission filters are only applied to the root table, not to joined relations.
-     */
     with?: Record<string, unknown>;
-    /** 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.
-     */
+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>;
-    /**
-     * 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>;
+    transaction: <T>(callback: (tx: Tx<TSchema>) => Promise<T>) => Promise<T>;
 };
-/**
- * A permission-aware database instance bound to a specific user.
- *
- * Created by {@link createDb}. All query and mutation methods return lazy {@link Operation}
- * objects that check permissions at `.run()` time. Create a new instance per request --
- * sharing across requests would apply one user's permissions to another's queries.
- *
- * @example
- * ```ts
- * // Read
- * const posts = await db.query(postsTable).findMany().run();
- *
- * // Write
- * await db.insert(postsTable).values({ title: "Hello" }).run();
- *
- * // Bypass permissions for system tasks
- * await db.unsafe().delete(sessionsTable).where(expired).run();
- * ```
- */
-type Db = {
-    /**
-     * Creates a {@link QueryBuilder} for reading rows from the given table.
-     *
-     * The builder is generic over `TTable`, so `findMany`/`findFirst` return rows
-     * typed via `InferRow<TTable>` -- callers don't need to cast to `as any`.
-     */
-    query: <TTable extends DrizzleTable>(table: TTable) => QueryBuilder<TTable>;
-    /** Creates an {@link InsertBuilder} for inserting rows into the given table. */
+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>;
-    /** Creates an {@link UpdateBuilder} for updating rows in the given table. */
     update: <TTable extends DrizzleTable>(table: TTable) => UpdateBuilder<TTable>;
-    /** Creates a {@link DeleteBuilder} for deleting rows from the given table. */
     delete: <TTable extends DrizzleTable>(table: TTable) => DeleteBuilder<TTable>;
-    /**
-     * Returns a new `Db` instance that skips all permission checks.
-     *
-     * Use for cron jobs, migrations, and system operations without an authenticated user.
-     * Every call site is greppable via `git grep '.unsafe()'`.
-     */
-    unsafe: () => Db;
-    /**
-     * Groups multiple operations into a single {@link Operation} with merged, deduplicated permissions.
-     *
-     * When every operation was produced by `db.insert/update/delete`, the batch is
-     * executed via D1's native `batch()` API, which is **atomic** -- if any
-     * statement fails, the entire batch is rolled back. This is the recommended
-     * way to perform multi-step mutations that need transactional safety, such as
-     * decrementing stock across multiple products during checkout.
-     *
-     * Permissions for every sub-operation are checked **upfront**: if the user
-     * lacks any required grant, the batch throws before any SQL is issued.
-     *
-     * Operations that don't carry the internal batchable hook (for example, ops
-     * produced by `compose()` executors) cause the batch to fall back to
-     * sequential execution. This preserves backward compatibility for non-trivial
-     * compositions but loses the atomicity guarantee.
-     */
+    unsafe: () => Db<TSchema>;
     batch: (operations: Operation<unknown>[]) => Operation<unknown[]>;
     /**
      * Runs a callback inside a transaction with atomic commit-or-rollback semantics.
@@ -488,10 +135,11 @@ type Db = {
      * @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).
+     * @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) => Promise<T>) => Promise<T>;
+    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. */
@@ -502,170 +150,54 @@ type Db = {
             tables?: string[];
         }) => Promise<void>;
     };
-};
-/**
- * Builder for read queries on a single table.
- *
- * Returned by `db.query(table)`. Provides `findMany`, `findFirst`, and `paginate` methods
- * that each return an {@link Operation} with permission-aware execution.
- *
- * @example
- * ```ts
- * const builder = db.query(posts);
- *
- * // Fetch all visible posts
- * const all = await builder.findMany().run();
- *
- * // Fetch a single post
- * const post = await builder.findFirst({ where: eq(posts.id, id) }).run();
- *
- * // Paginate
- * const page = await builder.paginate(params, { orderBy: desc(posts.createdAt) }).run();
- * ```
- */
-type QueryBuilder<TTable extends DrizzleTable = DrizzleTable> = {
     /**
-     * Returns an {@link Operation} that fetches multiple rows matching the given options.
+     * Clears the per-instance `with` lookup cache so that the next query
+     * re-runs every grant lookup function.
      *
-     * The result is typed via `InferRow<TTable>`, so callers get IntelliSense on
-     * `(row) => row.title` without any cast.
+     * 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.
      *
-     * **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:
+     * 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
-     * type RecipeWithIngredients = Recipe & { ingredients: Ingredient[] };
-     * const recipes = await db
-     *   .query(recipesTable)
-     *   .findMany<RecipeWithIngredients>({ with: { ingredients: true } })
-     *   .run();
-     * // recipes is RecipeWithIngredients[], no cast needed
+     * 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
      * ```
      */
-    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: <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>` by
-     * default; pass an explicit `TRow` to claim a wider shape (e.g. when using
-     * `with: { ... }` to embed related rows).
-     */
+    clearLookupCache: () => void;
+};
+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<TRow[]>;
+    findFirst: <TConfig extends FindFirstOptions = Record<string, never>, TRow = InferQueryResult<TSchema, TTable, TConfig>>(options?: TConfig) => Operation<TRow | undefined>;
     paginate: <TRow = InferRow<TTable>>(params: CursorParams | OffsetParams, options?: PaginateOptions) => Operation<CursorPage<TRow>> | Operation<OffsetPage<TRow>>;
 };
-/**
- * Builder for insert operations on a single table.
- *
- * Returned by `db.insert(table)`. Chain `.values()` to set the row data,
- * then optionally `.returning()` to get the inserted row back.
- *
- * @example
- * ```ts
- * // Insert without returning
- * 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();
- * ```
- */
 type InsertBuilder<TTable extends DrizzleTable = DrizzleTable> = {
-    /** Specifies the column values to insert, returning an {@link InsertReturningBuilder}. */
     values: (values: Record<string, unknown>) => InsertReturningBuilder<TTable>;
 };
-/**
- * An insert {@link Operation} that optionally returns the inserted row via `.returning()`.
- *
- * Without `.returning()`, the operation resolves to `void`. With `.returning()`,
- * it resolves to the full inserted row, typed as `InferRow<TTable>`.
- */
 type InsertReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
-    /** Chains `.returning()` to get the inserted row back from D1. */
     returning: () => Operation<InferRow<TTable>>;
 };
-/**
- * Builder for update operations on a single table.
- *
- * Returned by `db.update(table)`. Chain `.set()` to specify values, then `.where()`
- * to add a condition, and optionally `.returning()` to get the updated row back.
- *
- * @example
- * ```ts
- * await db.update(posts)
- *   .set({ published: true })
- *   .where(eq(posts.id, "abc-123"))
- *   .run();
- * ```
- */
 type UpdateBuilder<TTable extends DrizzleTable = DrizzleTable> = {
-    /** Specifies the column values to update, returning an {@link UpdateWhereBuilder}. */
     set: (values: Record<string, unknown>) => UpdateWhereBuilder<TTable>;
 };
-/**
- * Intermediate builder requiring a WHERE condition before the update can execute.
- *
- * The WHERE condition is AND'd with any permission-based WHERE clauses from the user's grants.
- */
 type UpdateWhereBuilder<TTable extends DrizzleTable = DrizzleTable> = {
-    /** Specifies the WHERE condition (AND'd with permission filters at `.run()` time). */
     where: (condition: unknown) => UpdateReturningBuilder<TTable>;
 };
-/**
- * An update {@link Operation} that optionally returns the updated row via `.returning()`.
- *
- * Without `.returning()`, the operation resolves to `void`. With `.returning()`,
- * it resolves to the full updated row, typed as `InferRow<TTable>`.
- */
 type UpdateReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
-    /** Chains `.returning()` to get the updated row back from D1. */
     returning: () => Operation<InferRow<TTable>>;
 };
-/**
- * Builder for delete operations on a single table.
- *
- * Returned by `db.delete(table)`. Chain `.where()` to add a condition,
- * and optionally `.returning()` to get the deleted row back.
- *
- * @example
- * ```ts
- * await db.delete(posts).where(eq(posts.id, "abc-123")).run();
- * ```
- */
 type DeleteBuilder<TTable extends DrizzleTable = DrizzleTable> = {
-    /** Specifies the WHERE condition (AND'd with permission filters at `.run()` time). */
     where: (condition: unknown) => DeleteReturningBuilder<TTable>;
 };
-/**
- * A delete {@link Operation} that optionally returns the deleted row via `.returning()`.
- *
- * Without `.returning()`, the operation resolves to `void`. With `.returning()`,
- * it resolves to the full deleted row, typed as `InferRow<TTable>`.
- */
 type DeleteReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
-    /** Chains `.returning()` to get the deleted row back from D1. */
     returning: () => Operation<InferRow<TTable>>;
 };
 
@@ -696,7 +228,7 @@ type DeleteReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operat
  * const posts = await db.query(postsTable).findMany().run();
  * ```
  */
-declare function createDb(config: DbConfig): Db;
+declare function createDb<TSchema extends Record<string, unknown>>(config: DbConfig<TSchema>): Db<TSchema>;
 /**
  * App-level db factory configuration. The "constants" — D1 binding,
  * Drizzle schema, cache config — that don't change between requests.
@@ -704,7 +236,7 @@ declare function createDb(config: DbConfig): Db;
  * 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 = {
+type AppDbConfig<TSchema extends Record<string, unknown> = Record<string, unknown>> = {
     /**
      * The Cloudflare D1 database binding. Pass either the binding directly
      * (for tests, where the mock D1 is in scope at module load) or a
@@ -720,7 +252,7 @@ type AppDbConfig = {
      * Drizzle schema. Same shape as {@link DbConfig.schema} -- pass
      * `import * as schema from "./schema"`.
      */
-    schema: Record<string, unknown>;
+    schema: TSchema;
     /**
      * Cache configuration shared across every per-request `Db`. Defaults to
      * `{ backend: "cache-api" }` to match `createDb`. Pass `false` to opt out.
@@ -736,9 +268,9 @@ type AppDbConfig = {
  * `@cfast/core`'s `dbPlugin`, route loaders) can pass the factory around
  * without re-deriving its signature.
  */
-type AppDbFactory = (grants: Grant[], user: {
+type AppDbFactory<TSchema extends Record<string, unknown> = Record<string, never>> = (grants: Grant[], user: {
     id: string;
-} | null) => Db;
+} | null) => Db<TSchema>;
 /**
  * Consolidates the three near-identical `createDb` factories that every
  * cfast app used to define (#149):
@@ -788,7 +320,7 @@ type AppDbFactory = (grants: Grant[], user: {
  * };
  * ```
  */
-declare function createAppDb(config: AppDbConfig): AppDbFactory;
+declare function createAppDb<TSchema extends Record<string, unknown>>(config: AppDbConfig<TSchema>): AppDbFactory<TSchema>;
 
 /**
  * A function that executes a single sub-operation within a {@link compose} executor.
@@ -999,10 +531,6 @@ declare function parseCursorParams(request: Request, options?: PaginationOptions
  */
 declare function parseOffsetParams(request: Request, options?: PaginationOptions): OffsetParams;
 
-/**
- * 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);
 }
@@ -1109,6 +637,54 @@ type Seed = {
  */
 declare function defineSeed(config: SeedConfig): Seed;
 
+/**
+ * Recursively converts Date fields in a value to ISO 8601 strings for
+ * JSON serialization.
+ *
+ * React Router loaders must return JSON-serializable data. Date objects
+ * are not JSON-serializable by default -- `JSON.stringify(new Date())`
+ * calls `Date.prototype.toJSON()` which produces an ISO string, but the
+ * resulting value on the client is a string, not a Date. This helper
+ * makes the conversion explicit and type-safe so every loader doesn't
+ * need to manually call `.toISOString()` on every date field.
+ *
+ * Works on:
+ * - Plain objects (shallow and nested)
+ * - Arrays of objects
+ * - Single Date values
+ * - Nested arrays and objects of arbitrary depth
+ *
+ * Non-Date primitives (string, number, boolean, null, undefined) pass
+ * through unchanged. The function is a no-op for values that don't
+ * contain Date instances.
+ *
+ * @param value - The value to convert. Typically a query result row or
+ *   array of rows from `db.query(...).findMany().run()`.
+ * @returns A new value with every Date replaced by its ISO string.
+ *
+ * @example
+ * ```ts
+ * import { toJSON } from "@cfast/db";
+ *
+ * export async function loader({ context }) {
+ *   const db = createDb({ ... });
+ *   const posts = await db.query(postsTable).findMany().run();
+ *   return { posts: toJSON(posts) };
+ * }
+ * ```
+ */
+declare function toJSON<T>(value: T): DateToString<T>;
+/**
+ * Type-level utility that converts Date fields to string in a type.
+ *
+ * Maps `{ createdAt: Date; title: string }` to
+ * `{ createdAt: string; title: string }` so the return type of
+ * `toJSON(row)` accurately reflects the runtime shape.
+ */
+type DateToString<T> = T extends Date ? string : T extends Array<infer U> ? DateToString<U>[] : T extends Record<string, unknown> ? {
+    [K in keyof T]: DateToString<T[K]>;
+} : T;
+
 /**
  * Per-request cache that holds the resolved `with` lookup map for each grant.
  *
@@ -1157,4 +733,4 @@ declare function createLookupCache(): LookupCache;
  */
 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 };
+export { type AppDbConfig, type AppDbFactory, type CacheBackend, type CacheConfig, type CursorPage, type CursorParams, type DateToString, type Db, type DbConfig, type DeleteBuilder, type DeleteReturningBuilder, type FindFirstOptions, type FindManyOptions, type InferQueryResult, 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 TransactionResult, type Tx, type UpdateBuilder, type UpdateReturningBuilder, type UpdateWhereBuilder, compose, composeSequential, composeSequentialCallback, createAppDb, createDb, createLookupCache, defineSeed, parseCursorParams, parseOffsetParams, runWithLookupCache, toJSON };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/create-db.ts
-import { drizzle as drizzle3 } from "drizzle-orm/d1";
+import { drizzle as drizzle4 } from "drizzle-orm/d1";
 
 // src/query-builder.ts
 import { count } from "drizzle-orm";
@@ -675,6 +675,7 @@ function createCacheManager(config) {
 }
 
 // src/transaction.ts
+import { drizzle as drizzle3 } from "drizzle-orm/d1";
 var TransactionError = class extends Error {
   constructor(message) {
     super(message);
@@ -684,14 +685,10 @@ var TransactionError = class extends Error {
 function wrapWriteOperation(ctx, op) {
   const record = (toQueue) => {
     if (ctx.closed) {
-      throw new TransactionError(
-        "Cannot run an operation after the transaction has committed or aborted."
-      );
+      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."
-      );
+      throw new TransactionError("Transaction has been aborted; no further operations may run.");
     }
     ctx.pending.push({ op: toQueue });
   };
@@ -718,9 +715,7 @@ function wrapWriteOperation(ctx, op) {
 }
 function createTxHandle(db, ctx) {
   return {
-    query: (table) => {
-      return db.query(table);
-    },
+    query: (table) => db.query(table),
     insert: (table) => {
       const realBuilder = db.insert(table);
       return {
@@ -753,13 +748,11 @@ function createTxHandle(db, ctx) {
         }
       };
     },
-    transaction: (callback) => {
-      return runTransaction(db, callback, ctx);
-    }
+    transaction: (callback) => runTransaction(db, callback, ctx)
   };
 }
-async function flushWrites(db, pending) {
-  if (pending.length === 0) return;
+async function flushWritesDirect(config, isUnsafe, pending) {
+  if (pending.length === 0) return { changes: 0, writeResults: [] };
   const ops = pending.map((p) => p.op);
   for (const op of ops) {
     if (getBatchable(op) === void 0) {
@@ -768,24 +761,39 @@ async function flushWrites(db, pending) {
       );
     }
   }
-  await db.batch(ops).run({});
+  const allPermissions = deduplicateDescriptors(ops.flatMap((op) => op.permissions));
+  if (!isUnsafe) {
+    checkOperationPermissions(config.grants, allPermissions);
+  }
+  const batchables = ops.map((op) => getBatchable(op));
+  await Promise.all(batchables.map((b) => b.prepare?.() ?? Promise.resolve()));
+  const sharedDb = drizzle3(config.d1, { schema: config.schema });
+  const items = batchables.map((b) => b.build(sharedDb));
+  const batchResults = await sharedDb.batch(
+    items
+  );
+  const writeResults = batchResults.map((r) => {
+    if (r && typeof r === "object" && "meta" in r) {
+      return r;
+    }
+    return { results: [], success: true, meta: { changes: 0 } };
+  });
+  const changes = writeResults.reduce(
+    (sum, r) => sum + (r?.meta?.changes ?? 0),
+    0
+  );
+  return { changes, writeResults };
 }
-async function runTransaction(db, callback, parentCtx) {
-  if (parentCtx) {
+async function runTransaction(db, callback, parentCtxOrConfig, isUnsafe) {
+  if (parentCtxOrConfig && "pending" in parentCtxOrConfig) {
+    const parentCtx = parentCtxOrConfig;
     if (parentCtx.closed || parentCtx.aborted) {
-      throw new TransactionError(
-        "Cannot start a nested transaction: parent has already committed or aborted."
-      );
+      throw new TransactionError("Cannot start a nested transaction: parent has already committed or aborted.");
     }
-    const nestedTx = createTxHandle(db, parentCtx);
-    return callback(nestedTx);
+    return callback(createTxHandle(db, parentCtx));
   }
-  const ctx = {
-    pending: [],
-    closed: false,
-    aborted: false,
-    nested: false
-  };
+  const config = parentCtxOrConfig;
+  const ctx = { pending: [], closed: false, aborted: false, nested: false };
   const tx = createTxHandle(db, ctx);
   let result;
   try {
@@ -796,15 +804,21 @@ async function runTransaction(db, callback, parentCtx) {
     ctx.pending.length = 0;
     throw err;
   }
+  let flushResult;
   try {
-    await flushWrites(db, ctx.pending);
+    if (config) {
+      flushResult = await flushWritesDirect(config, isUnsafe ?? false, ctx.pending);
+    } else {
+      if (ctx.pending.length > 0) await db.batch(ctx.pending.map((p) => p.op)).run({});
+      flushResult = { changes: 0, writeResults: [] };
+    }
     ctx.closed = true;
   } catch (err) {
     ctx.aborted = true;
     ctx.closed = true;
     throw err;
   }
-  return result;
+  return { result, meta: { changes: flushResult.changes, writeResults: flushResult.writeResults } };
 }
 
 // src/create-db.ts
@@ -895,7 +909,7 @@ function buildDb(config, isUnsafe, lookupCache) {
           const batchables = operations.map((op) => getBatchable(op));
           const everyOpBatchable = batchables.every((b) => b !== void 0);
           if (everyOpBatchable) {
-            const sharedDb = drizzle3(config.d1, { schema: config.schema });
+            const sharedDb = drizzle4(config.d1, { schema: config.schema });
             await Promise.all(
               batchables.map((b) => b.prepare?.() ?? Promise.resolve())
             );
@@ -921,7 +935,7 @@ function buildDb(config, isUnsafe, lookupCache) {
       };
     },
     transaction(callback) {
-      return runTransaction(db, callback);
+      return runTransaction(db, callback, { d1: config.d1, schema: config.schema, grants: config.grants }, isUnsafe);
     },
     cache: {
       async invalidate(options) {
@@ -935,6 +949,9 @@ function buildDb(config, isUnsafe, lookupCache) {
           }
         }
       }
+    },
+    clearLookupCache() {
+      lookupCache.clear();
     }
   };
   return db;
@@ -1051,7 +1068,7 @@ function createTrackingDb(real, perms) {
         insert: trackingDb.insert,
         update: trackingDb.update,
         delete: trackingDb.delete,
-        transaction: (cb) => trackingDb.transaction(cb)
+        transaction: (cb) => trackingDb.transaction(cb).then((txr) => txr.result)
       };
       try {
         await callback(trackingTx);
@@ -1059,7 +1076,8 @@ function createTrackingDb(real, perms) {
       }
       return createSentinel();
     },
-    cache: real.cache
+    cache: real.cache,
+    clearLookupCache: () => real.clearLookupCache()
   };
   return trackingDb;
 }
@@ -1117,6 +1135,27 @@ function defineSeed(config) {
     }
   };
 }
+
+// src/json.ts
+function toJSON(value) {
+  return convertDates(value);
+}
+function convertDates(value) {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    return value.map(convertDates);
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = convertDates(val);
+    }
+    return result;
+  }
+  return value;
+}
 export {
   TransactionError,
   compose,
@@ -1128,5 +1167,6 @@ export {
   defineSeed,
   parseCursorParams,
   parseOffsetParams,
-  runWithLookupCache
+  runWithLookupCache,
+  toJSON
 };

package/llms.txt

@@ -58,32 +58,48 @@ 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)
+#### Auto-inferred `.with()` relations (#240)
 
 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:
+embeds the joined rows into the result. As of `@cfast/db@0.5`, the result
+type is **automatically inferred** from the schema -- no type cast needed.
+`createDb` captures the full schema type via a generic, and `findMany`/
+`findFirst` thread the `with` config through Drizzle's `BuildQueryResult`
+to compute the exact result shape including nested relations.
 
 ```typescript
-type RecipeWithIngredients = Recipe & { ingredients: Ingredient[] };
+import { createDb } from "@cfast/db";
+import * as schema from "./schema";   // includes relations()
+
+const db = createDb({ d1, schema, grants, user });
 
+// Auto-inferred -- no cast, no manual generic
 const recipes = await db
-  .query(recipesTable)
-  .findMany<RecipeWithIngredients>({ with: { ingredients: true } })
+  .query(schema.recipesTable)
+  .findMany({ with: { ingredients: true } })
   .run();
-// recipes is RecipeWithIngredients[], no cast needed.
+// recipes is { id: string; title: string; ingredients: Ingredient[] }[]
 
-const recipe = await db
+// Nested relations work too
+const plan = await db
+  .query(schema.mealPlans)
+  .findFirst({
+    with: { entries: { with: { recipe: { with: { ingredients: true } } } } },
+  })
+  .run();
+// plan.entries[0].recipe.ingredients is fully typed
+```
+
+**Manual override:** pass `<TConfig, TRow>` to override when needed:
+
+```typescript
+type Custom = Recipe & { ingredients: Ingredient[] };
+const recipes = await db
   .query(recipesTable)
-  .findFirst<RecipeWithIngredients>({
-    where: eq(recipesTable.id, id),
+  .findMany<{ with: { ingredients: true } }, Custom>({
     with: { ingredients: true },
   })
   .run();
-// recipe is RecipeWithIngredients | undefined.
 ```
 
 ### Writes
@@ -223,7 +239,7 @@ 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>
+### db.transaction(async tx => ...): Promise<TransactionResult<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
@@ -231,6 +247,14 @@ 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.
 
+Returns a `TransactionResult<T>` with:
+- `result: T` — the callback's return value
+- `meta.changes: number` — total rows affected across all writes
+- `meta.writeResults: D1Result[]` — per-statement D1 results
+
+Use `meta.changes` to detect whether a WHERE-guarded UPDATE actually matched
+any rows (the "out of stock" signal) without falling back to raw SQL.
+
 Use `db.transaction` whenever the set of writes depends on logic inside the
 callback (read-modify-write, conditional inserts, state machines):
 
@@ -238,11 +262,7 @@ callback (read-modify-write, conditional inserts, state machines):
 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 { result: order, meta } = await db.transaction(async (tx) => {
   const product = await tx.query(products).findFirst({
     where: eq(products.id, pid),
   }).run();
@@ -250,24 +270,22 @@ const order = await db.transaction(async (tx) => {
     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.
+  // Guarded decrement: relative SQL + WHERE stock >= qty.
   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 };
 });
+
+// Check if the guarded decrement actually matched any rows.
+if (meta.changes === 0) {
+  throw new Error("out of stock — concurrent decrement won");
+}
 ```
 
 **`tx` is a `Pick<Db, "query" | "insert" | "update" | "delete">`** plus a
@@ -532,6 +550,27 @@ 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.
@@ -610,6 +649,30 @@ export default defineConfig({
 });
 ```
 
+### toJSON(value): DateToString<T>
+
+Recursively converts `Date` fields to ISO 8601 strings for JSON serialization.
+React Router loaders must return JSON-serializable data; `toJSON()` makes the
+Date-to-string conversion explicit so every loader doesn't need manual
+`.toISOString()` calls.
+
+```typescript
+import { toJSON } from "@cfast/db";
+
+export async function loader({ context }) {
+  const db = createDb({ ... });
+  const posts = await db.query(postsTable).findMany().run();
+  // Date fields (createdAt, updatedAt, etc.) become ISO strings automatically.
+  return { posts: toJSON(posts) };
+}
+```
+
+The return type `DateToString<T>` maps every `Date` property to `string` at the
+type level, so the client sees accurate types without manual casting.
+
+Works on plain objects, arrays, nested structures, and single Date values.
+Non-Date primitives pass through unchanged.
+
 ## 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.4.0",
+  "version": "0.5.0",
   "description": "Permission-aware Drizzle queries for Cloudflare D1",
   "keywords": [
     "cfast",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@cfast/permissions": ">=0.3.0 <0.5.0",
+    "@cfast/permissions": ">=0.3.0 <0.6.0",
     "drizzle-orm": ">=0.35"
   },
   "peerDependenciesMeta": {
@@ -51,7 +51,7 @@
     "tsup": "^8",
     "typescript": "^5.7",
     "vitest": "^4.1.0",
-    "@cfast/permissions": "0.4.0"
+    "@cfast/permissions": "0.5.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",