From a44744ec74f6cd90b95ca2667dc03fbaac64d9cf Mon Sep 17 00:00:00 2001 From: Igor Kamyshev Date: Tue, 25 Jul 2023 14:49:11 +0700 Subject: [PATCH 1/4] WIP --- apps/website/docs/.vitepress/config.js | 36 ++++++++++++++----- apps/website/docs/tutorial/index.md | 2 ++ .../docs/tutorial/migrate/effector/addons.md | 0 .../tutorial/migrate/effector/contracts.md | 0 .../docs/tutorial/migrate/effector/index.md | 15 ++++++++ .../migrate/effector/specific_factories.md | 0 .../tutorial/migrate/effector/trigger_api.md | 0 .../docs/tutorial/migrate/effector/wrap.md | 0 8 files changed, 44 insertions(+), 9 deletions(-) create mode 100644 apps/website/docs/tutorial/migrate/effector/addons.md create mode 100644 apps/website/docs/tutorial/migrate/effector/contracts.md create mode 100644 apps/website/docs/tutorial/migrate/effector/index.md create mode 100644 apps/website/docs/tutorial/migrate/effector/specific_factories.md create mode 100644 apps/website/docs/tutorial/migrate/effector/trigger_api.md create mode 100644 apps/website/docs/tutorial/migrate/effector/wrap.md diff --git a/apps/website/docs/.vitepress/config.js b/apps/website/docs/.vitepress/config.js index b78f58ae8..5d3be63dc 100644 --- a/apps/website/docs/.vitepress/config.js +++ b/apps/website/docs/.vitepress/config.js @@ -74,7 +74,7 @@ export default withMermaid( '/tutorial': [ { text: 'Thorough Tutorial', - collapsed: false, + collapsed: true, items: [ { text: 'Get started', link: '/tutorial/' }, { text: 'Installation', link: '/tutorial/install' }, @@ -135,21 +135,39 @@ export default withMermaid( ], }, { - text: 'Solid', + text: 'With UI-libs', collapsed: true, items: [ - { text: 'Get started', link: '/tutorial/solid/' }, - { text: 'Suspense', link: '/tutorial/solid/suspense' }, - { text: 'SSR and Testing', link: '/tutorial/solid/scope' }, + { + text: 'Solid', + collapsed: true, + items: [ + { text: 'Get started', link: '/tutorial/solid/' }, + { text: 'Suspense', link: '/tutorial/solid/suspense' }, + { text: 'SSR and Testing', link: '/tutorial/solid/scope' }, + ], + }, + { + text: 'React', + collapsed: true, + items: [ + { text: 'Get started', link: '/tutorial/react/' }, + { text: 'Suspense', link: '/tutorial/react/suspense' }, + { text: 'SSR and Testing', link: '/tutorial/react/scope' }, + ], + }, ], }, { - text: 'React', + text: 'Migration', collapsed: true, items: [ - { text: 'Get started', link: '/tutorial/react/' }, - { text: 'Suspense', link: '/tutorial/react/suspense' }, - { text: 'SSR and Testing', link: '/tutorial/react/scope' }, + { + text: 'from Effects', + items: [ + { text: 'Get started', link: '/tutorial/migrate/effector/' }, + ], + }, ], }, ], diff --git a/apps/website/docs/tutorial/index.md b/apps/website/docs/tutorial/index.md index 998dd32d7..93c36f23b 100644 --- a/apps/website/docs/tutorial/index.md +++ b/apps/website/docs/tutorial/index.md @@ -92,5 +92,7 @@ Pretty cool, right? We love it, and we hope you will too. Read on to learn more - Learn Farfetched at your own pace with our amazingly [Thorough Tutorial](/tutorial/install) - Read framework-specific recommendations for [Solid](/tutorial/solid/) and [React](/tutorial/react/) +- Learn about step-by-step adoption of Farfetched for existing applications which uses different tools for data fetching: + - [Effector's _Effects_](/tutorial/migrate/effector/) - See the whole picture in [API reference](/api/) - Check out Farfetched's [roadmap](/roadmap) to stay in the same wavelength with us diff --git a/apps/website/docs/tutorial/migrate/effector/addons.md b/apps/website/docs/tutorial/migrate/effector/addons.md new file mode 100644 index 000000000..e69de29bb diff --git a/apps/website/docs/tutorial/migrate/effector/contracts.md b/apps/website/docs/tutorial/migrate/effector/contracts.md new file mode 100644 index 000000000..e69de29bb diff --git a/apps/website/docs/tutorial/migrate/effector/index.md b/apps/website/docs/tutorial/migrate/effector/index.md new file mode 100644 index 000000000..212804626 --- /dev/null +++ b/apps/website/docs/tutorial/migrate/effector/index.md @@ -0,0 +1,15 @@ +# Continues adoption + +This tutorial describes how to add Farfetched to an existing application uses _Effects_ for data fetching step by step without rewriting big parts of the codebase. + +::: tip +This tutorial is not a replacement for the [Thorough Tutorial](/tutorial/install) which is a better starting point for learning Farfetched. Furthermore, it is assumed that you have read [Thorough Tutorial](/tutorial/install) and know the basics of Farfetched. +::: + +Farfetched is built with continues adoption in mind, so there are straightforward steps to add it to an existing application and embrace its benefits: + +1. Wrap existing data fetching _Effects_ to _Queries_ and _Mutations_ +2. Replace existing add-ons with Farfetched operators like `retry`, `cache` or `connectQuery` +3. Add strict _Contracts_ to server responses +4. Migrate to specific factories like `createJsonQuery` and `createJsonMutation` +5. Apply declarative approach with Trigger API and `keepFresh` operator diff --git a/apps/website/docs/tutorial/migrate/effector/specific_factories.md b/apps/website/docs/tutorial/migrate/effector/specific_factories.md new file mode 100644 index 000000000..e69de29bb diff --git a/apps/website/docs/tutorial/migrate/effector/trigger_api.md b/apps/website/docs/tutorial/migrate/effector/trigger_api.md new file mode 100644 index 000000000..e69de29bb diff --git a/apps/website/docs/tutorial/migrate/effector/wrap.md b/apps/website/docs/tutorial/migrate/effector/wrap.md new file mode 100644 index 000000000..e69de29bb From 2c943d25983032d54ff7df2fa6327f798d55551b Mon Sep 17 00:00:00 2001 From: Igor Kamyshev Date: Tue, 25 Jul 2023 18:10:50 +0700 Subject: [PATCH 2/4] Setup navigation for tutorial --- apps/website/docs/.vitepress/config.js | 27 ++++++++++++++++++- .../docs/tutorial/migrate/effector/index.md | 15 ++++++----- .../docs/tutorial/migrate/effector/next.md | 0 3 files changed, 34 insertions(+), 8 deletions(-) create mode 100644 apps/website/docs/tutorial/migrate/effector/next.md diff --git a/apps/website/docs/.vitepress/config.js b/apps/website/docs/.vitepress/config.js index 5d3be63dc..e32d4209c 100644 --- a/apps/website/docs/.vitepress/config.js +++ b/apps/website/docs/.vitepress/config.js @@ -164,8 +164,33 @@ export default withMermaid( items: [ { text: 'from Effects', + link: '/tutorial/migrate/effector/', + collapsed: true, items: [ - { text: 'Get started', link: '/tutorial/migrate/effector/' }, + { + text: '1. Wrap existing Effects', + link: '/tutorial/migrate/effector/wrap', + }, + { + text: '2. Use add-ons', + link: '/tutorial/migrate/effector/addons', + }, + { + text: '3. Add Contracts', + link: '/tutorial/migrate/effector/contracts', + }, + { + text: '4. Use specific factories', + link: '/tutorial/migrate/effector/specific_factories', + }, + { + text: '5. Apply declarative approach', + link: '/tutorial/migrate/effector/trigger_api', + }, + { + text: '6. Next steps', + link: '/tutorial/migrate/effector/next', + }, ], }, ], diff --git a/apps/website/docs/tutorial/migrate/effector/index.md b/apps/website/docs/tutorial/migrate/effector/index.md index 212804626..9e0de264f 100644 --- a/apps/website/docs/tutorial/migrate/effector/index.md +++ b/apps/website/docs/tutorial/migrate/effector/index.md @@ -1,6 +1,6 @@ -# Continues adoption +# Migration to Farfetched from plain _Effects_ -This tutorial describes how to add Farfetched to an existing application uses _Effects_ for data fetching step by step without rewriting big parts of the codebase. +This tutorial describes how to add Farfetched to an existing application uses [_Effects_](https://effector.dev/docs/api/effector/effect) for data fetching step by step without rewriting big parts of the codebase. ::: tip This tutorial is not a replacement for the [Thorough Tutorial](/tutorial/install) which is a better starting point for learning Farfetched. Furthermore, it is assumed that you have read [Thorough Tutorial](/tutorial/install) and know the basics of Farfetched. @@ -8,8 +8,9 @@ This tutorial is not a replacement for the [Thorough Tutorial](/tutorial/install Farfetched is built with continues adoption in mind, so there are straightforward steps to add it to an existing application and embrace its benefits: -1. Wrap existing data fetching _Effects_ to _Queries_ and _Mutations_ -2. Replace existing add-ons with Farfetched operators like `retry`, `cache` or `connectQuery` -3. Add strict _Contracts_ to server responses -4. Migrate to specific factories like `createJsonQuery` and `createJsonMutation` -5. Apply declarative approach with Trigger API and `keepFresh` operator +1. [Wrap existing data fetching _Effects_](/tutorial/migrate/effector/wrap) to _Queries_ and _Mutations_ +2. [Replace existing add-ons with Farfetched](/tutorial/migrate/effector/addons) operators like `retry`, `cache` or `connectQuery` +3. [Add strict _Contracts_](/tutorial/migrate/effector/contracts) to server responses +4. [Migrate to specific factories](/tutorial/migrate/effector/specific_factories) like `createJsonQuery` and `createJsonMutation` +5. [Apply declarative approach](/tutorial/migrate/effector/trigger_api) with Trigger API and `keepFresh` operator +6. [Continue migrating application step-by-step](/tutorial/migrate/effector/next_steps) diff --git a/apps/website/docs/tutorial/migrate/effector/next.md b/apps/website/docs/tutorial/migrate/effector/next.md new file mode 100644 index 000000000..e69de29bb From 45f3e287ef6c6c7abd47ec7d6545f2634c9affc9 Mon Sep 17 00:00:00 2001 From: Igor Kamyshev Date: Tue, 25 Jul 2023 18:13:50 +0700 Subject: [PATCH 3/4] Fix typo --- apps/website/docs/tutorial/migrate/effector/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/website/docs/tutorial/migrate/effector/index.md b/apps/website/docs/tutorial/migrate/effector/index.md index 9e0de264f..2181df8d3 100644 --- a/apps/website/docs/tutorial/migrate/effector/index.md +++ b/apps/website/docs/tutorial/migrate/effector/index.md @@ -13,4 +13,4 @@ Farfetched is built with continues adoption in mind, so there are straightforwar 3. [Add strict _Contracts_](/tutorial/migrate/effector/contracts) to server responses 4. [Migrate to specific factories](/tutorial/migrate/effector/specific_factories) like `createJsonQuery` and `createJsonMutation` 5. [Apply declarative approach](/tutorial/migrate/effector/trigger_api) with Trigger API and `keepFresh` operator -6. [Continue migrating application step-by-step](/tutorial/migrate/effector/next_steps) +6. [Continue migrating application step-by-step](/tutorial/migrate/effector/next) From 1e68d00f25f12491d3b2c12306b025de2a178fa0 Mon Sep 17 00:00:00 2001 From: Igor Kamyshev Date: Sat, 9 Sep 2023 18:17:35 +0700 Subject: [PATCH 4/4] WIP --- apps/website/docs/.vitepress/config.js | 2 +- .../docs/tutorial/migrate/effector/wrap.md | 74 +++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletion(-) diff --git a/apps/website/docs/.vitepress/config.js b/apps/website/docs/.vitepress/config.js index e32d4209c..c0ee4090a 100644 --- a/apps/website/docs/.vitepress/config.js +++ b/apps/website/docs/.vitepress/config.js @@ -184,7 +184,7 @@ export default withMermaid( link: '/tutorial/migrate/effector/specific_factories', }, { - text: '5. Apply declarative approach', + text: '5. Use Trigger API', link: '/tutorial/migrate/effector/trigger_api', }, { diff --git a/apps/website/docs/tutorial/migrate/effector/wrap.md b/apps/website/docs/tutorial/migrate/effector/wrap.md index e69de29bb..c76c2e677 100644 --- a/apps/website/docs/tutorial/migrate/effector/wrap.md +++ b/apps/website/docs/tutorial/migrate/effector/wrap.md @@ -0,0 +1,74 @@ +# Step 1: Wrap existing data fetching _Effects_ + +::: tip +In this tutorial, we assume you have an application that uses [_Effects_](https://effector.dev/docs/api/effector/effect) for data fetching. +::: + +Farfetched has two primitives for data fetching: [_Queries_](/api/primitives/query) and [_Mutations_](/api/primitives/mutation). It is a complete replacement for [_Effects_](https://effector.dev/docs/api/effector/effect) used for data fetching. Let's start with a key difference between _Effects_ and _Queries_/_Mutations_. + +## _Effects_ vs _Queries_/_Mutations_ + +## Differences between _Queries_ and _Mutations_ + +## Wrap _Effects_ to _Queries_ and _Mutations_ + +All Farfetched APIs are designed to be used with [_Queries_](/api/primitives/query) and [_Mutations_](/api/primitives/mutation). So, to take advantage of Farfetched, we need to wrap existing [_Effects_](https://effector.dev/docs/api/effector/effect) to [_Queries_](/api/primitives/query) and [_Mutations_](/api/primitives/mutation). + +```ts +import { createQuery, createMutation } from '@farfetched/core'; + +const fetchUserFx = createEffect(/*...*/); +const userQuery = createQuery({ effect }); // [!code ++] + +const createPostFx = createEffect(/*...*/); +const createPostMutation = createMutation({ effect }); // [!code ++] +``` + +After this change, instead of direct usage of [_Effects_](https://effector.dev/docs/api/effector/effect) we have to use [_Queries_](/api/primitives/query) and [_Mutations_](/api/primitives/mutation). + +```ts +// Use .start Event instead of Effect +sample({ + clock: someTrigger, + target: fetchUserFx, // [!code --] + target: userQuery.start, // [!code ++] +}); + +// Use .finished.success Event instead of .done Event +sample({ + clock: fetchUserFx.done, // [!code --] + clock: userQuery.finished.success, // [!code ++] + target: someTarget, +}); + +// Use .finished.failure Event instead of .fail Event +sample({ + clock: fetchUserFx.fail, // [!code --] + clock: userQuery.finished.failure, // [!code ++] + target: someTarget, +}); + +// Use .$data Store instead of creating a new Store +const $user = createStore(null); // [!code --] +$user.on(fetchUserFx.doneData, (_, newUser) => newUser); // [!code --] +const $user = userQuery.$data; // [!code ++] +``` + +As soon as no code in the application uses [_Effects_](https://effector.dev/docs/api/effector/effect) directly, we can hide them to prevent accidental usage. + +```ts +const fetchUserFx = createEffect(/*...*/); // [!code --] +const userQuery = createQuery({ effect }); // [!code --] + +const userQuery = createQuery({ effect: createEffect(/*...*/) }); // [!code ++] +``` + +This simple step allows us to use Farfetched APIs with existing [_Effects_](https://effector.dev/docs/api/effector/effect) without rewriting big parts of the codebase. For example, now we can easily add retries to `userQuery`: + +```ts +import { retry } from '@farfetched/core'; + +retry(userQuery, { limit: 3, delay: 1000 }); +``` + +We will dive into more details about Farfetched APIs in the next steps of this tutorial.