@cfast/db 0.1.1 → 0.2.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";
@@ -92,7 +95,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 +139,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) {
@@ -247,7 +268,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) {
@@ -302,50 +329,80 @@ 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) {
+  const drizzleDb = drizzle2(config.d1, { schema: config.schema });
+  const runOnce = async (returning) => {
+    checkIfNeeded(config, config.grants, permissions);
+    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] = {
+        build: (sharedDb) => buildQuery(sharedDb, true).query,
+        tableName,
+        withResult: true
+      };
+      return returningOp;
     }
   };
+  baseOp[BATCHABLE] = {
+    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 {
@@ -360,21 +417,27 @@ function createUpdateBuilder(config) {
             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();
-            }
-            await query.run();
-          });
+          const buildQuery = (sharedDb, returning) => {
+            const base = sharedDb.update(config.table).set(values);
+            if (combinedWhere) base.where(combinedWhere);
+            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 createDeleteBuilder(config) {
-  const db = drizzle2(config.d1, { schema: config.schema });
   const permissions = makePermissions(config.unsafe, "delete", config.table);
   const tableName = getTableName2(config.table);
   return {
@@ -387,14 +450,21 @@ function createDeleteBuilder(config) {
         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();
-        }
-        await query.run();
-      });
+      const buildQuery = (sharedDb, returning) => {
+        const base = sharedDb.delete(config.table);
+        if (combinedWhere) base.where(combinedWhere);
+        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);
     }
   };
 }
@@ -584,6 +654,26 @@ 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 });
+            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));
@@ -636,9 +726,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

@@ -23,13 +23,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 +64,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 +111,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
 
@@ -177,6 +260,26 @@ export async function action({ context, request }) {
 - **@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 +287,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.2.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.2.0"
   },
   "peerDependenciesMeta": {
     "@cloudflare/workers-types": {