Skip to content

Commit f70a0d7

Browse files
TheEdoRanTheEdoRan
committedFeb 5, 2024
docs(website): reorganize documentation, add v7 sections
·
v8.0.0-beta.11v7.0.0-next.5
1 parent fd64e29 commit f70a0d7

21 files changed

+91
-28
lines changed
 

‎website/docs/contributing.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 9
2+
sidebar_position: 8
33
description: Learn how to contribute to next-safe-action via GitHub.
44
---
55

‎website/docs/examples/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 6
2+
sidebar_position: 5
33
---
44

55
# Examples

‎website/docs/getting-started.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -108,4 +108,4 @@ export default function Login() {
108108
}
109109
```
110110

111-
You also can execute Server Actions with hooks, which are a more powerful way to handle mutations. For more information about these, check out the [`useAction`](/docs/usage-from-client/hooks/useaction) and [`useOptimisticAction`](/docs/usage-from-client/hooks/useoptimisticaction) hooks sections.
111+
You also can execute Server Actions with hooks, which are a more powerful way to handle mutations. For more information about these, check out the [`useAction`](/docs/usage/client-components/hooks/useaction) and [`useOptimisticAction`](/docs/usage/client-components/hooks/useoptimisticaction) hooks sections.

‎website/docs/migration/index.md ‎website/docs/migrations/index.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
2-
sidebar_position: 8
2+
sidebar_position: 7
33
description: Learn how to migrate from a version to the next one.
4-
title: Migration
5-
---
4+
---
5+
6+
# Migrations

‎website/docs/migration/v3-to-v4.md ‎website/docs/migrations/v3-to-v4.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
sidebar_position: 1
33
description: Learn how to migrate from next-safe-action version 3 to version 4.
4-
title: v3 to v4
4+
sidebar_label: v3 to v4
55
---
66

77
# Migration from v3 to v4
@@ -28,7 +28,7 @@ You can continue to use version 3 of the library if you want to. There are no se
2828
- Reorganized callbacks arguments for `onSuccess` and `onError`:
2929
- from `onSuccess(data, reset, input)` to `onSuccess(data, input, reset)`
3030
- from `onError(error, reset, input)` to `onError(error, input, reset)`
31-
- `useOptimisticAction` just required a safe action and an initial optimistic state before. Now it requires a `reducer` function too, that determines the behavior of the optimistic state update when the `execute` function is called. Also, now only one input argument is required by `execute`, instead of two. The same input passed to the actual safe action is now passed to the `reducer` function too, as the second argument (`input`). More information about this hook can be found [here](/docs/usage-from-client/hooks/useoptimisticaction).
31+
- `useOptimisticAction` just required a safe action and an initial optimistic state before. Now it requires a `reducer` function too, that determines the behavior of the optimistic state update when the `execute` function is called. Also, now only one input argument is required by `execute`, instead of two. The same input passed to the actual safe action is now passed to the `reducer` function too, as the second argument (`input`). More information about this hook can be found [here](/docs/usage/client-components/hooks/useoptimisticaction).
3232

3333
### Types
3434

‎website/docs/migration/v4-to-v5.md ‎website/docs/migrations/v4-to-v5.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
sidebar_position: 2
33
description: Learn how to migrate from next-safe-action version 4 to version 5.
4-
title: v4 to v5
4+
sidebar_label: v4 to v5
55
---
66

77
# Migration from v4 to v5

‎website/docs/migration/v5-to-v6.md ‎website/docs/migrations/v5-to-v6.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
sidebar_position: 3
33
description: Learn how to migrate from next-safe-action version 5 to version 6.
4-
title: v5 to v6
4+
sidebar_label: v5 to v6
55
---
66

77
# Migration from v5 to v6

‎website/docs/migration/v6-to-v7.md ‎website/docs/migrations/v6-to-v7.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
---
22
sidebar_position: 4
33
description: Learn how to migrate from next-safe-action version 6 to version 7.
4-
title: v6 to v7
4+
sidebar_label: v6 to v7
55
---
66

77
# Migration from v6 to v7
88

99
## What's new?
1010

11-
WIP
11+
TODO: WIP
1212

1313
## BREAKING CHANGES
1414

15-
WIP
15+
TODO: WIP

‎website/docs/safe-action-client/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 4
33
description: Safe action client is the instance that you can use to create typesafe actions.
44
---
55

‎website/docs/types.md

+48-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 7
2+
sidebar_position: 6
33
description: List of exported types.
44
---
55

@@ -42,6 +42,14 @@ type ServerCodeFn<S extends Schema, Data, Context> = (
4242
) => Promise<Data>;
4343
```
4444

45+
### `ValidationErrors`
46+
47+
Type of the returned object when input validation fails.
48+
49+
```typescript
50+
export type ValidationErrors<S extends Schema> = Extend<ErrorList & SchemaErrors<Infer<S>>>;
51+
```
52+
4553
## /hooks
4654

4755
### `HookResult`
@@ -87,6 +95,44 @@ type HookActionStatus = "idle" | "executing" | "hasSucceeded" | "hasErrored";
8795

8896
---
8997

98+
## Utility types
99+
100+
### `MaybePromise`
101+
102+
Returns type or promise of type.
103+
104+
```typescript
105+
export type MaybePromise<T> = Promise<T> | T;
106+
```
107+
108+
### `Extend`
109+
110+
Extends an object without printing "&".
111+
112+
```typescript
113+
export type Extend<S> = S extends infer U ? { [K in keyof U]: U[K] } : never;
114+
```
115+
116+
### `ErrorList`
117+
118+
Object with an optional list of validation errors. Used in [`ValidationErrors`](#validationerrors) type.
119+
120+
```typescript
121+
export type ErrorList = { _errors?: string[] } & {};
122+
```
123+
124+
### `SchemaErrors`
125+
126+
Creates nested schema validation errors type using recursion. Used in [`ValidationErrors`](#validationerrors) type.
127+
128+
```typescript
129+
export type SchemaErrors<S> = {
130+
[K in keyof S]?: S[K] extends object ? Extend<ErrorList & SchemaErrors<S[K]>> : ErrorList;
131+
} & {};
132+
```
133+
134+
---
135+
90136
## TypeSchema library
91137

92-
`Infer`, `InferIn`, `Schema` types come from [TypeSchema](https://typeschema.com/#types) library.
138+
`Infer`, `InferIn`, `Schema` types come from [TypeSchema](https://typeschema.com/#types) library.

‎website/docs/usage-from-client/action-result-object.md ‎website/docs/usage/action-result-object.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
sidebar_position: 4
3-
description: Action result object is the result of an action execution, returned by hooks.
2+
sidebar_position: 3
3+
description: Action result object is the result of an action execution.
44
---
55

66
# Action result object
@@ -11,5 +11,5 @@ Here's how action result object is structured (all keys are optional):
1111
| Name | When | Value |
1212
|--------------------|--------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
1313
| `data?` | Execution is successful. | What you returned in action's server code. |
14-
| `validationErrors?` | Input data doesn't pass schema validation. | A partial `Record` of input schema keys as key or `_root`, and `string[]` as value. `_root` is a reserved key, used for global validation issues. Example: `{ _root: ["A global error"], email: ["Email is required."] }`. |
14+
| `validationErrors?` | Input data doesn't pass validation. | An object whose keys are the names of the fields that failed validation. Each key's value is either an `ErrorList` or a nested key with an `ErrorList` inside.<br />`ErrorList` is defined as: `{ errors?: string[] }`.
1515
| `serverError?` | An error occurs during action's server code execution. | A `string` that by default is "Something went wrong while executing the operation" for every server error that occurs, but this is [configurable](/docs/safe-action-client/custom-server-error-handling#handlereturnedservererror) when instantiating a new client. |

‎website/docs/usage-from-client/direct-execution.md ‎website/docs/usage/client-components/direct-execution.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,6 @@ export default function Login({ loginUser }: Props) {
2525

2626
### Action result object
2727

28-
Every action you execute returns an object with the same structure. This is described in the [action result object](/docs/usage-from-client/action-result-object) section.
28+
Every action you execute returns an object with the same structure. This is described in the [action result object](/docs/usage/action-result-object) section.
2929

3030
Explore a working example [here](https://github.com/TheEdoRan/next-safe-action/tree/main/packages/example-app/src/app).

‎website/docs/usage-from-client/hooks/useaction.md ‎website/docs/usage/client-components/hooks/useaction.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: Learn how to use the `useAction` hook.
66
# `useAction`
77

88
:::info
9-
`useAction` **waits** for the action to finish execution before returning the result. If you need to perform optimistic updates, use [`useOptimisticAction`](/docs/usage-from-client/hooks/useoptimisticaction) instead.
9+
`useAction` **waits** for the action to finish execution before returning the result. If you need to perform optimistic updates, use [`useOptimisticAction`](/docs/usage/client-components/hooks/useoptimisticaction) instead.
1010
:::
1111

1212
With this hook, you get full control of the action execution flow.
@@ -60,7 +60,7 @@ As you can see, here we display a greet message after the action is performed, i
6060
| Name | Type | Purpose |
6161
|--------------|--------------------------------------------|--------------------------------------------------------------------------------------------------|
6262
| `safeAction` | [SafeAction](/docs/types#safeaction) | This is the action that will be called when you use `execute` from hook's return object. |
63-
| `callbacks?` | [HookCallbacks](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/usage-from-client/hooks/callbacks). |
63+
| `callbacks?` | [HookCallbacks](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/usage/client-components/hooks/callbacks). |
6464

6565
### `useAction` return object
6666

‎website/docs/usage-from-client/hooks/useoptimisticaction.md ‎website/docs/usage/client-components/hooks/useoptimisticaction.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ description: Learn how to use the `useOptimisticAction` hook.
66
# `useOptimisticAction`
77

88
:::info
9-
`useOptimisticAction` **does not wait** for the action to finish execution before returning the optimistic data. It is then synced with the real result from server when the action has finished its execution. If you need to perform normal mutations, use [`useAction`](/docs/usage-from-client/hooks/useaction) instead.
9+
`useOptimisticAction` **does not wait** for the action to finish execution before returning the optimistic data. It is then synced with the real result from server when the action has finished its execution. If you need to perform normal mutations, use [`useAction`](/docs/usage/client-components/hooks/useaction) instead.
1010
:::
1111

1212
:::caution warning
@@ -105,7 +105,7 @@ export default function AddLikes({ numOfLikes }: Props) {
105105
| `safeAction` | [`SafeAction`](/docs/types#safeaction) | This is the action that will be called when you use `execute` from hook's return object. |
106106
| `initialOptimisticData` | `Data` (return type of the `safeAction` you passed as first argument) | An initializer for the optimistic state. Usually this value comes from the parent Server Component. |
107107
| `reducer` | `(state: Data, input: InferIn<S>) => Data` | When you call the action via `execute`, this function determines how the optimistic update is performed. Basically, here you define what happens **immediately** after `execute` is called, and before the actual result comes back from the server. |
108-
| `callbacks?` | [`HookCallbacks`](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/usage-from-client/hooks/callbacks). |
108+
| `callbacks?` | [`HookCallbacks`](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/usage/client-components/hooks/callbacks). |
109109

110110

111111
### `useOptimisticAction` return object

‎website/docs/usage-from-client/index.md ‎website/docs/usage/client-components/index.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 1
33
description: Learn how to execute safe actions inside Client Components.
4+
sidebar_label: Client Components
45
---
56

6-
# Usage from client
7+
# Usage with Client Components
78

89
There are three different ways to execute Server Actions from Client Components. First one is the "direct way", the most simple one, but the least powerful too. The other two are by using `useAction` and `useOptimisticAction` hooks, which we will cover in the next sections.

‎website/docs/usage/custom-validation-errors.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
sidebar_position: 4
3+
description: Set custom validation errors in schema or in action's server code function.
4+
---
5+
6+
# Custom validation errors
7+
8+
TODO: WIP

‎website/docs/usage-with-forms.md ‎website/docs/usage/forms.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 2
33
description: Learn how to execute safe actions as form actions.
4+
sidebar_label: Forms
45
---
56

67
# Usage with forms

‎website/docs/usage/index.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
---
2+
sidebar_position: 3
3+
description: Learn how to migrate from a version to the next one.
4+
---
5+
6+
# Usage

‎website/docusaurus.config.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ export default {
8282
},
8383
footer: {
8484
style: "light",
85-
copyright: `Copyleft <span class="copyleft">&copy;</span> ${new Date().getFullYear()} Edoardo Ranghieri`,
85+
copyright: `Copyleft <span class="copyleft">&copy;</span> 2023 Edoardo Ranghieri`,
8686
},
8787
prism: {
8888
additionalLanguages: ["typescript"],

0 commit comments

Comments
 (0)
Please sign in to comment.