Merge pull request #71 from agile-ts/develop

Develop

Author: bennobuilder

docs/main/Installation.md

@@ -14,15 +14,15 @@ AgileTs is essentially a set of npm [packages](https://github.com/agile-ts/agile
 ### 🚀 Quick Start
 
 To make your start as easy as possible, we have created some quick guides. You can follow these to get AgileTs up and
-running in your environment without wasting any time. Below you can find environments AgileTs is already supporting.
+running in your environment without wasting any time. Below you find _Quick Starts_ for already supported frameworks.
 
 - [React](../quick_start/React.md)
 - Vue (coming soon)
 - Angular (coming soon)
 
 ### 🗂 Packages
 
-Here are some separate installation guides for single AgileTs packages.
+Separate installation guides for single AgileTs packages.
 
 - [Core](../packages/core/Installation.md)
 - [React](../packages/react/Installation.md)

docs/main/Introduction.md

@@ -5,7 +5,7 @@ sidebar_label: Introduction
 slug: /introduction/
 ---
 
-> **Spacy, Simple, Scalable State Management Framework**
+> **Global, Spacy, Scalable State and Logic Framework**
 
 <a href="https://github.com/agile-ts/agile">
   <img src="https://img.shields.io/github/license/agile-ts/agile.svg?label=license&style=flat&colorA=293140&colorB=4a4872" alt="GitHub License"/></a>
@@ -30,8 +30,8 @@ and not completed yet!
 
 ## 👋 Introduction
 
-AgileTs is a simple, fast, and well-tested State Management Framework implemented in TypeScript. It's more
-flexible and boilerplate-free than Redux and has an interesting approach to reducing the codebase size through a
+AgileTs is a global, simple, well-tested State Management Framework implemented in TypeScript. 
+It's more flexible and boilerplate-free than frameworks like Redux and has a powerful approach to reducing the codebase size through a
 centralized memory design pattern. The philosophy behind AgileTs is simple:
 
 ### 🚅 Straightforward
@@ -49,15 +49,15 @@ Write minimalistic, boilerplate-free code that captures your intent.
   MY_COLLECTION.collect({id: 1, name: "Frank"});
   MY_COLLECTION.collect({id: 2, name: "Dieter"});
   ```
-- Mutate or Check States with simple Functions
+- Mutate and Check States with simple Functions
   ```ts
   MY_STATE.undo(); // Undo latest change
   MY_STATE.is({hello: "jeff"}); // Check if State has the Value '{hello: "jeff"}'
   ```
 
 ### 🤸‍ Flexible
 
-- Works in nearly every UI-Framework. Check [here](https://agile-ts.org/docs/frameworks) if your preferred Framework is supported too.
+- Works in nearly any UI-Framework. Check [here](https://agile-ts.org/docs/frameworks) if your preferred Framework is supported too.
 - Surly behaves with the workflow which suits you best. No need for _reducers_, _actions_, ..
 - Has **no** external dependencies
 
@@ -110,8 +110,7 @@ our [Quick Start](./Installation.md) Guides, where you learn the basics about ho
 Framework. After knowing the ground concept of AgileTs, we recommend checking out the [Style Guides](./StyleGuide.md).
 The Style Guides will help you get some inspiration on structuring a scalable application using AgileTs. Now you
 are ready to use AgileTs wherever you want. In case you need some more information about some functionalities of AgileTs,
-use the search bar in the top right corner. If you have any questions and can't find the correct answer in the
-documentation, don't hesitate to join our [Discord Community](https://discord.gg/T9GzreAwPH).
+use the search bar in the top right corner. In case you have any further questions don't hesitate to join our [Community Discord](https://discord.gg/T9GzreAwPH).
 
 ## 🏢 Structure of Documentation
 

docs/packages/core/Introduction.md

@@ -21,23 +21,24 @@ slug: /core
 
 ## ❓ `core`
 
-The `core` package is the brain of AgileTs. Nearly everything related to AgileTs depends on this package. It
-includes the main Instance of AgileTs, the [`Agile Class`](./features/agile-instance/Introduction.md) often
-called `App`.
+The `core` is the main package of AgileTs and includes the whole state management logic.
+Therefore, it can be seen as the brain of AgileTs that manages all your States.
+It includes the main Instance of AgileTs, called [`Agile Class`](./features/agile-instance/Introduction.md).
 ```ts
 const App = new Agile();
 ```
-In summary, the main tasks of the `Agile Class` are to
-- manage Agile Sub Instances, like [States](./features/state/Introduction.md), ..
-- ingest changes into the Runtime
+In summary, the most important tasks of the `Agile Class` are to
+- manage `Agile Sub Instances`, like [States](./features/state/Introduction.md), ..
+- ingest changes into the `runtime`
 - trigger rerender in Integrations like [React](../react/Introduction.md)
 - store values in any [Storage](./features/storage/Introduction.md)
 
-As you can guess, each application using AgileTs has to install
-the `core` package and instantiate such an `Agile Class`.
-To get some inspiration where to instantiate such`Agile Class`, check out the [Style Guide](../../main/StyleGuide.md).
-Besides the `Agile Class` the `core` holds some other useful classes
-listed below. But each of these classes depends in some kind on the `Agile Class`.
+Each application using AgileTs needs the `core` package 
+and has to instantiate a `Agile Class` often called `App`.
+To get some inspiration where to instantiate the `Agile Class`, check out the [Style Guide](../../main/StyleGuide.md) Section.
+Besides the `Agile Class` the `core` holds some other useful classes,
+which represent the actual features of AgileTs, since the `Agile Class`
+is mostly used internally.
 
 ### ⚡️ [State](./features/state/Introduction.md)
 A State holds an Information that we need to remember at a later point in time.
@@ -57,7 +58,8 @@ 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`, it does automatically compute its value depending on other Agile Instances like States, Collections, ..
+A Computed is an extension of the `State Class`, 
+it automatically computes its value depending on other Agile Sub Instances like States, Collections, ..
 ```ts
  const MY_COMPUTED = App.createComputed(() => (MY_STATE_1.value + MY_STATE_2.value));
 ```

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

@@ -15,8 +15,9 @@ The `Agile Class` is the foundation of AgileTs. Everything related to AgileTs de
 ```ts
 const App = new Agile();
 ```
-It can be seen as your application store, which manages and stores each `Agile Sub Instance` (ASI).
-The `Agile Class` doesn't contain these ASI's internally, but each ASI includes a reference to the main `Agile Class`. For instance, to pass something into the `runtime`.
+It can be seen as your application store, which manages each `Agile Sub Instance` (ASI).
+The `Agile Class` doesn't contain these ASI's internally, but each ASI includes a reference to the main `Agile Class`. 
+For instance, to pass something into the `runtime`.
 Here are some Agile Sub Instances (ASI):
 
 - [State](../state/Introduction.md)
@@ -43,7 +44,8 @@ In summary, the main tasks of an instantiated `Agile Class` (Agile Instance) are
 - trigger rerender on Integrations like [React](../../../react/Introduction.md)
 - store values in any [Storage](../storage/Introduction.md)
 
-Be aware that each application using AgileTs should have **one** `Agile Instance` because multiple can cause trouble.
+Be aware that each application using AgileTs needs at least one `Agile Instance`,
+but also shouldn't have more, because multiple `Agile Instance` in one application might cause trouble.
 
 ## 📭 Props
 

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

@@ -11,7 +11,7 @@ WIP docs!
 
 :::
 
-A Collection holds a set of Information we need to remember at a later point in time.
+A Collection holds a _set_ of Information we need to remember at a later point in time.
 It is designed for arrays of data objects following the same pattern.
 Each of these objects must have a **unique primaryKey** to be correctly identified later.
 We instantiate a Collection with help of an existing [Agile Instance](../agile-instance/Introduction.md) often called `App`.
@@ -26,7 +26,7 @@ MY_COLLECTION.collect({id: 1, name: "jeff"}); // Add Item to Collection
 MY_COLLECTION.remove(1).everywhere(); // Remove Item from Collection
 MY_COLLECTION.persist(); // Persists Collection Value into a Storage
 ```
-If you want to find out more about the Collection's specific methods, check out the [Methods](./Methods.md) docs.
+If you want to find out more about the Collection's specific methods, check out the [Methods](./Methods.md) Section.
 Most methods we use to modify, mutate and access the Collection are chainable.
 ```ts
 MY_COLLECTION.collect({id: 1, name: "jeff"}).persist().removeGroup('myGroup').reset();
@@ -46,7 +46,7 @@ In the example above, we create a simple `TODO` Collection.
 After the instantiation, we add two todos to it
 and specify that both todos remain to the `user1` [Group](#groups).
 We do that to keep track of which todo relates to which user.
-Now that we cleaned our bathroom,
+Now that we `cleaned our bathroom`,
 we remove the todo related to the id `1` from the Collection and all Groups (everywhere).
 
 ### ⛳️ Sandbox
@@ -55,19 +55,23 @@ Test the Collection yourself. It's only one click away. Just select your preferr
 - Vue (coming soon)
 - Angular (coming soon)
 
-## 🔹 Item
+## 🗂 Collection Classes
+
+A Collection consists of several classes, all of which perform important tasks.
+
+### 🔹 Item
 
 Each Data Object we add to our Collection (for example, with the `collect()` method)
-automatically becomes an `Item` and gets stored in a so-called `data` object directly in the Collection.
+automatically becomes an `Item` and gets directly stored in a so-called `data` object in the Collection.
 ```ts
 {
-  99: Item() // has value '{id: 99, name: "frank"}'
-  1: Item() // has value '{id: 1, name: "jeff"}'
-  2: Item() // has value '{id: 2, name: "hans"}'
+  99: Item(99) // has value '{id: 99, name: "frank"}'
+  1: Item(1)  // has value '{id: 1, name: "jeff"}'
+  2: Item(2) // has value '{id: 2, name: "hans"}'
 }
 ```
 It is best not to touch the `data` object at all
-and use the provided functions by the Collection to mutate and get access to it instead.
+and use the functions provided by the Collection to mutate and get access to it instead.
 For instance, there are many ways to access our collected Items.
 
 - #### `getItem()`
@@ -104,7 +108,7 @@ myItem.patch({name: "frank"}); // Update property 'name' in Item
 myItem.undo(); // Undo latest change
 ```
 
-## 👨‍👧‍👦 [Group](./group/Introduction.md)
+### 👨‍👧‍👦 [Group](./group/Introduction.md)
 
 Often applications need to categorize and preserve the ordering of structured data.
 In AgileTs, Groups are the cleanest way to do so.
@@ -138,7 +142,7 @@ POSTS.collect(user.posts, user.id);
 In the above code snippet, we have two Collections, one for users and another for posts.
 We can collect posts specific to a user and group them automatically by the user's id.
 
-## 🔮 [Selector](./selector/Introduction.md)
+### 🔮 [Selector](./selector/Introduction.md)
 
 Sometimes we need access to one specific Item of a Collection in the long term.
 Therefore, AgileTs offers the Selector.
@@ -164,19 +168,23 @@ App.createCollection(config);
 
 ### `config`
 
-A `Collection` takes an optional configuration object as its only property.
+A `Collection` takes an optional configuration object as its only parameter.
 There are two different ways of configuring a Collection. Both have their advantages.
 
 - **1.** The plain _object_ way, which is notorious for its ease of use.
-  Because here, we configure everything in a specific object. For instance, this makes the creation of Groups pretty straightforward. But on the other hand, it gives us some limitations since we aren't creating and configuring the Groups and Selectors on our own. The Collection takes care of it instead.
+  Here, we configure everything in a specific object. For instance, this makes the creation of Groups pretty straightforward. 
+  But on the other hand, it gives us some limitations since we aren't creating and configuring the Groups and Selectors on our own. 
+  The Collection takes care of it instead.
      ```ts
      const Collection = App.createCollection({
      key: 'dummyCollection',
      group: ["dummyGroup"]
      })
      ```
 
-- **2.** The _function_ way, where a function, which has the Collection as  first parameter, returns the configuration object. This gives us more freedom in configuring Instances like Groups, since we have access to the Collection and can create them on our own.
+- **2.** The _function_ way, where a function, which has the Collection as  first parameter, returns the configuration object. 
+  This gives us more freedom in configuring Instances like Groups, 
+  since we have access to the Collection and can create them on our own.
      ```ts
      const Collection = App.createCollection((collection) => ({
      key: 'dummyCollection',
@@ -203,15 +211,15 @@ export interface CreateCollectionConfigInterface<DataType = DefaultItem> {
 
 #### `groups`
 The initial [Groups](#groups) of our Collection are defined with this property's help.
-There are two ways of doing this.
-The first one is to pass an Array of Group Names.
-AgileTs will than take care of the Group's creation and calls them after the previously passed names.
+There are two different ways of doing so.
+The first one is to pass an Array of Group names/keys,
+where AgileTs takes care of the Group's creation and names them after the previously passed names.
 ```ts
 const MY_COLLECTION = App.createCollection({
   groups: ["myGroup1", "myGroup2"]
 });
 ```
-The way mentioned above has some limitations. For instance, we can't define any initial Items.
+The way mentioned above has some limitations, since we can't configure the Groups on our own.
 Luckily there is a second way, where we have access to the Collection itself.
 ```ts
 const MY_COLLECTION = App.createCollection((collection) => ({
@@ -223,21 +231,21 @@ const MY_COLLECTION = App.createCollection((collection) => ({
 }));
 ```
 With the help of the Collection, we can 'instantiate' the Groups on our own,
-which gives us much more freedom configuring in configuring them.
+which gives us much more freedom in configuring them.
 
 <br/>
 
 #### `selectors`
 The initial [Selectors](#selectors) of our Collection are defined with this property's help.
-As with the `groups` property, there are two ways of doing that.
-The first one is to pass an Array of Selector Names.
-AgileTs will than take care of the Selector's creation and calls them after the previously passed names.
+As with the `groups` property, there are two different ways of doing so.
+The first one is to pass an Array of Selector names/keys,
+where AgileTs takes care of the Selector's creation and names them after the previously passed names.
 ```ts
 const MY_COLLECTION = App.createCollection({
   selectors: ["mySelector1", "mySelector2"]
 });
 ```
-The way mentioned above has some limitations. For instance, we can't define the initial selected Item Key.
+The way mentioned above has some limitations, since we can't configure the Selectors on our own.
 Luckily there is a second way, where we have access to the Collection which gets created.
 ```ts
 const MY_COLLECTION = App.createCollection((collection) => ({
@@ -257,7 +265,7 @@ which gives us much more freedom in configuring them.
 The name/key is an optional property that is used to identify a specific Collection.
 Such key is pretty useful during debug sessions or if we persist our Collection,
 it automatically uses the Collection `key` as persist key.
-We recommend giving each Collection an unique `key`, since it has only advantages.
+We recommend giving each Collection a unique `key`, since it has only advantages.
 ```ts
 const MY_COLLECTION = App.createCollection({
   key: "myKey"
@@ -267,7 +275,7 @@ const MY_COLLECTION = App.createCollection({
 <br/>
 
 #### `primaryKey`
-It defines which property's value in collected data will be selected as `primaryKey`.
+Defines which property's value in collected data will be selected as `primaryKey`.
 By default, it is `id`. A `primaryKey` identifies a specific Item, and has to be part of each collected data.
 ```ts
 const MY_COLLECTION = App.createCollection({
@@ -282,12 +290,12 @@ MY_COLLECTION.collect({key: 1, name: "hans"});
 <br/>
 
 #### `defaultGroupKey`
-The defaultGroupKey describes the name/key of the default [Group](#group).
+Describes the name/key of the default [Group](#group).
 The default Group represents all Items of the Collection.
-By default, its is `default`.
+By default, it is `default`.
 ```ts
 const MY_COLLECTION = App.createCollection({
-  defaultGroupKey: "allItemsOfCollection"
+  defaultGroupKey: "allItemsOfCollectionKey"
 });
 ```
 
@@ -303,7 +311,8 @@ const MY_COLLECTION = App.createCollection({
 
 ## 🟦 Typescript
 
-A `Collection` is almost 100% typesafe and takes an optional generic type for type safety that has to be followed by each collected data object.
+A `Collection` is almost 100% typesafe and takes an optional generic type for type safety 
+that has to be followed by each collected data object.
 ```ts
 interface UserInterface {
   id: number,