LogoLogo
  • Introduction
  • Intro
    • 🚀Getting Started
    • Key Characteristics
    • Fundamentals
    • Motivation
  • Fundamentals
    • 💾Units
      • BoolUnit
      • NumUnit
      • StringUnit
      • DictUnit
      • ListUnit
      • GenericUnit
    • 🤝Systems
      • AsyncSystem
      • Custom AsyncSystem
    • 🤜Action
    • 📦Cluster
  • 🔨Utilities
    • Stream
    • Selection
  • Integrations
    • Angular
    • React
      • useObservable Hook
      • useUnit Hook
  • 📖Guides
    • Configuration
    • Nesting
    • Events
    • Typings
    • Caching
    • Persistence
    • Immutability
    • Freeze and Mute
    • Development Environment
    • General Guidelines
  • More
    • 👀Examples
    • ✍️Articles
Powered by GitBook
On this page
  • Installation
  • Prerequisite
  • Prelude
  • Fundamentals
  • Playground
  • Do I need ActiveJS?

Was this helpful?

  1. Intro

Getting Started

PreviousIntroductionNextKey Characteristics

Last updated 4 years ago

Was this helpful?

Installation

If you don't have already, you'll need to install it first npm install rxjs, and then

npm i @activejs/core

If you don't have access to a module bundler, here's the . (not needed for frameworks like Angular, React, Vue etc.)

Prerequisite

ActiveJS assumes a prior understanding of . Some understanding of RxJS can also be helpful, but the basic knowledge of Observables should be enough. or might help you get up to speed.

Prelude

Imagine a variable that can only be assigned a value of a particular data type, let's say only number, and when we change the value of this variable, it gets broadcasted to observers, while we also keep past values in the cache to be able to undo/redo. That's basically what an ActiveJS allows us to do, and the one that only allows numbers is called .

At the heart of ActiveJS are these reactive data structures called, that emulate JavaScript's native data structures. Units behave almost exactly like a native data structure would, while the actual value is kept encapsulated inside the Unit. Units are observable and every operation and mutation is broadcasted.

Quick Example:

Let's take a simple and comparable example of implementing a counter. We'd use a for the counter since we expect the value to always be a number.

// initialize a NumUnit.
const counterUnit = new NumUnit({initialValue: 6});
// NumUnit has default initial value 0,
// you can also provide an initial value.
// observe the Unit for current and future values
counterUnit.subscribe(value => console.log(value)) 
// logs 6 immediately and will log future values

// or, directly access the current value
console.log(counterUnit.value()); // logs 6
// define two pure functions that produce a new value
const increment = value => value + 1; 
const decrement = value => value - 1;

// now we'll use the above pure functions as value-producers,
// the dispatch method expects a value or a value-producer-function
counterUnit.dispatch(increment); // makes the value 7
counterUnit.dispatch(decrement); // makes the value 6 again

// or just directly pass the value
counterUnit.dispatch(7); // makes the value 7

// try an invalid value
counterUnit.dispatch('20'); // NumUnit will ignore this invalid string value
// so the value is still 7

ActiveJS Units are cache-enabled, and by default, every Unit caches two values. When you navigate through the cache, the cache stays intact, while the value changes. This makes it very easy to travel back in time and then go back to the future.

// to recap, the list of cached values is [6, 7] at the moment
// and the current value is 7

// go back to the previous value
counterUnit.goBack(); // now value is 6 (cache isn't affected)

// go forward to the next value
counterUnit.goForward(); // now value is 7 (cache isn't affected)

// clear the value
counterUnit.clearValue(); // now value is 0 (the default value for NumUnit)

// reset the value
counterUnit.resetValue(); // now value is 6 again (the initial-value)

There are even more built-in things that a Unit can do, but this is the crux of it.

Fundamentals

Other constructs within ActiveJS build on the core concept of independent storage Units and work together to create a complete workflow for advanced use cases.

ActiveJS is made up of four fundamental constructs, visualized with their core components in the diagram below. Each one of them plays a different yet crucial role in the complete state-management lifecycle.

    • Units are cache-enabled, and based on JavaScript's native data structures like boolean, string or array.

Do I need ActiveJS?

As much as we'd like to say YES, we don't want you to get into something that you later realize is not for you.

That being said, If you're coming from a Flux background you'll see that it's different yet somehow familiar and easier. If you feel like Flux based state management solutions are overkill, you'll love it. If you're happy with RxJS, you'll be able to do more by doing less. If your single-page app is not using Observables, it can give you wings (maybe).

So, do you need it? The answer is we are not sure, it can definitely help you in one way or another, you can start small without much commitment, give it a go and see how it pans out.

Try it on . Or, let's also try some built-in methods.

are independent, reactive data structures. Units are responsible for holding the state of your App.

For example, is an elaborate array like construct which is also an Observable and implements all the Array.prototype methods in a way that, any mutation caused by these methods, emits a new array with the mutations applied to it.

All available Units are , , , , , and .

encompass a certain number of in a specialized way and implement inter-relationships among these Units to pertain to a specific task. For now, there's only one of its kind.

helps with async APIs like XHR or fetch, it makes sharing their state very easy.

are meant to represent unique events as Observables. Action is an RxJS Subject like construct, with extra features like replay on demand. Actions are useful, but not essential to start using ActiveJS.

is literally a cluster, a wrapper, that can be used to create a group of , , as well as . It creates a master Observable of the combined value of its members, and also provides direct static access to the combined value.

To jump right into the action without writing any code, you can try out , it might give you some more perspective, and help understand the most important ActiveJS constructs , and .

🚀
RxJS
UMD bundle link
Observables
This official guide
this primer
Unit
NumUnit
Units
NumUnit
StackBlitz
Units
ListUnit
BoolUnit
NumUnit
StringUnit
ListUnit
DictUnit
GenericUnit
Systems
Units
AsyncSystem
Actions
Cluster
Units
Systems
Actions
Clusters
Playground
this visual playground
Units
Systems
Bird's eye view of ActiveJS constructs.