@xeito/store v0.3.5

Xeito Store

This is the Router library for Xeito Framework. Provides a simple yet powerful router for web applications built with Xeito.

To find the full documentation and more links go to the main README file.

Table of Contents

• Xeito Store
• Table of Contents
• Exports
  • Classes
  • Interfaces
• What is a store?
• WriteStore
  • Updater function
• ReadStore
• Mixed Store

Exports

Classes

• WriteStore: A store that can be written to and read from.
• ReadStore: A store that can only be read from.
• MixedStore: A store that depends on other stores.

Interfaces

• Updater: A function that can be passed to a store to update its value.
• Subscription: Object returned from a store's subscribe method. Contains a unsubscribe method to unsubscribe from the store.

What is a store?

At its core, a store is a class that holds a value that changes over time, allowing you to subscribe to it. Stores allow the state of your application to be shared across multiple components and services or even regular Typescript modules.

There are three main types of stores, each with a different purpose, but a very similar API.

WriteStore

The most basic form of a store is a WriteStore, which allows us to write to it and notify subscribers of the change. Let's create a simple store that holds a number:

import { WriteStore } from '@xeito/store';

const store = new WriteStore(0);

Now we can subscribe to the store and get notified when the value changes:

store.subscribe((value) => {
  console.log(value);
});

Stores are fully typed, so you can rewrite the above code as:

import { WriteStore } from '@xeito/store';

const store: WriteStore<number> = new WriteStore(0);

store.subscribe((value: number) => {
  console.log(value);
});

We can now write to the store and notify subscribers:

store.set(1); // Every subscriber will be notified with the new value

We can also get the current value of a store without subscribing to it:

const value = store.value;

Note: Reading the value of a store like this will not create a subscription and it won't be notified of any changes.

Updater function

We can also pass an updater function when creating a WriteStore, this function will be called with the current value of the store and the set method. This allows us to transform the value and write it to the store in a single operation:

const store = new WriteStore(0, (value, set) => {
  set(value + 1);
});

Updater functions can return return a value or a cleanup function. If a cleanup function is returned, it will be called when the store is destroyed.

const store = new WriteStore(0, (value, set) => {
  const interval = setInterval(() => {
    set(value + 1);
  }, 1000);

  return () => {
    clearInterval(interval);
  };
});

If the updater returns a value, it will be set as the value of the store.

const store = new WriteStore(0, (value, set) => {
  return value + 1;
});

// This can also be written as:
const store = new WriteStore(0, (value, set) => value + 1);

The updater function can be changed after the store is created by using the update method:

store.update((value, set) => {
  return value + 1;
});

ReadStore

A ReadStore is a store that can only be read from, it can't be written to. This is useful when you want to share a value across multiple components or services, but you don't want them to be able to change it. ReadStore therefore only has a subscribe method and a value property and relies on the updater function to change its value.

import { ReadStore } from '@xeito/store';

const store = new ReadStore(0);

store.subscribe((value) => {
  console.log(value); // Logs 0
});

This can be useful for tasks like fetching data from an API and sharing it across multiple components without them being able to change it:

import { ReadStore } from '@xeito/store';

const store = new ReadStore(0, async (value, set) => {
  const response = await fetch('https://example.com/api');
  const data = await response.json();

  set(data);
});

store.subscribe((value) => {
  console.log(value); // Logs the data from the API
});

Mixed Store

A MixedStore is a type of store that depends on other stores to calculate its value, it can be read from and written to. This is useful when you need to merge data from multiple stores or compute a value when any of the store passed as a dependency changes.

import { WriteStore, MixedStore } from '@xeito/store';

const count = new WriteStore(0);

const store = new MixedStore(count, (value, set) => {
  return value + 1;
});

store.subscribe((value) => {
  console.log(value); // Logs 1
});

As you can see, the MixedStore accepts a store as its first argument, this store will be used to calculate the value of the MixedStore, the updater function will be called with the value of the store and the set method. A third argument can be provided, this argument will be the initial value of the MixedStore:

const store = new MixedStore(count, (value, set) => {
  return value + 1;
}, 0); // The initial value of the store will be 0

If we need to use multiple stores to calculate the value of the MixedStore, we can pass them as an array:

const value1 = new WriteStore('Hello');
const value2 = new WriteStore('World');

const store = new MixedStore([value1, value2], (value, set) => {
  return value.join(' ');
});

store.subscribe((value) => {
  console.log(value); // Logs 'Hello World'
});

value1.set('Goodbye'); // Logs 'Goodbye World' in the subscriber