state-ref

Universal state management library that can be easily integrated into UI libraries

• README_KR

StateRef is a state management library focused on data immutability.

It combines proxies and the functional programming lens pattern to efficiently and safely access and modify deeply structured data.

It provides more direct and fine-grained state management compared to other types of state management libraries.

It is also designed for easy integration with other UI libraries. We provide code snippets for connecting with React, Preact, Vue, Svelte, Solid, and Lithent , and users can also create their own connection snippets.

• Table of Contents

  • Acknowledgements

  • Basic Usage

  • Usage with React (Same for Preact)

  • Usage with Svelte

  • Usage with Vue

  • Usage with Solid

  • Usage with Lithent

  • Supports Flux-like State Management

  • createComputed

  • combinewatch

  • npm

  • test

Acknowledgements

I would like to extend my gratitude to the following people and projects:

• Juho Vepsäläinen: Thank you for the insightful interview and featuring me on your blog. Your work and contributions to the JavaScript community have been a great source of inspiration.

Basic Usage

The basic principle is that the subscription function only reacts to values retrieved through .value, and when a value is assigned with .value=, the subscription function is triggered if the value is already subscribed.

Below is a simple usage example.

import { createStore } from "state-ref";
import type { StateRefStore, Watch } from "state-ref";

type Info = { age: number; house: { color: string; floor: number }[] };
type People = { john: Info; brown: Info; sara: Info };

// const watch = createStore<number>(3); // Primitive types can also be used easily."
const watch = createStore<People>({
    // Type: Watch<People>
    john: {
        age: 20,
        house: [
            { color: "red", floor: 5 },
            { color: "red", floor: 5 },
        ],
    },
    brown: { age: 26, house: [{ color: "red", floor: 5 }] },
    sara: { age: 26, house: [{ color: "red", floor: 5 }] },
});

// Get references
const stateRef = watch();
// Type: StateRefStore<People>

// Using value.
console.log(stateRef.john.house[1].color.value);

// Change value.
stateRef.john.house[1].color.value = "yellow";

// To subscribe
watch((stateRef) => {
    console.log(
        "Changed John's Second House Color",
        stateRef.john.house[1].color.value
    );
});

When you define the initial state using the createStore function, it returns watch, which helps you subscribe to or reference the values.

You can register a subscription function with watch that triggers when the value changes.

The first argument passed to the subscription function is stateRef, and by using the value property of stateRef, you can retrieve the value. The subscription function will only execute when the referenced value changes.

Here is another example:

const stateRef = watch((stateRef) => {
    console.log(
        "Changed John's Second House Color",
        stateRef.john.house[1].color.value
    );
});

const {
    john: {
        house: [, { color: colorhandleref }],
    },
} = stateRef;

stateRef.john.house[1].color.value = "blue";
colorHandleRef.value = "green";

The watch function returns a stateRef. Through the returned stateRef, you can change or reference values outside of the subscription function.

By chaining directly from the stateRef and assigning a value to the .value of the part you want to change, the original data in the store will be reflected with copyOnWrite applied.

You can see in the example that you can use the destructuring operator to directly extract a reference to a specific state and use it.

If you simply read the .value from the returned stateRef, any changes to that value will automatically trigger the subscription function."

If you want to avoid automatic updates, you can use a new stateRef that is not connected to the subscription function.

const otherStateRef = watch();

If you want to cancel the subscription, use abortController as shown in the example below.

const abortController = new AbortController();

watch((stateRef) => {
    console.log(
        "Changed John's Second House Color",
        stateRef.john.house[1].color.value
    );

    return abortController.signal;
});

abortController.abort(); // run abort

Primitive types like numbers or strings can also be handled easily. Here's how:

const watch = createStore<number>(3);

watch((stateRef) => {
    console.log(
        "Changed Privitive Number",
        stateRef.value
    );
});

Usage with React (Same for Preact)

It can be easily integrated with other UI libraries, and below is an example using React.

profileStore.ts

Create the store and pass the watch to connectReact to create a state that can be used in components.

import { connectReact } from "@stateref/connect-react";
// import { connectPreact } from "@stateref/connect-preact"; // for Preact
import { createStore } from "state-ref";

type Info = { age: number; house: { color: string; floor: number }[] };
type People = { john: Info; brown: Info; sara: Info };

const watch = createStore<People>({
    john: {
        age: 20,
        house: [
            { color: "red", floor: 5 },
            { color: "red", floor: 5 },
        ],
    },
    brown: { age: 26, house: [{ color: "red", floor: 5 }] },
    sara: { age: 26, house: [{ color: "red", floor: 5 }] },
});

export const useProfileStore = connectReact(watch);

UserComponent.tsx

import { useProfileStore } from 'profileStore';

function UserComponent() {
  const {
    john: { age: ageRef },
  } = useProfileStore();

  const increaseAge = () => {
    ageRef.value += 1;
  };

  return (
    <button onClick={increaseAge}>
        john's age: {ageRef.value}
    </button>;
  );
}

In the example above, useProfileStore directly returns stateRef, allowing easy access to values and modification through copyOnWrite.

You can create your own custom connection pattern by referring to the connectReact implementation code.

Usage with Svelte

While React and Preact's useProfile function directly returns stateRef, SvelteConnect returns Svelte's built-in reactive Writable synchronized with the stateRef state value.

Below is a usage example.

profileStore.ts

import { connectSvelte } from "@stateref/connect-svelte";
// ... same as React example
export const useProfileStore = connectSvelte(watch);

UserComponent.svelte

<script lang="ts">
import { useProfileStore } from 'profileStore';
const age = useProfileStore<number>(stateRef => stateRef.john.age);

function handleClick() {
  age.update(n => n + 1);
}
</script>

<button on:click={handleClick}>
    john's age is {$age}
</button>

If Writable needs to reference and modify an object from the store, the copyable function is available to assist with copyOnWrite.

import { copyable } from "state-ref";
const profileObj = useProfileRef(stateRef => stateRef);

function handleClick() {
   profileObj.update(n => copyable(n).john.age.writeCopy(n.john.age + 1));
}

You can customize it by referring to the connectSvelte implementation code.

Usage with Vue

In Vue, the store is connected and returns Vue's built-in reactive Reactive synchronized with the stateRef state value.

You can customize it by referring to the connectVue implementation code.

profileStore.ts

import { connectVue } from "@stateref/connect-vue";
// ... same as React example
export const useProfileStore = connectVue(watch);

UserComponent.vue

<script setup lang="ts">
import { useProfileStore } from 'profileStore';

const age = useProfileStore<number>(store => store.john.age);

const incrementFromProfile = () => {
  // This looks the same as stateRef, but it's a Reactive value in Vue.
  age.value += 1;
};
</script>

<template>
  <button @click="incrementFromProfile">
    john's age is: {{ age.value }}
  </button>
</template>

Usage with Solid

Solid does not directly use stateRef but returns Solid's built-in reactive Signal synchronized with the stateRef state value.

You can customize it by referring to the connectSolid implementation code.

profileStore.ts

import { connectSolid } from "@stateref/connect-solid";
// ... same as React example
export const useProfileStore = connectSolid(watch);

UserComponent.tsx

import { useProfileStore } from 'profileStore';

function UserComponent() {
    const [age, setAge] = useProfileStore<number>(store => store.john.age);

    function increaseAge() {
      setAge(age => age + 1);
    }

    return (
      <button onClick={increaseAge}>
          john's age: {age()}
      </button>;
    );
}

If Signal needs to reference and modify an object from the store, the copyable function is available to assist with copyOnWrite.

import { copyable } from "state-ref";
const [profileObj, setProfileObj] = useProfileStore(stateRef => stateRef);

function handleClick() {
   setProfileObj(n => copyable(n).john.age.writeCopy(n.john.age + 1));
}

Usage with Lithent

profileStore.ts

In Lithent, you can use it directly with watch without needing a connect code.

import { createStore } from "state-ref";

type Info = { age: number; house: { color: string; floor: number }[] };
type People = { john: Info; brown: Info; sara: Info };

export const watch = createStore<People>({
    john: {
        age: 20,
        house: [
            { color: "red", floor: 5 },
            { color: "red", floor: 5 },
        ],
    },
    brown: { age: 26, house: [{ color: "red", floor: 5 }] },
    sara: { age: 26, house: [{ color: "red", floor: 5 }] },
});

UserComponent.tsx

import { mount, h } from 'lithent';
import { watch } from 'profileStore';

const UserComponent = mount(r => {
    const {
        john: { age: ageRef },
    } = watch(r);

    const increaseAge = () => {
        ageRef.value += 1;
    };

    return () => (
        <button onClick={increaseAge}>
            john's age: {ageRef.value}
        </button>;
    );
});

Supports Flux-like State Management

If users prefer to manage state using a centralized store pattern, state-ref provides flexibility with the createStoreManualSync function. This mode makes it easier to implement centralized patterns like Flux.

Below is a simple Flux-like example using createStoreManualSync with React.

profileStore

createStoreManualSync returns updateRef and sync, along with watch.

In the default mode, values can be modified through the references created by watch. However, in manualSync mode, values cannot be modified via watch.

To update values, you must use updateRef. To propagate the changes to subscribed code (and trigger subscription callbacks), you can manually execute the sync function at your desired time.

import { createStoreManualSync } from "state-ref";

type Info = { age: number; house: { color: string; floor: number }[] };
type People = { john: Info; brown: Info; sara: Info };

const { watch, updateRef, sync } = createStoreManualSync<People>({
    john: { age: 20, house: [ { color: "red", floor: 5 }] },
    brown: { age: 26, house: [{ color: "red", floor: 5 }] },
});

export const useProfileStore = connectReact(watch);

// Action to change John's age
export const changeJohnAge = (newAge: number) => {
    updateRef.john.age.value = newAge;
    sync();
};

// Action to change Brown's first house info
export const changeBrownFirstHouseInfo = (
    firstHouseInfo = { color: 'blue', floor: 7 }
) => {
    updateRef.brown.house[0].value = firstHouseInfo;
    sync();
};

UserComponent.tsx

Values can only be updated through actions created by profileStore. Any attempt to modify the values in other ways will result in an error.

import { useProfileStore, changeJohnAge } from 'profileStore';

function UserComponent() {
  // The stateRef received via watch or the values received via connect are for reference only
  // (direct modification is not allowed).
  const {
    john: { age: ageRef },
  } = useProfileStore();

  const increaseAge = () => {
    // An error occurs if you attempt to modify 'ageRef' directly.
    // ageRef.value += 1; // 

    // You must modify the reference through the action's updateRef.
    // Afterward, the subscribed code will synchronize via the sync function
    // (triggering subscription callbacks).
    changeJohnAge(ageRef.value + 1);
  };

  return (
    <button onClick={increaseAge}>
        john's age: {ageRef.value}
    </button>;
  );
}

createComputed

createComputed is a helper function that combines multiple watches to produce a new computed (derived) value, and executes a specified callback function whenever that computed value changes.

A Watch created with createComputed can be used just like any other watch, including in integrations such as connectReact or connectPreact.

Below is a simple usage example.

import { createStore, createComputed } from "state-ref";
import type { StateRefStore, Watch } from "state-ref";

type Info = { age: number; house: { color: string; floor: number }[] };

const watch1 = createStore<Info>(
    { age: 10, house: [{ color: "blue", floor: 7 }] },
);
const watch2 = createStore<number>(20);

const computedWatch = creatComputed<[Watch<Info>, Watch<number>], number>([watch1, watch2], ([ref1, ref2]) => {
    return ref1.age.value + ref2.value;
});


// To subscribe
computedWatch((stateRef) => {
    console.log(
        "Changed Computed Value",
        stateRef.value
    );
});

// Change value
const computedRef = watch2();
computedRef.value = 30;

// Connect another ui library
const useComputedValue = connectReact(computedWatch);

combineWatch

combineWatch is a helper function that observes multiple Watch instances together and produces a new Watch that delivers their combined values as a tuple-like structure.

Unlike createComputed, which produces a single derived value, combineWatch focuses on grouping multiple watches so you can react to changes from any of them in a single subscription. When combined multiple times, the structure naturally nests, allowing you to build hierarchical watch compositions.

Basic Usage

import { createStore, combineWatch } from "state-ref";

const countWatch = createStore<number>(100);
const textWatch = createStore<string>("hello");

// Combine multiple watches into one
const combinedCountTextWatch = combineWatch([countWatch, textWatch] as const);

combinedCountTextWatch(([countRef, textRef], isFirst) => {
  console.log("Combined Watches:", countRef.value, textRef.value, isFirst);
});

// Update a watch
const countRef = countWatch();
countRef.value = 200; 
// → triggers callback with [200, "hello"]

Nested Combination

You can nest combineWatch to observe more complex structures:

const countWatch = createStore<number>(100);
const textWatch = createStore<string>("hello");
const toggleWatch = createStore<boolean>(false);

// Combine countWatch and textWatch
const combinedCountTextWatch = combineWatch([countWatch, textWatch] as const);

// Nest the combined watch with toggleWatch
const combinedAllWatch = combineWatch([combinedCountTextWatch, toggleWatch] as const);

combinedAllWatch(([countTextRef, toggleRef], isFirst) => {
  const [countRef, textRef] = countTextRef;
  console.log("Nested Watches:", countRef.value, textRef.value, toggleRef.value, isFirst);
});

When to Use

• Use createComputed when you need a single derived value (e.g., number, string, object).
• Use combineWatch when you need to observe multiple watches together and handle their values as a structured group.

npm

• state-ref
• connect-react
• connect-preact
• connect-solid
• connect-svelte
• connect-vue
• lithent

test

Plugins must be build before they can be tested.

pnpm install
pnpm build
pnpm test