avem/readme.md

An easy state manager for all enviroments.

# Avem

<img src="/img/AvemLogoV1.png" align="right"
     title="Avem Logo By Ben Kincaid" width="450" height="375">

Avem is a dependency-free state management library for Javascript applications. For 
projects big or small, it asssists with managing your applications state and DOM 
operations in response to state change.

Avem was developed with vanilla Javascript in mind, but is also compatible with
React, Angular, Vue, and many other user interface libraries.


## How It Works

Avem is a basic library - it creates a state storage object with methods attached to it to help with 
changing and updating the state of an application or component. 

For example, Avem can be used for managing the state of a forms inputs. Every time a user focuses out
of the input, the state can be updated with the value of said input. This can be useful when submitting
AJAX form requests for example.

Another common use-case of Avem would be with API calls which need to retrieve and store data. Avem
can be used to update the user interface everytime the states `events` property is updated, for example. 


## Usage
Avem was created to provide state management for any website functionality/component, regardless of the scale. 

How Avem works is every new `Avem` instance creates a new 'state' object. This can be a global application state,
or specific to a component, depending on the scope it is called and used in. This state handler has methods attached 
to it to assist with mutating, reading, and updating the state and its attached components. 

When initializing an `Avem` instance, it expects only two paramaters: your mutations object, and an initial state.

heres a simple example of initializing an `Avem` instance for handling a mailing list form submission.

```javascript
function formHandler() {
    // Our mutation methods allow us to take in our previous state and apply our dispatched data to it. 
    const mutations = {
        setEmailInput: function(stateCopy, payload) {
            stateCopy.emailInput = payload;
            return stateCopy;
        }
    }
    
    // Our initial state defines our component/applications state on initializiation.
    const formInitialState = {
        emailInput: null,
    }
    
    // define our Avem instance as our components storage
    this.store = new Avem(formMutations, formInitialState);

    // subscribe a callback function to our states 'emailInput' value. This means that
    // every time the 'emailInput' value in our state is changed, this.emailInputChanged
    // will fire.
    this.store.subscribe('emailInput', this.emailInputChanged);

    // get reference to our email text input
    this.emailInput = document.querySelector('.email-input');

    // call this.HandleInputChange whenver the input is focused in or out of.
    this.emailInput.addEventListener('blur', this.handleInputChange.bind(this));
}


// Fired when this.emailInput is 'blur'd 
formHandler.prototype.handleInputChange = function(evt) {
    let inputValue = this.emailInput.value;
    // fire the setEmailInput mutation and pass in the payload(in this case, the new value from the 
    // text field).
    this.store.dispatch('setEmailInput', inputValue);
}

// fire this function after 'emailInput' value in state is mutated, and pass through the new binded value and new state.
formHandler.prototype.emailInputChanged = function(bindedValue, newState) {
    console.log(bindedValue);
}
```