@zeno-lib/db 0.4.0 → 0.6.0

package/dist/next.d.mts

@@ -1,6 +1,70 @@
 import { n as DrizzleClient, t as CreateClientConfig } from "./clients-BlUEH7QJ.mjs";
 import { AnyRelations, EmptyRelations } from "drizzle-orm";
 import { JwtPayload, SupabaseClient } from "@supabase/supabase-js";
+//#region src/action-result.d.ts
+/**
+ * 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.
+ */
+interface ActionError {
+  readonly fieldErrors: Record<string, string[]>;
+  readonly formErrors: string[];
+}
+/** What a form action resolves to: the handler's result, or the failure. */
+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. */
+interface ActionIssue {
+  readonly message: string;
+  readonly path?: ReadonlyArray<PropertyKey | {
+    readonly key: PropertyKey;
+  }> | undefined;
+}
+type FieldMessages = string | readonly string[];
+/**
+ * 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.
+ */
+declare class FieldValidationError extends Error {
+  readonly fieldErrors: Record<string, string[]>;
+  readonly formErrors: string[];
+  constructor(fieldErrors: Readonly<Record<string, FieldMessages>>, options?: {
+    formErrors?: FieldMessages;
+    message?: string;
+  });
+  /** The error as the returned failure shape. */
+  toActionError(): ActionError;
+}
+/**
+ * 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 `""`.
+ */
+declare function toFieldName(path: ActionIssue["path"]): string;
+/**
+ * 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`.
+ */
+declare function toActionError(issues: readonly ActionIssue[]): ActionError;
+//#endregion
 //#region src/define-action.d.ts
 /**
  * The slice of a schema `defineAction` needs: a throwing `parse`, plus the
@@ -23,12 +87,46 @@ interface ActionContext<TDb> {
 }
 /** An action's body: the RLS-bound `db`, the parsed input, and the context. */
 type ActionHandler<TContext extends ActionContext<unknown>, TOutput, TResult> = (db: TContext["db"], input: TOutput, context: TContext) => TResult | Promise<TResult>;
+/**
+ * What an action resolves to: the handler's result, with `undefined` (and
+ * `void`) replaced by `null`.
+ */
+type ActionValue<TResult> = undefined extends TResult ? Exclude<Exclude<TResult, undefined>, void> | null : 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)`.
+ * `handler(db, input, context)`. A handler that resolves to `undefined`, such
+ * as a Drizzle `findFirst` that matched no row, makes the action resolve to
+ * `null`, because TanStack Query rejects a query whose function resolves to
+ * `undefined`.
+ */
+type DefineAction<TContext extends ActionContext<unknown>> = <TInput, TOutput, TResult>(schema: ActionSchema<TInput, TOutput>, handler: ActionHandler<TContext, TOutput, TResult>) => (input: TInput) => Promise<ActionValue<TResult>>;
+/**
+ * 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.
  */
-type DefineAction<TContext extends ActionContext<unknown>> = <TInput, TOutput, TResult>(schema: ActionSchema<TInput, TOutput>, handler: ActionHandler<TContext, TOutput, TResult>) => (input: TInput) => Promise<TResult>;
+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.
+ */
+type DefineFormAction<TContext extends ActionContext<unknown>> = <TInput, TOutput, TResult>(schema: FormActionSchema<TInput, TOutput>, handler: ActionHandler<TContext, TOutput, TResult>) => (input: TInput) => Promise<ActionResult<Awaited<TResult>>>;
 //#endregion
 //#region src/next.d.ts
 /**
@@ -67,6 +165,11 @@ type RequestDb<TRelations extends AnyRelations = EmptyRelations> = {
   getRequestDb: () => Promise<DrizzleClient<TRelations>>;
   /** Wraps a handler into a `"use server"` export; see `DefineAction`. */
   defineAction: DefineAction<RequestContext<TRelations>>;
+  /**
+   * `defineAction` for forms: resolves to an `ActionResult` instead of
+   * throwing on invalid input; see `DefineFormAction`.
+   */
+  defineFormAction: DefineFormAction<RequestContext<TRelations>>;
 };
 /**
  * Request-scoped, RLS-bound Drizzle access for Next.js. Verifies the session
@@ -84,4 +187,4 @@ type RequestDb<TRelations extends AnyRelations = EmptyRelations> = {
  */
 declare function createRequestDb<TRelations extends AnyRelations = EmptyRelations>(options: CreateRequestDbOptions<TRelations>): RequestDb<TRelations>;
 //#endregion
-export { type ActionContext, type ActionHandler, type ActionSchema, ClaimsSource, CreateRequestDbOptions, type DefineAction, RequestContext, RequestDb, UnauthenticatedError, createRequestDb };
+export { type ActionContext, type ActionError, type ActionHandler, type ActionIssue, type ActionResult, type ActionSchema, type ActionValue, ClaimsSource, CreateRequestDbOptions, type DefineAction, type DefineFormAction, FieldValidationError, type FormActionSchema, RequestContext, RequestDb, UnauthenticatedError, createRequestDb, toActionError, toFieldName };

package/dist/next.mjs

@@ -1,5 +1,73 @@
 import { a as createSupabaseClient } from "./clients-CdPr3mCZ.mjs";
 import { cache } from "react";
+//#region src/action-result.ts
+function toMessages(messages) {
+	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.
+*/
+var FieldValidationError = class extends Error {
+	constructor(fieldErrors, options = {}) {
+		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 === void 0 ? [] : toMessages(options.formErrors);
+	}
+	/** The error as the returned failure shape. */
+	toActionError() {
+		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 `""`.
+*/
+function toFieldName(path) {
+	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`.
+*/
+function toActionError(issues) {
+	const fieldErrors = {};
+	const formErrors = [];
+	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
+	};
+}
+//#endregion
 //#region src/define-action.ts
 /**
 * Binds `defineAction` to a request-context resolver. Deliberately not a
@@ -13,7 +81,36 @@ function createDefineAction(getContext) {
 	return (schema, handler) => async (input) => {
 		const parsed = schema.parse(input);
 		const context = await getContext();
-		return await handler(context.db, parsed, context);
+		return await handler(context.db, parsed, context) ?? null;
+	};
+}
+/**
+* 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.
+*/
+function createDefineFormAction(getContext) {
+	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;
+		}
 	};
 }
 //#endregion
@@ -61,9 +158,10 @@ function createRequestDb(options) {
 	});
 	return {
 		defineAction: createDefineAction(getRequestContext),
+		defineFormAction: createDefineFormAction(getRequestContext),
 		getRequestContext,
 		getRequestDb: async () => (await getRequestContext()).db
 	};
 }
 //#endregion
-export { UnauthenticatedError, createRequestDb };
+export { FieldValidationError, UnauthenticatedError, createRequestDb, toActionError, toFieldName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeno-lib/db",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "exports": {
     ".": {
@@ -57,7 +57,7 @@
   },
   "peerDependencies": {
     "@supabase/supabase-js": ">=2",
-    "drizzle-kit": "1.0.0-rc.3",
+    "drizzle-kit": "1.0.0-rc.5-5935859",
     "drizzle-orm": "1.0.0-rc.3",
     "postgres": ">=3.4",
     "react": ">=19"
@@ -71,8 +71,8 @@
     "@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",
+    "dotenv": "18.0.4",
+    "drizzle-kit": "1.0.0-rc.5-5935859",
     "drizzle-orm": "1.0.0-rc.3",
     "postgres": "3.4.7",
     "react": "^19.2.5",
@@ -80,8 +80,9 @@
     "tsdown": "^0.22.14",
     "typescript": "7.0.2",
     "vite": "8.0.16",
-    "vitest": "4.1.11",
+    "vitest": "5.0.2",
     "zod": "^4.4.3",
+    "@zeno-lib/schema": "0.2.2",
     "@zeno-lib/test": "0.1.0",
     "@zeno-lib/typescript": "^1.1.0"
   },

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/define-action.ts

@@ -1,3 +1,10 @@
+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.
@@ -29,10 +36,21 @@ export type ActionHandler<
   context: TContext
 ) => TResult | Promise<TResult>
 
+/**
+ * What an action resolves to: the handler's result, with `undefined` (and
+ * `void`) replaced by `null`.
+ */
+export type ActionValue<TResult> = undefined extends TResult
+  ? Exclude<Exclude<TResult, undefined>, void> | null
+  : 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)`.
+ * `handler(db, input, context)`. A handler that resolves to `undefined`, such
+ * as a Drizzle `findFirst` that matched no row, makes the action resolve to
+ * `null`, because TanStack Query rejects a query whose function resolves to
+ * `undefined`.
  */
 export type DefineAction<TContext extends ActionContext<unknown>> = <
   TInput,
@@ -41,7 +59,7 @@ export type DefineAction<TContext extends ActionContext<unknown>> = <
 >(
   schema: ActionSchema<TInput, TOutput>,
   handler: ActionHandler<TContext, TOutput, TResult>
-) => (input: TInput) => Promise<TResult>
+) => (input: TInput) => Promise<ActionValue<TResult>>
 
 /**
  * Binds `defineAction` to a request-context resolver. Deliberately not a
@@ -54,10 +72,82 @@ export type DefineAction<TContext extends ActionContext<unknown>> = <
 export function createDefineAction<TContext extends ActionContext<unknown>>(
   getContext: () => Promise<TContext>
 ): DefineAction<TContext> {
+  return <TInput, TOutput, TResult>(
+    schema: ActionSchema<TInput, TOutput>,
+    handler: ActionHandler<TContext, TOutput, TResult>
+  ) =>
+    async (input: TInput) => {
+      const parsed = schema.parse(input)
+      const context = await getContext()
+      const result = await handler(context.db, parsed, context)
+
+      return (result ?? null) as ActionValue<TResult>
+    }
+}
+
+/**
+ * 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 = schema.parse(input)
+    const parsed = await schema["~standard"].validate(input)
+    if (parsed.issues) {
+      return { error: toActionError(parsed.issues), ok: false }
+    }
     const context = await getContext()
 
-    return await handler(context.db, parsed, context)
+    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/next.test-d.ts

@@ -2,9 +2,9 @@ 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"
+import { type ActionError, type ActionResult, createRequestDb } from "./next.ts"
 
-const { defineAction } = createRequestDb({
+const { defineAction, defineFormAction } = createRequestDb({
   supabase: () => ({
     auth: {
       getClaims: () => Promise.resolve({ data: null, error: null }),
@@ -30,3 +30,47 @@ test("a synchronous handler still yields an async action", () => {
 
   expectTypeOf(action).returns.toEqualTypeOf<Promise<boolean>>()
 })
+
+test("a result that may be undefined resolves to null instead", () => {
+  const action = defineAction(z.number(), (_db, input) =>
+    Promise.resolve(input > 0 ? { id: input } : undefined)
+  )
+
+  expectTypeOf(action).returns.toEqualTypeOf<Promise<{ id: number } | null>>()
+})
+
+test("a handler with no result resolves to null", () => {
+  const action = defineAction(z.number(), async () => {
+    await Promise.resolve()
+  })
+
+  expectTypeOf(action).returns.toEqualTypeOf<Promise<null>>()
+})
+
+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[]>
+    >()
+  }
+})

package/src/next.test.ts

@@ -1,7 +1,8 @@
 import { AuthError, type JwtPayload } from "@supabase/supabase-js"
 import { beforeEach, describe, expect, it, vi } from "vitest"
 import { z } from "zod"
-import { createDefineAction } from "./define-action.ts"
+import { FieldValidationError } from "./action-result.ts"
+import { createDefineAction, createDefineFormAction } from "./define-action.ts"
 
 // No database: the RLS client factory is replaced by a stub that returns a
 // marker object, so nothing here builds a pool or opens a connection. What
@@ -78,6 +79,23 @@ describe("defineAction", () => {
     expect(handler).toHaveBeenCalledWith(context.db, { id: 7 }, context)
   })
 
+  it("resolves to null when the handler resolves to undefined", async () => {
+    const action = createDefineAction(() => Promise.resolve({ db: {} }))(
+      schema,
+      () => Promise.resolve(undefined)
+    )
+
+    await expect(action({ id: 1 })).resolves.toBeNull()
+  })
+
+  it("keeps a falsy result other than undefined", async () => {
+    const define = createDefineAction(() => Promise.resolve({ db: {} }))
+
+    await expect(define(schema, () => 0)({ id: 1 })).resolves.toBe(0)
+    await expect(define(schema, () => false)({ id: 1 })).resolves.toBe(false)
+    await expect(define(schema, () => "")({ id: 1 })).resolves.toBe("")
+  })
+
   it("hands the handler the claims for authorship", async () => {
     const context = { claims: { sub: "user-1" }, db: {} }
     const action = createDefineAction(() => Promise.resolve(context))(
@@ -112,6 +130,108 @@ describe("defineAction", () => {
   })
 })
 
+describe("defineFormAction", () => {
+  const schema = z.object({
+    owners: z.array(
+      z.object({ percentage: z.number().max(100, "At most 100") })
+    ),
+  })
+  const context = { claims: { sub: "user-1" }, db: { name: "db" } }
+
+  it("resolves to { ok: true, data } with the handler's result", async () => {
+    const handler = vi.fn(
+      (_db: { name: string }, input: z.output<typeof schema>) =>
+        Promise.resolve(input.owners.length)
+    )
+    const action = createDefineFormAction(() => Promise.resolve(context))(
+      schema,
+      handler
+    )
+
+    await expect(action({ owners: [{ percentage: 50 }] })).resolves.toEqual({
+      data: 1,
+      ok: true,
+    })
+    expect(handler).toHaveBeenCalledWith(
+      context.db,
+      { owners: [{ percentage: 50 }] },
+      context
+    )
+  })
+
+  it("returns schema issues keyed by field name, before resolving the context", async () => {
+    const getContext = vi.fn(() => Promise.resolve(context))
+    const handler = vi.fn()
+    const action = createDefineFormAction(getContext)(schema, handler)
+
+    await expect(
+      action({ owners: [{ percentage: 10 }, { percentage: 150 }] })
+    ).resolves.toEqual({
+      error: {
+        fieldErrors: { "owners[1].percentage": ["At most 100"] },
+        formErrors: [],
+      },
+      ok: false,
+    })
+    expect(getContext).not.toHaveBeenCalled()
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it("returns a FieldValidationError thrown by the handler in the same shape", async () => {
+    const action = createDefineFormAction(() => Promise.resolve(context))(
+      schema,
+      () => {
+        throw new FieldValidationError(
+          { "owners[0].percentage": "Already allocated" },
+          { formErrors: "Record is locked" }
+        )
+      }
+    )
+
+    await expect(action({ owners: [{ percentage: 1 }] })).resolves.toEqual({
+      error: {
+        fieldErrors: { "owners[0].percentage": ["Already allocated"] },
+        formErrors: ["Record is locked"],
+      },
+      ok: false,
+    })
+  })
+
+  it("keeps a failure that is not a validation error throwing", async () => {
+    const boom = new Error("connection reset")
+    const action = createDefineFormAction(() => Promise.resolve(context))(
+      schema,
+      () => Promise.reject(boom)
+    )
+
+    await expect(action({ owners: [] })).rejects.toBe(boom)
+  })
+
+  it("keeps a context failure throwing", async () => {
+    const handler = vi.fn()
+    const action = createDefineFormAction(() =>
+      Promise.reject(new UnauthenticatedError())
+    )(schema, handler)
+
+    await expect(action({ owners: [] })).rejects.toBeInstanceOf(
+      UnauthenticatedError
+    )
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it("returns a result that survives a JSON round trip unchanged", async () => {
+    const action = createDefineFormAction(() => Promise.resolve(context))(
+      schema,
+      () => ({ id: 1 })
+    )
+    const failure = await action({ owners: [{ percentage: 101 }] })
+    const success = await action({ owners: [] })
+
+    expect(JSON.parse(JSON.stringify(failure))).toEqual(failure)
+    expect(JSON.parse(JSON.stringify(success))).toEqual(success)
+  })
+})
+
 describe("createRequestDb", () => {
   it("builds the RLS client from the whole verified claims object", async () => {
     const { getRequestContext, getRequestDb } = createRequestDb({
@@ -175,4 +295,19 @@ describe("createRequestDb", () => {
       sub: claims.sub,
     })
   })
+
+  it("binds defineFormAction to the request context", async () => {
+    const { defineFormAction } = createRequestDb({
+      supabase: supabaseReturning(getClaimsResult(claims, null)),
+    })
+    const action = defineFormAction(z.string(), (_db, input, context) => ({
+      input,
+      sub: context.claims.sub,
+    }))
+
+    await expect(action("hello")).resolves.toEqual({
+      data: { input: "hello", sub: claims.sub },
+      ok: true,
+    })
+  })
 })

package/src/next.ts

@@ -6,13 +6,30 @@ import {
   createSupabaseClient,
   type DrizzleClient,
 } from "./clients.ts"
-import { createDefineAction, type DefineAction } from "./define-action.ts"
+import {
+  createDefineAction,
+  createDefineFormAction,
+  type DefineAction,
+  type DefineFormAction,
+} from "./define-action.ts"
 
+// biome-ignore lint/performance/noBarrelFile: `/next` is the one entry server actions import; the result types and error class belong on it.
+export {
+  type ActionError,
+  type ActionIssue,
+  type ActionResult,
+  FieldValidationError,
+  toActionError,
+  toFieldName,
+} from "./action-result.ts"
 export type {
   ActionContext,
   ActionHandler,
   ActionSchema,
+  ActionValue,
   DefineAction,
+  DefineFormAction,
+  FormActionSchema,
 } from "./define-action.ts"
 
 /**
@@ -58,6 +75,11 @@ export type RequestDb<TRelations extends AnyRelations = EmptyRelations> = {
   getRequestDb: () => Promise<DrizzleClient<TRelations>>
   /** Wraps a handler into a `"use server"` export; see `DefineAction`. */
   defineAction: DefineAction<RequestContext<TRelations>>
+  /**
+   * `defineAction` for forms: resolves to an `ActionResult` instead of
+   * throwing on invalid input; see `DefineFormAction`.
+   */
+  defineFormAction: DefineFormAction<RequestContext<TRelations>>
 }
 
 /**
@@ -106,6 +128,7 @@ export function createRequestDb<
 
   return {
     defineAction: createDefineAction(getRequestContext),
+    defineFormAction: createDefineFormAction(getRequestContext),
     getRequestContext,
     getRequestDb: async () => (await getRequestContext()).db,
   }

package/src/schema-zod.test.ts

@@ -0,0 +1,37 @@
+import { defineTableSchema } from "@zeno-lib/schema"
+import { text } from "drizzle-orm/pg-core"
+import { describe, expect, it } from "vitest"
+
+import { auditColumns, sequentialPrimaryId, table } from "./schema.ts"
+
+// `@zeno-lib/schema` cannot import this package, so it recognises the audit
+// columns by the keys these helpers emit. This pins that contract.
+describe("schema helpers under defineTableSchema", () => {
+  const notes = table("notes", {
+    ...auditColumns(),
+    body: text().notNull(),
+    id: sequentialPrimaryId(),
+  })
+  const schemas = defineTableSchema(notes)
+
+  it("keeps every audit column out of insert and update", () => {
+    const forged = {
+      body: "Hello",
+      createdAt: new Date(),
+      createdBy: "00000000-0000-4000-8000-000000000000",
+      updatedAt: new Date(),
+      updatedBy: "00000000-0000-4000-8000-000000000000",
+    }
+
+    expect(schemas.insert.parse(forged)).toEqual({ body: "Hello" })
+    expect(schemas.update.parse(forged)).toEqual({ body: "Hello" })
+  })
+
+  it("accepts only positive sequential ids", () => {
+    expect(schemas.insert.safeParse({ body: "x", id: 0 }).success).toBe(false)
+    expect(schemas.insert.parse({ body: "x", id: 1 })).toEqual({
+      body: "x",
+      id: 1,
+    })
+  })
+})