react-form-action 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,23 @@
 # react-form-action
 
-Typesafe success & error state control for Next.js v14 form actions.
+End-to-end typesafe success, error & validation state control for Next.js 14 form actions.
+
+## Features
+
+**Action Creator**
+
+- ✅ Provides `"invalid" | "success" | "failure"` response objects.
+- ✅ Define generic payload for each of the response type.
+
+**Form Action builder**
+
+- ✅ tRPC-like builder API for `.input(zodSchema)` & context `.use(middleware)`
+- ✅ Parses `formData` with [`zod-form-data`](https://www.npmjs.com/package/zod-form-data)
+
+**Stateful `<Form />`**
+
+- ✅ `<Form />` component reads the action's response.
+- ✅ Computes progress meta-state like `isInvalid`, `isSuccess` and more.
 
 ## Install
 
@@ -10,57 +27,124 @@ npm i react-form-action
 
 ## Usage
 
+### `formAction` builder
+
+```ts
+// app/actions/auth.ts
+"use server";
+
+import { formAction } from "react-form-action";
+import { z } from "zod";
+import { cookies } from "next/headers";
+
+const emailSchema = z.object({ email: z.string().email() });
+
+const i18nMiddleware = async () => {
+  const { t } = await useTranslation("auth", cookies().get("i18n")?.value);
+  // will be added to context
+  return { t };
+};
+
+const authAction = formAction
+  .input(emailschema)
+  .use(i18nMiddleware)
+  .use(async ({ ctx: { t } }) =>
+    console.log("🎉 context enhanced by previous middlewares 🎉", t)
+  )
+  .error(({ error }) => {
+    if (error instanceof DbError) {
+      return error.custom.code;
+    } else {
+      // unknown error
+      // default Next.js error handling (error.js boundary)
+      throw error;
+    }
+  });
+
+export const resendVerifyEmailAction = authAction.run(
+  async ({ ctx: { t }, input: { email } }) => {
+    // do custom work
+    await db.resendVerificationEmail({ email });
+
+    // return translated success message
+    return t("verificationEmail.success");
+  }
+);
+
+export const signUp = authAction
+  // extend the input
+  .input(z.object({ password: z.string() }))
+  .run(async ({ ctx: { t }, input: { email, password } }) => {
+    // do custom work
+    await db.signupWithEmailAndPassword({ email, password });
+
+    // return translated success message
+    return t("signUp.success");
+  });
+```
+
 ### Server Action (usable in Next.js)
 
 ```ts
-// actions/updateUser.ts
 "use server";
+
 import { createFormAction } from "react-form-action";
+import { z } from "zod";
 
 // Define custom serializable error & success data types
 type ErrorData = {
   message: string;
-  validation?: boolean;
 };
 
-type SuccessData = string;
+type SuccessData = {
+  message: string;
+};
 
-export const updateUser = createFormAction<SuccessData, ErrorData>(
-  ({ success, failure }) =>
-    // success and failure helper functions create wrappers for success & error data respectively
-    async (prevState, formData) => {
-      if (prevState.type === "initial") {
-        // use the initialData passed to <Form /> here
-        // prevState.data === "foobar"
-      }
+type ValiationError = {
+  name?: string;
+};
 
-      try {
-        const { name } = updateUserSchema.parse({
-          name: formData.get("name"),
-        });
+const updateUserSchema = z.object({ name: z.string() });
+
+export const updateUser = createFormAction<
+  SuccessData,
+  ErrorData,
+  ValiationError
+>(({ success, failure, invalid }) =>
+  // success and failure helper functions create wrappers for success & error data respectively
+  async (prevState, formData) => {
+    if (prevState.type === "initial") {
+      // use the initialData passed to <Form /> here
+      // prevState.data === "foobar"
+    }
 
-        const user = await updateCurrentUser(name);
-
-        if (user) {
-          const successState = success("Your profile has been updated.");
-          // {type: "success", data: "Your profile has been updated.", error: null }
-          return successState;
-        } else {
-          const errorState = failure({ message: "No current user." });
-          // {type: "error", data: null, error: { message: "No current user." } }
-          return errorState;
-        }
-      } catch (error) {
-        if (error instanceof ZodError) {
-          return failure({
-            validation: true,
-            message: error.issues[0]?.message ?? "Validation error",
-          });
-        }
-
-        return failure({ message: "Failed to update user." });
+    try {
+      const { name } = updateUserSchema.parse({
+        name: formData.get("name"),
+      });
+
+      const user = await updateCurrentUser(name);
+
+      if (user) {
+        // {type: "success", data: "Your profile has been updated.", error: null, validationError: null}
+        return success({
+          message: "Your profile has been updated.",
+        });
+      } else {
+        // {type: "error", data: null, error: { message: "No current user." }, validationError: null}
+        return failure({ message: "No current user." });
+      }
+    } catch (error) {
+      if (error instanceof ZodError) {
+        // {type: "invalid", data: null, error: null, validationError: {name: "Invalid input"}}
+        return invalid({
+          name: error.issues[0]?.message ?? "Validation error",
+        });
       }
+
+      return failure({ message: "Failed to update user." });
     }
+  }
 );
 ```
 
@@ -76,18 +160,23 @@ import { updateUser } from "@/actions";
 export function UpdateUserForm() {
   return (
     <Form action={updateUser} initialData="foobar">
-      {({ error, data, isPending, isFailure, isSuccess, isInitial }) => (
+      {({
+        error,
+        data,
+        validationError,
+        isPending,
+        isFailure,
+        isInvalid,
+        isSuccess,
+        isInitial,
+      }) => (
         <>
           {/* safely access the data or error by checking the mutually exclusive boolean flags: */}
           {isSuccess && <p className="success-message">{data}</p>}
-
-          {isFailure && !error.validation && (
-            <p className="error-message">{error.message}</p>
-          )}
-
+          {isFailure && <p className="error-message">{error.message}</p>}
           <input type="text" name="name" disabled={isPending} />
-          {isFailure && error.validation && (
-            <span className="input-error">{error.message}</span>
+          {isInvalid && (
+            <span className="input-error">{validationError.name}</span>
           )}
 
           <button disabled={isPending}>

package/dist/client.d.mts

@@ -1,22 +1,24 @@
 import * as React from 'react';
 import React__default, { FormHTMLAttributes } from 'react';
 import { RenderProp } from 'react-render-prop-type';
-import { InitialState, FailureState, SuccessState, FormState } from './index.mjs';
+import { b as InitialState, I as InvalidState, a as FailureState, S as SuccessState, F as FormState } from './createFormAction-3a51310f.js';
 import { useFormStatus } from 'react-dom';
 
-type FormStateProps<Data, Error, Payload> = {
-    action: (state: FormState<Data, Error>, payload: Payload) => Promise<FormState<Data, Error>>;
+type FormStateProps<Data, ValidationError, Error, Payload> = {
+    action: (state: FormState<Data, ValidationError, Error>, payload: Payload) => Promise<FormState<Data, ValidationError, Error>>;
     initialData: Data;
     permalink?: string;
 };
-type FormMetaState<T extends FormState<unknown, unknown>> = T & {
+declare function initial<Data>(data: Data): InitialState<Data>;
+type FormMetaState<T extends FormState<unknown, unknown, unknown>> = T & {
     isPending: boolean;
     isInitial: T["type"] extends "initial" ? true : false;
     isFailure: T["type"] extends "failure" ? true : false;
     isSuccess: T["type"] extends "success" ? true : false;
+    isInvalid: T["type"] extends "invalid" ? true : false;
 };
-declare function Form<Data, Error>({ children, action, initialData, permalink, ...props }: Omit<FormHTMLAttributes<HTMLFormElement>, "action" | "children"> & FormStateProps<Data, Error, FormData> & RenderProp<FormMetaState<InitialState<Data>> | FormMetaState<FailureState<Error>> | FormMetaState<SuccessState<Data>>>): React__default.JSX.Element;
+declare function Form<Data, ValidationError, Error>({ children, action, initialData, permalink, ...props }: Omit<FormHTMLAttributes<HTMLFormElement>, "action" | "children"> & FormStateProps<Data, ValidationError, Error, FormData> & RenderProp<FormMetaState<InitialState<Data>> | FormMetaState<InvalidState<Error>> | FormMetaState<FailureState<Error>> | FormMetaState<SuccessState<Data>>>): React__default.JSX.Element;
 
 declare function FormStatus({ children, }: RenderProp<ReturnType<typeof useFormStatus>>): React.ReactNode;
 
-export { Form, FormStatus };
+export { Form, FormStatus, initial };

package/dist/client.mjs

@@ -1 +1 @@
-"use client";import a from"react";import{useFormState as l}from"react-dom";import{useFormStatus as u}from"react-dom";function r({children:t}){return t(u())}function c(t){return{type:"initial",data:t,error:null}}function D({children:t,action:o,initialData:i,permalink:n,...s}){let[e,m]=l(o,c(i),n);return a.createElement("form",{action:m,...s},a.createElement(r,null,({pending:p})=>t({...e,isPending:p,isInitial:e.type==="initial",isFailure:e.type==="failure",isSuccess:e.type==="success"})))}export{D as Form,r as FormStatus};
+"use client";import a from"react";import{useFormState as u}from"react-dom";import{useFormStatus as p}from"react-dom";function e({children:t}){return t(p())}function S(t){return{type:"initial",data:t,error:null,validationError:null}}function E({children:t,action:o,initialData:i,permalink:n,...s}){let[r,m]=u(o,S(i),n);return a.createElement("form",{action:m,...s},a.createElement(e,null,({pending:l})=>t({...r,isPending:l,isInitial:r.type==="initial",isInvalid:r.type==="invalid",isFailure:r.type==="failure",isSuccess:r.type==="success"})))}export{E as Form,e as FormStatus,S as initial};

package/dist/createFormAction-3a51310f.d.ts

@@ -0,0 +1,32 @@
+type InitialState<T> = {
+    type: "initial";
+    data: T;
+    error: null;
+    validationError: null;
+};
+type InvalidState<T> = {
+    type: "invalid";
+    data: null;
+    error: null;
+    validationError: T;
+};
+type FailureState<T> = {
+    type: "failure";
+    data: null;
+    error: T;
+    validationError: null;
+};
+type SuccessState<T> = {
+    type: "success";
+    data: T;
+    error: null;
+    validationError: null;
+};
+type FormState<Data, Error, ValidationError = Record<string, never>> = InitialState<Data> | InvalidState<ValidationError> | FailureState<Error> | SuccessState<Data>;
+declare function createFormAction<Data, Error = Data, ValidationError = Record<string, never>, Payload = FormData>(formAction: (params: {
+    success: (data: Data) => SuccessState<Data>;
+    failure: (error: Error) => FailureState<Error>;
+    invalid: (validationError: ValidationError) => InvalidState<ValidationError>;
+}) => (state: FormState<Data, Error, ValidationError>, payload: Payload) => Promise<FormState<Data, Error, ValidationError>>): (state: FormState<Data, Error, ValidationError>, payload: Payload) => Promise<FormState<Data, Error, ValidationError>>;
+
+export { FormState as F, InvalidState as I, SuccessState as S, FailureState as a, InitialState as b, createFormAction as c };

package/dist/index.d.mts

@@ -1,22 +1,53 @@
-type InitialState<T> = {
-    type: "initial";
-    data: T;
-    error: null;
-};
-type FailureState<T> = {
-    type: "failure";
-    data: null;
-    error: T;
-};
-type SuccessState<T> = {
-    type: "success";
-    data: T;
-    error: null;
+import { F as FormState, a as FailureState, S as SuccessState, I as InvalidState } from './createFormAction-3a51310f.js';
+export { b as InitialState, c as createFormAction } from './createFormAction-3a51310f.js';
+import { z, ZodRawShape, ZodObject, objectUtil, ZodSchema } from 'zod';
+
+type Flatten<T> = Identity<{
+    [K in keyof T]: T[K];
+}>;
+type Identity<T> = T;
+type InitialContext = Record<"formData", FormData>;
+/**
+ * Action without schema has no input.
+ */
+type Action<Data, Context> = (params: {
+    ctx: Context;
+}) => Promise<Data>;
+/**
+ * Action with schema will get parsed formData as the input.
+ */
+type SchemaAction<Data, Context, Schema extends ZodSchema> = (params: {
+    ctx: Context;
+    input: z.infer<Schema>;
+}) => Promise<Data>;
+type EmptyZodObject = ZodObject<ZodRawShape>;
+type FormActionBuilder<Schema extends EmptyZodObject, Err = Error, Context = InitialContext> = {
+    input: <T extends ZodRawShape>(schema: ZodObject<T>) => FormActionBuilder<ZodObject<objectUtil.extendShape<T, Schema["shape"]>>, Err, Context>;
+    /**
+     * A finishing call on the builder completing your action.
+     * @param action async function to execute. It will receive parsed formData as input, when the builder was initialized with a schema.
+     * @returns runnable server action exportable from a module.
+     */
+    run: Schema extends undefined ? <Data>(action: Action<Data, Context>) => (state: FormState<Data, Err>, payload: FormData) => Promise<Flatten<FailureState<Err> | SuccessState<Data>>> : <Data>(action: SchemaAction<Data, Context, Schema>) => (state: FormState<Data, Err, z.inferFlattenedErrors<Schema>>, payload: FormData) => Promise<Flatten<InvalidState<z.inferFlattenedErrors<Schema>> | FailureState<Err> | SuccessState<Data>>>;
+    /**
+     * A chainable context enhancing helper.
+     * @param middleware A function which receives the current context, and returns an object which will be added to the context.
+     * @returns FormActionBuilder
+     */
+    use: <NewContext extends Record<string, unknown>>(middleware: ({ ctx }: {
+        ctx: Context;
+    }) => Promise<NewContext>) => FormActionBuilder<Schema, Err, Context & NewContext>;
+    /**
+     * A chainable error handler to handle errors thrown while running the action passed to .run().
+     * It does not receive errors thrown from the context/middleware.
+     * @param processError A function which receives action's errors.
+     * @returns FormActionBuilder
+     */
+    error: <Err>(processError: (params: {
+        error: unknown;
+        ctx: Context;
+    }) => Err) => FormActionBuilder<Schema, Err, Context>;
 };
-type FormState<Data, Error> = InitialState<Data> | FailureState<Error> | SuccessState<Data>;
-declare function createFormAction<Data, Error = Data, Payload = FormData>(formAction: (params: {
-    success: (data: Data) => SuccessState<Data>;
-    failure: (data: Error) => FailureState<Error>;
-}) => (state: FormState<Data, Error>, payload: Payload) => Promise<FormState<Data, Error>>): (state: FormState<Data, Error>, payload: Payload) => Promise<FormState<Data, Error>>;
+declare const formAction: FormActionBuilder<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>, Error, InitialContext>;
 
-export { FailureState, FormState, InitialState, SuccessState, createFormAction };
+export { FailureState, FormState, InvalidState, SuccessState, formAction };

package/dist/index.mjs

@@ -1 +1 @@
-function u(t){function r(a){return{type:"success",data:a,error:null}}function e(a){return{type:"failure",data:null,error:a}}return(a,o)=>t({success:r,failure:e})(a,o)}export{u as createFormAction};
+function p(a){function o(e){return{type:"success",data:e,error:null,validationError:null}}function n(e){return{type:"failure",data:null,error:e,validationError:null}}function l(e){return{type:"invalid",data:null,error:null,validationError:e}}return(e,s)=>a({success:o,failure:n,invalid:l})(e,s)}import{z as D}from"zod";import{zfd as h}from"zod-form-data";function u(a,o=[],n){async function l(t){let r={formData:t};for(let i of o){let d=await i({ctx:r});r={...r,...d}}return r}let e=t=>p(({success:r,failure:i})=>async(d,x)=>{let m=await l(x);try{return r(await t({ctx:m}))}catch(c){if(n)return i(n({error:c,ctx:m}));throw c}}),s=t=>p(({success:r,failure:i,invalid:d})=>{let x=h.formData(a);return async(m,c)=>{let E=await l(c),S=x.safeParse(c);if(!S.success)return d(S.error.flatten());let y=S.data;try{return r(await t({input:y,ctx:E}))}catch(C){if(n)return i(n({error:C,ctx:E}));throw C}}});return{input(t){let r=a.merge(t);return u(r,o)},use(t){return u(a,[...o,t])},error(t){return u(a,o,t)},run:Object.keys(a.shape).length===0?e:s}}var j=u(D.object({}));export{p as createFormAction,j as formAction};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-form-action",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "State management helpers for the react form actions.",
   "repository": {
     "type": "git",
@@ -12,7 +12,8 @@
     "/dist"
   ],
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "test": "vitest"
   },
   "exports": {
     ".": {
@@ -30,18 +31,20 @@
   },
   "keywords": [
     "react",
-    "form",
-    "action",
+    "form-action",
+    "react-form-action",
     "next",
+    "next-form-action",
     "nextjs",
-    "server",
-    "action"
+    "server-action"
   ],
   "author": "Miroslav Petrik",
   "license": "MIT",
   "peerDependencies": {
     "react": ">=18.2",
-    "react-dom": ">=18.2"
+    "react-dom": ">=18.2",
+    "zod": "^3",
+    "zod-form-data": "^2"
   },
   "devDependencies": {
     "@types/react": "^18.2.37",
@@ -49,6 +52,9 @@
     "next": "^14.0.2",
     "react-render-prop-type": "^0.1.0",
     "tsup": "^7.2.0",
-    "typescript": "^5.2.2"
+    "typescript": "^5.2.2",
+    "vitest": "^1.2.2",
+    "zod": "^3.22.4",
+    "zod-form-data": "^2.0.2"
   }
 }