@zeno-lib/db 0.3.2 → 0.5.0

package/src/next.test.ts

@@ -0,0 +1,296 @@
+import { AuthError, type JwtPayload } from "@supabase/supabase-js"
+import { beforeEach, describe, expect, it, vi } from "vitest"
+import { z } from "zod"
+import { FieldValidationError } from "./action-result.ts"
+import { createDefineAction, createDefineFormAction } from "./define-action.ts"
+
+// No database: the RLS client factory is replaced by a stub that returns a
+// marker object, so nothing here builds a pool or opens a connection. What
+// that client does with the claims is covered by test/rls.integration.test.ts.
+const { createSupabaseClientMock } = vi.hoisted(() => ({
+  createSupabaseClientMock: vi.fn((claims: unknown) => ({
+    claims,
+    fake: true,
+  })),
+}))
+
+vi.mock("./clients.ts", () => ({
+  createSupabaseClient: createSupabaseClientMock,
+}))
+
+import {
+  type ClaimsSource,
+  createRequestDb,
+  UnauthenticatedError,
+} from "./next.ts"
+
+const claims: JwtPayload = {
+  aal: "aal1",
+  aud: "authenticated",
+  exp: 0,
+  iat: 0,
+  iss: "test",
+  role: "authenticated",
+  roles: ["admin"],
+  session_id: "session",
+  sub: "11111111-1111-1111-1111-111111111111",
+}
+
+type GetClaimsResult = Awaited<ReturnType<ClaimsSource["auth"]["getClaims"]>>
+
+function getClaimsResult(
+  payload: JwtPayload | null,
+  error: AuthError | null
+): GetClaimsResult {
+  if (payload) {
+    return {
+      data: {
+        claims: payload,
+        header: { alg: "HS256", kid: "test", typ: "JWT" },
+        signature: new Uint8Array(),
+      },
+      error: null,
+    }
+  }
+  return error ? { data: null, error } : { data: null, error: null }
+}
+
+function supabaseReturning(result: GetClaimsResult): () => ClaimsSource {
+  return () => ({ auth: { getClaims: () => Promise.resolve(result) } })
+}
+
+beforeEach(() => {
+  createSupabaseClientMock.mockClear()
+})
+
+describe("defineAction", () => {
+  const schema = z.object({ id: z.number().int().positive() }).strict()
+
+  it("parses the input, then calls the handler with db, parsed input and context", async () => {
+    const context = { claims: { sub: "user-1" }, db: { name: "db" } }
+    const getContext = vi.fn(() => Promise.resolve(context))
+    const handler = vi.fn((db: { name: string }, input: { id: number }) =>
+      Promise.resolve(`${db.name}:${input.id}`)
+    )
+
+    const action = createDefineAction(getContext)(schema, handler)
+
+    await expect(action({ id: 7 })).resolves.toBe("db:7")
+    expect(handler).toHaveBeenCalledWith(context.db, { id: 7 }, context)
+  })
+
+  it("hands the handler the claims for authorship", async () => {
+    const context = { claims: { sub: "user-1" }, db: {} }
+    const action = createDefineAction(() => Promise.resolve(context))(
+      schema,
+      (_db, input, { claims: { sub } }) => ({ createdBy: sub, ...input })
+    )
+
+    await expect(action({ id: 1 })).resolves.toEqual({
+      createdBy: "user-1",
+      id: 1,
+    })
+  })
+
+  it("rejects invalid input before resolving the context or calling the handler", async () => {
+    const getContext = vi.fn(() => Promise.resolve({ db: {} }))
+    const handler = vi.fn()
+    const action = createDefineAction(getContext)(schema, handler)
+
+    await expect(action({ id: -1 })).rejects.toBeInstanceOf(z.ZodError)
+    expect(getContext).not.toHaveBeenCalled()
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it("propagates a context failure without calling the handler", async () => {
+    const handler = vi.fn()
+    const action = createDefineAction(() =>
+      Promise.reject(new UnauthenticatedError())
+    )(schema, handler)
+
+    await expect(action({ id: 1 })).rejects.toBeInstanceOf(UnauthenticatedError)
+    expect(handler).not.toHaveBeenCalled()
+  })
+})
+
+describe("defineFormAction", () => {
+  const schema = z.object({
+    owners: z.array(
+      z.object({ percentage: z.number().max(100, "At most 100") })
+    ),
+  })
+  const context = { claims: { sub: "user-1" }, db: { name: "db" } }
+
+  it("resolves to { ok: true, data } with the handler's result", async () => {
+    const handler = vi.fn(
+      (_db: { name: string }, input: z.output<typeof schema>) =>
+        Promise.resolve(input.owners.length)
+    )
+    const action = createDefineFormAction(() => Promise.resolve(context))(
+      schema,
+      handler
+    )
+
+    await expect(action({ owners: [{ percentage: 50 }] })).resolves.toEqual({
+      data: 1,
+      ok: true,
+    })
+    expect(handler).toHaveBeenCalledWith(
+      context.db,
+      { owners: [{ percentage: 50 }] },
+      context
+    )
+  })
+
+  it("returns schema issues keyed by field name, before resolving the context", async () => {
+    const getContext = vi.fn(() => Promise.resolve(context))
+    const handler = vi.fn()
+    const action = createDefineFormAction(getContext)(schema, handler)
+
+    await expect(
+      action({ owners: [{ percentage: 10 }, { percentage: 150 }] })
+    ).resolves.toEqual({
+      error: {
+        fieldErrors: { "owners[1].percentage": ["At most 100"] },
+        formErrors: [],
+      },
+      ok: false,
+    })
+    expect(getContext).not.toHaveBeenCalled()
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it("returns a FieldValidationError thrown by the handler in the same shape", async () => {
+    const action = createDefineFormAction(() => Promise.resolve(context))(
+      schema,
+      () => {
+        throw new FieldValidationError(
+          { "owners[0].percentage": "Already allocated" },
+          { formErrors: "Record is locked" }
+        )
+      }
+    )
+
+    await expect(action({ owners: [{ percentage: 1 }] })).resolves.toEqual({
+      error: {
+        fieldErrors: { "owners[0].percentage": ["Already allocated"] },
+        formErrors: ["Record is locked"],
+      },
+      ok: false,
+    })
+  })
+
+  it("keeps a failure that is not a validation error throwing", async () => {
+    const boom = new Error("connection reset")
+    const action = createDefineFormAction(() => Promise.resolve(context))(
+      schema,
+      () => Promise.reject(boom)
+    )
+
+    await expect(action({ owners: [] })).rejects.toBe(boom)
+  })
+
+  it("keeps a context failure throwing", async () => {
+    const handler = vi.fn()
+    const action = createDefineFormAction(() =>
+      Promise.reject(new UnauthenticatedError())
+    )(schema, handler)
+
+    await expect(action({ owners: [] })).rejects.toBeInstanceOf(
+      UnauthenticatedError
+    )
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it("returns a result that survives a JSON round trip unchanged", async () => {
+    const action = createDefineFormAction(() => Promise.resolve(context))(
+      schema,
+      () => ({ id: 1 })
+    )
+    const failure = await action({ owners: [{ percentage: 101 }] })
+    const success = await action({ owners: [] })
+
+    expect(JSON.parse(JSON.stringify(failure))).toEqual(failure)
+    expect(JSON.parse(JSON.stringify(success))).toEqual(success)
+  })
+})
+
+describe("createRequestDb", () => {
+  it("builds the RLS client from the whole verified claims object", async () => {
+    const { getRequestContext, getRequestDb } = createRequestDb({
+      connectionString: () => "postgresql://lazy",
+      supabase: supabaseReturning(getClaimsResult(claims, null)),
+    })
+
+    const context = await getRequestContext()
+
+    expect(context.claims).toBe(claims)
+    expect(createSupabaseClientMock).toHaveBeenCalledWith(claims, {
+      connectionString: "postgresql://lazy",
+    })
+    await expect(getRequestDb()).resolves.toEqual({ claims, fake: true })
+  })
+
+  it("throws UnauthenticatedError when there is no session", async () => {
+    const { getRequestDb } = createRequestDb({
+      supabase: supabaseReturning(getClaimsResult(null, null)),
+    })
+
+    const error = await getRequestDb().catch((caught: unknown) => caught)
+
+    expect(error).toBeInstanceOf(UnauthenticatedError)
+    expect(error).toHaveProperty("name", "UnauthenticatedError")
+    expect(createSupabaseClientMock).not.toHaveBeenCalled()
+  })
+
+  it("throws UnauthenticatedError for claims without a subject", async () => {
+    const { getRequestDb } = createRequestDb({
+      supabase: supabaseReturning(
+        getClaimsResult({ ...claims, sub: "" }, null)
+      ),
+    })
+
+    await expect(getRequestDb()).rejects.toBeInstanceOf(UnauthenticatedError)
+  })
+
+  it("rethrows a getClaims error as is", async () => {
+    const failure = new AuthError("jwks unreachable")
+    const { getRequestDb } = createRequestDb({
+      supabase: supabaseReturning(getClaimsResult(null, failure)),
+    })
+
+    await expect(getRequestDb()).rejects.toBe(failure)
+  })
+
+  it("binds defineAction to the request context", async () => {
+    const { defineAction } = createRequestDb({
+      supabase: supabaseReturning(getClaimsResult(claims, null)),
+    })
+    const action = defineAction(z.string(), (db, input, context) => ({
+      db,
+      input,
+      sub: context.claims.sub,
+    }))
+
+    await expect(action("hello")).resolves.toEqual({
+      db: { claims, fake: true },
+      input: "hello",
+      sub: claims.sub,
+    })
+  })
+
+  it("binds defineFormAction to the request context", async () => {
+    const { defineFormAction } = createRequestDb({
+      supabase: supabaseReturning(getClaimsResult(claims, null)),
+    })
+    const action = defineFormAction(z.string(), (_db, input, context) => ({
+      input,
+      sub: context.claims.sub,
+    }))
+
+    await expect(action("hello")).resolves.toEqual({
+      data: { input: "hello", sub: claims.sub },
+      ok: true,
+    })
+  })
+})

package/src/next.ts

@@ -0,0 +1,134 @@
+import type { JwtPayload, SupabaseClient } from "@supabase/supabase-js"
+import type { AnyRelations, EmptyRelations } from "drizzle-orm"
+import { cache } from "react"
+import {
+  type CreateClientConfig,
+  createSupabaseClient,
+  type DrizzleClient,
+} from "./clients.ts"
+import {
+  createDefineAction,
+  createDefineFormAction,
+  type DefineAction,
+  type DefineFormAction,
+} from "./define-action.ts"
+
+// biome-ignore lint/performance/noBarrelFile: `/next` is the one entry server actions import; the result types and error class belong on it.
+export {
+  type ActionError,
+  type ActionIssue,
+  type ActionResult,
+  FieldValidationError,
+  toActionError,
+  toFieldName,
+} from "./action-result.ts"
+export type {
+  ActionContext,
+  ActionHandler,
+  ActionSchema,
+  DefineAction,
+  DefineFormAction,
+  FormActionSchema,
+} from "./define-action.ts"
+
+/**
+ * Thrown when a request carries no verified session. A named class so a caller
+ * with a legitimate answer for that case (a permission check, where "not signed
+ * in" means "no") can tell it apart from a real failure with `instanceof`.
+ */
+export class UnauthenticatedError extends Error {
+  constructor(message = "Unauthorized: no verified session on this request") {
+    super(message)
+    this.name = "UnauthenticatedError"
+  }
+}
+
+/** The only part of a Supabase client the request context reads. */
+export type ClaimsSource = { auth: Pick<SupabaseClient["auth"], "getClaims"> }
+
+/** A verified request: the full `getClaims()` payload and the RLS client. */
+export type RequestContext<TRelations extends AnyRelations = EmptyRelations> = {
+  readonly claims: JwtPayload
+  readonly db: DrizzleClient<TRelations>
+}
+
+export type CreateRequestDbOptions<
+  TRelations extends AnyRelations = EmptyRelations,
+> = Omit<CreateClientConfig<TRelations>, "connectionString"> & {
+  /**
+   * Builds the request's Supabase client, e.g. `createClient` from
+   * `@zeno-lib/supabase/next-server` (cookie session via `next/headers`).
+   */
+  supabase: () => ClaimsSource | Promise<ClaimsSource>
+  /**
+   * Overrides `SUPABASE_DATABASE_URL`. A function is resolved per request, not
+   * at import, so a build without server secrets can still import the module.
+   */
+  connectionString?: string | (() => string)
+}
+
+export type RequestDb<TRelations extends AnyRelations = EmptyRelations> = {
+  /** Memoised per render: `{ claims, db }` for the verified caller. */
+  getRequestContext: () => Promise<RequestContext<TRelations>>
+  /** The common case: just the RLS-bound client. */
+  getRequestDb: () => Promise<DrizzleClient<TRelations>>
+  /** Wraps a handler into a `"use server"` export; see `DefineAction`. */
+  defineAction: DefineAction<RequestContext<TRelations>>
+  /**
+   * `defineAction` for forms: resolves to an `ActionResult` instead of
+   * throwing on invalid input; see `DefineFormAction`.
+   */
+  defineFormAction: DefineFormAction<RequestContext<TRelations>>
+}
+
+/**
+ * Request-scoped, RLS-bound Drizzle access for Next.js. Verifies the session
+ * with `getClaims()` (which checks the signature) and installs the **whole**
+ * claims object, so custom claims reach `auth.jwt()` in policies. There is no
+ * fallback to `anon`: a caller without a verified `sub` gets
+ * `UnauthenticatedError` rather than the empty result of a policy it never
+ * satisfied.
+ *
+ * `getRequestContext` is wrapped in React's `cache`, so one server render shares
+ * one verification and one handle. A server action invoked from the browser
+ * runs outside a render and resolves afresh on every call.
+ *
+ * Do not `close()` the handle: pools are shared and reference-counted.
+ */
+export function createRequestDb<
+  TRelations extends AnyRelations = EmptyRelations,
+>(options: CreateRequestDbOptions<TRelations>): RequestDb<TRelations> {
+  const { connectionString, supabase, ...config } = options
+
+  const getRequestContext = cache(
+    async (): Promise<RequestContext<TRelations>> => {
+      const client = await supabase()
+      const { data, error } = await client.auth.getClaims()
+
+      if (error) {
+        throw error
+      }
+      if (!data?.claims.sub) {
+        throw new UnauthenticatedError()
+      }
+
+      const url =
+        typeof connectionString === "function"
+          ? connectionString()
+          : connectionString
+      const db = createSupabaseClient<TRelations>(
+        data.claims,
+        url === undefined ? config : { ...config, connectionString: url }
+      )
+
+      return { claims: data.claims, db }
+    }
+  )
+
+  return {
+    defineAction: createDefineAction(getRequestContext),
+    defineFormAction: createDefineFormAction(getRequestContext),
+    getRequestContext,
+    getRequestDb: async () => (await getRequestContext()).db,
+  }
+}

package/src/query.test-d.ts

@@ -0,0 +1,20 @@
+import { defineRelations } from "drizzle-orm"
+import type { PgAsyncDatabase, PgAsyncTransaction } from "drizzle-orm/pg-core"
+import type { PostgresJsQueryResultHKT } from "drizzle-orm/postgres-js"
+import { expectTypeOf, test } from "vitest"
+import type { DrizzleClient } from "./clients.ts"
+import type { QueryExecutor } from "./query.ts"
+import { primaryId, table } from "./schema.ts"
+
+const posts = table("posts", { id: primaryId("sequential") })
+const relations = defineRelations({ posts })
+
+test("selectFunctionPermissions takes every client and transaction shape", () => {
+  expectTypeOf<DrizzleClient<typeof relations>>().toExtend<QueryExecutor>()
+  expectTypeOf<
+    PgAsyncDatabase<PostgresJsQueryResultHKT, typeof relations>
+  >().toExtend<QueryExecutor>()
+  expectTypeOf<
+    PgAsyncTransaction<PostgresJsQueryResultHKT, typeof relations>
+  >().toExtend<QueryExecutor>()
+})