@supatype/cli 0.1.12 → 0.2.0

package/src/docker-postgres.ts

@@ -256,7 +256,7 @@ export const DEFAULT_SERVER_DOCKER_IMAGE = "supatype/server:latest"
  * Run `supatype-server migrate` on the Postgres container network (loopback trust).
  * Used on Windows + database.provider docker, host-published :5432 breaks libpq TLS there.
  */
-export function runGotrueMigrationsViaDocker(
+export function runAuthMigrationsViaDocker(
   pgContainerName: string,
   serverImage: string,
   migrateEnv: Record<string, string>,
@@ -276,7 +276,7 @@ export function runGotrueMigrationsViaDocker(
   if (result.status !== 0) {
     const detail = (result.stderr ?? result.stdout ?? "").trim()
     throw new Error(
-      `GoTrue migrations failed in Docker (exit ${result.status ?? "unknown"})` +
+      `auth migrations failed in Docker (exit ${result.status ?? "unknown"})` +
         (detail ? `:\n${detail}` : ""),
     )
   }

package/src/engine-floor.ts

@@ -0,0 +1,113 @@
+/**
+ * The engine version a schema needs, checked before the engine is asked to apply it.
+ *
+ * Field bounds and model constraints compile to CHECK constraints that call helper functions in
+ * the `_supatype` schema, and only the engine creates those helpers. A CLI that emits the call
+ * against an engine that does not create the function produces this, three times, and then gives
+ * up:
+ *
+ *     Failed to apply migration
+ *     Caused by: error returned from database:
+ *       function _supatype.richtext_text(jsonb) does not exist
+ *
+ * Which says nothing about the cause. A project on `latest` is fine; the exposed case is a pin,
+ * `versions: { engine: "0.1.9" }`, where the CLI moved and the engine did not.
+ *
+ * The check is conditional on the schema, not a flat floor: a schema that declares no bounds and
+ * no model constraints works on an older engine, and refusing it would break projects for a
+ * feature they do not use.
+ *
+ * It reads the pin rather than asking a binary for its version, because the pin is what both paths
+ * resolve from: the native provider downloads that version, and the docker provider tags the
+ * compose image with it. An unpinned project resolves to latest, which is at or above the floor by
+ * definition, so there is nothing to check.
+ */
+import type { ExtractedSchemaAstV2, ModelAstV2 } from "./schema-ast-v2.js"
+
+/** First engine release that creates the `_supatype` constraint helpers (schema-engine v0.2.0). */
+export const ENGINE_MIN_FOR_BOUNDS = "0.2.0"
+
+/**
+ * Compare two dotted versions numerically. Returns <0, 0 or >0.
+ *
+ * Pre-release suffixes are dropped before comparing, so `0.2.0-rc.1` counts as `0.2.0`. That is
+ * deliberate: a release candidate of the engine that creates the helpers does create them, and
+ * refusing it would send someone testing a pre-release down a false trail.
+ */
+export function compareVersions(a: string, b: string): number {
+  const parts = (v: string): number[] =>
+    v
+      .trim()
+      .replace(/^v/, "")
+      .split("-")[0]!
+      .split(".")
+      .map((n) => Number.parseInt(n, 10))
+      .map((n) => (Number.isNaN(n) ? 0 : n))
+  const left = parts(a)
+  const right = parts(b)
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0)
+    if (diff !== 0) return diff
+  }
+  return 0
+}
+
+/** Field paths in the schema that declare a bound, as `model.field`, for naming them in an error. */
+function fieldsWithBounds(models: ModelAstV2[]): string[] {
+  const found: string[] = []
+  for (const model of models) {
+    for (const [fieldName, field] of Object.entries(model.fields)) {
+      if (Object.keys(field.validation ?? {}).length > 0) found.push(`${model.name}.${fieldName}`)
+    }
+  }
+  return found
+}
+
+/** Models declaring a constraint, which compiles to a table-level CHECK. */
+function modelsWithConstraints(models: ModelAstV2[]): string[] {
+  return models
+    .filter((model) => (model.annotations.db.constraints ?? []).length > 0)
+    .map((model) => model.name)
+}
+
+/**
+ * Everything in the schema that needs {@link ENGINE_MIN_FOR_BOUNDS}, or an empty array.
+ *
+ * Exported for the error message and for tests: a check nobody can see the input of is a check
+ * that gets deleted the first time it is inconvenient.
+ */
+export function boundsRequiringHelpers(ast: ExtractedSchemaAstV2): string[] {
+  return [...fieldsWithBounds(ast.models), ...modelsWithConstraints(ast.models)]
+}
+
+/**
+ * Refuse a push whose schema needs helpers this engine does not create.
+ *
+ * Takes the pin from `versions.engine`, or undefined when unpinned. See the note above on why
+ * that is the right source rather than the binary's own `--version`.
+ */
+export function assertEngineSupportsSchema(
+  ast: ExtractedSchemaAstV2,
+  pinnedEngineVersion: string | undefined,
+): void {
+  // Unpinned resolves to latest, and `local` points at a build whose version the config does not
+  // know. Neither can be compared, and neither is the case that breaks.
+  if (pinnedEngineVersion === undefined || pinnedEngineVersion === "local") return
+  if (compareVersions(pinnedEngineVersion, ENGINE_MIN_FOR_BOUNDS) >= 0) return
+
+  const needed = boundsRequiringHelpers(ast)
+  if (needed.length === 0) return
+
+  const shown = needed.slice(0, 3).join(", ")
+  const more = needed.length > 3 ? `, and ${needed.length - 3} more` : ""
+  throw new Error(
+    `This schema declares bounds that need schema-engine ${ENGINE_MIN_FOR_BOUNDS} or newer, ` +
+      `and this project pins ${pinnedEngineVersion}.\n\n` +
+      `  Declared on: ${shown}${more}\n\n` +
+      `Bounds compile to CHECK constraints that call helpers in the _supatype schema, and only ` +
+      `engine ${ENGINE_MIN_FOR_BOUNDS}+ creates them. Applying this would fail inside Postgres ` +
+      `with "function _supatype.richtext_text(jsonb) does not exist".\n\n` +
+      `Raise or remove the pin in supatype.config.ts:\n` +
+      `  versions: { engine: "${ENGINE_MIN_FOR_BOUNDS}" }   // or omit it to track latest`,
+  )
+}

package/src/field-bounds.ts

@@ -0,0 +1,359 @@
+/**
+ * What a declared bound means for each field kind, and the SQL it compiles to.
+ *
+ * **This table is the mechanism.** Bounds used to be compiled inside the modifier cases of
+ * `type-extractor.ts`, which meant `MaxLength` became `char_length(col)` whatever the column turned
+ * out to be: `char_length(text[])` does not exist, so the RFC's own `tags: MaxLength<string[], 10>`
+ * produced SQL that fails `CREATE TABLE`. Worse, nine of twelve engine field structs had nowhere to
+ * put a `check`, so the constraint was dropped by serde with no error anywhere in the chain.
+ *
+ * A table keyed by kind fixes the class of bug rather than the instances: a kind absent from
+ * {@link BOUNDS_BY_KIND} throws, so a new field kind cannot be added without answering "what does a
+ * bound mean here", and every answer is either an expression or a refusal with a named alternative.
+ * There is no third outcome, which is what "no bound is ever silent" means in practice.
+ */
+import { FIELD_KINDS, type FieldKind, type FieldValidation } from "./schema-ast-v2.js"
+
+/** Bounds as declared on the type, before anything knows what column they will land on. */
+export interface DeclaredBounds {
+  maxLength?: number
+  minLength?: number
+  maxItems?: number
+  minItems?: number
+  min?: number | string
+  max?: number | string
+}
+
+/** What "length" counts, per storage. */
+type LengthForm = "chars" | "octets" | "richText"
+/** What "items" counts, per storage. */
+type ItemsForm = "array" | "jsonbArray"
+/** What a range compares against. Temporal forms name the cast, which is never `numeric`. */
+type RangeForm = "numeric" | "timestamptz" | "date" | "timestamp" | "interval"
+
+type BoundFamily = "length" | "items" | "range"
+
+interface KindBounds {
+  length?: LengthForm
+  items?: ItemsForm
+  range?: RangeForm
+  /** Where to send someone whose bound this kind refuses. */
+  instead?: Partial<Record<BoundFamily, string>>
+}
+
+const TEXTUAL: KindBounds = {
+  length: "chars",
+  instead: {
+    items: "text has characters, not items; use MaxLength/MinLength",
+    range: "text is not ordered numerically; use a model-level constraint if you need a comparison",
+  },
+}
+
+const NUMERIC: KindBounds = {
+  range: "numeric",
+  instead: {
+    length: "a number has no length; use Between to bound its value",
+    items: "a number has no items; use Between to bound its value",
+  },
+}
+
+const temporal = (range: RangeForm): KindBounds => ({
+  range,
+  instead: {
+    length: "a date has no length; use Between with ISO-8601 string bounds",
+    items: "a date has no items; use Between with ISO-8601 string bounds",
+  },
+})
+
+const NO_BOUNDS = (why: string): KindBounds => ({
+  instead: { length: why, items: why, range: why },
+})
+
+/**
+ * What each bound means for each kind.
+ *
+ * `Record<FieldKind, KindBounds>` is the whole mechanism: it is **exhaustive by the compiler**, so
+ * adding a kind to `FIELD_KINDS` fails the build here until someone says what `MaxLength`,
+ * `MaxItems` and `Between` do for it. Composite kinds (`timestamps`, `publishable`, `softDelete`)
+ * expand into real columns before a bound could apply, so they carry none, but they still have to
+ * say so.
+ */
+const BOUNDS_BY_KIND: Record<FieldKind, KindBounds> = {
+  text: TEXTUAL,
+  email: TEXTUAL,
+  url: TEXTUAL,
+  slug: TEXTUAL,
+  color: TEXTUAL,
+  xml: TEXTUAL,
+  ip: TEXTUAL,
+  cidr: TEXTUAL,
+  macaddr: TEXTUAL,
+  tsQuery: TEXTUAL,
+  tsVector: TEXTUAL,
+
+  richText: {
+    length: "richText",
+    instead: {
+      items: "rich text is measured in characters of plain text; use MaxLength/MinLength",
+      range: "rich text is not ordered; use MaxLength/MinLength",
+    },
+  },
+
+  bytes: {
+    length: "octets",
+    instead: {
+      items: "a binary column has octets, not items; use MaxLength/MinLength",
+      range: "a binary column is not ordered; use MaxLength/MinLength",
+    },
+  },
+
+  integer: NUMERIC,
+  smallInt: NUMERIC,
+  bigInt: NUMERIC,
+  float: NUMERIC,
+  serial: NUMERIC,
+  bigSerial: NUMERIC,
+  decimal: NUMERIC,
+  money: NUMERIC,
+
+  datetime: temporal("timestamptz"),
+  timestamp: temporal("timestamp"),
+  date: temporal("date"),
+  interval: temporal("interval"),
+
+  array: {
+    items: "array",
+    instead: {
+      length: "an array has items, not characters; use MaxItems/MinItems",
+      range: "an array is not ordered; use MaxItems/MinItems",
+    },
+  },
+
+  blocks: {
+    items: "jsonbArray",
+    instead: {
+      length: "blocks are counted, not measured; use MaxItems/MinItems",
+      range: "blocks are not ordered; use MaxItems/MinItems",
+    },
+  },
+
+  // `json` is decided per field, not per kind: `JSON<Item[]>` takes item bounds and `JSON<{...}>`
+  // takes none. {@link boundsForKind} applies that, which is why the entry here is the object case.
+  json: NO_BOUNDS(
+    "a JSON object has no single measure; bound a sub-field with a model-level constraint, " +
+      "or declare the field as JSON<T[]> to bound its element count",
+  ),
+  button: NO_BOUNDS("a button is a composite value; bound a sub-field with a model-level constraint"),
+
+  enum: NO_BOUNDS("the union already constrains the permitted values"),
+  boolean: NO_BOUNDS("a boolean has two values and needs no bound"),
+  uuid: NO_BOUNDS("a UUID is fixed width"),
+  image: NO_BOUNDS("size and type limits belong on the bucket: fileSizeLimit and allowedMimeTypes"),
+  file: NO_BOUNDS("size and type limits belong on the bucket: fileSizeLimit and allowedMimeTypes"),
+  geo: NO_BOUNDS("a geometry is not measured this way"),
+  vector: NO_BOUNDS("the dimension is already fixed by the type, as Vector<N>"),
+  relation: NO_BOUNDS("bound the column on the model this relation points at"),
+  custom: NO_BOUNDS("a plugin field declares its own storage; bounds are the plugin's to define"),
+
+  timestamps: NO_BOUNDS("a composite expands into columns before a bound could apply"),
+  publishable: NO_BOUNDS("a composite expands into columns before a bound could apply"),
+  softDelete: NO_BOUNDS("a composite expands into columns before a bound could apply"),
+}
+
+/**
+ * Re-exported for tests. Completeness is now the compiler's job, not a test's: this exists so the
+ * matrix can assert it covers every kind, which is a different question from whether every kind is
+ * classified.
+ */
+export const CLASSIFIED_KINDS: readonly FieldKind[] = FIELD_KINDS
+
+/** `JSON<T[]>` counts elements; `JSON<{...}>` takes no bound. Anything else follows its kind. */
+function boundsForKind(kind: FieldKind, jsonIsArray: boolean): KindBounds {
+  const entry = BOUNDS_BY_KIND[kind]
+  if (kind === "json" && jsonIsArray) {
+    return {
+      items: "jsonbArray",
+      instead: {
+        length: "a JSON array has items, not characters; use MaxItems/MinItems",
+        range: "a JSON array is not ordered; use MaxItems/MinItems",
+      },
+    }
+  }
+  return entry
+}
+
+/** How a column is measured, once the kind has decided. */
+export type MeasureForm = LengthForm | ItemsForm
+
+export interface MeasureResolution {
+  /** How to measure, when this kind can be measured this way. */
+  form?: MeasureForm
+  /** Why it cannot, and what to use instead. Present exactly when `form` is not. */
+  instead?: string
+}
+
+/**
+ * How a kind is measured, for one measure family.
+ *
+ * **The single answer for both paths.** `MaxLength<T, N>` on a field and `Length<"col">` inside a
+ * model constraint have to agree about what "length" means for a given column, or the same schema
+ * gets `char_length` in one place and `cardinality` in the other. A second table for the constraint
+ * path is how `char_length(text[])` would come back, in a new file, having been fixed once already.
+ */
+export function measureFormFor(
+  kind: FieldKind,
+  measure: "length" | "items",
+  options: { jsonIsArray?: boolean } = {},
+): MeasureResolution {
+  const entry = boundsForKind(kind, options.jsonIsArray === true)
+  const form = measure === "length" ? entry.length : entry.items
+  if (form !== undefined) return { form }
+  return { instead: entry.instead?.[measure] ?? `a ${kind} field cannot be measured that way` }
+}
+
+const COLUMN = '"{name}"'
+
+function lengthExpr(form: LengthForm): string {
+  switch (form) {
+    case "chars":
+      return `char_length(${COLUMN})`
+    case "octets":
+      return `octet_length(${COLUMN})`
+    case "richText":
+      return `char_length(_supatype.richtext_text(${COLUMN}))`
+  }
+}
+
+/**
+ * `jsonb_array_length` raises `cannot get array length of a non-array` at insert time, so the type
+ * guard is part of the constraint rather than an assumption about what callers send.
+ */
+function itemsClause(form: ItemsForm, comparisons: string[]): string {
+  if (form === "array") {
+    return comparisons.map((c) => `cardinality(${COLUMN}) ${c}`).join(" AND ")
+  }
+  const guarded = comparisons.map((c) => `jsonb_array_length(${COLUMN}) ${c}`).join(" AND ")
+  return `jsonb_typeof(${COLUMN}) = 'array' AND ${guarded}`
+}
+
+function rangeLiteral(form: RangeForm, value: number | string): string {
+  if (form === "numeric") return String(value)
+  const cast = form === "timestamptz" ? "timestamptz" : form
+  return `'${String(value).replace(/'/g, "''")}'::${cast}`
+}
+
+/** ISO-8601 date, date-time or a Postgres interval. Validated here so a bad literal is a CLI error. */
+function isTemporalLiteral(form: RangeForm, value: string): boolean {
+  if (form === "interval") return /^\s*\d+\s+[a-z]+(\s+\d+\s+[a-z]+)*\s*$/i.test(value)
+  return !Number.isNaN(Date.parse(value))
+}
+
+export interface BoundsCompileResult {
+  check?: string
+  validation?: FieldValidation
+}
+
+function refuse(field: string, modifier: string, kind: FieldKind, hint: string | undefined): never {
+  const tail = hint ? ` ${hint}.` : ""
+  throw new Error(
+    `Field "${field}": ${modifier} is not supported on a ${kind} field.${tail}`,
+  )
+}
+
+/**
+ * Compile declared bounds against the kind they landed on.
+ *
+ * Throws rather than dropping. A bound that cannot be honoured is a mistake in the schema, and the
+ * failure it used to produce, silence, is the one failure this must not have.
+ */
+export function compileBounds(
+  field: string,
+  kind: FieldKind,
+  bounds: DeclaredBounds,
+  options: { jsonIsArray?: boolean } = {},
+): BoundsCompileResult {
+  const entry = boundsForKind(kind, options.jsonIsArray === true)
+  const clauses: string[] = []
+  const validation: FieldValidation = {}
+
+  const { maxLength, minLength } = bounds
+  if (maxLength !== undefined || minLength !== undefined) {
+    const resolved = measureFormFor(kind, "length", options)
+    if (resolved.form === undefined) {
+      refuse(field, maxLength !== undefined ? "MaxLength" : "MinLength", kind, resolved.instead)
+    }
+    const expr = lengthExpr(resolved.form as LengthForm)
+    if (maxLength !== undefined) {
+      clauses.push(`${expr} <= ${maxLength}`)
+      validation.maxLength = maxLength
+    }
+    if (minLength !== undefined) {
+      clauses.push(`${expr} >= ${minLength}`)
+      validation.minLength = minLength
+    }
+  }
+
+  const { maxItems, minItems } = bounds
+  const itemsResolved = measureFormFor(kind, "items", options)
+  if (maxItems !== undefined || minItems !== undefined) {
+    if (itemsResolved.form === undefined) {
+      refuse(field, maxItems !== undefined ? "MaxItems" : "MinItems", kind, itemsResolved.instead)
+    }
+    const comparisons: string[] = []
+    if (maxItems !== undefined) {
+      comparisons.push(`<= ${maxItems}`)
+      validation.maxItems = maxItems
+    }
+    if (minItems !== undefined) {
+      comparisons.push(`>= ${minItems}`)
+      validation.minItems = minItems
+    }
+    clauses.push(itemsClause(itemsResolved.form as ItemsForm, comparisons))
+  }
+
+  const { min, max } = bounds
+  if (min !== undefined || max !== undefined) {
+    if (!entry.range) refuse(field, "Between", kind, entry.instead?.range)
+    for (const [bound, comparison] of [[min, ">="], [max, "<="]] as const) {
+      if (bound === undefined) continue
+      assertRangeShape(field, kind, entry.range, bound)
+      clauses.push(`${COLUMN} ${comparison} ${rangeLiteral(entry.range, bound)}`)
+    }
+    if (min !== undefined) validation.min = min
+    if (max !== undefined) validation.max = max
+  }
+
+  // Parenthesised only when there is something to bind, matching `mergeCheckConstraint`. Gratuitous
+  // parentheses are not cosmetic here: the differ compares this text against what Postgres hands
+  // back from `pg_get_constraintdef`, so every avoidable difference is a false "changed" on push.
+  return {
+    ...(clauses.length > 0 && { check: joinClauses(clauses) }),
+    ...(Object.keys(validation).length > 0 && { validation }),
+  }
+}
+
+function joinClauses(clauses: string[]): string {
+  const [only] = clauses
+  if (clauses.length === 1 && only !== undefined) return only
+  return clauses.map((c) => `(${c})`).join(" AND ")
+}
+
+/** A number bounds a number and a string bounds a date. Crossing them is a mistake, not a cast. */
+function assertRangeShape(field: string, kind: FieldKind, form: RangeForm, bound: number | string): void {
+  const isNumeric = form === "numeric"
+  if (isNumeric && typeof bound !== "number") {
+    throw new Error(
+      `Field "${field}": Between on a ${kind} field takes numbers, but "${bound}" is a string.`,
+    )
+  }
+  if (!isNumeric && typeof bound !== "string") {
+    throw new Error(
+      `Field "${field}": Between on a ${kind} field takes ISO-8601 string bounds, but ${bound} is a number.`,
+    )
+  }
+  if (!isNumeric && !isTemporalLiteral(form, bound as string)) {
+    throw new Error(
+      `Field "${field}": Between bound "${bound}" is not a valid ${form === "interval" ? "interval" : "ISO-8601 date"}.`,
+    )
+  }
+}

package/src/hooks-generator.ts

@@ -28,16 +28,21 @@ function hookedModels(ast: unknown): HookedModel[] {
 
   return models
     .filter((model) => {
-      const hooks = (model as { annotations?: { platform?: { hooks?: unknown } } }).annotations
-        ?.platform?.hooks
-      return typeof hooks === "object" && hooks !== null && Object.keys(hooks).length > 0
+      const platform = (
+        model as { annotations?: { platform?: { hooks?: unknown; validate?: unknown } } }
+      ).annotations?.platform
+      const declares = (value: unknown): boolean =>
+        typeof value === "object" && value !== null && Object.keys(value).length > 0
+      // Validators need the same row types hooks do, so a model declaring only validators must
+      // still appear here or `FieldValidator<"products", ...>` would not compile.
+      return declares(platform?.hooks) || declares(platform?.validate)
     })
     .map((model) => ({ table: resolveTableName(model), fields: model.fields }))
     .sort((a, b) => a.table.localeCompare(b.table))
 }
 
 /**
- * The module source, or `null` when no model declares a hook.
+ * The module source, or `null` when no model declares a hook or a field validator.
  *
  * Returning null rather than an empty module keeps a `_supatype/hooks.ts` from appearing in projects
  * that have no hooks, a generated file nobody imports is a file somebody eventually edits.
@@ -169,6 +174,78 @@ export type AfterDelete<T extends HookedTable> = (
   ctx: AfterDeleteContext<T>,
 ) => void | Promise<void>
 
+
+/**
+ * A per-field validator: one field's value, and a verdict about it.
+ *
+ * \`FieldValidator<"products", "setup_items">\` types \`value\` as that column's real type, so a
+ * validator cannot quietly be written against the wrong shape.
+ *
+ * Return \`true\` to accept, or a message to refuse. The message reaches the caller attached to the
+ * field name, which is what lets a form put it on the input rather than in a banner: the whole
+ * reason for declaring this instead of putting the same logic in a \`beforeChange\` hook.
+ */
+export type FieldValidatorContext<T extends HookedTable, F extends keyof HookTables[T]["Row"]> =
+  HookBase & {
+    readonly operation: "insert" | "update"
+    readonly field: F
+    readonly value: HookTables[T]["Row"][F]
+  }
+
+export type FieldVerdict = true | string
+
+export type FieldValidator<T extends HookedTable, F extends keyof HookTables[T]["Row"]> = (
+  ctx: FieldValidatorContext<T, F>,
+) => FieldVerdict | Promise<FieldVerdict>
+
+interface WireValidatorContext {
+  table?: string
+  operation?: string
+  field?: string
+  value?: unknown
+  user?: unknown
+  requestId?: string
+}
+
+/**
+ * Wrap a typed validator as the request handler the worker expects.
+ *
+ * A refusal is **422 with the field named**, not a bare 400: the request was understood and one
+ * value was rejected. A thrown error is deliberately *not* turned into a refusal, because a broken
+ * validator has not decided anything: it becomes a 500, which the server reads as unavailable and
+ * refuses the write on, rather than as the validator saying no.
+ */
+export function fieldValidator(
+  handler: (ctx: never) => FieldVerdict | Promise<FieldVerdict>,
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    if (req.method !== "POST") {
+      return json({ message: "A validator is invoked with POST" }, 405)
+    }
+
+    let wire: WireValidatorContext
+    try {
+      wire = (await req.json()) as WireValidatorContext
+    } catch {
+      return json({ message: "Validator payload was not JSON" }, 400)
+    }
+
+    const field = wire.field ?? ""
+    const ctx = {
+      table: wire.table ?? "",
+      operation: wire.operation === "update" ? "update" : "insert",
+      field,
+      value: wire.value,
+      user: (wire.user ?? null) as never,
+      requestId: wire.requestId ?? "",
+    }
+
+    const verdict = await handler(ctx as never)
+    if (verdict === true) return json({}, 200)
+    return json({ field, message: String(verdict), error: String(verdict) }, 422)
+  }
+}
+
 /** Every handler a single function may serve, when one function covers a model's whole lifecycle. */
 export interface HookHandlers<T extends HookedTable> {
   readonly beforeChange?: BeforeChange<T>

package/src/link.ts

@@ -23,7 +23,7 @@ export interface ProjectLink {
   defaultEnvironment: string
   /** Access token (cloud user JWT) or self-host SERVICE_ROLE_KEY. */
   token?: string
-  /** Cloud GoTrue refresh token, used to renew short-lived access JWTs. */
+  /** Cloud auth refresh token, used to renew short-lived access JWTs. */
   refreshToken?: string
   orgId?: string | undefined
   cloudApiUrl?: string