👁️ watch for changes to properties
🕵️ track only the properties you are reading, automatically
♻️ keeps you safe from circular updates
⛹️ updates are debounced, avoiding duplicate updates
🌳 carve large state trees into substates
🧬 implemented with recursive es proxies
🔬 typescript-native types, es modules
💖 free and open source, just for you

snapstate is designed to be a modern replacement for mobx. mobx was amazing, but has grown comically large at like 50 KB. mobx is also global, among other complications that we don't prefer.

snapstate is 1.5 KB, minified and gzipped.

🕵️ tracking changes to properties

first, let's create some state.
```
import {snapstate} from "@chasemoskal/snapstate"

const snap = snapstate({
  count: 0,
  coolmode: "enabled",
  also: {
    nesting: {
      isAllowed: true,
    },
  },
})
```

snap.track allows us to track changes to the state

snap.track(state => {
  console.log(state.count)
   //               ☝️
   // snapstate detects this property read,
   // and will run our track callback
   // whenever this property changes
})
 // 0 —— runs once initially

snap.state.count += 1
 // 1 —— automatically runs the relevant tracker functions

snap.state.coolmode = "super"
 // *nothing happens*
 // our track callback doesn't care about this property :)

if you prefer driving stick-shift, we can make a manual track and even avoid the initial run.

snap.track(

  // observer: listen specifically to "count"
  ({count}) => ({count}),

  // reaction: responding to changes
  ({count}) => console.log(`count changed: ${count}`),
)

snap.state.count += 1
 // 1

of course, we can stop tracking things when we want.

const untrack = snap.track(({count}) => console.log(count))
 // 0

snap.state.count += 1
 // 1

untrack()
snap.state.count += 1
 // *nothing happens*

💾 control which parts of your app can write to state

this is a pillar of good state management.

if every part of our app can write to the state, all willy-nilly, it quickly becomes a convoluted mess that is hard to debug.

snap.readable is just like snap.state, except that it's read-only.

const snap = snapstate({count: 0})

snap.state.count += 1
 // this is allowed

snap.readable.count += 1
 // SnapstateReadonlyError —— no way, bucko!

we can pass the readable around to the parts of our application that should only have read-access to the state (like our components).
but components will also need access to track, subscribe, and the rest of it —

so snapstate has a handy restricted function, which makes a read-only version of a snapstate.

import {snapstate, restricted} from "@chasemoskal/snapstate"
const snap = snapstate({count: 0})

myFrontendComponents({
  snap: restricted(snap),
})

it's easy to formalize actions with snapstate.

const snap = snapstate({count: 0})

// only our actions have write-access to state
const actions = {
  increment() {
    snap.state.count += 1
  },
}

myFrontendComponents({

  // components only have read-only access to the state
  snap: restricted(snap),

  // components can call our formalized actions to change the state
  actions,
})

note: snap.state and snap.writable are aliases for each other.

subscriptions will execute whenever any state is changed in the tree.

snap.subscribe(state => {
  console.log("something has changed")
})

of course you can unsubscribe, too.

const unsubscribe = snap.subscribe(state => {
  console.log("something has changed")
})

unsubscribe()

✋ untrack and unsubscribe all

delete all trackers
```
snap.untrackAll()
```
delete all subscriptions
```
snap.unsubscribeAll()
```

⛹️ debouncing and waiting

tracking and subscription callbacks are debounced.
this prevents consecutive changes from firing more callbacks than necessary.

const snap = snapstate({count: 0})
snap.track(({count}) => console.log(count))
snap.state.count += 1
snap.state.count += 1
snap.state.count += 1
 // 1 —— only runs once

but be advised — this might mean you have to wait before seeing the effects of your callbacks

const snap = snapstate({count: 0})

let called = false
snap.subscribe(() => called = true)

snap.state.count += 1
console.log(called)
 // false —— *what the heck!?*

await snap.wait()
 // true —— oh! i just had to wait, for the debouncer!

♻️ circular-safety

you are prevented from writing to state while reacting to it.

const snap = snapstate({count: 0})

snap.track(state => {
  state.count += 1
   // SnapstateReadonlyError —— not a chance, buster!

   // "state" is actually "snap.readable" in this context,
   // (same with subscribe)
})

you might think you're clever, and could outsmart snapstate. you'd be wrong!

snap.track(({count}) => {
  // here's you being clever, thinking you can access the *outer* snap.state
  snap.state.count += 1
   // SnapstateCircularError —— dead in your tracks!
})

as we've established, you can't make circular references in track callbacks.

you also can't make circles with track reactions.

snap.track(
  ({count}) => ({count}),
  () => {
    snap.state.count += 1
  },
)
snap.state.count += 1
await snap.wait()
 // SnapstateCircularError —— thwarted again, buddy!

and you can't make circles in subscriptions, either.

snap.subscribe(() => snap.state.count += 1)
snap.state.count += 1
await snap.wait()
 // SnapstateCircularError —— just give up

you can catch these async errors on the snap.wait() promise.

✂️ substate: carve your state into subsections

it's awkward to pass your whole application state to every little part of your app.

so you can snip off chunks, to pass along to the components that need it.

import {snapstate, substate} from "@chasemoskal/snapstate"

const snap = snapstate({
  outerCount: 1,
  coolgroup: {
    innerCount: 2,
  }
})

const coolgroup = substate(snap, tree => tree.coolgroup)

// note: coolgroup has no access to "outerCount"
console.log(coolgroup.state.innerCount)
 // 2

coolgroup.track(state => console.log(state.innerCount))
coolgroup.state.innerCount += 1
await coolgroup.wait()
 // 3

a substate's subscribe function only listens to its subsection of the state.
a substate's untrackAll function only applies to tracking called on the subsection.
a substate's unsubscribeAll function only applies to subscriptions called on the subsection.

substates can also be restricted.

const restrictedCoolgroup = restricted(coolgroup)
restrictedCoolgroup.state.innerCount += 1
 // SnapstateReadonlyError

👨‍⚖️ super-strict typescript readonly

introducing snap.readonly. it's snap.readable's strict and demanding mother-in-law.
readonly literally is readable, but with more strict typescript typing.
you see, typescript is extremely strict about its typescript "readonly" properties.
so much so, that it's very painful to use typescript "readonly" structures throughout your app.
for this reason, snapstate provides snap.readable by default, which will throw errors only at runtime when you're being naughty attempting to write properties there — but the typescript compiler doesn't complain with readable.
if your shirt is fully tucked-in, you can use snap.readonly to produce compile-time typescript errors.
anywhere you find a readable (for example in track and subscribe callbacks), you could set its type to Read<typeof readable> to make typescript super strict about it.

📜 beware of arrays, maps, and other fancy objects

snapstate only tracks changes when properties are set on plain objects.

what this means, is that methods like array.push aren't visible to snapstate.

const snap = snapstate({myArray: []})

// bad -- updates will not respond.
snap.state.myArray.push("hello")

to update an array, we must wholly replace it:

// good -- updates will respond.
snap.state.myArray = [...snap.state.myArray, "hello"]

this also means that the properties on any class instances won't be tracked.

const snap = snapstate({
  date: new Date(), // properties within this aren't tracked
  myCoolObject: new MyCoolObject(), // properties within this aren't tracked
})

this is an entirely survivable state of affairs, but we may eventually do the work to implement special handling for arrays, maps, sets, and other common objects. (contributions welcome!)

🧬 using proxies in your state, if you must

snapstate doesn't like proxies in the state, so it destroys them on-sight (by making object copies).
this is to prevent circularity issues, since snapstate's readables are made of proxies.
if you'd like to specifically allow a particular proxy, you can convince snapstate to allow it into the state tree, by having your proxy return true when symbolToAllowProxyIntoState is accessed.
snapstate will check for this symbol whenever it ingests objects into the state.

here's an example:

import {snapstate, symbolToAllowProxyIntoState} from "@chasemoskal/snapstate"

const snap = snapstate({
  proxy: new Proxy({}, {
    get(t, property) {
      if (property === symbolToAllowProxyIntoState)
        return true
      else if (property === "hello")
        return "world!"
    },
  })
})

console.log(snap.state.proxy.hello)
 // "world!"

💖 made with open source love

mit licensed.

please consider contributing by opening issues or pull requests.

// chase

Keywords

state

state-management

FAQs

What is @chasemoskal/snapstate?

Is @chasemoskal/snapstate well maintained?

Package last updated on 10 Jan 2023

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@chasemoskal/snapstate

🔮 snapstate