Minimal watchable state for your app

Install

npm install @watchable/store

# for optional features
npm install @watchable/store-react # React binding
npm install @watchable/store-follow # Business-logic binding
npm install @watchable/store-edit # Immer drafts

Summary

A @watchable/store Store maintains a immutably-typed reference to an (array or object) state with intuitive utilities for wiring up ui components and business logic.

See the Medium article

Import OR Require

import { createStore } from "@watchable/store"; // esm
const { createStore } = require("@watchable/store"); //commonjs

Create a Store (Javascript)

const store = createStore({ counter: 0 });

See below for runtime Immutable state in Typescript!

Track State

In React...

import { useSelected } from "@watchable/store-react";
const counter = useSelected(store, (state) => state.counter);

// get and set keyed property, like React useState
const [counter, setCounter] = useStateProperty(store, "counter");

In pure business logic...

// watching the store
store.watch((state) => console.log(`Counter is ${state.counter}`));

// follow a selector (called back any time the selected value changes)
import { followSelector } from "@watchable/store-follow";
followSelector(
  store,
  (state) => state.counter,
  (counter) => {
    console.log(`Counter is ${counter}`);
  }
);

Read and Write State

Using a draft...

// create the next immutable state by editing a draft
import { edit } from "@watchable/store-edit";
edit(store, (draft) => (draft.counter += 1));

Using pure immutable patterns...

// read state
const state = store.read();

// write state using immutable patterns
store.write({
  ...state,
  counter: state.counter + 1,
});

Create an Immutable Store (Typescript)

import { createStore, type Immutable } from "@watchable/store";

// `Immutable` is recommended to block inadvertent edits of state
type CounterState = Immutable<{
  counter: number;
}>;

const INITIAL_STATE: CounterState = {
  counter: 0,
} as const;

const store = createStore(INITIAL_STATE);

Description

472 gzipped bytes of powerful state-management!

When a new state is passed to store.write(), user interfaces and business logic are notified of changes to state matching their Selectors.

@watchable/store is incredibly simple, lightweight and framework-independent, and therefore suited to manage state within almost any server-side or client-side Typescript or Javascript project.

Read the API Reference, examine the example code below, or browse the source on Github.

Demonstration Apps

The Example Counter Apps offer minimal demonstrations of @watchable/store

• Counter Apps using various Web Frameworks:
  • with React (using @watchable/store-react)
  • with no framework (using @watchable/store-follow)
  • with Preact (using @watchable/store-react) and aliased React
• Counter Apps using various Bundling approaches:
  • via Commonjs
  • via ESM
  • for tiniest bundle (a tree-shaken counter app in just 406 bytes!)
• Counter Apps demonstrating Tips and Tricks:
  • Manage Immutability using editable drafts - eliminates Immutable update patterns
  • Share a store with multiple components using React Context API - eliminates prop drilling
  • The fastest possible app using @watchable/store (32000 updates per second)
  • The smallest possible app using @watchable/store-react (316 bytes)