@gencow/core 0.1.8 → 0.1.10

package/src/table.ts

@@ -0,0 +1,165 @@
+/**
+ * packages/core/src/table.ts
+ *
+ * gencowTable() — Drizzle pgTable wrapper with schema-level access control.
+ * Inspired by KeystoneJS's declarative filter pattern.
+ *
+ * Run tests: bun test packages/core/src/__tests__/table.test.ts
+ */
+
+import { pgTable } from "drizzle-orm/pg-core";
+import { eq } from "drizzle-orm";
+import type { GencowCtx } from "./reactive";
+import type { SQL } from "drizzle-orm";
+
+// ─── Types ──────────────────────────────────────────────
+
+/**
+ * Access control filter function.
+ * Returns a Drizzle SQL condition, `true` (allow all), or `false` (deny all).
+ * Can be async (e.g., for team membership lookups).
+ */
+export type AccessFilter = (ctx: GencowCtx) => SQL | boolean | Promise<SQL | boolean>;
+
+/** Field-level access control: per-field read permission. */
+export interface FieldAccessRule {
+    read: (ctx: GencowCtx) => boolean;
+}
+
+/** Options for gencowTable — access control metadata. */
+export interface GencowTableOptions {
+    /** Row-level filter — auto-injected into all queries on this table */
+    filter: AccessFilter;
+    /** Field-level access — unauthorized fields are nullified in results */
+    fieldAccess?: Record<string, FieldAccessRule>;
+}
+
+/** Stored metadata for a gencowTable. */
+export interface TableAccessMeta {
+    filter: AccessFilter;
+    fieldAccess?: Record<string, FieldAccessRule>;
+    tableName: string;
+}
+
+// Internal marker for ownerFilter
+interface OwnerFilterOptions extends GencowTableOptions {
+    _ownerColumn: string;
+}
+
+function isOwnerFilter(opts: GencowTableOptions): opts is OwnerFilterOptions {
+    return "_ownerColumn" in opts;
+}
+
+// ─── Global Registry ────────────────────────────────────
+
+declare global {
+    // eslint-disable-next-line no-var
+    var __gencow_tableAccessRegistry: Map<any, TableAccessMeta>;
+}
+
+if (!globalThis.__gencow_tableAccessRegistry) {
+    globalThis.__gencow_tableAccessRegistry = new Map();
+}
+
+const tableAccessRegistry = globalThis.__gencow_tableAccessRegistry;
+
+// ─── gencowTable() ──────────────────────────────────────
+
+/**
+ * Drizzle pgTable wrapper with schema-level access control.
+ *
+ * Creates a standard Drizzle pgTable (100% compatible) and registers
+ * filter + fieldAccess metadata that ctx.db Proxy uses to auto-inject
+ * WHERE clauses.
+ *
+ * @param name    - PostgreSQL table name
+ * @param columns - Drizzle column definitions (same as pgTable)
+ * @param options - Access control (filter required, fieldAccess optional)
+ */
+export function gencowTable<T extends Record<string, any>>(
+    name: string,
+    columns: T,
+    options: GencowTableOptions,
+): ReturnType<typeof pgTable<string, T>> {
+    if (!options || (typeof options.filter !== "function" && !isOwnerFilter(options))) {
+        throw new Error(
+            `[gencow] gencowTable("${name}") requires a filter option. ` +
+            `Use ownerFilter("userId") for simple user isolation, ` +
+            `or { filter: () => true } for public tables.`
+        );
+    }
+
+    // Create standard Drizzle pgTable — fully compatible
+    const table = pgTable(name, columns);
+
+    // Resolve ownerFilter to a concrete filter bound to this table
+    let filter: AccessFilter;
+    if (isOwnerFilter(options)) {
+        const columnName = options._ownerColumn;
+        const col = (table as any)[columnName];
+        if (!col) {
+            throw new Error(
+                `[gencow] ownerFilter("${columnName}"): column "${columnName}" not found on table "${name}". ` +
+                `Available columns: ${Object.keys(table as any).filter(k => !k.startsWith("_") && !k.startsWith("$")).join(", ")}`
+            );
+        }
+        filter = (ctx: GencowCtx) => {
+            const user = ctx.auth.requireAuth();
+            return eq(col, user.id);
+        };
+    } else {
+        filter = options.filter;
+    }
+
+    // Store access control metadata keyed by the table object reference
+    tableAccessRegistry.set(table, {
+        filter,
+        fieldAccess: options.fieldAccess,
+        tableName: name,
+    });
+
+    return table;
+}
+
+// ─── ownerFilter() helper ───────────────────────────────
+
+/**
+ * Convenience helper for userId-based isolation.
+ *
+ * Usage:
+ *   export const tasks = gencowTable("tasks", { ... }, ownerFilter("userId"));
+ *   export const files = gencowTable("files", { ... }, ownerFilter("ownerId"));
+ *
+ * @param columnName - Name of the user ID column (default: "userId")
+ */
+export function ownerFilter(columnName: string = "userId"): GencowTableOptions {
+    // Return a marker object — gencowTable() resolves this to a concrete filter
+    // by binding to the actual table column at registration time.
+    return {
+        _ownerColumn: columnName,
+        // Placeholder filter — replaced by gencowTable()
+        filter: () => { throw new Error("[gencow] ownerFilter placeholder should not be called directly"); },
+    } as OwnerFilterOptions;
+}
+
+// ─── Lookup ─────────────────────────────────────────────
+
+/** Get access control metadata for a table. Returns undefined for plain pgTable. */
+export function getTableAccessMeta(table: any): TableAccessMeta | undefined {
+    return tableAccessRegistry.get(table);
+}
+
+/** Check if a table has gencowTable metadata registered. */
+export function isGencowTable(table: any): boolean {
+    return tableAccessRegistry.has(table);
+}
+
+/** Get all registered gencowTables (for audit/boot-time checks). */
+export function getAllGencowTables(): Map<any, TableAccessMeta> {
+    return new Map(tableAccessRegistry);
+}
+
+/** Reset registry (for testing only). */
+export function _resetTableRegistry(): void {
+    tableAccessRegistry.clear();
+}