scribaX

A simple state repository and manager for JavaScript applications

Why scribaX?

Because we don't need a massive amount of software to address a given request. Sometimes a little piece of code will do the trick.

Goals

Data Integrity - A single source of truth (SSOT)
Predictability - All the views have access to the same value and type of any given data.
Enforced security - Data can only be mutated invoking a known action and not by unknown sources or actions.
Easy of use - Subscribe to multiple or single property change in the store and customize how your application responds to data changes.

Components & Data Flow

The data flow is always unidirectional and all shareable data will be persisted in the store.

The only way to update data is by explicitly executing a self provided method called "commit".

Every time a "commit" action is performed, the store will notify this update one and only to the "notifier" function.

Within the "notifier" function, you can customize how your application "reacts" to this event.

The Store

scribaX manages only #2 kind of data: "state" data and "computed" data.

A sample store would be something like this:

const store = new Store({
        state: {
                cards: [],
                engine: false,
                name: null,
                helmet: 0,
                round: 0
        },
        schema: {
                helmet: 'number',
                name: 'string',
                engine: 'boolean',
                cards: 'object',
                round: 'number'
        },
        computed: {
                Comp1: {
                        code: function () {
                                return this.helmet + this.round ;
                        }
                }
        }
});

Plain and simple, "state" data is the one you update(mutate) by invoking the "commit" method:

store.commit('round',4);

And "computed" data is derived state based on store state, by defining "getters" in the store. In the above example:

function () {
  return this.helmet + this.round ;
}

You can replace the store's root state at any given time by invoking the "replaceState" method:

var data = JSON.parse(document.querySelector('initialState').getAttribute('__APP_INITIAL_STATE__'));
store.replaceState(data);

With "replaceState", it throws out the current state and replaces it with only what you provide.
Use this only for "state hydration" purposes.

Validation Rules

In order to achieve predictability scribaX performs schema validation during updates.

To specify validation rules when creating a new store use the "schema" property:

        schema: {
                helmet: 'number',
                name: 'string',
                engine: 'boolean',
                cards: 'object',
                round: 'number'
        }

Reactions to updates

Simply connect a custom function to the self provided "notify" method, and that's it.

store.notify('notifier');

You can customize your "notifier" function as you wish:

function notifier(args) {
  const el = document.getElementById('commit');
  el.insertAdjacentHTML('beforeend',`<p>${args.state} now: ${args.value}</p>`);

  const elStore = document.getElementById('store');
  elStore.innerHTML = `round: ${store.round} win: ${store.win} helmet: ${store.helmet} myComp: ${store.Comp1}`;
}

What functionalites are not present here?

Reducers / Mutations: The goal of this project is to provide "only data" and not mixing "data" with "business logic".
Setters: A setter would be just another "business logic" snippet.
Actions: Again, more bussiness logic.

Installation via CDN

<script src="https://unpkg.com/scribax"></script>

Demos

Reach me out

Acknowledgements

Thanks to the incredible people who maintain projects such as Redux, Vuex and MobX et. al.

And thanks to all the people who share their knowledge and experiences freely on the Internet, you guys inspired this project.

License

MIT

smartITNinja/scribaX