Dragonbinder

1kb progressive state management library inspired by Vuex.

Features

Immutable state.

Immutable state. Getters.

Getters. Mutations.

Mutations. Actions.

Actions. Event listeners.

Event listeners. Nested modules.

Nested modules. Plugin system.

Table of Contents

Install

You can get this library as a Node.js module available through the npm registry:

// With npm $ npm install dragonbinder // With yarn $ yarn add dragonbinder

Or you can use it standalone in the browser with: <script src="https://cdn.jsdelivr.net/npm/dragonbinder"></script>

Use

const Dragonbinder = require ( ' dragonbinder ' ) ; const store = new Dragonbinder ( { state : { count : 0 } , mutations : { increment ( state ) { state . count ++ } } } ) ; store . commit ( ' increment ' ) ; console . log ( store . state . count )

State

Dragonbinder use Proxies to create a state as a "single source of truth" which cannot be changed unless you commit a mutation. This means that you cannot delete, modify or add a property directly. This allow us to keep track of all changes we made to the state.

If you don't provide an initial state by the state property Dragonbinder will create one.

const store = new Dragonbinder ( { state : { count : 0 } , mutations : { addProperty ( state , value ) { state . hello = ' world ' ; } , modifyProperty ( state ) { state . count ++ } , removeProperty ( state ) { delete state . count ; } } } ) ; store . state . hello = ' world ' ; store . state . count ++ ; delete state . count ; store . commit ( ' addProperty ' ) ; store . commit ( ' modifyProperty ' ) ; store . commit ( ' removeProperty ' ) ;

Also, if you want to avoid singletons to reuse your initial store definition, you can declare its state as a factory function.

const myStoreDefinition = { state ( ) { return { count : 1 } } , mutations : { increment ( state , payload ) { state . count = state . count + payload ; } } } ; const store1 = new Dragonbinder ( myStoreDefinition ) ; const store2 = new Dragonbinder ( myStoreDefinition ) ; store1 . commit ( ' increment ' , 5 ) ; store2 . commit ( ' increment ' , 3 ) ; console . log ( store1 . state . count ) ; console . log ( store2 . state . count ) ;

Getters

As with Vue, with Dragonbinder you can create getters to create computed properties based on the state. This getters will receive the state as first argument and all other getters as second.

const store = new Dragonbinder ( { state : { todos : [ { content : ' First ' , completed : false } , { content : ' Second ' , completed : true } ] } , getters : { completed ( state ) { return state . todos . filter ( item => item . completed ) ; } , completedCount ( state , getters ) { return getters . completed . length ; } } } ) ; console . log ( store . getters . completed ) ; console . log ( store . getters . completedCount ) ;

Mutations

Mutations are the only way to change the state and you must consider the next points when designing mutations.

Following the Vuex pattern, mutations must be synchronous.

Unlike many other libraries you can pass any number of arguments to a mutation.

With Dragonbinder the state is deep frozen using Object.freeze to prevent direct changes. So, when you are changing the state by using a mutation, you can add, modify or delete only first level properties, second level properties will be read only.

const store = new Dragonbinder ( { state : { hello : { name : ' John Doe ' } } , mutations : { changeNameError ( state , payload ) { state . hello . name = payload ; } , changeNameOk ( state , payload ) { state . hello = { ... state . hello , name : payload } ; } , changeNameTo ( state , ... args ) { state . hello = { ... state . hello , name : args . join ( ' ' ) } ; } } } ) ; store . commit ( ' changeNameError ' , ' Jane Doe ' ) ; store . commit ( ' changeNameOk ' , ' Jane Doe ' ) ; store . commit ( ' changeNameTo ' , ' Jane ' , ' Doe ' ) ;

Actions

If you need to handle async functions you must use actions. And actions will always return a promise as result of calling them.

const store = new Dragonbinder ( { state : { count : 0 } , mutations : { increment ( state ) { state . count ++ } } , actions : { increment ( state ) { return new Promise ( ( resolve ) => { setTimeout ( ( ) => { store . commit ( ' increment ' ) ; resolve ( ) ; } , 1000 ) ; } ) } } } ) ; store . dispatch ( ' increment ' ) . then ( ( ) => console . log ( store . state . count ) ) ;

Events

You can register/unregister callbacks to events.

const store = new Dragonbinder ( { state : { count : 0 } , mutations : { increment ( state ) { state . count ++ } } } ) ; let namedListener = ( store , prop , newVal , oldVal ) => console . log ( ` The property ${ prop } was changed from ${ oldVal } to ${ newVal } ` ) ; store . on ( ' set ' , namedListener ) ; let removeAnonymousListener = store . on ( ' set ' , ( ) => console . log ( ' Anonymous listener triggered ' ) ) ; store . commit ( ' increment ' ) ; store . off ( ' set ' , namedListener ) ; removeAnonymousListener ( ) ; store . commit ( ' increment ' ) ;

Event types

All events receive the store instance as the first argument.

Event name Its called when Arguments received by place addlistener An event listener is added Event name | Listener added removelistener An event listener is removed Event name | Listener removed set A property of the state is added or modified, also triggered when a module is registered Property name | New value | Old value delete A property of the state is deleted, also triggered when a module is unregistered Property name | Old value beforecommit Commit method called and before apply the mutation Mutation name | (...) Arguments passed to the mutation commit Commit method called and after apply the mutation Mutation name | (...) Arguments passed to the mutation beforedispatch Dispatch method called and before apply the action Action name | (...) Arguments passed to the action dispatch Dispatch method called and after apply the action Action name | (...) Arguments passed to the action getter A getter is called Getter name | Value of the getter plugin A plugin is added Plugin added | (...) Options passed to the plugin registerModule A module is registered Namespace registered | Module definition | Store created with the definition unregisterModule A module is unregistered Namespace unregistered | Store created with the definition

Nested modules

Like Vuex, Dragonbinder allows you to divide your store into modules and each module can contain its own store definition including more nested modules.

const moduleA = { state : { ... } , mutations : { ... } , actions : { ... } , getters : { ... } } const moduleB = { state : { ... } , mutations : { ... } , actions : { ... } , getters : { ... } modules : { a : moduleA } } const store = new Dragonbinder ( { modules : { b : moduleB } } ) ; console . log ( store . state . b ) console . log ( store . state [ ' b.a ' ] )

Also, after the store is created you can register/unregister modules with the registerModule and unregisterModule methods.

Consider that when you unregister a module, only its initial nested modules will be unregistered with it.

const moduleA = { state : { ... } , mutations : { ... } , actions : { ... } , getters : { ... } } const moduleB = { state : { ... } , mutations : { ... } , actions : { ... } , getters : { ... } , modules : { a : moduleA } } const moduleC = { state : { ... } , mutations : { ... } , actions : { ... } , getters : { ... } } const store = new Dragonbinder ( ) ; store . registerModule ( ' b ' , moduleB ) ; store . registerModule ( ' b.c ' , moduleC ) ; console . log ( store . state . b ) console . log ( store . state [ ' b.a ' ] ) console . log ( store . state [ ' b.c ' ] ) store . unregisterModule ( ' b ' ) ; console . log ( store . state . b ) console . log ( store . state [ ' b.a ' ] ) console . log ( store . state [ ' b.c ' ] )

Local and root state

Each module will behave like any other store, but, unlike Vuex, all Dragonbinder modules are namespaced by design. There is no option to add root mutations, actions or getters with a module. So, when you call a module mutation, action or getter, you need to supply its full namespace.

The first argument for mutations and getters will continue to be the local state, and with actions the first argument will be the local context/store.

Getters will get the root state and root getters as the third and fourth arguments.

Actions will access the root context by the rootStore property of the local context.

const moduleA = { state : { hello : ' world ' } , mutations : { sayHello ( state , payload ) { state . hello = payload ; } } , actions : { change ( store , payload ) { store . commit ( ' sayHello ' , payload ) ; store . rootStore . commit ( ' increment ' ) ; } } , getters : { hello ( state , getters , rootState , rootGetters ) { return ` You have said hello ${ rootState . count } times to ${ state . hello } ` ; } } } ; const store = new Dragonbinder ( { state : { count : 0 } , mutations : { increment ( state ) { state . count ++ ; } } , modules : { a : moduleA } } ) ; store . dispatch ( ' a.change ' , ' John Doe ' ) ; console . log ( store . getters [ ' a.hello ' ] ) ; console . log ( store . state . count ) console . log ( store . state . a . hello )

Plugin system

Dragonbinder comes with a simple but powerfull plugin system. You can extend its core functionality or change it completely by making use of plugins.

Using plugins

let store = new Dragonbinder ( ) ; store . use ( myPlugin , ... options ) ;

Developing plugins

A Dragonbinder plugin is a module that exports a single function that will be called with the store instance as first argument and optionally with the passed options if any.

const Dragonbinder = require ( ' dragonbinder ' ) ; const myPlugin = ( store , ... options ) => { Dragonbinder . myGlobalMethod = function ( ) { } ; Dragonbinder . fn . myPrototypeMethod = function ( ) { } ; store . myLocalMethod = function ( ) { } ; } ;

API

Check the docs at: https://masquerade-circus.github.io/dragonbinder/?api

Contributing

Check the contributing guide at: https://masquerade-circus.github.io/dragonbinder/?content=contributing

Development, Build and Tests

Use yarn dev to watch and compile the library on every change to it.

to watch and compile the library on every change to it. Use yarn build to build the library.

to build the library. Use yarn test to run tests only once.

to run tests only once. Use yarn dev:test to run the tests watching changes to library and tests.

to run the tests watching changes to library and tests. Use yarn dev:test:nyc to run the tests watching changes and get the test coverage at last.

to run the tests watching changes and get the test coverage at last. Use yarn docs to build the documentation.

to build the documentation. Use yarn docs:watch to watch and rebuild the documentation on every change to the library or the md files.

to watch and rebuild the documentation on every change to the library or the md files. Use yarn docs:serve to see the generated documentation locally.

Legal

Author: Masquerade Circus. License Apache-2.0