AgileTs

Global State and Logic Framework

👋 Introduction

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.

Some straightforward syntax examples:

• Mutate and Check States with simple Functions
  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
  MY_STATE.persist("storage-key")
• Create a reactive Array of States
  const MY_COLLECTION = App.createCollection();

  MY_COLLECTION.collect({id: 1, name: "Frank"});

  MY_COLLECTION.collect({id: 2, name: "Dieter"});
• Compute State depending on other States
  const MY_INTRODUCTION = App.createComputed(() => {

  return `Hello I am '${MY_NAME.vale}' and I use ${MY_STATE_MANAGER.value} for State Management.`;

  });

🤸‍ Flexible

• Works in nearly any UI-Layer. Check here if your preferred Framework is supported too.
• Surly behaves with the workflow which suits you best. No need for reducers, actions, ..
• Has 0 external dependencies

⛳️ Centralize

AgileTs is designed to take all business logic out of UI-Components and put them in a central place often called core. The benefit of keeping logic separate to UI-Components is to make your code more decoupled, portable and above all easily testable.

🎯 Easy to Use

Learn the powerful tools of AgileTs in a short amount of time. An excellent place to start are our Quick Start Guides, or if you don't like following any tutorial, jump straight into our Example section.

⏳ Quick Example

Instead of talking too much about the benefits of AgileTs, let's start programming.

😎 Our first State

// -- core.js ------------------------------------------

// Let's start by creating an Instance of AgileTs

const App = new Agile();

// Now we are able to create our first State 😃

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 rerenders

const myFirstState = useAgile(MY_FIRST_STATE); // returns value of State ("Hello Stranger!")

To find out more, check out our Quick Start Guides.

⛳️ Sandbox

Test AgileTs yourself. It's only one click away. Just select your preferred Framework below.

• React
• React-Native
• Vue (coming soon)
• Angular (coming soon)

More examples can be found in the Example 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. We recommend using AgileTs to manage global States and their logic at a central place.

👨‍🏫 Learn AgileTs

We have a variety of resources available to help you learn AgileTs. An excellent place to start are our Quick Start Guides, where you learn the basics about how to use AgileTs in a specific Framework. After knowing the ground concept of AgileTs, we recommend checking out the Style Guides. 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. In case you have any further questions don't hesitate to join our Community Discord.

🏢 Structure of Documentation

📁 AgileTs

You are currently in the AgileTs section, which serves as source for general topics like the Style Guide or an Installation Guide.

📁 Quick Start

The quick start section is all about how to get AgileTs up and running in different environments like React or Vue. In each Quick Start Guide the basics of some AgileTs classes (State, ..) are covered too.

📁 Packages

In the packages section all the AgileTs packages are listed. For instance the core and the api package. If you click on one of them, it will reveal you an Introduction about the package, an Installation Guide and all its features. In case of the core package you find the State and Collection docs in the Features Section. Be aware that ⚠️ WIP isn't an actual package. It is meant to separate packages that are currently work in progress and not ready for the outer world.

📁 Examples

Some interactive examples can be found in the example section.

📁 Interfaces

Without any context this section might be useless to you. As the name suggests, it's all about typescript interfaces of 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.

💬 What others say

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, 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. 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 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 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. 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 and PulseJs.

❓ Something missing

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 for us or join our Discord Community.