@cfast/db 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,205 +1,7 @@
-import { Grant, DrizzleTable, PermissionDescriptor } from '@cfast/permissions';
-import { Table, TablesRelationalConfig, ExtractTablesWithRelations, TableRelationalConfig, BuildQueryResult } from 'drizzle-orm';
-
-type InferRow<TTable> = TTable extends {
-    $inferSelect: infer R;
-} ? R : Record<string, unknown>;
-/** @internal */
-type FindTableKeyByName<TSchema extends TablesRelationalConfig, TTableName extends string> = {
-    [K in keyof TSchema]: TSchema[K]["dbName"] extends TTableName ? K : never;
-}[keyof TSchema];
-/** @internal */
-type LookupTableConfig<TFullSchema extends Record<string, unknown>, TTable> = TTable extends Table<infer TTableConfig> ? FindTableKeyByName<ExtractTablesWithRelations<TFullSchema>, TTableConfig["name"]> extends infer TKey extends keyof ExtractTablesWithRelations<TFullSchema> ? ExtractTablesWithRelations<TFullSchema>[TKey] : never : never;
-type InferQueryResult<TFullSchema extends Record<string, unknown>, TTable, TConfig> = [TFullSchema] extends [Record<string, never>] ? InferRow<TTable> : LookupTableConfig<TFullSchema, TTable> extends infer TTableConfig extends TableRelationalConfig ? BuildQueryResult<ExtractTablesWithRelations<TFullSchema>, TTableConfig, TConfig extends Record<string, unknown> ? TConfig : true> : InferRow<TTable>;
-type Operation<TResult> = {
-    permissions: PermissionDescriptor[];
-    run: (params?: Record<string, unknown>) => Promise<TResult>;
-};
-type CacheBackend = "cache-api" | "kv";
-type CacheConfig = {
-    backend: CacheBackend;
-    kv?: KVNamespace;
-    ttl?: string;
-    staleWhileRevalidate?: string;
-    exclude?: string[];
-    onHit?: (key: string, table: string) => void;
-    onMiss?: (key: string, table: string) => void;
-    onInvalidate?: (tables: string[]) => void;
-};
-type QueryCacheOptions = false | {
-    ttl?: string;
-    staleWhileRevalidate?: string;
-    tags?: string[];
-};
-type DbConfig<TSchema extends Record<string, unknown> = Record<string, unknown>> = {
-    d1: D1Database;
-    schema: TSchema;
-    grants: Grant[];
-    user: {
-        id: string;
-    } | null;
-    cache?: CacheConfig | false;
-};
-type FindManyOptions = {
-    columns?: Record<string, boolean>;
-    where?: unknown;
-    orderBy?: unknown;
-    limit?: number;
-    offset?: number;
-    with?: Record<string, unknown>;
-    cache?: QueryCacheOptions;
-};
-type FindFirstOptions = Omit<FindManyOptions, "limit" | "offset">;
-type CursorParams = {
-    type: "cursor";
-    cursor: string | null;
-    limit: number;
-};
-type OffsetParams = {
-    type: "offset";
-    page: number;
-    limit: number;
-};
-type PaginateParams = CursorParams | OffsetParams;
-type CursorPage<T> = {
-    items: T[];
-    nextCursor: string | null;
-};
-type OffsetPage<T> = {
-    items: T[];
-    total: number;
-    page: number;
-    totalPages: number;
-};
-type PaginateOptions = {
-    columns?: Record<string, boolean>;
-    where?: unknown;
-    orderBy?: unknown;
-    cursorColumns?: unknown[];
-    orderDirection?: "asc" | "desc";
-    with?: Record<string, unknown>;
-    cache?: QueryCacheOptions;
-};
-type TransactionResult<T> = {
-    result: T;
-    meta: {
-        changes: number;
-        writeResults: D1Result[];
-    };
-};
-type Tx<TSchema extends Record<string, unknown> = Record<string, never>> = {
-    query: <TTable extends DrizzleTable>(table: TTable) => QueryBuilder<TTable, TSchema>;
-    insert: <TTable extends DrizzleTable>(table: TTable) => InsertBuilder<TTable>;
-    update: <TTable extends DrizzleTable>(table: TTable) => UpdateBuilder<TTable>;
-    delete: <TTable extends DrizzleTable>(table: TTable) => DeleteBuilder<TTable>;
-    transaction: <T>(callback: (tx: Tx<TSchema>) => Promise<T>) => Promise<T>;
-};
-type Db<TSchema extends Record<string, unknown> = Record<string, never>> = {
-    query: <TTable extends DrizzleTable>(table: TTable) => QueryBuilder<TTable, TSchema>;
-    insert: <TTable extends DrizzleTable>(table: TTable) => InsertBuilder<TTable>;
-    update: <TTable extends DrizzleTable>(table: TTable) => UpdateBuilder<TTable>;
-    delete: <TTable extends DrizzleTable>(table: TTable) => DeleteBuilder<TTable>;
-    unsafe: () => Db<TSchema>;
-    batch: (operations: Operation<unknown>[]) => Operation<unknown[]>;
-    /**
-     * Runs a callback inside a transaction with atomic commit-or-rollback semantics.
-     *
-     * All writes (`tx.insert`/`tx.update`/`tx.delete`) recorded inside the callback
-     * are deferred and flushed together as a single atomic `db.batch([...])` when
-     * the callback returns successfully. If the callback throws, pending writes are
-     * discarded and the error is re-thrown — nothing reaches D1.
-     *
-     * Reads (`tx.query(...)`) execute eagerly so the caller can branch on their
-     * results. **D1 does not provide snapshot isolation across async code**, so
-     * reads inside a transaction can see concurrent writes. For concurrency-safe
-     * read-modify-write (e.g. stock decrement), combine the transaction with a
-     * relative SQL update and a WHERE guard:
-     *
-     * ```ts
-     * await db.transaction(async (tx) => {
-     *   // The WHERE guard ensures the decrement only applies when stock is
-     *   // still >= qty at commit time. Two concurrent transactions cannot
-     *   // both oversell because D1's atomic batch re-evaluates the WHERE.
-     *   await tx.update(products)
-     *     .set({ stock: sql`stock - ${qty}` })
-     *     .where(and(eq(products.id, pid), gte(products.stock, qty)))
-     *     .run();
-     *   return tx.insert(orders).values({ productId: pid, qty }).returning().run();
-     * });
-     * ```
-     *
-     * Nested `db.transaction()` calls inside the callback are flattened into the
-     * parent's pending queue so everything still commits atomically.
-     *
-     * @typeParam T - The return type of the callback.
-     * @param callback - The transaction body. Receives a `tx` handle with
-     *   `query`/`insert`/`update`/`delete` methods (no `unsafe`, `batch`, or
-     *   `cache` — those are intentionally off-limits inside a transaction).
-     * @returns A {@link TransactionResult} containing the callback's return value
-     *   and transaction metadata (`meta.changes`, `meta.writeResults`), or rejects
-     *   with whatever the callback threw (after rolling back pending writes).
-     */
-    transaction: <T>(callback: (tx: Tx<TSchema>) => Promise<T>) => Promise<TransactionResult<T>>;
-    /** Cache control methods for manual invalidation. */
-    cache: {
-        /** Invalidate cached queries by tag names and/or table names. */
-        invalidate: (options: {
-            /** Tag names to invalidate (from {@link QueryCacheOptions} `tags`). */
-            tags?: string[];
-            /** Table names to invalidate (bumps their version counters). */
-            tables?: string[];
-        }) => Promise<void>;
-    };
-    /**
-     * Clears the per-instance `with` lookup cache so that the next query
-     * re-runs every grant lookup function.
-     *
-     * In production this is rarely needed because each request gets a fresh
-     * `Db` via `createDb()`. In tests that reuse a single `Db` across grant
-     * mutations (e.g. inserting a new friendship and then querying recipes),
-     * call this after the mutation to avoid stale lookup results.
-     *
-     * For finer-grained control, wrap each logical request in
-     * {@link runWithLookupCache} instead -- that scopes the cache via
-     * `AsyncLocalStorage` so it is automatically discarded at scope exit.
-     *
-     * @example
-     * ```ts
-     * const db = createDb({ ... });
-     * await db.query(recipes).findMany().run(); // populates lookup cache
-     * await db.insert(friendGrants).values({ ... }).run(); // adds new grant
-     * db.clearLookupCache(); // drop stale lookups
-     * await db.query(recipes).findMany().run(); // sees new grant
-     * ```
-     */
-    clearLookupCache: () => void;
-};
-type QueryBuilder<TTable extends DrizzleTable = DrizzleTable, TSchema extends Record<string, unknown> = Record<string, never>> = {
-    findMany: <TConfig extends FindManyOptions = Record<string, never>, TRow = InferQueryResult<TSchema, TTable, TConfig>>(options?: TConfig) => Operation<TRow[]>;
-    findFirst: <TConfig extends FindFirstOptions = Record<string, never>, TRow = InferQueryResult<TSchema, TTable, TConfig>>(options?: TConfig) => Operation<TRow | undefined>;
-    paginate: <TRow = InferRow<TTable>>(params: CursorParams | OffsetParams, options?: PaginateOptions) => Operation<CursorPage<TRow>> | Operation<OffsetPage<TRow>>;
-};
-type InsertBuilder<TTable extends DrizzleTable = DrizzleTable> = {
-    values: (values: Record<string, unknown>) => InsertReturningBuilder<TTable>;
-};
-type InsertReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
-    returning: () => Operation<InferRow<TTable>>;
-};
-type UpdateBuilder<TTable extends DrizzleTable = DrizzleTable> = {
-    set: (values: Record<string, unknown>) => UpdateWhereBuilder<TTable>;
-};
-type UpdateWhereBuilder<TTable extends DrizzleTable = DrizzleTable> = {
-    where: (condition: unknown) => UpdateReturningBuilder<TTable>;
-};
-type UpdateReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
-    returning: () => Operation<InferRow<TTable>>;
-};
-type DeleteBuilder<TTable extends DrizzleTable = DrizzleTable> = {
-    where: (condition: unknown) => DeleteReturningBuilder<TTable>;
-};
-type DeleteReturningBuilder<TTable extends DrizzleTable = DrizzleTable> = Operation<void> & {
-    returning: () => Operation<InferRow<TTable>>;
-};
+import { Grant, PermissionDescriptor } from '@cfast/permissions';
+import { D as DbConfig, a as Db, O as Operation, C as CursorParams, b as OffsetParams } from './types-FUFR36h1.js';
+export { c as CacheBackend, d as CacheConfig, e as CursorPage, f as DeleteBuilder, g as DeleteReturningBuilder, F as FindFirstOptions, h as FindManyOptions, I as InferQueryResult, i as InferRow, j as InsertBuilder, k as InsertReturningBuilder, l as OffsetPage, P as PaginateOptions, m as PaginateParams, Q as QueryBuilder, n as QueryCacheOptions, T as TransactionResult, o as Tx, U as UpdateBuilder, p as UpdateReturningBuilder, q as UpdateWhereBuilder, W as WithCan } from './types-FUFR36h1.js';
+import 'drizzle-orm';
 
 /**
  * Creates a permission-aware database instance bound to the given user.
@@ -535,108 +337,6 @@ declare class TransactionError extends Error {
     constructor(message: string);
 }
 
-/**
- * A single seed entry — every row in `rows` is inserted into `table` at seed
- * time. Row shape is inferred from the Drizzle table so typos in column names
- * are caught by `tsc` instead of failing at runtime when `INSERT` rejects
- * the statement.
- *
- * @typeParam TTable - The Drizzle table reference (e.g. `typeof usersTable`).
- */
-type SeedEntry<TTable extends DrizzleTable = DrizzleTable> = {
-    /**
-     * The Drizzle table to insert into. Must be imported from your schema
-     * (`import { users } from "~/db/schema"`) rather than passed as a string
-     * so the helper can infer row types and forward the reference to
-     * `db.insert()`.
-     */
-    table: TTable;
-    /**
-     * Rows to insert. The row shape is inferred from the table's
-     * `$inferSelect` — making a typo in a column name is a compile-time error.
-     *
-     * Entries are inserted in the order they appear, which lets you control
-     * foreign-key ordering just by ordering your `entries` array
-     * (`{ users }` before `{ posts }`, etc.).
-     */
-    rows: readonly InferRow<TTable>[];
-};
-/**
- * Configuration passed to {@link defineSeed}.
- */
-type SeedConfig = {
-    /**
-     * Ordered list of seed entries. Each entry is flushed as a batched insert
-     * in list order, so place parent tables (users, orgs) before child tables
-     * (posts, memberships) that reference them via foreign keys.
-     */
-    entries: readonly SeedEntry[];
-};
-/**
- * The compiled seed returned by {@link defineSeed}.
- *
- * Holds a frozen copy of the entry list so runner callers can introspect
- * what would be seeded, plus a `run(db)` method that actually executes the
- * inserts against a real {@link Db} instance.
- */
-type Seed = {
-    /** The frozen list of entries this seed will insert, in order. */
-    readonly entries: readonly SeedEntry[];
-    /**
-     * Executes every entry against the given {@link Db} in the order they were
-     * declared. Uses `db.unsafe()` internally so seed scripts don't need
-     * their own grants plumbing — seeding is a system task by definition.
-     *
-     * Entries with an empty `rows` array are skipped so callers can leave
-     * placeholder entries in the config without crashing the seed.
-     *
-     * @param db - A {@link Db} instance, typically created once at the top
-     *   of a `scripts/seed.ts` file via `createDb({...})`.
-     */
-    run: (db: Db) => Promise<void>;
-};
-/**
- * Declares a database seed in a portable, type-safe way.
- *
- * The canonical replacement for hand-rolled `scripts/seed.ts` files that
- * called `db.mutate("tablename")` (a method that never existed) or reached
- * straight into raw Drizzle. Use the scaffolded `scripts/seed.ts` in a
- * `create-cfast` project for a ready-made example.
- *
- * @example
- * ```ts
- * // scripts/seed.ts
- * import { defineSeed, createDb } from "@cfast/db";
- * import * as schema from "~/db/schema";
- *
- * const seed = defineSeed({
- *   entries: [
- *     {
- *       table: schema.users,
- *       rows: [
- *         { id: "u-1", email: "ada@example.com", name: "Ada" },
- *         { id: "u-2", email: "grace@example.com", name: "Grace" },
- *       ],
- *     },
- *     {
- *       table: schema.posts,
- *       rows: [
- *         { id: "p-1", authorId: "u-1", title: "Hello" },
- *       ],
- *     },
- *   ],
- * });
- *
- * // In a worker/runner that already has a real D1 binding:
- * const db = createDb({ d1, schema, grants: [], user: null });
- * await seed.run(db);
- * ```
- *
- * @param config - The {@link SeedConfig} with the ordered list of entries.
- * @returns A {@link Seed} with a `.run(db)` executor.
- */
-declare function defineSeed(config: SeedConfig): Seed;
-
 /**
  * Recursively converts Date fields in a value to ISO 8601 strings for
  * JSON serialization.
@@ -733,4 +433,4 @@ declare function createLookupCache(): LookupCache;
  */
 declare function runWithLookupCache<T>(fn: () => T, cache?: LookupCache): T;
 
-export { type AppDbConfig, type AppDbFactory, type CacheBackend, type CacheConfig, type CursorPage, type CursorParams, type DateToString, type Db, type DbConfig, type DeleteBuilder, type DeleteReturningBuilder, type FindFirstOptions, type FindManyOptions, type InferQueryResult, type InferRow, type InsertBuilder, type InsertReturningBuilder, type LookupCache, type OffsetPage, type OffsetParams, type Operation, type PaginateOptions, type PaginateParams, type QueryBuilder, type QueryCacheOptions, type Seed, type SeedConfig, type SeedEntry, TransactionError, type TransactionResult, type Tx, type UpdateBuilder, type UpdateReturningBuilder, type UpdateWhereBuilder, compose, composeSequential, composeSequentialCallback, createAppDb, createDb, createLookupCache, defineSeed, parseCursorParams, parseOffsetParams, runWithLookupCache, toJSON };
+export { type AppDbConfig, type AppDbFactory, CursorParams, type DateToString, Db, DbConfig, type LookupCache, OffsetParams, Operation, TransactionError, compose, composeSequential, composeSequentialCallback, createAppDb, createDb, createLookupCache, parseCursorParams, parseOffsetParams, runWithLookupCache, toJSON };

package/dist/index.js

@@ -2,8 +2,9 @@
 import { drizzle as drizzle4 } from "drizzle-orm/d1";
 
 // src/query-builder.ts
-import { count } from "drizzle-orm";
+import { count, sql, or as drizzleOr } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/d1";
+import { getGrantedActions } from "@cfast/permissions";
 
 // src/permissions.ts
 import {
@@ -220,6 +221,53 @@ function getTableKey(schema, table) {
 function getQueryTable(db, key) {
   return db.query[key];
 }
+var CAN_PREFIX = "_can_";
+async function buildCanExtras(config, grantedActions, queriedAction) {
+  const extras = {};
+  for (const ga of grantedActions) {
+    const alias = `${CAN_PREFIX}${ga.action}`;
+    if (ga.action === queriedAction) {
+      extras[alias] = sql`1`.as(alias);
+      continue;
+    }
+    if (ga.unrestricted) {
+      extras[alias] = sql`1`.as(alias);
+      continue;
+    }
+    const needsLookupDb = ga.grants.some((g) => g.with !== void 0);
+    const lookupDb = needsLookupDb ? config.getLookupDb() : void 0;
+    const lookupSets = await Promise.all(
+      ga.grants.map((g) => resolveGrantLookups(g, config.user, lookupDb, config.lookupCache))
+    );
+    const columns = config.table;
+    const clauses = ga.grants.map(
+      (g, i) => g.where ? g.where(columns, config.user, lookupSets[i]) : void 0
+    ).filter((c) => c !== void 0);
+    if (clauses.length === 0) {
+      extras[alias] = sql`1`.as(alias);
+      continue;
+    }
+    const combined = clauses.length === 1 ? clauses[0] : drizzleOr(...clauses);
+    extras[alias] = sql`CASE WHEN ${combined} THEN 1 ELSE 0 END`.as(alias);
+  }
+  return extras;
+}
+function attachCan(row, grantedActions) {
+  const can = {};
+  const grantedSet = new Set(grantedActions.map((ga) => ga.action));
+  const allActions = ["read", "create", "update", "delete"];
+  for (const action of allActions) {
+    const key = `${CAN_PREFIX}${action}`;
+    if (key in row) {
+      can[action] = row[key] === 1 || row[key] === true;
+      delete row[key];
+    } else if (!grantedSet.has(action)) {
+      can[action] = false;
+    }
+  }
+  row._can = can;
+  return row;
+}
 function buildQueryOperation(config, db, tableKey, method, options) {
   const permissions = makePermissions(config.unsafe, "read", config.table);
   return {
@@ -244,8 +292,32 @@ function buildQueryOperation(config, db, tableKey, method, options) {
         queryOptions.where = combinedWhere;
       }
       delete queryOptions.cache;
+      const grantedActions = !config.unsafe && config.user ? getGrantedActions(config.grants, config.table) : [];
+      if (grantedActions.length > 0) {
+        const canExtras = await buildCanExtras(config, grantedActions, "read");
+        const userExtras = queryOptions.extras;
+        queryOptions.extras = userExtras ? { ...userExtras, ...canExtras } : canExtras;
+      }
       const queryTable = getQueryTable(db, tableKey);
       const result = await queryTable[method](queryOptions);
+      if (grantedActions.length > 0) {
+        if (method === "findFirst" && result != null) {
+          attachCan(result, grantedActions);
+        } else if (method === "findMany" && Array.isArray(result)) {
+          for (const row of result) {
+            attachCan(row, grantedActions);
+          }
+        }
+      } else if (!config.unsafe && config.user) {
+        const emptyCan = { read: false, create: false, update: false, delete: false };
+        if (method === "findFirst" && result != null) {
+          result._can = { ...emptyCan };
+        } else if (method === "findMany" && Array.isArray(result)) {
+          for (const row of result) {
+            row._can = { ...emptyCan };
+          }
+        }
+      }
       return method === "findFirst" ? result ?? void 0 : result;
     }
   };
@@ -583,8 +655,8 @@ function createCacheManager(config) {
   const defaultTtl = config.ttl ?? "60s";
   const excludedTables = new Set(config.exclude ?? []);
   return {
-    generateKey(sql, role, tableVersion) {
-      return `cfast:${role}:v${tableVersion}:${simpleHash(sql)}`;
+    generateKey(sql2, role, tableVersion) {
+      return `cfast:${role}:v${tableVersion}:${simpleHash(sql2)}`;
     },
     getTableVersion(table) {
       return tableVersions.get(table) ?? 0;
@@ -952,7 +1024,8 @@ function buildDb(config, isUnsafe, lookupCache) {
     },
     clearLookupCache() {
       lookupCache.clear();
-    }
+    },
+    _schema: config.schema
   };
   return db;
 }
@@ -1077,7 +1150,8 @@ function createTrackingDb(real, perms) {
       return createSentinel();
     },
     cache: real.cache,
-    clearLookupCache: () => real.clearLookupCache()
+    clearLookupCache: () => real.clearLookupCache(),
+    _schema: real._schema
   };
   return trackingDb;
 }
@@ -1109,33 +1183,6 @@ function composeSequentialCallback(db, callback) {
   };
 }
 
-// src/seed.ts
-function defineSeed(config) {
-  const entries = Object.freeze(
-    config.entries.map((entry) => ({
-      table: entry.table,
-      rows: Object.freeze([...entry.rows])
-    }))
-  );
-  return {
-    entries,
-    async run(db) {
-      const unsafeDb = db.unsafe();
-      for (const entry of entries) {
-        if (entry.rows.length === 0) continue;
-        const ops = entry.rows.map(
-          (row) => unsafeDb.insert(entry.table).values(row)
-        );
-        if (ops.length === 1) {
-          await ops[0].run({});
-        } else {
-          await unsafeDb.batch(ops).run({});
-        }
-      }
-    }
-  };
-}
-
 // src/json.ts
 function toJSON(value) {
   return convertDates(value);
@@ -1164,7 +1211,6 @@ export {
   createAppDb,
   createDb,
   createLookupCache,
-  defineSeed,
   parseCursorParams,
   parseOffsetParams,
   runWithLookupCache,