@inglorious/store 1.0.0 → 1.2.0

package/README.md

@@ -90,7 +90,7 @@ Creates a convenient API object that encapsulates the store's methods and provid
 
 - An `api` object with methods for interacting with the store and state, including:
   - `createSelector(inputSelectors, resultFunc)`: A helper function that automatically binds the store's state to a new selector.
-  - `getTypes()`, `getEntities()`, `getEntity(id)`, `getType(id)`: Utility functions for accessing state.
+  - `getTypes()`, `getEntities()`, `getEntity(id)`: Utility functions for accessing state.
   - `notify(type, payload)`, `dispatch(action)`: Aliases to the store's event dispatching methods.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A state manager inspired by Redux, but tailored for the specific needs of game development.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -22,14 +22,15 @@
     "store"
   ],
   "type": "module",
+  "exports": {
+    ".": "./src/store.js",
+    "./*": "./src/*"
+  },
   "files": [
     "src",
     "README.md",
     "LICENSE"
   ],
-  "exports": {
-    "./*": "./src/*"
-  },
   "publishConfig": {
     "access": "public"
   },

package/src/api.js

@@ -12,23 +12,12 @@ export function createApi(store) {
 
   const getEntity = (id) => getEntities()[id]
 
-  const notify = (type, payload) => {
-    store.notify(type, payload)
-  }
-
-  const dispatch = (action) => {
-    store.dispatch(action)
-  }
-
-  const getType = (id) => store.getOriginalTypes()?.[id]
-
   return {
     createSelector,
     getTypes,
     getEntities,
     getEntity,
-    getType,
-    notify,
-    dispatch,
+    dispatch: store.dispatch,
+    notify: store.notify,
   }
 }

package/src/entities.js

@@ -0,0 +1,27 @@
+import { map } from "@inglorious/utils/data-structures/object.js"
+
+/**
+ * @typedef {Object.<string, any>} Entity - An object representing a game entity.
+ * @typedef {Object.<string, Entity>} Entities - A collection of named entities.
+ */
+
+/**
+ * Augments a single entity by adding a unique ID.
+ *
+ * @param {string} id The unique ID for the entity.
+ * @param {Entity} entity The raw entity object.
+ * @returns {Entity} The augmented entity, including its ID.
+ */
+export function augmentEntity(id, entity) {
+  return { ...entity, id }
+}
+
+/**
+ * Augments a collection of raw entities, adding a unique ID to each one.
+ *
+ * @param {Entities} entities The raw entities to be augmented.
+ * @returns {Entities} The augmented entities.
+ */
+export function augmentEntities(entities) {
+  return map(entities, augmentEntity)
+}

package/src/entities.test.js

@@ -0,0 +1,51 @@
+import { expect, test } from "vitest"
+
+import { augmentEntities, augmentEntity } from "./entities.js"
+
+test("augmentEntity should add an id to an entity", () => {
+  const entity = { type: "player", health: 100 }
+  const result = augmentEntity("player1", entity)
+
+  expect(result).toStrictEqual({ id: "player1", type: "player", health: 100 })
+})
+
+test("augmentEntity should not mutate the original entity", () => {
+  const entity = { type: "player" }
+  augmentEntity("player1", entity)
+
+  expect(entity).toStrictEqual({ type: "player" })
+  expect(entity).not.toHaveProperty("id")
+})
+
+test("augmentEntity should overwrite an existing id property", () => {
+  const entity = { id: "oldId", type: "player" }
+  const result = augmentEntity("newId", entity)
+
+  expect(result).toStrictEqual({ id: "newId", type: "player" })
+})
+
+test("augmentEntities should augment a collection of entities", () => {
+  const entities = {
+    player1: { type: "player", health: 100 },
+    enemy1: { type: "enemy", damage: 10 },
+  }
+  const result = augmentEntities(entities)
+
+  expect(result).toStrictEqual({
+    player1: { id: "player1", type: "player", health: 100 },
+    enemy1: { id: "enemy1", type: "enemy", damage: 10 },
+  })
+})
+
+test("augmentEntities should handle an empty collection", () => {
+  const result = augmentEntities({})
+
+  expect(result).toStrictEqual({})
+})
+
+test("augmentEntities should not mutate the original entities object", () => {
+  const entities = { player1: { type: "player" } }
+  augmentEntities(entities)
+
+  expect(entities.player1).not.toHaveProperty("id")
+})

package/src/event-map.js

@@ -0,0 +1,75 @@
+/**
+ * @typedef {Object.<string, any>} Type - An object representing an augmented entity type.
+ * @typedef {Object.<string, any>} Entity - An object representing a game entity.
+ */
+
+/**
+ * A class to manage the mapping of event names to the entity IDs that handle them.
+ * This is used for optimized event handling in a game loop.
+ */
+export class EventMap {
+  /**
+   * Creates an instance of EventMap and initializes it with entities and their types.
+   *
+   * @param {Object.<string, Type>} types - An object containing all augmented type definitions.
+   * @param {Object.<string, Entity>} entities - An object containing all game entities.
+   */
+  constructor(types, entities) {
+    /**
+     * The internal map where keys are event names and values are Sets of entity IDs.
+     *
+     * @type {Object.<string, Set<string>>}
+     */
+    this.map = {}
+
+    for (const entityId in entities) {
+      const entity = entities[entityId]
+      const type = types[entity.type]
+      if (type) {
+        this.addEntity(entityId, type)
+      }
+    }
+  }
+
+  /**
+   * Adds an entity's ID to the Sets for all event handlers defined in its type.
+   * This should be called when a new entity is created or its type is morphed.
+   *
+   * @param {string} entityId - The ID of the entity.
+   * @param {Type} type - The augmented type object of the entity.
+   */
+  addEntity(entityId, type) {
+    for (const eventName in type) {
+      if (!this.map[eventName]) {
+        this.map[eventName] = new Set()
+      }
+      this.map[eventName].add(entityId)
+    }
+  }
+
+  /**
+   * Removes an entity's ID from the Sets for all event handlers defined in its type.
+   * This should be called when an entity is removed or its type is morphed.
+   *
+   * @param {string} entityId - The ID of the entity.
+   * @param {Type} type - The augmented type object of the entity.
+   */
+  removeEntity(entityId, type) {
+    for (const eventName in type) {
+      const entitySet = this.map[eventName]
+      if (entitySet) {
+        entitySet.delete(entityId)
+      }
+    }
+  }
+
+  /**
+   * Retrieves the Set of entity IDs that are subscribed to a given event.
+   *
+   * @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.
+   */
+  getEntitiesForEvent(eventName) {
+    return this.map[eventName] || new Set()
+  }
+}

package/src/event-map.test.js

@@ -0,0 +1,168 @@
+import { performance } from "node:perf_hooks"
+
+import { expect, test, vi } from "vitest"
+
+import { EventMap } from "./event-map.js"
+
+test("constructor should initialize the event map from types and entities", () => {
+  const types = {
+    player: {
+      update: () => {},
+      fire: () => {},
+    },
+    enemy: {
+      update: () => {},
+    },
+    item: {}, // Type with no events
+  }
+  const entities = {
+    player1: { type: "player" },
+    player2: { type: "player" },
+    enemy1: { type: "enemy" },
+    item1: { type: "item" },
+    ghost1: { type: "ghost" }, // Type that doesn't exist
+  }
+
+  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"]),
+  )
+
+  // 'item' type has no events, so it shouldn't be in the map
+  expect(eventMap.getEntitiesForEvent("item")).toStrictEqual(new Set())
+  // 'ghost' type doesn't exist, so it should be ignored
+  expect(eventMap.getEntitiesForEvent("ghost")).toStrictEqual(new Set())
+})
+
+test("addEntity should add an entity to the correct event sets", () => {
+  const types = {
+    player: {
+      update: () => {},
+      jump: () => {},
+    },
+  }
+  const eventMap = new EventMap(types, {})
+
+  eventMap.addEntity("player1", types.player)
+
+  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual(
+    new Set(["player1"]),
+  )
+  expect(eventMap.getEntitiesForEvent("jump")).toStrictEqual(
+    new Set(["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"]),
+  )
+})
+
+test("removeEntity should remove an entity from its event sets", () => {
+  const types = {
+    player: {
+      update: () => {},
+      fire: () => {},
+    },
+  }
+  const entities = {
+    player1: { type: "player" },
+    player2: { type: "player" },
+  }
+  const eventMap = new EventMap(types, entities)
+
+  eventMap.removeEntity("player1", types.player)
+
+  expect(eventMap.getEntitiesForEvent("update")).toStrictEqual(
+    new Set(["player2"]),
+  )
+  expect(eventMap.getEntitiesForEvent("fire")).toStrictEqual(
+    new Set(["player2"]),
+  )
+
+  // Removing a non-existent entity should not throw an error
+  expect(() => eventMap.removeEntity("player3", types.player)).not.toThrow()
+})
+
+test("getEntitiesForEvent should return the correct set of entities for an event", () => {
+  const types = {
+    player: { update: () => {} },
+    enemy: { update: () => {} },
+  }
+  const entities = {
+    player1: { type: "player" },
+    enemy1: { type: "enemy" },
+  }
+  const eventMap = new EventMap(types, entities)
+
+  const updateEntities = eventMap.getEntitiesForEvent("update")
+  expect(updateEntities).toStrictEqual(new Set(["player1", "enemy1"]))
+
+  const fireEntities = eventMap.getEntitiesForEvent("fire")
+  expect(fireEntities).toStrictEqual(new Set())
+})
+
+test("EventMap provides a significant performance benefit for event handling", async () => {
+  const ENTITY_COUNT = 10000
+  const { entities, types } = createTestEntities(ENTITY_COUNT)
+  const eventMap = new EventMap(types, entities)
+
+  // We'll use a mock function to ensure the "work" is consistent
+  const updateHandler = vi.fn()
+  types.updater.update = updateHandler
+
+  // --- Simulation A: The Old Way (iterating all entities) ---
+  const oldWayStartTime = performance.now()
+  for (const id in entities) {
+    const entity = entities[id]
+    const type = types[entity.type]
+    if (type.update) {
+      type.update()
+    }
+  }
+  const oldWayTime = performance.now() - oldWayStartTime
+
+  // Reset the mock for the next simulation
+  updateHandler.mockClear()
+
+  // --- Simulation B: The New Way (using EventMap) ---
+  const newWayStartTime = performance.now()
+  const updaterIds = eventMap.getEntitiesForEvent("update")
+  for (const id of updaterIds) {
+    const entity = entities[id]
+    const type = types[entity.type]
+    type.update()
+  }
+  const newWayTime = performance.now() - newWayStartTime
+
+  // Assertions to verify correctness
+  expect(oldWayTime).toBeGreaterThan(newWayTime)
+  expect(updateHandler).toHaveBeenCalledTimes(updaterIds.size)
+})
+
+// Helper function to create a large set of test entities
+function createTestEntities(count) {
+  const entities = {}
+  const types = {}
+  // 10% of entities will have a mock 'update' handler
+  const updaterType = { update: vi.fn() }
+  const staticType = {}
+
+  for (let i = 0; i < count; i++) {
+    const isUpdater = Math.random() < 0.1
+    const typeId = isUpdater ? "updater" : "static"
+    entities[`entity-${i}`] = { id: `entity-${i}`, type: typeId }
+  }
+  types["updater"] = updaterType
+  types["static"] = staticType
+
+  return { entities, types }
+}

package/src/store.js

@@ -1,10 +1,12 @@
-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 { produce } from "immer"
 
+import { augmentEntities, augmentEntity } from "./entities.js"
+import { EventMap } from "./event-map.js"
+import { augmentType, augmentTypes } from "./types.js"
+
 /**
  * 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.
@@ -16,13 +18,11 @@ export function createStore({
   systems = [],
 }) {
   const listeners = new Set()
-  let incomingEvents = []
 
-  let types = augmentTypes(originalTypes)
-  let entities = augmentEntities(originalEntities)
+  const types = augmentTypes(originalTypes)
 
-  const initialState = { entities }
-  let state = initialState
+  let state, eventMap, incomingEvents
+  reset()
 
   return {
     subscribe,
@@ -38,6 +38,7 @@ export function createStore({
 
   /**
    * Subscribes a listener to state updates.
+   *
    * @param {Function} listener - The listener function to call on updates.
    * @returns {Function} A function to unsubscribe the listener.
    */
@@ -51,6 +52,7 @@ 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.
    * @param {Object} api - The engine's public API.
    */
@@ -66,25 +68,43 @@ export function createStore({
 
         if (event.type === "morph") {
           const { id, type } = event.payload
+
+          const entity = state.entities[id]
+          const oldType = types[entity.type]
+
           originalTypes[id] = type
-          types = augmentTypes(originalTypes)
+          types[id] = augmentType(originalTypes[id])
+          const newType = types[id]
+
+          eventMap.removeEntity(id, oldType)
+          eventMap.addEntity(id, newType)
         }
 
         if (event.type === "add") {
           const { id, ...entity } = event.payload
           state.entities[id] = augmentEntity(id, entity)
+          const type = types[entity.type]
+
+          eventMap.addEntity(id, type)
+          incomingEvents.unshift({ type: "create", payload: id })
         }
 
         if (event.type === "remove") {
           const id = event.payload
+          const entity = state.entities[id]
+          const type = types[entity.type]
           delete state.entities[id]
+
+          eventMap.removeEntity(id, type)
+          incomingEvents.unshift({ type: "destroy", payload: id })
         }
 
-        for (const id in state.entities) {
+        const entityIds = eventMap.getEntitiesForEvent(event.type)
+        for (const id of entityIds) {
           const entity = state.entities[id]
           const type = types[entity.type]
           const handle = type[event.type]
-          handle?.(entity, event.payload, api)
+          handle(entity, event.payload, api)
         }
 
         systems.forEach((system) => {
@@ -101,6 +121,7 @@ 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.
    */
@@ -110,6 +131,7 @@ export function createStore({
 
   /**
    * Dispatches an event to be processed in the next update cycle.
+   *
    * @param {Object} event - The event object.
    * @param {string} event.type - The type of the event.
    * @param {any} [event.payload] - The payload of the event.
@@ -121,6 +143,7 @@ export function createStore({
   /**
    * Retrieves the augmented types configuration.
    * This includes composed behaviors and event handlers wrapped for immutability.
+   *
    * @returns {Object} The augmented types configuration.
    */
   function getTypes() {
@@ -129,6 +152,7 @@ export function createStore({
 
   /**
    * Retrieves the original, un-augmented types configuration.
+   *
    * @returns {Object} The original types configuration.
    */
   function getOriginalTypes() {
@@ -137,42 +161,50 @@ export function createStore({
 
   /**
    * Retrieves the current state.
+   *
    * @returns {Object} The current state.
    */
   function getState() {
     return state
   }
 
-  function setState(newState) {
-    state = newState
-  }
-
-  function reset() {
-    state = initialState // Reset state to its originally computed value
-  }
-}
+  /**
+   * 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.
+   */
+  function setState(nextState) {
+    const oldEntities = state?.entities ?? {}
+    const newEntities = augmentEntities(nextState.entities)
 
-function augmentTypes(types) {
-  return pipe(applyBehaviors)(types)
-}
+    state = { entities: newEntities }
+    eventMap = new EventMap(types, nextState.entities)
+    incomingEvents = []
 
-function applyBehaviors(types) {
-  return map(types, (_, type) => {
-    if (!Array.isArray(type)) {
-      return type
-    }
+    const oldEntityIds = new Set(Object.keys(oldEntities))
+    const newEntityIds = new Set(Object.keys(newEntities))
 
-    const behaviors = type.map((fn) =>
-      typeof fn !== "function" ? (type) => extend(type, fn) : fn,
+    const entitiesToCreate = [...newEntityIds].filter(
+      (id) => !oldEntityIds.has(id),
+    )
+    const entitiesToDestroy = [...oldEntityIds].filter(
+      (id) => !newEntityIds.has(id),
     )
-    return pipe(...behaviors)({})
-  })
-}
 
-function augmentEntities(entities) {
-  return map(entities, augmentEntity)
-}
+    entitiesToCreate.forEach((id) => {
+      incomingEvents.push({ type: "create", payload: id })
+    })
 
-function augmentEntity(id, entity) {
-  return { ...entity, id }
+    entitiesToDestroy.forEach((id) => {
+      incomingEvents.push({ type: "destroy", payload: id })
+    })
+  }
+
+  /**
+   * Resets the store to its initial state.
+   */
+  function reset() {
+    setState({ entities: originalEntities })
+  }
 }

package/src/store.test.js

@@ -108,3 +108,45 @@ test("it should remove an entity via a 'remove' event", () => {
   const state = store.getState()
   expect(state.entities.kitty1).toBeUndefined()
 })
+
+test("it should change an entity's behavior via a 'morph' event", () => {
+  const Caterpillar = {
+    eat(entity) {
+      entity.isFull = true
+    },
+  }
+  const Butterfly = {
+    fly(entity) {
+      entity.hasFlown = true
+    },
+  }
+
+  const config = {
+    types: {
+      bug: Caterpillar,
+    },
+
+    entities: {
+      bug: { type: "bug" },
+    },
+  }
+
+  const store = createStore(config)
+
+  store.notify("eat")
+  store.update(0, {})
+  expect(store.getState()).toStrictEqual({
+    entities: {
+      bug: { id: "bug", type: "bug", isFull: true },
+    },
+  })
+
+  store.notify("morph", { id: "bug", type: [Caterpillar, Butterfly] })
+  store.notify("fly")
+  store.update(0, {})
+  expect(store.getState()).toStrictEqual({
+    entities: {
+      bug: { id: "bug", type: "bug", isFull: true, hasFlown: true },
+    },
+  })
+})

package/src/types.js

@@ -0,0 +1,37 @@
+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"
+
+/**
+ * Augments a single type by composing its behaviors and mixins.
+ * If a behavior is an object, it's treated as a mixin and its properties are extended onto the type.
+ * If a behavior is a function, it's called with the current type object to apply its logic.
+ *
+ * @param {Type|AugmentFunction[]} type The raw type definition, which can be an object or an array of mixins/functions.
+ * @returns {Type} The fully composed and augmented type object.
+ */
+export function augmentType(type) {
+  const behaviors = ensureArray(type).map((fn) =>
+    typeof fn !== "function" ? (type) => extend(type, fn) : fn,
+  )
+
+  return pipe(...behaviors)({})
+}
+
+/**
+ * @typedef {Object.<string, any>} Type - An object representing an entity's base type or a behavioral mixin.
+ * @typedef {Object.<string, Type>} Types - A collection of named type definitions.
+ * @typedef {Function} AugmentFunction - A function that applies augmentations.
+ */
+
+/**
+ * Augments a collection of raw type definitions into a usable format.
+ * This process applies all behaviors and mixins to each type.
+ *
+ * @param {Types} types The raw types to be augmented.
+ * @returns {Types} The augmented types, with all behaviors composed.
+ */
+export function augmentTypes(types) {
+  return map(types, (_, type) => augmentType(type))
+}

package/src/types.test.js

@@ -0,0 +1,87 @@
+import { expect, test } from "vitest"
+
+import { augmentType, augmentTypes } from "./types.js"
+
+test("should handle a single behavior object (mixin)", () => {
+  const behavior = { onFire: () => "bang" }
+  const result = augmentType(behavior)
+
+  expect(result).toStrictEqual(behavior)
+  // Ensure it's a new object, not the same reference
+  expect(result).not.toBe(behavior)
+})
+
+test("should compose an array of behavior objects (mixins)", () => {
+  const behavior1 = { onFire: () => "bang", onMove: () => "vroom" }
+  const behavior2 = { onJump: () => "boing", onFire: () => "pow" } // onFire overwrites
+  const result = augmentType([behavior1, behavior2])
+
+  expect(result).toHaveProperty("onMove")
+  expect(result).toHaveProperty("onJump")
+  expect(result).toHaveProperty("onFire")
+  expect(result.onFire()).toBe("pow")
+})
+
+test("should handle a single behavior function", () => {
+  const behavior = (type) => ({ ...type, onJump: () => "boing" })
+  const result = augmentType(behavior)
+
+  expect(result).toHaveProperty("onJump")
+  expect(result.onJump()).toBe("boing")
+})
+
+test("should compose an array of behavior functions (pipe)", () => {
+  const behavior1 = (type) => ({ ...type, onMove: () => "vroom" })
+  const behavior2 = (type) => ({ ...type, onJump: () => "boing" })
+  const result = augmentType([behavior1, behavior2])
+
+  expect(result).toHaveProperty("onMove")
+  expect(result).toHaveProperty("onJump")
+  expect(result.onMove()).toBe("vroom")
+  expect(result.onJump()).toBe("boing")
+})
+
+test("should compose a mixed array of objects and functions", () => {
+  const mixin1 = { onFire: () => "bang" }
+  const behavior1 = (type) => ({ ...type, onJump: () => "boing" })
+  const mixin2 = { onMove: () => "vroom", onFire: () => "pow" } // onFire overwrites
+
+  const result = augmentType([mixin1, behavior1, mixin2])
+
+  expect(result).toHaveProperty("onFire")
+  expect(result).toHaveProperty("onJump")
+  expect(result).toHaveProperty("onMove")
+  expect(result.onFire()).toBe("pow")
+  expect(result.onJump()).toBe("boing")
+  expect(result.onMove()).toBe("vroom")
+})
+
+test("should return an empty object for an empty array", () => {
+  const result = augmentType([])
+  expect(result).toStrictEqual({})
+})
+
+test("should handle undefined or null input gracefully", () => {
+  expect(augmentType(undefined)).toStrictEqual({})
+  expect(augmentType(null)).toStrictEqual({})
+})
+
+test("should augment a map of types correctly", () => {
+  const types = {
+    player: { onJump: () => "boing" },
+    enemy: [
+      { onMove: () => "stomp" },
+      (type) => ({ ...type, onAttack: () => "bite" }),
+    ],
+    item: [],
+  }
+
+  const result = augmentTypes(types)
+
+  expect(result.player).toStrictEqual({ onJump: expect.any(Function) })
+  expect(result.enemy).toStrictEqual({
+    onMove: expect.any(Function),
+    onAttack: expect.any(Function),
+  })
+  expect(result.item).toStrictEqual({})
+})