feat: Add ActionInputSchema utility type

[mauriciabad]

Changes

Adds the utility type ActionInputSchema that returns the type of the zod schema used in defineAction({ input: z.object(...) }).

This is incredibly useful for creating abstractions that use actions.

The main use will be getting the action input type when the action has accept: 'form'.

Example usage:

import { type ActionInputSchema, defineAction } from 'astro:actions';
import { z } from 'astro/zod';

const action = defineAction({
  accept: 'form',
  input: z.object({ name: z.string() }),
  handler: ({ name }) => ({ message: `Welcome, ${name}!` }),
});

type Schema = ActionInputSchema<typeof action>; 
// typeof z.object({ name: z.string() })

type Input = z.input<Schema>;
// { name: string }

Since it's quite hard to pull off by a non-typescript fluent dev, I suggest including it along the other action utility types.

Decisions to be made

1. If the input validator is omitted, it returns never. Do you think it's fine? Or it should return something else, like undefined?

2. Initially, I was going to create the type ActionInput directly, to avoid having to do z.input<ActionInputSchema<typeof action>>. But I thought the name would be confusing because when the action accepts a form, the input is actually a FormData, not a JS object. And returning the schema seems more versatile. Let me know if you think it would be valuable to also add a utility type ActionInputObject or something like that.

Testing

No tests needed because it's a type.

Docs

The astro-actions page should be updated. I opened a PR with the documentation: withastro/docs#12647

/cc @withastro/maintainers-docs

[changeset-bot]

🦋 Changeset detected

Latest commit: 67c9bb5

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

📝 Changeset Validation Results

❌ Changeset validation failed

Issues Found:

.changeset/poor-loops-boil.md

Issue with: 'Adds the ActionInputSchema utility type to infer an action's input zod schema.'

❌ The description specifies addition or introduction of a feature, which aligns better with the 'minor' change type rather than 'patch'.

💡 Suggestions:
• Use the 'minor' change type for introducing new features and APIs, aligning with the described addition.
• Revise the YAML frontmatter to reflect: ```yaml

'astro': minor

**General Suggestions:**
- Consider revising the change type to better reflect the user's perspective in alignment with the described change (minor instead of patch).

---
*📖 See [Astro's changeset guide](https://contribute.docs.astro.build/docs-for-code-changes/changesets/) for details.*

[codspeed-hq]

CodSpeed Performance Report

Merging #14698 will not alter performance

_{Comparing mauriciabad:patch-1 (67c9bb5) with main (c29a785)}

Summary

✅ 6 untouched

[florian-lefebvre]

Hi, thanks for opening a PR! I think it's a nice addition, a few comments:

1. I wonder if it should be named something else, eg. InferActionInputSchema<T>? Would be nice to check if we have other cases like this in Astro (I don't think we do) and otherwise what other tools use. I'm suggesting "infer" because of zod but really it could be anything
2. Can you add type tests for this? In packages/astro/test/types/

[sarah11918]

Just noting that I will wait to review the docs until @florian-lefebvre 's naming issue has been addressed!

[mauriciabad]

@florian-lefebvre Thanks for taking a look.

1. I wouldn't use infer in the name because it would confuse devs. z.infer<T> transformations a ZodType to its TypeScript type, on the other side ActionInputSchema<T> returns the ZodType. Maybe we could also add InferActionInput<T>, that does z.infer<ActionInputSchema<T>>.

2. Yes I'll add the tests

[florian-lefebvre]

Okay makes sense! Then let's keep the currrent naming 👍 (and a single new type helper). FYI we plan to include these changes in 5.16, to be released next week

[mauriciabad]

I added JSDoc; if you don't like it, remove it.

I also added the tests.

[florian-lefebvre]

Approving in terms of code! @sarah11918 this is ready for your review

[sarah11918]

Just a quick note from me re: introducing the code sample!