Async Operations #

In Inglorious Store, your event handlers can be async, and you get deterministic behavior automatically. Inside an async handler, you can access other parts of state (read-only), and you can trigger other events via api.notify().

export const types = {
  todoList: {
    async loadTodos(entity, payload, api) {
      try {
        entity.loading = true
        const { name } = api.getEntity("user")
        const response = await fetch(`/api/todos/${name}`)
        const data = await response.json()
        api.notify("todosLoaded", todos)
      } catch (error) {
        api.notify("loadFailed", error.message)
      }
    },

    todosLoaded(entity, todos) {
      entity.todos = todos
      entity.loading = false
    },

    loadFailed(entity, error) {
      entity.error = error
      entity.loading = false
    },
  },
}

Notice: you don't need pending/fulfilled/rejected actions. You stay in control of the flow — no hidden action chains. The api object passed to handlers provides:

• api.getEntities() - read entire state
• api.getEntities(typeName) - read entities by type
• api.getEntity(id) - read one entity
• api.notify(type, payload) - trigger other events (queued, not immediate)
• api.dispatch(action) - optional, if you prefer Redux-style dispatching
• api.getTypes() - access type definitions (mainly for middleware/plugins)
• api.getType(typeName) - access type definition (mainly for overrides)

All events triggered via api.notify() enter the queue and process together, maintaining predictability and testability.

handleAsync #

The handleAsync helper generates a set of event handlers representing the lifecycle of an async operation.

handleAsync(type, handlers, options?)

Think of the flow like a newspaper article:

• start writes the headline and sets the scene
• run gathers the reporting
• success publishes the story
• error prints the correction
• finally archives the notes

Example:

import { handleAsync } from "@inglorious/store/async"

const todoList = {
  ...handleAsync("fetchTodos", {
    async run(payload) {
      const res = await fetch("/api/todos")
      return res.json()
    },

    success(entity, todos) {
      entity.todos = todos
    },

    error(entity, error) {
      entity.error = error.message
    },

    finally(entity) {
      entity.loading = false
    },
  }),
}

Triggering fetchTodos emits the following events:

fetchTodos
fetchTodosRun
fetchTodosSuccess | fetchTodosError
fetchTodosFinally

Each step is an event handler, not an implicit callback.

Optional start handler #

Use start for synchronous setup (loading flags, resets, optimistic state):

handleAsync("save", {
  start(entity) {
    entity.loading = true
  },
  async run(payload) {
    return api.save(payload)
  },
})

If omitted, no Start event is generated.

Optimistic Updates #

If you want optimistic UI state, wrap the async behavior with optimistic. This helper lives at @inglorious/store/optimistic, so only users who need it import it:

import { handleAsync } from "@inglorious/store/async"
import { optimistic } from "@inglorious/store/optimistic"

const saveTodo = optimistic(
  handleAsync("saveTodo", {
    async run(payload) {
      const res = await fetch("/api/todos", {
        method: "POST",
        body: JSON.stringify(payload),
      })
      if (!res.ok) throw new Error("Failed")
      return res.json()
    },
    success(entity, todo) {
      entity.todos = entity.todos.map((item) =>
        item.id === todo.tempId ? todo : item,
      )
    },
  }),
  (entity, payload) => ({
    todos: [
      ...entity.todos,
      {
        id: payload.tempId,
        title: payload.title,
        completed: payload.completed,
        pending: true,
      },
    ],
  }),
)

If the optimistic state does not depend on the payload, use a static patch instead:

const saveSettings = optimistic(
  handleAsync("saveSettings", {
    async run(payload) {
      return api.save(payload)
    },
  }),
  { status: "saving" },
)

The wrapper stores a shallow snapshot of the patched keys, applies the optimistic patch during Start, and restores the previous values if the request fails.

Event scoping #

By default, lifecycle events are scoped to the triggering entity:

#entityId:fetchTodosSuccess

You can override this behavior:

handleAsync("bootstrap", handlers, { scope: "global" })

Available scopes:

• "entity" (default)
• "type"
• "global"

Key rule: Async code must not access entities after await. All updates happen in event handlers.