@zeno-lib/db 0.3.1 → 0.4.0

package/dist/triggers.mjs

@@ -0,0 +1,93 @@
+import { getTableName, is } from "drizzle-orm";
+import { PgTable, getTableConfig } from "drizzle-orm/pg-core";
+//#region src/triggers.ts
+const DEFAULT_EXTENSION_SCHEMA = "extensions";
+const DEFAULT_COLUMN = "updated_at";
+const DEFAULT_AUTHOR_COLUMN = "updated_by";
+const DEFAULT_TABLE_SCHEMA = "public";
+const quote = (identifier) => `"${identifier.split("\"").join("\"\"")}"`;
+function resolveTable(table, schema) {
+	const name = is(table, PgTable) ? getTableName(table) : table;
+	const tableSchema = schema ?? (is(table, PgTable) ? getTableConfig(table).schema ?? DEFAULT_TABLE_SCHEMA : DEFAULT_TABLE_SCHEMA);
+	return { qualified: `${quote(tableSchema)}.${quote(name)}` };
+}
+/**
+* `CREATE TRIGGER` SQL that keeps `updated_at` current for **every** writer,
+* including PostgREST, the dashboard and psql.
+*
+* `timestamps()` gives the column a `DEFAULT now()`, which covers the insert.
+* SQL has no "on update" default, so without this trigger the column is only
+* ever the insert time. Required, not optional.
+*
+* ```ts
+* // pnpm db:generate --custom --name=posts_audit_triggers
+* // then paste the output into the generated migration:
+* console.log(updatedAtTrigger(posts))
+* ```
+*/
+function updatedAtTrigger(table, { column = DEFAULT_COLUMN, createExtension = true, extensionSchema = DEFAULT_EXTENSION_SCHEMA, name, schema } = {}) {
+	const { qualified } = resolveTable(table, schema);
+	const triggerName = name ?? `handle_${column}`;
+	const trigger = [
+		`drop trigger if exists ${quote(triggerName)} on ${qualified};`,
+		`create trigger ${quote(triggerName)}`,
+		`  before update on ${qualified}`,
+		"  for each row",
+		`  execute function ${quote(extensionSchema)}.moddatetime (${quote(column)});`
+	].join("\n");
+	return createExtension ? `${moddatetimeExtension(extensionSchema)}\n\n${trigger}` : trigger;
+}
+/** `create extension if not exists moddatetime`, safe to repeat per migration. */
+function moddatetimeExtension(schema = DEFAULT_EXTENSION_SCHEMA) {
+	return `create extension if not exists moddatetime with schema ${quote(schema)};`;
+}
+/**
+* `CREATE TRIGGER` SQL that stamps an author column with `auth.uid()` on every
+* update, the `updated_at` story for `updated_by`.
+*
+* `updatedBy()` gives the column a `DEFAULT (select auth.uid())`, which covers
+* the insert. This covers the update, for every writer rather than only the
+* ones going through Drizzle.
+*
+* A write with no session (the admin or `service_role` clients) records `NULL`,
+* because that is what `auth.uid()` returns there.
+*/
+function updatedByTrigger(table, { column = DEFAULT_AUTHOR_COLUMN, createFunction = true, functionSchema = DEFAULT_TABLE_SCHEMA, name, schema } = {}) {
+	const { qualified } = resolveTable(table, schema);
+	const triggerName = name ?? `handle_${column}`;
+	const functionName = `set_${column}`;
+	const qualifiedFunction = `${quote(functionSchema)}.${quote(functionName)}`;
+	const routine = [
+		`create or replace function ${qualifiedFunction}()`,
+		"  returns trigger",
+		"  language plpgsql",
+		"  security invoker",
+		`  set search_path = ''`,
+		"as $$",
+		"begin",
+		`  new.${quote(column)} = (select auth.uid());`,
+		"  return new;",
+		"end;",
+		"$$;"
+	].join("\n");
+	const trigger = [
+		`drop trigger if exists ${quote(triggerName)} on ${qualified};`,
+		`create trigger ${quote(triggerName)}`,
+		`  before update on ${qualified}`,
+		"  for each row",
+		`  execute function ${qualifiedFunction}();`
+	].join("\n");
+	return createFunction ? `${routine}\n\n${trigger}` : trigger;
+}
+/**
+* Both update triggers `auditColumns()` needs, in one string.
+*
+* `auditColumns()` and `timestamps()` leave `updated_at` and `updated_by` at
+* their insert values without these, so a table using either helper wants this
+* in a `drizzle-kit generate --custom` migration.
+*/
+function auditTriggers(table, options = {}) {
+	return `${updatedAtTrigger(table, options)}\n\n${updatedByTrigger(table, options)}`;
+}
+//#endregion
+export { auditTriggers, moddatetimeExtension, updatedAtTrigger, updatedByTrigger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/db",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": {
@@ -18,6 +18,21 @@
       "import": "./dist/config.mjs",
       "default": "./dist/config.mjs"
     },
+    "./errors": {
+      "types": "./dist/errors.d.mts",
+      "import": "./dist/errors.mjs",
+      "default": "./dist/errors.mjs"
+    },
+    "./next": {
+      "types": "./dist/next.d.mts",
+      "import": "./dist/next.mjs",
+      "default": "./dist/next.mjs"
+    },
+    "./query": {
+      "types": "./dist/query.d.mts",
+      "import": "./dist/query.mjs",
+      "default": "./dist/query.mjs"
+    },
     "./schema": {
       "types": "./dist/schema.d.mts",
       "import": "./dist/schema.mjs",
@@ -44,21 +59,30 @@
     "@supabase/supabase-js": ">=2",
     "drizzle-kit": "1.0.0-rc.3",
     "drizzle-orm": "1.0.0-rc.3",
-    "postgres": ">=3.4"
+    "postgres": ">=3.4",
+    "react": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@supabase/supabase-js": "2.106.1",
+    "@supabase/supabase-js": "2.116.0",
     "@types/node": "24.10.0",
+    "@types/react": "19.2.14",
     "dotenv": "17.4.2",
     "drizzle-kit": "1.0.0-rc.3",
     "drizzle-orm": "1.0.0-rc.3",
     "postgres": "3.4.7",
+    "react": "^19.2.5",
     "supabase": "2.84.1",
     "tsdown": "^0.22.14",
     "typescript": "7.0.2",
     "vite": "8.0.16",
-    "vitest": "4.1.0",
-    "@zeno-lib/test": "0.0.3",
+    "vitest": "4.1.11",
+    "zod": "^4.4.3",
+    "@zeno-lib/test": "0.1.0",
     "@zeno-lib/typescript": "^1.1.0"
   },
   "scripts": {

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()
+  })
+})