@e-scape/store NPM

Store

Library for storing values and subscribing to their changes.

Creation

The Store takes absolutely any value as its first parameter.

import { Store } from '@e-scape/store'

const myStore = new Store('hello world')

Subscription

Subscribing to changes in the store is done by passing a callback to the subscribe method. This callback will be added to the call queue, and after the store value changes, the callback will be invoked.

myStore.subscribe(() => {
  console.log('Store value has changed')
})

When called, the callback receives the current and previous values.

myStore.subscribe(({ current, previous }) => {
  console.log(current, previous)
})

By default, callbacks will be invoked in the order of subscription to the store. You can change this by passing a second parameter with a value other than undefined.

// Will be called third
myStore.subscribe(callback, 20)
// Will be called second
myStore.subscribe(callback, 0)
// Will be called first
myStore.subscribe(callback, -10)

Unsubscription

Subscribing to the store returns a function that can be called to unsubscribe from the store.

const unsubscribe = myStore.subscribe(callback)

unsubscribe()

Alternatively, you can call the unsubscribe method.

const callback = () => {}

myStore.subscribe(callback)

myStore.unsubscribe(callback)

Removing all subscriptions

myStore.close()

Resetting the value to the initial one

Calling the reset method sets the current value of the store to the value passed to its constructor during creation.

myStore.reset()

Current value

To see the current value of the store outside of subscription, you can access the current getter.

console.log(myStore.current)

To change the current value of the store, assign a new value to the current setter.

myStore.current = 123

Previous value

To see the previous value of the store outside of subscription, you can access the previous getter. Initially, this value is undefined.

console.log(myStore.previous)

Initial value

console.log(myStore.initial)

Types of stores

Derived

Takes any store as the first parameter and a callback as the second parameter, which reacts to changes in the passed store. The value returned from this callback will be set as the current value of the derived store.

import { Store, Derivative } from '@e-scape/store'

const numberStore = new Store(2)
const doubleNumberStore = new Derivative(numberStore, (v) => v * 2)

doubleNumberStore.subscribe(({ current }) => {
  console.log(current) // 4
})

Derived from an array

Same as the Derivative store but only accepts stores whose values are arrays.

import { Store, Derivatives } from '@e-scape/store'

const numberStore = new Store([1, 2, 3])
const doubleNumberStore = new Derivatives(numberStore, (v) => v * 2)

doubleNumberStore.subscribe(({ current }) => {
  console.log(current) // [2, 4, 6]
})

Resource

Takes the initial value as the first parameter and a function as the second parameter that returns a Promise. The data obtained from the Promise will be set as the current value.

import { Resource } from '@e-scape/store'

const todoStore = new Resource(null, async () => {
  const response = await fetch('https://jsonplaceholder.typicode.com/todos/1')
  const data = await response.json()

  return data
})

todoStore.isPending.subscribe(({ current }) => {
  console.log(current)
})

todoStore.subscribe(({ current }) => {
  console.log(current)
})

To fetch the data again, call the refetch method.

todoStore.refetch()

Store parameters

All stores accept the following optional object as the last parameter:

equalityCheck

By default, all values are compared using ===, and if the values are equal, subscribers will not be notified that a new value has been assigned. You can change this by providing a custom comparison function:

const store = new Store(0, {
  equalityCheck: (currentValue, newValue) => currentValue === newValue,
})

passport

All stores with a specified name in passport will be added to the store registry:

new Store(0, {
  passport: {
    name: 'My Store',
  },
})

For example, this property is actively used by the tweaker library to create a GUI that controls values in stores.

Store Registry

Purpose

he main task of the store registry is to quickly replace all store values with some previously saved state, for example, from tweaker.

The entire setup for the project will look like this:

import { Store, storeRegistry } from '@e-scape/store'
import state from 'state.json'

// Load and save the state
storeRegistry.loadState(state)

// Now all stores will be initialized with values from the state loaded above, not the values passed in the constructor.
const store = new Store(0, {
  passport: {
    name: 'My Store',
  },
})

How to add to the registry

All stores with a specified name in passport will be added to the registry as soon as the first subscription occurs, and will be removed from the registry if there are no more subscriptions to the store.

import { Store, storeRegistry } from '@e-scape/store'

const store = new Store(0, {
  passport: {
    name: 'My Store',
  },
})

store.subscribe(() => {})

console.log(storeRegistry.getState())

Registry Methods and Properties

storeRegistry.getState()

Returns the current state of all named stores.

storeRegistry.resetState()

Resets the values of all named stores to their initial values.

storeRegistry.saveState()

Saves the state of all named stores to localStorage. By default, the save is done under the name store-state. You can change this by setting a value for the data-project attribute on the <html> tag:

<html data-project="my-project"></html>

Now, in localStorage, the state will be saved under the name my-project-store-state.

storeRegistry.loadState(string | StoreRegistryState | undefinded)

If no parameter is passed, it loads data from localStorage. If a string is passed, it will try to parse it into a StorageState object, and if a StoreRegistryState is passed, it takes the data directly from it and updates all current named