@inglorious/store 11.0.1 → 11.0.2

package/README.md

@@ -1072,6 +1072,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 +1089,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "11.0.1",
+  "version": "11.0.2",
   "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": "4.0.0",
     "mutative": "^1.3.0"
   },
   "peerDependencies": {
-    "@inglorious/utils": "3.8.0"
+    "@inglorious/utils": "4.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/client/devtools.js

@@ -1,4 +1,4 @@
-import { deserialize } from "@inglorious/utils/data-structures/object.js"
+import { deserialize } from "@inglorious/utils/objects"
 
 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,8 +1,4 @@
-import {
-  deserialize,
-  serialize,
-} from "@inglorious/utils/data-structures/object.js"
-import { extend } from "@inglorious/utils/data-structures/objects.js"
+import { deserialize, extend, serialize } from "@inglorious/utils/objects"
 
 // A constant for the server's WebSocket URL.
 const DEFAULT_SERVER_URL = `ws://${window.location.hostname}:3000`

package/src/entities.js

@@ -1,4 +1,4 @@
-import { map } from "@inglorious/utils/data-structures/object.js"
+import { map } from "@inglorious/utils/objects"
 
 /**
  * @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/objects"
 
 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,7 +55,10 @@ export function createStore({
   middlewares = [],
   autoCreateEntities = false,
   updateMode = "auto",
+  updateStrategy = STRUCTURAL_SHARING,
 } = {}) {
+  assertUpdateStrategy(updateStrategy)
+
   const listeners = new Set()
 
   const types = augmentTypes(originalTypes)
@@ -73,6 +106,12 @@ 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) {
@@ -81,18 +120,37 @@ export function createStore({
 
     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.
+     *
+     * @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)
@@ -193,7 +251,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]
@@ -229,7 +288,8 @@ export function createStore({
   /**
    * 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 +349,18 @@ export function createStore({
 
   /**
    * Resets the store to its initial state.
+   * @returns {void}
    */
   function reset() {
     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 +370,40 @@ export function createStore({
     incomingEvents.unshift({ type: `#${id}:create` })
   }
 
-  function removeEntity(draft, payload) {
-    const id = payload
-
+  /**
+   * 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/objects"
 
 /**
  * Augments a single type by composing its behaviors and mixins.

package/types/store.d.ts

@@ -43,6 +43,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 +78,8 @@ export interface StoreConfig<
   systems?: System<TState>[]
   middlewares?: Middleware<TEntity, TState>[]
   autoCreateEntities?: boolean
-  mode?: "eager" | "batched"
+  updateMode?: UpdateMode
+  updateStrategy?: UpdateStrategy
 }
 
 /**