Quick, zero-setup, persistent State management with Stoxy

With so many state management solutions flowing around the web, I've noticed that a lot of them focus on the current state and just forget about everything after the user navigates away from the page.

With us going even more mobile each day, PWA's getting more used across the board, having a offline-first experience can be crucial for your web app.

This coupled with the fact that the current most used state management systems seem to require you to either put in the time to learn the API or stick to a certain library like React, I decided to write up my own state management system with framework agnosticism in mind.

So without further ado, introducing: Stoxy.

With Stoxy, I had a few key pillars I wanted to build it around:

• Up and running from the first API call
• Simple, extendable and easy to learn API
• Framework agnostic
• Offline ready from the start.

With these pillars in mind, Stoxy was built and with it, a few Web Components to ship with it to support the library. The components are completely opt-in, and not required for basic state management

In this post we'll be going through the basic functions of Stoxy to manage state

Read & Write

The most basic state management operations would be reading from state and writing to it.

In many state management systems, you would need to first create a reducer of sorts to handle the state changes, and then give your state a default value and then modify it.

With Stoxy you're up and running with just a single line of code

import { write } from '@stoxy/core';

write("counter", 0);

Stoxy supports complex objects too of course, so you could set, say the whole logged in user's data to state

const userData = {
    userName: "Stoxy",
    customerPoints: 10,
    shoppingCart: [
        { id: 123, name: "Flaming hot cheetos" }
    ],
    shoppingHistory: {
        latestProducts: [
            { id: 555, name: "Doritos" },
            { id: 958, name: "Pringles" }
        ]
    }
};

write("userData", userData);

It's just that simple. We get the data stored in the state, and we're able to read it from anywhere.

Reading data is just as simple. It functions around a Promise-based system, which allows for nice and intuitive workflows.

import { read } from '@stoxy/core';

read('userData').then(userData => {
    console.log("User name: " + userData.userName);
});

The reasoning for using promises comes from the use of IndexedDB to persist the data, which is an asynchronous API.

Next let's look into updating the state

Update

With a state system, you usually want to update the state object without having to explicitly read it and then write it. For this the Stoxy core ships a nice and fast update function.

import { update } from '@stoxy/core';

update('counter', counter => (counter += 1));

The update function takes a delegate as a parameter, and applies the delegate to the state object.

As you might realize, this allows for quite a lot of manuvering.

Say we wanted to add points to our userData above, we could simply run

update('userData.customerPoints', points => (points += 100));

And the state of the userData would be updated accordingly.

All state objects and their properties in Stoxy can be directly accessed

This means that if you wanted to get only the shopping cart of the user, you could with the same way you would when accessing a normal javascript object

read("userData.shoppingCart").then(shoppingCart=> {
    shoppingCart.map(item => console.log(item));
});

Write operations function the same way

write("userData.userName", "Foobar");

Persistence

As the final section of the first part of this series, I'll quickly go over how to implement the persistence I promised in the title.

Say we wanted to persist the userData state object so that we would have it saved up on our next visit to the page, even before we call the API to get it. We would need to only write one line of code to implement that.

At the start of our application, we would declare that we want to persist said state key with

import { persistKey } from '@stoxy/core';

persistKey('userData');

And we're all set! Stoxy takes all control after that to persist the data into the IndexedDB for later use in this browsing session or the next.

Final word

This is the first part of a multi part post series in which I go through the features of Stoxy. I hope you enjoyed the first part and stay tuned for the next ones.

If you want to read more about stoxy, you can:

• Read the documentation and guides at Stoxy.dev
• Check out the code and star the GitHub Repo
• Reach out to me on Twitter

Until next time!

You can read the second part of Stoxy introduction here:

Quick, zero-setup, persistent State management with Stoxy Part 2:

Matsuuu ・ Mar 22 '21 ・ 3 min read