@inglorious/store 5.0.1 → 5.2.0

package/README.md

@@ -3,11 +3,11 @@
 [![NPM version](https://img.shields.io/npm/v/@inglorious/store.svg)](https://www.npmjs.com/package/@inglorious/store)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**State management inspired by video games.**
+**Build apps that are already multiplayer-ready.**
 
-Inglorious Store brings battle-tested patterns from game development to modern web applications. If your app needs real-time updates, multiplayer features, or complex interactive state, you'll benefit from the same techniques that power multiplayer games and collaborative tools like Figma.
+Inglorious Store uses battle-tested patterns from game development to give you an architecture that scales from simple solo apps to real-time collaboration—without refactoring. Start with a basic todo list today. Add collaborative features next year. Same code, zero rewrites.
 
-Perfect for: real-time collaboration, live dashboards, chat apps, interactive visualizations, and any application where state synchronization matters.
+Why settle for state management that wasn't designed for real-time sync? Games solved distributed state synchronization decades ago. Now you can use the same proven patterns for your apps.
 
 ---
 
@@ -128,8 +128,8 @@ const types = {
 }
 
 const entities = {
-  "counter-1": { type: "counter", value: 0 },
-  "counter-2": { type: "counter", value: 10 },
+  counter1: { type: "counter", value: 0 },
+  counter2: { type: "counter", value: 10 },
 }
 
 const store = createStore({ types, entities })
@@ -138,8 +138,8 @@ const store = createStore({ types, entities })
 store.notify("increment")
 store.update()
 
-console.log(store.getState().entities["counter-1"].value) // => 1
-console.log(store.getState().entities["counter-2"].value) // => 11
+console.log(store.getState().counter1.value) // => 1
+console.log(store.getState().counter2.value) // => 11
 
 // To update just one counter, add filtering logic in the handler
 ```
@@ -233,7 +233,7 @@ store.subscribe(() => {
 
 // 6. Dispatch events (use notify or dispatch - both work!)
 store.notify("inputChange", "Buy milk")
-store.notify("formSubmit", store.getState().entities.form.value)
+store.notify("formSubmit", store.getState().form.value)
 store.notify("toggleClick", 1) // Only todo with id=1 will respond
 store.notify("filterClick", "active")
 
@@ -302,8 +302,8 @@ Your state is a collection of **entities** (instances) organized by **type** (li
 
 ```javascript
 const entities = {
-  "item-1": { type: "cartItem", name: "Shoes", quantity: 1, price: 99 },
-  "item-2": { type: "cartItem", name: "Shirt", quantity: 2, price: 29 },
+  item1: { type: "cartItem", name: "Shoes", quantity: 1, price: 99 },
+  item2: { type: "cartItem", name: "Shirt", quantity: 2, price: 29 },
 }
 ```
 
@@ -346,13 +346,13 @@ Events are broadcast to all relevant handlers in a pub/sub pattern.
 
 ```javascript
 // Simplest form - just the entity ID
-store.notify("increment", "counter-1")
+store.notify("increment", "counter1")
 
 // With additional data
-store.notify("applyDiscount", { id: "item-1", percent: 10 })
+store.notify("applyDiscount", { id: "item1", percent: 10 })
 
 // Also supports dispatch() for Redux compatibility
-store.dispatch({ type: "increment", payload: "counter-1" })
+store.dispatch({ type: "increment", payload: "counter1" })
 
 // Process the queue - this is when handlers actually run
 store.update()
@@ -367,8 +367,8 @@ For global state logic that doesn't belong to a specific entity type.
 ```javascript
 const systems = [
   {
-    calculateTotal(state) {
-      state.cartTotal = Object.values(state.entities)
+    calculateTotal(entities) {
+      state.cartTotal = Object.values(entities)
         .filter((e) => e.type === "cartItem")
         .reduce((sum, item) => sum + item.price * item.quantity, 0)
     },
@@ -415,9 +415,8 @@ Creates a convenience wrapper with utility methods.
 Create memoized, performant selectors.
 
 ```javascript
-const selectCompletedTodos = createSelector(
-  [(state) => state.entities],
-  (entities) => Object.values(entities).filter((e) => e.completed),
+const selectCompletedTasks = createSelector([(state) => state.tasks], (tasks) =>
+  tasks.filter((task) => task.completed),
 )
 ```
 
@@ -572,7 +571,9 @@ This store powers the [Inglorious Engine](https://github.com/IngloriousCoderz/in
 
 ## License
 
-MIT
+MIT © [Matteo Antony Mistretta](https://github.com/IngloriousCoderz)
+
+This is free and open-source software. Use it however you want!
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inglorious/store",
-  "version": "5.0.1",
-  "description": "A state manager inspired by Redux, but tailored for the specific needs of game development.",
+  "version": "5.2.0",
+  "description": "A state manager for real-time, collaborative apps, inspired by game development patterns and compatible with Redux.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
   "repository": {
@@ -13,18 +13,26 @@
     "url": "https://github.com/IngloriousCoderz/inglorious-engine/issues"
   },
   "keywords": [
-    "functional-programming",
-    "gamedev",
-    "game-engine",
-    "inglorious-engine",
-    "state-manager",
+    "state",
+    "state-management",
+    "store",
     "redux",
-    "store"
+    "redux-alternative",
+    "mutative",
+    "immer",
+    "collaborative",
+    "multiplayer",
+    "realtime",
+    "event-batching"
   ],
   "type": "module",
   "exports": {
-    ".": "./src/store.js",
-    "./*": "./src/*"
+    ".": {
+      "import": "./src/store.js"
+    },
+    "./*": {
+      "import": "./src/*"
+    }
   },
   "files": [
     "src"
@@ -34,10 +42,10 @@
   },
   "dependencies": {
     "mutative": "^1.3.0",
-    "@inglorious/utils": "3.6.0"
+    "@inglorious/utils": "3.6.1"
   },
   "peerDependencies": {
-    "@inglorious/utils": "3.6.0"
+    "@inglorious/utils": "3.6.1"
   },
   "devDependencies": {
     "prettier": "^3.6.2",

package/src/api.js

@@ -8,7 +8,7 @@ export function createApi(store) {
 
   const getTypes = () => store.getTypes()
 
-  const getEntities = () => store.getState().entities
+  const getEntities = () => store.getState()
 
   const getEntity = (id) => getEntities()[id]
 

package/src/client/dev-tools.js

@@ -0,0 +1,120 @@
+const LAST_STATE = 1
+
+let devToolsInstance = null
+let unsubscribe = null
+
+export function connectDevTools(store, config = {}) {
+  // Prevent multiple connections
+  if (devToolsInstance) {
+    return
+  }
+
+  if (typeof window === "undefined" || !window.__REDUX_DEVTOOLS_EXTENSION__) {
+    return
+  }
+
+  const name = config.name ?? document.title
+  const skippedEvents = config.skippedEvents ?? []
+
+  devToolsInstance = window.__REDUX_DEVTOOLS_EXTENSION__.connect({
+    name,
+    predicate: (state, action) => !skippedEvents.includes(action.type),
+    // @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
+    },
+  })
+
+  unsubscribe = devToolsInstance.subscribe((message) => {
+    switch (message.type) {
+      case "DISPATCH":
+        handleDispatch(message, store)
+        break
+
+      case "ACTION":
+        handleAction(message, store)
+        break
+    }
+  })
+
+  devToolsInstance.init(store.getState())
+}
+
+export function disconnectDevTools() {
+  // The `disconnect` method on the devToolsInstance is not available in all
+  // environments or versions of the extension.
+  // The safest way to "disconnect" is to unsubscribe from any listeners
+  // and release our reference to the instance, which prevents any further
+  // actions from being sent.
+  if (unsubscribe) {
+    unsubscribe()
+    unsubscribe = null
+    devToolsInstance = null
+  }
+}
+
+export function sendAction(action, state) {
+  if (devToolsInstance) {
+    devToolsInstance.send(action, state)
+  }
+}
+
+function handleDispatch(message, store) {
+  switch (message.payload.type) {
+    // reset button
+    case "RESET": {
+      store.reset()
+      devToolsInstance.init(store.getState())
+      break
+    }
+
+    // revert button
+    case "ROLLBACK": {
+      const newState = JSON.parse(message.state)
+      store.setState(newState)
+      break
+    }
+
+    // commit button
+    case "COMMIT": {
+      devToolsInstance.init(store.getState())
+      break
+    }
+
+    // import from file button
+    case "IMPORT_STATE": {
+      const { computedStates, actionsById } = message.payload.nextLiftedState
+
+      const [firstComputedState] = computedStates
+      const lastComputedState =
+        computedStates[computedStates.length - LAST_STATE]
+      if (lastComputedState) {
+        store.setState(lastComputedState.state)
+      }
+
+      const flattenedActions = Object.values(actionsById)
+        .flatMap(({ action }) => action.payload ?? action)
+        .map((action, index) => [index, action])
+
+      devToolsInstance.init(
+        firstComputedState.state,
+        Object.fromEntries(flattenedActions),
+      )
+      break
+    }
+  }
+}
+
+function handleAction(message, store) {
+  const action = JSON.parse(message.payload)
+  store.dispatch(action)
+}

package/src/client/multiplayer-middleware.js

@@ -0,0 +1,94 @@
+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`
+const DEFAULT_RECONNECTION_DELAY = 1000
+
+/**
+ * Creates and returns the multiplayer middleware.
+ * @returns {Function} The middleware function.
+ */
+export function multiplayerMiddleware(config = {}) {
+  const serverUrl = config.serverUrl ?? DEFAULT_SERVER_URL
+  const reconnectionDelay =
+    config.reconnectionDelay ?? DEFAULT_RECONNECTION_DELAY
+  const skippedEvents = config.skippedEvents ?? []
+
+  let ws = null
+  const localQueue = []
+
+  // The middleware function that will be applied to the store.
+  return (store) => (next) => (event) => {
+    if (skippedEvents.includes(event.type)) {
+      return next(event)
+    }
+
+    // Establish the connection on the first event.
+    if (!ws) {
+      establishConnection(store)
+    }
+
+    // Only send the event to the server if it didn't come from the server.
+    if (!event.fromServer) {
+      if (ws?.readyState === WebSocket.OPEN) {
+        // If the connection is open, send the event immediately.
+        ws.send(serialize(event))
+      } else {
+        // If the connection is not open, queue the event for later.
+        localQueue.push(event)
+      }
+    }
+
+    // Pass the event to the next middleware in the chain,
+    // which is eventually the store's original dispatch function.
+    return next(event)
+  }
+
+  /**
+   * 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()))
+      }
+    }
+
+    ws.onmessage = (event) => {
+      const serverEvent = deserialize(event.data)
+
+      if (serverEvent.type === "initialState") {
+        // 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.
+    }
+  }
+}

package/src/store.js

@@ -68,7 +68,7 @@ export function createStore({
     const processedEvents = []
 
     state = create(state, patcher, {
-      enableAutoFreeze: state.entities.game?.devMode,
+      enableAutoFreeze: state.game?.devMode,
     })
 
     listeners.forEach((onUpdate) => onUpdate())
@@ -83,7 +83,7 @@ export function createStore({
         if (event.type === "morph") {
           const { id, type } = event.payload
 
-          const entity = draft.entities[id]
+          const entity = draft[id]
           const oldType = types[entity.type]
 
           originalTypes[id] = type
@@ -96,7 +96,7 @@ export function createStore({
 
         if (event.type === "add") {
           const { id, ...entity } = event.payload
-          draft.entities[id] = augmentEntity(id, entity)
+          draft[id] = augmentEntity(id, entity)
           const type = types[entity.type]
 
           eventMap.addEntity(id, type)
@@ -105,9 +105,9 @@ export function createStore({
 
         if (event.type === "remove") {
           const id = event.payload
-          const entity = draft.entities[id]
+          const entity = draft[id]
           const type = types[entity.type]
-          delete draft.entities[id]
+          delete draft[id]
 
           eventMap.removeEntity(id, type)
           incomingEvents.unshift({ type: "destroy", payload: id })
@@ -115,7 +115,7 @@ export function createStore({
 
         const entityIds = eventMap.getEntitiesForEvent(event.type)
         for (const id of entityIds) {
-          const entity = draft.entities[id]
+          const entity = draft[id]
           const type = types[entity.type]
           const handle = type[event.type]
           handle(entity, event.payload, api)
@@ -187,11 +187,11 @@ export function createStore({
    * @param {Object} nextState - The new state to set.
    */
   function setState(nextState) {
-    const oldEntities = state?.entities ?? {}
-    const newEntities = augmentEntities(nextState.entities)
+    const oldEntities = state ?? {}
+    const newEntities = augmentEntities(nextState)
 
-    state = { entities: newEntities }
-    eventMap = new EventMap(types, nextState.entities)
+    state = newEntities
+    eventMap = new EventMap(types, nextState)
     incomingEvents = []
 
     const oldEntityIds = new Set(Object.keys(oldEntities))
@@ -217,6 +217,6 @@ export function createStore({
    * Resets the store to its initial state.
    */
   function reset() {
-    setState({ entities: originalEntities })
+    setState(originalEntities)
   }
 }

package/src/store.test.js

@@ -16,12 +16,10 @@ test("it should process events by mutating state inside handlers", () => {
     },
   }
   const afterState = {
-    entities: {
-      kitty1: {
-        id: "kitty1",
-        type: "kitty",
-        isFed: true,
-      },
+    kitty1: {
+      id: "kitty1",
+      type: "kitty",
+      isFed: true,
     },
   }
 
@@ -50,13 +48,11 @@ test("it should process an event queue in the same update cycle", () => {
     },
   }
   const afterState = {
-    entities: {
-      kitty1: {
-        id: "kitty1",
-        type: "kitty",
-        isFed: true,
-        isMeowing: true,
-      },
+    kitty1: {
+      id: "kitty1",
+      type: "kitty",
+      isFed: true,
+      isMeowing: true,
     },
   }
 
@@ -89,10 +85,8 @@ test("it should send an event from an entity and process it in the same update c
     },
   }
   const afterState = {
-    entities: {
-      doggo1: { id: "doggo1", type: "doggo" },
-      kitty1: { id: "kitty1", type: "kitty", position: "far" },
-    },
+    doggo1: { id: "doggo1", type: "doggo" },
+    kitty1: { id: "kitty1", type: "kitty", position: "far" },
   }
 
   const store = createStore(config)
@@ -112,17 +106,16 @@ test("it should add an entity via an 'add' event", () => {
     entities: {},
   }
   const newEntity = { id: "kitty1", type: "kitty" }
+  const afterState = {
+    kitty1: { id: "kitty1", type: "kitty" },
+  }
 
   const store = createStore(config)
   store.notify("add", newEntity)
   store.update()
 
   const state = store.getState()
-  expect(state).toStrictEqual({
-    entities: {
-      kitty1: { id: "kitty1", type: "kitty" },
-    },
-  })
+  expect(state).toStrictEqual(afterState)
 })
 
 test("it should remove an entity via a 'remove' event", () => {
@@ -138,7 +131,7 @@ test("it should remove an entity via a 'remove' event", () => {
   store.update()
 
   const state = store.getState()
-  expect(state.entities.kitty1).toBeUndefined()
+  expect(state.kitty1).toBeUndefined()
 })
 
 test("it should change an entity's behavior via a 'morph' event", () => {
@@ -169,17 +162,13 @@ test("it should change an entity's behavior via a 'morph' event", () => {
   store.update()
 
   expect(store.getState()).toStrictEqual({
-    entities: {
-      bug: { id: "bug", type: "bug", isFull: true },
-    },
+    bug: { id: "bug", type: "bug", isFull: true },
   })
 
   store.notify("morph", { id: "bug", type: [Caterpillar, Butterfly] })
   store.notify("fly")
   store.update()
   expect(store.getState()).toStrictEqual({
-    entities: {
-      bug: { id: "bug", type: "bug", isFull: true, hasFlown: true },
-    },
+    bug: { id: "bug", type: "bug", isFull: true, hasFlown: true },
   })
 })