@cfast/db 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,19 @@
 import { DrizzleTable, PermissionDescriptor, Grant } 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.
  *
@@ -126,8 +140,13 @@ type DbConfig = {
     /**
      * 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, DrizzleTable>;
+    schema: Record<string, unknown>;
     /** Resolved permission grants for the current user's role, from `resolveGrants()`. */
     grants: Grant[];
     /**
@@ -348,14 +367,19 @@ type PaginateOptions = {
  * ```
  */
 type Db = {
-    /** Creates a {@link QueryBuilder} for reading rows from the given table. */
-    query: (table: DrizzleTable) => QueryBuilder;
+    /**
+     * 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: (table: DrizzleTable) => InsertBuilder;
+    insert: <TTable extends DrizzleTable>(table: TTable) => InsertBuilder<TTable>;
     /** Creates an {@link UpdateBuilder} for updating rows in the given table. */
-    update: (table: DrizzleTable) => UpdateBuilder;
+    update: <TTable extends DrizzleTable>(table: TTable) => UpdateBuilder<TTable>;
     /** Creates a {@link DeleteBuilder} for deleting rows from the given table. */
-    delete: (table: DrizzleTable) => DeleteBuilder;
+    delete: <TTable extends DrizzleTable>(table: TTable) => DeleteBuilder<TTable>;
     /**
      * Returns a new `Db` instance that skips all permission checks.
      *
@@ -365,7 +389,20 @@ type Db = {
     unsafe: () => Db;
     /**
      * Groups multiple operations into a single {@link Operation} with merged, deduplicated permissions.
-     * Operations are executed sequentially (not via D1 native batch).
+     *
+     * 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[]>;
     /** Cache control methods for manual invalidation. */
@@ -399,18 +436,26 @@ type Db = {
  * const page = await builder.paginate(params, { orderBy: desc(posts.createdAt) }).run({});
  * ```
  */
-type QueryBuilder = {
-    /** Returns an {@link Operation} that fetches multiple rows matching the given options. */
-    findMany: (options?: FindManyOptions) => Operation<unknown[]>;
-    /** Returns an {@link Operation} that fetches the first matching row, or `undefined` if none match. */
-    findFirst: (options?: FindFirstOptions) => Operation<unknown | undefined>;
+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.
+     */
+    findMany: (options?: FindManyOptions) => Operation<InferRow<TTable>[]>;
+    /**
+     * Returns an {@link Operation} that fetches the first matching row, or `undefined`
+     * if none match. The row type is propagated from `TTable`.
+     */
+    findFirst: (options?: FindFirstOptions) => Operation<InferRow<TTable> | 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"`.
+     * {@link OffsetPage} for `"offset"`. Each page's items are typed as `InferRow<TTable>`.
      */
-    paginate: (params: CursorParams | OffsetParams, options?: PaginateOptions) => Operation<CursorPage<unknown>> | Operation<OffsetPage<unknown>>;
+    paginate: (params: CursorParams | OffsetParams, options?: PaginateOptions) => Operation<CursorPage<InferRow<TTable>>> | Operation<OffsetPage<InferRow<TTable>>>;
 };
 /**
  * Builder for insert operations on a single table.
@@ -430,19 +475,19 @@ type QueryBuilder = {
  *   .run({});
  * ```
  */
-type InsertBuilder = {
+type InsertBuilder<TTable extends DrizzleTable = DrizzleTable> = {
     /** Specifies the column values to insert, returning an {@link InsertReturningBuilder}. */
-    values: (values: Record<string, unknown>) => 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.
+ * it resolves to the full inserted row, typed as `InferRow<TTable>`.
  */
-type InsertReturningBuilder = Operation<void> & {
+type InsertReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
     /** Chains `.returning()` to get the inserted row back from D1. */
-    returning: () => Operation<unknown>;
+    returning: () => Operation<InferRow<TTable>>;
 };
 /**
  * Builder for update operations on a single table.
@@ -458,28 +503,28 @@ type InsertReturningBuilder = Operation<void> & {
  *   .run({});
  * ```
  */
-type UpdateBuilder = {
+type UpdateBuilder<TTable extends DrizzleTable = DrizzleTable> = {
     /** Specifies the column values to update, returning an {@link UpdateWhereBuilder}. */
-    set: (values: Record<string, unknown>) => 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 = {
+type UpdateWhereBuilder<TTable extends DrizzleTable = DrizzleTable> = {
     /** Specifies the WHERE condition (AND'd with permission filters at `.run()` time). */
-    where: (condition: unknown) => UpdateReturningBuilder;
+    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.
+ * it resolves to the full updated row, typed as `InferRow<TTable>`.
  */
-type UpdateReturningBuilder = Operation<void> & {
+type UpdateReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
     /** Chains `.returning()` to get the updated row back from D1. */
-    returning: () => Operation<unknown>;
+    returning: () => Operation<InferRow<TTable>>;
 };
 /**
  * Builder for delete operations on a single table.
@@ -492,19 +537,19 @@ type UpdateReturningBuilder = Operation<void> & {
  * await db.delete(posts).where(eq(posts.id, "abc-123")).run({});
  * ```
  */
-type DeleteBuilder = {
+type DeleteBuilder<TTable extends DrizzleTable = DrizzleTable> = {
     /** Specifies the WHERE condition (AND'd with permission filters at `.run()` time). */
-    where: (condition: unknown) => DeleteReturningBuilder;
+    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.
+ * it resolves to the full deleted row, typed as `InferRow<TTable>`.
  */
-type DeleteReturningBuilder = Operation<void> & {
+type DeleteReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
     /** Chains `.returning()` to get the deleted row back from D1. */
-    returning: () => Operation<unknown>;
+    returning: () => Operation<InferRow<TTable>>;
 };
 
 /**
@@ -600,6 +645,56 @@ declare function compose<TResult>(operations: Operation<unknown>[], executor: (.
  * @returns A single {@link Operation} that runs all operations sequentially and returns their results.
  */
 declare function composeSequential(operations: Operation<unknown>[]): Operation<unknown[]>;
+/**
+ * Sequential `compose` variant that accepts a callback for ad-hoc workflows where
+ * later operations depend on the results of earlier ones (e.g. inserting a child
+ * row that references the inserted parent's id).
+ *
+ * Permissions are still collected ahead-of-time: the callback is run twice. The
+ * first pass uses a tracking proxy that records every operation's permission
+ * descriptors and returns sentinel values from `.run()` (so `card.id` and similar
+ * accesses don't crash). The second pass runs the callback against the real Db
+ * to actually execute the queries.
+ *
+ * Because the callback runs twice, **it must be free of side effects outside of
+ * `db.*` calls** (no `fetch`, no `console.log` you care about, no global state
+ * mutation). All control flow that depends on db results should use the sentinel-
+ * tolerant property accesses.
+ *
+ * The dry-run pass is asynchronous, so `op.permissions` is empty until the dry-run
+ * resolves. Consumers that need to inspect permissions before calling `.run()` (e.g.
+ * the `@cfast/actions` permission UI) should `await op.permissionsAsync()` instead.
+ * Calling `op.run()` always awaits the dry-run internally, so permissions are
+ * guaranteed to be populated by the time the real callback runs.
+ *
+ * @typeParam TResult - The return type of the callback.
+ * @param db - The real Db that will execute the operations on the second pass.
+ * @param callback - A function that receives a Db and returns a value.
+ * @returns A single {@link Operation} whose `.permissions` is the union of every
+ *   operation discovered during the dry-run pass and whose `.run()` re-executes
+ *   the callback against the real Db. The returned object also exposes
+ *   `permissionsAsync()` for guaranteed permission retrieval.
+ *
+ * @example
+ * ```ts
+ * import { composeSequentialCallback } from "@cfast/db";
+ *
+ * const op = composeSequentialCallback(db, async (tx) => {
+ *   const card = await tx.insert(cards).values({ title: "New" }).returning().run();
+ *   await tx.insert(activityLog).values({
+ *     cardId: (card as { id: string }).id,
+ *     action: "card_created",
+ *   }).run();
+ *   return card;
+ * });
+ *
+ * await op.permissionsAsync();  // [{ create, cards }, { create, activityLog }]
+ * await op.run();
+ * ```
+ */
+declare function composeSequentialCallback<TResult>(db: Db, callback: (db: Db) => Promise<TResult>): Operation<TResult> & {
+    permissionsAsync: () => Promise<PermissionDescriptor[]>;
+};
 
 /**
  * Options for controlling default and maximum pagination limits.
@@ -654,4 +749,4 @@ 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 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, createDb, parseCursorParams, parseOffsetParams };
+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 };

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/create-db.ts
+import { drizzle as drizzle3 } from "drizzle-orm/d1";
+
 // src/query-builder.ts
 import { count } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/d1";
@@ -9,14 +12,17 @@ import {
 } from "@cfast/permissions";
 import { CRUD_ACTIONS } from "@cfast/permissions";
 function resolvePermissionFilters(grants, action, table) {
+  const targetName = getTableName(table);
   const matching = grants.filter((g) => {
     const actionMatch = g.action === action || g.action === "manage";
-    const tableMatch = g.subject === "all" || g.subject === table || typeof g.subject === "object" && getTableName(g.subject) === getTableName(table);
+    const tableMatch = g.subject === "all" || g.subject === table || getTableName(g.subject) === targetName;
     return actionMatch && tableMatch;
   });
   if (matching.length === 0) return [];
   if (matching.some((g) => !g.where)) return [];
-  return matching.filter((g) => !!g.where).map((g) => g.where);
+  return matching.filter(
+    (g) => !!g.where
+  );
 }
 function grantMatchesAction(grantAction, requiredAction) {
   if (grantAction === requiredAction) return true;
@@ -71,13 +77,38 @@ function deduplicateDescriptors(descriptors) {
   }
   return result;
 }
-function buildPermissionFilter(grants, action, table, user, unsafe) {
+function createLookupCache() {
+  return /* @__PURE__ */ new Map();
+}
+async function resolveGrantLookups(grant, user, lookupDb, cache) {
+  if (!grant.with) return {};
+  const cached = cache.get(grant);
+  if (cached) return cached;
+  const entries = Object.entries(grant.with);
+  const promise = (async () => {
+    const resolved = {};
+    await Promise.all(
+      entries.map(async ([key, fn]) => {
+        resolved[key] = await fn(user, lookupDb);
+      })
+    );
+    return resolved;
+  })();
+  cache.set(grant, promise);
+  return promise;
+}
+async function buildPermissionFilter(grants, action, table, user, unsafe, getLookupDb, cache) {
   if (unsafe || !user) return void 0;
-  const filters = resolvePermissionFilters(grants, action, table);
-  if (filters.length === 0) return void 0;
+  const matching = resolvePermissionFilters(grants, action, table);
+  if (matching.length === 0) return void 0;
   const columns = table;
-  const clauses = filters.map(
-    (fn) => fn(columns, user)
+  const needsLookupDb = matching.some((g) => g.with !== void 0);
+  const lookupDb = needsLookupDb ? getLookupDb() : void 0;
+  const lookupSets = await Promise.all(
+    matching.map((g) => resolveGrantLookups(g, user, lookupDb, cache))
+  );
+  const clauses = matching.map(
+    (g, i) => g.where(columns, user, lookupSets[i])
   );
   return or(...clauses);
 }
@@ -92,7 +123,8 @@ function makePermissions(unsafe, action, table) {
 }
 
 // src/paginate.ts
-import { and as and2, or as or2, lt, gt, eq } from "drizzle-orm";
+import { and as and2, or as or2, lt, gt, eq, getTableColumns } from "drizzle-orm";
+import { getTableConfig } from "drizzle-orm/sqlite-core";
 function parseIntParam(raw, fallback) {
   if (raw == null) return fallback;
   const n = Number(raw);
@@ -135,6 +167,23 @@ function decodeCursor(cursor) {
     return null;
   }
 }
+function getPrimaryKeyColumns(table) {
+  const tableColumns = getTableColumns(table);
+  const singleColumnPks = [];
+  for (const col of Object.values(tableColumns)) {
+    if (col.primary) {
+      singleColumnPks.push(col);
+    }
+  }
+  if (singleColumnPks.length > 0) {
+    return singleColumnPks;
+  }
+  const config = getTableConfig(table);
+  if (config.primaryKeys.length > 0) {
+    return config.primaryKeys[0].columns;
+  }
+  return [];
+}
 function buildCursorWhere(cursorColumns, cursorValues, direction = "desc") {
   const compare = direction === "desc" ? lt : gt;
   if (cursorColumns.length === 1) {
@@ -170,12 +219,14 @@ function buildQueryOperation(config, db, tableKey, method, options) {
       if (!config.unsafe) {
         checkOperationPermissions(config.grants, permissions);
       }
-      const permFilter = buildPermissionFilter(
+      const permFilter = await buildPermissionFilter(
         config.grants,
         "read",
         config.table,
         config.user,
-        config.unsafe
+        config.unsafe,
+        config.getLookupDb,
+        config.lookupCache
       );
       const userWhere = options?.where;
       const combinedWhere = combineWhere(userWhere, permFilter);
@@ -222,16 +273,18 @@ function createQueryBuilder(config) {
         if (!tableKey) throw new Error("Table not found in schema");
         return tableKey;
       }
-      function checkAndBuildWhere(extraWhere) {
+      async function checkAndBuildWhere(extraWhere) {
         if (!config.unsafe) {
           checkOperationPermissions(config.grants, permissions);
         }
-        const permFilter = buildPermissionFilter(
+        const permFilter = await buildPermissionFilter(
           config.grants,
           "read",
           config.table,
           config.user,
-          config.unsafe
+          config.unsafe,
+          config.getLookupDb,
+          config.lookupCache
         );
         return combineWhere(
           combineWhere(options?.where, permFilter),
@@ -247,7 +300,13 @@ function createQueryBuilder(config) {
         return qo;
       }
       if (params.type === "cursor") {
-        const cursorColumns = options?.cursorColumns ?? [];
+        const explicitCursorColumns = options?.cursorColumns;
+        const cursorColumns = explicitCursorColumns && explicitCursorColumns.length > 0 ? explicitCursorColumns : getPrimaryKeyColumns(config.table);
+        if (cursorColumns.length === 0) {
+          throw new Error(
+            "paginate(): cursor pagination requires either explicit `cursorColumns` or a table with a primary key. Pass `cursorColumns` in the paginate options."
+          );
+        }
         return {
           permissions,
           async run(_params) {
@@ -255,7 +314,7 @@ function createQueryBuilder(config) {
             const cursorValues = decodeCursor(params.cursor);
             const direction = options?.orderDirection ?? "desc";
             const cursorWhere = cursorValues ? buildCursorWhere(cursorColumns, cursorValues, direction) : void 0;
-            const combinedWhere = checkAndBuildWhere(cursorWhere);
+            const combinedWhere = await checkAndBuildWhere(cursorWhere);
             const queryOptions = buildBaseQueryOptions(combinedWhere);
             queryOptions.limit = params.limit + 1;
             const queryTable = getQueryTable(db, key);
@@ -276,7 +335,7 @@ function createQueryBuilder(config) {
         permissions,
         async run(_params) {
           const key = ensureTableKey();
-          const combinedWhere = checkAndBuildWhere();
+          const combinedWhere = await checkAndBuildWhere();
           const queryOptions = buildBaseQueryOptions(combinedWhere);
           queryOptions.limit = params.limit;
           queryOptions.offset = (params.page - 1) * params.limit;
@@ -302,99 +361,185 @@ function createQueryBuilder(config) {
 
 // src/mutate-builder.ts
 import { drizzle as drizzle2 } from "drizzle-orm/d1";
+
+// src/batchable.ts
+var BATCHABLE = /* @__PURE__ */ Symbol.for("@cfast/db/batchable");
+function getBatchable(op) {
+  if (op === null || typeof op !== "object") return void 0;
+  const meta = op[BATCHABLE];
+  return meta;
+}
+
+// src/mutate-builder.ts
 function checkIfNeeded(config, grants, permissions) {
   if (!config.unsafe) {
     checkOperationPermissions(grants, permissions);
   }
 }
-function buildMutationWithReturning(config, permissions, tableName, execute) {
-  return {
+function buildMutationWithReturning(config, permissions, tableName, buildQuery, prepareFn) {
+  const drizzleDb = drizzle2(config.d1, { schema: config.schema });
+  const runOnce = async (returning) => {
+    checkIfNeeded(config, config.grants, permissions);
+    if (prepareFn) await prepareFn();
+    const built = buildQuery(drizzleDb, returning);
+    const result = await built.execute(returning);
+    config.onMutate?.(tableName);
+    return result;
+  };
+  const baseOp = {
     permissions,
     async run(_params) {
-      checkIfNeeded(config, config.grants, permissions);
-      await execute(false);
-      config.onMutate?.(tableName);
+      await runOnce(false);
     },
     returning() {
-      return {
+      const returningOp = {
         permissions,
         async run(_params) {
-          checkIfNeeded(config, config.grants, permissions);
-          const result = await execute(true);
-          config.onMutate?.(tableName);
-          return result;
+          return runOnce(true);
         }
       };
+      returningOp[BATCHABLE] = {
+        prepare: prepareFn,
+        build: (sharedDb) => buildQuery(sharedDb, true).query,
+        tableName,
+        withResult: true
+      };
+      return returningOp;
     }
   };
+  baseOp[BATCHABLE] = {
+    prepare: prepareFn,
+    build: (sharedDb) => buildQuery(sharedDb, false).query,
+    tableName,
+    withResult: false
+  };
+  return baseOp;
 }
 function createInsertBuilder(config) {
-  const db = drizzle2(config.d1, { schema: config.schema });
   const permissions = makePermissions(config.unsafe, "create", config.table);
   const tableName = getTableName2(config.table);
   return {
     values(values) {
-      return buildMutationWithReturning(config, permissions, tableName, async (returning) => {
-        const query = db.insert(config.table).values(values);
-        if (returning) {
-          return query.returning().get();
-        }
-        await query.run();
-      });
+      const buildQuery = (sharedDb, returning) => {
+        const base = sharedDb.insert(config.table).values(values);
+        const query = returning ? base.returning() : base;
+        return {
+          query,
+          execute: async (wantsResult) => {
+            if (wantsResult) {
+              return query.get();
+            }
+            await base.run();
+          }
+        };
+      };
+      return buildMutationWithReturning(config, permissions, tableName, buildQuery);
     }
   };
 }
 function createUpdateBuilder(config) {
-  const db = drizzle2(config.d1, { schema: config.schema });
   const permissions = makePermissions(config.unsafe, "update", config.table);
   const tableName = getTableName2(config.table);
   return {
     set(values) {
       return {
         where(condition) {
-          const permFilter = buildPermissionFilter(
-            config.grants,
-            "update",
-            config.table,
-            config.user,
-            config.unsafe
-          );
-          const combinedWhere = combineWhere(condition, permFilter);
-          return buildMutationWithReturning(config, permissions, tableName, async (returning) => {
-            const query = db.update(config.table).set(values);
-            if (combinedWhere) query.where(combinedWhere);
-            if (returning) {
-              return query.returning().get();
+          let resolvedCombinedWhere;
+          let preparePromise;
+          const prepareFn = () => {
+            if (!preparePromise) {
+              preparePromise = (async () => {
+                const permFilter = await buildPermissionFilter(
+                  config.grants,
+                  "update",
+                  config.table,
+                  config.user,
+                  config.unsafe,
+                  config.getLookupDb,
+                  config.lookupCache
+                );
+                resolvedCombinedWhere = combineWhere(
+                  condition,
+                  permFilter
+                );
+              })();
             }
-            await query.run();
-          });
+            return preparePromise;
+          };
+          const buildQuery = (sharedDb, returning) => {
+            const base = sharedDb.update(config.table).set(values);
+            if (resolvedCombinedWhere) base.where(resolvedCombinedWhere);
+            const query = returning ? base.returning() : base;
+            return {
+              query,
+              execute: async (wantsResult) => {
+                if (wantsResult) {
+                  return query.get();
+                }
+                await base.run();
+              }
+            };
+          };
+          return buildMutationWithReturning(
+            config,
+            permissions,
+            tableName,
+            buildQuery,
+            prepareFn
+          );
         }
       };
     }
   };
 }
 function createDeleteBuilder(config) {
-  const db = drizzle2(config.d1, { schema: config.schema });
   const permissions = makePermissions(config.unsafe, "delete", config.table);
   const tableName = getTableName2(config.table);
   return {
     where(condition) {
-      const permFilter = buildPermissionFilter(
-        config.grants,
-        "delete",
-        config.table,
-        config.user,
-        config.unsafe
-      );
-      const combinedWhere = combineWhere(condition, permFilter);
-      return buildMutationWithReturning(config, permissions, tableName, async (returning) => {
-        const query = db.delete(config.table);
-        if (combinedWhere) query.where(combinedWhere);
-        if (returning) {
-          return query.returning().get();
+      let resolvedCombinedWhere;
+      let preparePromise;
+      const prepareFn = () => {
+        if (!preparePromise) {
+          preparePromise = (async () => {
+            const permFilter = await buildPermissionFilter(
+              config.grants,
+              "delete",
+              config.table,
+              config.user,
+              config.unsafe,
+              config.getLookupDb,
+              config.lookupCache
+            );
+            resolvedCombinedWhere = combineWhere(
+              condition,
+              permFilter
+            );
+          })();
         }
-        await query.run();
-      });
+        return preparePromise;
+      };
+      const buildQuery = (sharedDb, returning) => {
+        const base = sharedDb.delete(config.table);
+        if (resolvedCombinedWhere) base.where(resolvedCombinedWhere);
+        const query = returning ? base.returning() : base;
+        return {
+          query,
+          execute: async (wantsResult) => {
+            if (wantsResult) {
+              return query.get();
+            }
+            await base.run();
+          }
+        };
+      };
+      return buildMutationWithReturning(
+        config,
+        permissions,
+        tableName,
+        buildQuery,
+        prepareFn
+      );
     }
   };
 }
@@ -522,14 +667,21 @@ function createCacheManager(config) {
 
 // src/create-db.ts
 function createDb(config) {
-  return buildDb(config, false);
+  const lookupCache = createLookupCache();
+  return buildDb(config, false, lookupCache);
 }
-function buildDb(config, isUnsafe) {
+function buildDb(config, isUnsafe, lookupCache) {
   const cacheManager = config.cache === false ? null : createCacheManager(config.cache ?? { backend: "cache-api" });
   const onMutate = (tableName) => {
     cacheManager?.invalidateTable(tableName);
   };
-  return {
+  let lookupDbCache = null;
+  const getLookupDb = () => {
+    if (lookupDbCache) return lookupDbCache;
+    lookupDbCache = isUnsafe ? db : buildDb(config, true, lookupCache);
+    return lookupDbCache;
+  };
+  const db = {
     query(table) {
       return createQueryBuilder({
         d1: config.d1,
@@ -537,7 +689,9 @@ function buildDb(config, isUnsafe) {
         grants: config.grants,
         user: config.user,
         table,
-        unsafe: isUnsafe
+        unsafe: isUnsafe,
+        lookupCache,
+        getLookupDb
       });
     },
     insert(table) {
@@ -548,7 +702,9 @@ function buildDb(config, isUnsafe) {
         user: config.user,
         table,
         unsafe: isUnsafe,
-        onMutate
+        onMutate,
+        lookupCache,
+        getLookupDb
       });
     },
     update(table) {
@@ -559,7 +715,9 @@ function buildDb(config, isUnsafe) {
         user: config.user,
         table,
         unsafe: isUnsafe,
-        onMutate
+        onMutate,
+        lookupCache,
+        getLookupDb
       });
     },
     delete(table) {
@@ -570,11 +728,13 @@ function buildDb(config, isUnsafe) {
         user: config.user,
         table,
         unsafe: isUnsafe,
-        onMutate
+        onMutate,
+        lookupCache,
+        getLookupDb
       });
     },
     unsafe() {
-      return buildDb(config, true);
+      return buildDb(config, true, lookupCache);
     },
     batch(operations) {
       const allPermissions = deduplicateDescriptors(
@@ -584,6 +744,29 @@ function buildDb(config, isUnsafe) {
         permissions: allPermissions,
         async run(params) {
           const p = params ?? {};
+          if (!isUnsafe) {
+            checkOperationPermissions(config.grants, allPermissions);
+          }
+          const batchables = operations.map((op) => getBatchable(op));
+          const everyOpBatchable = operations.length > 0 && batchables.every((b) => b !== void 0);
+          if (everyOpBatchable) {
+            const sharedDb = drizzle3(config.d1, { schema: config.schema });
+            await Promise.all(
+              batchables.map((b) => b.prepare?.() ?? Promise.resolve())
+            );
+            const items = batchables.map((b) => b.build(sharedDb));
+            const batchResults = await sharedDb.batch(
+              items
+            );
+            const tables = /* @__PURE__ */ new Set();
+            for (const b of batchables) {
+              tables.add(b.tableName);
+            }
+            for (const t of tables) {
+              cacheManager?.invalidateTable(t);
+            }
+            return batchables.map((b, i) => b.withResult ? batchResults[i] : void 0);
+          }
           const results = [];
           for (const op of operations) {
             results.push(await op.run(p));
@@ -606,6 +789,7 @@ function buildDb(config, isUnsafe) {
       }
     }
   };
+  return db;
 }
 
 // src/compose.ts
@@ -636,9 +820,101 @@ function composeSequential(operations) {
     }
   };
 }
+function createSentinel() {
+  const target = function() {
+  };
+  return new Proxy(target, {
+    get(_t, prop) {
+      if (prop === "then") return void 0;
+      if (prop === Symbol.toPrimitive) return () => "[sentinel]";
+      if (prop === "toString") return () => "[sentinel]";
+      if (prop === "valueOf") return () => 0;
+      return createSentinel();
+    },
+    apply() {
+      return createSentinel();
+    }
+  });
+}
+function wrapForTracking(target, perms) {
+  return new Proxy(target, {
+    get(t, prop, receiver) {
+      const orig = Reflect.get(t, prop, receiver);
+      if (prop === "permissions") return orig;
+      if (prop === "run" && typeof orig === "function") {
+        return async () => {
+          const opPerms = t.permissions;
+          if (Array.isArray(opPerms)) {
+            perms.push(...opPerms);
+          }
+          return createSentinel();
+        };
+      }
+      if (typeof orig === "function") {
+        return (...args) => {
+          const result = orig.apply(t, args);
+          if (result && typeof result === "object") {
+            return wrapForTracking(result, perms);
+          }
+          return result;
+        };
+      }
+      return orig;
+    }
+  });
+}
+function createTrackingDb(real, perms) {
+  return {
+    query: (table) => wrapForTracking(real.query(table), perms),
+    insert: (table) => wrapForTracking(real.insert(table), perms),
+    update: (table) => wrapForTracking(real.update(table), perms),
+    delete: (table) => wrapForTracking(real.delete(table), perms),
+    unsafe: () => createTrackingDb(real.unsafe(), perms),
+    batch: (operations) => {
+      for (const op of operations) {
+        perms.push(...op.permissions);
+      }
+      return {
+        permissions: deduplicateDescriptors(operations.flatMap((op) => op.permissions)),
+        async run() {
+          return [createSentinel()];
+        }
+      };
+    },
+    cache: real.cache
+  };
+}
+function composeSequentialCallback(db, callback) {
+  const collected = [];
+  const trackingDb = createTrackingDb(db, collected);
+  const dryRunPromise = (async () => {
+    try {
+      await callback(trackingDb);
+    } catch {
+    }
+  })();
+  const permissions = [];
+  const populated = dryRunPromise.then(() => {
+    for (const d of deduplicateDescriptors(collected)) {
+      permissions.push(d);
+    }
+  });
+  return {
+    permissions,
+    async permissionsAsync() {
+      await populated;
+      return permissions;
+    },
+    async run(_params) {
+      await populated;
+      return callback(db);
+    }
+  };
+}
 export {
   compose,
   composeSequential,
+  composeSequentialCallback,
   createDb,
   parseCursorParams,
   parseOffsetParams

package/llms.txt

@@ -10,8 +10,9 @@ Use `@cfast/db` whenever you need to read or write a D1 database in a cfast app.
 
 - **Operations are lazy.** Every `db.query/insert/update/delete` call returns an `Operation<TResult>` with `.permissions` (inspectable immediately) and `.run(params)` (executes with permission checks). Nothing touches D1 until you call `.run()`.
 - **Permission checks are structural.** `.run()` always checks the user's grants before executing SQL. Row-level WHERE clauses from grants are injected automatically.
-- **One Db per request.** `createDb()` captures the user at creation time. Never share a `Db` across requests.
-- **`db.unsafe()` is the only escape hatch.** Returns a `Db` that skips all permission checks. Greppable via `git grep '.unsafe()'`.
+- **Cross-table grants run prerequisite lookups.** When a grant declares a `with` map (see `@cfast/permissions`), `@cfast/db` resolves those lookups against an unsafe-mode handle **before** running the main query, caches the results for the lifetime of the per-request `Db`, and threads them into the `where` clause as its third argument. A single lookup runs at most once per request even across many queries.
+- **One Db per request.** `createDb()` captures the user at creation time. Never share a `Db` across requests. The per-request grant lookup cache lives on the `Db` instance, so creating a fresh one each request gives every request a fresh cache.
+- **`db.unsafe()` is the only escape hatch.** Returns a `Db` that skips all permission checks. Greppable via `git grep '.unsafe()'`. The unsafe sibling shares the per-request lookup cache so lookups dispatched through it (the `LookupDb` passed to grant `with` functions) never duplicate work.
 
 ## API Reference
 
@@ -23,13 +24,17 @@ import * as schema from "./schema";   // must be `import *`
 
 const db = createDb({
   d1: D1Database,                      // env.DB
-  schema: Record<string, DrizzleTable>,
+  schema,                              // typeof import("./schema") -- no cast needed
   grants: Grant[],                     // from resolveGrants(permissions, roles)
   user: { id: string } | null,        // null = anonymous
   cache?: CacheConfig | false,         // default: { backend: "cache-api" }
 });
 ```
 
+`schema` is typed as `Record<string, unknown>` so you can pass `import * as schema`
+directly even when the module also exports Drizzle `relations()`. Non-table entries
+are ignored at runtime when looking up tables by key.
+
 ### Operation<TResult>
 
 ```typescript
@@ -60,6 +65,24 @@ db.delete(table).where(cond): DeleteReturningBuilder
 
 All write builders are `Operation<void>` with an optional `.returning()` that changes return type.
 
+#### Single-op shorthand (no compose required)
+
+For a single mutation, call `.run()` directly on the Operation -- there's no need to wrap
+it in `compose()` or `db.batch()`. Reserve those for multi-op workflows.
+
+```typescript
+// Insert
+const card = await db.insert(cards).values({ title: "New" }).returning().run();
+
+// Update
+await db.update(cards).set({ archived: true }).where(eq(cards.id, id)).run();
+
+// Delete
+await db.delete(cards).where(eq(cards.id, id)).run();
+```
+
+`.run()` arguments are optional -- only pass `params` when your query uses `sql.placeholder()`.
+
 ### compose(operations, executor): Operation<TResult>
 
 ```typescript
@@ -89,9 +112,70 @@ await op.run();  // runs operations in order, returns results array
 
 Runs operations in order, returns results array. Shorthand for `compose` when there are no data dependencies between operations.
 
+### composeSequentialCallback(db, callback): Operation<TResult>
+
+For workflows where later operations depend on the **results** of earlier ones
+(e.g. inserting a child row that references the inserted parent's id):
+
+```typescript
+import { composeSequentialCallback } from "@cfast/db";
+
+const op = composeSequentialCallback(db, async (tx) => {
+  const card = await tx.insert(cards).values({ title: "New" }).returning().run();
+  await tx.insert(activityLog).values({
+    cardId: (card as { id: string }).id,
+    action: "card_created",
+  }).run();
+  return card;
+});
+
+await op.permissionsAsync();  // [{ create, cards }, { create, activityLog }]
+await op.run();
+```
+
+The callback runs **twice**: first against a tracking proxy that records each
+operation's permission descriptors and returns sentinel values from `.run()`,
+then against the real db. Because of the dry-run pass, the callback **must be
+free of side effects outside of `db.*` calls** (no `fetch`, no global state
+mutation, no `console.log` you care about).
+
+`op.permissions` is populated asynchronously after the dry-run resolves; use
+`op.permissionsAsync()` for a guaranteed-populated array. `op.run()` always
+awaits the dry-run internally, so permissions are checked on every sub-op.
+
+Use this only when you actually need data dependencies. For independent
+operations, prefer `composeSequential([...])` (faster, fully synchronous
+permissions).
+
 ### db.batch(operations): Operation<unknown[]>
 
-Runs operations sequentially with merged permissions. Not D1 native batch.
+Runs multiple operations with merged, deduplicated permissions. **Atomic** when
+every operation was produced by `db.insert/update/delete`: the batch is sent to
+D1's native `batch()` API, which executes the statements as a single transaction
+and rolls everything back if any statement fails.
+
+Use this whenever you need transactional safety -- for example, decrementing
+stock across multiple products during checkout, or inserting an order plus its
+line items together:
+
+```typescript
+// Atomic checkout: stock decrements + order creation either all succeed or
+// all roll back. Permissions for every sub-op are checked upfront.
+await db.batch([
+  db.update(products).set({ stock: sql`stock - 1` }).where(eq(products.id, id1)),
+  db.update(products).set({ stock: sql`stock - 1` }).where(eq(products.id, id2)),
+  db.insert(orders).values({ userId, items: [...] }),
+]).run();
+```
+
+Permission checks happen **before** any SQL is issued. If the user lacks any
+required grant, the batch throws and zero statements run.
+
+Operations produced by `compose()`/`composeSequential()` executors don't carry
+the batchable hook; mixing them into `db.batch([...])` causes a fallback to
+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.unsafe(): Db
 
@@ -171,12 +255,76 @@ export async function action({ context, request }) {
 }
 ```
 
+### Cross-table grants ("show recipes from my friends")
+
+When a row-level filter needs data from another table, declare a `with` map on the grant. `@cfast/db` resolves every prerequisite once per request and threads the result into the `where` clause:
+
+```typescript
+// permissions.ts
+export const permissions = definePermissions<AppUser, typeof schema>()({
+  roles: ["user"] as const,
+  grants: (g) => ({
+    user: [
+      g("read", recipes, {
+        with: {
+          friendIds: async (user, db) => {
+            const rows = await db
+              .query(friendGrants)
+              .findMany({ where: eq(friendGrants.grantee, user.id) })
+              .run();
+            return (rows as { target: string }[]).map((r) => r.target);
+          },
+        },
+        where: (recipe, user, { friendIds }) =>
+          or(
+            eq(recipe.visibility, "public"),
+            eq(recipe.authorId, user.id),
+            inArray(recipe.authorId, friendIds as string[]),
+          ),
+      }),
+    ],
+  }),
+});
+
+// loader.ts -- one createDb() per request, one friend-grant fetch per request
+export async function loader({ context, request }) {
+  const { user, grants } = await auth.requireUser(request);
+  const db = createDb({ d1: context.env.DB, schema, grants, user });
+
+  // Both reads share the cached friendIds lookup -- it runs once total.
+  const myRecipes = await db.query(recipes).findMany({ limit: 10 }).run();
+  const popular = await db.query(recipes).paginate(params).run();
+
+  return { myRecipes, popular };
+}
+```
+
 ## Integration
 
 - **@cfast/permissions** -- `grants` come from `resolveGrants(permissions, user.roles)`. Permission WHERE clauses are defined via `grant()` in your permissions config.
 - **@cfast/auth** -- `auth.requireUser(request)` returns `{ user, grants }` which you pass directly to `createDb()`.
 - **@cfast/actions** -- Actions define operations using `@cfast/db`. The framework extracts `.permissions` for client-side UI adaptation.
 
+## Schema Gotchas
+
+### Self-referential foreign keys
+
+Drizzle cannot infer the return type of a `references()` callback that points at the same table. Without an explicit annotation, TypeScript fails with `TS7022: ... implicitly has type 'any'`. Annotate the callback with `AnySQLiteColumn`:
+
+```typescript
+import { sqliteTable, text, type AnySQLiteColumn } from "drizzle-orm/sqlite-core";
+
+export const folders = sqliteTable("folders", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  parentFolderId: text("parent_folder_id").references(
+    (): AnySQLiteColumn => folders.id,
+  ),
+});
+```
+
+Use `AnyPgColumn` / `AnyMySqlColumn` for other dialects. The same pattern applies to any self-reference (comment threads, org charts, category trees).
+
 ## Common Mistakes
 
 - **Forgetting `.run()`** -- Operations are lazy. `db.query(t).findMany()` returns an Operation, not results. You must call `.run()`.
@@ -184,6 +332,7 @@ export async function action({ context, request }) {
 - **Using `import { posts }` instead of `import * as schema`** -- The `schema` config must be `import *` so Drizzle's relational API can look up tables by key name.
 - **Using `db.unsafe()` for admin endpoints** -- Use a role with `grant("manage", "all")` instead. Reserve `unsafe()` for genuinely user-less contexts (cron, migrations).
 - **Expecting relational `with` to have permission filters** -- Permission WHERE clauses only apply to the root table, not joined relations.
+- **Self-referential FK without `AnySQLiteColumn` annotation** -- TypeScript fails with TS7022. See "Schema Gotchas" above.
 
 ## See Also
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/db",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Permission-aware Drizzle queries for Cloudflare D1",
   "keywords": [
     "cfast",
@@ -37,7 +37,7 @@
     "drizzle-orm": ">=0.35"
   },
   "dependencies": {
-    "@cfast/permissions": "0.1.0"
+    "@cfast/permissions": "0.3.0"
   },
   "peerDependenciesMeta": {
     "@cloudflare/workers-types": {