Extend Astro.getActionResult and/or getActionContext to surface inputs of the latest request

[essential-randomness]

Summary

Allow consumers of action results to easily access the inputs of the action, just like they can now access results and errors.

Background & Motivation

Broadly, my question was: if my form action has an error and I want to know what data was originally submitted, how can I get this information back? This is what I came up with:

const hideSubmissionResult = Astro.getActionResult(actions.hideSubmission);
const body = await Astro.request.clone().formData();
const actionSubmissionAtUri = body.get("atUri").valueOf();

There are multiple ways one can use this value, like more complex error messages that mention the original value, link to relevant data (e.g. in this case, a link to the original URI to manually check if it matches expectations), etc.

My particular use case is that I like to have actions handling self-contained within a component, and so I want each component to be able to tell if the action started from itself. That is:

---
interface Props {
  atUri: AtUri;
}

const { atUri } = Astro.props;

const hideSubmissionResult = Astro.getActionResult(actions.hideSubmission);
const body = await Astro.request.clone().formData();
const actionSubmissionAtUri = body.get("atUri").valueOf();
---
<!-- form code -->
{actionSubmissionAtUri == atUri && hideSubmissionResult?.error && (
<div>
    <p class="error">{hideSubmissionResult.error.message}</p>
</div>
)}

Here's a slightly different variation, where the action originated from the component, but I want to be able to have a global message.

---
const hideSubmissionResult = Astro.getActionResult(actions.hideSubmission);
const body = await Astro.request.clone().formData();
const actionSubmissionAtUri = body.get("atUri").valueOf();
---
<!-- page code -->
{hideSubmissionResult.data && <div>Good job hiding {actionSubmissionAtUri}!</div>}
<!-- page code -->
{ // The action will originate from one of these cards, but I don't know which here
  submissions.map(submission => <SubmissionCard atUri={atUri} />)
}

Note that when I do this for every Card I get:

(node:72421) MaxListenersExceededWarning: Possible EventTarget memory leak detected. 
11 abort listeners added to [AbortSignal].  Use events.setMaxListeners() to increase limit

Obviously doing it in a middleware and passing it down would avoid this, but I do believe this should be an easy thing to access—result data and errors are there already, after all!

Goals

• Make it easy and intuitive to get back the original data of the action submitted in the current request

Example

What I'd like is to write my components like this:

---
interface Props {
  atUri: AtUri;
}

const { atUri } = Astro.props;

const hideSubmissionResult = Astro.getActionResult(actions.hideSubmission);
const actionSubmissionAtUri = hideSubmissionResult.inputData.atUri;
---
<!-- form code -->
{actionSubmissionAtUri == atUri && hideSubmissionResult?.error && (
<div>
    <p class="error">{hideSubmissionResult.error.message}</p>
</div>
)}

And similarly

---
const hideSubmissionResult = Astro.getActionResult(actions.hideSubmission);
const actionSubmissionAtUri = hideSubmissionResult.inputData.atUri;
---
<!-- page code -->
{hideSubmissionResult.data && <div>Good job hiding {actionSubmissionAtUri}!</div>}
<!-- page code -->
{ // The action will originate from one of these cards, but I don't know which here
  submissions.map(submission => <SubmissionCard atUri={atUri} />)
}

Much cleaner!

Now, it was also suggested to surface this from getActionContext. I'm not going to say no to that. I think it should be in both.

Typing

Obviously you couldn't really make this type safe if there's an error (after all it did fail validation), but even then I'd be very happy to get the data the action received, including undeclared one, as for example:

type InputDataOnError = {
  // Declare these explicitly so you still get autocomplete... I think 
  // I'd also need to think more about potential types
  atUri?: string;
} & Record<string, unknown>;

This would be different for form actions vs json, but it shouldn't be impossible to figure out.

[Fryuni]

Regarding types, the request might have come with a single string or number in place of the whole object, or even just malformed in general. So the only type that could be provided in case of error would be { inputData?: unknown }.

It would be incorrect to even give Partial<YourInputType> because the input could be just a null, and no field can be read from it so it would be unsound.

It should be mostly trivial to implement, so contributions are welcome. But since there is really no guarantees about it in case of errors and reusing the values in case of success for something seems like an design mistake or an XY problem, I don't see much benefit to this. The action is an abstraction that includes validation, deciding whether it really is an error or not based on the input shouldn't be leaking to the page.

For the given example, you can customize the errors emitted by Zod with something like "Skipped action" and decide what to show on the UI based on that. Whether a particular input skips the action is defined on the action, whether to show an error on screen depends solely on the error and is defined on the component that renders the error. You can even include the input for that field in the error object if you really want that.

[essential-randomness]

Regarding types, the request might have come with a single string or number in place of the whole object, or even just malformed in general. So the only type that could be provided in case of error would be { inputData?: unknown }.

I wrote a whole thing here, but then I remembered that there are also json actions (I use them with form, mostly) and that json doesn't have guarantee of a valid body being anything but unknown (unlike, unless there's something I don't know, FormData).

[Irrelevant question about how this is dealt with today, feel free to ignore]

I got sent down a rabbit hole of "ok but how do getActionResult errors behave when the Zod validator is not an object??". I haven't had time to look at it running an example, but this is the type isInputError(error) && error.fields end up being, which is... likely wrong?

ActionInputError<ErrorInferenceObject>.fields: {
    [x: string]: string[];
}

Unsure if I'm missing something...this is really my own curiosity, and I should just find the time to try it fully. Even if it were, I don't think this is as relevant here because that's more of a edge case that someone willingly threw themselves in, while with inputs that would be more common.

With that being the case, let's go back to the original goal: the core of my "give me a way pls" is to have a safe and intuitive way to do this:

const hideSubmissionResult = Astro.getActionResult(actions.hideSubmission);
let actionSubmissionAtUri = null;
// This action has run here!
if (hideSubmissionResult) {
  const actionBody = hideSubmissionResult && await Astro.request.formData();
  actionSubmissionAtUri = body.get("atUri").valueOf();
}

This cannot work because after the first time, the Request body has been consumed and an error is thrown. The Astro docs already show how to do this in a form how-to recipe, except they do it in a page, not in a component. This gets around the issue I mentioned because there's no possibility of Request body being consumed twice.

However, I want to be able to both:

• Fully encapsulate my action in a component that accesses its inputs (like the recipe does do!) without accidental errors if I add that component twice in a page
• Have different components access the inputs of the same action (again, like the recipe does do!) without accidental errors if I add another DIFFERENT component to the page who cares about the same action (and its inputs)

This issue forces me to think beyond the boundaries of single components when dealing with a reasonable impulse (getting back the data a user submitted as part of an action).

(Regarding your comment on skipping the action, I'm talking about the opposite: the component decides whether to display something or not according to what was submitted to the action, but the action is always executed. In my use case, I want each component to decide whether it should react to the current action by looking at the id sent within the action data.)

New Example

What about something like:

const hideSubmissionBody = Astro.getActionBody(actions.hideSubmission);
let actionSubmissionAtUri = null;
// Checks it the action has run in this request AND
// there was no error parsing the request body as its "rightful" type (`body.formData()` or `body.json()`)
if (hideSubmissionBody && !hideSubmissionBody.error) {
  // Since this action is a form action, the result of `getActionBody` would have `formData` (typed as `FormData`)
  // If this was a regular action, it would have `json` (typed as `unknown`)
  actionSubmissionAtUri = hideSubmissionBody.formData.get("atUri").valueOf();
}

This would really just cache and return the result of Astro.request.formData() or Astro.request.json() so it can be accessed safely multiple times, with the additional benefit that consumers of actions don't have to stumble upon the overwhelming Request object (and its edge cases) to get back the action data.

Returning FormData and unknown is also consistent with what handler receives if input validator is omitted..

Aside: about the recipe + documentation

It could argued that the "build an HTML form" recipe's example is misleading, and those error messages should really be build on the action itself through Zod's various validation methods. IMO the recipe should indeed be updated, since Zod can easily handle that level of customization.

That said, my experience is that teaching people about Zod error handling increases in complexity quickly: I do love abusing Zod, but I wouldn't want to force people I recommend Astro to (who love Astro Actions!) down the "superRefine" rabbit hole. And again, there are more reasons than error handling to wanting to access the original data anyway.

Regardless of what we decide here, I do believe how to access the original data should be documented somewhere in the actual Actions documentation, not just in a recipe. I can bring this up on the Docs side and I assume they'll deal with getting agreement from the technical side.

[Fryuni]

I wrote a whole thing here, but then I remembered that there are also json actions (I use them with form, mostly) and that json doesn't have guarantee of a valid body being anything but unknown (unlike, unless there's something I don't know, FormData).

Thinking again about this, we might have a guarantee that it would be a FormData instance 🤔

Actions can be called with JSON, but that is through calling the action on client code. Astro.getActionResult is only for actions called from form submissions or from saved action result state (that originally also came from a form).

So it should be fine to provide the form data on the result of that call even on errors.

I got sent down a rabbit hole of "ok but how do getActionResult errors behave when the Zod validator is not an object??"

I believe we just translate the Zod errors into a map of fields to list of error messages. So an error at the root will probably just be mapped to the field '' (empty string) or '.', I don't remember which one Zod v3 uses.

Haven't checked this tho, feel free to explore the rabbit hole 😄

New Example
What about something like:
...

Yeah, for the success case it is totally doable. I wouldn't be against it, but I don't see that as a real gain. If you want to change the logic based on which page submits the form you can look at the referrer using a same-origin policy. The examples you shown seem to be like trying to workaround a problem somewhere else.

Aside: about the recipe + documentation
It could argued that the "build an HTML form" recipe's example is misleading, and those error messages should really be build on the action itself through Zod's various validation methods.

That guide is for building a form without using Actions. It predates the Astro Actions feature and has a callout at the top explaining that. We currently don't have a recipe using Actions, you can add that to the Recipe Ideas discussion or, if you feel like being a write, send a PR with it 📝

[essential-randomness]

Thinking again about this, we might have a guarantee that it would be a FormData instance 🤔

Actions can be called with JSON, but that is through calling the action on client code. Astro.getActionResult is only for actions called from form submissions or from saved action result state (that originally also came from a form).

Oh, nice! Hadn't thought about it, but it makes sense now that you say it.

If you want to change the logic based on which page submits the form you can look at the referrer using a same-origin policy. The examples you shown seem to be like trying to workaround a problem somewhere else.

I'll keep the referrer trick in mind (thank you!), but I don't think it helps with my situation. What I want is:

• I have 1 page
• I have 1 component, e.g. TodoItemCard
• I have (let's say) 50 TodoItemCards on the 1 page
• I add a form in TodoItemCard.astro that submits a markDone action. It has a type="hidden" input with the id of the specific card so the action knows which item is being marked done.
• When the page re-renders after submission, I want each TodoItemCard to (independently):
  • If it was the one that started the action (submitted id == its id), show the the error or success message
  • Otherwise, show nothing

In this case, I don't think I can know which one of the many TodoItemCards submitted the action without looking at the original request. This is especially true in case of errors, since I cannot return the id back as part of the response (which I likely would, but still wouldn't love being forced into).

That guide is for building a form without using Actions. It predates the Astro Actions feature and has a callout at the top explaining that.

I'd ask "how did I miss it??" except I know I have that bad developer habit to skip the intro and go straight to reading the code. Apologies.

If you're ok with me implementing this Astro.getActionBody method, I'll get on that PR first. If I have some stamina left, I'd love to give the "form with actions" recipe a shot! I should be able to just use the existing example as a base, so hopefully it'd be quick.

[Fryuni]

Ok, now I understood the use case. Personally I would have architected it in a different way, but I have never tried what you described to have a proper opinion of pros and cons.

If you're ok with me implementing this Astro.getActionBody method, I'll get on that PR first.

I'm not quite sure about the method name, maybe getActionInput or getActionArguments would be a better compliment name given the existing getActionResult. But this is more of a nitpick, feel free to send a PR and we can change this in the PR during review with input from other reviewers. 😄