UStor

Reactive Store Library

This library provides a powerful reactivity system for creating stateful objects using signals, integrated seamlessly into JavaScript objects and arrays. This library does not depend on any specific reactive library and can be used by any UI framework to manage and react to changes in state effectively.

Table of Contents

• Installation

• Setup

• API

  • store(values, proto)
  • is(value)
  • api.is
  • api.signal
  • api.get
  • api.set

• Usage

  • Basic Usage
  • Advanced Usage
  • Deeply Nested Structures
  • Arrays and Objects
  • Reactivity and Effects
    • state.$prop

• Integration with Solid.js, Preact Signals or any

Installation

To use this library, you can install it using npm or yarn:

1npm install ustor
2yarn add ustor

This library can be integrated with solid-js, @preact/signals-core, ulive, usignal, oby, sinuous any other libarary you can think of for managing reactive signals.

Setup

First, import the store function and the api object. You need to initialize api with your preferred signal implementation.

1import { store, api } from "./src";
2import { createSignal } from "solid-js";
3// import { signal } from '@preact/signals-core'; // 'usignal' 'ulive'
4
5// Solid.js setup
6api.signal = createSignal;
7api.get = (v) => v[0]();
8api.set = (signal, v) => signal[1](v);
9api.is = (v) =>
10	(Array.isArray(v) &&
11		typeof v[0] === "function" &&
12		typeof v[1] === "function") ||
13	v[0]?.name?.includes("readSignal");
14
15// @preact/signals-core, usignal or ulive setup
16api.signal = signal;
17api.get = (v) => v.value;
18api.set = (signal, v) => (signal.value = v);
19api.is = (v) => v?.peek;

API

store(values, proto)

The store function creates a stateful object that automatically converts properties into reactive signals.

• values: The initial values for the store, which can be objects, arrays, or primitives.
• proto: Optional prototype to set for the new store object.

The function returns a reactive store object that maintains the structure of the original values while adding reactivity.

is(value)

The is function checks if a given value is a reactive store instance.

• value: The value to check.

Returns true if the value is a reactive store, otherwise false.

api.is

The api.is function checks if a given value is a signal.

• value: The value to check.

Returns true if the value is a signal, otherwise false.

api.signal

The api.signal function is used to create a reactive signal.

• value: The initial value for the signal.

Returns a signal that can be used to create reactive state within the store.

api.get

The api.get function retrieves the current value of a signal.

• signal: The signal whose value you want to retrieve.

Returns the current value of the signal.

api.set

The api.set function updates the value of a signal.

• signal: The signal whose value you want to update.
• value: The new value to set.

Updates the signal with the provided value.

Usage

Basic Usage

1const s = store({ a: 1, b: 2 });
2console.log(s.a); // 1
3s.a = 5;
4console.log(s.a); // 5

You can use the store function to create a reactive state object. Assigning a new value to s.a will automatically trigger updates wherever s.a is used.

Advanced Usage

1const s = store({
2	a: 2,
3	b: 3,
4	get sum() {
5		return this.a + this.b;
6	},
7});
8
9console.log(s.sum); // 5
10s.a = 5;
11console.log(s.sum); // 8

Here, you can define getters that automatically compute derived state values, and these getters will update whenever the underlying signals change.

Deeply Nested Structures

The store function can also handle deeply nested objects, converting nested properties into reactive signals:

1const s = store({ nested: { deep: { value: 10 } } });
2const deepValue = s.nested.deep.value * 2;
3
4console.log(deepValue); // 20
5s.nested.deep.value = 15;
6console.log(s.nested.deep.value) * 2; // 30

Arrays and Objects

This library can handle arrays and objects seamlessly, automatically wrapping array elements with reactivity:

1const s = store({ list: [1, 2, 3] });
2const sum = s.list.reduce((acc, item) => acc + item, 0);
3
4console.log(sum); // 6
5s.list = [1, 5, 3];
6console.log(s.list.reduce((acc, item) => acc + item, 0)); // 9

Reactivity and Effects

The signal value trigger with effects to track dependencies and automatically re-run whenever dependencies change:

1const s = store({ a: 1 });
2let effectValue = 0;
3
4effect(() => {
5	effectValue = s.a * 2;
6});
7
8console.log(effectValue); // 2
9s.a = 4;
10console.log(effectValue); // 8

state.$prop

The $ properties are automatically generated for each property in the store. These $-prefixed properties contain the underlying signal, providing direct access to the signal itself, separate from the reactive value it holds. The $ properties are non-enumerable and are useful when you need to access or manipulate the signal directly, rather than the reactive value.

For example, if you have a store with a count property:

1const s = store({ count: 0 });
2console.log(s.count); // 0
3console.log(s.$count); // The underlying signal object

Integration with Solid.js, Preact Signals or any

This library can be used with Solid.js, Preact Signals, or any other UI framework to provide reactive signals.

To use Solid.js:

1import { createSignal } from "solid-js";
2
3api.signal = createSignal;
4api.get = (v) => v?.[0]();
5api.set = (signal, v) => signal?.[1](v);
6api.is = (v) =>
7	(Array.isArray(v) &&
8		typeof v[0] === "function" &&
9		typeof v[1] === "function") ||
10	v?.[0]?.name?.includes("readSignal");

To use Preact Signals, usignal, ulive, etc:

1import { signal } from "@preact/signals-core";
2
3api.signal = signal;
4api.get = (v) => v?.value;
5api.set = (signal, v) => (signal.value = v);
6api.is = (v) => v?.peek;

To use any signal library

1import ... from "...";
2
3api.signal = ...;
4api.get = ...;
5api.set = (signal, value) => ...;
6api.is = (v) => ...;
7
8const state = store({
9	count: 0
10});

The library provides a unified API to work with different reactive systems, allowing you to switch between Solid.js, Preact Signals, or any other UI framework easily.

License

This library is provided "as-is" under the MIT license. Feel free to use, modify, and distribute it in your projects.

Thanks and Inspiration

• dy