created Persisting Data docs

Author: bennobuilder

docs/main/Introduction.md

@@ -162,6 +162,21 @@ Without any context this Section might be useless to you. As the name suggests,
 AgileTs, which are outsourced for a better overview. You might get redirected to parts of the Interface Section from
 other documentation sections. Often to learn some more about specific properties of an interface.
 
+## 🤓 Glossary
+
+In these docs, we will refer to our classes with a capital first letter.
+For example, when you see 'state' we are referring to the programming concept `state`,
+but when you see 'State' we are referring to our [State](../packages/core/features/state/Introduction.md) class.
+
+### `Agile Sub Instance`
+Instances that hold a reference to the [`Agile Instance`](../packages/core/features/agile-instance/Introduction.md)
+and depend on its functionalities.
+- [States](../packages/core/features/state/Introduction.md)
+- [Collections](../packages/core/features/collection/Introduction.md)
+- [Groups](../packages/core/features/collection/group/Introduction.md)
+- [Selectors](../packages/core/features/collection/selector/Introduction.md)
+- [Computed States](../packages/core/features/computed/Introduction.md)
+
 ## 💬 What others say
 
 Actually, nothing, yet. If you want to be the first one, don't mind tweeting whatever you think about AgileTs.

docs/main/StyleGuide.md

@@ -46,7 +46,7 @@ We use the `store.ts` file of a simple TODO application to illustrate how it can
 
 ### 📝 store.ts
 
-In the `store.ts` file, we instantiate the Agile Instance (`Agile`) and define all Agile Sub Instances (`MY_TODOS`).
+In the `store.ts` file, we instantiate the Agile Instance (`Agile`) and define all [Agile Sub Instances](../main/Introduction.md#agile-sub-instance) (`MY_TODOS`).
 In addition, all actions (`updateTodo()`, `toogleTodo()`, ..) and if you are using Typescript, interfaces (`TodoInterface`) are located here.
 If you are wondering why we write AgileTs States uppercase. Well, it has a simple advantage.
 We can easily differentiate between global and local States in our Components.
@@ -237,8 +237,8 @@ export const addTodo = async (userId: string, description: string): Promise<void
 
 ### 📝 .controller.ts
 
-The `controller.ts` manages and represents the Agile Sub Instance (like States, Collections, ..) for an Entity.
-These Agile Sub Instances might get modified by the actions in the [action.ts](#📝-.action.ts) file or bound to Components in the UI-Layer.
+The `controller.ts` manages and represents the [Agile Sub Instances](../main/Introduction.md#agile-sub-instance) (like States, Collections, ..) for an Entity.
+These [Agile Sub Instances](../main/Introduction.md#agile-sub-instance) might get modified by the actions in the [action.ts](#📝-.action.ts) file or bound to Components in the UI-Layer.
 If you are wondering why we write AgileTs States uppercase. Well, it has a simple advantage.
 We can easily differentiate between global and local States in our Components.
 ```ts title="todo.controller.ts in 📁todo"

docs/packages/core/Installation.md

@@ -10,8 +10,8 @@ The `core` package can be installed over [npm](https://www.npmjs.com/).
 ```bash npm2yarn
 npm install @agile-ts/core 
 ```
-If you prefer following a Quick Start Guide,
-which guides you through the process of installing AgileTs in a specific UI-Framework. 🚀
+In case you prefer following a Quick Start Guide,
+which guides you through the process of installing AgileTs in a specific UI-Framework:
 - [React/React-Native](../../quick_start/React.md)
 - [Vue](../../quick_start/Vue.md)
 - [Angular](../../quick_start/Angular.md)

docs/packages/core/Introduction.md

@@ -27,7 +27,7 @@ Therefore, it contains the main Instance of AgileTs, called [`Agile Class`](./fe
 const App = new Agile();
 ```
 In summary the main tasks of the `Agile Class` are to:
-- queuing `Agile Sub Instance` changes in the `runtime` and preventing race conditions
+- queuing [`Agile Sub Instance`](../../main/Introduction.md#agile-sub-instance) changes in the `runtime` and preventing race conditions
 - provide configuration object
 - update/rerender subscribed Components through Integrations like the [React Integration](../react/Introduction.md)
 - Integrating with persistent [Storage](./features/storage/Introduction.md)
@@ -59,7 +59,7 @@ MY_COLLECTION.remove(1).everywhere(); // Remove Data at primary Key '1' from Col
 ```
 
 ### 🤖 [Computed](./features/state/Introduction.md)
-A Computed is an extension of the `State Class` and automatically computes its value depending on other Agile Sub Instances like States, Collections, ..
+A Computed is an extension of the `State Class` and automatically computes its value depending on other [Agile Sub Instances](../../main/Introduction.md#agile-sub-instance) like States, Collections, ..
 ```ts
  const MY_COMPUTED = App.createComputed(() => (MY_STATE_1.value + MY_STATE_2.value));
 ```
@@ -85,4 +85,5 @@ A Computed is an extension of the `State Class` and automatically computes its v
   - [Properties](./features/computed/Properties.md)
   - [Methods](./features/computed/Methods.md)
 - [Storage](./features/storage/Introduction.md)
+  - [Persisting Data](./features/storage/PersistingData.md)
 - [Integration](./features/integration/Introduction.md)

docs/packages/core/features/agile-instance/Introduction.md

@@ -9,11 +9,11 @@ The `Agile Class` is the main Instance of AgileTs and should be unique to our ap
 ```ts
 const App = new Agile();
 ```
-It can be seen as the interface to any Storage or the Frameworks AgileTs is implemented in.
-In addition, it manages the changes of `Agile Sub Instances` to prevent race conditions.
+It can be seen as an Interface to any Storage or the Frameworks AgileTs is implemented in.
+In addition, it manages the changes of [`Agile Sub Instances`](../../../../main/Introduction.md#agile-sub-instance) to prevent race conditions.
 Each `Agile Sub Instance` (ASI) holds a reference to the `Agile Class` and depends on its functionalities.
-Furthermore, ASI's are created with the help of an instantiated `Agile Class`.
-For reference, here are some `Agile Sub Instances` (ASI) created with an `Agile Instance` called `App`:
+Furthermore, ASI's can be created with the help of an instantiated `Agile Class`.
+For reference, here are some `Agile Sub Instances` (ASI) created with an instantiated `Agile Instance` called `App`:
 
 - [State](../state/Introduction.md)
   ```ts
@@ -29,7 +29,7 @@ For reference, here are some `Agile Sub Instances` (ASI) created with an `Agile
    ```
 
 In summary the main tasks of the `Agile Class` are to:
-- queuing `Agile Sub Instance` changes in the `runtime` and preventing race conditions
+- queuing [`Agile Sub Instance`](../../../../main/Introduction.md#agile-sub-instance) changes in the `runtime` and preventing race conditions
 - provide configuration object
 - update/rerender subscribed Components through Integrations like the [React Integration](../../../react/Introduction.md)
 - Integrating with persistent [Storage](../storage/Introduction.md)
@@ -80,7 +80,7 @@ To find out more about possible configuration options, checkout the [CreateLogge
 
 #### `localStorage`
 Whether AgileTs should create an interface to the [Local Storage](https://www.w3schools.com/html/html5_webstorage.asp) and set it as default Storage.
-Each Agile Sub Instance we persist (`.persist()`), will then be stored in the `localStorage` by default.
+Each [Agile Sub Instance](../../../../main/Introduction.md#agile-sub-instance) we persist (`.persist()`), will then be stored in the `localStorage` by default.
 ```ts
 new Agile({
   localStorage: false // default true

docs/packages/core/features/agile-instance/Properties.md

@@ -13,8 +13,8 @@ Here are valuable properties of the `Agile Class` listed.
 
 ## `logger`
 
-The `logger` is a static property of the `Agile Class`,
-used internally to log warnings, errors, debug messages, .. to the console.
+The `logger` is a static property of the `Agile Class`.
+It is used internally to log warnings, errors, debug messages, .. to the console.
 ```ts
 Agile.logger.warn("This is a Warning");
 Agile.logger.log("This is a normal Log");

docs/packages/core/features/collection/Methods.md

@@ -989,83 +989,10 @@ All other Instances that refer to the Collection have to be persisted separately
 MY_COOL_GROUP.persist();
 ```
 
-### 💻 Web
-In a web environment, it is common to use the [Local Storage](https://www.w3schools.com/html/html5_webstorage.asp) to store values permanently.
-AgileTs has set up the Local Storage by default.
-```ts {2}
-const App = new Agile({
-  localStorage: true
-});
-```
-Therefore, we can use the `persist()` method out of the box.
-
-### 📱 Mobile
-Since the Local Storage doesn't exist in a mobile environment,
-we have to resort to an alternative, such as the [Async Storage](https://reactnative.dev/docs/asyncstorage).
-AgileTs hasn't set up the Async Storage by default.
-Therefore, we need to create a [Storage](../storage/Introduction.md) Interface representing the Async Storage
-and register it to AgileTs.
-```ts {3-9}
-App.registerStorage(
-  App.createStorage({
-    key: "AsyncStorage",
-    async: true,
-    methods: {
-      get: AsyncStorage.getItem,
-      set: AsyncStorage.setItem,
-      remove: AsyncStorage.removeItem,
-    },
-  }), {default: true} // Tells AgileTs that it is the default Storage
-);
-```
-
-### 🔑 Local Storage Key
-Thus AgileTs can access and identify the stored value in the appropriate Storage,
-we have to define a unique `storageKey`.
-There are several ways to provide such required `storageKey` to the `persist()` method.
-
-- **1.** Assign a unique key to the Collection itself.
-  Because if no key is given to the `persist()` method,
-  it takes the Collection key as `storageKey`.
-  ```ts {2}
-  MY_COLLECTION.key = "myCoolKey";
-  MY_COLLECTION.persist(); // Success (storageKey = 'myCoolKey')
-  ```
-- **2.** Pass the `storageKey` directly into the `persist()` method.
-  ```ts {1}
-  MY_COLLECTION.persist("myCoolPassedKey"); // Success (storageKey = 'myCoolPassedKey')
-  ```
-
-If AgileTs couldn't find any fitting `storageKey`,
-it throws an error and doesn't persist the Collection `value`.
-```ts {2}
-MY_COLLECTION.key = undefined;
-MY_COLLECTION.persist(); // Error
-```
+### 🤓 Learn more
 
-### 💾 `default` Storage
-In AgileTs we can register `multipe` Storages. However only one of these Storages can be the `default` Storage.
-The `default` Storage is used by the `persist()` method whenever no specific Storage is defined.
-```ts {1}
-MY_COLLECTION.persist(); // persist in default Storage
-MY_COLLECTION.persist({
-  storageKeys: ["storageA"]
-}); // persist in Storage called 'storageA'
-```
-
-### 📝 Multiple Storages
-Sometimes we may store Collections in different Storages.
-For example, _Collection A_ should be stored in _Storage B_, and _Collection B_ should be stored in _Storage A_.
-Then, we can define with `storageKeys` in which specific Storage the Collection `value` should be persisted.
-```ts {2}
-MY_COLLECTION.persist({
-  storageKeys: ["myCustomStorage"]
-});
-```
-By default, the Collection will be stored in the [default Storage](#-default-storage).
-```ts
-App.storages.config.defaultStorageKey; // Returns key of current default Storage
-```
+If you want to find out more about persisting Instances like Collections,
+checkout the [Persisting Data](../storage/PersistingData.md) Section.
 
 ### 📭 Props
 

docs/packages/core/features/computed/Introduction.md

@@ -14,7 +14,7 @@ const MY_COMPUTED = App.createComputed(() => {
     return `My name is '${MY_NAME.value}' and I am ${MY_AGE.value} years old.`;
 });
 ```
-A `Computed` will magically track used dependencies (such as Agile Sub Instances like [States](../state/Introduction.md) or [Collections](../collection/Introduction.md))
+A `Computed` will magically track used dependencies (such as [Agile Sub Instances](../../../../main/Introduction.md#agile-sub-instance) like [States](../state/Introduction.md) or [Collections](../collection/Introduction.md))
 and recomputes when any of its dependencies mutates. For instance, in the above example, it would recompute when the `MY_NAME` value changes from 'jeff' to 'hans'.
 ```ts
 MY_COMPUTED.value; // Returns "My name is 'jeff' and I am 10 years old"
@@ -99,7 +99,7 @@ MY_COMPUTED.value; // Returns "My name is 'jeff' and I am 10 years old."
 ```
 In most cases, it isn't necessary to provide any hard-coded dependency.
 However, it might occur that the Computed Class fails to autodetect a particular dependency.
-You can check if all dependencies got correctly noticed by giving each used Agile Sub Instance a unique key
+You can check if all dependencies got correctly noticed by giving each used [Agile Sub Instance](../../../../main/Introduction.md#agile-sub-instance) a unique key
 and reviewing the `deps` array.
 ```ts
 MY_COMPUTED.deps; // Returns '[Observer('myName'), Observer('myAge')]'

docs/packages/core/features/integration/Introduction.md

@@ -16,7 +16,7 @@ If there is no existing Integration yet, this Section might be interesting for y
 :::
 
 The `Integration Class` serves an Interface to UI-Frameworks like [React](https://reactjs.org/).
-Its main task is to cause rerender on Components that have subscribed Agile Sub Instances like [States](../state/Introduction.md).
+Its main task is to cause rerender on Components that have subscribed A[Agile Sub Instances](../../../../main/Introduction.md#agile-sub-instance) like [States](../state/Introduction.md).
 ```ts
 new Integration({
   key: 'myFramework',
@@ -29,7 +29,7 @@ new Integration({
   updateMethod: (componentInstance, updatedData) => {
     // Will be called on each State value mutation (only in Component based Subscriptions)
     // For example, if MY_STATE value mutates from 'jeff' to 'hans'
-    // Then this method will be called with folowing props:  
+    // Then this method will be called with the following props:  
     // componentInstance: Component to which the State is subscribed to
     // updatedData: Changed data (in our case '{myState: 'hans'}')
     // 
@@ -93,7 +93,7 @@ App.subController.subscribeWithSubsArray(
    }
 );
 ```
-This way, we can ensure that each Agile Sub Instance can be mapped into the `updateData` object.
+This way, we can ensure that each [Agile Sub Instance](../../../../main/Introduction.md#agile-sub-instance) can be mapped into the `updateData` object.
 
 ### `Callback` based
 
@@ -164,14 +164,15 @@ However, to efficiently use AgileTs in Functional and Class Components,
 we had to create ways to simplify the binding of States to UI-Components.
 Therefore, we created the `useAgile()` Hook for Functional Components
 and the `AgileHOC()` for Class Components.
-Below we visually demonstrate the difference of,
+In the following examples we visually demonstrate the difference of,
 how much easier e.g. the `useAgile()` Hook made the binding of States to Components:
 - binding State with `useAgile()`:
    ```ts title=FunctionalComponent.ts
     useAgile(MY_STATE);
    ```
 - binding State manually:
    ```ts title=FunctionalComponent.ts
+    // Simple reducer to create a 'rerender' callback
     const [, forceRender] = React.useReducer((s) => s + 1, 0);
 
     useEffect(() => {
@@ -259,7 +260,7 @@ new Integration(config);
 
 ### `config`
 
-A `Integration` takes a required configuration object as its only parameter.
+An `Integration` takes a required configuration object as its only parameter.
 ```ts
 new Integration<typeof React, AgileReactComponent>({
   key: 'myFramework',
@@ -350,7 +351,7 @@ Will be called as soon as a State subscribed to a Component (`componentInstance`
 new Integration({
   updateMethod: (componentInstance, updatedData) => {
     // For example, if MY_STATE value mutates from 'jeff' to 'hans'
-    // Then this method will be called with folowing props:  
+    // Then this method will be called with the following props:  
     // componentInstance: Component to which the State is subscribed to
     // updatedData: Changed data (for instance '{myState: 'hans'}')
   }

docs/packages/core/features/state/Methods.md

@@ -527,83 +527,10 @@ Preserves the State `value` in the appropriate local Storage for the current env
 MY_STATE.perist("myStorageKey");
 ```
 
-### 💻 Web
-In a web environment, it is common to use the [Local Storage](https://www.w3schools.com/html/html5_webstorage.asp) to store values permanently.
-AgileTs has set up the Local Storage by default.
-```ts {2}
-const App = new Agile({
-  localStorage: true
-});
-```
-Therefore, we can use the `persist()` method out of the box.
-
-### 📱 Mobile
-Since the Local Storage doesn't exist in a mobile environment,
-we have to resort to an alternative, such as the [Async Storage](https://reactnative.dev/docs/asyncstorage).
-AgileTs hasn't set up the Async Storage by default.
-Therefore, we need to create a [Storage](../storage/Introduction.md) Interface representing the Async Storage
-and register it to AgileTs.
-```ts {3-9}
-App.registerStorage(
-  App.createStorage({
-    key: "AsyncStorage",
-    async: true,
-    methods: {
-      get: AsyncStorage.getItem,
-      set: AsyncStorage.setItem,
-      remove: AsyncStorage.removeItem,
-    },
-  }), {default: true} // Tells AgileTs that it is the default Storage
-);
-```
-
-### 🔑 Local Storage Key
-Thus AgileTs can access and identify the stored value in the appropriate Storage,
-we have to define a unique `storageKey`.
-There are several ways to provide such required `storageKey` to the `persist()` method.
-
-- **1.** Assign a unique key to the State itself.
-  Because if no key is given to the `persist()` method,
-  it takes the State key as `storageKey`.
-  ```ts {2}
-  MY_STATE.key = "myCoolKey";
-  MY_STATE.persist(); // Success (storageKey = 'myCoolKey')
-  ```
-- **2.** Pass the `storageKey` directly into the `persist()` method.
-  ```ts {1}
-  MY_STATE.persist("myCoolPassedKey"); // Success (storageKey = 'myCoolPassedKey')
-  ```
-
-If AgileTs couldn't find any fitting `storageKey`,
-it throws an error and doesn't persist the State `value`.
-```ts {2}
-MY_STATE.key = undefined;
-MY_STATE.persist(); // Error
-```
+### 🤓 Learn more
 
-### 💾 `default` Storage
-In AgileTs we can register `multipe` Storages. However only one of these Storages can be the `default` Storage.
-The `default` Storage is used by the `persist()` method whenever no specific Storage is defined.
-```ts {1}
-MY_STATE.persist(); // persist in default Storage
-MY_STATE.persist({
-  storageKeys: ["storageA"]
-}); // persist in Storage called 'storageA'
-```
-
-### 📝 Multiple Storages
-Sometimes we may store States in different Storages.
-For example, _State A_ should be stored in _Storage B_, and _State B_ should be stored in _Storage A_.
-Then, we can define with `storageKeys` in which specific Storage the State `value` should be persisted.
-```ts {2}
-MY_STATE.persist({
-  storageKeys: ["myCustomStorage"]
-});
-```
-By default, the State will be stored in the [default Storage](#-default-storage).
-```ts
-App.storages.config.defaultStorageKey; // Returns key of current default Storage
-```
+If you want to find out more about persisting Instances like States,
+checkout the [Persisting Data](../storage/PersistingData.md) Section.
 
 ### 📭 Props