feat: Add ActionInputSchema utility type

.changeset/poor-loops-boil.md

@@ -0,0 +1,24 @@
+---
+'astro': minor
+---
+
+Adds the `ActionInputSchema` utility type to automatically infer the TypeScript type of an action's input based on its Zod schema
+
+For example, this type can be used to retrieve the input type of a form action:
+
+```ts
+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 }
+```

packages/astro/src/actions/runtime/server.ts

@@ -38,6 +38,19 @@ export type ActionHandler<TInputSchema, TOutput> = TInputSchema extends z.ZodTyp
 
 export type ActionReturnType<T extends ActionHandler<any, any>> = Awaited<ReturnType<T>>;
 
+const inferSymbol = Symbol('#infer');
+
+/**
+ * Infers the type of an action's input based on its Zod schema
+ *
+ * @see https://docs.astro.build/en/reference/modules/astro-actions/#actioninputschema
+ */
+export type ActionInputSchema<T extends ActionClient<any, any, any>> = T extends {
+	[inferSymbol]: any;
+}
+	? T[typeof inferSymbol]
+	: never;
+
 export type ActionClient<
 	TOutput,
 	TAccept extends ActionAccept | undefined,
@@ -57,6 +70,7 @@ export type ActionClient<
 			orThrow: (
 				input: TAccept extends 'form' ? FormData : z.input<TInputSchema>,
 			) => Promise<Awaited<TOutput>>;
+			[inferSymbol]: TInputSchema;
 		}
 	: ((input?: any) => Promise<SafeResult<never, Awaited<TOutput>>>) & {
 			orThrow: (input?: any) => Promise<Awaited<TOutput>>;

packages/astro/test/types/action-input-schema.ts

@@ -0,0 +1,51 @@
+import { describe, it } from 'node:test';
+import { expectTypeOf } from 'expect-type';
+import { type ActionInputSchema, defineAction } from '../../dist/actions/runtime/server.js';
+import { z } from '../../dist/zod.js';
+
+describe('ActionInputSchema', () => {
+	const acceptVariants = ['form', 'json', undefined] as const;
+
+	for (const accept of acceptVariants) {
+		describe(`accept = ${typeof accept === 'string' ? `'${accept}'` : accept}`, () => {
+			it('Infers action input schema', async () => {
+				const inputSchema = z.object({
+					name: z.string(),
+					age: z.number(),
+				});
+
+				const _action = defineAction({
+					accept,
+					input: inputSchema,
+					handler: () => undefined,
+				});
+
+				expectTypeOf<ActionInputSchema<typeof _action>>().toEqualTypeOf<typeof inputSchema>();
+			});
+
+			it('Infers action input value', async () => {
+				const schema = z.object({
+					name: z.string(),
+					age: z.number(),
+				});
+				const _action = defineAction({
+					accept,
+					input: schema,
+					handler: () => undefined,
+				});
+				expectTypeOf<z.input<ActionInputSchema<typeof _action>>>().toEqualTypeOf<{
+					name: string;
+					age: number;
+				}>();
+			});
+
+			it('Infers action input schema when input is omitted', async () => {
+				const _action = defineAction({
+					accept,
+					handler: () => undefined,
+				});
+				expectTypeOf<ActionInputSchema<typeof _action>>().toBeNever;
+			});
+		});
+	}
+});