fluxible-js
v6.1.5
Published
Smaller, faster, better state management system that supports asynchronicity and state persistence out of the box.
Downloads
1,396
Maintainers
Readme
Fluxible-JS v6
Smaller, faster, better event-driven state management architecture that supports asynchronicity and state persistence out of the box with no extra code.
Change logs
From 5.0.10, the changelogs on the project will be kept in CHANGELOG, which follows keepachangelog.
Demo
https://user-images.githubusercontent.com/21032419/139810793-ba875041-133e-4087-b80f-a523213e974d.mp4
Run me
git clone [email protected]:aprilmintacpineda/fluxible-js.git
yarn
yarn test
Install
yarn add fluxible-js
Usage
import { createStore } from 'fluxible-js';
const initialStore = {
user: null,
someOtherState: 'value',
anotherState: {
value: 'value'
}
};
const store = createStore({
initialStore,
persist: {
stringify: true,
syncStorage: {
setItem: (key, value) =>
window.localStorage.setItem(key, value as string),
getItem: key => window.localStorage.getItem(key)
},
restore: savedStore => ({
user: savedStore.user
})
}
});
Creating a store
import { createStore } from 'fluxible-js';
const initialStore = {
user: null,
someOtherState: 'value',
anotherState: {
value: 'value'
}
};
function initCallback () {
console.log('initialization complete');
}
const myStore = createStore({ initialStore }, initCallback);
createStore
function returns an instance of a store
that has variety of methods in it. You can access the store's current value by via myStore.store
. The 2nd parameter which is the initCallback
is optional function that gets called after the store has been initialized, this is especially useful when using async storage.
Persisting states
Persisting states allows you to save your application's state to a storage on the local device and then reuse those states the next time your application starts.
You need to tell fluxible-js
which storage to use, a storage API must have a getItem
and setItem
methods in them. An example of this would be window.localStorage or React-Async-Storage
You also need to tell fluxible-js
which states to persist, you can do this via the restore
callback function.
You need to tell fluxible-js
if the states has to be stringified (using JSON.stringify
) before being saved to the storage by specifying stringify
parameter.
Using asynchronous storage
setItem
and getItem
should be async or should return a promise, pretty much like with React-Native-Async-Storage. See example use-case with react-fluxible.
import { createStore } from 'fluxible-js';
const initialStore = {
token: null,
isLoggedIn: false,
initComplete: false
};
const store = createStore(
{
initialStore,
persist: {
stringify: true,
asyncStorage: {
setItem: (key, value) => someAsyncStorage.setItem(key, value as string), // value will be a string because `stringify` is set to `true`
getItem: key => someAsyncStorage.getItem(key) // has to be a string because `stringify` is set to true
}
restore: (savedStore) => {
return {
token: savedStore.token
};
}
}
},
() => {
store.updateStore({ initComplete: true });
}
);
Using synchronous storage
getItem
and setItem
should be sync, pretty much like with window.localStorage. See example use-case with react-fluxible.
import { createStore } from 'fluxible-js';
const initialStore = {
token: null,
isLoggedIn: false
};
const store = createStore({
initialStore,
persist: {
stringify: true,
syncStorage: {
setItem: (key, value) =>
window.localStorage.setItem(key, value as string), // value will be a string because `stringify` is set to `true`
getItem: key => window.localStorage.getItem(key) // has to be a string because `stringify` is set to true
},
restore: (savedStore) => {
return {
token: savedStore.token
};
}
}
});
If you don't care that much about typings, you can also just do:
syncStorage: window.localStorage as SyncStorage<typeof initialStore>,
or
syncStorage: ReactNativeAsyncStorage as AsyncStorage<typeof initialStore>,
Updating the store
You can update the store by doing:
import { createStore } from 'fluxible-js';
const initialStore = {
token: null,
isLoggedIn: false
};
const store = createStore({
initialStore,
persist: {
stringify: true,
syncStorage: {
setItem: (key, value) =>
window.localStorage.setItem(key, value as string),
getItem: key => window.localStorage.getItem(key)
},
restore: (savedStore) => {
return {
token: savedStore.token
};
}
}
});
// somewhere in your code
store.updateStore({
token: userToken,
isLoggedIn: true
});
Adding observers
Observers are callback functions that listen to certain changes in your store. Observers will be called AFTER the store has been updated and they will receive the updated store. You can add an observer by doing:
import { createStore } from ".";
const store = createStore({
initialStore: {
token: null
}
});
store.addObserver(
(store) => {
console.log(store.token);
// do something
},
// states that you want to watch changes for
['token']
);
Observers will only be called when the state they are watching changes, in this case, the observer is only watching token
, so this observer will only be called when you do store.updateStore({ token })
. This prevents unnecessary calls to all observers when other states changes.
Events
You can add, emit, and remove events in your store. You can take advantage of events to do various things in your applications such as updating the store.
Adding events
import { createStore } from ".";
const store = createStore({
initialStore: {
token: null
}
});
/**
* Event callbacks receive the:
* payload = passed on emitEvent
* store = the latest value of thes store
* event = the event that was emited, this is useful when using `addEvents`
*/
const unsubscribeCallback = store.addEvent('test-event', (payload, store, event) => {
console.log(payload, store, event);
// do something
});
// when you want to remove the event listener from the event
unsubscribeCallback();
There is also addEvents
in case you want an event listener to listen to multiple events.
const unsubscribeCallback = store.addEvents(
['event1', 'event2', 'event3'],
(payload, store, event) => {
console.log(payload, store, event);
// do something
}
);
// when you want to remove the event listener from the event
unsubscribeCallback();
Emitting an event
store.emitEvent(
'event1',
// optional: any value you want to pass to all the event listeners
{ value: 1 }
);
Emitting multiple events
store.emitEvents(
['anEvent', 'anotherEvent'],
// optional: any value you want to pass to all the event listeners
{ value: 1 }
);
Removing an event
store.removeEvent('event1');
Removing multiple events
store.removeEvents(['anEvent', 'anotherEvent']);
Migrating from v5 to v6
The only changes that occured in v6 are the following:
- Used TypeScript for better coding experience.
- Changed architecture to be more self-contained.
- No more
-1
returns.
Your code should still work with minimal changes. Here's how you can migrate real quick.
Create a file called globalStore.ts
, and add the following code:
import { createStore } from 'fluxible-js';
const initialStore = {
// ... your store values here
};
export default createStore({
initialStore,
// ... other options
});
Now, change all occurences of import { updateStore } from 'fluxible-js';
and other similar imports to import { updateStore } from 'globalStore';
.