Easy to use store and event emitter — async, immutable, self-documenting, highly extensible

• Install
• Using the store
  • Set values (immutably)
  • Get values
  • Subscribe to changes
• Store operations
• Store subscribers
  • Order of operation
  • Subscriber options
  • Dynamic subscribers
  • Check if prop value changed
  • Unsubscribe
• Custom operations
• Extensions

npm install --save dot-store

import Store from "dot-store"
const store = new Store()

Pass an object to the Store constructor to set a default state.

await store.set("users.bob.admin", true)

store.get("users.bob.admin") // true
store.get() // {users: {bob: {admin: true}}}

This subscriber responds to any change within users.bob:

store.on("users.bob", async () => {
  console.log("bob changed")
})

Subscriber functions like store.on(event, props, fn) allow you to subscribe to any change within the prop location.

The event string consists of a preposition (before or after), plus an operation. For example, a valid event string would be beforeSet or afterDelete.

The after preposition is used by default when it is not specified. You may also use update in place of the operation to subscribe to all updates.

When omitted entirely, the event parameter defaults to "afterUpdate".

1. Call operation function (e.g. store.set(props, value))
2. Execute all before subscribers and wait for them to resolve
3. Perform operation on store
4. Execute all after subscribers and wait for them to resolve
5. Operation function resolves

Subscribers receive an options argument with lots of useful stuff:

store.on(
  "users.bob",
  async ({
    change,
    event,
    prevState,
    state,
    store,
    subscriber,
  }) => {
    // see example values below
  }
)

await store.set("users.bob.admin", true)

Use curly braces around a prop key to capture its value:

store.on("users.{userId}", async ({ userId }) => {
  userId // "bob", then "ted"
})

await store.set("users.bob.admin", true)
await store.set("users.ted.admin", true)

The change.test(props) function tests if a prop value changed.

The return value is truthy and doubles as a way to retrieve prop keys:

store.on("users", async ({ change }) => {
  // ✓ Value did change
  change.test("users.{userId}.{attr}") // { userId: "bob", attr: "admin" }
  change.test("users.bob.admin") // {}
  change.test("users.bob") // {}
  change.test("users") // {}

  // ⃠ Value didn't change
  change.test("users.ted.{attr}") // false
  change.test("users.ted") // false
})

await store.set("users.bob.admin", true)

const off = store.on("users.bob", async () => {})
off()

Custom operations do not modify the store. They allow you to leverage store eventing to run your own logic.

After initializing the store, add a custom operation:

const store = new Store()
store.op("fetch")

Subscribe to the custom event:

store.on("fetch", "users", async function({ value }) {
  value // { admin: "true" }
})

await store.fetch("users", { admin: "true" })