Introduction to the Firefly Semantics Slice Reactive Object Store | Guide

Ole Ersoy
Feb - 08  -  5 min

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.