README.md

staty

Build a proxy-state from plain objects. With automatic rollback to previous state in case of errors.

Install

$ npm install @geut/staty

Usage

import { staty, subscribe, snapshot, action } from '@geut/staty'

const state = staty({
  count: 0
})

console.log(snapshot(state)) // => { count: 0 }

subscribe(state, () => {
  console.log(state) // => { count: 1 }
})

subscribe(state, () => {
  console.log(state.count) // => 1
}, { props: 'count' })

// filter multiple values
subscribe(state, () => {
  console.log(state.count) // => 1
}, { props: ['count'] })

state.count++

try {
  action(() => {
    state.count = 100
    throw new Error('ups')
  })
} catch (err) {
  console.log(err) // => ups
}

// rollback to the last good state and subscriptions won't be trigger it
state.count // => 1

API

staty(target, opts?) => any

Creates a new proxy-state

• target: any
• opts?: Object = {}
  • onReadOnly?: (target: any, prop: any, value: any) => {} global handle for readonly snapshot errors
  • onAction?: (state: Proxy, actionName: any) => {} global subscription to run before every action. Create a state is also an action so it will run on every staty({}) call.

listeners(state) => ListenersReport

Get subscription listeners count

• state: any

subscribe(state, handler, opts?) => UnsubscribeFunction

Subscribe for changes in the state

• state: any
• handler: () => void
• opts?: Object = {}
  • props?: string | string[] props to subscribe
  • filter?: (actionName: string) => boolean subscribe only for specific action names
  • batch?: boolean = false execute in batch turning the subscription into async. Required before=false
  • autorun?: boolean run immediately. Required before=false
  • before?: boolean run before the other subscriptions and after the action finish. Good place to validate your state. Required batch=false && autorun=false

ref(value, mapSnapshot?, cache?) => any

Add a ref to another object

• value: any
• mapSnapshot?: (ref: any) => any
• cache?: boolean = false enable cache for snapshots

action(handler, actionName) => void

Create a action

• handler: Function
• actionName: string

snapshot(state, prop?) => any

Creates a snapshot of the state

• state: any
• prop?: (string | Array<string>)

Issues

🐛 If you found an issue we encourage you to report it on github. Please specify your OS and the actions to reproduce it.

Contributing

👥 Ideas and contributions to the project are welcome. You must follow this guideline.

License

MIT © A GEUT project