@inglorious/store 11.0.1 → 11.0.3

package/README.md

@@ -30,7 +30,7 @@ Game engines solved state complexity years ago — Inglorious Store brings those
 - ✅ Entity-based state (manage multiple instances effortlessly)
 - ✅ No action creators, thunks, or slices
 - ✅ Predictable, testable, purely functional code
-- ✅ Built-in lifecycle events (`add`, `remove`)
+- ✅ Built-in lifecycle events (`add`, `remove`, `patch`, `replace`)
 - ✅ 10x faster immutability than Redux Toolkit (Mutative vs Immer)
 
 ---
@@ -364,6 +364,56 @@ Inglorious Store has a few built-in events that you can use:
 
 - `add`: adds a new entity to the state. Triggers a `create` lifecycle event.
 - `remove`: removes an entity from the state. Triggers a `destroy` lifecycle event.
+- `patch`: changes some of a standing entity and leaves the rest alone.
+- `replace`: installs a new configuration on a standing entity, dropping what it does
+  not mention.
+
+`patch` and `replace` cover the case `add` and `remove` do not: changing something that is
+already in the world without taking it out of it. They are the same pair the web settled
+long ago — `POST`, `DELETE`, `PUT`, `PATCH` — for the same reason:
+
+```javascript
+// A patch touches only what it names. Anything else the entity already had survives,
+// which is what makes it safe to nudge part of something mid-flight.
+store.notify("patch", { id: "counter1", value: 10 })
+
+// A replace says the whole of it is different, so anything it does not name is gone.
+store.notify("replace", { id: "counter1", type: "Counter", value: 10 })
+```
+
+A field set to `undefined` is set to _nothing_ in either, rather than being left alone:
+
+```javascript
+// The key stops being mapped. This is not the same as saying nothing about it, which
+// would leave whatever it was mapped to last time standing.
+store.notify("patch", {
+  id: "keyboard",
+  mapping: { Escape: "pause", ArrowUp: undefined },
+})
+```
+
+Neither runs `create` or `destroy`: the entity never stopped standing, and something that
+was never removed cannot have been destroyed. Naming a different `type` in either moves
+the entity onto that type's handlers.
+
+The practical use is a world whose rules change with its state — a keyboard whose keys
+mean one thing on a menu and another in play:
+
+```javascript
+const types = {
+  Keyboard: { keyDown: (entity, key) => report(key) },
+  Game: [
+    scenes({
+      menu: () => [{ id: "keyboard", type: "Keyboard", mapping: MENU_KEYS }],
+      play: () => [{ id: "keyboard", type: "Keyboard", mapping: PLAY_KEYS }],
+    }),
+    fsm({/* … */}),
+  ],
+}
+```
+
+The keyboard is one keyboard, not two: the mapping is patched when the state moves, and
+`isDeepEqual` from `@inglorious/utils` is what tells the two apart.
 
 The lifecycle events can be used to define event handlers similar to constructor and destructor methods in OOP:
 
@@ -634,6 +684,19 @@ The wrapper snapshots the keys in the patch, applies them in `Start`, restores t
 
 ---
 
+### Reading a store from outside a handler
+
+`api.getEntity` is the answer during a handler. Outside one — a test driving a world, or
+anything else holding the store rather than an event — the store says the same thing
+itself:
+
+```javascript
+store.getEntity("user") // one entity, or undefined
+store.getState() // the lot
+```
+
+There is one lookup rather than two spellings of it: `api.getEntity` asks the store.
+
 ### Event scoping
 
 By default, lifecycle events are **scoped to the triggering entity**:
@@ -1072,6 +1135,7 @@ const store = createStore({
   systems, // Array (optional): global state handlers
   autoCreateEntities, // Boolean (optional): false (default) or true
   updateMode, // String (optional): 'auto' (default) or 'manual'
+  updateStrategy, // String (optional): 'structural-sharing' (default) or 'full-clone'
 })
 ```
 
@@ -1088,6 +1152,79 @@ const store = createStore({
 - **`updateMode`** (optional) - Controls when React components re-render:
   - `'auto'` (default) - Automatic updates after each event
   - `'manual'` - Manual control via `api.update()`
+- **`updateStrategy`** (optional) - Controls how the state is copied before queued events are applied:
+  - `'structural-sharing'` (default) - Only the entities that actually changed are copied
+  - `'full-clone'` - The whole state is deep-cloned and updated without a proxy
+
+#### Update Strategy
+
+`updateStrategy` decides how much copying work each update does. It exists because the right
+answer depends on how many entities change per update.
+
+**`'structural-sharing'`** (default) applies events to a draft proxy (via
+[Mutative](https://github.com/pmndrs/mutative)), so only the entities that actually changed
+get copied. Untouched entities keep their previous object reference, which makes
+reference-equality change detection nearly free. This is what you want for UI stores, where a
+handful of entities change per interaction.
+
+**`'full-clone'`** deep-clones the entire state with `structuredClone` and applies events directly to
+the copy, with no proxy involved. Every update costs time proportional to the total state size,
+but there's no per-entity proxy overhead, so it scales much better when thousands of entities
+change every frame — the typical case for a game simulation.
+
+```javascript
+// A UI store: few entities change, reference equality matters
+const store = createStore({
+  types,
+  entities,
+  updateStrategy: "structural-sharing",
+})
+
+// A game simulation: thousands of entities change every frame
+const store = createStore({ types, entities, updateStrategy: "full-clone" })
+```
+
+#### State swapping
+
+Both strategies keep the current state intact while the queued events are applied to a separate
+draft, and swap the two only once every event has been processed. Handlers and systems always
+receive that draft as their first argument and mutate it directly, and subscribers are notified
+only after the swap.
+
+A consequence worth knowing: during an update, `api.getEntity()` and `api.getEntities()` read the
+**previous** state, not the in-flight changes. This holds under both strategies, so code that
+needs to read another entity's up-to-date value must go through the event payload, or read it in
+a system that runs after the entity handlers.
+
+```javascript
+const types = {
+  Counter: {
+    // Reads the previous value of `other`, not the value set earlier in this same update.
+    increment(entity, payload, api) {
+      entity.previous = api.getEntity("other").count
+    },
+  },
+}
+```
+
+**Caveats for `'full-clone'`:**
+
+- Every value in the state must be [structured-cloneable](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
+  Functions, DOM nodes, and class instances with non-cloneable internals throw a
+  `DataCloneError`. Keep such values in module scope or in a closure inside a behavior factory
+  (as the `images()` and `audio()` engine behaviors do) rather than in the state.
+- The state is not frozen, even in `devMode`.
+- Writing to an entity obtained from `api.getEntity()` during an update mutates the _previous_
+  state and is discarded, because the draft is a deep copy. Under `'structural-sharing'` the
+  draft may still share that reference, so the write happens to survive. Always mutate the
+  entity passed to your handler rather than one fetched through the api.
+
+An unsupported strategy throws a `TypeError` at store creation:
+
+```javascript
+createStore({ types, entities, updateStrategy: "immutable" })
+// TypeError: Unsupported update strategy: immutable. Expected one of: structural-sharing, full-clone.
+```
 
 #### Auto-Create Entities
 
@@ -1182,6 +1319,54 @@ Each handler receives three arguments:
 
 - **`create(entity)`** - triggered when entity added via `add` event, visible only to that entity
 - **`destroy(entity)`** - triggered when entity removed via `remove` event, visible only to that entity
+- **`pause`** - halts the world, see below
+- **`resume`** - unhalts it
+- **`add` / `remove`** - put a thing into the world or take it out, triggering `create` / `destroy`
+- **`patch` / `replace`** - change a thing that is already standing, the first touching only
+  what it names and the second installing all of it
+- **`update`** - the frame tick, disabled while the world is paused
+
+#### Pausing the world
+
+`notify("pause")` stops the store handing out `update` events, and `notify("resume")` starts it again:
+
+```javascript
+store.notify("pause")
+store.notify("update")
+store.update() // nothing updated
+
+store.notify("resume")
+store.notify("update")
+store.update() // updated as normal
+```
+
+This is for anything that moves by integrating a delta time. Those entities do not need to know about pausing at all: their `update` is simply never called, so they cannot drift.
+
+Everything else keeps flowing. Input handlers, custom events and rendering are untouched, which is what lets a pause screen take itself back off:
+
+```javascript
+// Still works while the world is halted
+pauseMenu.pause(entity, _, api) {
+  api.notify("resume")
+}
+```
+
+An entity opts out by setting `updatesWhilePaused`, which is for overlays and menus rather than for gameplay:
+
+```javascript
+const Overlay = [{ update(entity, dt) { entity.ticks++ } }]
+
+// in entities
+overlay: { type: "Overlay", updatesWhilePaused: true }
+```
+
+It is a property of the entity rather than of the type so that a type stays a plain index signature of handlers, which is what keeps it freely callable and indexable from TypeScript.
+
+The default is to **stop**. Anything that keeps updating has to say so, so forgetting a flag pauses the thing you meant to pause rather than freezing the menu.
+
+`reset()` clears the halt, so replacing the entities does not leave the world frozen.
+
+Note that `pause` and `resume` keep dispatching like any other event, unlike `add` and `remove`. The store acts on them _and_ every type that handles them still gets called, so one notification can both halt the world and let the game record why.
 
 ### Notify vs Dispatch
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "11.0.1",
+  "version": "11.0.3",
   "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",
@@ -55,18 +55,18 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@inglorious/utils": "3.8.0",
+    "@inglorious/utils": "5.0.0",
     "mutative": "^1.3.0"
   },
   "peerDependencies": {
-    "@inglorious/utils": "3.8.0"
+    "@inglorious/utils": "5.0.0"
   },
   "devDependencies": {
     "@inglorious/eslint-config": "1.1.2",
-    "@reduxjs/toolkit": "^2.11.2",
-    "prettier": "^3.6.2",
-    "vite": "^7.1.3",
-    "vitest": "^1.6.1"
+    "@reduxjs/toolkit": "^2.12.0",
+    "prettier": "^3.9.6",
+    "vite": "^8.2.2",
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">= 22"

package/src/api.js

@@ -37,10 +37,14 @@ export function createApi(store, extras) {
     },
     /**
      * Retrieves a single entity by ID.
+     *
+     * The store answers this for itself, so there is one lookup rather than two
+     * spellings of the same one.
+     *
      * @param {string} id
      * @returns {Object | undefined}
      */
-    getEntity: (id) => store.getState()[id],
+    getEntity: store.getEntity,
     /**
      * Runs a selector against the current state.
      *

package/src/client/devtools.js

@@ -1,4 +1,4 @@
-import { deserialize } from "@inglorious/utils/data-structures/object.js"
+import { deserialize } from "@inglorious/utils/object.js"
 
 const LAST_STATE = 1
 
@@ -55,21 +55,21 @@ function connectDevTools(store, config = {}) {
       // Hot-swap store without resetting DevTools history
       existing.restoreSetState?.()
       const baseSetState = store.setState
-      let restoreSetState = null
+      const restoreSetState =
+        updateMode === "auto"
+          ? () => {
+              if (store.setState !== baseSetState) {
+                store.setState = baseSetState
+              }
+            }
+          : () => {
+              // no-op when not wrapping setState
+            }
       if (updateMode === "auto") {
-        restoreSetState = () => {
-          if (store.setState !== baseSetState) {
-            store.setState = baseSetState
-          }
-        }
         store.setState = (newState) => {
           baseSetState(newState)
           sendAction({ type: "stateInit", payload: newState }, store.getState())
         }
-      } else {
-        restoreSetState = () => {
-          // no-op when not wrapping setState
-        }
       }
       existing.store = store
       existing.restoreSetState = restoreSetState
@@ -90,22 +90,22 @@ function connectDevTools(store, config = {}) {
 
   const name = config.name ?? document.title
   const baseSetState = store.setState
-  let restoreSetState = null
+  const restoreSetState =
+    updateMode === "auto"
+      ? () => {
+          if (store.setState !== baseSetState) {
+            store.setState = baseSetState
+          }
+        }
+      : () => {
+          // 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") {
-    restoreSetState = () => {
-      if (store.setState !== baseSetState) {
-        store.setState = baseSetState
-      }
-    }
     store.setState = (newState) => {
       baseSetState(newState)
       sendAction({ type: "stateInit", payload: newState }, store.getState())
     }
-  } else {
-    restoreSetState = () => {
-      // noop; we didn't wrap setState
-    }
   }
 
   const devToolsInstance = window.__REDUX_DEVTOOLS_EXTENSION__.connect({

package/src/client/multiplayer-middleware.js

@@ -1,19 +1,25 @@
-import {
-  deserialize,
-  serialize,
-} from "@inglorious/utils/data-structures/object.js"
-import { extend } from "@inglorious/utils/data-structures/objects.js"
-
-// A constant for the server's WebSocket URL.
-const DEFAULT_SERVER_URL = `ws://${window.location.hostname}:3000`
+import { deserialize, extend, serialize } from "@inglorious/utils/object.js"
+
 const DEFAULT_RECONNECTION_DELAY = 1000
 
+/**
+ * Where the server is, when the caller has not said.
+ *
+ * Read when it is asked for rather than when this module is imported, so that importing it
+ * does not require a browser -- which is what lets the store be imported anywhere.
+ *
+ * @returns {string} The server's WebSocket URL.
+ */
+function defaultServerUrl() {
+  return `ws://${window.location.hostname}:3000`
+}
+
 /**
  * Creates and returns the multiplayer middleware.
  * @returns {Function} The middleware function.
  */
 export function multiplayerMiddleware(config = {}) {
-  const serverUrl = config.serverUrl ?? DEFAULT_SERVER_URL
+  const serverUrl = config.serverUrl ?? defaultServerUrl()
   const reconnectionDelay =
     config.reconnectionDelay ?? DEFAULT_RECONNECTION_DELAY
 

package/src/entities.js

@@ -1,4 +1,4 @@
-import { map } from "@inglorious/utils/data-structures/object.js"
+import { map } from "@inglorious/utils/object.js"
 
 /**
  * @typedef {Object.<string, any>} Entity - An object representing an entity.

package/src/middlewares.js

@@ -1,4 +1,4 @@
-import { compose } from "@inglorious/utils/functions/functions.js"
+import { compose } from "@inglorious/utils/functions"
 
 /**
  * Applies a list of middleware functions to a store's dispatch method.

package/src/migration/rtk.js

@@ -5,7 +5,7 @@
  * Inglorious types, enabling gradual migration from RTK to Inglorious Store.
  */
 
-import { extend } from "@inglorious/utils/data-structures/objects.js"
+import { extend } from "@inglorious/utils/object.js"
 
 import { handleAsync } from "../async"
 

package/src/store.js

@@ -7,16 +7,46 @@ import { EventMap, parseEvent } from "./event-map.js"
 import { applyMiddlewares } from "./middlewares.js"
 import { augmentType, augmentTypes } from "./types.js"
 
+/** Copies only the entities that change, using a draft proxy. */
+const STRUCTURAL_SHARING = "structural-sharing"
+
+/** Deep-clones the whole state and applies events to the copy, without a proxy. */
+const FULL_CLONE = "full-clone"
+
+const UPDATE_STRATEGIES = [STRUCTURAL_SHARING, FULL_CLONE]
+
 /**
  * Creates a store to manage state and events.
- * @param {Object} config - Configuration options for the store.
- * @param {Object} [config.types] - The initial types configuration.
- * @param {Object} [config.entities] - The initial entities configuration.
- * @param {Array} [config.systems] - The initial systems configuration.
- * @param {Array} [config.middlewares] - The initial middlewares configuration.
- * @param {boolean} [config.autoCreateEntities] - Creates entities if not defined in `config.entities`.
- * @param {"auto" | "manual"} [config.updateMode] - The update mode (defaults to "auto").
- * @returns {Object} The store with methods to interact with state and events.
+ *
+ * Events are queued and drained by {@link createStore|update}. The `updateStrategy` option
+ * controls how the state is copied before the queued events are applied:
+ *
+ * - `"structural-sharing"` (default) - Applies events to a draft proxy, so only the entities
+ *   that actually changed are copied. Unchanged entities keep their previous reference, which
+ *   makes change detection cheap for consumers that rely on reference equality. This is the
+ *   right choice for UI stores, where a small number of entities change at a time.
+ * - `"full-clone"` - Deep-clones the whole state with `structuredClone` and applies events directly
+ *   to the copy, without a proxy. The cost is proportional to the total state size on every
+ *   update, but there is no per-entity proxy overhead, so it scales better when thousands of
+ *   entities change every frame, as in a game simulation.
+ *
+ * Under both strategies the current state is kept intact while the queued events are applied to a
+ * separate draft, and the two are swapped only once every event has been processed. Handlers and
+ * systems therefore always receive the draft as their first argument and mutate it directly, and
+ * subscribers are notified only after the swap. This also means that, during an update,
+ * `api.getEntity()` and `api.getEntities()` read the *previous* state rather than the in-flight
+ * changes, under either strategy.
+ *
+ * @param {StoreConfig} config - Configuration options for the store.
+ * @param {Types} [config.types] - The initial types configuration.
+ * @param {Entities} [config.entities] - The initial entities configuration.
+ * @param {Object[]} [config.systems] - The initial systems configuration.
+ * @param {Function[]} [config.middlewares] - The initial middlewares configuration.
+ * @param {boolean} [config.autoCreateEntities=false] - Creates entities if not defined in `config.entities`.
+ * @param {"auto" | "manual"} [config.updateMode="auto"] - Whether each event triggers an update, or updates are batched until `update()` is called.
+ * @param {UpdateStrategy} [config.updateStrategy="structural-sharing"] - How the state is copied before events are applied.
+ * @returns {Store} The store with methods to interact with state and events.
+ * @throws {TypeError} If `updateStrategy` is not a supported strategy.
  */
 export function createStore({
   types: originalTypes = {},
@@ -25,12 +55,15 @@ export function createStore({
   middlewares = [],
   autoCreateEntities = false,
   updateMode = "auto",
+  updateStrategy = STRUCTURAL_SHARING,
 } = {}) {
+  assertUpdateStrategy(updateStrategy)
+
   const listeners = new Set()
 
   const types = augmentTypes(originalTypes)
 
-  let state, eventMap, incomingEvents, isProcessing
+  let state, eventMap, incomingEvents, isProcessing, isHalted
   reset()
 
   const baseStore = {
@@ -42,6 +75,7 @@ export function createStore({
     getType,
     setType,
     getState,
+    getEntity,
     setState,
     reset,
   }
@@ -73,39 +107,128 @@ export function createStore({
 
   /**
    * Updates the state based on elapsed time and processes events.
+   *
+   * The current state is left untouched while the queued events are applied to a separate
+   * draft, according to the configured `updateStrategy`. The draft only replaces the current
+   * state once every queued event has been processed, and subscribers are notified afterwards.
+   *
+   * @returns {Event[]} The events processed during this update.
    */
   function update() {
     if (isProcessing) {
       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 []
+    }
+
     isProcessing = true
     const processedEvents = []
+    let nextState
 
-    state = create(state, patcher, {
-      enableAutoFreeze: state.game?.devMode,
-    })
+    if (updateStrategy === STRUCTURAL_SHARING) {
+      nextState = create(state, patch, {
+        enableAutoFreeze: state.game?.devMode,
+      })
+    } else {
+      const draft = structuredClone(state)
+
+      patch(draft)
+      nextState = draft
+    }
 
+    state = nextState
     isProcessing = false
 
     listeners.forEach((onUpdate) => onUpdate())
 
     return processedEvents
 
-    function patcher(draft) {
+    /**
+     * Applies every queued event to the given draft.
+     *
+     * The draft is either the proxy returned by `create` (structural sharing) or the
+     * deep copy produced by `structuredClone` (full clone). The current state is not
+     * modified, and only becomes the new state once this function returns.
+     *
+     * A change made by a handler is not visible to the next handler in the same pass:
+     * `getState` still returns the state as it was before the pass began. This is on
+     * purpose -- every event in the pass sees one consistent world, rather than some
+     * changes having landed and others not -- and it means a handler that asks what is
+     * left is asking about the past. Anything reacting to a change should be told the
+     * change rather than go looking for it.
+     *
+     * @param {Entities} draft - The draft to apply the queued events to.
+     * @returns {void}
+     */
+    function patch(draft) {
       while (incomingEvents.length) {
         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
+        }
+
+        if (event.type === "resume") {
+          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)
-          continue
         }
 
         if (event.type === "remove") {
           removeEntity(draft, event.payload)
-          continue
+        }
+
+        // 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)
+        }
+
+        if (event.type === "replace") {
+          replaceEntity(draft, event.payload)
         }
 
         // Parse the event to get handler name
@@ -114,9 +237,21 @@ export function createStore({
         // 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
+        // integrating a delta time would otherwise carry on regardless. An entity that
+        // sets `updatesWhilePaused` is exempt, which is how an overlay, a button or the
+        // thing that takes the pause back off keeps working while the rest stands still.
+        //
+        // It is read off the entity rather than the type so that the type stays an index
+        // signature of handlers, which is what lets it be called and indexed freely.
+        const halted = isHalted && handlerName === "update"
+
         for (const id of entityIds) {
           const entity = draft[id]
           const type = types[entity.type]
+
+          if (halted && !entity.updatesWhilePaused) continue
+
           const handle = type[handlerName]
 
           handle?.(entity, event.payload, api)
@@ -151,8 +286,14 @@ export function createStore({
    * - 'form:submit' - only form entities
    * - 'form[loginForm]:submit' - only loginForm entity
    *
+   * Two of these are the store's own. 'pause' stops the store handing out 'update'
+   * events, and 'resume' starts it again, which is how anything that moves by
+   * integrating a delta time stops without being told about it. A type declares
+   * `updatesWhilePaused` to keep updating regardless. Both keep dispatching to types
+   *
    * @param {string} type - The event type to notify.
-   * @param {any} payload - The event payload.
+   * @param {any} payload - The event payload. Carries the least that can be had
+   *   about what happened.
    */
   function notify(type, payload) {
     // NOTE: it's important to invoke store.dispatch instead of dispatch, otherwise we cannot override it
@@ -193,7 +334,8 @@ export function createStore({
   /**
    * Sets an augmented type configuration given its name.
    * @param {string} typeName - The name of the type to set.
-   * @param {Object} type - The type configuration.
+   * @param {Type} type - The type configuration.
+   * @returns {void}
    */
   function setType(typeName, type) {
     const oldType = types[typeName]
@@ -226,10 +368,25 @@ export function createStore({
     return state
   }
 
+  /**
+   * One entity by its id, or `undefined` if there is no such entity.
+   *
+   * This is what `api.getEntity` answers with during a handler, exposed here for the
+   * code that runs outside one: a test looking at a world it is driving, or anything else
+   * holding the store rather than an event's `api`.
+   *
+   * @param {string} id - The entity's id.
+   * @returns {Object|undefined} The entity, as the last finished pass left it.
+   */
+  function getEntity(id) {
+    return state?.[id]
+  }
+
   /**
    * Sets the entire state of the store.
    * This is useful for importing state or setting initial state from a server.
-   * @param {Object} nextState - The new state to set.
+   * @param {Entities} nextState - The new state to set.
+   * @returns {void}
    */
   function setState(nextState) {
     const oldEntities = state ?? {}
@@ -289,11 +446,19 @@ export function createStore({
 
   /**
    * Resets the store to its initial state.
+   * @returns {void}
    */
   function reset() {
+    isHalted = false
     setState(originalEntities)
   }
 
+  /**
+   * Adds an entity to the state and registers its event handlers.
+   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {Entity} payload - The entity to add, including its id.
+   * @returns {void}
+   */
   function addEntity(draft, payload) {
     const { id, ...entity } = payload
     draft[id] = augmentEntity(id, entity)
@@ -303,9 +468,109 @@ export function createStore({
     incomingEvents.unshift({ type: `#${id}:create` })
   }
 
-  function removeEntity(draft, payload) {
-    const id = payload
+  /**
+   * Moves a standing thing onto the handlers of whatever type it now names.
+   *
+   * A type is the only thing about a thing that cannot be merged: there is no such thing
+   * as being half a sort, so naming a different one means taking the thing out of the old
+   * one's list of entities before putting it in the new one.
+   *
+   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {string} id - The thing being moved.
+   * @param {string} previousType - The type it was under.
+   * @param {string|undefined} type - The type it is under now, if it has named one.
+   * @returns {void}
+   */
+  function moveToType(draft, id, previousType, type) {
+    if (!type || type === previousType) return
+
+    eventMap.removeEntity(id, types[previousType], previousType)
+    eventMap.addEntity(id, types[type], type)
+  }
+
+  /**
+   * Merges a new configuration into a thing that is already standing.
+   *
+   * Only the fields the configuration names are touched, so anything the world has done
+   * to the thing since it was made survives unless the
+   * new configuration says otherwise. A field named as `undefined` is set to nothing,
+   * which is what taking a key off a mapping means.
+   *
+   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {Entity} payload - The thing and the fields to merge into it.
+   * @returns {void}
+   */
+  function patchEntity(draft, payload) {
+    const { id, ...config } = payload
+    const existing = draft[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[id] = augmentEntity(id, { ...existing, ...config })
+
+    moveToType(draft, id, existing.type, config.type)
+  }
+
+  /**
+   * Installs a new configuration on a standing thing, dropping what it does not mention.
+   *
+   * The thing keeps its place in the world and its name; everything else is whatever it
+   * is told, and anything it is not told is gone. A field set to `undefined` is set to
+   * nothing here as much as it is in a patch -- the difference between the two is what
+   * happens to the fields neither mentions.
+   *
+   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {Entity} payload - The thing and the fields it is to be.
+   * @returns {void}
+   */
+  function replaceEntity(draft, payload) {
+    const { id, ...config } = payload
+    const existing = draft[id]
+
+    if (!existing) return
 
+    draft[id] = augmentEntity(id, config)
+
+    moveToType(draft, id, existing.type, config.type)
+  }
+
+  /**
+   * Queues the destruction of an entity. The entity is removed by the `#id:destroy` event.
+   * @param {Entities} draft - The draft (structural sharing) or the copy (full clone) to mutate.
+   * @param {string} id - The id of the entity to remove.
+   * @returns {void}
+   */
+  function removeEntity(draft, id) {
     incomingEvents.unshift({ type: `#${id}:destroy` })
   }
 }
+
+/**
+ * Validates the given update strategy.
+ * @param {UpdateStrategy} updateStrategy - The update strategy to validate.
+ * @returns {void}
+ * @throws {TypeError} If the update strategy is not supported.
+ */
+function assertUpdateStrategy(updateStrategy) {
+  if (UPDATE_STRATEGIES.includes(updateStrategy)) {
+    return
+  }
+
+  throw new TypeError(
+    `Unsupported update strategy: ${updateStrategy}. Expected one of: ${UPDATE_STRATEGIES.join(", ")}.`,
+  )
+}
+
+/**
+ * @typedef {"structural-sharing" | "full-clone"} UpdateStrategy - How the state is copied before events are applied.
+ * @typedef {Object} StoreConfig - Configuration options accepted by {@link createStore}.
+ * @typedef {Object.<string, any>} Type - An augmented entity type.
+ * @typedef {Object.<string, Type>} Types - A collection of augmented types.
+ * @typedef {Object.<string, any>} Entity - An object representing an entity.
+ * @typedef {Object.<string, Entity>} Entities - A collection of entities indexed by id.
+ * @typedef {(listener: () => void) => () => void} Listener - Subscribes to state updates and returns an unsubscribe function.
+ * @typedef {Object} Store - The store returned by {@link createStore}.
+ */

package/src/types.js

@@ -1,7 +1,6 @@
 import { ensureArray } from "@inglorious/utils/data-structures/array.js"
-import { map } from "@inglorious/utils/data-structures/object.js"
-import { extend } from "@inglorious/utils/data-structures/objects.js"
-import { pipe } from "@inglorious/utils/functions/functions.js"
+import { pipe } from "@inglorious/utils/functions"
+import { extend, map } from "@inglorious/utils/object.js"
 
 /**
  * Augments a single type by composing its behaviors and mixins.

package/types/store.d.ts

@@ -17,7 +17,12 @@ export interface Event<T = any> {
 }
 
 /**
- * Entity type definition with event handlers
+ * Entity type definition with event handlers.
+ *
+ * `updatesWhilePaused` opts the type out of a pause: the store stops handing out
+ * `update` events while the world is halted, and a type that says this keeps
+ * receiving them. It is for overlays and menus; anything that moves should leave it
+ * off so that it stops.
  */
 export type EntityType<TEntity extends BaseEntity = BaseEntity> = {
   [K: string]: (entity: TEntity, payload: any, api: Api) => void
@@ -43,6 +48,28 @@ export type EntitiesState<TEntity extends BaseEntity = BaseEntity> = {
 export type TypesConfig<TEntity extends BaseEntity = BaseEntity> = {
   [typeName: string]: EntityType<TEntity>
 }
+/**
+ * Whether each event triggers an update, or updates are batched until `update()` is called.
+ */
+export type UpdateMode = "auto" | "manual"
+
+/**
+ * How the state is copied before queued events are applied.
+ *
+ * - `"structural-sharing"` (default) applies events to a draft proxy, so only the entities that
+ *   actually changed are copied. Unchanged entities keep their previous reference, which keeps
+ *   reference-equality change detection cheap. Best for UI stores.
+ * - `"full-clone"` deep-clones the whole state with `structuredClone` and applies events to the
+ *   copy without a proxy. Cost is proportional to the total state size per update, but there is
+ *   no per-entity proxy overhead, so it scales better when thousands of entities change every
+ *   frame, as in a game simulation.
+ *
+ * Under both strategies the current state is left intact while the queued events are applied to
+ * a separate draft, and the two are swapped only once every event has been processed. This means
+ * that during an update `api.getEntity()` and `api.getEntities()` read the previous state rather
+ * than the in-flight changes.
+ */
+export type UpdateStrategy = "structural-sharing" | "full-clone"
 
 /**
  * Store configuration
@@ -56,7 +83,8 @@ export interface StoreConfig<
   systems?: System<TState>[]
   middlewares?: Middleware<TEntity, TState>[]
   autoCreateEntities?: boolean
-  mode?: "eager" | "batched"
+  updateMode?: UpdateMode
+  updateStrategy?: UpdateStrategy
 }
 
 /**
@@ -84,6 +112,7 @@ export interface Store<
   getType: (typeName: string) => EntityType<TEntity>
   setType: (typeName: string, type: EntityType<TEntity>) => void
   getState: () => TState
+  getEntity: (id: string) => TState[string] | undefined
   setState: (nextState: TState) => void
   reset: () => void
   _api?: Api<TEntity, TState>