@zeno-lib/db 0.3.2 → 0.5.0

package/dist/schema.mjs

@@ -1,17 +1,22 @@
 import { authUsers } from "./auth-schema.mjs";
+import { n as functionPolicyName, t as FUNCTION_POLICY_OPERATIONS } from "./function-names-BDc-AuFm.mjs";
 import { Column, getColumnTable, getTableName, is, sql } from "drizzle-orm";
 import { bigint, integer, isPgEnum as isEnum, isPgMaterializedView as isMaterializedView, isPgSchema as isSchema, isPgSequence as isSequence, isPgView as isView, pgEnum as enum$1, pgMaterializedView as materializedView, pgPolicy, pgPolicy as policy, pgRole as role, pgSequence as sequence, pgTableCreator as tableCreator, pgView as view, timestamp, uuid, varchar } from "drizzle-orm/pg-core";
 import { snakeCase } from "drizzle-orm/pg-core/casing";
 import { anonRole, authUid, authUid as authUid$1, authenticatedRole, authenticatedRole as authenticatedRole$1, postgresRole, realtimeMessages, realtimeTopic, serviceRole, supabaseAuthAdminRole } from "drizzle-orm/supabase";
 //#region src/schema.ts
-const timestamps = ({ precision, withTimezone = true } = {}) => {
-	const config = {
+const timestamps = ({ mode, precision, withTimezone = true } = {}) => {
+	const column = (name) => mode === "string" ? timestamp(name, {
+		mode: "string",
 		precision,
 		withTimezone
-	};
+	}).notNull().defaultNow() : timestamp(name, {
+		precision,
+		withTimezone
+	}).notNull().defaultNow();
 	return {
-		createdAt: timestamp("created_at", config).notNull().defaultNow(),
-		updatedAt: timestamp("updated_at", config).notNull().defaultNow()
+		createdAt: column("created_at"),
+		updatedAt: column("updated_at")
 	};
 };
 const NULLABLE_AUTHOR_ACTIONS = {
@@ -118,12 +123,6 @@ const POLICY_BUILDERS = {
 	select: selectPolicy,
 	update: updatePolicy
 };
-const FUNCTION_POLICY_OPERATIONS = [
-	"select",
-	"insert",
-	"update",
-	"delete"
-];
 const isWholeSetArgument = (argument) => is(argument, Column) || Array.isArray(argument);
 const argumentsFor = (argument, operation) => {
 	if (!argument) return [];
@@ -163,7 +162,7 @@ const functionPolicies = (columns, { argument, name, prefix = "can", schema: fun
 	if (!firstColumn) throw new Error("functionPolicies needs a table with at least one column");
 	const tableName = getTableName(getColumnTable(firstColumn));
 	return FUNCTION_POLICY_OPERATIONS.map((operation) => {
-		const functionName = `${prefix}_${operation}_${tableName}`;
+		const functionName = functionPolicyName(prefix, operation, tableName);
 		const callee = functionSchema ? sql`${sql.identifier(functionSchema)}.${sql.identifier(functionName)}` : sql`${sql.identifier(functionName)}`;
 		const condition = sql`(select ${callee}(${sql.join(argumentsFor(argument, operation), sql`, `)}))`;
 		const clause = { [POLICY_CLAUSE[operation]]: condition };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/db",
-  "version": "0.3.2",
+  "version": "0.5.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,22 +59,32 @@
     "@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",
-    "@zeno-lib/typescript": "^1.1.0"
+    "vitest": "4.1.11",
+    "zod": "^4.4.3",
+    "@zeno-lib/schema": "0.2.2",
+    "@zeno-lib/typescript": "^1.1.0",
+    "@zeno-lib/test": "0.1.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/action-result.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest"
+import { z } from "zod"
+import {
+  FieldValidationError,
+  toActionError,
+  toFieldName,
+} from "./action-result.ts"
+
+describe("toFieldName", () => {
+  it("joins keys with dots and brackets array indices", () => {
+    expect(toFieldName(["owners", 0, "percentage"])).toBe(
+      "owners[0].percentage"
+    )
+    expect(toFieldName(["address", "city"])).toBe("address.city")
+    expect(toFieldName(["matrix", 1, 2])).toBe("matrix[1][2]")
+    expect(toFieldName([0, "name"])).toBe("[0].name")
+  })
+
+  it("reads Standard Schema path segment objects", () => {
+    expect(toFieldName([{ key: "owners" }, { key: 3 }])).toBe("owners[3]")
+  })
+
+  it("returns an empty name for a missing or empty path", () => {
+    expect(toFieldName(undefined)).toBe("")
+    expect(toFieldName([])).toBe("")
+  })
+})
+
+describe("toActionError", () => {
+  it("groups a Zod failure by field name and keeps path-less issues form-level", () => {
+    const schema = z
+      .object({
+        address: z.object({ city: z.string().min(1, "City required") }),
+        owners: z.array(
+          z.object({ percentage: z.number().max(100, "At most 100") })
+        ),
+      })
+      .refine(() => false, "Rejected as a whole")
+    const result = schema.safeParse({
+      address: { city: "" },
+      owners: [{ percentage: 10 }, { percentage: 120 }],
+    })
+    if (result.success) {
+      throw new Error("expected a failure")
+    }
+
+    expect(toActionError(result.error.issues)).toEqual({
+      fieldErrors: {
+        "address.city": ["City required"],
+        "owners[1].percentage": ["At most 100"],
+      },
+      formErrors: ["Rejected as a whole"],
+    })
+  })
+
+  it("collects several messages for one field in order", () => {
+    expect(
+      toActionError([
+        { message: "Too short", path: ["password"] },
+        { message: "Needs a digit", path: ["password"] },
+        { message: "Try again later" },
+      ])
+    ).toEqual({
+      fieldErrors: { password: ["Too short", "Needs a digit"] },
+      formErrors: ["Try again later"],
+    })
+  })
+})
+
+describe("FieldValidationError", () => {
+  it("normalises single messages to arrays", () => {
+    const error = new FieldValidationError(
+      { email: "Taken", "owners[0].name": ["A", "B"] },
+      { formErrors: "Locked" }
+    )
+
+    expect(error).toBeInstanceOf(Error)
+    expect(error.name).toBe("FieldValidationError")
+    expect(error.toActionError()).toEqual({
+      fieldErrors: { email: ["Taken"], "owners[0].name": ["A", "B"] },
+      formErrors: ["Locked"],
+    })
+  })
+
+  it("defaults to no form errors", () => {
+    expect(new FieldValidationError({ email: "Taken" }).formErrors).toEqual([])
+  })
+})

package/src/action-result.ts

@@ -0,0 +1,109 @@
+/**
+ * The serializable validation failure a form action returns instead of
+ * throwing. Next.js redacts a thrown error's message in production, so a
+ * `ZodError` thrown by a server action reaches the browser as an opaque
+ * failure; a returned value survives the round trip intact.
+ *
+ * `fieldErrors` is keyed by TanStack Form field name (`address.city`,
+ * `owners[0].percentage`); `formErrors` holds the issues with no path.
+ * `@zeno-lib/forms` declares the same shape on its side and matches it
+ * structurally, so neither package depends on the other.
+ */
+export interface ActionError {
+  readonly fieldErrors: Record<string, string[]>
+  readonly formErrors: string[]
+}
+
+/** What a form action resolves to: the handler's result, or the failure. */
+export type ActionResult<TData> =
+  | { readonly ok: true; readonly data: TData }
+  | { readonly ok: false; readonly error: ActionError }
+
+/** A Standard Schema issue, reduced to what the mapping reads. */
+export interface ActionIssue {
+  readonly message: string
+  readonly path?:
+    | ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+    | undefined
+}
+
+type FieldMessages = string | readonly string[]
+
+function toMessages(messages: FieldMessages): string[] {
+  return typeof messages === "string" ? [messages] : [...messages]
+}
+
+/**
+ * Thrown from a `defineFormAction` handler to reject the input for a reason
+ * only the server can see (a uniqueness conflict, a stale reference). The
+ * action catches it and returns `{ ok: false, error }` in the same shape a
+ * schema failure produces. Keys are TanStack Form field names.
+ *
+ * Thrown inside `db.transaction(...)`, it rolls the transaction back like any
+ * other error before the action converts it. From a plain `defineAction`
+ * handler it is an ordinary error and stays thrown.
+ */
+export class FieldValidationError extends Error {
+  readonly fieldErrors: Record<string, string[]>
+  readonly formErrors: string[]
+
+  constructor(
+    fieldErrors: Readonly<Record<string, FieldMessages>>,
+    options: { formErrors?: FieldMessages; message?: string } = {}
+  ) {
+    super(options.message ?? "Validation failed")
+    this.name = "FieldValidationError"
+    this.fieldErrors = Object.fromEntries(
+      Object.entries(fieldErrors).map(([name, messages]) => [
+        name,
+        toMessages(messages),
+      ])
+    )
+    this.formErrors =
+      options.formErrors === undefined ? [] : toMessages(options.formErrors)
+  }
+
+  /** The error as the returned failure shape. */
+  toActionError(): ActionError {
+    return { fieldErrors: this.fieldErrors, formErrors: this.formErrors }
+  }
+}
+
+/**
+ * Formats an issue path the way TanStack Form names fields: object keys joined
+ * with `.`, array indices in brackets (`["owners", 0, "percentage"]` becomes
+ * `owners[0].percentage`). An empty path yields `""`.
+ */
+export function toFieldName(path: ActionIssue["path"]): string {
+  let name = ""
+  for (const segment of path ?? []) {
+    const key = typeof segment === "object" ? segment.key : segment
+    if (typeof key === "number") {
+      name += `[${key}]`
+    } else {
+      const part = typeof key === "symbol" ? (key.description ?? "") : key
+      name += name === "" ? part : `.${part}`
+    }
+  }
+  return name
+}
+
+/**
+ * Groups Standard Schema issues into an `ActionError`: each issue lands under
+ * its field name, in order, and an issue without a path goes to `formErrors`.
+ */
+export function toActionError(issues: readonly ActionIssue[]): ActionError {
+  const fieldErrors: Record<string, string[]> = {}
+  const formErrors: string[] = []
+  for (const issue of issues) {
+    const name = toFieldName(issue.path)
+    if (name === "") {
+      formErrors.push(issue.message)
+    } else {
+      const messages = fieldErrors[name] ?? []
+      messages.push(issue.message)
+      fieldErrors[name] = messages
+    }
+  }
+  return { fieldErrors, formErrors }
+}

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