superstate
The superstate wrapper. This is the function that you should use to create a superstate.
Examples:
// Primitives
const greet = superstate('Hello world!')
const count = superstate(0)
const isLoggedIn = superstate(false)
// Objects
const person = superstate({ id: '0', name: 'John' })
// Nested objects
const theme = superstate({
header: { color: 'red' },
footer: { color: 'blue' },
links: [
{ href: '#', text: 'Home' },
{ href: '#', text: 'About' },
],
})
// Collections
const people = superstate([
{ id: '0', name: 'John' },
{ id: '1', name: 'Doe' },
])
// Maps
const numbers = superstate(
new Map([
['one', 1],
['two', 2],
])
)
// Sets
const colors = superstate(new Set(['Red', 'Yellow']))
now
Returns the current value of your state.
const count = superstate(0)
console.log(count.now()) // 0
count.set(10)
console.log(count.now()) // 10
draft
The draft version of your state. Will be undefined
if no draft is available. To set the value of the draft, call .sketch()
.
const count = superstate(0)
console.log(count.draft()) // undefined
count.sketch(10)
console.log(count.draft()) // 10
set
Overrides the value of now
, which is the current value of your state:
const count = superstate(0)
count.set(1) // now === 1
If you want to use the previous value as a reference:
const count = superstate(0)
count.set((prev) => prev + 1) // now === 1
count.set((prev) => prev + 1) // now === 2
Broadcasting
Whenever you .set()
, changes will be broadcasted unless the new now
is equal to the previous one,
or you pass true
to the silent
option:
const count = superstate(0)
count.set(1, { silent: true }) // won't be broadcasted
sketch
Overrides the value of draft
:
const count = superstate(0)
count.sketch(1) // `draft` === 1
And just like .set
, you can use the previous draft
as a reference:
const count = superstate(0)
count.sketch(1) // `draft` === 1
count.sketch((prev) => prev + 1) // `draft` === 2
Broadcasting
Whenever you .sketch()
, changes will be broadcasted unless the new draft
is equal to the previous one,
or you pass true
to the silent
option:
const count = superstate(0)
count.sketch(1, { silent: true })
Note that draft changes will only be broadcasted to draft subscribers. Learn more โ
publish
When you have a draft
ready to go, call .publish()
to make it the new now
value:
const count = superstate(0)
count.sketch(1)
console.log(count.draft()) // logs 1
count.publish()
console.log(count.draft()) // logs `undefined`
console.log(count.now()) // logs 1
info
Don't worry about publishing if you're not using Drafts.
Broadcasting
Whenever you .publish()
, changes will be broadcasted unless the new now
is equal to the previous one,
or you pass true
to the silent
option:
const count = superstate(0)
count.sketch(1)
count.publish({ silent: true }) // won't be broadcasted
discard
Discards the draft, setting its value to undefined
.
Upon calling this function, a draft broadcast will occur.
const count = superstate(0)
count.set(1) // draft === 1
count.discard() // draft === undefined
If there's no draft to discard, nothing is going to happen.
Broadcasting
Whenever you .discard()
, changes will be broadcasted unless the new draft
is equal to the previous one,
or you pass true
to the silent
option:
const count = superstate(0)
count.sketch(1)
count.discard({ silent: true }) // won't be broadcasted
subscribe
Starts monitoring changes to the state.
const count = superstate(0)
count.subscribe((value) => console.log(value))
count.set(10) // this will trigger the subscribe callback
You can also subscribe to changes made to the draft
:
const count = superstate(0)
// Note the 'draft' at the line below
count.subscribe((value) => console.log(value), 'draft')
count.sketch(10) // this will trigger the subscribe callback
unsubscribe
The .subscribe()
method returns a unsubscribe function:
const count = superstate(0)
const unsubscribe = count.subscribe((value) => console.log(value))
count.set(10) // this will trigger the subscribe callback
unsubscribe() // stop listening to changes
count.set(10) // this wont trigger the subscribe callback
unsubscribeAll
Unsubscribes all now
and draft
subscribers.
After you call this method, changes will no longer be broadcasted.
const count = superstate(0)
count.subscribe((value) => console.log(value))
count.publish(10) // this will trigger the subscribe callback
count.unsubscribeAll() // stop listening to changes
count.publish(10) // this wont trigger the subscribe callback
caution
Only call this function if you know what you're doing. If possible, always prefer to unsubscribe to particular subscriptions.
extend
Read more about Extensions.
use
Read more about Middlewares.