refactor: pass utils to validation errors shape customizer functions (#…

…263)

Code in this PR adds a second argument to `handleValidationErrorsShape`
and `handleBindArgsValidationErrorsShape` functions, called `utils`,
which is an object that contains `clientInput`, `bindArgsClientInputs`,
`metadata` and `ctx` properties. This addition allows you to set dynamic
validation errors based on current action execution data.

re #256

packages/next-safe-action/src/action-builder.ts

@@ -46,8 +46,8 @@ export function actionBuilder<
  bindArgsSchemas?: BAS;
  outputSchema?: OS;
  validationAdapter: ValidationAdapter;
- handleValidationErrorsShape: HandleValidationErrorsShapeFn<IS, CVE>;
- handleBindArgsValidationErrorsShape: HandleBindArgsValidationErrorsShapeFn<BAS, CBAVE>;
+ handleValidationErrorsShape: HandleValidationErrorsShapeFn<IS, BAS, MD, Ctx, CVE>;
+ handleBindArgsValidationErrorsShape: HandleBindArgsValidationErrorsShapeFn<IS, BAS, MD, Ctx, CBAVE>;
  metadataSchema: MetadataSchema;
  metadata: MD;
  handleServerError: NonNullable<SafeActionClientOpts<ServerError, MetadataSchema, any>["handleServerError"]>;
@@ -179,7 +179,14 @@ export function actionBuilder<
  const validationErrors = buildValidationErrors<IS>(parsedInput.issues);
 
  middlewareResult.validationErrors = await Promise.resolve(
- args.handleValidationErrorsShape(validationErrors)
+ args.handleValidationErrorsShape(validationErrors, {
+ clientInput: clientInputs.at(-1) as IS extends Schema ? InferIn<IS> : undefined,
+ bindArgsClientInputs: (bindArgsSchemas.length
+ ? clientInputs.slice(0, -1)
+ : []) as InferInArray<BAS>,
+ ctx: currentCtx as Ctx,
+ metadata: args.metadata as MetadataSchema extends Schema ? Infer<MetadataSchema> : undefined,
+ })
  );
  }
  }
@@ -188,7 +195,17 @@ export function actionBuilder<
  // If there are bind args validation errors, format them and store them in the middleware result.
  if (hasBindValidationErrors) {
  middlewareResult.bindArgsValidationErrors = await Promise.resolve(
- args.handleBindArgsValidationErrorsShape(bindArgsValidationErrors as BindArgsValidationErrors<BAS>)
+ args.handleBindArgsValidationErrorsShape(
+ bindArgsValidationErrors as BindArgsValidationErrors<BAS>,
+ {
+ clientInput: clientInputs.at(-1) as IS extends Schema ? InferIn<IS> : undefined,
+ bindArgsClientInputs: (bindArgsSchemas.length
+ ? clientInputs.slice(0, -1)
+ : []) as InferInArray<BAS>,
+ ctx: currentCtx as Ctx,
+ metadata: args.metadata as MetadataSchema extends Schema ? Infer<MetadataSchema> : undefined,
+ }
+ )
  );
  }
 
@@ -241,7 +258,16 @@ export function actionBuilder<
  // If error is `ActionServerValidationError`, return `validationErrors` as if schema validation would fail.
  if (e instanceof ActionServerValidationError) {
  const ve = e.validationErrors as ValidationErrors<IS>;
- middlewareResult.validationErrors = await Promise.resolve(args.handleValidationErrorsShape(ve));
+ middlewareResult.validationErrors = await Promise.resolve(
+ args.handleValidationErrorsShape(ve, {
+ clientInput: clientInputs.at(-1) as IS extends Schema ? InferIn<IS> : undefined,
+ bindArgsClientInputs: (bindArgsSchemas.length
+ ? clientInputs.slice(0, -1)
+ : []) as InferInArray<BAS>,
+ ctx: currentCtx as Ctx,
+ metadata: args.metadata as MetadataSchema extends Schema ? Infer<MetadataSchema> : undefined,
+ })
+ );
  } else {
  // If error is not an instance of Error, wrap it in an Error object with
  // the default message.

packages/next-safe-action/src/safe-action-client.ts

@@ -42,8 +42,8 @@ export class SafeActionClient<
  readonly #ctxType: Ctx;
  readonly #bindArgsSchemas: BAS;
  readonly #validationAdapter: ValidationAdapter;
- readonly #handleValidationErrorsShape: HandleValidationErrorsShapeFn<IS, CVE>;
- readonly #handleBindArgsValidationErrorsShape: HandleBindArgsValidationErrorsShapeFn<BAS, CBAVE>;
+ readonly #handleValidationErrorsShape: HandleValidationErrorsShapeFn<IS, BAS, MD, Ctx, CVE>;
+ readonly #handleBindArgsValidationErrorsShape: HandleBindArgsValidationErrorsShapeFn<IS, BAS, MD, Ctx, CBAVE>;
  readonly #defaultValidationErrorsShape: ODVES;
  readonly #throwValidationErrors: boolean;
 
@@ -56,8 +56,8 @@ export class SafeActionClient<
  outputSchema: OS;
  bindArgsSchemas: BAS;
  validationAdapter: ValidationAdapter;
- handleValidationErrorsShape: HandleValidationErrorsShapeFn<IS, CVE>;
- handleBindArgsValidationErrorsShape: HandleBindArgsValidationErrorsShapeFn<BAS, CBAVE>;
+ handleValidationErrorsShape: HandleValidationErrorsShapeFn<IS, BAS, MD, Ctx, CVE>;
+ handleBindArgsValidationErrorsShape: HandleBindArgsValidationErrorsShapeFn<IS, BAS, MD, Ctx, CBAVE>;
  ctxType: Ctx;
  } & Required<
  Pick<
@@ -143,7 +143,7 @@ export class SafeActionClient<
  >(
  inputSchema: OIS,
  utils?: {
- handleValidationErrorsShape?: HandleValidationErrorsShapeFn<AIS, OCVE>;
+ handleValidationErrorsShape?: HandleValidationErrorsShapeFn<AIS, BAS, MD, Ctx, OCVE>;
  }
  ) {
  return new SafeActionClient({
@@ -163,8 +163,9 @@ export class SafeActionClient<
  outputSchema: this.#outputSchema,
  validationAdapter: this.#validationAdapter,
  handleValidationErrorsShape: (utils?.handleValidationErrorsShape ??
- this.#handleValidationErrorsShape) as HandleValidationErrorsShapeFn<AIS, OCVE>,
- handleBindArgsValidationErrorsShape: this.#handleBindArgsValidationErrorsShape,
+ this.#handleValidationErrorsShape) as HandleValidationErrorsShapeFn<AIS, BAS, MD, Ctx, OCVE>,
+ handleBindArgsValidationErrorsShape: this
+ .#handleBindArgsValidationErrorsShape as HandleBindArgsValidationErrorsShapeFn<AIS, BAS, MD, Ctx, CBAVE>,
  ctxType: {} as Ctx,
  defaultValidationErrorsShape: this.#defaultValidationErrorsShape,
  throwValidationErrors: this.#throwValidationErrors,
@@ -185,7 +186,7 @@ export class SafeActionClient<
  : BindArgsValidationErrors<OBAS>,
  >(
  bindArgsSchemas: OBAS,
- utils?: { handleBindArgsValidationErrorsShape?: HandleBindArgsValidationErrorsShapeFn<OBAS, OCBAVE> }
+ utils?: { handleBindArgsValidationErrorsShape?: HandleBindArgsValidationErrorsShapeFn<IS, OBAS, MD, Ctx, OCBAVE> }
  ) {
  return new SafeActionClient({
  middlewareFns: this.#middlewareFns,
@@ -196,9 +197,15 @@ export class SafeActionClient<
  bindArgsSchemas,
  outputSchema: this.#outputSchema,
  validationAdapter: this.#validationAdapter,
- handleValidationErrorsShape: this.#handleValidationErrorsShape,
+ handleValidationErrorsShape: this.#handleValidationErrorsShape as unknown as HandleValidationErrorsShapeFn<
+ IS,
+ OBAS,
+ MD,
+ Ctx,
+ CVE
+ >,
  handleBindArgsValidationErrorsShape: (utils?.handleBindArgsValidationErrorsShape ??
- this.#handleBindArgsValidationErrorsShape) as HandleBindArgsValidationErrorsShapeFn<OBAS, OCBAVE>,
+ this.#handleBindArgsValidationErrorsShape) as HandleBindArgsValidationErrorsShapeFn<IS, OBAS, MD, Ctx, OCBAVE>,
  ctxType: {} as Ctx,
  defaultValidationErrorsShape: this.#defaultValidationErrorsShape,
  throwValidationErrors: this.#throwValidationErrors,

packages/next-safe-action/src/validation-errors.types.ts

@@ -1,4 +1,4 @@
-import type { Infer, Schema } from "./adapters/types";
+import type { Infer, InferIn, Schema } from "./adapters/types";
 import type { Prettify } from "./utils.types";
 
 // Object with an optional list of validation errors.
@@ -46,13 +46,37 @@ export type FlattenedBindArgsValidationErrors<BAVE extends readonly ValidationEr
 /**
  * Type of the function used to format validation errors.
  */
-export type HandleValidationErrorsShapeFn<S extends Schema | undefined, CVE> = (
- validationErrors: ValidationErrors<S>
+export type HandleValidationErrorsShapeFn<
+ S extends Schema | undefined,
+ BAS extends readonly Schema[],
+ MD,
+ Ctx extends object,
+ CVE,
+> = (
+ validationErrors: ValidationErrors<S>,
+ utils: {
+ clientInput: S extends Schema ? InferIn<S> : undefined;
+ bindArgsClientInputs: BAS;
+ metadata: MD;
+ ctx: Prettify<Ctx>;
+ }
 ) => CVE;
 
 /**
  * Type of the function used to format bind arguments validation errors.
  */
-export type HandleBindArgsValidationErrorsShapeFn<BAS extends readonly Schema[], CBAVE> = (
- bindArgsValidationErrors: BindArgsValidationErrors<BAS>
+export type HandleBindArgsValidationErrorsShapeFn<
+ S extends Schema | undefined,
+ BAS extends readonly Schema[],
+ MD,
+ Ctx extends object,
+ CBAVE,
+> = (
+ bindArgsValidationErrors: BindArgsValidationErrors<BAS>,
+ utils: {
+ clientInput: S extends Schema ? InferIn<S> : undefined;
+ bindArgsClientInputs: BAS;
+ metadata: MD;
+ ctx: Prettify<Ctx>;
+ }
 ) => CBAVE;

website/docs/define-actions/validation-errors.md

@@ -13,7 +13,7 @@ This can be customized both at the safe action client level and at the action le
 - using [`defaultValidationErrorsShape`](/docs/define-actions/create-the-client#defaultvalidationerrorsshape) optional property in `createSafeActionClient`;
 - using `handleValidationErrorsShape` and `handleBindArgsValidationErrorsShape` optional functions in [`schema`](/docs/define-actions/instance-methods#schema) and [`bindArgsSchemas`](/docs/define-actions/instance-methods#bindargsschemas) methods.
 
-The second way overrides the shape set at the instance level, per action. More information below.
+The second way overrides the shape set at the instance level, per action.
 
 For example, if you want to flatten the validation errors (emulation of Zod's [`flatten`](https://zod.dev/ERROR_HANDLING?id=flattening-errors) method), you can (but not required to) use the `flattenValidationErrors` utility function exported from the library, combining it with `handleValidationErrorsShape` inside `schema` method:
 
@@ -39,19 +39,21 @@ export const loginUser = actionClient
  // Here we use the `flattenValidationErrors` function to customize the returned validation errors
  // object to the client.
  // highlight-next-line
- handleValidationErrorsShape: (ve) => flattenValidationErrors(ve).fieldErrors,
+ handleValidationErrorsShape: (ve, utils) => flattenValidationErrors(ve).fieldErrors,
  })
  .bindArgsSchemas(bindArgsSchemas, {
  // Here we use the `flattenBindArgsValidatonErrors` function to customize the returned bind args
  // validation errors object array to the client.
  // highlight-next-line
- handleBindArgsValidationErrors: (ve) => flattenBindArgsValidationErrors(ve),
+ handleBindArgsValidationErrors: (ve, utils) => flattenBindArgsValidationErrors(ve),
  })
  .action(async ({ parsedInput: { username, password } }) => {
  // Your code here...
  });
 ```
 
+The second argument of both `handleValidationErrorsShape` and `handleBindArgsValidationErrors` functions is an `utils` object that contains info about the current action execution (`clientInput`, `bindArgsClientInputs`, `metadata` and `ctx` properties). It's passed to the functions to allow granular and dynamic customization of the validation errors shape.
+
 :::note
 If you chain multiple `schema` methods, as explained in the [Extend previous schema](/docs/define-actions/extend-previous-schemas) page, and want to override the default validation errors shape, you **must** use `handleValidationErrorsShape` inside the last `schema` method, otherwise there would be a type mismatch in the returned action result.
 :::