Arbor Store

A fully typed reactive state management library with very little boilerplate.

Installation

Via npm

1npm install @arborjs/store

Or via yarn

1yarn add @arborjs/store

Usage

There are three steps to working with Arbor:

1. Create a store object to hold your application state:

1import { Arbor } from "@arborjs/store"
2
3// The store object in this example is our application store holding the state of a counter.
4const store = new Arbor({
5  count: 0,
6})

2. Then subscribe to changes made to the store:

1const unsubscribe = store.subscribe((event) => {
2  // Subscribers are provided with information about the change (a.k.a mutation)
3  // triggered on the store, such as type of operation (set, delete, push, splice, etc...).
4  // This allows for fine grained control over how to react to the state mutation.
5  console.log("Count:", event.state.count)
6})
7
8// You can call the returned unsubscribe function whenever you want to stop listening to store updates.
9unsubscribe()

3. Lastly, interact with the store making changes to its state:

1// The store state is a reactive object, Arbor uses proxies to track access to different
2// parts of the state and notify the relevant subscribers when a mutation that affect them
3// is triggered in the store.
4const counter = store.state
5
6// Mutations can then be triggered via regular JavaScript APIs causing subscribers to react.
7counter.count++
8=> Count: 1
9counter.count++
10=> Count: 2
11counter.count--
12=> Count: 1
13counter.count = 5
14=> Count: 5

Arbor will lazily and recursively proxy every object composing the state of the store, no matter how deep and complex that state is, making every bit of it reactive, that means that you can subscribe to changes to any part of the state and react to changes accordingly simply relying on the old regular JS APIs you are already used to, such as assignments, or APIs like Array#push and Array#splice.

Scoped Stores

Arbor implements a path tracking mechanism that allows apps to have scoped references of a store, ultimately enabling different parts of an app to react only to state changes affecting the scope they are subscribed to.

[!IMPORTANT] This is what's behind the optimal re-rendering behavior of the React binding, enabling Arbor to only re-render components that truly depend on the parts of the state being updated.

Let's take the previous "counter" example and extend it so we can track two different counters:

1const store = new Arbor({
2  counter1: {
3    count: 0,
4  },
5  counter2: {
6    count: 0,
7  },
8})

We can then create one scope for each counter:

1import { ScopedStore } from "@arborjs/store"
2
3const scope1 = new ScopedStore(store)
4const scope2 = new ScopedStore(store)

Then subscribe to both scopes so we can see which one reacts to what changes:

1const unsubscribeFromScope1 = scope1.subscribe((event) => {
2  console.log("Scope1 counter1:", event.state.counter1.count)
3  console.log("Scope1 counter2:", event.state.counter2.count)
4})
5
6const unsubscribeFromScope2 = scope2.subscribe((event) => {
7  console.log("Scope2 counter1:", event.state.counter1.count)
8  console.log("Scope2 counter2:", event.state.counter2.count)
9})

Each scope will automatically subscribe to state fields as they are accessed. For example, the following will cause scope1 to automatically subscribe to changes to counter1.count but changes to counter2 will not affect subscribers of scope1:

1console.log(scope1.state.counter1.count)
2=> 0

Now, should we change counter1.count from the original store (or from scope1), only scope1 will react to the change since scope2 has not yet accessed any part of the state, therefore does not depend on any particular part of the state:

1store.state.counter1.count++
2=> Scope1 counter1: 1
3=> Scope1 counter2: 0

Changing counter2.count will not notify either scope since none have accessed that part of the state:

1store.state.counter2.count++ // no console logs are executed

As soon as we access any part of the state from scope2 it starts to react to changes to the part of the state it has accessed since it now depends on it:

1console.log(scope2.state.counter1.count)
2=> 1
3console.log(scope2.state.counter2.count)
4=> 0

The code above causes scope2 to subscribe to both counter1 and counter2 and react to mutations triggered on either counter:

1store.state.counter1.count++
2=> Scope1 counter1: 2
3=> Scope1 counter2: 0
4=> Scope2 counter1: 2
5=> Scope2 counter2: 0
6store.state.counter2.count++
7=> Scope2 counter1: 2
8=> Scope2 counter2: 1

Note that mutations to counter2 only notified scope2 since scope1 never accessed counter2.

Subscriptions

The simplest way to subscribe to store changes is from the store itself like in the previous examples, however, you may choose to subscribe to specific nodes of the state tree directly, keeping your subscriptions focused on a subset of the application state:

1const store = new Arbor({
2  counter1: {
3    count: 0,
4  },
5  counter2: {
6    count: 0,
7  },
8})
9
10store.subscribeTo(store.state.counter1, (event) => {
11  // React to changes to `counter1`
12})

Focusing your subscriptions to specific state tree nodes can be interesting if you have a large number of subscribers that only care about a subset of your application state, making notifications more efficient since not every subscriber needs to be processed.

If you are curious to understand better how this is done internally, check out the details of the Subscription Tree, mechanism used by Arbor to achieve this behavior.

Utility Functions

Arbor also provides a couple of utility functions that can be used to simplify certain operations in the state tree:

detach

With detach you can remove any node from the state tree without necessarily knowing where the node is held, making it easy to remove for instance items from a list without having a reference to that list.

Here's a simple example inspired by our sample Todo App:

1import { Arbor, detach, proxiable } from "@arborjs/store"
2
3@proxiable
4class Todo {
5  constructor(public text: string) {}
6
7  delete() {
8    // Arbor will automatically determine which stat tree node is this todo's parent
9    // and trigger a mutation that removes the todo from that node.
10    detach(this)
11  }
12}
13
14const store = new Arbor([
15  new Todo("Do the dishes"),
16  new Todo("Walk the dogs"),
17  new Todo("Clean the house"),
18])
19
20store.subscribe(event => {
21  console.log(`Todo list now has ${event.state.length} items.`)
22})
23
24const firstTodo = store.state[0]
25
26// Deleting the todo will cause the subscriber above to run and log the result
27firstTodo.delete()
28=> Todo list now has 2 items.

merge

Can merge an object into a given Arbor node as a single operation, calling subscribers only once:

1import { Arbor, merge } from "@arborjs/store"
2
3const store = new Arbor([
4  {
5    id: 1,
6    text: "Do the dishes",
7    description: "The kitchen could use some love...",
8    done: false,
9  },
10  {
11    id: 2,
12    text: "Walk the dogs",
13    description: "Alice took them out last night, it's time to go out again.",
14    done: false,
15  },
16])
17
18const todo = store.state[0]
19const updatedTodo = merge(todo, {
20  title: "Do all the dishes",
21  description: "The kitchen is a mess right now.",
22})

unwrap

If you need to access the underlying data wrapped by an Arbor node, you can unwrap the node:

1import { Arbor, unwrap } from "@arborjs/store"
2
3const store = new Arbor([
4  { id: 1, text: "Do the dishes", done: false },
5  { id: 2, text: "Walk the dogs", done: false },
6])
7
8const todo = store.state[0]
9const unwrappedTodo = unwrap(firstTodo)
10
11// This will not notify subscribers since `unwrappedTodo` is no longer a node of the state tree.
12unwrappedTodo.done = true

Arbor ❤️ OOP

Arbor will not enforce any particular data model style, you can use literal objects and arrays to represent your data model or go more "functional" style if that's what you prefer. However, Arbor shines brighter in more complex applications when you start introducing abstractions to represent your data model usually via JS classes.

You can leverage JavaScript built-in constructs like classes to build more complex data models, all you have to do is decorate them with @proxiable, which lets Arbor know instances of the decorated class should be reactive.

Here's what the data model for a Todo app could look like in Arbor:

1import { detatch, detached, proxiable } from "@arborjs/store"
2
3/**
4 * Represents a todo entry in the application.
5 *
6 * This class provides an API that encapsulates and manages a specific
7 * Todo entry.
8 */
9@proxiable
10class Todo {
11  done = false
12
13  // Detached fields are "detached" from the store's state tree so changing
14  // its value will not notify subscribers.
15  @detached priorityChanged = false
16
17  constructor(public content: string, public priority = 0) {}
18
19  delete() {
20    // Arbor provides this `detach` utility function
21    // that makes it easy for you to remove this from the store
22    // without necessarily knowing where exactly it is within your state.
23    detach(this)
24  }
25}
26
27/**
28 * Represents the Todo list itself, holding all Todo entries created in the application
29 *
30 * This class extends the JS built-in Array API with handy methods that make it easier
31 * to manage the Todo list.
32 */
33@proxiable
34class TodoList extends Array<Todo> {
35  get first() {
36    return this[0]
37  }
38
39  get last() {
40    return this[this.length - 1]
41  }
42
43  isEmpty() {
44    return this.length === 0
45  }
46
47  clear() {
48    this.splice(0, this.length)
49  }
50}

Then we'd use that data model to initialize our store:

1import { Arbor } from "@arborjs/store"
2
3const store = new Arbor(
4  new TodoList(
5    new Todo("Do the dishes"),
6    new Todo("Walk the dogs"),
7    ...
8  )
9)
10
11const todoList = store.state
12const doTheDishesTodo = todoList.first
13
14doTheDishesTodo.done
15=> false
16// The following triggers a mutation event in the store and subscribers will be notified
17doTheDishesTodo.toggle()
18doTheDishesTodo.done
19=> true
20todoList.length
21=> 2
22// The following triggers a mutation event in the store and subscribers will be notified
23todoList.clear()
24todoList.length
25=> 0
26// The following triggers a mutation event in the store and subscribers will be notified
27doTheDishesTodo.priority++
28// Because Todo#priorityChanged is @detached, a mutation event is not emitted, so no subscribers are notified.
29doTheDishesTodo.priorityChanged = true

When building your data model like that, you may need to serialize that data model without losing type information, so when you deserialize that data you get back instances of the correct classes representing each part of your data. Check out @arborjs/json for that.

Learn By Example

We've put together a couple of CodeSanboxes with examples of how to use Arbor in a React app with code comments further explaining some of the concepts that you may find helpful.

[!NOTE] We'll put together some Vanilla JS examples of Arbor usage soon.

• Counter App
• Todo App
• Payments App

Support This Project

License

Arbor is MIT licensed.