zsa

Callbacks allow you to execute side effects (like logging or error handling) based on the lifecycle of a server action. You can define them on individual actions or at the procedure level to share them across multiple actions.

Lifecycle Order

When an action is invoked, the callbacks execute in this specific sequence:

1. onStart runs.
2. onInputParseError runs if input parsing fails (execution stops here).
3. The main action handler runs.
4. onSuccess runs (if handler succeeds) OR onError runs (if handler throws).
5. onComplete runs under all exit conditions.
6. The action's response is returned.

Procedure vs. Action Callbacks

• Procedure Callbacks: Defined on a createServerActionProcedure(). They run for every action that uses that procedure.
• Execution Order: Procedure callbacks execute before their corresponding action callbacks. For example, if both a procedure and an action have an onComplete callback, the procedure's onComplete runs first.

const exampleAction = createServerAction()
  .input(z.object({message: z.string()}))
  .onStart(async () => { /* ... */ })
  .onSuccess(async () => { /* ... */ })
  .onComplete(async () => { /* ... */ })
  .onError(async () => { /* ... */ })
  .onInputParseError(async () => { /* ... */ })
  .handler(async ({input}) => { /* ... */ })

When defining error shapes, you can use the typedData object provided to the callback to access input information. This is useful when TypeScript cannot yet infer the full input/output schemas.

typedData contains:

• inputRaw: The raw input data.
• inputParsed: The parsed input data.
• inputParseErrors: Validation errors for the input.
• outputParseErrors: Validation errors for the output.

Note: You must return typedData properties as values within an object; you cannot return a typedData property directly as the error object.

const shapeErrorAction = createServerAction()
  .input(z.object({ number: z.number().refine((n) => n > 0) }))
  .experimental_shapeError(({ err, typedData }) => {
    return {
      inputRaw: typedData.inputRaw,
      inputParsed: typedData.inputParsed,
      inputParseErrors: typedData.inputParseErrors,
      outputParseErrors: typedData.outputParseErrors
    }
  })
  .handler(async ({ input }) => {
    return input.number
  })

You can chain procedures together to create complex authorization layers. By passing an existing procedure as an argument to createServerActionProcedure(previousProcedure), the new procedure will run after the previous one.

Each procedure in the chain can access the ctx returned by the preceding procedure, allowing you to pass data forward (e.g., passing a user object from an authedProcedure to an isAdminProcedure). The final server action will only execute if every procedure in the chain succeeds without throwing an error.

// 1. Base procedure
const authedProcedure = createServerActionProcedure().handler(async () => { /* returns user */ });

// 2. Chained procedure (runs after authedProcedure)
const isAdminProcedure = createServerActionProcedure(authedProcedure)
  .handler(async ({ ctx }) => {
    const role = await getUserRole(ctx.user.id);
    if (role !== "admin") throw new Error("User is not an admin");
    
    return { ...ctx.user, role }; // Passes updated context forward
  });

// 3. Final Action
const deleteUser = isAdminProcedure
  .createServerAction()
  .input(z.object({ userIdToDelete: z.string() }))
  .handler(async ({ input, ctx }) => {
    // ctx contains data from BOTH authedProcedure and isAdminProcedure
    const { user } = ctx;
    // ... logic
  });

Procedures allow you to add additional context to a set of server actions, such as a userId. They are used to enforce conditions (like authentication or permissions) before an action's handler is executed.

To create a basic procedure, use createServerActionProcedure(). You define its logic in a .handler() method. This handler can return data that will be injected into the ctx (context) of any server action that chains off this procedure.

When you chain .createServerAction() onto a procedure, the procedure's handler runs first. If the procedure's handler throws an error, the server action's handler will not execute.

import { createServerActionProcedure } from "zsa"

const authedProcedure = createServerActionProcedure()
  .handler(async () => {
    try {
      const { email, id } = await getUser();
      return { user: { email, id } }
    } catch {
      throw new Error("User not authenticated")
    }
  })

export const updateEmail = authedProcedure
  .createServerAction()
  .input(z.object({ newEmail: z.string() }))
  .handler(async ({ input, ctx }) => {
    const { user } = ctx;
    // ... logic using ctx.user
    return input.newEmail;
  });

When using createServerActionProcedure, shaped errors can be chained. A subsequent procedure in the chain has access to a ctx object containing the error shape defined by the previous procedure. This allows you to incrementally build a complex error object.

const procedureA = createServerActionProcedure()
  .experimental_shapeError(({ err, typedData }) => {
    return { isError: true }
  })
  .handler(() => {})

const procedureB = createServerActionProcedure(procedureA)
  .experimental_shapeError(({ err, typedData, ctx }) => {
    return { ...ctx, addingOn: true }
  })
  .handler(() => {})

const action = procedureB.createServerAction()
  .experimental_shapeError(({ err, typedData, ctx }) => {
    return { ...ctx, addingOnFromAction: true }
  })
  .handler(() => {})

const [data, err] = await action()
type ERROR = typeof err
//   ^? { isError: true; addingOn: true; addingOnFromAction: true } | null