stoxydeprecated

Stoxy is a state management tool used for easy access to frequently used data without the hassle of template strings.

Usage no npm install needed!

<script type="module">
  import stoxy from 'https://cdn.skypack.dev/stoxy';
</script>

README

Stoxy Logo

🗂️ Stoxy

Stoxy is a state management API equipped with Web Components for ease of use.

Stoxy allows you to easily handle, persist and update data in your DOM without the weight of a framework.

❓ How

Stoxy utilizes the browser's tooling with respect to your computer's memory.

Stoxy stores the data in a in-browser Database called IndexedDB, only keeping the latest 5 accessed objects in-memory for faster access.

Stoxy utilizes a promise-based use flow making it really easy to asynchronously read and write from the storage.

If your browser doesn't support IndexedDB, there's no need to worry. Stoxy recognizes these cases automatically, and opts out of using it and utilizes a in-memory system only.

❓ Why

When writing websites with dynamic content, the markdown can easily become a spaghetti of plain text and Javascript escaped variables inside a template literal. like:

<h1>Hello, ${user.name}</h1>
<p>Your profile has accumulated ${user.viewCount} views</p>
<p>Top 3 visitors on your page:</p>
<ul>
    ${
        user.topVisitors.map(vis => `<li>${vis}</li>`);
    }
</ul>

With Stoxy, the same markdown could be created without being in the same context as the data with:

<stoxy-object key="user" prefix="u.">
    <h1>Hello, u.name</h1>
    <p>Your profile has accumulated u.viewCount views</p>
    <p>Top 3 visitors on your page:</p>
    <ul>
        <stoxy-repeat key="user.topVisitors" id="vis">
            <li>vis</li>
        </stoxy-repeat>
    </ul>
</stoxy-object>

Dynamic content inside Stoxy Elements updates when the data does. Update once, DOM updates everywhere.

🔔 Reactivity

Stoxy is a reactive state management system, meaning that when you update the data in Stoxy with the write command, all of the elements using that object will automatically update their content in the DOM.

No more need for flowing data around the whole system.

write('user', newData);

// Triggers update in the element below

<stoxy-object key="user" prefix="u.">
    <p>Hello, u.name</p>
</stoxy-object>;

Stoxy will not update any element which's data didn't change, enhancing the performance greatly.

_ Only the DOM elements which had their data changed will be updated _

Stoxy Demo

🧰 Installation

npm install stoxy

Usage

Data Storage

Write
import { write } from 'stoxy';

const userData = {
    name: 'Matsuuu',
    favoriteLanguage: 'Javascript',
    knownLanguages: ['Java', 'Javascript', 'C#'],
};

write('user', userData);
Read
import { read } from 'stoxy';

const userData = await read('user');
console.log(userData);
/*
 *  {
 *    name: 'Matsuuu',
 *    favoriteLanguage: 'Javascript',
 *    knownLanguages: ['Java', 'Javascript', 'C#'],
 *  }
 */

Usage in DOM

Stoxy ships with 3 Web Components to ease the usage:

Stoxy Object

Stoxy object is the most common use case: you want to access multiple keys of a certain object within your DOM.

<stoxy-object key="user-data" prefix="u.">
    <h1>Hello, World!</h1>

    <p>My name is: u.name, and I'm from u.country.countryName (u.country.countryCode).</p>
    <p>My favorite animal is: u.favoriteAnimal</p>

    <p>My favorite programming languages are:</p>
    <stoxy-repeat key="stoxy-user-demo.favoriteProgrammingLanguages" id="progLang">
        <li>progLang</li>
    </stoxy-repeat>
</stoxy-object>

Which then renders as

<stoxy-object key="stoxy-user-demo" prefix="u." ready="">
    <h1>Hello, World!</h1>

    <p>My name is: Matsu, and I'm from Finland (FI).</p>
    <p>My favorite animal is: Cats</p>

    <p>My favorite programming languages are:</p>
    <stoxy-repeat key="stoxy-user-demo.favoriteProgrammingLanguages" id="progLang">
        <li>Javascript</li>

        <li>Java</li>

        <li>C++</li>
    </stoxy-repeat>
</stoxy-object>

Stoxy Object can access data in as low levels as needed. As seen in the example, you can access subobjects like user.country.countryCode

Stoxy elements can also be nested without any stress.

Stoxy Repeat

A lot of the time when you have content, you end up having lists of data you want to display.

In these cases you can use the Stoxy Repeat Web Component

<p>My favorite games:</p>
<stoxy-repeat key="user.favoriteGames" id="game">
    <div class="game-entry">
        <p>Name: game.name</p>
        <p>Genre: game.genre</p>
        <p>Rating: game.rating</p>
    </div>
</stoxy-repeat>

Which will then result in the following HTML

<p>My favorite games:</p>
<stoxy-repeat key="user.favoriteGames" id="game">
    <div class="game-entry">
        <p>Name: StarCraft 2</p>
        <p>Genre: RTS</p>
        <p>Rating: 4.7/5</p>
    </div>
    <div class="game-entry">
        <p>Name: World of Warcraft</p>
        <p>Genre: MMORPG</p>
        <p>Rating: 4.0/5</p>
    </div>
</stoxy-repeat>

Stoxy String

The final Web Component is for when you just want to use a single string from your object

<h2>Hello, <stoxy-string>user.name</stoxy-string>!</h2>

Future plans

  • Pub-Sub system for programmatic reactions

Have something you want Stoxy to support? Create an issue!