@nkzw/fate 0.1.2 → 1.0.0-rc.0

package/docs/api/type-aliases/Mask.md

@@ -0,0 +1,15 @@
+# Type Alias: Mask\<T, S\>
+
+> **Mask**\<`T`, `S`\> = `WithNullish`\<`T`, `MaskNonNullish`\<`NonNullish`\<`T`\>, `S`\>\>
+
+Defined in: [packages/fate/src/types.ts:300](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L300)
+
+## Type Parameters
+
+### T
+
+`T`
+
+### S
+
+`S`

package/docs/api/type-aliases/MutationDefinition.md

@@ -0,0 +1,21 @@
+# Type Alias: MutationDefinition\<T, I, R\>
+
+> **MutationDefinition**\<`T`, `I`, `R`\> = `Readonly`\<\{ `__fate__mutation`: `true`; `entity`: `T`\[`"__typename"`\]; \}\> & `__MutationEntityAnchor`\<`T`\> & `__MutationInputAnchor`\<`I`\> & `__MutationResultAnchor`\<`R`\>
+
+Defined in: [packages/fate/src/types.ts:434](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L434)
+
+Metadata describing a mutation for a particular entity, input, and output.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`Entity`](Entity.md)
+
+### I
+
+`I`
+
+### R
+
+`R`

package/docs/api/type-aliases/MutationEntity.md

@@ -0,0 +1,13 @@
+# Type Alias: MutationEntity\<M\>
+
+> **MutationEntity**\<`M`\> = `M` *extends* `__MutationEntityAnchor`\<infer E\> ? `E` : `never`
+
+Defined in: [packages/fate/src/types.ts:452](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L452)
+
+Extracts the entity type from a mutation definition or identifier.
+
+## Type Parameters
+
+### M
+
+`M`

package/docs/api/type-aliases/MutationIdentifier.md

@@ -0,0 +1,19 @@
+# Type Alias: MutationIdentifier\<T, I, R\>
+
+> **MutationIdentifier**\<`T`, `I`, `R`\> = [`MutationDefinition`](MutationDefinition.md)\<`T`, `I`, `R`\> & `Readonly`\<\{ `key`: `string`; \}\>
+
+Defined in: [packages/fate/src/types.ts:442](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L442)
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`Entity`](Entity.md)
+
+### I
+
+`I`
+
+### R
+
+`R`

package/docs/api/type-aliases/MutationInput.md

@@ -0,0 +1,13 @@
+# Type Alias: MutationInput\<M\>
+
+> **MutationInput**\<`M`\> = `M` *extends* `__MutationInputAnchor`\<infer I\> ? `I` : `never`
+
+Defined in: [packages/fate/src/types.ts:446](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L446)
+
+Extracts the input type from a mutation definition or identifier.
+
+## Type Parameters
+
+### M
+
+`M`

package/docs/api/type-aliases/MutationResult.md

@@ -0,0 +1,13 @@
+# Type Alias: MutationResult\<M\>
+
+> **MutationResult**\<`M`\> = `M` *extends* `__MutationResultAnchor`\<infer R\> ? `R` : `never`
+
+Defined in: [packages/fate/src/types.ts:449](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L449)
+
+Extracts the result type from a mutation definition or identifier.
+
+## Type Parameters
+
+### M
+
+`M`

package/docs/api/type-aliases/NodesItem.md

@@ -0,0 +1,13 @@
+# Type Alias: NodesItem\<V\>
+
+> **NodesItem**\<`V`\> = `Readonly`\<\{ `ids`: `ReadonlyArray`\<`string` \| `number`\>; `view`: `V`; \}\>
+
+Defined in: [packages/fate/src/types.ts:334](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L334)
+
+Definition of a node request with explicit IDs for fetching data from the backend.
+
+## Type Parameters
+
+### V
+
+`V` *extends* [`View`](View.md)\<`any`, `any`\>

package/docs/api/type-aliases/Pagination.md

@@ -0,0 +1,39 @@
+# Type Alias: Pagination
+
+> **Pagination** = `object`
+
+Defined in: [packages/fate/src/types.ts:124](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L124)
+
+Pagination state returned alongside connection lists.
+
+## Properties
+
+### hasNext
+
+> **hasNext**: `boolean`
+
+Defined in: [packages/fate/src/types.ts:125](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L125)
+
+***
+
+### hasPrevious
+
+> **hasPrevious**: `boolean`
+
+Defined in: [packages/fate/src/types.ts:126](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L126)
+
+***
+
+### nextCursor?
+
+> `optional` **nextCursor?**: `string`
+
+Defined in: [packages/fate/src/types.ts:127](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L127)
+
+***
+
+### previousCursor?
+
+> `optional` **previousCursor?**: `string`
+
+Defined in: [packages/fate/src/types.ts:128](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L128)

package/docs/api/type-aliases/Request.md

@@ -0,0 +1,7 @@
+# Type Alias: Request
+
+> **Request** = `Record`\<`string`, `RequestItem`\>
+
+Defined in: [packages/fate/src/types.ts:346](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L346)
+
+Collection of node and list requests describing the data a screen needs.

package/docs/api/type-aliases/RequestMode.md

@@ -0,0 +1,7 @@
+# Type Alias: RequestMode
+
+> **RequestMode** = `"cache-first"` \| `"stale-while-revalidate"` \| `"network-only"`
+
+Defined in: [packages/fate/src/client.ts:73](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/client.ts#L73)
+
+Strategy used when resolving a request.

package/docs/api/type-aliases/RequestOptions.md

@@ -0,0 +1,7 @@
+# Type Alias: RequestOptions
+
+> **RequestOptions** = `Readonly`\<\{ `mode?`: [`RequestMode`](RequestMode.md); \}\>
+
+Defined in: [packages/fate/src/client.ts:84](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/client.ts#L84)
+
+Request options that affect how requests are fetched and retained.

package/docs/api/type-aliases/RequestResult.md

@@ -0,0 +1,18 @@
+# Type Alias: RequestResult\<R, Q\>
+
+> **RequestResult**\<`R`, `Q`\> = `{ [K in keyof Q]: K extends keyof R ? ListResult<Q[K], RootType<R[K]>, RootResult<R[K]>> : never }`
+
+Defined in: [packages/fate/src/types.ts:392](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L392)
+
+The result of a `FateClient.request` and `useRequest` call, mapping each
+request key to its corresponding result.
+
+## Type Parameters
+
+### R
+
+`R` *extends* [`FateRoots`](FateRoots.md)
+
+### Q
+
+`Q` *extends* `AnyRequest`

package/docs/api/type-aliases/Selection.md

@@ -0,0 +1,13 @@
+# Type Alias: Selection\<T\>
+
+> **Selection**\<`T`\> = `SelectionShape`\<`T`\> & `SelectionViewSpread`\<`T`\>
+
+Defined in: [packages/fate/src/types.ts:199](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L199)
+
+Declarative selection of the fields a view needs from an entity.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`Entity`](Entity.md)

package/docs/api/type-aliases/Snapshot.md

@@ -0,0 +1,7 @@
+# Type Alias: Snapshot
+
+> **Snapshot** = `Readonly`\<\{ `mask?`: `FieldMask`; `record?`: [`FateRecord`](FateRecord.md); \}\>
+
+Defined in: [packages/fate/src/types.ts:481](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L481)
+
+Snapshot captured before mutating the cache, used to roll back on errors.

package/docs/api/type-aliases/TypeConfig.md

@@ -0,0 +1,41 @@
+# Type Alias: TypeConfig
+
+> **TypeConfig** = `object`
+
+Defined in: [packages/fate/src/types.ts:117](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L117)
+
+Configuration for a server entity type used by the client cache.
+
+## Properties
+
+### fields?
+
+> `optional` **fields?**: `Record`\<`string`, `RelationDescriptor`\>
+
+Defined in: [packages/fate/src/types.ts:118](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L118)
+
+***
+
+### getId
+
+> **getId**: (`record`) => `string` \| `number`
+
+Defined in: [packages/fate/src/types.ts:119](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L119)
+
+#### Parameters
+
+##### record
+
+`unknown`
+
+#### Returns
+
+`string` \| `number`
+
+***
+
+### type
+
+> **type**: `string`
+
+Defined in: [packages/fate/src/types.ts:120](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L120)

package/docs/api/type-aliases/View.md

@@ -0,0 +1,17 @@
+# Type Alias: View\<T, S\>
+
+> **View**\<`T`, `S`\> = `Readonly`\<\{\[`viewTag`: `` `__fate-view__${string}` ``\]: `Readonly`\<\{ `[ViewKind]`: `true`; `select`: `S`; \}\>; \}\> & `__ViewEntityAnchor`\<`T`\> & `__ViewSelectionAnchor`\<`S`\>
+
+Defined in: [packages/fate/src/types.ts:215](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L215)
+
+Definition of a view over an entity type, including the selection of fields.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`Entity`](Entity.md)
+
+### S
+
+`S` *extends* [`Selection`](Selection.md)\<`T`\> = [`Selection`](Selection.md)\<`T`\>

package/docs/api/type-aliases/ViewData.md

@@ -0,0 +1,18 @@
+# Type Alias: ViewData\<T, S\>
+
+> **ViewData**\<`T`, `S`\> = `Readonly`\<`S` *extends* [`Selection`](Selection.md)\<`T`\> ? [`Mask`](Mask.md)\<`T`, `S`\> : `T` & `object`\>
+
+Defined in: [packages/fate/src/types.ts:231](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L231)
+
+Data returned from a resolved view with masking applied and view tags
+attached for downstream composition.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`Entity`](Entity.md)
+
+### S
+
+`S` *extends* [`Selection`](Selection.md)\<`T`\>

package/docs/api/type-aliases/ViewEntity.md

@@ -0,0 +1,13 @@
+# Type Alias: ViewEntity\<V\>
+
+> **ViewEntity**\<`V`\> = `V` *extends* [`View`](View.md)\<infer T, `any`\> ? `T` : `never`
+
+Defined in: [packages/fate/src/types.ts:303](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L303)
+
+Entity type captured from a view definition.
+
+## Type Parameters
+
+### V
+
+`V`

package/docs/api/type-aliases/ViewEntityName.md

@@ -0,0 +1,13 @@
+# Type Alias: ViewEntityName\<V\>
+
+> **ViewEntityName**\<`V`\> = [`ViewEntity`](ViewEntity.md)\<`V`\>\[`"__typename"`\] & `string`
+
+Defined in: [packages/fate/src/types.ts:306](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L306)
+
+Name of the entity type captured from a view definition.
+
+## Type Parameters
+
+### V
+
+`V`

package/docs/api/type-aliases/ViewRef.md

@@ -0,0 +1,13 @@
+# Type Alias: ViewRef\<TName\>
+
+> **ViewRef**\<`TName`\> = `Readonly`\<\{ `__typename`: `TName`; `[ViewsTag]`: `Set`\<`string`\>; `id`: `string` \| `number`; \}\>
+
+Defined in: [packages/fate/src/types.ts:101](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L101)
+
+Reference to a normalized entity instance that can be resolved against one or more view tags.
+
+## Type Parameters
+
+### TName
+
+`TName` *extends* `string`

package/docs/api/type-aliases/ViewSelection.md

@@ -0,0 +1,13 @@
+# Type Alias: ViewSelection\<V\>
+
+> **ViewSelection**\<`V`\> = `V` *extends* `object` ? `S` : `never`
+
+Defined in: [packages/fate/src/types.ts:309](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L309)
+
+Selection captured from a view definition.
+
+## Type Parameters
+
+### V
+
+`V`

package/docs/api/type-aliases/ViewSnapshot.md

@@ -0,0 +1,18 @@
+# Type Alias: ViewSnapshot\<T, S\>
+
+> **ViewSnapshot**\<`T`, `S`\> = `Readonly`\<\{ `coverage`: `ReadonlyArray`\<readonly \[[`EntityId`](EntityId.md), `ReadonlySet`\<`string`\>\]\>; `data`: [`ViewData`](ViewData.md)\<`T`, `S`\>; \}\>
+
+Defined in: [packages/fate/src/types.ts:241](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L241)
+
+Snapshot returned by the cache for a view, including the masked data and all
+referenced entity IDs.
+
+## Type Parameters
+
+### T
+
+`T` *extends* [`Entity`](Entity.md)
+
+### S
+
+`S` *extends* [`Selection`](Selection.md)\<`T`\>

package/docs/api/type-aliases/ViewTag.md

@@ -0,0 +1,7 @@
+# Type Alias: ViewTag
+
+> **ViewTag** = `` `__fate-view__${string}` ``
+
+Defined in: [packages/fate/src/types.ts:49](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L49)
+
+Unique key that identifies a view composition entry inside a selection or reference.

package/docs/api/variables/ConnectionTag.md

@@ -0,0 +1,7 @@
+# Variable: ConnectionTag
+
+> `const` **ConnectionTag**: *typeof* `ConnectionTag`
+
+Defined in: [packages/fate/src/types.ts:20](https://github.com/nkzw-tech/fate/blob/d972c17c02c8292194208ab53c91f9216703a5a7/packages/fate/src/types.ts#L20)
+
+Symbol attached to connection results so pagination helpers can find their metadata.

package/docs/guide/actions.md

@@ -0,0 +1,263 @@
+# Actions
+
+fate does not provide hooks for mutations like traditional data fetching libraries do. Instead, mutations are exposed in two ways:
+
+- `fate.actions` for use with [`useActionState`](https://react.dev/reference/react/useActionState) and React Actions.
+- `fate.mutations` for traditional imperative mutation calls.
+
+Mutations in your tRPC backend are made available as actions and mutations by fate's generated client.
+
+Let's assume that our `Post` entity has a tRPC mutation for liking a post called `post.like`. A `LikeButton` component using fate Actions and an async component library could then look like this:
+
+```tsx
+import { useActionState } from 'react';
+import { useFateClient } from 'react-fate';
+
+const LikeButton = ({ post }: { post: { id: string; likes: number } }) => {
+  const fate = useFateClient();
+  const [result, like] = useActionState(fate.actions.post.like, null);
+
+  return (
+    <Button action={() => like({ input: { id: post.id } })}>
+      {result?.error ? 'Oops!' : 'Like'}
+    </Button>
+  );
+};
+```
+
+If you are not using an async component library, you can use React's `useTransition` to start the action in a transition:
+
+```tsx
+const LikeButton = ({ post }: { post: { id: string; likes: number } }) => {
+  const fate = useFateClient();
+  const [, startTransition] = useTransition();
+  const [result, like, isPending] = useActionState(fate.actions.post.like, null);
+
+  return (
+    <button
+      disabled={isPending}
+      onClick={() => {
+        startTransition(() =>
+          like({
+            input: { id: post.id },
+          }),
+        );
+      }}
+    >
+      {result?.error ? 'Oops!' : 'Like'}
+    </button>
+  );
+};
+```
+
+By using `useActionState`, fate Actions integrate with Suspense and concurrent rendering.
+
+## Optimistic Updates
+
+fate Actions support optimistic updates out of the box. For example, to update the post's like count optimistically, you can pass an `optimistic` object to the action call. This will immediately update the cache with the new like count and re-render all views that select the `likes` field:
+
+```tsx
+like({
+  input: { id: post.id },
+  optimistic: { likes: post.likes + 1 },
+});
+```
+
+When data changes through optimistic updates or otherwise, fate only re-renders the views that select the changed fields. In the above example, only views that select the `likes` field will re-render. If a view only selects the `title` field, it won't re-render when the `likes` field changes.
+
+If a mutation fails, the cache will be rolled back to its previous state and any views depending on the mutated data will be updated.
+
+## Inserting New Objects
+
+When a mutation inserts a new object, you can provide an optimistic object with a temporary ID to represent the new object in the cache until the server responds with the actual ID. For example, to add a new comment to a post optimistically, you can do the following:
+
+```tsx
+const content = 'New Comment text';
+addComment({
+  input: { content, postId: post.id },
+  optimistic: {
+    author: { id: user.id, name: user.name },
+    content,
+    id: `optimistic:${Date.now().toString(36)}`,
+    post: { commentCount: post.commentCount + 1, id: post.id },
+  },
+});
+```
+
+By default, fate inserts new records after existing items in matching root lists and nested lists. For a newest-first list, pass `insert: 'before'` so optimistic records appear at the beginning:
+
+```tsx
+addComment({
+  input: { content, postId: post.id },
+  insert: 'before',
+  optimistic: {
+    content,
+    id: `optimistic:${Date.now().toString(36)}`,
+    post: { id: post.id },
+  },
+});
+```
+
+Insertion respects pagination boundaries. If you append to a list that still has a next page, fate keeps the new record attached to the unresolved trailing edge instead of mixing it into the loaded page. As you load more pages, the inserted record stays at the end until the server returns the canonical item or the list reaches the edge. The same behavior applies to prepends while `hasPrevious` is true.
+
+Multiple pending optimistic inserts keep their visible order. For example, two `insert: 'before'` calls on a newest-first feed show the second optimistic item before the first, matching what users expect from newly created content.
+
+## Selecting a View with Actions
+
+Mutations may change data that is not directly specified in the mutation result. For example, adding a comment increases the post's comment count. For such cases, you can provide a `view` to an action that specifies which fields to fetch as part of the mutation:
+
+```tsx
+addComment({
+  input: { content: 'New Comment text', postId: post.id },
+  view: view<Comment>()({
+    ...CommentView,
+    post: { commentCount: true },
+  }),
+});
+```
+
+The server will return the selected fields and fate updates the cache and re-renders all views that depend on the changed data. The action result contains the newly added comment with the selected fields:
+
+```tsx
+const [result, addComment] = useActionState(fate.actions.comment.add, null);
+
+const newComment = result?.result;
+if (newComment) {
+  // All the fields selected in the view are available on `newComment`:
+  console.log(newComment.post.commentCount);
+}
+```
+
+## Mutations
+
+fate Actions are the recommended way to execute server mutations in React components. However, there are cases where you might want to call mutations imperatively, outside of React components, or without waiting for previous actions to finish like `useActionState` does. For such cases, you can use `fate.mutations` to call mutations imperatively:
+
+```tsx
+const result = await fate.mutations.comment.add({
+  input: { content, postId: post.id },
+});
+```
+
+You can call mutations from anywhere, and without waiting for previous mutations to finish. The mutation API matches the API of fate Actions, including optimistic updates and view selection. With mutations, you'll need to handle loading states and errors manually, and the result is returned as a promise.
+
+## Mutation Server Implementation
+
+fate Actions & Mutations are backed by regular tRPC mutations on the server. Here is an example implementation of the `like` mutation in the `postRouter`.
+
+```tsx
+import { z } from 'zod';
+import { connectionArgs, createResolver } from '@nkzw/fate/server';
+import { procedure, router } from '../init.ts';
+import { postDataView, PostItem } from '../views.ts';
+
+export const postRouter = router({
+  like: procedure
+    .input(
+      z.object({
+        args: connectionArgs,
+        id: z.string().min(1, 'Post id is required.'),
+        select: z.array(z.string()),
+      }),
+    )
+    .mutation(async ({ ctx, input }) => {
+      const { resolve, select } = createResolver({
+        ...input,
+        ctx,
+        view: postDataView,
+      });
+
+      return resolve(
+        await ctx.prisma.post.update({
+          data: {
+            likes: {
+              increment: 1,
+            },
+          },
+          select,
+          where: { id: input.id },
+        } as PostUpdateArgs),
+      );
+    }),
+});
+```
+
+See the [Server Integration](#server-integration) section for more details on how to integrate tRPC routers with fate.
+
+## Action & Mutation Error Handling
+
+fate Actions & Mutations separate error handling into two scopes: "call site" and "boundary". Call site errors are expected to be handled at the location where the action or mutation is called. Boundary errors are unexpected errors that should be handled by a higher-level error boundary.
+
+If your server returns a `NOT_FOUND` error with code `404`, the result of an Action or Mutation will contain an error object that you can handle at the call site:
+
+```tsx
+const [result] = useActionState(fate.actions.post.delete, null);
+
+if (result?.error) {
+  if (result.error.code === 'NOT_FOUND') {
+    // Handle not found error at call site.
+  } else {
+    // Handle other *expected* errors.
+  }
+}
+```
+
+However, if an `INTERNAL_SERVER_ERROR` error with code `500` occurs, it will be thrown and can be caught by the nearest React error boundary:
+
+```tsx
+<ErrorBoundary FallbackComponent={ErrorComponent}>
+  <Suspense fallback={<div>Loading…</div>}>
+    <PostPage postId={postId} />
+  </Suspense>
+</ErrorBoundary>
+```
+
+You can find the error classification behavior in [`mutation.ts`](https://github.com/nkzw-tech/fate/blob/main/packages/fate/src/mutation.ts#L227-L254).
+
+## Deleting Records
+
+When you want to delete a record using fate Actions, you can pass a `delete: true` flag to the action call. This flag removes the object from the cache and re-renders all views that depend on the deleted data:
+
+```tsx
+const [result, deleteAction] = useActionState(fate.actions.post.delete, null);
+
+deleteAction({
+  input: { id: post.id },
+  delete: true,
+});
+```
+
+## Resetting Action State
+
+When using `useActionState`, the result of the action is cached until the component using the action is unmounted. When a mutation fails with an error, you might want to clear the error state without invoking the action again. fate Actions take a `'reset'` token to reset the action state:
+
+```tsx
+const [result, like] = useActionState(fate.actions.post.like, null);
+
+useEffect(() => {
+  if (result?.error) {
+    // Reset the action state after 3 seconds.
+    const timeout = setTimeout(() => startTransition(() => like('reset')), 3000);
+    return () => clearTimeout(timeout);
+  }
+}, [like, result]);
+```
+
+## Controlling List Insertion Behavior
+
+When inserting new objects into lists, the default behavior is to append the new object to the list. You can provide an `insert` option with `before`, `after` or `none` values to customize this behavior and specify where the new object should be inserted in the list:
+
+```tsx
+addComment({
+  input: { content: 'New Comment text', postId: post.id },
+  insert: 'before', // Insert the new comment at the beginning of the list.
+});
+```
+
+Or, use the `none` option if you want to ignore inserting the new object into any lists:
+
+```tsx
+addComment({
+  input: { content: 'New Comment text', postId: post.id },
+  insert: 'none', // Do not insert the new comment into any lists.
+});
+```