react-form-action 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # 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.
 
 ## Install
 
@@ -10,57 +10,122 @@ 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(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 sendResetPasswordEmail = authAction.run(
+  async ({ ctx: { t }, input: { email } }) => {
+    // do custom work
+    await db.emailPasswordSendPasswordResetEmail({ email });
+
+    // return translated success message
+    return t("resetPasswordEmail.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"
+    }
+
+    try {
+      const { name } = updateUserSchema.parse({
+        name: formData.get("name"),
+      });
 
-        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." });
+      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 +141,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 { I as InitialState, a as InvalidState, b as FailureState, S as SuccessState, F as FormState } from './createFormAction-0c8f36ce.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-0c8f36ce.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, InitialState as I, SuccessState as S, InvalidState as a, FailureState as b, createFormAction as c };

package/dist/index.d.mts

@@ -1,22 +1,58 @@
-type InitialState<T> = {
-    type: "initial";
-    data: T;
-    error: null;
-};
-type FailureState<T> = {
-    type: "failure";
-    data: null;
-    error: T;
+import { F as FormState } from './createFormAction-0c8f36ce.js';
+export { b as FailureState, I as InitialState, a as InvalidState, S as SuccessState, c as createFormAction } from './createFormAction-0c8f36ce.js';
+import { ZodSchema, ZodUndefined, z } from 'zod';
+
+type MiddlewareFn<Context, NewContext extends Record<string, unknown> = Record<string, unknown>> = ({ ctx }: {
+    ctx: Context;
+}) => Promise<NewContext>;
+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 FormActionBuilder<Schema extends ZodSchema = ZodUndefined, Err = Error, Context = InitialContext> = {
+    /**
+     * 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<Data> : <Data>(action: SchemaAction<Data, Context, Schema>) => (state: FormState<Data, Err, ZodErrorMessages<Schema>>, payload: FormData) => Promise<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: (error: unknown) => Err) => FormActionBuilder<Schema, Err, Context>;
 };
-type SuccessState<T> = {
-    type: "success";
-    data: T;
-    error: null;
+declare function formAction<Schema extends ZodSchema = ZodUndefined, Err = Error, Context = InitialContext, NewContext extends Record<string, unknown> = Record<string, unknown>>(schema?: Schema, 
+/**
+ * @private
+ */
+middleware?: MiddlewareFn<Context, NewContext>[], 
+/**
+ * @private
+ */
+processError?: (error: unknown) => Err): FormActionBuilder<Schema, Err, Context>;
+type ZodErrorMessages<Schema extends ZodSchema> = {
+    [k in keyof z.infer<Schema>]?: string;
 };
-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>>;
 
-export { FailureState, FormState, InitialState, SuccessState, createFormAction };
+export { FormState, 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 x(r){function n(a){return{type:"success",data:a,error:null,validationError:null}}function e(a){return{type:"failure",data:null,error:a,validationError:null}}function i(a){return{type:"invalid",data:null,error:null,validationError:a}}return(a,m)=>r({success:n,failure:e,invalid:i})(a,m)}function C(r,n=[],e){async function i(t){let o={formData:t};for(let c of n){let d=await c({ctx:o});o={...o,...d}}return o}return{run:r?t=>x(({success:o,failure:c,invalid:d})=>async(S,s)=>{let l=await i(s),u=r.safeParse(s);if(!u.success)return d(D(u.error));let p=u.data;try{return o(await t({input:p,ctx:l}))}catch(E){if(e)return c(e(E));throw E}}):t=>x(({success:o,failure:c})=>async(d,S)=>{let s=await i(S);try{return o(await t({ctx:s}))}catch(l){if(e)return c(e(l));throw l}}),use(t){return C(r,[...n,t])},error(t){return C(r,n,t)}}}var D=r=>r.errors.reduce((n,{message:e,path:i})=>({...n,[i[0]]:e}),{});export{x as createFormAction,C as formAction};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-form-action",
-  "version": "0.1.0",
+  "version": "0.2.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,19 @@
   },
   "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"
   },
   "devDependencies": {
     "@types/react": "^18.2.37",
@@ -49,6 +51,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"
   }
 }