@inglorious/store 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "1.0.0",
+  "version": "1.1.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/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,8 +1,9 @@
-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.
@@ -18,9 +19,10 @@ export function createStore({
   const listeners = new Set()
   let incomingEvents = []
 
-  let types = augmentTypes(originalTypes)
-  let entities = augmentEntities(originalEntities)
+  const types = augmentTypes(originalTypes)
+  const eventMap = new EventMap(types, originalEntities)
 
+  const entities = augmentEntities(originalEntities)
   const initialState = { entities }
   let state = initialState
 
@@ -66,21 +68,37 @@ 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)
         }
 
         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)
         }
 
-        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]
@@ -148,31 +166,6 @@ export function createStore({
   }
 
   function reset() {
-    state = initialState // Reset state to its originally computed value
+    state = initialState
   }
 }
-
-function augmentTypes(types) {
-  return pipe(applyBehaviors)(types)
-}
-
-function applyBehaviors(types) {
-  return map(types, (_, type) => {
-    if (!Array.isArray(type)) {
-      return type
-    }
-
-    const behaviors = type.map((fn) =>
-      typeof fn !== "function" ? (type) => extend(type, fn) : fn,
-    )
-    return pipe(...behaviors)({})
-  })
-}
-
-function augmentEntities(entities) {
-  return map(entities, augmentEntity)
-}
-
-function augmentEntity(id, entity) {
-  return { ...entity, id }
-}

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({})
+})