From f70a0d71dc2d9ae56d7198b117b376428913a587 Mon Sep 17 00:00:00 2001 From: Edoardo Ranghieri Date: Mon, 5 Feb 2024 01:14:24 +0100 Subject: [PATCH] docs(website): reorganize documentation, add v7 sections --- website/docs/contributing.md | 2 +- website/docs/examples/index.md | 2 +- website/docs/getting-started.md | 2 +- .../docs/{migration => migrations}/index.md | 7 +-- .../{migration => migrations}/v3-to-v4.md | 4 +- .../{migration => migrations}/v4-to-v5.md | 2 +- .../{migration => migrations}/v5-to-v6.md | 2 +- .../{migration => migrations}/v6-to-v7.md | 6 +-- website/docs/safe-action-client/index.md | 2 +- website/docs/types.md | 50 ++++++++++++++++++- .../action-result-object.md | 6 +-- .../client-components}/direct-execution.md | 2 +- .../client-components}/hooks/callbacks.md | 0 .../client-components}/hooks/index.md | 0 .../client-components}/hooks/useaction.md | 4 +- .../hooks/useoptimisticaction.md | 4 +- .../client-components}/index.md | 5 +- .../docs/usage/custom-validation-errors.md | 8 +++ .../{usage-with-forms.md => usage/forms.md} | 3 +- website/docs/usage/index.md | 6 +++ website/docusaurus.config.js | 2 +- 21 files changed, 91 insertions(+), 28 deletions(-) rename website/docs/{migration => migrations}/index.md (63%) rename website/docs/{migration => migrations}/v3-to-v4.md (96%) rename website/docs/{migration => migrations}/v4-to-v5.md (97%) rename website/docs/{migration => migrations}/v5-to-v6.md (98%) rename website/docs/{migration => migrations}/v6-to-v7.md (80%) rename website/docs/{usage-from-client => usage}/action-result-object.md (77%) rename website/docs/{usage-from-client => usage/client-components}/direct-execution.md (90%) rename website/docs/{usage-from-client => usage/client-components}/hooks/callbacks.md (100%) rename website/docs/{usage-from-client => usage/client-components}/hooks/index.md (100%) rename website/docs/{usage-from-client => usage/client-components}/hooks/useaction.md (96%) rename website/docs/{usage-from-client => usage/client-components}/hooks/useoptimisticaction.md (97%) rename website/docs/{usage-from-client => usage/client-components}/index.md (80%) create mode 100644 website/docs/usage/custom-validation-errors.md rename website/docs/{usage-with-forms.md => usage/forms.md} (97%) create mode 100644 website/docs/usage/index.md diff --git a/website/docs/contributing.md b/website/docs/contributing.md index 01f1d82a..0d630774 100644 --- a/website/docs/contributing.md +++ b/website/docs/contributing.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 8 description: Learn how to contribute to next-safe-action via GitHub. --- diff --git a/website/docs/examples/index.md b/website/docs/examples/index.md index 5fc99409..1b437e91 100644 --- a/website/docs/examples/index.md +++ b/website/docs/examples/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 5 --- # Examples \ No newline at end of file diff --git a/website/docs/getting-started.md b/website/docs/getting-started.md index 29c2b564..1c1dcd72 100644 --- a/website/docs/getting-started.md +++ b/website/docs/getting-started.md @@ -108,4 +108,4 @@ export default function Login() { } ``` -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/website/docs/migration/index.md b/website/docs/migrations/index.md similarity index 63% rename from website/docs/migration/index.md rename to website/docs/migrations/index.md index 3932dfc3..9862508c 100644 --- a/website/docs/migration/index.md +++ b/website/docs/migrations/index.md @@ -1,5 +1,6 @@ --- -sidebar_position: 8 +sidebar_position: 7 description: Learn how to migrate from a version to the next one. -title: Migration ---- \ No newline at end of file +--- + +# Migrations \ No newline at end of file diff --git a/website/docs/migration/v3-to-v4.md b/website/docs/migrations/v3-to-v4.md similarity index 96% rename from website/docs/migration/v3-to-v4.md rename to website/docs/migrations/v3-to-v4.md index a4de864a..dcf57b7d 100644 --- a/website/docs/migration/v3-to-v4.md +++ b/website/docs/migrations/v3-to-v4.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 description: Learn how to migrate from next-safe-action version 3 to version 4. -title: v3 to v4 +sidebar_label: v3 to v4 --- # 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 - Reorganized callbacks arguments for `onSuccess` and `onError`: - from `onSuccess(data, reset, input)` to `onSuccess(data, input, reset)` - from `onError(error, reset, input)` to `onError(error, input, reset)` -- `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). +- `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). ### Types diff --git a/website/docs/migration/v4-to-v5.md b/website/docs/migrations/v4-to-v5.md similarity index 97% rename from website/docs/migration/v4-to-v5.md rename to website/docs/migrations/v4-to-v5.md index 778e7f11..900dee21 100644 --- a/website/docs/migration/v4-to-v5.md +++ b/website/docs/migrations/v4-to-v5.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 description: Learn how to migrate from next-safe-action version 4 to version 5. -title: v4 to v5 +sidebar_label: v4 to v5 --- # Migration from v4 to v5 diff --git a/website/docs/migration/v5-to-v6.md b/website/docs/migrations/v5-to-v6.md similarity index 98% rename from website/docs/migration/v5-to-v6.md rename to website/docs/migrations/v5-to-v6.md index b1d82b56..56b23610 100644 --- a/website/docs/migration/v5-to-v6.md +++ b/website/docs/migrations/v5-to-v6.md @@ -1,7 +1,7 @@ --- sidebar_position: 3 description: Learn how to migrate from next-safe-action version 5 to version 6. -title: v5 to v6 +sidebar_label: v5 to v6 --- # Migration from v5 to v6 diff --git a/website/docs/migration/v6-to-v7.md b/website/docs/migrations/v6-to-v7.md similarity index 80% rename from website/docs/migration/v6-to-v7.md rename to website/docs/migrations/v6-to-v7.md index e633b617..53c7b194 100644 --- a/website/docs/migration/v6-to-v7.md +++ b/website/docs/migrations/v6-to-v7.md @@ -1,15 +1,15 @@ --- sidebar_position: 4 description: Learn how to migrate from next-safe-action version 6 to version 7. -title: v6 to v7 +sidebar_label: v6 to v7 --- # Migration from v6 to v7 ## What's new? -WIP +TODO: WIP ## BREAKING CHANGES -WIP \ No newline at end of file +TODO: WIP \ No newline at end of file diff --git a/website/docs/safe-action-client/index.md b/website/docs/safe-action-client/index.md index 8f3bf696..228380fe 100644 --- a/website/docs/safe-action-client/index.md +++ b/website/docs/safe-action-client/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 4 description: Safe action client is the instance that you can use to create typesafe actions. --- diff --git a/website/docs/types.md b/website/docs/types.md index 8cd3d5e1..3fad6413 100644 --- a/website/docs/types.md +++ b/website/docs/types.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 6 description: List of exported types. --- @@ -42,6 +42,14 @@ type ServerCodeFn = ( ) => Promise; ``` +### `ValidationErrors` + +Type of the returned object when input validation fails. + +```typescript +export type ValidationErrors = Extend>>; +``` + ## /hooks ### `HookResult` @@ -87,6 +95,44 @@ type HookActionStatus = "idle" | "executing" | "hasSucceeded" | "hasErrored"; --- +## Utility types + +### `MaybePromise` + +Returns type or promise of type. + +```typescript +export type MaybePromise = Promise | T; +``` + +### `Extend` + +Extends an object without printing "&". + +```typescript +export type Extend = S extends infer U ? { [K in keyof U]: U[K] } : never; +``` + +### `ErrorList` + +Object with an optional list of validation errors. Used in [`ValidationErrors`](#validationerrors) type. + +```typescript +export type ErrorList = { _errors?: string[] } & {}; +``` + +### `SchemaErrors` + +Creates nested schema validation errors type using recursion. Used in [`ValidationErrors`](#validationerrors) type. + +```typescript +export type SchemaErrors = { + [K in keyof S]?: S[K] extends object ? Extend> : ErrorList; +} & {}; +``` + +--- + ## TypeSchema library -`Infer`, `InferIn`, `Schema` types come from [TypeSchema](https://typeschema.com/#types) library. \ No newline at end of file +`Infer`, `InferIn`, `Schema` types come from [TypeSchema](https://typeschema.com/#types) library. diff --git a/website/docs/usage-from-client/action-result-object.md b/website/docs/usage/action-result-object.md similarity index 77% rename from website/docs/usage-from-client/action-result-object.md rename to website/docs/usage/action-result-object.md index 0b53c466..8e663757 100644 --- a/website/docs/usage-from-client/action-result-object.md +++ b/website/docs/usage/action-result-object.md @@ -1,6 +1,6 @@ --- -sidebar_position: 4 -description: Action result object is the result of an action execution, returned by hooks. +sidebar_position: 3 +description: Action result object is the result of an action execution. --- # Action result object @@ -11,5 +11,5 @@ Here's how action result object is structured (all keys are optional): | Name | When | Value | |--------------------|--------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `data?` | Execution is successful. | What you returned in action's server code. | -| `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."] }`. | +| `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.
`ErrorList` is defined as: `{ errors?: string[] }`. | `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. | \ No newline at end of file diff --git a/website/docs/usage-from-client/direct-execution.md b/website/docs/usage/client-components/direct-execution.md similarity index 90% rename from website/docs/usage-from-client/direct-execution.md rename to website/docs/usage/client-components/direct-execution.md index 0b0bbf13..3562e01f 100644 --- a/website/docs/usage-from-client/direct-execution.md +++ b/website/docs/usage/client-components/direct-execution.md @@ -25,6 +25,6 @@ export default function Login({ loginUser }: Props) { ### Action result object -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. +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. Explore a working example [here](https://github.com/TheEdoRan/next-safe-action/tree/main/packages/example-app/src/app). \ No newline at end of file diff --git a/website/docs/usage-from-client/hooks/callbacks.md b/website/docs/usage/client-components/hooks/callbacks.md similarity index 100% rename from website/docs/usage-from-client/hooks/callbacks.md rename to website/docs/usage/client-components/hooks/callbacks.md diff --git a/website/docs/usage-from-client/hooks/index.md b/website/docs/usage/client-components/hooks/index.md similarity index 100% rename from website/docs/usage-from-client/hooks/index.md rename to website/docs/usage/client-components/hooks/index.md diff --git a/website/docs/usage-from-client/hooks/useaction.md b/website/docs/usage/client-components/hooks/useaction.md similarity index 96% rename from website/docs/usage-from-client/hooks/useaction.md rename to website/docs/usage/client-components/hooks/useaction.md index 2bd1da0e..35821418 100644 --- a/website/docs/usage-from-client/hooks/useaction.md +++ b/website/docs/usage/client-components/hooks/useaction.md @@ -6,7 +6,7 @@ description: Learn how to use the `useAction` hook. # `useAction` :::info -`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. +`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. ::: 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 | Name | Type | Purpose | |--------------|--------------------------------------------|--------------------------------------------------------------------------------------------------| | `safeAction` | [SafeAction](/docs/types#safeaction) | This is the action that will be called when you use `execute` from hook's return object. | -| `callbacks?` | [HookCallbacks](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/usage-from-client/hooks/callbacks). | +| `callbacks?` | [HookCallbacks](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/usage/client-components/hooks/callbacks). | ### `useAction` return object diff --git a/website/docs/usage-from-client/hooks/useoptimisticaction.md b/website/docs/usage/client-components/hooks/useoptimisticaction.md similarity index 97% rename from website/docs/usage-from-client/hooks/useoptimisticaction.md rename to website/docs/usage/client-components/hooks/useoptimisticaction.md index 4ae6b748..9e160adc 100644 --- a/website/docs/usage-from-client/hooks/useoptimisticaction.md +++ b/website/docs/usage/client-components/hooks/useoptimisticaction.md @@ -6,7 +6,7 @@ description: Learn how to use the `useOptimisticAction` hook. # `useOptimisticAction` :::info -`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. +`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. ::: :::caution warning @@ -105,7 +105,7 @@ export default function AddLikes({ numOfLikes }: Props) { | `safeAction` | [`SafeAction`](/docs/types#safeaction) | This is the action that will be called when you use `execute` from hook's return object. | | `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. | | `reducer` | `(state: Data, input: InferIn) => 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. | -| `callbacks?` | [`HookCallbacks`](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/usage-from-client/hooks/callbacks). | +| `callbacks?` | [`HookCallbacks`](/docs/types#hookcallbacks) | Optional callbacks. More information about them [here](/docs/usage/client-components/hooks/callbacks). | ### `useOptimisticAction` return object diff --git a/website/docs/usage-from-client/index.md b/website/docs/usage/client-components/index.md similarity index 80% rename from website/docs/usage-from-client/index.md rename to website/docs/usage/client-components/index.md index 6758ebaf..68b6a62c 100644 --- a/website/docs/usage-from-client/index.md +++ b/website/docs/usage/client-components/index.md @@ -1,8 +1,9 @@ --- -sidebar_position: 3 +sidebar_position: 1 description: Learn how to execute safe actions inside Client Components. +sidebar_label: Client Components --- -# Usage from client +# Usage with Client Components 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. \ No newline at end of file diff --git a/website/docs/usage/custom-validation-errors.md b/website/docs/usage/custom-validation-errors.md new file mode 100644 index 00000000..cad944a7 --- /dev/null +++ b/website/docs/usage/custom-validation-errors.md @@ -0,0 +1,8 @@ +--- +sidebar_position: 4 +description: Set custom validation errors in schema or in action's server code function. +--- + +# Custom validation errors + +TODO: WIP \ No newline at end of file diff --git a/website/docs/usage-with-forms.md b/website/docs/usage/forms.md similarity index 97% rename from website/docs/usage-with-forms.md rename to website/docs/usage/forms.md index 0d401307..e11a093c 100644 --- a/website/docs/usage-with-forms.md +++ b/website/docs/usage/forms.md @@ -1,6 +1,7 @@ --- -sidebar_position: 4 +sidebar_position: 2 description: Learn how to execute safe actions as form actions. +sidebar_label: Forms --- # Usage with forms diff --git a/website/docs/usage/index.md b/website/docs/usage/index.md new file mode 100644 index 00000000..2eb59558 --- /dev/null +++ b/website/docs/usage/index.md @@ -0,0 +1,6 @@ +--- +sidebar_position: 3 +description: Learn how to migrate from a version to the next one. +--- + +# Usage \ No newline at end of file diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index a45ae072..e242000a 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -82,7 +82,7 @@ export default { }, footer: { style: "light", - copyright: `Copyleft © ${new Date().getFullYear()} Edoardo Ranghieri`, + copyright: `Copyleft © 2023 Edoardo Ranghieri`, }, prism: { additionalLanguages: ["typescript"],