@cfast/db 0.4.1 → 0.6.0

package/dist/index.d.ts

@@ -1,696 +1,7 @@
-import { Grant, DrizzleTable, PermissionDescriptor } from '@cfast/permissions';
-
-/**
- * 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();
- * ```
- */
-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`. */
-    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()`. */
-    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.
-     */
-    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.
- *
- * 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. */
-    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.
-     */
-    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. */
-        invalidate: (options: {
-            /** Tag names to invalidate (from {@link QueryCacheOptions} `tags`). */
-            tags?: string[];
-            /** Table names to invalidate (bumps their version counters). */
-            tables?: string[];
-        }) => Promise<void>;
-    };
-    /**
-     * Clears the per-instance `with` lookup cache so that the next query
-     * re-runs every grant lookup function.
-     *
-     * In production this is rarely needed because each request gets a fresh
-     * `Db` via `createDb()`. In tests that reuse a single `Db` across grant
-     * mutations (e.g. inserting a new friendship and then querying recipes),
-     * call this after the mutation to avoid stale lookup results.
-     *
-     * For finer-grained control, wrap each logical request in
-     * {@link runWithLookupCache} instead -- that scopes the cache via
-     * `AsyncLocalStorage` so it is automatically discarded at scope exit.
-     *
-     * @example
-     * ```ts
-     * const db = createDb({ ... });
-     * await db.query(recipes).findMany().run(); // populates lookup cache
-     * await db.insert(friendGrants).values({ ... }).run(); // adds new grant
-     * db.clearLookupCache(); // drop stale lookups
-     * await db.query(recipes).findMany().run(); // sees new grant
-     * ```
-     */
-    clearLookupCache: () => void;
-};
-/**
- * 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.
-     *
-     * 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: <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).
-     */
-    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>>;
-};
+import { Grant, PermissionDescriptor } from '@cfast/permissions';
+import { D as DbConfig, a as Db, O as Operation, C as CursorParams, b as OffsetParams } from './types-FUFR36h1.js';
+export { c as CacheBackend, d as CacheConfig, e as CursorPage, f as DeleteBuilder, g as DeleteReturningBuilder, F as FindFirstOptions, h as FindManyOptions, I as InferQueryResult, i as InferRow, j as InsertBuilder, k as InsertReturningBuilder, l as OffsetPage, P as PaginateOptions, m as PaginateParams, Q as QueryBuilder, n as QueryCacheOptions, T as TransactionResult, o as Tx, U as UpdateBuilder, p as UpdateReturningBuilder, q as UpdateWhereBuilder, W as WithCan } from './types-FUFR36h1.js';
+import 'drizzle-orm';
 
 /**
  * Creates a permission-aware database instance bound to the given user.
@@ -719,7 +30,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.
@@ -727,7 +38,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
@@ -743,7 +54,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.
@@ -759,9 +70,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):
@@ -811,7 +122,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.
@@ -1022,115 +333,57 @@ 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);
 }
 
 /**
- * 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.
+ * Recursively converts Date fields in a value to ISO 8601 strings for
+ * JSON serialization.
  *
- * @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}.
+ * 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.
  *
- * 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.
+ * Works on:
+ * - Plain objects (shallow and nested)
+ * - Arrays of objects
+ * - Single Date values
+ * - Nested arrays and objects of arbitrary depth
  *
- * 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.
+ * 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
- * // 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" },
- *       ],
- *     },
- *   ],
- * });
+ * import { toJSON } from "@cfast/db";
  *
- * // In a worker/runner that already has a real D1 binding:
- * const db = createDb({ d1, schema, grants: [], user: null });
- * await seed.run(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.
  *
- * @param config - The {@link SeedConfig} with the ordered list of entries.
- * @returns A {@link Seed} with a `.run(db)` executor.
+ * Maps `{ createdAt: Date; title: string }` to
+ * `{ createdAt: string; title: string }` so the return type of
+ * `toJSON(row)` accurately reflects the runtime shape.
  */
-declare function defineSeed(config: SeedConfig): Seed;
+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.
@@ -1180,4 +433,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, CursorParams, type DateToString, Db, DbConfig, type LookupCache, OffsetParams, Operation, TransactionError, compose, composeSequential, composeSequentialCallback, createAppDb, createDb, createLookupCache, parseCursorParams, parseOffsetParams, runWithLookupCache, toJSON };