data-api wip

Author: LadyBluenotes

src/routes/solid-router/reference/data-apis/action.mdx

@@ -1,28 +1,18 @@
 ---
 title: action
 use_cases: >-
-  forms, user input, data mutations, optimistic updates, form submissions,
-  server actions, post requests
+  actions, form actions, mutations, submissions
 tags:
   - actions
   - forms
   - mutations
-  - post
-  - validation
-  - optimistic-updates
-  - server
+  - submissions
 version: "1.0"
 description: >-
-  Learn how to handle form submissions and data mutations in SolidJS with
-  actions, including optimistic updates and server-side processing.
+  action wraps an async function as a router action.
 ---
 
-The `action` function wraps an asynchronous function and returns an [action](/solid-router/concepts/actions).
-
-When an action is triggered, it creates a submission object that tracks its execution status.
-This state can be accessed with the [`useSubmission`](/solid-router/reference/data-apis/use-submission) and [`useSubmissions`](/solid-router/reference/data-apis/use-submissions) primitives.
-
-After an action completed successfully, all queries active in the same page are revalidated, unless revalidation is configured using [response helpers](/solid-router/concepts/actions#managing-navigation-and-revalidation).
+`action` wraps an async function and returns an action function with router submission tracking. Matching submissions can be read with [`useSubmission`](/solid-router/reference/data-apis/use-submission) and [`useSubmissions`](/solid-router/reference/data-apis/use-submissions).
 
 ## Import
 
@@ -40,116 +30,121 @@ function action<T extends Array<any>, U = void>(
 
 function action<T extends Array<any>, U = void>(
 	fn: (...args: T) => Promise<U>,
-	options?: { name?: string; onComplete?: (s: Submission<T, U>) => void }
-): Action<T, U>;
-
-function action<T extends Array<any>, U = void>(
-	fn: (...args: T) => Promise<U>,
-	options:
-		| string
-		| { name?: string; onComplete?: (s: Submission<T, U>) => void } = {}
+	options?: {
+		name?: string;
+		onComplete?: (submission: Submission<T, U>) => void;
+	}
 ): Action<T, U>;
 ```
 
 ## Parameters
 
-### `handler`
+### `fn`
 
 - **Type:** `(...args: T) => Promise<U>`
 - **Required:** Yes
 
-An asynchronous function that performs the action's logic.
-When the action is used with a [`<form>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/form), the function receives a [`FormData` object](https://developer.mozilla.org/en-US/docs/Web/API/FormData) as its first parameter.
+Async function called when the action runs.
 
-### `options`
+When native form handling calls the action, the argument is `FormData` for `multipart/form-data` forms and `URLSearchParams` otherwise.
 
-- **Type:** `string | { name?: string; onComplete?: (s: Submission<T, U>) => void }`
-- **Required**: No
 
-A unique string used to identify the action in Server-Side Rendering (SSR) environments.
-This is required when using the action with a `<form>` element.
 
-Alternatively, a configuration object can be passed with the following properties.
+### `options`
+
+- **Type:** `{ name?: string; onComplete?: (submission: Submission<T, U>) => void }`
+- **Required:** No
+
+Action options.
 
 #### `name`
 
 - **Type:** `string`
 - **Required:** No
 
-The unique string to identify the action in SSR environments.
-Required for `<form>` usage.
+Name used to create the action URL.
+
+The name provides a stable URL for form actions and server rendering.
 
-#### `onComplete` (optional):
+#### `onComplete`
 
-- **Type:** `(s: Submission<T, U>) => void`
+- **Type:** `(submission: Submission<T, U>) => void`
 - **Required:** No
 
-A function that runs after the action completes.
-It receives a submission object as its parameter.
+Function called after the action response is handled.
 
 ## Return value
 
-`action` returns an action with the following properties.
+`action` returns a function with the following properties:
+
+### `url`
+
+- **Type:** `string`
+
+String used when the action is rendered as a form `action` and when submissions are matched back to this action. The optional `name` provides a stable value for this string.
 
 ### `with`
 
-A method that wraps the original action and returns a new one.
-When this new action is triggered, the arguments passed to `with` are forwarded to the original action.
-If this new action is used with a `<form>`, the `FormData` object is passed as the last parameter, after any other forwarded parameters.
+- **Type:** `(...args: any[]) => Action<any[], U>`
+
+Function that creates an action with leading arguments prefilled.
+
+## Behavior
+
+- Calling an action adds a submission to the router submissions signal.
+- Each submission exposes `input`, `url`, `result`, `error`, `pending`, `clear`, and `retry`.
+- `with` creates another action that calls the original action with leading arguments already supplied.
+- `onComplete` receives a submission snapshot after the response is handled.
+- `Response` objects with an `X-Revalidate` header supply the keys passed to `revalidate`; without that header, action response handling passes `undefined`.
+- Returned `Response` objects with a `Location` header trigger client navigation to that location.
+- On the client, actions are registered by URL in the action map and removed during cleanup when an owner exists.
+- If an action has no URL, converting it to a string throws.
 
 ## Examples
 
-### Form submission
+### Basic usage
 
 ```tsx
 import { action } from "@solidjs/router";
 
-const addTodoAction = action(async (formData: FormData) => {
-	// Adds a new todo to the server.
+const addTodo = action(async (data: URLSearchParams) => {
+	return data.get("title")?.toString();
 }, "addTodo");
 
 function TodoForm() {
 	return (
-		<form action={addTodoAction} method="post">
-			<input name="name" />
+		<form action={addTodo} method="post">
+			<input name="title" />
 			<button>Add todo</button>
 		</form>
 	);
 }
 ```
 
-### Passing additional arguments
+### Prefilled arguments
 
 ```tsx
 import { action } from "@solidjs/router";
 
-const addTodoAction = action(async (userId: number, formData: FormData) => {
-	// ... Adds a new todo for a specific user.
+const addTodo = action(async (userId: string, data: URLSearchParams) => {
+	return {
+		userId,
+		title: data.get("title")?.toString(),
+	};
 }, "addTodo");
 
-function TodoForm() {
-	const userId = 1;
+function TodoForm(props: { userId: string }) {
 	return (
-		<form action={addTodoAction.with(userId)} method="post">
-			<input name="name" />
+		<form action={addTodo.with(props.userId)} method="post">
+			<input name="title" />
 			<button>Add todo</button>
 		</form>
 	);
 }
 ```
 
-### Triggering actions programmatically
+## Related
 
-```tsx
-import { action, useAction } from "@solidjs/router";
-
-const markDoneAction = action(async (id: string) => {
-	// ... Marks a todo as done on the server.
-});
-
-function NotificationItem(props: { id: string }) {
-	const markDone = useAction(markDoneAction);
-
-	return <button onClick={() => markDone(props.id)}>Mark as done</button>;
-}
-```
+- [`useAction`](/solid-router/reference/data-apis/use-action)
+- [`useSubmission`](/solid-router/reference/data-apis/use-submission)
+- [`useSubmissions`](/solid-router/reference/data-apis/use-submissions)

src/routes/solid-router/reference/data-apis/cache.mdx

@@ -2,136 +2,58 @@
 title: cache
 isDeprecated: true
 use_cases: >-
-  api calls, data fetching, deduplication, preloading routes, caching responses,
-  preventing waterfalls
+  deprecated query alias, cached functions, route data
 tags:
   - cache
   - deprecated
-  - data-fetching
-  - deduplication
-  - preload
+  - query
 version: "1.0"
 description: >-
-  Deprecated caching API for deduplicating requests and preloading data. Use
-  query instead for better performance and invalidation.
+  cache is a deprecated alias for query.
 ---
 
-:::caution[Deprecation Warning]
-This API is deprecated since `v0.15.0` of Solid Router. Use [query](/solid-router/reference/data-apis/query) instead. It will be removed in an upcoming release.
-:::
+`cache` is a deprecated alias for [`query`](/solid-router/reference/data-apis/query).
 
-`cache` is a [higher-order function](https://en.wikipedia.org/wiki/Higher-order_function) designed to create a new function with the same signature as the function passed to it.
-When this newly created function is called for the first time with a specific set of arguments, the original function is run, and its return value is stored in a cache and returned to the caller of the created function.
-The next time the created function is called with the same arguments (as long as the cache is still valid), it will return the cached value instead of re-executing the original function.
+## Import
 
-:::note
-`cache` can be defined anywhere and then used inside your components with [`createAsync`](/solid-router/reference/data-apis/create-async).
-
-However, using `cache` directly in [`createResource`](/reference/basic-reactivity/create-resource) will not work since the fetcher is not reactive and will not invalidate properly.
-
-:::
-
-## Usage
-
-```js
-const getUser = query(
-	(id, options = {}) =>
-		fetch(`/api/users/${id}?summary=${options.summary || false}`).then((r) =>
-			r.json()
-		),
-	"usersById"
-);
-
-getUser(123); // Causes a GET request to /api/users/123?summary=false
-getUser(123); // Does not cause a GET request
-getUser(123, { summary: true }); // Causes a GET request to /api/users/123?summary=true
-setTimeout(() => getUser(123, { summary: true }), 999000); // Eventually causes another GET request to /api/users/123?summary=true
+```tsx
+import { cache } from "@solidjs/router";
 ```
 
-### With preload functions
-
-Using it with a [preload function](/solid-router/reference/preload-functions/preload):
-
-```js
-import { lazy } from "solid-js";
-import { Route } from "@solidjs/router";
-import { getUser } from ... // the cache function
-
-const User = lazy(() => import("./pages/users/[id].js"));
-
-// preload function
-function preloadUser({params, location}) {
-  void getUser(params.id)
-}
+## Type
 
-// Pass it in the route definition
-<Route path="/users/:id" component={User} preload={preloadUser} />;
+```tsx
+const cache: typeof query;
 ```
 
-### Inside a route's component
-
-Using it inside a route's component:
-
-```jsx
-// pages/users/[id].js
-import { getUser } from ... // the cache function
-
-export default function User(props) {
-  const user = createAsync(() => getUser(props.params.id));
-  return <h1>{user().name}</h1>;
-}
-```
-
-## Cache function capabilities
-
-`cache` accomplishes the following:
-
-1. Deduping on the server for the lifetime of the request.
-2. Preloading the cache in the browser - this lasts 5 seconds.
-   When a route is preloaded on hover or when preload is called when entering a route it will make sure to dedupe calls.
-3. A reactive refetch mechanism based on key.
-   This prevents routes that are not new from retriggering on action revalidation.
-4. Serve as a back/forward cache for browser navigation for up to 5 minutes.
-   Any user based navigation or link click bypasses it.
-   Upon revalidation or new fetch the cache is updated.
-
-## Cache keys
+## Parameters
 
-To ensure that the cache keys are consistent and unique, arguments are deterministically serialized using JSON.stringify.
-Before serialization, key/value pairs in objects are sorted so that the order of properties does not affect the serialization.
-For instance, both `{ name: 'Ryan', awesome: true }` and `{ awesome: true, name: 'Ryan' }` will serialize to the same string so that they produce the same cache key.
+`cache` has the same parameters as [`query`](/solid-router/reference/data-apis/query).
 
 ## Return value
 
-The return value is a `CachedFunction`, a function that has the same signature as the function you passed to `cache`.
-This cached function stores the return value using the cache key.
-Under most circumstances, this temporarily prevents the passed function from running with the same arguments, even if the created function is called repeatedly.
+- **Type:** `CachedFunction<T>`
 
-## Arguments
+`cache` returns the same value as [`query`](/solid-router/reference/data-apis/query).
 
-| argument | type                    | description                                                               |
-| -------- | ----------------------- | ------------------------------------------------------------------------- |
-| `fn`     | `(...args: any) => any` | A function whose return value you'd like to be cached.                    |
-| `name`\* | string                  | Any arbitrary string that you'd like to use as the rest of the cache key. |
+## Behavior
 
-\*Since the internal cache is shared by all the functions using `cache`, the string should be unique for each function passed to `cache`.
-If the same key is used with multiple functions, one function might return the cached result of the other.
+- `cache` and `query` reference the same function.
+- Cache keys, reuse behavior, static methods, and revalidation behavior are the same as [`query`](/solid-router/reference/data-apis/query).
 
-## Methods
+## Examples
 
-### `.key` and `.keyFor`
+### Basic usage
 
-Cached functions provide `.key` and `.keyFor`, are useful when retrieving the keys used in cases involving invalidation:
+```tsx
+import { cache } from "@solidjs/router";
 
-```ts
-let id = 5;
-getUser.key; // returns "users"
-getUser.keyFor(id); // returns "users[5]"
+const getUser = cache(async (id: string) => {
+	const response = await fetch(`/api/users/${id}`);
+	return response.json();
+}, "user");
 ```
 
-### `revalidate`
+## Related
 
-The cache can be revalidated using the `revalidate` method or the `revalidate` keys that are set on the response from the actions.
-If the entire key is passed, it will invalidate all entries for the cache (ie. `users` in the example above).
-If only a single entry needs to be invalidated, `keyFor` is provided.
-To revalidate everything in the cache, pass `undefined` as the key.
+- [`query`](/solid-router/reference/data-apis/query)