@inglorious/store 1.1.0 → 2.0.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.1.0",
+  "version": "2.0.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",

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/store.js

@@ -6,6 +6,7 @@ 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.
@@ -17,14 +18,11 @@ export function createStore({
   systems = [],
 }) {
   const listeners = new Set()
-  let incomingEvents = []
 
   const types = augmentTypes(originalTypes)
-  const eventMap = new EventMap(types, originalEntities)
 
-  const entities = augmentEntities(originalEntities)
-  const initialState = { entities }
-  let state = initialState
+  let state, eventMap, incomingEvents
+  reset()
 
   return {
     subscribe,
@@ -40,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.
    */
@@ -53,15 +52,14 @@ 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.
    */
-  function update(dt, api) {
+  function update(api) {
     const processedEvents = []
 
     state = produce(state, (state) => {
-      incomingEvents.push({ type: "update", payload: dt })
-
       while (incomingEvents.length) {
         const event = incomingEvents.shift()
         processedEvents.push(event)
@@ -86,6 +84,7 @@ export function createStore({
           const type = types[entity.type]
 
           eventMap.addEntity(id, type)
+          incomingEvents.unshift({ type: "create", payload: id })
         }
 
         if (event.type === "remove") {
@@ -95,6 +94,7 @@ export function createStore({
           delete state.entities[id]
 
           eventMap.removeEntity(id, type)
+          incomingEvents.unshift({ type: "destroy", payload: id })
         }
 
         const entityIds = eventMap.getEntitiesForEvent(event.type)
@@ -102,7 +102,7 @@ export function createStore({
           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) => {
@@ -119,6 +119,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.
    */
@@ -128,6 +129,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.
@@ -139,6 +141,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() {
@@ -147,6 +150,7 @@ export function createStore({
 
   /**
    * Retrieves the original, un-augmented types configuration.
+   *
    * @returns {Object} The original types configuration.
    */
   function getOriginalTypes() {
@@ -155,17 +159,50 @@ export function createStore({
 
   /**
    * Retrieves the current state.
+   *
    * @returns {Object} The current state.
    */
   function getState() {
     return state
   }
 
-  function setState(newState) {
-    state = newState
+  /**
+   * 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)
+
+    state = { entities: newEntities }
+    eventMap = new EventMap(types, nextState.entities)
+    incomingEvents = []
+
+    const oldEntityIds = new Set(Object.keys(oldEntities))
+    const newEntityIds = new Set(Object.keys(newEntities))
+
+    const entitiesToCreate = [...newEntityIds].filter(
+      (id) => !oldEntityIds.has(id),
+    )
+    const entitiesToDestroy = [...oldEntityIds].filter(
+      (id) => !newEntityIds.has(id),
+    )
+
+    entitiesToCreate.forEach((id) => {
+      incomingEvents.push({ type: "create", payload: id })
+    })
+
+    entitiesToDestroy.forEach((id) => {
+      incomingEvents.push({ type: "destroy", payload: id })
+    })
   }
 
+  /**
+   * Resets the store to its initial state.
+   */
   function reset() {
-    state = initialState
+    setState({ entities: originalEntities })
   }
 }

package/src/store.test.js

@@ -3,6 +3,37 @@ import { expect, test } from "vitest"
 import { createStore } from "./store.js"
 
 test("it should process events by mutating state inside handlers", () => {
+  const config = {
+    types: {
+      kitty: {
+        feed(entity) {
+          entity.isFed = true
+        },
+      },
+    },
+    entities: {
+      kitty1: { type: "kitty" },
+    },
+  }
+  const afterState = {
+    entities: {
+      kitty1: {
+        id: "kitty1",
+        type: "kitty",
+        isFed: true,
+      },
+    },
+  }
+
+  const store = createStore(config)
+  store.notify("feed")
+  store.update()
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})
+
+test("it should process an event queue in the same update cycle", () => {
   const config = {
     types: {
       kitty: {
@@ -31,7 +62,8 @@ test("it should process events by mutating state inside handlers", () => {
 
   const store = createStore(config)
   store.notify("feed")
-  store.update(0, {})
+  store.notify("update")
+  store.update()
 
   const state = store.getState()
   expect(state).toStrictEqual(afterState)
@@ -65,7 +97,8 @@ test("it should send an event from an entity and process it in the same update c
 
   const store = createStore(config)
   const api = { notify: store.notify }
-  store.update(0, api)
+  store.notify("update")
+  store.update(api)
 
   const state = store.getState()
   expect(state).toStrictEqual(afterState)
@@ -82,7 +115,7 @@ test("it should add an entity via an 'add' event", () => {
 
   const store = createStore(config)
   store.notify("add", newEntity)
-  store.update(0, {})
+  store.update()
 
   const state = store.getState()
   expect(state).toStrictEqual({
@@ -102,8 +135,7 @@ test("it should remove an entity via a 'remove' event", () => {
   const store = createStore(config)
 
   store.notify("remove", "kitty1")
-
-  store.update(0, {})
+  store.update()
 
   const state = store.getState()
   expect(state.entities.kitty1).toBeUndefined()
@@ -134,7 +166,8 @@ test("it should change an entity's behavior via a 'morph' event", () => {
   const store = createStore(config)
 
   store.notify("eat")
-  store.update(0, {})
+  store.update()
+
   expect(store.getState()).toStrictEqual({
     entities: {
       bug: { id: "bug", type: "bug", isFull: true },
@@ -143,7 +176,7 @@ test("it should change an entity's behavior via a 'morph' event", () => {
 
   store.notify("morph", { id: "bug", type: [Caterpillar, Butterfly] })
   store.notify("fly")
-  store.update(0, {})
+  store.update()
   expect(store.getState()).toStrictEqual({
     entities: {
       bug: { id: "bug", type: "bug", isFull: true, hasFlown: true },