@zeno-lib/db 0.3.2 → 0.5.0

package/src/define-action.ts

@@ -0,0 +1,137 @@
+import {
+  type ActionIssue,
+  type ActionResult,
+  FieldValidationError,
+  toActionError,
+} from "./action-result.ts"
+
+/**
+ * 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)
+  }
+}
+
+/**
+ * The schema `defineFormAction` needs: the Standard Schema `validate`, which
+ * reports failures as issues with paths instead of throwing. Zod 4 schemas
+ * satisfy it as they are.
+ */
+export interface FormActionSchema<TInput, TOutput> {
+  readonly "~standard": {
+    readonly types?:
+      | { readonly input: TInput; readonly output: TOutput }
+      | undefined
+    readonly validate: (
+      value: unknown
+    ) =>
+      | FormActionSchemaResult<TOutput>
+      | Promise<FormActionSchemaResult<TOutput>>
+  }
+}
+
+type FormActionSchemaResult<TOutput> =
+  | { readonly value: TOutput; readonly issues?: undefined }
+  | { readonly issues: readonly ActionIssue[] }
+
+/**
+ * `defineFormAction(schema, handler)` is `defineAction` for a form: the action
+ * resolves to an `ActionResult` instead of throwing on invalid input, so field
+ * errors survive Next.js's production redaction of thrown messages.
+ */
+export type DefineFormAction<TContext extends ActionContext<unknown>> = <
+  TInput,
+  TOutput,
+  TResult,
+>(
+  schema: FormActionSchema<TInput, TOutput>,
+  handler: ActionHandler<TContext, TOutput, TResult>
+) => (input: TInput) => Promise<ActionResult<Awaited<TResult>>>
+
+/**
+ * Binds `defineFormAction` to a request-context resolver. Same order as
+ * `createDefineAction` (validate, then resolve the context, then run the
+ * handler), but two failures come back as `{ ok: false, error }`: schema
+ * issues, and a `FieldValidationError` thrown by the handler. Everything else
+ * (an `UnauthenticatedError`, a database error) still throws.
+ */
+export function createDefineFormAction<TContext extends ActionContext<unknown>>(
+  getContext: () => Promise<TContext>
+): DefineFormAction<TContext> {
+  return (schema, handler) => async (input) => {
+    const parsed = await schema["~standard"].validate(input)
+    if (parsed.issues) {
+      return { error: toActionError(parsed.issues), ok: false }
+    }
+    const context = await getContext()
+
+    try {
+      return {
+        data: await handler(context.db, parsed.value, context),
+        ok: true,
+      }
+    } catch (error) {
+      if (error instanceof FieldValidationError) {
+        return { error: error.toActionError(), ok: false }
+      }
+      throw error
+    }
+  }
+}

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,60 @@
+import type { JwtPayload } from "@supabase/supabase-js"
+import { expectTypeOf, test } from "vitest"
+import { z } from "zod"
+import type { DrizzleClient } from "./clients.ts"
+import { type ActionError, type ActionResult, createRequestDb } from "./next.ts"
+
+const { defineAction, defineFormAction } = 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>>()
+})
+
+test("defineFormAction takes the schema's input and resolves to an ActionResult", () => {
+  const schema = z.object({ id: z.string().transform(Number) })
+  const action = defineFormAction(schema, (db, input) => {
+    expectTypeOf(db).toEqualTypeOf<DrizzleClient>()
+    expectTypeOf(input).toEqualTypeOf<{ id: number }>()
+    return Promise.resolve({ saved: input.id })
+  })
+
+  expectTypeOf(action).parameter(0).toEqualTypeOf<{ id: string }>()
+  expectTypeOf(action).returns.toEqualTypeOf<
+    Promise<ActionResult<{ saved: number }>>
+  >()
+})
+
+test("an ActionResult narrows on ok", async () => {
+  const action = defineFormAction(z.number(), (_db, input) => input > 0)
+  const result = await action(1)
+
+  if (result.ok) {
+    expectTypeOf(result.data).toEqualTypeOf<boolean>()
+  } else {
+    expectTypeOf(result.error).toEqualTypeOf<ActionError>()
+    expectTypeOf(result.error.fieldErrors).toEqualTypeOf<
+      Record<string, string[]>
+    >()
+  }
+})