live-state.ts

Create composable and reactive state that propagate updates down the stream without unnecessary computation.

This library helps to maintain consistent state in realtime applications.

It is inspired from s.js and rxjs, and aims to keep simple.

Features

• Live State with realtime updates automatically pushed to attached lifecycle hooks
• Skip unnecessary computation
• Built-in Typescript support
• 100% tested with ts-mocha

Usage Examples

Importing the library

Import npm package

Install from npm:

# install with npm
npm i live-state.ts
# or pnpm
pnpm i live-state.ts
# or yarn
yarn add live-state.ts

Import as typescript package / esm package:

import { LiveState } from 'live-state.ts'

Import as commonjs package

let { LiveState } = require('live-state.ts')

Import esm package over CDN

<script type="module">
  import { LiveState } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/esm.js'
  let state = LiveState.of(1)
</script>

Import iife library over CDN

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/browser.js"></script>
<script>
  let state = LiveState.of(1)
</script>

Lifecycle Hook Example

let state = LiveState.of(1)
state.attach({
  setup(value) {
    console.log('initial value:', value)
  },
  update(value, oldValue) {
    console.log('update:', { value, oldValue })
  },
  teardown(value) {
    console.log('last value:', value)
  },
})
// print initial value: 1
state.update(2)
// print update: { value: 2, oldValue: 1 }
state.update(3)
// print update: { value: 3, oldValue: 2 }
state.teardown()
// print last value: 3

Derived State Example

The state.map(fn) takes a projection function and derives a new state.

When the current state is teardown, the derived state will also be teardown.

let state = LiveState.of(10)
let doubleState = state.map(x => x * 2)
let tupleState = LiveState.combine(state, doubleState, (a, b) => [a, b])

console.log(tupleState.peek())
// print [10, 20]

state.update(15)
console.log(tupleState.peek())
// print [15, 30]

Tips: You can attach lifecycle hooks to derived state as well.

Watching State Example

Similar to the state.map(fn) method, the state.watch(fn) method will push the current state and future updates to the callback function.

However, this method does not derive a new state. You can use this method with less overhead when the return value of the callback function is not useful.

The concept of 'watch' is also called as 'observe', 'subscribe', or 'forEach' in other libraries.

let state = LiveState.of(10)

let detach = state.watch(value => console.log(value))
// print 10

state.update(20)
// print 20

detach()
state.update(30)
// won't print 30

More usage examples refer to:

• browser-example
• commonjs-example
• esm-example
• state.spec.ts

License

This project is licensed with BSD-2-Clause

This is free, libre, and open-source software. It comes down to four essential freedoms [ref]:

• The freedom to run the program as you wish, for any purpose
• The freedom to study how the program works, and change it so it does your computing as you wish
• The freedom to redistribute copies so you can help others
• The freedom to distribute copies of your modified versions to others