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

info

If you don't plan to use Drafts, always use now() instead to get the value of your state.

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

info

If you don't plan to use Drafts, prefer to mutate your state with set instead.

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.