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: 1b69b4d

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 change type is specified as 'patch', but the description suggests it involves new capabilities, better suited for a 'minor' change type.

💡 Update the change type to 'minor' in the frontmatter.

---

📖 See Astro's changeset guide for details.

[codspeed-hq]

CodSpeed Performance Report

Merging #14698 will not alter performance

_{Comparing mauriciabad:patch-1 (1b69b4d) with main (f657183)¹}

Summary

✅ 6 untouched

Footnotes

1. No successful run was found on main (be566b3) during the generation of this report, so f657183 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩