@zeno-lib/db 0.3.2 → 0.4.0

package/src/casing.test.ts

@@ -1,4 +1,4 @@
-import { getTableColumns, type SQL, sql } from "drizzle-orm"
+import { getTableColumns, is, type SQL, sql } from "drizzle-orm"
 import {
   bigint,
   getTableConfig,
@@ -8,6 +8,7 @@ import {
   isPgSequence,
   isPgView,
   PgDialect,
+  PgTimestampString,
   pgEnum,
   pgMaterializedView,
   pgPolicy,
@@ -507,6 +508,28 @@ describe("default casing", () => {
     )
   })
 
+  it("reads timestamps back as strings with mode: string, emitting the same type", () => {
+    const dated = getTableColumns(table("dated", { ...timestamps() }))
+    const stringly = getTableColumns(
+      table("stringly", { ...timestamps({ mode: "string", precision: 6 }) })
+    )
+    const audited = getTableColumns(
+      table("audited", { ...auditColumns({ mode: "string" }) })
+    )
+
+    expect(is(dated.createdAt, PgTimestampString)).toBe(false)
+    expect(is(stringly.createdAt, PgTimestampString)).toBe(true)
+    expect(is(stringly.updatedAt, PgTimestampString)).toBe(true)
+    expect(is(audited.createdAt, PgTimestampString)).toBe(true)
+    // drizzle spaces the precision differently per mode ("timestamp (6)" vs
+    // "timestamp(6)"); Postgres reads both as the same type.
+    expect(stringly.createdAt.getSQLType().replace(" (", "(")).toBe(
+      "timestamp(6) with time zone"
+    )
+    expect(stringly.updatedAt.notNull).toBe(true)
+    expect(stringly.updatedAt.default).toBeDefined()
+  })
+
   it("exports grouped audit column mixins", () => {
     expect(Object.keys(timestamps())).toEqual(["createdAt", "updatedAt"])
     expect(Object.keys(authorship())).toEqual(["createdBy", "updatedBy"])
@@ -751,45 +774,45 @@ describe("default casing", () => {
   })
 
   it("varies the argument per operation, insert usually taking none", () => {
-    const deals = table(
-      "deals",
+    const projects = table(
+      "projects",
       { id: primaryId("assigned"), ownerId: uuid() },
       (t) => functionPolicies(t, { argument: { delete: t.id, select: t.id } })
     )
-    const policies = getTableConfig(deals).policies
+    const policies = getTableConfig(projects).policies
     const dialect = new PgDialect()
 
     // select and delete get the row; insert and update fall to no arguments,
     // insert because a missing key means "called with none" and update because
     // it was left out of the record too.
     expect(dialect.sqlToQuery(policies[0]?.using as SQL).sql).toBe(
-      '(select "can_select_deals"("deals"."id"))'
+      '(select "can_select_projects"("projects"."id"))'
     )
     expect(dialect.sqlToQuery(policies[1]?.withCheck as SQL).sql).toBe(
-      '(select "can_insert_deals"())'
+      '(select "can_insert_projects"())'
     )
     expect(dialect.sqlToQuery(policies[2]?.using as SQL).sql).toBe(
-      '(select "can_update_deals"())'
+      '(select "can_update_projects"())'
     )
     expect(dialect.sqlToQuery(policies[3]?.using as SQL).sql).toBe(
-      '(select "can_delete_deals"("deals"."id"))'
+      '(select "can_delete_projects"("projects"."id"))'
     )
   })
 
   it("reads an explicit null as a call with no arguments", () => {
-    const deals = table("deals", { id: primaryId("assigned") }, (t) =>
+    const projects = table("projects", { id: primaryId("assigned") }, (t) =>
       functionPolicies(t, { argument: { insert: null, select: t.id } })
     )
-    const policies = getTableConfig(deals).policies
+    const policies = getTableConfig(projects).policies
 
     expect(new PgDialect().sqlToQuery(policies[1]?.withCheck as SQL).sql).toBe(
-      '(select "can_insert_deals"())'
+      '(select "can_insert_projects"())'
     )
   })
 
   it("passes several columns to a function that takes several", () => {
-    const investors = table(
-      "investors",
+    const memberships = table(
+      "memberships",
       {
         id: primaryId("uuid"),
         organisationId: bigint({ mode: "number" }),
@@ -797,22 +820,22 @@ describe("default casing", () => {
       },
       (t) => functionPolicies(t, { argument: [t.profileId, t.organisationId] })
     )
-    const policies = getTableConfig(investors).policies
+    const policies = getTableConfig(memberships).policies
 
     expect(new PgDialect().sqlToQuery(policies[0]?.using as SQL).sql).toBe(
-      '(select "can_select_investors"("investors"."profile_id", "investors"."organisation_id"))'
+      '(select "can_select_memberships"("memberships"."profile_id", "memberships"."organisation_id"))'
     )
   })
 
   it("qualifies the function with a schema when one is given", () => {
-    const bexio = schema("bexio")
-    const bills = bexio.table("bexio_bills", { id: primaryId("uuid") }, (t) =>
-      functionPolicies(t, { schema: "bexio" })
+    const billing = schema("billing")
+    const invoices = billing.table("invoices", { id: primaryId("uuid") }, (t) =>
+      functionPolicies(t, { schema: "billing" })
     )
-    const policies = getTableConfig(bills).policies
+    const policies = getTableConfig(invoices).policies
 
     expect(new PgDialect().sqlToQuery(policies[0]?.using as SQL).sql).toBe(
-      '(select "bexio"."can_select_bexio_bills"())'
+      '(select "billing"."can_select_invoices"())'
     )
   })
 })

package/src/clients.ts

@@ -21,6 +21,64 @@ export type CreateClientConfig<
 > = DrizzlePgConfig<TRelations> & {
   /** Overrides `process.env.SUPABASE_DATABASE_URL`. */
   connectionString?: string
+  /**
+   * Require the Supabase transaction pooler: port 6543 on a non-local host.
+   * Pass `true` in production (e.g. `process.env.VERCEL_ENV === "production"`)
+   * to fail at client creation rather than exhaust connections under load.
+   * Default `false`, which checks only that a URL is present.
+   */
+  requirePooler?: boolean
+}
+
+export type ResolveDatabaseUrlOptions = Pick<
+  CreateClientConfig,
+  "connectionString" | "requirePooler"
+>
+
+const POOLER_PORT = "6543"
+const LOCAL_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]", "0.0.0.0"])
+
+/**
+ * The connection string every factory uses: `connectionString`, else
+ * `SUPABASE_DATABASE_URL`. Throws when neither is set, and with
+ * `requirePooler` also when the URL is not the transaction pooler. Read per
+ * call, never at import, so a build without server secrets does not fail.
+ * Errors never echo the URL, which carries the password.
+ */
+export function resolveDatabaseUrl({
+  connectionString,
+  requirePooler = false,
+}: ResolveDatabaseUrlOptions = {}): string {
+  const url = connectionString ?? process.env.SUPABASE_DATABASE_URL ?? ""
+  if (!url) {
+    throw new Error("Missing SUPABASE_DATABASE_URL environment variable")
+  }
+  if (!requirePooler) {
+    return url
+  }
+
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    throw new Error("SUPABASE_DATABASE_URL is not a valid URL")
+  }
+  if (parsed.protocol !== "postgresql:" && parsed.protocol !== "postgres:") {
+    throw new Error(
+      `SUPABASE_DATABASE_URL must be a postgresql:// URL, got ${parsed.protocol}//`
+    )
+  }
+  if (LOCAL_HOSTS.has(parsed.hostname)) {
+    throw new Error(
+      "SUPABASE_DATABASE_URL points at a local database, but the transaction pooler is required"
+    )
+  }
+  if (parsed.port !== POOLER_PORT) {
+    throw new Error(
+      `SUPABASE_DATABASE_URL must use the transaction pooler (port ${POOLER_PORT}), got port ${parsed.port || "(default)"}. Session mode holds one connection per instance for its whole lifetime.`
+    )
+  }
+  return url
 }
 
 // A directly-queryable Drizzle client plus a reference-counted `close()`.
@@ -108,11 +166,8 @@ 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 { connectionString, requirePooler, ...drizzleConfig } = config ?? {}
+  const url = resolveDatabaseUrl({ connectionString, requirePooler })
   const entry = acquirePool(url, kind)
   const db = drizzle<TRelations>({
     client: entry.client,

package/src/database-url.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { createAdminClient, resolveDatabaseUrl } from "./clients.ts"
+
+// Pure string checks: nothing here builds a pool or opens a socket, except the
+// last test, which only reaches the check (it throws before `postgres()`).
+const POOLER =
+  "postgresql://postgres.ref:secret@aws-0-eu-central-1.pooler.supabase.com:6543/postgres"
+const SESSION =
+  "postgresql://postgres.ref:secret@aws-0-eu-central-1.pooler.supabase.com:5432/postgres"
+const LOCAL = "postgresql://postgres:postgres@127.0.0.1:54322/postgres"
+
+beforeEach(() => {
+  vi.stubEnv("SUPABASE_DATABASE_URL", undefined)
+})
+
+afterEach(() => {
+  vi.unstubAllEnvs()
+})
+
+describe("resolveDatabaseUrl", () => {
+  it("prefers the override, then the environment", () => {
+    vi.stubEnv("SUPABASE_DATABASE_URL", LOCAL)
+    expect(resolveDatabaseUrl()).toBe(LOCAL)
+    expect(resolveDatabaseUrl({ connectionString: POOLER })).toBe(POOLER)
+  })
+
+  it("throws when neither is set", () => {
+    expect(() => resolveDatabaseUrl()).toThrow(
+      "Missing SUPABASE_DATABASE_URL environment variable"
+    )
+  })
+
+  it("accepts any URL without requirePooler, as before", () => {
+    expect(resolveDatabaseUrl({ connectionString: LOCAL })).toBe(LOCAL)
+    expect(resolveDatabaseUrl({ connectionString: SESSION })).toBe(SESSION)
+  })
+
+  it("accepts the transaction pooler with requirePooler", () => {
+    expect(
+      resolveDatabaseUrl({ connectionString: POOLER, requirePooler: true })
+    ).toBe(POOLER)
+  })
+
+  it("rejects another port with requirePooler, without echoing the URL", () => {
+    const check = () =>
+      resolveDatabaseUrl({ connectionString: SESSION, requirePooler: true })
+
+    expect(check).toThrow("port 6543), got port 5432")
+    expect(check).not.toThrow("secret")
+  })
+
+  it("rejects a missing port with requirePooler", () => {
+    expect(() =>
+      resolveDatabaseUrl({
+        connectionString: "postgresql://u:p@db.example.com/postgres",
+        requirePooler: true,
+      })
+    ).toThrow("got port (default)")
+  })
+
+  it.each([
+    LOCAL,
+    "postgresql://u:p@localhost:6543/postgres",
+    "postgresql://u:p@[::1]:6543/postgres",
+  ])("rejects a local host with requirePooler: %s", (connectionString) => {
+    expect(() =>
+      resolveDatabaseUrl({ connectionString, requirePooler: true })
+    ).toThrow("points at a local database")
+  })
+
+  it("rejects a non-postgres URL with requirePooler", () => {
+    expect(() =>
+      resolveDatabaseUrl({
+        connectionString: "https://db.example.com:6543",
+        requirePooler: true,
+      })
+    ).toThrow("must be a postgresql:// URL")
+    expect(() =>
+      resolveDatabaseUrl({ connectionString: "not a url", requirePooler: true })
+    ).toThrow("is not a valid URL")
+  })
+
+  it("is what the factories run", () => {
+    expect(() =>
+      createAdminClient({ connectionString: LOCAL, requirePooler: true })
+    ).toThrow("points at a local database")
+  })
+})

package/src/define-action.ts

@@ -0,0 +1,63 @@
+/**
+ * The slice of a schema `defineAction` needs: a throwing `parse`, plus the
+ * Standard Schema `types` marker it reads the caller-facing input type from.
+ * Zod 4 schemas satisfy it as they are; so does anything else that implements
+ * Standard Schema and exposes `parse`.
+ */
+export interface ActionSchema<TInput, TOutput> {
+  readonly "~standard": {
+    readonly types?:
+      | { readonly input: TInput; readonly output: TOutput }
+      | undefined
+  }
+  parse(input: unknown): TOutput
+}
+
+/** What a request context must carry for `defineAction` to hand it over. */
+export interface ActionContext<TDb> {
+  readonly db: TDb
+}
+
+/** An action's body: the RLS-bound `db`, the parsed input, and the context. */
+export type ActionHandler<
+  TContext extends ActionContext<unknown>,
+  TOutput,
+  TResult,
+> = (
+  db: TContext["db"],
+  input: TOutput,
+  context: TContext
+) => TResult | Promise<TResult>
+
+/**
+ * `defineAction(schema, handler)` returns the server action itself: an async
+ * function that parses its argument, resolves the request context, then calls
+ * `handler(db, input, context)`.
+ */
+export type DefineAction<TContext extends ActionContext<unknown>> = <
+  TInput,
+  TOutput,
+  TResult,
+>(
+  schema: ActionSchema<TInput, TOutput>,
+  handler: ActionHandler<TContext, TOutput, TResult>
+) => (input: TInput) => Promise<TResult>
+
+/**
+ * Binds `defineAction` to a request-context resolver. Deliberately not a
+ * `"use server"` module: it only returns a function, and the app file that
+ * exports the result is the one that carries the directive.
+ *
+ * Input is parsed before the context is resolved, so a malformed call fails
+ * without a session round trip, and the handler never sees an unparsed value.
+ */
+export function createDefineAction<TContext extends ActionContext<unknown>>(
+  getContext: () => Promise<TContext>
+): DefineAction<TContext> {
+  return (schema, handler) => async (input) => {
+    const parsed = schema.parse(input)
+    const context = await getContext()
+
+    return await handler(context.db, parsed, context)
+  }
+}

package/src/errors.test.ts

@@ -0,0 +1,95 @@
+import { DrizzleQueryError } from "drizzle-orm"
+import postgres from "postgres"
+import { describe, expect, it } from "vitest"
+import { isConstraintViolation, SqlState, toPostgresError } from "./errors.ts"
+
+// postgres.js builds its errors from a server message; this is that shape,
+// constructed directly so no server is needed.
+const postgresError = (fields: Record<string, string>) =>
+  Object.assign(new postgres.PostgresError(fields.message ?? "failed"), fields)
+
+// What Drizzle throws: the driver error as `cause`, `code` undefined.
+const wrapped = (cause: Error) =>
+  new DrizzleQueryError("insert into contacts …", [], cause)
+
+const duplicate = postgresError({
+  code: SqlState.uniqueViolation,
+  constraint_name: "contacts_email_key",
+  message: "duplicate key value violates unique constraint",
+})
+
+describe("toPostgresError", () => {
+  it("unwraps Drizzle's DrizzleQueryError", () => {
+    const error = wrapped(duplicate)
+
+    expect((error as { code?: string }).code).toBeUndefined()
+    expect(toPostgresError(error)).toBe(duplicate)
+  })
+
+  it("unwraps a second level, as a failed transaction nests", () => {
+    const outer = Object.assign(new Error("transaction failed"), {
+      cause: wrapped(duplicate),
+    })
+
+    expect(toPostgresError(outer)).toBe(duplicate)
+  })
+
+  it("returns the error itself when it is already one", () => {
+    expect(toPostgresError(duplicate)).toBe(duplicate)
+  })
+
+  it("returns undefined for anything else", () => {
+    expect(toPostgresError(new Error("nope"))).toBeUndefined()
+    expect(toPostgresError("nope")).toBeUndefined()
+    expect(toPostgresError(undefined)).toBeUndefined()
+  })
+
+  it("stops on a cyclic cause chain", () => {
+    const a = new Error("a")
+    const b = Object.assign(new Error("b"), { cause: a })
+    Object.assign(a, { cause: b })
+
+    expect(toPostgresError(a)).toBeUndefined()
+  })
+})
+
+describe("isConstraintViolation", () => {
+  it("matches any class 23 code by default", () => {
+    expect(isConstraintViolation(wrapped(duplicate))).toBe(duplicate)
+
+    const notNull = postgresError({ code: SqlState.notNullViolation })
+    expect(isConstraintViolation(notNull)).toBe(notNull)
+  })
+
+  it("does not match other SQLSTATE classes", () => {
+    const denied = postgresError({ code: SqlState.insufficientPrivilege })
+
+    expect(isConstraintViolation(denied)).toBeUndefined()
+    expect(isConstraintViolation(new Error("nope"))).toBeUndefined()
+  })
+
+  it("narrows to named constraints", () => {
+    expect(
+      isConstraintViolation(duplicate, new Set(["contacts_email_key"]))
+    ).toBe(duplicate)
+    expect(isConstraintViolation(duplicate, ["other_key"])).toBeUndefined()
+    expect(
+      isConstraintViolation(postgresError({ code: SqlState.uniqueViolation }), [
+        "contacts_email_key",
+      ])
+    ).toBeUndefined()
+  })
+
+  it("narrows to one code", () => {
+    expect(
+      isConstraintViolation(duplicate, undefined, {
+        code: SqlState.uniqueViolation,
+      })
+    ).toBe(duplicate)
+    expect(
+      isConstraintViolation(duplicate, ["contacts_email_key"], {
+        code: SqlState.foreignKeyViolation,
+      })
+    ).toBeUndefined()
+  })
+})

package/src/errors.ts

@@ -0,0 +1,133 @@
+// Recognising Postgres errors through Drizzle. Runtime code, not a test helper:
+// mapping a unique violation to a form error is ordinary request handling.
+import type { PostgresError } from "postgres"
+
+/**
+ * SQLSTATE codes worth naming. The full list is Postgres's "Error Codes"
+ * appendix; these are the ones an application branches on.
+ */
+export const SqlState = {
+  /** `check_violation`. */
+  checkViolation: "23514",
+  /** `exclusion_violation`. */
+  exclusionViolation: "23P01",
+  /** `foreign_key_violation`. */
+  foreignKeyViolation: "23503",
+  /** `insufficient_privilege`: an RLS policy or a missing grant refused it. */
+  insufficientPrivilege: "42501",
+  /**
+   * `invalid_column_reference`, which is what an `ON CONFLICT` target that no
+   * unique index can arbitrate raises. It is raised while the statement is
+   * planned, so it fires on the first insert, not on the first conflict.
+   */
+  invalidColumnReference: "42P10",
+  /** `not_null_violation`. */
+  notNullViolation: "23502",
+  /** `undefined_function`: a function missing, or called with the wrong signature. */
+  undefinedFunction: "42883",
+  /** `unique_violation`. */
+  uniqueViolation: "23505",
+} as const
+
+export type SqlStateCode = (typeof SqlState)[keyof typeof SqlState]
+
+/** SQLSTATE class 23, every `integrity_constraint_violation`. */
+const INTEGRITY_CONSTRAINT_CLASS = "23"
+
+// Drizzle wraps once, and a failure inside `db.transaction()` can nest one
+// more level. The bound only stops a cyclic `cause` chain.
+const MAX_CAUSE_DEPTH = 5
+
+/**
+ * The postgres.js error underneath whatever Drizzle threw, or `undefined`.
+ *
+ * Drizzle wraps **every** driver error in a `DrizzleQueryError` whose own
+ * `code` is `undefined`, so `error.code === "23505"` is always false:
+ *
+ * ```
+ * depth 0: DrizzleQueryError  code=undefined  "Failed query: insert into …"
+ * depth 1: PostgresError      code=23505      "duplicate key value violates …"
+ * ```
+ *
+ * Matched by `name` rather than `instanceof`, so a second copy of `postgres`
+ * in the tree cannot make it miss.
+ */
+export const toPostgresError = (error: unknown): PostgresError | undefined => {
+  let current: unknown = error
+
+  for (
+    let depth = 0;
+    current instanceof Error && depth < MAX_CAUSE_DEPTH;
+    depth += 1
+  ) {
+    if (current.name === "PostgresError") {
+      return current as PostgresError
+    }
+    // `Error.cause` is ES2022, past this package's `lib`.
+    current = (current as Error & { cause?: unknown }).cause
+  }
+
+  return
+}
+
+export type ConstraintViolationOptions = {
+  /**
+   * The SQLSTATE to require, e.g. `SqlState.uniqueViolation`. Defaults to any
+   * code in class 23 (`integrity_constraint_violation`).
+   */
+  code?: string
+}
+
+/**
+ * Whether `error` is an integrity-constraint violation, optionally one of the
+ * named constraints. Returns the `PostgresError` so a caller can read its
+ * `constraint_name` or `detail`, or `undefined` when it does not match.
+ *
+ * ```ts
+ * try {
+ *   await db.insert(contacts).values(row)
+ * } catch (error) {
+ *   if (isConstraintViolation(error, ["contacts_email_key"], { code: SqlState.uniqueViolation })) {
+ *     return { error: "That email is already a contact" }
+ *   }
+ *   throw error
+ * }
+ * ```
+ */
+export const isConstraintViolation = (
+  error: unknown,
+  constraints?: Iterable<string>,
+  { code }: ConstraintViolationOptions = {}
+): PostgresError | undefined => {
+  const postgresError = toPostgresError(error)
+
+  if (!postgresError) {
+    return
+  }
+
+  const matchesCode = code
+    ? postgresError.code === code
+    : postgresError.code.startsWith(INTEGRITY_CONSTRAINT_CLASS)
+
+  if (!matchesCode) {
+    return
+  }
+
+  if (constraints === undefined) {
+    return postgresError
+  }
+
+  const name = postgresError.constraint_name
+
+  if (name === undefined) {
+    return
+  }
+
+  for (const constraint of constraints) {
+    if (constraint === name) {
+      return postgresError
+    }
+  }
+
+  return
+}

package/src/function-names.ts

@@ -0,0 +1,21 @@
+// The naming convention `functionPolicies` writes policies against and
+// `selectFunctionPermissions` calls: `<prefix>_<operation>_<table>`. Shared so
+// the two cannot drift apart.
+
+export const FUNCTION_POLICY_OPERATIONS = [
+  "select",
+  "insert",
+  "update",
+  "delete",
+] as const
+
+export type FunctionPolicyOperation =
+  (typeof FUNCTION_POLICY_OPERATIONS)[number]
+
+export const DEFAULT_FUNCTION_PREFIX = "can"
+
+export const functionPolicyName = (
+  prefix: string,
+  operation: FunctionPolicyOperation,
+  tableName: string
+) => `${prefix}_${operation}_${tableName}`

package/src/index.ts

@@ -7,5 +7,7 @@ export {
   createServiceClient,
   createSupabaseClient,
   type DrizzleClient,
+  type ResolveDatabaseUrlOptions,
+  resolveDatabaseUrl,
   type SupabaseToken,
 } from "./clients.ts"

package/src/next.test-d.ts

@@ -0,0 +1,32 @@
+import type { JwtPayload } from "@supabase/supabase-js"
+import { expectTypeOf, test } from "vitest"
+import { z } from "zod"
+import type { DrizzleClient } from "./clients.ts"
+import { createRequestDb } from "./next.ts"
+
+const { defineAction } = createRequestDb({
+  supabase: () => ({
+    auth: {
+      getClaims: () => Promise.resolve({ data: null, error: null }),
+    },
+  }),
+})
+
+test("the action takes the schema's input and resolves to the handler's result", () => {
+  const schema = z.object({ id: z.string().transform(Number) })
+  const action = defineAction(schema, (db, input, context) => {
+    expectTypeOf(db).toEqualTypeOf<DrizzleClient>()
+    expectTypeOf(input).toEqualTypeOf<{ id: number }>()
+    expectTypeOf(context.claims).toEqualTypeOf<JwtPayload>()
+    return Promise.resolve(input.id)
+  })
+
+  expectTypeOf(action).parameter(0).toEqualTypeOf<{ id: string }>()
+  expectTypeOf(action).returns.toEqualTypeOf<Promise<number>>()
+})
+
+test("a synchronous handler still yields an async action", () => {
+  const action = defineAction(z.number(), (_db, input) => input > 0)
+
+  expectTypeOf(action).returns.toEqualTypeOf<Promise<boolean>>()
+})