Introduction
The Firefly Semantics Slice Object Store ( OStore
) contains observable key value pairs.
Use it in single page, web, mobile, and server side applications for reactive state management.
In this guide we will go through it’s capabilities.
You may also wish to follow along on Youtube.
Stackblitz
To follow along in this guide, open a new Stackblitz Typescript project and add @fireflysemantics/slice
to the dependencies.
Notice the peer dependencies that are automatically pulled in.
This is a completed version. Feel free to fork it or add the snippets as we are going along.
Store Initialization
In order to illustrate how the Firefly Semantics Slice Object Store works we will store 2 values.
One for name
which will be a string
value and a count
which will be a number
.
We use an OStoreStart
configuration instance to initialize our store like this:
interface ISTART extends KeyObsValueReset {
name: ObsValueReset;
count: ObsValueReset;
}
const START: OStoreStart = {
name: { value: 'Calvin', reset: 'Calvin' },
count: { value: 0, reset: 100000 },
};
let OS: OStore<ISTART> = new OStore(START);
Notice that for both name
and count
we have provide an initial value
and a reset
value.
If we call reset
on the store the reseet
values will be used to reinitialize the store.
IDE Auto Completion and Observable References
You'll notice that we created an ISTART
interface.
We initialize the Object Store using this interface in order to get autocomplete in our IDE.
The interface
values are typed ObsValueReset
and that interface is defined like this:
/**
* OStore Key Value Reset
*/
export interface ObsValueReset {
value:any
reset?:any
obs?: Observable<any>}
And so each initialization object passed to the store contains the initial value
, the reset
value, and an obs
refrence to an Observable<any>
that will emit the current value stored.
The obs
reference is set when the store is initialized by the store itself.
Snapshot Values
Once the store is initialized we can retrieve snapshots of keyed values like this:
//=====================================
// Take a snapshot of the count value
//=====================================
let countSnapshot = OS.snapshot(OS.S.count);
console.log(`The snapshot for the count key is: ${countSnapshot}`);
//=====================================
// Take a snapshot of the name value
//=====================================
let nameSnapshot = OS.snapshot(OS.S.name);
console.log(nameSnapshot);
Notice that we are using the OS.S
property to get auto completion for the keys that are contained in the store.
If we try to retrieve a value of a key that is not in the store then we get undefined
back:
//=====================================
// Use a key that has is not included
// in our initialization object.
//=====================================
let undefinedSnapshot = OS.snapshot('nothere');
console.log(`The snapshot for the nothere key is: ${undefinedSnapshot}`);
Subscribing to Store Observables
We can subscribe to the name
entry Observable
like this:
//=====================================
// Create an observable reference for the
// value keyed by name.
//=====================================
let name$: Observable<string> = OS.S.name.obs;
name$.subscribe((v) => console.log(`The value for name$ is ${v}`));
This will log the initial value contained in the store (Calvin
).
The process for subscribing the the count
Observable
is the same.
Updating Values
We can update name
from Calvin
to Suzie
like this:
OS.put(OS.S.name, 'Suzie');
Our name$
subscription will now log Suzie
as the name.
If we take a snapshot of the name
key we get Suzie
back:
//=====================================
// Get a snapshot of the
// updated name value
//=====================================
nameSnapshot = OS.snapshot(OS.S.name);
Resetting the Store
To reset the store call reset :
OS.reset()
After the reset the value of name
is now Calvin
again,
since that’s the value we configured reset to.
The value of count
is 10000
, since that is the configured reset
value for count
.
Deleting Values
We can delete the count
entry like this:
OS.delete(OS.S.count);
countSnapshot = OS.snapshot(OS.S.count);
console.log(`The deleted count value is ${countSnapshot}`);
Now when we log the value of the count
snapshot it logs undefined.
Checking if a Value Exists
We can can check whether the name entry exists using the exists
API call like this:
const exists = OS.exists(OS.S.count)
In this case exists will be false since we deleted the entry.
Entry Count
We check check the number of entries in the store like this:
OS.count()
Since we deleted name
we only have one value left in the store.
Clear
Run clear()
to delete all entries.
OS.clear()
Store Empty
We can check whether the store is empty using isEmpty()
:
OS.isEmpty()
And since we ran OS.clear()
the store is empty.
Summary
This has been a review of the features and API that the OStore supports. For a real world use case demonstraing the API check out Recreating the NgRx Demo App With the Firefly Semantics Slice State Manager.