Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve handler() reference docs #9261

Merged
merged 3 commits into from
Aug 29, 2024
Merged

Improve handler() reference docs #9261

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3ac3582
Improve `handler()` reference docs
delucis Aug 29, 2024
76781bd
Better with Sarah
delucis Aug 29, 2024
1780e69
Better with Armand!
delucis Aug 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 9 additions & 11 deletions src/content/docs/en/reference/api-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2495,15 +2495,15 @@ Actions help you build a type-safe backend you can call from client code and HTM
<Since v="4.15.0" />
</p>

The `defineAction()` utility is used to define new actions from the `src/actions/index.ts` file. This accepts a `handler()` function containing the server logic to run, and an optional `input` property to validate input parameters at runtime.
The `defineAction()` utility is used to define new actions from the `src/actions/index.ts` file. This accepts a [`handler()`](#handler-property) function containing the server logic to run, and an optional [`input`](#input-validator) property to validate input parameters at runtime.

```ts
export const server = {
getGreeting: defineAction({
getGreeting: defineAction({
input: z.object({
name: z.string(),
}),
handler: async (input) => {
handler: async (input, context) => {
return `Hello, ${input.name}!`
}
Comment on lines +2506 to 2508
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a good idea to show that context is also available, but shouldn't we update the example to include context?

This is a rough draft (I haven't taken the time to familiarize myself with Actions yet to find a better example) but maybe something like:

Suggested change
handler: async (input, context) => {
return `Hello, ${input.name}!`
}
handler: async (input, context) => {
if (!input.name) context.redirect();
return `Hello, ${input.name}!`
}

Copy link
Member Author

@delucis delucis Aug 29, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

context.redirect() is not available on this version of context 😅

I also thought about this, but I mainly wanted to show it exists here without muddying the example. I think the reason context was excluded in the initial version is that it’s mostly for pretty advanced use cases (for example it allows you to read context.locals if you have some middleware), so I think it’s OK not to demonstrate it — just to mention its existence.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I did say that I wasn't familiar enough with this feature. 😅 It's good for me so, no need for an overly complex example!

})
Expand All @@ -2512,19 +2512,17 @@ export const server = {

#### `handler()` property

<p>
<Since v="4.15.0" />
</p>
**Type:** `(input, context) => any`
delucis marked this conversation as resolved.
Show resolved Hide resolved

`defineAction()` requires a `handler()` function containing the server logic to run when the action is called. This function can return data that is automatically serialized and sent to the caller.
delucis marked this conversation as resolved.
Show resolved Hide resolved

`defineAction()` accepts a `handler()` function containing the server logic to run when the action is called. This function can return data that is automatically serialized and sent to the caller.
The `handler()` is called with user input as its first argument. If an [`input`](#input-validator) validator is set, the user input will be validated before being passed to the handler. The second argument is a `context` object containing most of Astro’s [standard endpoint context](#endpoint-context), excluding `getActionResult()`, `callAction()`, and `redirect()`.

Return values are parsed using the [devalue library](https://github.com/Rich-Harris/devalue). This supports JSON values, along with instances of `Date()`, `Map()`, `Set()`, or `URL()`.
Return values are parsed using the [devalue library](https://github.com/Rich-Harris/devalue). This supports JSON values and instances of `Date()`, `Map()`, `Set()`, and `URL()`.

#### `input` validator

<p>
<Since v="4.15.0" />
</p>
**Type:** `ZodObject | undefined`
delucis marked this conversation as resolved.
Show resolved Hide resolved

The optional `input` property accepts a Zod validator to validate handler inputs at runtime. If the action fails to validate, [a `BAD_REQUEST` error](#actionerror) is returned and the `handler` is not called.

Expand Down
Loading