@inglorious/store 7.0.0 → 7.1.1

package/README.md

@@ -477,6 +477,7 @@ Notice: you don't need pending/fulfilled/rejected actions. You stay in control o
 - **`api.notify(type, payload)`** - trigger other events (queued, not immediate)
 - **`api.dispatch(action)`** - optional, if you prefer Redux-style dispatching
 - **`api.getTypes()`** - access type definitions (mainly for middleware/plugins)
+- **`api.getType(typeName)`** - access type definition (mainly for overrides)
 
 All events triggered via `api.notify()` enter the queue and process together, maintaining predictability and testability.
 
@@ -635,10 +636,10 @@ When multiple behaviors define the same event, they all run in order. This allow
 
 ### ⏱️ Batched Mode
 
-The Inglorious Store features an **event queue**. In the default `eager` mode, each notified event will trigger and update of the state (same as Redux). But in `batched` mode, you can process multiple events together before re-rendering:
+The Inglorious Store features an **event queue**. In the default `auto` update mode, each notified event will trigger and update of the state (same as Redux). But in `manual` update mode, you can process multiple events together before re-rendering:
 
 ```javascript
-const store = createStore({ types, entities, mode: "batched" })
+const store = createStore({ types, entities, updateMode: "manual" })
 
 // add events to the event queue
 store.notify("playerMoved", { x: 100, y: 50 })
@@ -677,7 +678,7 @@ const store = createStore({
   types, // Object: entity type definitions
   entities, // Object: initial entities
   systems, // Array (optional): global state handlers
-  mode, // String (optional): 'eager' (default) or 'batched'
+  updateMode, // String (optional): 'auto' (default) or 'manual'
 })
 ```
 
@@ -718,6 +719,7 @@ Each handler receives three arguments:
   - `notify(type, payload)` - trigger other events
   - `dispatch(action)` - optional, if you prefer Redux-style dispatching
   - `getTypes()` - type definitions (for middleware)
+  - `getType(typeName)` - type definition (for overriding)
 
 ### Built-in Lifecycle Events
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "7.0.0",
+  "version": "7.1.1",
   "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",
@@ -58,7 +58,7 @@
     "prettier": "^3.6.2",
     "vite": "^7.1.3",
     "vitest": "^1.6.1",
-    "@inglorious/eslint-config": "1.0.1"
+    "@inglorious/eslint-config": "1.1.0"
   },
   "engines": {
     "node": ">= 22"

package/src/api.js

@@ -1,6 +1,7 @@
 export function createApi(store, extras) {
   return {
     getTypes: store.getTypes,
+    getType: store.getType,
     getEntities: store.getState,
     getEntity: (id) => store.getState()[id],
     dispatch: store.dispatch,

package/src/client/devtools.js

@@ -12,7 +12,7 @@ const globalContainer = import.meta.hot
 //   devToolsInstance,
 //   unsubscribe,
 //   store,
-//   mode,
+//   updateMode,
 //   restoreSetState: () => void,
 // }
 
@@ -45,18 +45,18 @@ export function createDevtools(config = {}) {
 }
 
 function connectDevTools(store, config = {}) {
-  const mode = config.mode ?? "eager"
+  const updateMode = config.updateMode ?? "auto"
 
-  // Prevent duplicate connections; rewire if store or mode changed
+  // Prevent duplicate connections; rewire if store or update mode changed
   const existing = getConnection()
   if (existing) {
-    const sameMode = existing.mode === mode
+    const sameMode = existing.updateMode === updateMode
     if (sameMode) {
       // Hot-swap store without resetting DevTools history
       existing.restoreSetState?.()
       const baseSetState = store.setState
       let restoreSetState = null
-      if (mode === "eager") {
+      if (updateMode === "auto") {
         restoreSetState = () => {
           if (store.setState !== baseSetState) {
             store.setState = baseSetState
@@ -75,7 +75,7 @@ function connectDevTools(store, config = {}) {
       existing.restoreSetState = restoreSetState
     }
 
-    // Different mode: fully disconnect previous and proceed
+    // Different update mode: fully disconnect previous and proceed
     try {
       existing.unsubscribe?.()
     } finally {
@@ -91,8 +91,8 @@ function connectDevTools(store, config = {}) {
   const name = config.name ?? document.title
   const baseSetState = store.setState
   let restoreSetState = null
-  // Only add setState side-effects in eager mode; batched mode logs explicitly from engine.
-  if (mode === "eager") {
+  // 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
@@ -140,7 +140,13 @@ function connectDevTools(store, config = {}) {
 
   devToolsInstance.init(store.getState())
 
-  setConnection({ devToolsInstance, unsubscribe, store, mode, restoreSetState })
+  setConnection({
+    devToolsInstance,
+    unsubscribe,
+    store,
+    updateMode,
+    restoreSetState,
+  })
 }
 
 function disconnectDevTools() {
@@ -234,12 +240,12 @@ function handleAction(message) {
 
 function shouldLogEvent(event, config) {
   const {
-    mode = "eager",
+    updateMode = "auto",
     blacklist = [],
     whitelist = [],
     filter = null,
   } = config
-  if (mode !== "eager") return false
+  if (updateMode !== "auto") return false
   const passesBlacklist = !blacklist.length || !blacklist.includes(event.type)
   const passesWhitelist = !whitelist.length || whitelist.includes(event.type)
   const passesFilter = !filter || filter(event)

package/src/event-map.js

@@ -3,9 +3,11 @@
  * @typedef {Object.<string, any>} Entity - An object representing a entity.
  */
 
+const SPLIT_LIMIT = 2
+
 /**
  * A class to manage the mapping of event names to the entity IDs that handle them.
- * This is used for optimized event handling.
+ * This is used for optimized event handling with support for scoped events.
  */
 export class EventMap {
   /**
@@ -16,17 +18,26 @@ export class EventMap {
    */
   constructor(types, entities) {
     /**
-     * The internal map where keys are event names and values are Sets of entity IDs.
+     * Maps handler names to type names to Sets of entity IDs.
+     * Structure: handlerName -> typeName -> Set<entityId>
+     * Example: 'submit' -> 'form' -> Set(['loginForm', 'signupForm'])
+     *
+     * @type {Map<string, Map<string, Set<string>>>}
+     */
+    this.handlerToTypeToEntities = new Map()
+
+    /**
+     * Maps entity IDs to their type names for quick lookup.
      *
-     * @type {Object.<string, Set<string>>}
+     * @type {Map<string, string>}
      */
-    this.map = {}
+    this.entityTypes = new Map()
 
     for (const entityId in entities) {
       const entity = entities[entityId]
       const type = types[entity.type]
       if (type) {
-        this.addEntity(entityId, type)
+        this.addEntity(entityId, type, entity.type)
       }
     }
   }
@@ -37,13 +48,24 @@ export class EventMap {
    *
    * @param {string} entityId - The ID of the entity.
    * @param {Type} type - The augmented type object of the entity.
+   * @param {string} typeName - The name of the entity's type.
    */
-  addEntity(entityId, type) {
-    for (const eventName in type) {
-      if (!this.map[eventName]) {
-        this.map[eventName] = new Set()
+  addEntity(entityId, type, typeName) {
+    this.entityTypes.set(entityId, typeName)
+
+    for (const handlerName in type) {
+      if (typeof type[handlerName] !== "function") continue
+
+      if (!this.handlerToTypeToEntities.has(handlerName)) {
+        this.handlerToTypeToEntities.set(handlerName, new Map())
+      }
+
+      const typeMap = this.handlerToTypeToEntities.get(handlerName)
+      if (!typeMap.has(typeName)) {
+        typeMap.set(typeName, new Set())
       }
-      this.map[eventName].add(entityId)
+
+      typeMap.get(typeName).add(entityId)
     }
   }
 
@@ -53,23 +75,77 @@ export class EventMap {
    *
    * @param {string} entityId - The ID of the entity.
    * @param {Type} type - The augmented type object of the entity.
+   * @param {string} typeName - The name of the entity's type.
    */
-  removeEntity(entityId, type) {
-    for (const eventName in type) {
-      const entitySet = this.map[eventName]
-      if (entitySet) {
-        entitySet.delete(entityId)
+  removeEntity(entityId, type, typeName) {
+    this.entityTypes.delete(entityId)
+
+    for (const handlerName in type) {
+      const typeMap = this.handlerToTypeToEntities.get(handlerName)
+      if (typeMap) {
+        const entitySet = typeMap.get(typeName)
+        if (entitySet) {
+          entitySet.delete(entityId)
+        }
       }
     }
   }
 
   /**
-   * Retrieves the Set of entity IDs that are subscribed to a given event.
+   * Retrieves the array of entity IDs that should handle a given event.
+   * Supports scoped events:
+   * - 'submit' -> all entities with 'submit' handler
+   * - 'form:submit' -> all form entities with 'submit' handler
+   * - 'form#loginForm:submit' -> only loginForm entity (of type form)
+   * - '#loginForm:submit' -> only loginForm entity
    *
-   * @param {string} eventName - The name of the event (e.g., 'update', 'fire').
-   * @returns {Set<string>} A Set of entity IDs. Returns an empty Set if no entities are found.
+   * @param {string} eventString - The event string (e.g., 'submit', 'form:submit', 'form[id]:submit')
+   * @returns {string[]} An array of entity IDs that should handle this event.
    */
-  getEntitiesForEvent(eventName) {
-    return this.map[eventName] || new Set()
+  getEntitiesForEvent(eventString) {
+    const {
+      type: targetType,
+      entityId: targetEntityId,
+      event: handlerName,
+    } = parseEvent(eventString)
+
+    const typeMap = this.handlerToTypeToEntities.get(handlerName)
+    if (!typeMap) return []
+
+    if (targetEntityId) {
+      const type = targetType ?? this.entityTypes.get(targetEntityId)
+      const entitySet = typeMap.get(type)
+      return entitySet && entitySet.has(targetEntityId) ? [targetEntityId] : []
+    }
+
+    // form:submit - all entities of this type
+    if (targetType) {
+      const entitySet = typeMap.get(targetType)
+      return entitySet ? Array.from(entitySet) : []
+    }
+
+    // submit - all entities with this handler (broadcast)
+    const allEntities = []
+    for (const entitySet of typeMap.values()) {
+      allEntities.push(...entitySet)
+    }
+    return allEntities
+  }
+}
+
+/**
+ * Parses an event string into its components.
+ * @param {string} eventString - The event string (e.g., 'submit', 'form:submit', 'form#loginForm:submit')
+ * @returns {{ type: string|null, entityId: string|null, event: string }}
+ */
+export function parseEvent(eventString) {
+  const [left, event] = eventString.split(":", SPLIT_LIMIT)
+  if (!event) return { type: null, entityId: null, event: left }
+
+  const [type, entityId] = left.split("#", SPLIT_LIMIT)
+  return {
+    type: type || null,
+    entityId: entityId || null,
+    event,
   }
 }

package/src/event-map.test.js

@@ -25,17 +25,20 @@ test("constructor should initialize the event map from types and entities", () =
 
   const eventMap = new EventMap(types, entities)
 
-  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual(
-    new Set(["player1", "player2", "enemy1"]),
-  )
-  expect(eventMap.getEntitiesForEvent("fire")).toStrictEqual(
-    new Set(["player1", "player2"]),
-  )
+  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual([
+    "player1",
+    "player2",
+    "enemy1",
+  ])
+  expect(eventMap.getEntitiesForEvent("fire")).toStrictEqual([
+    "player1",
+    "player2",
+  ])
 
   // 'item' type has no events, so it shouldn't be in the map
-  expect(eventMap.getEntitiesForEvent("item")).toStrictEqual(new Set())
+  expect(eventMap.getEntitiesForEvent("item")).toStrictEqual([])
   // 'ghost' type doesn't exist, so it should be ignored
-  expect(eventMap.getEntitiesForEvent("ghost")).toStrictEqual(new Set())
+  expect(eventMap.getEntitiesForEvent("ghost")).toStrictEqual([])
 })
 
 test("addEntity should add an entity to the correct event sets", () => {
@@ -47,23 +50,21 @@ test("addEntity should add an entity to the correct event sets", () => {
   }
   const eventMap = new EventMap(types, {})
 
-  eventMap.addEntity("player1", types.player)
+  eventMap.addEntity("player1", types.player, "player")
 
-  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual(
-    new Set(["player1"]),
-  )
-  expect(eventMap.getEntitiesForEvent("jump")).toStrictEqual(
-    new Set(["player1"]),
-  )
+  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual(["player1"])
+  expect(eventMap.getEntitiesForEvent("jump")).toStrictEqual(["player1"])
 
   // Add another entity of the same type
-  eventMap.addEntity("player2", types.player)
-  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual(
-    new Set(["player1", "player2"]),
-  )
-  expect(eventMap.getEntitiesForEvent("jump")).toStrictEqual(
-    new Set(["player1", "player2"]),
-  )
+  eventMap.addEntity("player2", types.player, "player")
+  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual([
+    "player1",
+    "player2",
+  ])
+  expect(eventMap.getEntitiesForEvent("jump")).toStrictEqual([
+    "player1",
+    "player2",
+  ])
 })
 
 test("removeEntity should remove an entity from its event sets", () => {
@@ -79,17 +80,15 @@ test("removeEntity should remove an entity from its event sets", () => {
   }
   const eventMap = new EventMap(types, entities)
 
-  eventMap.removeEntity("player1", types.player)
+  eventMap.removeEntity("player1", types.player, "player")
 
-  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual(
-    new Set(["player2"]),
-  )
-  expect(eventMap.getEntitiesForEvent("fire")).toStrictEqual(
-    new Set(["player2"]),
-  )
+  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual(["player2"])
+  expect(eventMap.getEntitiesForEvent("fire")).toStrictEqual(["player2"])
 
   // Removing a non-existent entity should not throw an error
-  expect(() => eventMap.removeEntity("player3", types.player)).not.toThrow()
+  expect(() =>
+    eventMap.removeEntity("player3", types.player, "player"),
+  ).not.toThrow()
 })
 
 test("getEntitiesForEvent should return the correct set of entities for an event", () => {
@@ -104,10 +103,57 @@ test("getEntitiesForEvent should return the correct set of entities for an event
   const eventMap = new EventMap(types, entities)
 
   const updateEntities = eventMap.getEntitiesForEvent("update")
-  expect(updateEntities).toStrictEqual(new Set(["player1", "enemy1"]))
+  expect(updateEntities).toStrictEqual(["player1", "enemy1"])
 
   const fireEntities = eventMap.getEntitiesForEvent("fire")
-  expect(fireEntities).toStrictEqual(new Set())
+  expect(fireEntities).toStrictEqual([])
+})
+
+test("getEntitiesForEvent should handle scoped events correctly", () => {
+  const types = {
+    form: { submit: () => {} },
+    button: { submit: () => {} },
+  }
+  const entities = {
+    loginForm: { type: "form" },
+    signupForm: { type: "form" },
+    submitButton: { type: "button" },
+  }
+  const eventMap = new EventMap(types, entities)
+
+  // Scoped to a type: 'form:submit' should only return form entities
+  expect(eventMap.getEntitiesForEvent("form:submit")).toStrictEqual([
+    "loginForm",
+    "signupForm",
+  ])
+
+  // Scoped to a specific entity by ID: '#loginForm:submit'
+  expect(eventMap.getEntitiesForEvent("#loginForm:submit")).toStrictEqual([
+    "loginForm",
+  ])
+
+  // Scoped to a specific entity by type and ID: 'form#loginForm:submit'
+  expect(eventMap.getEntitiesForEvent("form#loginForm:submit")).toStrictEqual([
+    "loginForm",
+  ])
+
+  // Scoped to a non-existent entity ID
+  expect(eventMap.getEntitiesForEvent("#nonExistent:submit")).toStrictEqual([])
+
+  // Scoped to an entity that exists but doesn't handle the event
+  expect(eventMap.getEntitiesForEvent("#loginForm:click")).toStrictEqual([])
+
+  // Scoped to an entity ID, but with the wrong type specified
+  expect(eventMap.getEntitiesForEvent("button#loginForm:submit")).toStrictEqual(
+    [],
+  )
+
+  // Broadcast event should return all entities with the handler
+  expect(eventMap.getEntitiesForEvent("submit")).toStrictEqual([
+    "loginForm",
+    "signupForm",
+    "submitButton",
+  ])
 })
 
 test("EventMap provides a significant performance benefit for event handling", async () => {
@@ -145,7 +191,7 @@ test("EventMap provides a significant performance benefit for event handling", a
 
   // Assertions to verify correctness
   expect(oldWayTime).toBeGreaterThan(newWayTime)
-  expect(updateHandler).toHaveBeenCalledTimes(updaterIds.size)
+  expect(updateHandler).toHaveBeenCalledTimes(updaterIds.length)
 })
 
 // Helper function to create a large set of test entities

package/src/store.js

@@ -2,7 +2,7 @@ import { create } from "mutative"
 
 import { createApi } from "./api.js"
 import { augmentEntities, augmentEntity } from "./entities.js"
-import { EventMap } from "./event-map.js"
+import { EventMap, parseEvent } from "./event-map.js"
 import { applyMiddlewares } from "./middlewares.js"
 import { augmentType, augmentTypes } from "./types.js"
 
@@ -11,9 +11,9 @@ import { augmentType, augmentTypes } from "./types.js"
  * @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.systens] - The initial systems configuration.
+ * @param {Array} [config.systems] - The initial systems configuration.
  * @param {Array} [config.middlewares] - The initial middlewares configuration.
- * @param {"eager" | "batched"} [config.mode] - The dispatch mode (defaults to "eager").
+ * @param {"auto" | "manual"} [config.updateMode] - The update mode (defaults to "auto").
  * @returns {Object} The store with methods to interact with state and events.
  */
 export function createStore({
@@ -21,13 +21,13 @@ export function createStore({
   entities: originalEntities,
   systems = [],
   middlewares = [],
-  mode = "eager",
+  updateMode = "auto",
 }) {
   const listeners = new Set()
 
   const types = augmentTypes(originalTypes)
 
-  let state, eventMap, incomingEvents
+  let state, eventMap, incomingEvents, isProcessing
   reset()
 
   const baseStore = {
@@ -36,6 +36,7 @@ export function createStore({
     notify,
     dispatch, // needed for compatibility with Redux
     getTypes,
+    getType,
     getState,
     setState,
     reset,
@@ -63,15 +64,21 @@ export function createStore({
 
   /**
    * Updates the state based on elapsed time and processes events.
-   * @param {number} dt - The delta time since the last update in milliseconds.
    */
   function update() {
+    if (isProcessing) {
+      return []
+    }
+
+    isProcessing = true
     const processedEvents = []
 
     state = create(state, patcher, {
       enableAutoFreeze: state.game?.devMode,
     })
 
+    isProcessing = false
+
     listeners.forEach((onUpdate) => onUpdate())
 
     return processedEvents
@@ -81,18 +88,21 @@ export function createStore({
         const event = incomingEvents.shift()
         processedEvents.push(event)
 
+        // Handle special system events
         if (event.type === "morph") {
           const { id, type } = event.payload
 
           const entity = draft[id]
           const oldType = types[entity.type]
+          const oldTypeName = entity.type
 
-          originalTypes[id] = type
-          types[id] = augmentType(originalTypes[id])
-          const newType = types[id]
+          originalTypes[entity.type] = type
+          types[entity.type] = augmentType(originalTypes[entity.type])
+          const newType = types[entity.type]
 
-          eventMap.removeEntity(id, oldType)
-          eventMap.addEntity(id, newType)
+          eventMap.removeEntity(id, oldType, oldTypeName)
+          eventMap.addEntity(id, newType, oldTypeName) // Use the original type name
+          continue
         }
 
         if (event.type === "add") {
@@ -100,30 +110,42 @@ export function createStore({
           draft[id] = augmentEntity(id, entity)
           const type = types[entity.type]
 
-          eventMap.addEntity(id, type)
+          eventMap.addEntity(id, type, entity.type)
           incomingEvents.unshift({ type: "create", payload: id })
+          continue
         }
 
         if (event.type === "remove") {
           const id = event.payload
           const entity = draft[id]
           const type = types[entity.type]
+          const typeName = entity.type
           delete draft[id]
 
-          eventMap.removeEntity(id, type)
+          eventMap.removeEntity(id, type, typeName)
           incomingEvents.unshift({ type: "destroy", payload: id })
+          continue
         }
 
+        // Parse the event to get handler name
+        const { event: handlerName } = parseEvent(event.type)
+
+        // Get entities that should handle this event (filtered by EventMap)
         const entityIds = eventMap.getEntitiesForEvent(event.type)
+
         for (const id of entityIds) {
           const entity = draft[id]
           const type = types[entity.type]
-          const handle = type[event.type]
-          handle(entity, event.payload, api)
+          const handle = type[handlerName]
+
+          if (handle) {
+            handle(entity, event.payload, api)
+          }
         }
 
+        // Systems process events by handler name (not scoped)
         systems.forEach((system) => {
-          const handle = system[event.type]
+          const handle = system[handlerName]
           handle?.(draft, event.payload, api)
         })
       }
@@ -132,8 +154,13 @@ export function createStore({
 
   /**
    * Notifies the store of a new event.
-   * @param {string} type - The event object type to notify.
-   * @param {any} payload - The event object payload to notify.
+   * Supports scoped events:
+   * - 'submit' - broadcast to all entities with submit handler
+   * - 'form:submit' - only form entities
+   * - 'form[loginForm]:submit' - only loginForm entity
+   *
+   * @param {string} type - The event type to notify.
+   * @param {any} payload - The event payload.
    */
   function notify(type, payload) {
     // NOTE: it's important to invoke store.dispatch instead of dispatch, otherwise we cannot override it
@@ -148,7 +175,7 @@ export function createStore({
    */
   function dispatch(event) {
     incomingEvents.push(event)
-    if (mode === "eager") {
+    if (updateMode === "auto") {
       update()
     }
   }
@@ -162,6 +189,15 @@ export function createStore({
     return types
   }
 
+  /**
+   * Retrieves an augmented type configuration given its name.
+   * @param {string} typeName - The type of the entity.
+   * @returns {Object} The augmented type configuration.
+   */
+  function getType(typeName) {
+    return types[typeName]
+  }
+
   /**
    * Retrieves the current state.
    * @returns {Object} The current state.
@@ -182,6 +218,7 @@ export function createStore({
     state = newEntities
     eventMap = new EventMap(types, nextState)
     incomingEvents = []
+    isProcessing = false
 
     const oldEntityIds = new Set(Object.keys(oldEntities))
     const newEntityIds = new Set(Object.keys(newEntities))

package/src/store.test.js

@@ -86,7 +86,7 @@ test("it should send an event from an entity and process it in the same update c
       kitty1: { type: "kitty", position: "near" },
     },
 
-    mode: "batched",
+    updateMode: "manual",
   }
   const afterState = {
     doggo1: { id: "doggo1", type: "doggo" },