@cfast/db 0.2.0 → 0.3.0

package/dist/index.js

@@ -12,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;
@@ -74,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);
 }
@@ -191,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);
@@ -243,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),
@@ -282,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);
@@ -303,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;
@@ -344,10 +376,11 @@ function checkIfNeeded(config, grants, permissions) {
     checkOperationPermissions(grants, permissions);
   }
 }
-function buildMutationWithReturning(config, permissions, tableName, buildQuery) {
+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);
@@ -366,6 +399,7 @@ function buildMutationWithReturning(config, permissions, tableName, buildQuery)
         }
       };
       returningOp[BATCHABLE] = {
+        prepare: prepareFn,
         build: (sharedDb) => buildQuery(sharedDb, true).query,
         tableName,
         withResult: true
@@ -374,6 +408,7 @@ function buildMutationWithReturning(config, permissions, tableName, buildQuery)
     }
   };
   baseOp[BATCHABLE] = {
+    prepare: prepareFn,
     build: (sharedDb) => buildQuery(sharedDb, false).query,
     tableName,
     withResult: false
@@ -409,17 +444,31 @@ function createUpdateBuilder(config) {
     set(values) {
       return {
         where(condition) {
-          const permFilter = buildPermissionFilter(
-            config.grants,
-            "update",
-            config.table,
-            config.user,
-            config.unsafe
-          );
-          const combinedWhere = combineWhere(condition, permFilter);
+          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
+                );
+              })();
+            }
+            return preparePromise;
+          };
           const buildQuery = (sharedDb, returning) => {
             const base = sharedDb.update(config.table).set(values);
-            if (combinedWhere) base.where(combinedWhere);
+            if (resolvedCombinedWhere) base.where(resolvedCombinedWhere);
             const query = returning ? base.returning() : base;
             return {
               query,
@@ -431,7 +480,13 @@ function createUpdateBuilder(config) {
               }
             };
           };
-          return buildMutationWithReturning(config, permissions, tableName, buildQuery);
+          return buildMutationWithReturning(
+            config,
+            permissions,
+            tableName,
+            buildQuery,
+            prepareFn
+          );
         }
       };
     }
@@ -442,17 +497,31 @@ function createDeleteBuilder(config) {
   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);
+      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
+            );
+          })();
+        }
+        return preparePromise;
+      };
       const buildQuery = (sharedDb, returning) => {
         const base = sharedDb.delete(config.table);
-        if (combinedWhere) base.where(combinedWhere);
+        if (resolvedCombinedWhere) base.where(resolvedCombinedWhere);
         const query = returning ? base.returning() : base;
         return {
           query,
@@ -464,7 +533,13 @@ function createDeleteBuilder(config) {
           }
         };
       };
-      return buildMutationWithReturning(config, permissions, tableName, buildQuery);
+      return buildMutationWithReturning(
+        config,
+        permissions,
+        tableName,
+        buildQuery,
+        prepareFn
+      );
     }
   };
 }
@@ -592,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,
@@ -607,7 +689,9 @@ function buildDb(config, isUnsafe) {
         grants: config.grants,
         user: config.user,
         table,
-        unsafe: isUnsafe
+        unsafe: isUnsafe,
+        lookupCache,
+        getLookupDb
       });
     },
     insert(table) {
@@ -618,7 +702,9 @@ function buildDb(config, isUnsafe) {
         user: config.user,
         table,
         unsafe: isUnsafe,
-        onMutate
+        onMutate,
+        lookupCache,
+        getLookupDb
       });
     },
     update(table) {
@@ -629,7 +715,9 @@ function buildDb(config, isUnsafe) {
         user: config.user,
         table,
         unsafe: isUnsafe,
-        onMutate
+        onMutate,
+        lookupCache,
+        getLookupDb
       });
     },
     delete(table) {
@@ -640,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(
@@ -661,6 +751,9 @@ function buildDb(config, isUnsafe) {
           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
@@ -696,6 +789,7 @@ function buildDb(config, isUnsafe) {
       }
     }
   };
+  return db;
 }
 
 // src/compose.ts

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
 
@@ -254,6 +255,50 @@ 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfast/db",
-  "version": "0.2.0",
+  "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.2.0"
+    "@cfast/permissions": "0.3.0"
   },
   "peerDependenciesMeta": {
     "@cloudflare/workers-types": {