diff --git a/src/routes/solid-router/reference/data-apis/data.json b/src/routes/solid-router/reference/data-apis/data.json index b2aae6844..4db544bd0 100644 --- a/src/routes/solid-router/reference/data-apis/data.json +++ b/src/routes/solid-router/reference/data-apis/data.json @@ -6,7 +6,6 @@ "create-async.mdx", "create-async-store.mdx", "query.mdx", - "response-helpers.mdx", "use-submission.mdx", "use-submissions.mdx" ] diff --git a/src/routes/solid-router/reference/data-apis/response-helpers.mdx b/src/routes/solid-router/reference/data-apis/response-helpers.mdx deleted file mode 100644 index cde1e2e12..000000000 --- a/src/routes/solid-router/reference/data-apis/response-helpers.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Response helpers ---- - -**Note:** These response helpers must be called within a `cache` or `action` function. If you want to -programmatically navigate, you will want to use the [useNavigate](/solid-router/reference/primitives/use-navigate) primitive. - -## Redirect - -Signature: `redirect(path, options)` - -Redirects to the next route. - -```js -const getUser = query(() => { - const user = await api.getCurrentUser(); - if (!user) throw redirect("/login"); - return user; -}) -``` - -## Reload - -Signature: `reload(options)` - -Reloads the data at the given cache key on the current route. - -```js -const getTodo = query(async (id: number) => { - const todo = await fetchTodo(id); - return todo; -}, "todo"); - -const updateTodo = action(async (todo: Todo) => { - await putTodo(todo.id, todo); - return reload({ revalidate: getTodo.keyFor(id) }); -}); -``` - -## json - -Signature: `json(data, options)` - -Returns JSON data from an action while also providing options for controlling revalidation of cache data on the route. - -```js -const getTodo = query(async (id: number) => { - const todo = await fetchTodo(id); - return todo; -}, "todo"); - -const getCompletedTodos = action(async () => { - const completedTodos = await fetchTodo({ status: 'complete' }); - return json(completedTodos, { revalidate: getTodo.keyFor(id) }); -}); -``` diff --git a/src/routes/solid-router/reference/data.json b/src/routes/solid-router/reference/data.json index cb72b51c0..ebaabcf79 100644 --- a/src/routes/solid-router/reference/data.json +++ b/src/routes/solid-router/reference/data.json @@ -1,4 +1,10 @@ { "title": "Reference", - "pages": ["components", "data-apis", "preload-functions", "primitives"] + "pages": [ + "components", + "data-apis", + "response-helpers", + "preload-functions", + "primitives" + ] } diff --git a/src/routes/solid-router/reference/response-helpers/data.json b/src/routes/solid-router/reference/response-helpers/data.json new file mode 100644 index 000000000..f61b14f3c --- /dev/null +++ b/src/routes/solid-router/reference/response-helpers/data.json @@ -0,0 +1,4 @@ +{ + "title": "Response Helpers", + "pages": ["json.mdx", "redirect.mdx", "reload.mdx", "revalidate.mdx"] +} diff --git a/src/routes/solid-router/reference/response-helpers/json.mdx b/src/routes/solid-router/reference/response-helpers/json.mdx new file mode 100644 index 000000000..59e8b2703 --- /dev/null +++ b/src/routes/solid-router/reference/response-helpers/json.mdx @@ -0,0 +1,28 @@ +--- +title: json +--- + +Returns JSON data from an action while also providing options for controlling revalidation of cache data on the route. + +```ts title="/actions/get-completed-todos.ts" {7} +import { action, json } from "@solidjs/router"; +import { fetchTodo } from "../fetchers"; + +const getCompletedTodos = action(async () => { + const completedTodos = await fetchTodo({ status: 'complete' }); + + return json(completedTodos, { revalidate: getTodo.keyFor(id) }); +}); +``` + +Also read [action](/solid-router/reference/data-apis/action) and [revalidate](/solid-router/reference/response-helpers/revalidate). + +## Type Signature + +```typescript +interface ResponseOptions { + revalidate?: string | string[]; +} + +json(data: T, opt?: ResponseOptions): CustomResponse; +``` \ No newline at end of file diff --git a/src/routes/solid-router/reference/response-helpers/redirect.mdx b/src/routes/solid-router/reference/response-helpers/redirect.mdx new file mode 100644 index 000000000..20d427b18 --- /dev/null +++ b/src/routes/solid-router/reference/response-helpers/redirect.mdx @@ -0,0 +1,71 @@ +--- +title: redirect +--- + +Redirects to the next route. +When done over a server RPC (Remote Procedure Call), the redirect will be done through the server. +By default the status code of a `redirect()` is `302 - FOUND`, also known as a temporary redirect. + +Other useful redirect codes: + +| Code | Description | +| ---- | ----------- | +| `301` | Moved Permanently | +| `307` | Temporary Redirect | +| `308` | Permanent redirect | + + +307 and 308 won't allow the browser to change the method of the request. If you want to change the method, you should use 301 or 302. + + +A common use-case for throwing a redirect is when a user is not authenticated and needs to be sent to the login page or another public route. + +```js title="/queries/get-user.ts" {7} +import { query, redirect } from "@solidjs/router"; +import { getCurrentUser } from "../auth"; + +const getUser = query(() => { + const user = await getCurrentUser(); + + if (!user) throw redirect("/login"); + + return user; +}, "get-user") +``` + +## Single-Flight Mutations + +When using `redirect` during a Server Action, the redirect will be done through the server. +The response value will automatically send data for the destination route, avoiding a subsequent roundtrip to load the data from the target route. + +This is useful when redirecting the user to a different route once a mutation is done. + +```ts title="/actions/add-user.ts" {3,6} +import { action, redirect } from "@solidjs/router"; + +const addUser = action(async (user: User) => { + await postUser(user); + + return redirect("/users"); +}); +``` + +The `addUser` action will redirect the user to the `/users` route once the user has been added to the database. +The response from the form action will send the updated data for the `/users` route without the developer needing to revalidate or reload. + +## Throw vs Return + +Both `throw` and `return` can be used to redirect the user to a different route. +For general usage `throw` is recommended as it immediately stops the execution of the current action and redirects the user. + +When returning from a nested method, the parent method will continue to execute, which can lead to unexpected behavior. + +### TypeScript Signature + +```typescript +interface ResponseOptions { + revalidate?: string | string[]; +} | number + +function redirect(url: string, opts = 302): CustomResponse; +``` diff --git a/src/routes/solid-router/reference/response-helpers/reload.mdx b/src/routes/solid-router/reference/response-helpers/reload.mdx new file mode 100644 index 000000000..02382ae5b --- /dev/null +++ b/src/routes/solid-router/reference/response-helpers/reload.mdx @@ -0,0 +1,30 @@ +--- +title: reload +--- + +Reload is a response helper built on top of [revalidate](/solid-router/response-helpers/revalidate). +It will receive a cache key, or an array of cache keys, to invalidate those queries, and cause them to fire again. + +```ts title="/actions/update-todo.ts"{4} +import { action, reload } from "@solidjs/router"; +import { putTodo, getTodo } from "../db"; + +const updateTodo = action(async (todo: Todo) => { + await putTodo(todo.id, todo); + + return reload({ revalidate: getTodo.keyFor(id) }); +}); +``` + +The code snippet above uses the cache-key from a user-defined query (`getTodo`). +To better understand how queries work, check the [query](/solid-router/reference/data-apis/query) documentation. + +## TypeScript Signature + +```ts +interface ResponseOptions { + revalidate?: string | string[]; +} + +reload(opt?: ResponseOptions): CustomResponse; +``` \ No newline at end of file diff --git a/src/routes/solid-router/reference/response-helpers/revalidate.mdx b/src/routes/solid-router/reference/response-helpers/revalidate.mdx new file mode 100644 index 000000000..c7de6fbcc --- /dev/null +++ b/src/routes/solid-router/reference/response-helpers/revalidate.mdx @@ -0,0 +1,43 @@ +--- +title: revalidate +--- + +Revalidate will receive the either a cache key or an array of cache keys and invalidate those queries. + + +If you intend to re-fire the queries immediately, check the [reload](/solid-router/reference/response-helpers/reload) helper. + + +The code below will revalidate the `getTodo` query with the cache key. + +```ts title="/actions/update-todo.ts"{4} +import { action, revalidate } from "@solidjs/router"; + +const updateTodo = action(async (todo: Todo) => { + await putTodo(todo.id, todo); + + return revalidate(getTodo.keyFor()); +}); +``` + +To better understand how queries work, check the [query](/solid-router/reference/data-apis/query) documentation. + +## Force Revalidation + +The `revalidate` function also accepts a second parameter to force the revalidation of the cache data. + +```ts title="/actions/update-todo.ts"{4} +import { action, revalidate } from "@solidjs/router"; + +const updateTodo = action(async (todo: Todo) => { + await putTodo(todo.id, todo); + + return revalidate(getTodo.keyFor(), true); +}); +``` + +## TypeScript Signature + +```ts +function revalidate(key?: string | string[] | void, force?: boolean): Promise; +```