Skip to content

geut/staty

Repository files navigation

staty

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

Test Status Coverage JavaScript Style Guide standard-readme compliant

Made by GEUT

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

About

Build a proxy-state from plain objects

Resources

License

Stars

Watchers

Forks

Packages

No packages published