SpringType: st-state

Nano library for client-side state management and persistency

Purpose

This is an exremely tiny, yet powerful library for global state management. st-state can also save and load state from/to sessionStorage and localStorage.

Features

• ✅ Abstracts the HTML5 local/sessionStorage API
• ✅ Tiny: 202 bytes (best, brotli) - 324 bytes (worst, umd, gz)
• ✅ Zero dependencies
• ✅ First class TypeScript support
• ✅ 100% Unit Test coverage

How to

This is how using st-state looks like:

import { tsx, render, Ref } from 'springtype';
import { $ } from 'st-query';
import { store } from 'st-state';

const RANDOM_NUMBERS = 'randomNumbers';

const RandomNumbersList = () => {
  return <fragment>
    {state.get(RANDOM_NUMBERS).map((randomNumber) => <p>{randomNumber}</p>)}
  </fragment>
}

const App = () => {

  const randomNumberListRef: Ref = {};

  // remember randomNumbers generated before
  const defaultRandomNumbers = store.load(RANDOM_NUMBERS, []);

  // current randomNumbers state, possibly initialized by remembered ones
  const randomNumbers: Array<number> = store.get(RANDOM_NUMBERS);

  const onGenerateRandomNumber = () => {

    // updating the state locally
    randomNumbers.push(Math.random());

    // setting the state gobally
    store.set(RANDOM_NUMBERS, randomNumbers);

    // also persisting the state for re-visits
    store.save(RANDOM_NUMBERS);

    // re-render the UI
    $(randomNumberListRef.current).html(<RandomNumbersList />);
  }

  return (
    <fragment>
      <h3>Random numbers:</h3>

      <div ref={randomNumberListRef}>
        <RandomNumbersList />
      </div>

      <button onClick={onGenerateRandomNumber}>
        Generate random number
      </button>
    </fragment>
  );
};
render(<App />);

API

The following contract is made between the webapp and st-state:

export interface State {
  [key: string]: any;
}

export interface API {
  state: State;
  get(key: string, defaultValue?: any): any;
  set(key: string, value: any): API;
  load(key: string, defaultValue?: any): API;
  save(key: string): API;
  loadForSession(key: string, defaultValue?: any): API;
  saveForSession(key: string): API;
}

Backers

Thank you so much for supporting us financially! 🙏🏻😎🥳👍

Tom

Maintainers

st-state is brought to you by:

Aron Homberg

Contributing

Please help out to make this project even better and see your name added to the list of our CONTRIBUTORS.md 🎉