Merge pull request #83 from agile-ts/develop

Develop

Author: bennobuilder

docs/examples/react/All.mdx

@@ -44,3 +44,6 @@ export const CodeSandBoxEmbed = ({ uri, height }) => (
 ## 👴 First State [Class Component]
 <CodeSandBoxEmbed uri={"agilets-first-state-with-hoc-1qdew"}/>
 
+## ✔️ Simple Todo List
+<CodeSandBoxEmbed uri={"agilets-simple-todo-list-glmc4"}/>
+

docs/main/Introduction.md

@@ -5,7 +5,7 @@ sidebar_label: Introduction
 slug: /introduction/
 ---
 
-> **Global, Spacy, Scalable State and Logic Framework**
+> **Global 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>
@@ -21,18 +21,12 @@ slug: /introduction/
 <br />
 <br />
 
-:::warning
-
-These docs are work in progress
-and not completed yet!
-
-:::
-
 ## 👋 Introduction
 
-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:
+AgileTs is a global, simple, well-tested State Management Framework implemented in Typescript.
+It offers a reimagined API that focus on **developer experience** and allows you to **quickly** and **easily** manage your States.
+Besides States, AgileTs offers other powerful classes which make your life easier.
+The philosophy behind AgileTs is simple:
 
 ### 🚅 Straightforward
 Write minimalistic, boilerplate-free code that captures your intent.
@@ -43,6 +37,7 @@ Write minimalistic, boilerplate-free code that captures your intent.
   ```ts
   MY_STATE.undo(); // Undo latest change
   MY_STATE.is({hello: "jeff"}); // Check if State has the Value '{hello: "jeff"}'
+  MY_STATE.watch((value) => {console.log(value);}); // Watch on State changes
   ```
 - Store State in any Storage, like [Local Storage](https://www.w3schools.com/html/html5_webstorage.asp)
   ```ts
@@ -54,6 +49,12 @@ Write minimalistic, boilerplate-free code that captures your intent.
   MY_COLLECTION.collect({id: 1, name: "Frank"});
   MY_COLLECTION.collect({id: 2, name: "Dieter"});
   ```
+- Compute State depending on other States
+  ```ts
+  const MY_INTRODUCTION = App.createComputed(() => {
+     return `Hello I am '${MY_NAME.vale}' and I use ${MY_STATE_MANAGER.value} for State Management.`;
+  });
+  ```
 
 ### 🤸‍ Flexible
 
@@ -69,7 +70,7 @@ The benefit of keeping logic separate to UI-Components is to make your code more
 ### 🎯 Easy to Use
 
 Learn the powerful tools of AgileTs in a short amount of time. An excellent place to start are
-our [Quick Start](./Installation.md) Guides, or if you are no fan of following any tutorial, 
+our [Quick Start](./Installation.md) Guides, or if you don't like following any tutorial, 
 jump straight into our [Example](../examples) section.
 
 
@@ -92,7 +93,7 @@ const MY_FIRST_STATE = App.createState("Hello Stranger!");
 // -- myComponent.whatever ------------------------------------------
 
 // Finally, we bind the just initialized State to our desired UI-Component
-// And wolla, it's reactive. Everytime the State mutates the Component gets rerendered
+// And wolla, it's reactive. Everytime the State mutates the Component rerenders
 const myFirstState = useAgile(MY_FIRST_STATE); // returns value of State ("Hello Stranger!")
 ```
 
@@ -112,7 +113,7 @@ More examples can be found in the [Example](../examples/Indroduction.md) Section
 ## 👨‍💻 When use AgileTs
 
 AgileTs is thought to handle the business logic and logic in general that isn't explicitly bound to a Component of your application.
-So you should use AgileTs if you have to handle any global State and logic that you want to manage at a central place.
+We recommend using AgileTs to manage global States and their logic at a central place.
 
 ## 👨‍🏫 Learn AgileTs
 
@@ -156,20 +157,62 @@ 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 docs. Often to learn some more about specific properties of an interface.
 
-## ❓ Something missing
+## 💬 What others say
 
-If you find issues with the documentation or have suggestions on how to improve the documentation or the project in
-general, please [file an issue](https://github.com/agile/agile-ts/issues) for us or join
-our [Discord Community](https://discord.gg/T9GzreAwPH).
+Actually nothing, yet. If you want to be the first one, don't mind tweeting what ever you think about AgileTs.
+But don't forget to tag [@AgileFramework](https://twitter.com/AgileFramework), otherwise we can't find your tweet.
+
+## 🌏 Creation of AgileTs
+
+After exploring the many options for Javascript State libraries, including the popular Redux and MobX.
+I felt like I need a simpler, more straightforward solution. 
+One day I accidentally stumbled across a stream from [@jamiepine](https://twitter.com/jamiepine).
+Jamie was using an interesting approach of State Management which I haven't seen yet.
+The framework he used, was PulseJs, the ancestor of AgileTs, so to speak.
+I liked this concept of State Management a lot and started using it in my own projects.
+At this point in time (spring 2020) it wasn't officially released. 
+Therefore, it was quite buggy and had no documentation. But I figured out of to use it anyway
+and saved my finding in a small [pre-documentation](https://www.notion.so/bennoworkspace/Pulse-v3-No-official-Docs-4e92e8d02dd3423582fa95072806cab6) for PulseJs fellows.
+The months went by and no stable version came out. Not even a npm package.
+In July, I came to the conclusion to contribute to PulseJs, in order to speed the development process a bit up.
+But before I could do anything, I had to figure out how PulseJs works internally.
+After hours, I still haven't figured out how it works. This was due to the fact that I was a Typescript noob,
+and the codebase was not contributor friendly. (No comments, variables called x, a, b, ..).
+In order to learn how PulseJs works and to get a deeper understanding of Typescript, 
+I decided to rewrite PulseJs from scratch in a separate project, later AgileTs.
+After a while, I got the hang and had a good understanding how PulseJs works under the hood.
+Now that I knew how PulseJs works, I could finally start contributing.
+My [first contribution](https://github.com/pulse-framework/pulse/commits?author=bennodev19) was on the 16th August 2020,
+where I refactored the `PulseHOC`. Unfortunately PulseJs was moving further and further away from my idea of an ideal State Management Framework.
+For instance, they introduced the `Pulse.Core`, which more or less forced me to define all States, Actions in a single object called `core`.
+I wouldn't say I liked that change since I switched among other reasons to PulseJs in order to not define all my States in a single object.
+Because of this relatively large design change, I would have to rebuild my entire State Management Logic of my applications.
+Which I didn't want to do, because I liked the old concept more.
+Luckily I had the refactored PulseJs version lying around, which I created to learn how PulseJs works internally and released it as an own framework called
+[agile-architecture](https://www.npmjs.com/package/agile-architecture).
+Agile-Architecture was at that point just an old refactored version of PulseJs without the `Pulse.Core`.
+Another reason I turned away from PulseJs, besides the different visions, was the leak of organisation. 
+Some of my changes never got merged into the `master` branch. Why? Idk. But I am sure that it was not intentional.
+For instance, I fixed an annoying `usePulse` type issue, and 8 months later, it is still not merged into the `master`. 
+Why should I contribute if my changes, which fixed a problem I had, will never be in the release version.
+Now that I had my own State Management Framework, I had more control and adapted it to my needs.
+Over the time AgileTs evolved away from PulseJs with other visions and goals.
+During this time I rewrote and optimized all internal classes, created tests and created a documentation.
+Today AgileTs has only a similar syntax to PulseJs. Internal, it works entirely different.
+
+**Conclusion:** The idea of AgileTs is based on PulseJs, and I would have loved to continue working on PulseJs.
+But certain circumstances, such as a poor organization and different visions,
+have driven me to write my own State Manager based on the ground concept of PulseJs and MVVM frameworks.
 
 ## 🎉 Credits
 
 AgileTs is inspired by MVVM frameworks like [MobX](https://mobx.js.org/README.html)
 and [PulseJs](https://github.com/pulse-framework/pulse).
 
-## 💬 What others say
+## ❓ Something missing
 
-Actually nothing, yet. If you want to be the first one, don't mind tweeting what ever you think about AgileTs.
-But don't forget to tag [@AgileFramework](https://twitter.com/AgileFramework), otherwise we can't find your tweet.
+If you find issues with the documentation or have suggestions on how to improve the documentation or the project in
+general, please [file an issue](https://github.com/agile/agile-ts/issues) for us or join
+our [Discord Community](https://discord.gg/T9GzreAwPH).
 
 

docs/main/StyleGuide.md

@@ -17,6 +17,98 @@ Feel free to choose one of them and adapt it to your needs.
 
 ## 🚀 Inspiration 1
 
+In general, the `Style Guide 1` is intended for smaller applications, 
+since we put the whole business logic into one singe file called `store.ts`.
+If your applications scales and has many entities we don't recommend this Style Guide.
+It might get a mess to put everything into a singe file.
+
+#### 🖥 Example Application
+- [Simple Todo List](https://codesandbox.io/s/agilets-simple-todo-list-glmc4)
+
+In this Style-Guide, we have a so-called `store.ts` file at the top-level of our `src` folder, besides our UI-Components.
+The `store.ts` is thought to be the brain of our application and should contain all business logic
+and logic in general that isn't explicitly bound to a Component.
+This outsourcing of our logic makes our code more decoupled,
+portable, and above all easy testable.
+
+Below you see where our `store.ts` file might be located in the main tree.
+```js {3} title="MyApp"
+my-app
+├── src
+│   └── store.ts
+│   └── render
+.
+```
+We use the `store.ts` file of a simple TODO application to visually illustrate how it can be constructed.
+
+### 📝 store.ts
+
+In the `store.ts` file we instantiate the Agile Instance (`Agile`) and define all Agile Sub Instances (`MY_TODOS`).
+In addition, all actions (`updateTodo()`, `toogleTodo()`, ..) and if you are using Typescript, interfaces (`TodoInterface`) are located here.
+If you are wondering why in the hell should I write the global States uppercase. Well, it has a simple advantage.
+You can easily differentiate between global and local States.
+```ts
+import { Agile } from "@agile-ts/core";
+import reactIntegration from "@agile-ts/react";
+
+export interface TodoInterface {
+  id: number;
+  text: string;
+  done: boolean;
+}
+
+// Create Agile Instance
+const App = new Agile().integrate(reactIntegration);
+
+// Create Collection (A dynamic Array of States)
+export const MY_TODOS = App.createCollection<TodoInterface>({
+  key: "todos"
+}).persist(); // perist does store the Collection in the Local Storage
+
+export const updateTodo = (id: number, text: string): void => {
+  MY_TODOS.update(id, { text: text });
+};
+
+export const toggleTodo = (id: number): void => {
+  MY_TODOS.update(id, { done: true });
+};
+
+export const removeTodo = (id: number): void => {
+  MY_TODOS.remove(id).everywhere();
+};
+
+export const addTodo = (text: string): void => {
+  MY_TODOS.collect(
+    {
+      id: randomId(),
+      text: text,
+      done: false
+    }
+  );
+};
+```
+
+
+
+<br />
+
+---
+
+<br />
+
+
+
+## 🚀 Inspiration 2
+
+At the first look the `Style Guide 2` might look very boiler-plate-ey.
+Every entity has its own directory, with a bunch of files.
+True, for small applications like a simple singe page application, this might be an overkill.
+But for enterprise applications that have planned to scale, its definitely worth a try.
+
+####  🖥 ExampleApplications
+Currently, no open source application is using this `Style Guide`. 
+But I have worked with it in a private repo, and I love it.
+
 In this Style-Guide, we have a so-called `core` at the top-level of our `src` folder, besides our UI-Components.
 The `core` is thought to be the brain of our application and should contain all business logic
 and logic in general that isn't explicitly bound to a Component.
@@ -32,7 +124,7 @@ my-app
 .
 ```
 We use the `core` of a simple TODO application to visually illustrate how such a `core` can be constructed.
-Our todo application has two main [Entities](#📁-entities), that AgileTs should handle.
+Our todo application has two main [Entities](#📁-entities), which a State Manager like AgileTs should handle.
 The **User** and of course, the **TODO-Item**. These two parts are mapped in our `core`.
 ```js title="TodoList-Core"
 core
@@ -55,7 +147,7 @@ core
 |── index.ts
 .
 ```
-Each property you find above in the folder structure of the `TodoList-Core`, is described in detail below ⬇️.
+Each property you find in the above folder structure of the `TodoList-Core`, is described in detail below ⬇️.
 
 ## 📁 api
 
@@ -65,8 +157,8 @@ If your application doesn't need to communicate to a `backend,` you can entirely
 
 ### 📝 index.ts
 
-To make rest calls possible, we initialize our api class in the `index` file in the `api` folder.
-The defined API Instance will be mainly used in the [route](#-routets) file of an [Entity](#-entities),
+To make rest calls possible, we initialize our api class in the `index` file of the `api` folder.
+The defined API Instance will be mainly used in the [route](#-routets) files of the [Entities](#-entities),
 where we define the single routes to the backend.
 ```ts title="index.ts"
 import API from '@agile-ts/api';
@@ -89,7 +181,7 @@ Each `Entity` manages its Data separately by doing rest calls or mutating States
 structured, readable and improves maintainability.
 
 **For example:** <br />
-The _User Entity_ should only treat the user's whole logic and shouldn't do rest calls, for instance, for the _Todo Entity_.
+The _User Entity_ should only treat the user's whole logic and shouldn't do rest calls, for instance, for the _Todo-Item Entity_.
 
 ### 📝 index.ts
 
@@ -111,15 +203,15 @@ export default {
 
 ### 📝 .action.ts
 
-Here all actions of the Entity are listed.
+All actions of the Entity are defined in this file.
 In general, an action modifies the `State`, makes rest calls (through the functions provided by the [route.ts](#-routets) file), 
 and computes some values if necessary.
 In principle, actions always happen in response to an event. For example, if the add todo button got clicked.
 Therefore, they should be called after action sounding names. For instance `createTodo`, `removeTodo`.
 
 **For example:** <br />
 The creation of a Todo-Item in the UI-Layer triggers the `addTodo()` action, 
-which then mutates our TodoItems State and makes a rest call to add the todo to our backend.
+which then mutates our TodoItems State and makes a rest call to the backend.
 
 ```ts title="todo.action.ts in 📁todo"
 import {TodoInterface} from './todo.interface';
@@ -141,7 +233,9 @@ 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) or bound to a Component in the UI-Layer.
+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.
+If you are wondering why in the hell should I write the global States uppercase. Well, it has a simple advantage.
+You can easily differentiate between global and local States.
 ```ts title="todo.controller.ts in 📁todo"
 import {App} from '../../app';
 import {TodoInterface} from './todo.interface';
@@ -165,7 +259,7 @@ The `interface` section can be ignored by non [Typescript](https://www.typescrip
 :::
 
 If you are a [Typescript](https://www.typescriptlang.org/) user, you properly want to create some interfaces for your Entity.
-These interfaces belonging to this Entity should be defined here.
+These interfaces belonging to the Entity should be defined here.
 
 **For example** <br />
 In case of the TODO-Entity, it contains the `TodoInterface`.
@@ -181,8 +275,8 @@ export interface TodoInterface {
 
 ### 📝 .route.ts
 
-In order to communicate to our server, we have to create [rest calls](https://en.wikipedia.org/wiki/Representational_state_transfer).
-For better maintainability, these rest calls are outsourced from the [action.ts](#-actionts) and provided by this section in function shape.
+In order to communicate to our backend, we have to create [rest calls](https://en.wikipedia.org/wiki/Representational_state_transfer).
+For better maintainability, these rest calls are outsourced from the [action.ts](#-actionts) file and provided by this section in function shape.
 These route functions should only be used in the [action.ts](#-actionts) of the Entity.
 It's not recommended calling them from outside the corresponding Entity.
 ```ts title="todo.route.ts in 📁todo"
@@ -213,7 +307,7 @@ States, Collections, etc. can then be created with the help of this instance.
 import {Agile} from "@agile-ts/core";
 import reactIntegration from "@agile-ts/react";
 
-export const App = new Agile({logJobs: true}).use(reactIntegration);
+export const App = new Agile({logJobs: true}).integrate(reactIntegration);
 ```
 
 ## 📝 index.ts
@@ -247,11 +341,11 @@ export default core;
 
 
 
-## 🚀 Inspiration 2
+## 🚀 Inspiration 3
 
 :::note
 
-There is no second Inspiration yet, but feel free to share your own 'style guide' inspiration here. Every contribution
+There is no third Inspiration yet, but feel free to share your own 'style guide' inspiration here. Every contribution
 is welcome. :D
 
 :::