⛏️ strata

get in loser, we're managing state

📦 npm install @e280/strata
🧙‍♂️ probably my tenth state management library, lol
💁 it's all about rerendering ui when data changes
🦝 powers reactivity in our view library @e280/sly
🧑‍💻 a project by https://e280.org/

🚦 signals — ephemeral view-level state
🌳 tree — persistent app-level state
🪄 tracker — reactivity integration hub

🚦 strata signals

ephemeral view-level state

import {signal, effect} from "@e280/strata"

🚦 each signal holds a value

• make signal

  const $count = signal(0)

  maybe you like the $ prefix convention for signals?

• read signal

  $count() // 0

• write signal

  $count(1)

• write signal (and await all downstream effects)

  await $count(2)

  this is supposed to impress you

🚦 pick your poison

• signal hipster-fn syntax

  $count()        // read
  await $count(2) // write

• signal get/set syntax

  $count.get()        // read
  await $count.set(2) // write

• signal .value accessor syntax

  $count.value     // read
  $count.value = 2 // write

  value pattern is super nice for these vibes

  $count.value++
  $count.value += 1

🚦 effects

• effects run when the relevant signals change

  effect(() => console.log($count()))
    // 1
    // the system detects '$count' is relevant
  
  $count.value++
    // 2
    // when $count is changed, the effect fn is run

🚦 signal.derived and signal.lazy are computed signals

• signal.derived
  is for combining signals, like a formula

  const $a = signal(1)
  const $b = signal(10)
  const $product = signal.derived(() => $a() * $b())
  
  $product() // 10
  
  // change a dependency,
  // and the derived signal is automatically updated
  await $a(2)
  
  $product() // 20

• signal.lazy
  is for making special optimizations.
  it's like derived, except it cannot trigger effects,
  because it's so damned lazy, it only computes the value on read, and only when necessary.

  i repeat: lazy signals cannot trigger effects!

🚦 core primitive classes

• the hipster-fn syntax has a slight performance cost
• you can instead use the core primitive classes

  const $count = new Signal(1)

  core signals work mostly the same

  // ✅ legal
  $count.get()
  $count.set(2)

  except you cannot directly invoke them

  // ⛔ illegal on core primitives
  $count()
  $count(2)

• same thing for derived/lazy

  const $product = new Derived(() => $a() * $b())

  const $product = new Lazy(() => $a() * $b())

• conversions
  • all core primitives (signal/derived/lazy) have a convert-to-hipster-fn method

    new Signal(1).fn() // SignalFn<number>, hipster-fn

  • and all hipster fns (signal/derived/lazy) have a .core property to get the primitive

    signal(0).core // Signal<number>, primitive instance

🚦 types

• Signaly<V> — can be Signal<V> or Derived<V> or Lazy<V>
  • these are types for the core primitive classes
• SignalyFn<V> — can be SignalFn<V> or DerivedFn<V> or LazyFn<V>
  • these *Fn types are for the hipster-fn-syntax enabled variants

🌳 strata trees

persistent app-level state

import {Trunk} from "@e280/strata"

• single-source-of-truth state tree
• immutable except for mutate(fn) calls
• localStorage persistence, cross-tab sync, undo/redo history
• no spooky-dookie proxy magic — just god's honest javascript

🌳 Trunk is your app's state tree root

• better stick to json-friendly serializable data

  const trunk = new Trunk({
    count: 0,
    snacks: {
      peanuts: 8,
      bag: ["popcorn", "butter"],
    },
  })
  
  trunk.state.count // 0
  trunk.state.snacks.peanuts // 8

🌳 formal mutations to change state

• ⛔ informal mutations are denied

  trunk.state.count++ // error is thrown

• ✅ formal mutations are allowed

  await trunk.mutate(s => s.count++)

🌳 Branch is a view into a subtree

• it's a lens, make lots of them, pass 'em around your app

  const snacks = trunk.branch(s => s.snacks)

• run branch mutations

  await snacks.mutate(s => s.peanuts++)

• array mutations are unironically based, actually

  await snacks.mutate(s => s.bag.push("salt"))

• you can branch a branch

🌳 on to watch for mutations

• on the trunk, we can listen deeply for mutations within the whole tree

  trunk.on(s => console.log(s.count))

• whereas branch listeners don't care about changes outside their scope

  snacks.on(s => console.log(s.peanuts))

• on returns a fn to stop listening

  const stop = trunk.on(s => console.log(s.count))
  stop() // stop listening

🌳 fancy advanced usage

only discerning high-class aristocrats are permitted beyond this point

🌳 Trunk.setup for localStorage persistence etc

• it automatically handles persistence to localStorage and cross-tab synchronization
• simple setup

  const {trunk} = await Trunk.setup({
    version: 1, // 👈 bump whenever you change state schema!
    initialState: {count: 0},
  })

  • uses localStorage by default
• it's compatible with @e280/kv

  import {Kv, StorageDriver} from "@e280/kv"
  
  const kv = new Kv(new StorageDriver())
  const store = kv.store<any>("appState")
  
  const {trunk} = await Trunk.setup({
    version: 1,
    initialState: {count: 0},
    persistence: {
      store,
      onChange: StorageDriver.onStorageEvent,
    },
  })

🌳 Chronobranch for undo/redo history

• first, put a Chronicle into your state tree

  const trunk = new Trunk({
    count: 0,
    snacks: Trunk.chronicle({
      peanuts: 8,
      bag: ["popcorn", "butter"],
    }),
  })

  • big-brain moment: the whole chronicle itself is stored in the state.. serializable.. think persistence — user can close their project, reopen, and their undo/redo history is still chillin' — brat girl summer
• second, make a Chronobranch which is like a branch, but is concerned with history

  const snacks = trunk.chronobranch(64, s => s.snacks)
    //                               \
    //               how many past snapshots to store

• mutations will advance history (undoable/redoable)

  await snacks.mutate(s => s.peanuts = 101)
  
  await snacks.undo()
    // back to 8 peanuts
  
  await snacks.redo()
    // forward to 101 peanuts

• you can check how many undoable or redoable steps are available

  snacks.undoable // 2
  snacks.redoable // 1

• chronobranch can have its own branches — all their mutations advance history
• plz pinky-swear right now, that you won't create a chronobranch under a branch under another chronobranch 💀

🪄 strata tracker

reactivity integration hub

import {tracker} from "@e280/strata/tracker"

if you're some kinda framework author, making a new ui thing, or a new state concept -- then you can use the tracker to jack into the strata reactivity system, and suddenly your stuff will be fully strata-compatible, reactin' and triggerin' with the best of 'em.

the tracker is agnostic and independent, and doesn't know about strata specifics like signals or trees -- and it would be perfectly reasonable for you to use strata solely to integrate with the tracker, thus making your stuff reactivity-compatible with other libraries that use the tracker, like sly.

note, the items that the tracker tracks can be any object, or symbol.. the tracker cares about the identity of the item, not the value (tracker holds them in a WeakMap to avoid creating a memory leak)..

🪄 integrate your ui's reactivity

• we need to imagine you have some prerequisites
  • myRenderFn -- your fn that might access some state stuff
  • myRerenderFn -- your fn that is called when some state stuff changes
  • it's okay if these are the same fn, but they don't have to be
• tracker.observe to check what is touched by a fn

  // 🪄 run myRenderFn and collect seen items
  const {seen, result} = tracker.observe(myRenderFn)
  
  // a set of items that were accessed during myRenderFn
  seen
  
  // the value returned by myRenderFn
  result

• it's a good idea to debounce your rerender fn

  import {debounce} from "@e280/stz"
  const myDebouncedRerenderFn = debounce(0, myRerenderFn)

• tracker.subscribe to respond to changes

  const stoppers: (() => void)[] = []
  
  // loop over every seen item
  for (const item of seen) {
  
    // 🪄 react to changes
    const stop = tracker.subscribe(item, myDebouncedRerenderFn)
  
    stoppers.push(stop)
  }
  
  const stopReactivity = () => stoppers.forEach(stop => stop())

🪄 integrate your own novel state concepts

• as an example, we'll invent the simplest possible signal

  export class SimpleSignal<Value> {
    constructor(private value: Value) {}
  
    get() {
  
      // 🪄 tell the tracker this signal was accessed
      tracker.notifyRead(this)
  
      return this.value
    }
  
    async set(value: Value) {
      this.value = value
  
      // 🪄 tell the tracker this signal has changed
      await tracker.notifyWrite(this)
    }
  }

🧑‍💻 strata is by e280

free and open source by https://e280.org/
join us if you're cool and good at dev