snap-state

state management in a snap 👌. (under 1KB)

Usage no npm install needed!

<script type="module">
  import snapState from 'https://cdn.skypack.dev/snap-state';
</script>

README

snap-state

state management in a snap 👌. (under 1KB)

Motivation

You probably don't always need to use Redux or React Context API and wrapping your Consumer inside your Provider, or is it the other way around? 🤷‍♂️

For simpler applications you might just want a K.I.S.S. approach 🤔(did he just called me stupid?)

How does it work?

This library was done with React and Preact in mind, but if you're using your own thing good on you. I got you fam! Snap state is a little bit like a singleton with event dispatching. Everytime you set or change a property on the state, components listening to those events will be notified of changes.

So in the simplest form you can have

// 1) import the state
import { State } from 'snap-state';

// 2) define a property
State.test = 123;

This property State.test will now be available from anywhere in your application. You just need to import the State class. For example:

import { State } from 'snap-state';
console.log(State.test); // returns 123;

If you want to do anything every time the prop State.test changes, you can do something like:

import { State, onSnapState } from 'snap-state';

onSnapState(['test'], ({ key, value }) => {
    console.log('prop of key', key, 'changed to', value);
});

// change value of test to a random number.
State.test = Math.random();

// change value of test to a string
State.test = 'abc';

// change value of test to null
State.test = null;

The onSnapState method receives an array of props so you can listen to changes on multiple properties at the same time. It also returns a unsubscribe method that you should use when you want to unsubscribe from future events. The full example below:

import { State, onSnapState } from 'snap-state';

const unsubscribe = onSnapState(['test'], ({ key, value }) => {
    console.log('prop of key', key, 'changed to', value);
});

// change value of test to a random number
State.test = Math.random();

// stops the subscription to prop changes
unsubscribe();

// changing the prop now will work as expected, but the `onSnapState` callback isn't called because we unsubscribe from it.
State.test = 'abc';
State.test = null;

React

You can create your state somewhere (well, maybe at the application level to look profesh)! Once that's out of the way, you can change it from anywhere in your app regardless of component hierarchy. 🎉🎉🎉

Now every time the state changes, any component subscribing to changes will be updated.

For example, lets say we want to create a property that stores a "theme", how does that look? Well, just create your initial state:

import { State } from 'snap-state';

State.theme = 'dark';

Now you just need to subscribe to changes to that particular prop. How? However you want to! Some examples below.

Hooks

I know you're fancy, so if functional programming is your thing, check out the useSnapState hook.

import { useSnapState } from 'snap-state';

function Example() {
    const state = useSnapState(['theme']);
    return (
        <p>the theme is {state.theme}</p>
    );
}

Every time you change State.theme anywhere on your app, your component will be updated.

High Order Components

If you're more into class based components you can decorate your component with withSnapState HOC.

import React, { Component } from 'react';
import { withSnapState } from 'snap-state';

class Example extends Component {
    render() {
        return (
            <p>the theme is {this.props.theme}</p>
        );
    }
}

export default withSnapState(['theme'])(Example);

Vanilla

What if you're building a custom WebGL application that makes a cat fly through space? What if you want to store all the planets your Space Cat visits?

import { State, onSnapState } from 'snap-state';

// subscribe to changes on the "planet" prop
const unsubscribe = onSnapState(['planet'], ({ value }) => {
    console.log(`Space cat just went pass ${value}.`);
});

// change your state and look at that amazing callback.
State.planet = 'mars';

// when your cat reaches another galaxy and you feel its time to let it go
// you can unsubscribe from further changes
unsubscribe();