@inglorious/store 12.1.0 → 12.2.0

package/README.md

@@ -522,7 +522,7 @@ const types = {
         const { name } = api.getEntity("user")
         const response = await fetch(`/api/todos/${name}`)
         const data = await response.json()
-        api.notify("todosLoaded", todos)
+        api.notify("todosLoaded", data)
       } catch (error) {
         api.notify("loadFailed", error.message)
       }
@@ -553,6 +553,11 @@ Notice: you don't need pending/fulfilled/rejected actions. You stay in control o
 
 All events triggered via `api.notify()` enter the queue and process together, maintaining predictability and testability.
 
+Two things to keep in mind:
+
+- **`entity` ends at the first `await`.** `entity`, and every object or array read from it, is a draft of the current update, revoked when the update ends, and the update does not wait for your `await`. After it, writing to `entity` or reading anything taken from it throws. Write before the first `await`, then notify an event that does the rest, as `todosLoaded` does above. The same goes for payloads: pass a copy (`{ ...entity.values }`), not the draft, to a handler that reads it after an `await`.
+- **`api.getEntity()` reads the state from before the update.** A handler cannot see what an earlier handler in the same chain of events changed: see [State swapping](#state-swapping).
+
 ### `handleAsync`
 
 The `handleAsync` helper generates a set of event handlers representing the lifecycle of an async operation.
@@ -611,6 +616,8 @@ fetchTodosFinally
 
 Each step is an **event handler**, not an implicit callback.
 
+Each call gets a `callId`, and every event of that call carries it: `Start` and `Run` get `{ payload, callId }`, `Success` gets `{ result, callId }`, `Error` gets `{ error, callId }` and `Finally` gets `{ callId }`. The `start`, `run`, `success`, `error` and `finally` handlers still receive the payload, result or error alone; the `callId` matters to code that listens to the events directly, such as `optimistic`.
+
 ---
 
 ### Optional `start` handler
@@ -685,6 +692,26 @@ const saveSettings = optimistic(
 
 The wrapper snapshots the keys in the patch, applies them in `Start`, restores the previous values in `Error`, and leaves `Success`/`Finally` handlers in control of cleanup.
 
+Each call keeps its own snapshot, so saves on the same entity can overlap. A failed call restores the keys it patched, except those a later pending call patched too: those go back to what they were before both once that call fails as well, or stay as that call left them.
+
+A patch built on the current value, such as a list with a temporary item added, cannot be undone key by key when two calls change the same list. Give `rollback` to undo the call's own change in place of restoring the snapshot:
+
+```ts
+const addTodo = optimistic(
+  handleAsync("addTodo", {
+    async run(todo) {
+      return api.add(todo)
+    },
+  }),
+  (entity, todo) => ({ todos: [...entity.todos, { ...todo, pending: true }] }),
+  {
+    rollback(entity, todo) {
+      entity.todos = entity.todos.filter(({ id }) => id !== todo.id)
+    },
+  },
+)
+```
+
 ---
 
 ### Reading a store from outside a handler

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "12.1.0",
+  "version": "12.2.0",
   "description": "A state manager for real-time, collaborative apps, inspired by game development patterns and compatible with Redux.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -75,14 +75,14 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@inglorious/utils": "5.1.0",
     "mutative": "^1.3.0"
   },
   "peerDependencies": {
-    "@inglorious/utils": "5.1.0"
+    "@inglorious/utils": "^5.1.0"
   },
   "devDependencies": {
     "@inglorious/eslint-config": "1.2.0",
+    "@inglorious/utils": "5.1.0",
     "@reduxjs/toolkit": "^2.12.0",
     "prettier": "^3.9.6",
     "typescript": "~7.0.2",
@@ -90,7 +90,7 @@
     "vitest": "^5.0.0"
   },
   "engines": {
-    "node": ">= 22"
+    "node": ">= 26"
   },
   "scripts": {
     "format": "prettier --write .",

package/src/behaviors/async.js

@@ -36,6 +36,11 @@
  *   - "type": notify `typeName:event` (broadcasts to all entities of this type)
  *   - "global": notify `event` (global broadcast to any listener)
  *
+ * Each call gets a `callId`, and every event of that call carries it: `Start`
+ * and `Run` get `{ payload, callId }`, `Success` gets `{ result, callId }`,
+ * `Error` gets `{ error, callId }` and `Finally` gets `{ callId }`. The
+ * handlers above still receive the payload, result or error alone.
+ *
  * @returns {Object} An object containing the generated event handlers that can be spread into a type:
  *   - `[type]`: Main trigger - dispatches Start (if defined) and Run events
  *   - `[typeStart]`: (if start handler provided) Executes the start handler
@@ -148,38 +153,39 @@ export function handleAsync(type, handlers, options = {}) {
 
   const asyncHandlers = {
     [type](entity, payload, api) {
+      const callId = nextCallId()
+
       if (handlers.start) {
-        notify(api, entity, `${type}Start`, payload)
+        notify(api, entity, `${type}Start`, { payload, callId })
       }
 
-      notify(api, entity, `${type}Run`, payload)
+      notify(api, entity, `${type}Run`, { payload, callId })
     },
 
     ...(handlers.start && {
-      [`${type}Start`](entity, payload, api) {
+      [`${type}Start`](entity, { payload }, api) {
         handlers.start(entity, payload, api)
       },
     }),
 
-    async [`${type}Run`](entity, payload, api) {
-      // Snapshot routing keys before await — mutative revokes draft proxies after the patch.
+    async [`${type}Run`](entity, { payload, callId }, api) {
       const scopedEntity = { id: entity.id, type: entity.type }
 
       try {
         const result = await handlers.run(payload, api)
-        notify(api, scopedEntity, `${type}Success`, result)
+        notify(api, scopedEntity, `${type}Success`, { result, callId })
       } catch (error) {
-        notify(api, scopedEntity, `${type}Error`, error)
+        notify(api, scopedEntity, `${type}Error`, { error, callId })
       } finally {
-        notify(api, scopedEntity, `${type}Finally`)
+        notify(api, scopedEntity, `${type}Finally`, { callId })
       }
     },
 
-    [`${type}Success`](entity, result, api) {
+    [`${type}Success`](entity, { result }, api) {
       handlers.success?.(entity, result, api)
     },
 
-    [`${type}Error`](entity, error, api) {
+    [`${type}Error`](entity, { error }, api) {
       handlers.error?.(entity, error, api)
     },
 
@@ -196,4 +202,17 @@ export function handleAsync(type, handlers, options = {}) {
   return asyncHandlers
 }
 
+const NEXT = 1
+
+let lastCallId = 0
+
+/**
+ * A new id for one call of an async behavior, which its events carry.
+ * @returns {number}
+ */
+export function nextCallId() {
+  lastCallId += NEXT
+  return lastCallId
+}
+
 export const ASYNC_META = Symbol.for("@inglorious/store/asyncMeta")

package/src/behaviors/optimistic.js

@@ -1,6 +1,8 @@
-import { ASYNC_META } from "./async.js"
+import { ASYNC_META, nextCallId } from "./async.js"
 
 const START = 0
+const NOT_FOUND = -1
+const ONE_CALL = 1
 
 /**
  * Decorates an async behavior with optimistic update boilerplate.
@@ -8,6 +10,16 @@ const START = 0
  * Pass either a static shallow patch object or a factory that returns one.
  * The wrapper applies the patch during `Start` and rolls it back during `Error`.
  *
+ * Each call keeps its own snapshot, so calls on the same entity can overlap. A
+ * failed call restores the keys it patched, except those a later pending call
+ * patched too: that call's own rollback then restores them to what they were
+ * before both.
+ *
+ * A patch built on the current value, such as a list with a temporary item
+ * added, cannot be undone key by key when two calls change the same list. Give
+ * `rollback` instead: it undoes the call's own change in place of restoring
+ * the snapshot.
+ *
  * @template {import('../store').BaseEntity} TEntity
  * @template TPayload
  * @template TResult
@@ -16,6 +28,9 @@ const START = 0
  * @param {import('./async').AsyncEvents<TType, TEntity, TPayload, TResult>} behavior
  * @param {Record<string, any> | ((entity: TEntity, payload: TPayload, api: import('../store').Api) => Record<string, any> | null | undefined)} optimistic
  *   Shallow patch applied optimistically on start, or a factory that returns it.
+ * @param {object} [options]
+ * @param {(entity: TEntity, payload: TPayload, api: import('../store').Api) => void} [options.rollback]
+ *   Undoes a failed call's change, in place of restoring the snapshot.
  *
  * @returns {import('./async').AsyncEvents<TType, TEntity, TPayload, TResult>}
  *
@@ -46,8 +61,23 @@ const START = 0
  *     data: { ...entity.data, ...payload },
  *   }),
  * )
+ *
+ * @example
+ * const addTodo = optimistic(
+ *   handleAsync("addTodo", {
+ *     async run(todo) {
+ *       return api.add(todo)
+ *     },
+ *   }),
+ *   (entity, todo) => ({ todos: [...entity.todos, todo] }),
+ *   {
+ *     rollback(entity, todo) {
+ *       entity.todos = entity.todos.filter(({ id }) => id !== todo.id)
+ *     },
+ *   },
+ * )
  */
-export function optimistic(behavior, optimistic) {
+export function optimistic(behavior, optimistic, { rollback } = {}) {
   const { type, scope } = resolveAsyncMeta(behavior)
 
   const startEvent = `${type}Start`
@@ -55,7 +85,8 @@ export function optimistic(behavior, optimistic) {
   const errorEvent = `${type}Error`
   const finallyEvent = `${type}Finally`
 
-  const snapshots = new Map()
+  /** The calls still pending, by entity id, in the order they started. */
+  const pending = new Map()
 
   function notify(api, entity, event, payload) {
     switch (scope) {
@@ -75,19 +106,16 @@ export function optimistic(behavior, optimistic) {
     ...behavior,
 
     [type](entity, payload, api) {
-      notify(api, entity, startEvent, payload)
-      notify(api, entity, runEvent, payload)
+      const callId = nextCallId()
+      notify(api, entity, startEvent, { payload, callId })
+      notify(api, entity, runEvent, { payload, callId })
     },
 
-    [startEvent](entity, payload, api) {
+    [startEvent](entity, event, api) {
+      const { payload, callId } = event
       const patch = toPatch(optimistic, entity, payload, api)
 
-      if (!patch) {
-        behavior[startEvent]?.(entity, payload, api)
-        return
-      }
-
-      if (typeof patch !== "object") {
+      if (patch && typeof patch !== "object") {
         throw new TypeError(
           "optimistic expects the patch to be an object or a factory that returns an object",
         )
@@ -95,25 +123,46 @@ export function optimistic(behavior, optimistic) {
 
       const key = getEntityKey(entity)
       const currentEntity = api.getEntity?.(key) ?? entity
-      snapshots.set(key, snapshotPatch(currentEntity, patch))
-      Object.assign(entity, patch)
-
-      behavior[startEvent]?.(entity, payload, api)
+      const calls = pending.get(key) ?? []
+      calls.push({
+        callId,
+        payload,
+        snapshot: snapshotPatch(currentEntity, patch ?? {}),
+      })
+      pending.set(key, calls)
+      if (patch) Object.assign(entity, patch)
+
+      behavior[startEvent]?.(entity, event, api)
     },
 
     [runEvent]: behavior[runEvent],
 
-    [errorEvent](entity, error, api) {
-      const key = getEntityKey(entity)
-      restorePatch(entity, snapshots.get(key))
-      behavior[errorEvent]?.(entity, error, api)
+    [errorEvent](entity, event, api) {
+      const calls = pending.get(getEntityKey(entity)) ?? []
+      const index = calls.findIndex(({ callId }) => callId === event.callId)
+
+      if (index !== NOT_FOUND) {
+        const [call] = calls.splice(index, ONE_CALL)
+        if (rollback) {
+          rollback(entity, call.payload, api)
+        } else {
+          restorePatch(entity, call.snapshot, calls.slice(index))
+        }
+      }
+
+      behavior[errorEvent]?.(entity, event, api)
     },
 
-    [finallyEvent](entity, payload, api) {
+    [finallyEvent](entity, event, api) {
       try {
-        behavior[finallyEvent]?.(entity, payload, api)
+        behavior[finallyEvent]?.(entity, event, api)
       } finally {
-        snapshots.delete(getEntityKey(entity))
+        const key = getEntityKey(entity)
+        const calls = (pending.get(key) ?? []).filter(
+          ({ callId }) => callId !== event?.callId,
+        )
+        if (calls.length) pending.set(key, calls)
+        else pending.delete(key)
       }
     },
   }
@@ -168,27 +217,21 @@ function toPatch(optimistic, entity, payload, api) {
 }
 
 function snapshotPatch(entity, patch) {
-  const entries = []
-
-  for (const key of Object.keys(patch)) {
-    entries.push([
+  return new Map(
+    Object.keys(patch).map((key) => [
       key,
-      Object.prototype.hasOwnProperty.call(entity, key),
-      entity[key],
-    ])
-  }
-
-  return entries
+      { existed: Object.hasOwn(entity, key), value: entity[key] },
+    ]),
+  )
 }
 
-function restorePatch(entity, entries) {
-  if (!entries) {
-    return
-  }
-
-  for (const [key, existed, value] of entries) {
-    if (existed) {
-      entity[key] = value
+function restorePatch(entity, snapshot, laterCalls) {
+  for (const [key, before] of snapshot) {
+    const later = laterCalls.find((call) => call.snapshot.has(key))
+    if (later) {
+      later.snapshot.set(key, before)
+    } else if (before.existed) {
+      entity[key] = before.value
     } else {
       delete entity[key]
     }

package/src/behaviors/state-machine/fsm.js

@@ -20,12 +20,6 @@ export function fsm(states) {
           [eventName](entity, event, api) {
             const from = entity.state
 
-            // A state answers for itself, and what it has to say replaces what the type
-            // would have said. The type-stage handler is the default -- the thing every
-            // state would otherwise do -- and a state takes it over by naming the same
-            // event, which is how a state can take the way out for itself rather than
-            // being quit by, without whatever answers by default having to know that
-            // state exists.
             const handler = states[entity.state]?.[eventName] ?? type[eventName]
 
             handler?.(entity, event, api)

package/src/behaviors/state-machine/scenes.js

@@ -59,10 +59,6 @@ export function scenes(scenesByState) {
         continue
       }
 
-      // The same thing stands on both sides of the move, so it is neither added nor
-      // removed -- but it may be wanted to be a different thing now, and then only what
-      // has actually changed is merged over it. That is what leaves a shared thing where
-      // the world had put it when the next state says nothing different about it.
       const previous = leaving.find(({ id }) => id === added.id)
 
       if (!isDeepEqual(previous, added)) {
@@ -78,8 +74,6 @@ export function scenes(scenesByState) {
       build(entity, entity.state, api)
     },
 
-    // The announcement is broadcast and carries the id, so that anything else listening
-    // for it can tell which machine moved. This one is only interested in its own.
     stateChange(entity, { entityId, to }, api) {
       if (entityId !== entity.id) return
 

package/src/client/devtools.js

@@ -2,21 +2,10 @@ import { deserialize } from "@inglorious/utils/object.js"
 
 const LAST_STATE = 1
 
-// HMR-safe container to persist a single DevTools connection across Vite reloads.
-// Uses import.meta.hot.data when available (preferred), falls back to module scope.
 const globalContainer = import.meta.hot
   ? ((import.meta.hot.data ??= {}).__INGLORIOUS_DEVTOOLS__ ??= {})
   : {}
 
-// connection shape: {
-//   devToolsInstance,
-//   unsubscribe,
-//   store,
-//   updateMode,
-//   restoreSetState: () => void,
-// }
-
-// Unified API for cleaner integration across apps and engine
 export function createDevtools(config = {}) {
   return {
     connect(store) {
@@ -51,12 +40,10 @@ export function createDevtools(config = {}) {
 function connectDevTools(store, config = {}) {
   const updateMode = config.updateMode ?? "auto"
 
-  // Prevent duplicate connections; rewire if store or update mode changed
   const existing = getConnection()
   if (existing) {
     const sameMode = existing.updateMode === updateMode
     if (sameMode) {
-      // Hot-swap store without resetting DevTools history
       existing.restoreSetState?.()
       const baseSetState = store.setState
       const restoreSetState =
@@ -79,7 +66,6 @@ function connectDevTools(store, config = {}) {
       existing.restoreSetState = restoreSetState
     }
 
-    // Different update mode: fully disconnect previous and proceed
     try {
       existing.unsubscribe?.()
     } finally {
@@ -104,7 +90,6 @@ function connectDevTools(store, config = {}) {
       : () => {
           // noop; we didn't wrap setState
         }
-  // Only add setState side-effects in auto update mode; manual update mode logs explicitly from engine.
   if (updateMode === "auto") {
     store.setState = (newState) => {
       baseSetState(newState)
@@ -114,19 +99,17 @@ function connectDevTools(store, config = {}) {
 
   const devToolsInstance = window.__REDUX_DEVTOOLS_EXTENSION__.connect({
     name,
-    // predicate: // doesn't work
-    // @see https://github.com/reduxjs/redux-devtools/blob/main/extension/docs/API/Arguments.md#features
     features: {
-      pause: true, // start/pause recording of dispatched actions
-      lock: true, // lock/unlock dispatching actions and side effects
-      persist: true, // persist states on page reloading
-      export: true, // export history of actions in a file
-      import: "custom", // import history of actions from a file
-      jump: false, // jump back and forth (time travelling)
-      skip: false, // skip (cancel) actions
-      reorder: false, // drag and drop actions in the history list
-      dispatch: true, // dispatch custom actions or action creators
-      test: false, // generate tests for the selected actions
+      pause: true,
+      lock: true,
+      persist: true,
+      export: true,
+      import: "custom",
+      jump: false,
+      skip: false,
+      reorder: false,
+      dispatch: true,
+      test: false,
     },
   })
 
@@ -154,9 +137,6 @@ function connectDevTools(store, config = {}) {
 }
 
 function disconnectDevTools() {
-  // The `disconnect` method on the devToolsInstance is not available in all
-  // environments or versions of the extension.
-  // Safest is to unsubscribe and release our reference, and restore setState.
   const existing = getConnection()
   if (!existing) return
   try {
@@ -171,7 +151,6 @@ function handleDispatch(message) {
   const { store } = getConnection() ?? {}
   if (!store) return
   switch (message.payload.type) {
-    // reset button
     case "RESET": {
       store.reset()
       const existing = getConnection()
@@ -179,21 +158,18 @@ function handleDispatch(message) {
       break
     }
 
-    // revert button
     case "ROLLBACK": {
       const newState = deserialize(message.state)
       store.setState(newState)
       break
     }
 
-    // commit button
     case "COMMIT": {
       const existing = getConnection()
       existing?.devToolsInstance?.init(store.getState())
       break
     }
 
-    // import from file button
     case "IMPORT_STATE": {
       const { computedStates, actionsById } = message.payload.nextLiftedState
 

package/src/client/multiplayer-middleware.js

@@ -18,7 +18,6 @@ export function multiplayerMiddleware(config = {}) {
   let ws = null
   const localQueue = []
 
-  // The middleware function that will be applied to the store.
   return (store) => {
     const next = store.dispatch
     store.dispatch = (event) => send(store, event, next)
@@ -38,7 +37,6 @@ export function multiplayerMiddleware(config = {}) {
       return next(event)
     }
 
-    // Establish the connection on the first event.
     if (!ws) {
       establishConnection(store)
     }
@@ -51,8 +49,6 @@ export function multiplayerMiddleware(config = {}) {
       }
     }
 
-    // Pass the event to the next middleware in the chain,
-    // which is eventually the store's original dispatch function.
     return next(event)
   }
 
@@ -60,18 +56,12 @@ export function multiplayerMiddleware(config = {}) {
    * Attempts to establish a WebSocket connection to the server.
    */
   function establishConnection(store) {
-    // If a connection already exists, close it first.
     if (ws) {
       ws.close()
     }
     ws = new WebSocket(serverUrl)
 
-    // =====================================================================
-    // WebSocket Event Handlers
-    // =====================================================================
-
     ws.onopen = () => {
-      // Send any queued events to the server.
       while (localQueue.length) {
         ws.send(serialize(localQueue.shift()))
       }
@@ -81,22 +71,19 @@ export function multiplayerMiddleware(config = {}) {
       const serverEvent = deserialize(event.data)
 
       if (serverEvent.type === "stateInit") {
-        // Merge the server's initial state with the client's local state.
         const nextState = extend(store.getState(), serverEvent.payload)
         store.setState(nextState)
       } else {
-        // Dispatch the event to the local store to update the client's state.
         store.dispatch({ ...serverEvent, fromServer: true })
       }
     }
 
     ws.onclose = () => {
-      // Attempt to reconnect after a short delay.
       setTimeout(() => establishConnection(store), reconnectionDelay)
     }
 
     ws.onerror = () => {
-      ws.close() // The 'onclose' handler will trigger the reconnect.
+      ws.close()
     }
   }
 }

package/src/event-map.js

@@ -8,6 +8,10 @@ const SPLIT_LIMIT = 2
 /**
  * A class to manage the mapping of event names to the entity IDs that handle them.
  * This is used for optimized event handling with support for scoped events.
+ *
+ * Do not replace it with a scan of all entities: every event would then visit
+ * every entity, and a game dispatching dozens of events a frame over thousands
+ * of entities cannot afford that (see the comparison in event-map.test.js).
  */
 export class EventMap {
   /**
@@ -118,13 +122,11 @@ export class EventMap {
       return entitySet && entitySet.has(targetEntityId) ? [targetEntityId] : []
     }
 
-    // form:submit - all entities of this type
     if (targetType) {
       const entitySet = typeMap.get(targetType)
       return entitySet ? Array.from(entitySet) : []
     }
 
-    // submit - all entities with this handler (broadcast)
     const allEntities = []
     for (const entitySet of typeMap.values()) {
       allEntities.push(...entitySet)

package/src/migration/rtk.js

@@ -76,8 +76,6 @@ export function convertAsyncThunk(name, payloadCreator, options = {}) {
         : undefined,
 
       run: async (payload, api) => {
-        // RTK payloadCreator signature: (arg, thunkAPI)
-        // Use dispatch for action compatibility, with notify fallback in tests/minimal APIs.
         const dispatch = api.dispatch
           ? api.dispatch.bind(api)
           : (action) => {
@@ -170,15 +168,12 @@ export function convertSlice(slice, options = {}) {
   const { asyncThunks = {}, extraHandlers = {}, extraActions = [] } = options
 
   const type = {
-    // Convert initialState to create handler.
-    // Preserve explicitly preloaded fields from entities (common in tests/SSR hydration).
     create(entity) {
       const initialState = slice.getInitialState()
       Object.assign(entity, extend(initialState, entity))
     },
   }
 
-  // Convert each reducer to an event handler
   for (const [actionName, reducer] of Object.entries(slice.caseReducers)) {
     const thunkConfig = asyncThunks[actionName]
     const isAsyncThunkReducer =
@@ -249,22 +244,15 @@ export function convertSlice(slice, options = {}) {
     }
 
     const handler = (entity, payload) => {
-      // Create a mock action object for the RTK reducer
       const action = { type: `${slice.name}/${actionName}`, payload }
 
-      // RTK reducers expect to mutate state directly (via Immer)
-      // Inglorious handlers do the same (via Mutative)
-      // So we can call the reducer directly on the entity
       reducer(entity, action)
     }
 
-    // Expose both Inglorious-style event names and RTK action-type aliases.
-    // This enables direct dispatch of RTK slice actions without extra bridge wiring.
     type[actionName] = handler
     type[`${slice.name}/${actionName}`] = handler
   }
 
-  // Convert explicitly configured async thunks that are not embedded in slice reducers.
   for (const [thunkName, thunkHandlers] of Object.entries(asyncThunks)) {
     if (thunkHandlers?.payloadCreator && !type[thunkName]) {
       const asyncHandlers = convertAsyncThunk(
@@ -283,9 +271,6 @@ export function convertSlice(slice, options = {}) {
     }
   }
 
-  // Register additional RTK action types (e.g. createAction + extraReducers).
-  // RTK does not expose extraReducers through slice.caseReducers, so callers can
-  // provide the action creators/types explicitly and we route them through slice.reducer.
   for (const action of extraActions) {
     const actionType = typeof action === "string" ? action : action?.type
     if (typeof actionType !== "string" || type[actionType]) continue
@@ -295,7 +280,6 @@ export function convertSlice(slice, options = {}) {
     }
   }
 
-  // Add any extra handlers
   Object.assign(type, extraHandlers)
 
   return type
@@ -330,7 +314,6 @@ export function createMigrationGuide(slice) {
   lines.push("=".repeat(SEP_LENGTH))
   lines.push("")
 
-  // Show state structure
   lines.push("STATE STRUCTURE:")
   lines.push("RTK:")
   lines.push(
@@ -350,7 +333,6 @@ export function createMigrationGuide(slice) {
   lines.push("=".repeat(SEP_LENGTH))
   lines.push("")
 
-  // Show each reducer conversion
   lines.push("ACTIONS / EVENTS:")
   for (const actionName of Object.keys(slice.caseReducers)) {
     lines.push("")
@@ -365,7 +347,6 @@ export function createMigrationGuide(slice) {
   lines.push("=".repeat(SEP_LENGTH))
   lines.push("")
 
-  // Show selector conversion
   lines.push("SELECTORS:")
   lines.push("RTK:")
   lines.push(
@@ -403,22 +384,17 @@ export function createMigrationGuide(slice) {
 export function createRTKCompatDispatch(api, entityId) {
   return (action) => {
     if (typeof action === "function") {
-      // Thunk - not supported in compat mode
       console.warn("Thunks are not supported in RTK compat mode")
       return
     }
 
-    // Extract action type and payload
     const { type, payload } = action
 
-    // Convert RTK action type to Inglorious event
-    // RTK: 'todos/addTodo' -> Inglorious: '#todos:addTodo'
     const parts = type.split("/")
     if (parts.length === SLICE_PLUS_ACTION) {
       const [, actionName] = parts
       api.notify(`#${entityId}:${actionName}`, payload)
     } else {
-      // Fallback for non-standard action types
       api.notify(`#${entityId}:${type}`, payload)
     }
   }

package/src/store.js

@@ -72,7 +72,7 @@ export function createStore({
     subscribe,
     update,
     notify,
-    dispatch, // needed for compatibility with Redux
+    dispatch,
     getTypes,
     getType,
     setType,
@@ -119,10 +119,6 @@ export function createStore({
       return []
     }
 
-    // Nothing queued means nothing to apply and nothing to publish: skipping the draft
-    // entirely, rather than copying the world just to arrive back where it started.
-    // This is what keeps a loop that pumps every animation frame cheap on the frames
-    // where neither the game nor the player had anything to say.
     if (!incomingEvents.length) {
       return []
     }
@@ -172,9 +168,6 @@ export function createStore({
         const event = incomingEvents.shift()
         processedEvents.push(event)
 
-        // Pausing and resuming are the store's own, and they keep dispatching like any
-        // other event, so the game behaviour still sees them and anything else that
-        // wants to react gets the same notification.
         if (event.type === "pause") {
           isHalted = true
         }
@@ -183,24 +176,6 @@ export function createStore({
           isHalted = false
         }
 
-        // Handle special system events
-        // `add` and `remove` change the world and are then dispatched like any
-        // other event, so that whatever is watching can hear about it. They are
-        // broadcast: the entity named by the payload is not the only one that wants
-        // to know, and something counting down what it put up needs to hear about
-        // each of them going.
-        //
-        // They are not the counterpart to `create` and `destroy`, which reach only
-        // the entity they are about so that those read as a constructor and a
-        // destructor without every handler beginning by checking whether it is the
-        // one being talked about.
-        //
-        // The two carry different payloads, and that is on purpose: a payload
-        // carries the least that can be had. A removal needs only the id, because
-        // everything else about the entity can still be looked up by it. An
-        // addition carries the entity itself, because there is nothing yet to look
-        // it up by -- the same asymmetry as removing a user by id but updating one
-        // by the patched user.
         if (event.type === "add") {
           addEntity(draft, event.payload)
         }
@@ -209,21 +184,6 @@ export function createStore({
           removeEntity(draft, event.payload)
         }
 
-        // A thing that stands through a change of state can still be told a different
-        // configuration, in either of the two ways the world offers.
-        //
-        // `patch` changes some of it and leaves the rest alone, which is how a screen
-        // takes over one field of something it shares with the screen before it. A field
-        // named as `undefined` is set to nothing rather than being left alone, which is
-        // how a key is taken off a mapping.
-        //
-        // `replace` installs what it is given and drops everything it does not mention,
-        // which is how the whole of something is said to be different.
-        //
-        // Neither takes the thing out of the world, so neither runs `create` or `destroy`:
-        // it never stopped standing, and a thing that was never removed cannot have been
-        // destroyed. This is the same pair the world has to hand for anything else --
-        // `add` and `remove` beside them, and post/delete/put/patch before that.
         if (event.type === "patch") {
           patchEntity(draft, event.payload)
         }
@@ -232,10 +192,8 @@ export function createStore({
           replaceEntity(draft, event.payload)
         }
 
-        // Parse the event to get handler name
         const { event: handlerName } = parseEvent(event.type)
 
-        // Get entities that should handle this event (filtered by EventMap)
         const entityIds = eventMap.getEntitiesForEvent(event.type)
 
         // A halted world stops handing out updates, because anything that moves by
@@ -248,8 +206,6 @@ export function createStore({
         const halted = isHalted && handlerName === "update"
 
         for (const id of entityIds) {
-          // Looked at before it is taken, because an entity the pause holds back is
-          // not going to be written to, and taking it would copy it for nothing.
           const entity = draft.entities[id]
           const type = types[entity.type]
 
@@ -273,7 +229,6 @@ export function createStore({
           }
         }
 
-        // Systems process events by handler name (not scoped)
         systems.forEach((system) => {
           const handle = system[handlerName]
           handle?.(draft.forSystems, event.payload, api)
@@ -338,7 +293,8 @@ export function createStore({
    * Sets an augmented type configuration given its name. Replacing a type, as
    * hot module reloading does, notifies subscribers, since what its entities
    * render may have changed. Adding a type does not: the store is unchanged,
-   * and a type can be added while rendering.
+   * and a type can be added while rendering. Entities already of a type being
+   * added get their `create` now: when they were added, it reached no handler.
    * @param {string} typeName - The name of the type to set.
    * @param {Type} type - The type configuration.
    * @returns {void}
@@ -354,6 +310,7 @@ export function createStore({
       if (entity.type === typeName) {
         eventMap.removeEntity(id, oldType, typeName)
         eventMap.addEntity(id, newType, typeName)
+        if (!oldType) notify(`#${id}:create`)
       }
     }
 
@@ -516,9 +473,6 @@ export function createStore({
     // does not mention, and what it keeps must not be shared with the previous state.
     const existing = draft.take(id)
 
-    // Configuring something that is not there is not a thing that can be done. The world
-    // is built in one pass, so a scene naming a thing another scene is yet to put up is
-    // ordinary rather than a mistake, and is not worth failing over.
     if (!existing) return
 
     draft.put(id, augmentEntity(id, { ...existing, ...config }))

package/types/api.d.ts

@@ -36,7 +36,7 @@ export interface Api<
   select: <TResult>(selector: (state: TState) => TResult) => TResult
   dispatch: (event: Event) => void
   notify: (type: string, payload?: any) => void
-  [key: string]: any // For middleware extras
+  [key: string]: any
 }
 
 /**

package/types/behaviors/async.d.ts

@@ -73,6 +73,9 @@ export interface AsyncHandlers<
  * ```
  *
  * The `scope` option changes where the events are sent, not their names.
+ *
+ * Each call gets a `callId` that all its events carry, so that a wrapper such
+ * as `optimistic` can tell overlapping calls apart.
  */
 export type AsyncEvents<
   TType extends string,
@@ -85,27 +88,38 @@ export type AsyncEvents<
 } & {
   [K in `${TType}Start`]?: (
     entity: TEntity,
-    payload: TPayload,
+    event: AsyncCall<{ payload: TPayload }>,
     api: TApi,
   ) => void
 } & {
   [K in `${TType}Run`]: (
     entity: TEntity,
-    payload: TPayload,
+    event: AsyncCall<{ payload: TPayload }>,
     api: TApi,
   ) => Promise<void>
 } & {
   [K in `${TType}Success`]: (
     entity: TEntity,
-    result: TResult,
+    event: AsyncCall<{ result: TResult }>,
     api: TApi,
   ) => void
 } & {
-  [K in `${TType}Error`]: (entity: TEntity, error: any, api: TApi) => void
+  [K in `${TType}Error`]: (
+    entity: TEntity,
+    event: AsyncCall<{ error: any }>,
+    api: TApi,
+  ) => void
 } & {
-  [K in `${TType}Finally`]: (entity: TEntity, payload: void, api: TApi) => void
+  [K in `${TType}Finally`]: (
+    entity: TEntity,
+    event: AsyncCall,
+    api: TApi,
+  ) => void
 }
 
+/** What an event of one call of an async behavior carries: its `callId`. */
+export type AsyncCall<T = {}> = T & { callId: number }
+
 /**
  * Creates a set of event handlers for managing an asynchronous operation lifecycle.
  *

package/types/behaviors/optimistic.d.ts

@@ -1,5 +1,5 @@
 import { Api } from "../api"
-import { AsyncEvents } from "./async"
+import { AsyncCall, AsyncEvents } from "./async"
 import { BaseEntity } from "../store"
 
 /**
@@ -9,6 +9,10 @@ import { BaseEntity } from "../store"
  * The wrapper snapshots the current values for those keys, applies the patch
  * on start, and restores the previous values automatically if the operation fails.
  *
+ * Each call keeps its own snapshot, so calls can overlap. Give `rollback` to
+ * undo a failed call's change yourself, such as removing the temporary item it
+ * added to a list, in place of restoring the snapshot.
+ *
  * The behavior keeps the events `handleAsync` named and typed, and always has
  * a start event.
  */
@@ -27,10 +31,13 @@ export function optimistic<
         payload: TPayload,
         api: TApi,
       ) => Record<string, any> | null | undefined),
+  options?: {
+    rollback?: (entity: TEntity, payload: TPayload, api: TApi) => void
+  },
 ): AsyncEvents<TType, TEntity, TPayload, TResult, TApi> & {
   [K in `${TType}Start`]: (
     entity: TEntity,
-    payload: TPayload,
+    event: AsyncCall<{ payload: TPayload }>,
     api: TApi,
   ) => void
 }

package/types/migration/rtk.d.ts

@@ -6,8 +6,6 @@ import { Api, BaseEntity } from "../store"
  */
 export interface ThunkAPI {
   dispatch: Api["notify"]
-  // Add other thunk API properties as needed
-  // getState, extra, requestId, signal, rejectWithValue, fulfillWithValue
 }
 
 /**