@zeno-lib/db 0.0.1

package/README.md

@@ -0,0 +1,3 @@
+# @zeno-lib/db
+
+See [Database](https://www.zeno-lib.com/docs/core-framework/data-management/database).

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@zeno-lib/db",
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "pnpm exec supabase start",
+    "stop": "pnpm exec supabase stop",
+    "reset": "pnpm exec supabase db reset",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "test": "vitest --run",
+    "test:watch": "vitest watch",
+    "types:check": "tsc --noEmit"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./config": "./src/config.ts",
+    "./schema": "./src/schema.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "url": "https://github.com/zeno-lib/zeno.git",
+    "directory": "packages/db"
+  },
+  "peerDependencies": {
+    "@supabase/supabase-js": ">=2",
+    "drizzle-kit": "1.0.0-rc.3",
+    "drizzle-orm": "1.0.0-rc.3",
+    "postgres": ">=3.4"
+  },
+  "devDependencies": {
+    "@supabase/supabase-js": "2.106.1",
+    "@types/node": "24.10.0",
+    "@zeno-lib/test": "workspace:*",
+    "@zeno-lib/typescript": "workspace:^",
+    "dotenv": "16.4.7",
+    "drizzle-kit": "1.0.0-rc.3",
+    "drizzle-orm": "1.0.0-rc.3",
+    "postgres": "3.4.7",
+    "supabase": "2.84.1",
+    "vite": "8.0.16",
+    "vitest": "4.1.0"
+  }
+}

package/src/casing.test.ts

@@ -0,0 +1,264 @@
+import { getTableColumns, sql } from "drizzle-orm"
+import {
+  getTableConfig,
+  isPgEnum,
+  isPgMaterializedView,
+  isPgSchema,
+  isPgSequence,
+  isPgView,
+  pgEnum,
+  pgMaterializedView,
+  pgPolicy,
+  pgRole,
+  pgSchema,
+  pgSequence,
+  pgTableCreator,
+  pgView,
+  text,
+  uuid,
+} from "drizzle-orm/pg-core"
+import { camelCase, snakeCase } from "drizzle-orm/pg-core/casing"
+import { describe, expect, it } from "vitest"
+import { createAdminClient } from "./clients.ts"
+import { defineDrizzleConfig } from "./config.ts"
+import {
+  allPolicy,
+  auditColumns,
+  authenticatedOwnerDeletePolicy,
+  authenticatedOwnerInsertPolicy,
+  authenticatedOwnerSelectPolicy,
+  authenticatedOwnerUpdatePolicy,
+  authenticatedRole,
+  authorship,
+  authUid,
+  authUserId,
+  authUsers,
+  createdBy,
+  deletePolicy,
+  enum as enum_,
+  insertPolicy,
+  isEnum,
+  isMaterializedView,
+  isSchema,
+  isSequence,
+  isView,
+  materializedView,
+  policy,
+  primaryId,
+  role,
+  schema,
+  selectPolicy,
+  sequence,
+  table,
+  tableCreator,
+  timestamps,
+  unsecureTable,
+  updatedBy,
+  updatePolicy,
+  view,
+} from "./schema.ts"
+
+describe("default casing", () => {
+  it("leaves casing to Drizzle table constructors", () => {
+    expect(defineDrizzleConfig()).not.toHaveProperty("casing")
+  })
+
+  it("works with Drizzle's snake_case table builders", async () => {
+    const posts = snakeCase.table("posts", {
+      displayName: text(),
+      ownerId: uuid(),
+    })
+    const db = createAdminClient()
+
+    expect(db.select().from(posts).toSQL().sql).toContain('"display_name"')
+    expect(db.select().from(posts).toSQL().sql).toContain('"owner_id"')
+
+    await db.close()
+  })
+
+  it("allows callers to opt into camelCase table builders", async () => {
+    const posts = camelCase.table("posts", {
+      displayName: text(),
+    })
+    const db = createAdminClient()
+
+    expect(db.select().from(posts).toSQL().sql).toContain('"displayName"')
+
+    await db.close()
+  })
+
+  it("exports an RLS-enabled snake_case table helper", async () => {
+    const posts = table("posts", {
+      displayName: text(),
+      ownerId: uuid(),
+    })
+    const db = createAdminClient()
+
+    expect(db.select().from(posts).toSQL().sql).toContain('"display_name"')
+    expect(db.select().from(posts).toSQL().sql).toContain('"owner_id"')
+    expect(getTableConfig(posts).enableRLS).toBe(true)
+
+    await db.close()
+  })
+
+  it("exports an explicit non-RLS snake_case table helper", async () => {
+    const auditEvents = unsecureTable("audit_events", {
+      displayName: text(),
+      ownerId: uuid(),
+    })
+    const db = createAdminClient()
+
+    expect(db.select().from(auditEvents).toSQL().sql).toContain(
+      '"display_name"'
+    )
+    expect(db.select().from(auditEvents).toSQL().sql).toContain('"owner_id"')
+    expect(getTableConfig(auditEvents).enableRLS).toBe(false)
+
+    await db.close()
+  })
+
+  it("re-exports likely pg-prefixed schema builders without the pg prefix", () => {
+    expect(enum_).toBe(pgEnum)
+    expect(isEnum).toBe(isPgEnum)
+    expect(isMaterializedView).toBe(isPgMaterializedView)
+    expect(isSchema).toBe(isPgSchema)
+    expect(isSequence).toBe(isPgSequence)
+    expect(isView).toBe(isPgView)
+    expect(materializedView).toBe(pgMaterializedView)
+    expect(policy).toBe(pgPolicy)
+    expect(role).toBe(pgRole)
+    expect(schema).toBe(pgSchema)
+    expect(sequence).toBe(pgSequence)
+    expect(tableCreator).toBe(pgTableCreator)
+    expect(view).toBe(pgView)
+  })
+
+  it("exports common ID and Supabase auth-user column helpers", () => {
+    const posts = table("posts", {
+      id: primaryId("uuid"),
+      ownerId: authUserId(),
+      sequentialId: primaryId("sequential"),
+    })
+    const columns = getTableColumns(posts)
+    const config = getTableConfig(posts)
+
+    expect(columns.id.getSQLType()).toBe("uuid")
+    expect(columns.id.primary).toBe(true)
+    expect(columns.id.default).toBeDefined()
+    expect(columns.sequentialId.getSQLType()).toBe("integer")
+    expect(columns.sequentialId.primary).toBe(true)
+    expect(columns.sequentialId.generatedIdentity?.type).toBe("always")
+    expect(columns.ownerId.getSQLType()).toBe("uuid")
+    expect(columns.ownerId.notNull).toBe(true)
+    expect(config.foreignKeys).toHaveLength(1)
+    expect(config.foreignKeys[0]?.reference().foreignTable).toBe(authUsers)
+  })
+
+  it("exports audit timestamp and auth-user column helpers with runtime defaults", () => {
+    const posts = table("posts", {
+      createdBy,
+      updatedBy,
+      ...timestamps,
+    })
+    const columns = getTableColumns(posts)
+    const config = getTableConfig(posts)
+
+    expect(columns.createdAt.name).toBe("created_at")
+    expect(columns.createdAt.notNull).toBe(true)
+    expect(columns.createdAt.default).toBeDefined()
+    expect(columns.createdAt.onUpdateFn).toBeUndefined()
+    expect(columns.updatedAt.name).toBe("updated_at")
+    expect(columns.updatedAt.notNull).toBe(true)
+    expect(columns.updatedAt.default).toBeDefined()
+    expect(columns.updatedAt.onUpdateFn?.()).toBeInstanceOf(Date)
+    expect(columns.createdBy.name).toBe("created_by")
+    expect(columns.createdBy.notNull).toBe(true)
+    expect(columns.createdBy.default).toBe(authUid)
+    expect(columns.createdBy.onUpdateFn).toBeUndefined()
+    expect(columns.updatedBy.name).toBe("updated_by")
+    expect(columns.updatedBy.notNull).toBe(true)
+    expect(columns.updatedBy.default).toBe(authUid)
+    expect(columns.updatedBy.onUpdateFn?.()).toBe(authUid)
+    expect(config.foreignKeys).toHaveLength(2)
+    expect(
+      config.foreignKeys.map(
+        (foreignKey) => foreignKey.reference().foreignTable
+      )
+    ).toEqual([authUsers, authUsers])
+  })
+
+  it("exports grouped audit column mixins", () => {
+    expect(Object.keys(timestamps)).toEqual(["createdAt", "updatedAt"])
+    expect(Object.keys(authorship)).toEqual(["createdBy", "updatedBy"])
+    expect(Object.keys(auditColumns)).toEqual([
+      "createdAt",
+      "updatedAt",
+      "createdBy",
+      "updatedBy",
+    ])
+
+    const posts = table("posts", {
+      id: primaryId("uuid"),
+      ...auditColumns,
+    })
+    const columns = getTableColumns(posts)
+
+    expect(columns.createdAt.name).toBe("created_at")
+    expect(columns.updatedAt.name).toBe("updated_at")
+    expect(columns.createdBy.name).toBe("created_by")
+    expect(columns.updatedBy.name).toBe("updated_by")
+  })
+
+  it("exports generic policy helpers that set the policy operation", () => {
+    const condition = sql`true`
+
+    expect(selectPolicy("select_posts", { using: condition }).for).toBe(
+      "select"
+    )
+    expect(insertPolicy("insert_posts", { withCheck: condition }).for).toBe(
+      "insert"
+    )
+    expect(updatePolicy("update_posts", { using: condition }).for).toBe(
+      "update"
+    )
+    expect(deletePolicy("delete_posts", { using: condition }).for).toBe(
+      "delete"
+    )
+    expect(allPolicy("all_posts", { using: condition }).for).toBe("all")
+  })
+
+  it("exports authenticated owner policy helpers for common Supabase RLS", () => {
+    const posts = table(
+      "posts",
+      {
+        id: primaryId("uuid"),
+        userId: authUserId(),
+      },
+      (t) => [
+        authenticatedOwnerSelectPolicy("posts_owner_select", t.userId),
+        authenticatedOwnerInsertPolicy("posts_owner_insert", t.userId),
+        authenticatedOwnerUpdatePolicy("posts_owner_update", t.userId),
+        authenticatedOwnerDeletePolicy("posts_owner_delete", t.userId),
+      ]
+    )
+    const policies = getTableConfig(posts).policies
+
+    expect(policies.map((rlsPolicy) => rlsPolicy.for)).toEqual([
+      "select",
+      "insert",
+      "update",
+      "delete",
+    ])
+    expect(policies.map((rlsPolicy) => rlsPolicy.to)).toEqual([
+      authenticatedRole,
+      authenticatedRole,
+      authenticatedRole,
+      authenticatedRole,
+    ])
+    expect(policies[0]?.using).toBeDefined()
+    expect(policies[1]?.withCheck).toBeDefined()
+    expect(policies[2]?.using).toBeDefined()
+    expect(policies[2]?.withCheck).toBeDefined()
+    expect(policies[3]?.using).toBeDefined()
+  })
+})

package/src/clients.test.ts

@@ -0,0 +1,94 @@
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+// Use the REAL postgres driver and REAL drizzle here — postgres-js connects
+// lazily, so a pool can be built and `end()`ed without a running server. We
+// only intercept the factory (a counting passthrough) to observe the pool
+// caching and reference-counted close() that live in clients.ts. Behavioral
+// concerns (RLS, role/claims, query replay) are covered by the integration
+// suite in test/rls.integration.test.ts, which runs against real Postgres.
+const { postgresSpy, endSpies } = vi.hoisted(() => ({
+  endSpies: [] as ReturnType<typeof vi.fn>[],
+  postgresSpy: vi.fn(),
+}))
+
+vi.mock("postgres", async (importOriginal) => {
+  const actual = await importOriginal<{ default: typeof import("postgres") }>()
+  return {
+    default: (url: string, options?: unknown) => {
+      postgresSpy(url, options)
+      const client = actual.default(url, options as never)
+      const realEnd = client.end.bind(client)
+      const end = vi.fn((opts?: { timeout?: number }) => realEnd(opts))
+      client.end = end as typeof client.end
+      endSpies.push(end)
+      return client
+    },
+  }
+})
+
+import { createAdminClient } from "./clients.ts"
+
+// Pools are cached by connection string, so each test uses a fresh URL to stay
+// isolated; the pool-sharing tests deliberately reuse one URL.
+let urlCounter = 0
+function url() {
+  urlCounter += 1
+  return `postgresql://postgres:postgres@localhost/db${urlCounter}`
+}
+
+beforeEach(() => {
+  postgresSpy.mockClear()
+  endSpies.length = 0
+})
+
+describe("createAdminClient", () => {
+  it("exposes close", () => {
+    const db = createAdminClient({ connectionString: url() })
+
+    expect(db.close).toEqual(expect.any(Function))
+  })
+
+  it("throws when SUPABASE_DATABASE_URL is unset and no override is provided", () => {
+    vi.stubEnv("SUPABASE_DATABASE_URL", "")
+    expect(() => createAdminClient()).toThrow(
+      "Missing SUPABASE_DATABASE_URL environment variable"
+    )
+    vi.unstubAllEnvs()
+  })
+})
+
+describe("pool sharing", () => {
+  it("creates one pool per connection string", () => {
+    const shared = url()
+
+    createAdminClient({ connectionString: shared })
+    createAdminClient({ connectionString: shared })
+
+    expect(postgresSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it("reference-counts the shared pool so close() ends it once the last handle closes", async () => {
+    const shared = url()
+
+    const first = createAdminClient({ connectionString: shared })
+    const second = createAdminClient({ connectionString: shared })
+
+    // One underlying pool was created for the shared connection string.
+    expect(endSpies).toHaveLength(1)
+    const end = endSpies[0]
+
+    expect(end).not.toHaveBeenCalled()
+
+    await first.close()
+    // Second handle still shares the pool — it must stay open.
+    expect(end).not.toHaveBeenCalled()
+
+    await second.close()
+    // Last handle closed -> pool ended exactly once.
+    expect(end).toHaveBeenCalledTimes(1)
+
+    // Closing again is a no-op (does not re-end an already-closed pool).
+    await second.close()
+    expect(end).toHaveBeenCalledTimes(1)
+  })
+})

package/src/clients.ts

@@ -0,0 +1,213 @@
+// https://orm.drizzle.team/docs/rls#using-with-supabase
+import type { JwtPayload, SupabaseClient } from "@supabase/supabase-js"
+import type { AnyRelations, EmptyRelations } from "drizzle-orm"
+import { sql } from "drizzle-orm"
+import type { DrizzlePgConfig } from "drizzle-orm/pg-core"
+import { drizzle, type PostgresJsDatabase } from "drizzle-orm/postgres-js"
+import postgres from "postgres"
+import { createRlsQueryClient } from "./rls-query-client.ts"
+
+// Roles a user token may switch into. A forged/unexpected `role` claim is
+// clamped to `anon`; the privileged `service_role` is reachable only via the
+// explicit `createServiceClient`, never from a JWT.
+const ALLOWED_RLS_ROLES = new Set(["anon", "authenticated"])
+
+type CloseFn = (options?: { timeout?: number }) => Promise<void>
+
+// Drizzle config minus the connection, which the factory resolves from
+// `SUPABASE_DATABASE_URL` (or the optional override).
+export type CreateClientConfig<
+  TRelations extends AnyRelations = EmptyRelations,
+> = DrizzlePgConfig<TRelations> & {
+  /** Overrides `process.env.SUPABASE_DATABASE_URL`. */
+  connectionString?: string
+}
+
+// A directly-queryable Drizzle client plus a reference-counted `close()`.
+export type DrizzleClient<TRelations extends AnyRelations = EmptyRelations> =
+  PostgresJsDatabase<TRelations> & { close: CloseFn }
+
+// The only JWT claims the RLS clients read.
+export type SupabaseToken = Pick<JwtPayload, "role" | "sub">
+
+// The role-clamped RLS context installed into each transaction.
+type RlsContext = { claims: string; role: string; sub: string }
+
+// Clamps a token's role to the allowlist and re-serializes the claims so a
+// policy reading auth.jwt()->>'role' can never disagree with the role we
+// `set local role` to.
+function clampClaims(token: Partial<SupabaseToken>): RlsContext {
+  const role =
+    token.role && ALLOWED_RLS_ROLES.has(token.role) ? token.role : "anon"
+  return {
+    claims: JSON.stringify({ ...token, role }),
+    role,
+    sub: token.sub ?? "",
+  }
+}
+
+// Trusted role chosen by the caller (not read from a JWT), so it skips the
+// user-token allowlist.
+function fixedContext(role: string): RlsContext {
+  return { claims: JSON.stringify({ role }), role, sub: "" }
+}
+
+// Pools are cached by kind + connection string. "admin" and "rls" get separate
+// pools on the same URL so the admin connection is never role-switched. Each
+// handle shares the cached pool and reference-counts it, so a per-request
+// `close()` ends the pool only once the last handle releases it.
+type PoolKind = "admin" | "rls"
+type PoolEntry = {
+  readonly client: ReturnType<typeof postgres>
+  readonly key: string
+  ended: boolean
+  refCount: number
+}
+const poolCache = new Map<string, PoolEntry>()
+
+function acquirePool(connectionString: string, kind: PoolKind): PoolEntry {
+  const key = `${kind} ${connectionString}`
+  let entry = poolCache.get(key)
+  if (!entry) {
+    // `prepare: false` is required for the Supabase transaction-mode pooler
+    // (port 6543), which doesn't support prepared statements.
+    entry = {
+      client: postgres(connectionString, { prepare: false }),
+      ended: false,
+      key,
+      refCount: 0,
+    }
+    poolCache.set(key, entry)
+  }
+  entry.refCount += 1
+  return entry
+}
+
+function makeClose(entry: PoolEntry): CloseFn {
+  let released = false
+  // Idempotent per handle: closing twice must not double-decrement the pool.
+  return async (options) => {
+    if (released) {
+      return
+    }
+    released = true
+    entry.refCount -= 1
+    if (entry.refCount <= 0 && !entry.ended) {
+      entry.ended = true
+      if (poolCache.get(entry.key) === entry) {
+        poolCache.delete(entry.key)
+      }
+      await entry.client.end(options)
+    }
+  }
+}
+
+// Resolves the connection string, acquires the shared pool, and builds a fresh
+// (cheap) per-handle drizzle instance over it.
+function buildDrizzle<TRelations extends AnyRelations>(
+  kind: PoolKind,
+  config?: CreateClientConfig<TRelations>
+): { close: CloseFn; db: PostgresJsDatabase<TRelations> } {
+  const { connectionString, ...drizzleConfig } = config ?? {}
+  const url = connectionString ?? process.env.SUPABASE_DATABASE_URL ?? ""
+  if (!url) {
+    throw new Error("Missing SUPABASE_DATABASE_URL environment variable")
+  }
+  const entry = acquirePool(url, kind)
+  const db = drizzle<TRelations>({
+    client: entry.client,
+    ...(drizzleConfig as DrizzlePgConfig<TRelations>),
+  })
+  return { close: makeClose(entry), db }
+}
+
+// Wraps a drizzle instance in the lazy RLS query proxy. Claims are resolved
+// before each transaction opens (so `createAuthClient` re-checks the live
+// session per query), then installed transaction-locally via
+// `set_config(..., true)` + `set local role`, which auto-reset at commit.
+function buildRlsClient<TRelations extends AnyRelations>(
+  resolveContext: () => Promise<RlsContext>,
+  config?: CreateClientConfig<TRelations>
+): DrizzleClient<TRelations> {
+  const { close, db } = buildDrizzle("rls", config)
+  const runTransaction = async (transaction: (tx: unknown) => unknown) => {
+    const { claims, role, sub } = await resolveContext()
+    return db.transaction(async (tx) => {
+      await tx.execute(
+        sql`select set_config('request.jwt.claims', ${claims}, true), set_config('request.jwt.claim.sub', ${sub}, true)`
+      )
+      await tx.execute(sql`set local role ${sql.raw(role)}`)
+      return transaction(tx)
+    })
+  }
+  return createRlsQueryClient(
+    runTransaction,
+    close
+  ) as DrizzleClient<TRelations>
+}
+
+/**
+ * RLS-bypassing client (the docs' `admin`). Connects with
+ * `SUPABASE_DATABASE_URL` and queries drizzle directly. Use for webhooks,
+ * background jobs, and seeding, never for user-scoped reads/writes.
+ */
+export function createAdminClient<
+  TRelations extends AnyRelations = EmptyRelations,
+>(config?: CreateClientConfig<TRelations>): DrizzleClient<TRelations> {
+  const { close, db } = buildDrizzle("admin", config)
+  return Object.assign(db, { close })
+}
+
+/**
+ * RLS client scoped to an already-verified, decoded token (e.g. from
+ * `supabase.auth.getClaims()`). The role is clamped to the allowlist.
+ */
+export function createSupabaseClient<
+  TRelations extends AnyRelations = EmptyRelations,
+>(
+  accessToken: SupabaseToken,
+  config?: CreateClientConfig<TRelations>
+): DrizzleClient<TRelations> {
+  const context = clampClaims(accessToken)
+  return buildRlsClient(() => Promise.resolve(context), config)
+}
+
+/**
+ * RLS client bound to a Supabase client. Verified claims are resolved via
+ * `supabase.auth.getClaims()` on every query, so it always reflects the live
+ * session.
+ */
+export function createAuthClient<
+  TRelations extends AnyRelations = EmptyRelations,
+>(
+  supabase: SupabaseClient,
+  config?: CreateClientConfig<TRelations>
+): DrizzleClient<TRelations> {
+  return buildRlsClient(async () => {
+    const { data, error } = await supabase.auth.getClaims()
+    if (error) {
+      throw error
+    }
+    return clampClaims(data?.claims ?? {})
+  }, config)
+}
+
+/** RLS client that runs every query as the `anon` role. */
+export function createAnonClient<
+  TRelations extends AnyRelations = EmptyRelations,
+>(config?: CreateClientConfig<TRelations>): DrizzleClient<TRelations> {
+  return buildRlsClient(() => Promise.resolve(fixedContext("anon")), config)
+}
+
+/**
+ * Client that runs every query as `service_role`, which bypasses RLS via
+ * Supabase's BYPASSRLS grant. Use for trusted server-side work.
+ */
+export function createServiceClient<
+  TRelations extends AnyRelations = EmptyRelations,
+>(config?: CreateClientConfig<TRelations>): DrizzleClient<TRelations> {
+  return buildRlsClient(
+    () => Promise.resolve(fixedContext("service_role")),
+    config
+  )
+}

package/src/config.ts

@@ -0,0 +1,28 @@
+// https://orm.drizzle.team/docs/drizzle-config-file
+// https://orm.drizzle.team/docs/rls#migrations  (entities.roles.provider: "supabase")
+import { type Config, defineConfig } from "drizzle-kit"
+
+export function defineDrizzleConfig(
+  overrides: Partial<Config> = {}
+): ReturnType<typeof defineConfig> {
+  const { entities, ...configOverrides } = overrides
+  // `entities.roles` may be a boolean (`true`) in drizzle-kit config; in that
+  // form there are no role options to preserve, so we only merge the object
+  // form. The `provider: "supabase"` flag below is always enforced regardless.
+  const roleOverrides =
+    typeof entities?.roles === "object" ? entities.roles : {}
+
+  return defineConfig({
+    dbCredentials: { url: process.env.SUPABASE_DATABASE_URL ?? "" },
+    dialect: "postgresql",
+    // Tells drizzle-kit that Supabase's built-in roles (anon, authenticated,
+    // service_role, ...) already exist — don't try to CREATE or DROP them.
+    entities: {
+      ...entities,
+      roles: { ...roleOverrides, provider: "supabase" },
+    },
+    out: "./supabase/migrations",
+    schema: "./src/schema.ts",
+    ...configOverrides,
+  } as Config)
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// biome-ignore lint/performance/noBarrelFile: public package entrypoint
+export {
+  type CreateClientConfig,
+  createAdminClient,
+  createAnonClient,
+  createAuthClient,
+  createServiceClient,
+  createSupabaseClient,
+  type DrizzleClient,
+  type SupabaseToken,
+} from "./clients.ts"

package/src/rls-query-client.ts

@@ -0,0 +1,100 @@
+// The lazy "record a query chain, then replay it inside one RLS transaction"
+// client returned by `createSupabaseDrizzle`. Kept separate from `clients.ts`
+// because it depends only on the `runTransaction`/`close` callbacks passed in —
+// it knows nothing about pools, Supabase, or drizzle.
+
+// One recorded step of a chained call: `db.select` is a get, the following `()`
+// is an apply.
+type AsUserChainStep =
+  | { kind: "get"; prop: PropertyKey }
+  | { kind: "apply"; args: unknown[] }
+
+// Walk the recorded chain against the live transaction `tx`, tracking the
+// receiver so methods are invoked with the right `this`. Returns whatever the
+// chain produces — a thenable drizzle builder, or a relational query promise.
+function replayAsUserChain(tx: unknown, path: AsUserChainStep[]): unknown {
+  let receiver: unknown = tx
+  let current: unknown = tx
+  for (const step of path) {
+    if (step.kind === "get") {
+      receiver = current
+      current = (current as Record<PropertyKey, unknown>)[step.prop]
+    } else {
+      current = (current as (...args: unknown[]) => unknown).apply(
+        receiver,
+        step.args
+      )
+    }
+  }
+  return current
+}
+
+const PROMISE_METHODS = new Set<PropertyKey>(["then", "catch", "finally"])
+
+// Awaiting a recorded chain triggers the transaction + replay. The transaction
+// is opened lazily when the promise method is *called* (not merely accessed),
+// so probing `.then` for thenable-detection never starts a stray transaction.
+// The call returns a real promise, so any further `.then`/`.catch`/`.finally`
+// chaining runs on it.
+function replayPromiseMethod(
+  prop: PropertyKey,
+  path: AsUserChainStep[],
+  runTransaction: (transaction: (tx: unknown) => unknown) => Promise<unknown>
+) {
+  return (...promiseArgs: unknown[]) => {
+    const promise = runTransaction((tx) => replayAsUserChain(tx, path))
+    return (
+      promise[prop as keyof Promise<unknown>] as (...args: unknown[]) => unknown
+    ).apply(promise, promiseArgs)
+  }
+}
+
+// Builds the RLS query client returned by `createSupabaseDrizzle`. Querying it
+// records the get/apply chain lazily; only when the chain is awaited
+// (`.then`/`.catch`/`.finally`) does it open an RLS transaction and replay the
+// chain against that transaction's `tx`. Each awaited chain is its own
+// transaction. `db.transaction(cb)` runs several statements in one transaction,
+// and `db.close()` releases the pools. The root itself is intentionally not
+// thenable and not callable.
+export function createRlsQueryClient(
+  runTransaction: (transaction: (tx: unknown) => unknown) => Promise<unknown>,
+  close: (...args: never[]) => Promise<void>
+): unknown {
+  const build = (path: AsUserChainStep[], isRoot: boolean): unknown => {
+    // The proxy target must be callable so the `apply` trap fires for `()`.
+    const target = () => undefined
+    return new Proxy(target, {
+      apply(_target, _thisArg, args: unknown[]) {
+        if (isRoot) {
+          throw new Error(
+            "The createSupabaseDrizzle() client is queried directly (e.g. db.select().from(table)). Use db.transaction(cb) to run multiple statements in one RLS transaction."
+          )
+        }
+        return build([...path, { args, kind: "apply" }], false)
+      },
+      get(_target, prop) {
+        // Multi-statement RLS transaction and pool release live on the root.
+        if (isRoot && prop === "transaction") {
+          return runTransaction
+        }
+        if (isRoot && prop === "close") {
+          return close
+        }
+        if (PROMISE_METHODS.has(prop)) {
+          // Root stays a plain (non-thenable) object so `await db` / probes
+          // never open a stray transaction; recorded chains are awaitable.
+          return isRoot
+            ? undefined
+            : replayPromiseMethod(prop, path, runTransaction)
+        }
+        // Ignore symbol probes (inspection, `Symbol.toPrimitive`, etc.) so they
+        // are not recorded as part of the query chain.
+        if (typeof prop === "symbol") {
+          return
+        }
+        return build([...path, { kind: "get", prop }], false)
+      },
+    })
+  }
+  return build([], true)
+}

package/src/schema.ts

@@ -0,0 +1,187 @@
+// https://orm.drizzle.team/docs/rls#using-with-supabase  (re-exported roles, authUsers, authUid, realtimeMessages)
+import { sql } from "drizzle-orm"
+import {
+  type AnyPgColumn,
+  integer,
+  type PgPolicyConfig,
+  pgPolicy,
+  timestamp,
+  uuid,
+} from "drizzle-orm/pg-core"
+import { snakeCase } from "drizzle-orm/pg-core/casing"
+import { authenticatedRole, authUid, authUsers } from "drizzle-orm/supabase"
+
+// Curated pg-core aliases for schema primitives that otherwise repeat the pg
+// prefix at every call site. `table` is Zeno's RLS-by-default helper below.
+// biome-ignore lint/performance/noBarrelFile: intentional public re-export surface
+export {
+  isPgEnum as isEnum,
+  isPgMaterializedView as isMaterializedView,
+  isPgSchema as isSchema,
+  isPgSequence as isSequence,
+  isPgView as isView,
+  pgEnum as enum,
+  pgMaterializedView as materializedView,
+  pgPolicy as policy,
+  pgRole as role,
+  pgSchema as schema,
+  pgSequence as sequence,
+  pgTableCreator as tableCreator,
+  pgView as view,
+} from "drizzle-orm/pg-core"
+
+// Curated Supabase primitives from drizzle-orm/supabase so consumers can import
+// roles, the auth.users table, and helpers from one Zeno-owned schema entrypoint.
+export {
+  anonRole,
+  authenticatedRole,
+  authUid,
+  authUsers,
+  postgresRole,
+  realtimeMessages,
+  realtimeTopic,
+  serviceRole,
+  supabaseAuthAdminRole,
+} from "drizzle-orm/supabase"
+
+// Reusable created_at / updated_at columns — spread into a pgTable column map.
+export const timestamps = {
+  createdAt: timestamp("created_at", { withTimezone: true })
+    .notNull()
+    .defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true })
+    .notNull()
+    .defaultNow()
+    .$onUpdate(() => new Date()),
+}
+
+export const authUserId = (name?: string) =>
+  uuid(name)
+    .notNull()
+    .references(() => authUsers.id)
+
+export const createdBy = authUserId("created_by").default(authUid)
+export const updatedBy = authUserId("updated_by")
+  .default(authUid)
+  .$onUpdate(() => authUid)
+
+export const authorship = {
+  createdBy,
+  updatedBy,
+}
+
+export const auditColumns = {
+  ...timestamps,
+  ...authorship,
+}
+
+const uuidPrimaryId = () => uuid("id").primaryKey().defaultRandom()
+const sequentialPrimaryId = () =>
+  integer("id").primaryKey().generatedAlwaysAsIdentity()
+
+export function primaryId(kind?: "uuid"): ReturnType<typeof uuidPrimaryId>
+export function primaryId(
+  kind: "sequential"
+): ReturnType<typeof sequentialPrimaryId>
+export function primaryId(kind: "uuid" | "sequential" = "uuid") {
+  return kind === "sequential" ? sequentialPrimaryId() : uuidPrimaryId()
+}
+
+type PolicyOptions = Omit<PgPolicyConfig, "for">
+type PolicyOperation = NonNullable<PgPolicyConfig["for"]>
+
+function operationPolicy(
+  name: string,
+  operation: PolicyOperation,
+  config: PolicyOptions = {}
+) {
+  return pgPolicy(name, { ...config, for: operation })
+}
+
+export const selectPolicy = (name: string, config: PolicyOptions = {}) =>
+  operationPolicy(name, "select", config)
+
+export const insertPolicy = (name: string, config: PolicyOptions = {}) =>
+  operationPolicy(name, "insert", config)
+
+export const updatePolicy = (name: string, config: PolicyOptions = {}) =>
+  operationPolicy(name, "update", config)
+
+export const deletePolicy = (name: string, config: PolicyOptions = {}) =>
+  operationPolicy(name, "delete", config)
+
+export const allPolicy = (name: string, config: PolicyOptions = {}) =>
+  operationPolicy(name, "all", config)
+
+export const authUserOwns = (ownerColumn: AnyPgColumn) =>
+  sql`${ownerColumn} = ${authUid}`
+
+type OwnerPolicyOptions = Omit<PgPolicyConfig, "for" | "to">
+
+export const authenticatedOwnerSelectPolicy = (
+  name: string,
+  ownerColumn: AnyPgColumn,
+  config: OwnerPolicyOptions = {}
+) =>
+  selectPolicy(name, {
+    ...config,
+    to: authenticatedRole,
+    using: config.using ?? authUserOwns(ownerColumn),
+  })
+
+export const authenticatedOwnerInsertPolicy = (
+  name: string,
+  ownerColumn: AnyPgColumn,
+  config: OwnerPolicyOptions = {}
+) =>
+  insertPolicy(name, {
+    ...config,
+    to: authenticatedRole,
+    withCheck: config.withCheck ?? authUserOwns(ownerColumn),
+  })
+
+export const authenticatedOwnerUpdatePolicy = (
+  name: string,
+  ownerColumn: AnyPgColumn,
+  config: OwnerPolicyOptions = {}
+) => {
+  const ownerCondition = authUserOwns(ownerColumn)
+  return updatePolicy(name, {
+    ...config,
+    to: authenticatedRole,
+    using: config.using ?? ownerCondition,
+    withCheck: config.withCheck ?? ownerCondition,
+  })
+}
+
+export const authenticatedOwnerDeletePolicy = (
+  name: string,
+  ownerColumn: AnyPgColumn,
+  config: OwnerPolicyOptions = {}
+) =>
+  deletePolicy(name, {
+    ...config,
+    to: authenticatedRole,
+    using: config.using ?? authUserOwns(ownerColumn),
+  })
+
+export const authenticatedOwnerAllPolicy = (
+  name: string,
+  ownerColumn: AnyPgColumn,
+  config: OwnerPolicyOptions = {}
+) => {
+  const ownerCondition = authUserOwns(ownerColumn)
+  return allPolicy(name, {
+    ...config,
+    to: authenticatedRole,
+    using: config.using ?? ownerCondition,
+    withCheck: config.withCheck ?? ownerCondition,
+  })
+}
+
+// Default table helper for application-owned tables: TypeScript columns stay
+// camelCase, database identifiers become snake_case, and RLS is enabled.
+export const table = snakeCase.table.withRLS
+
+// Escape hatch for intentionally non-RLS tables such as seed/reference data.
+export const unsecureTable = snakeCase.table