@inglorious/store 11.0.2 → 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**:
@@ -1256,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.2",
+  "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,11 +55,11 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@inglorious/utils": "4.0.0",
+    "@inglorious/utils": "5.0.0",
     "mutative": "^1.3.0"
   },
   "peerDependencies": {
-    "@inglorious/utils": "4.0.0"
+    "@inglorious/utils": "5.0.0"
   },
   "devDependencies": {
     "@inglorious/eslint-config": "1.1.2",

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/objects"
+import { deserialize } from "@inglorious/utils/object.js"
 
 const LAST_STATE = 1
 

package/src/client/multiplayer-middleware.js

@@ -1,15 +1,25 @@
-import { deserialize, extend, serialize } from "@inglorious/utils/objects"
+import { deserialize, extend, serialize } from "@inglorious/utils/object.js"
 
-// A constant for the server's WebSocket URL.
-const DEFAULT_SERVER_URL = `ws://${window.location.hostname}:3000`
 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/objects"
+import { map } from "@inglorious/utils/object.js"
 
 /**
  * @typedef {Object.<string, any>} Entity - An object representing an entity.

package/src/migration/rtk.js

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

package/src/store.js

@@ -63,7 +63,7 @@ export function createStore({
 
   const types = augmentTypes(originalTypes)
 
-  let state, eventMap, incomingEvents, isProcessing
+  let state, eventMap, incomingEvents, isProcessing, isHalted
   reset()
 
   const baseStore = {
@@ -75,6 +75,7 @@ export function createStore({
     getType,
     setType,
     getState,
+    getEntity,
     setState,
     reset,
   }
@@ -118,6 +119,14 @@ 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 []
+    }
+
     isProcessing = true
     const processedEvents = []
     let nextState
@@ -147,6 +156,13 @@ export function createStore({
      * 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}
      */
@@ -155,15 +171,64 @@ 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
+        }
+
+        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
@@ -172,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)
@@ -209,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
@@ -285,6 +368,20 @@ 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.
@@ -352,6 +449,7 @@ export function createStore({
    * @returns {void}
    */
   function reset() {
+    isHalted = false
     setState(originalEntities)
   }
 
@@ -370,6 +468,75 @@ export function createStore({
     incomingEvents.unshift({ type: `#${id}:create` })
   }
 
+  /**
+   * 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.

package/src/types.js

@@ -1,6 +1,6 @@
 import { ensureArray } from "@inglorious/utils/data-structures/array.js"
 import { pipe } from "@inglorious/utils/functions"
-import { extend, map } from "@inglorious/utils/objects"
+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
@@ -107,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>