add more docs for response helpers (#958)

Co-authored-by: Sarah <[email protected]>

Author: atilafassina

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"
 	]

src/routes/solid-router/reference/data-apis/response-helpers.mdx

@@ -1,4 +1,10 @@
 {
 	"title": "Reference",
-	"pages": ["components", "data-apis", "preload-functions", "primitives"]
+	"pages": [
+		"components",
+		"data-apis",
+		"response-helpers",
+		"preload-functions",
+		"primitives"
+	]
 }

src/routes/solid-router/reference/data.json

@@ -0,0 +1,4 @@
+{
+	"title": "Response Helpers",
+	"pages": ["json.mdx", "redirect.mdx", "reload.mdx", "revalidate.mdx"]
+}

src/routes/solid-router/reference/response-helpers/data.json

@@ -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<T>(data: T, opt?: ResponseOptions): CustomResponse<T>;
+``` 

src/routes/solid-router/reference/response-helpers/json.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 |
+
+<Callout type="tip" name="Redirect Methods">
+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.
+</Callout>
+
+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<never>;
+``` 

src/routes/solid-router/reference/response-helpers/redirect.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<never>;
+```

src/routes/solid-router/reference/response-helpers/reload.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.
+
+<Callout type="tip" name="Firing Queries Again">
+If you intend to re-fire the queries immediately, check the [reload](/solid-router/reference/response-helpers/reload) helper.
+</Callout>
+
+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<void>;
+```