@inglorious/store 3.0.0 → 4.0.1

package/README.md

@@ -21,7 +21,7 @@ npm install @inglorious/store
 
 The state management is built on a few simple principles:
 
-1.  **Entities and Properties**: The state is composed of **entities**, which are unique objects. Each entity has a **type** and a set of properties (e.g., `position: [0, 0, 0]`, `health: 100`). Unlike a traditional ECS, properties are not grouped into explicit components.
+1.  **Entities and Properties**: The state is composed of **entities**, which are unique objects. Each entity has a **type** and a set of properties (e.g., `position: v(0, 0, 0)`, `health: 100`). Unlike a traditional ECS, properties are not grouped into explicit components.
 
 2.  **Types and Behaviors**: The logic for how entities and the overall state change is defined in **types** and **systems**.
     - **Types** are arrays of **behaviors**. A behavior is an object that contains event handlers (e.g., `update(entity, dt) { ... }`). Behaviors are composable, allowing you to define a type by combining multiple sets of properties and event handlers.
@@ -31,7 +31,7 @@ The state management is built on a few simple principles:
     - The store processes events by first applying behaviors defined on an entity's type, and then running the logic in the systems.
     - An `update` event with a `dt` (delta time) payload is automatically dispatched on every `store.update()` call, making it suitable for a game loop.
 
-4.  **Immutability**: The state is immutable. Updates are handled internally by **[Immer](https://immerjs.github.io/immer/)**, so you can "mutate" the state directly within a type's or system's behavior function, and a new, immutable state will be produced.
+4.  **Immutability**: The state is immutable. Updates are handled internally by **[Mutative](https://mutative.js.org/)**, so you can "mutate" the state directly within a type's or system's behavior function, and a new, immutable state will be created.
 
 ---
 
@@ -101,7 +101,7 @@ Here is a simple example of a player entity that moves based on events.
 
 ```javascript
 import { createStore, createApi } from "@inglorious/store"
-import { add, scale } from "@inglorious/utils/math/linear-algebra/vectors.js"
+import { add, scale } from "@inglorious/utils/math/vectors.js"
 
 // 1. Define the behaviors
 const transform = {
@@ -133,8 +133,8 @@ const types = {
 const entities = {
   player1: {
     type: "player",
-    position: [0, 0, 0],
-    velocity: [0.0625, 0, 0],
+    position: v(0, 0, 0),
+    velocity: v(0.0625, 0, 0),
   },
 }
 
@@ -154,17 +154,17 @@ store.subscribe(() => {
 })
 
 // 7. Notify the store of an event
-console.log("Initial player position:", selectPlayerPosition()) // => [0, 0, 0]
+console.log("Initial player position:", selectPlayerPosition()) // => v(0, 0, 0)
 
 // Dispatch a custom `move` event with a payload
 api.notify("move", { id: "player1", dx: 5, dz: 5 })
 
 // Events are queued but not yet processed
-console.log("Position after notify:", selectPlayerPosition()) // => [0, 0, 0]
+console.log("Position after notify:", selectPlayerPosition()) // => v(0, 0, 0)
 
 // 8. Run the update loop to process the queue and trigger `update` behaviors
 store.update(16) // Pass delta time
-// Console output from subscriber: "State updated! [6, 0, 5]"
+// Console output from subscriber: "State updated! v(6, 0, 5)"
 
-console.log("Final position:", selectPlayerPosition()) // => [6, 0, 5]
+console.log("Final position:", selectPlayerPosition()) // => v(6, 0, 5)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "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",
@@ -27,19 +27,23 @@
     "./*": "./src/*"
   },
   "files": [
-    "src/*"
+    "src"
   ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "immer": "^10.1.1",
-    "@inglorious/utils": "2.0.0"
+    "mutative": "^1.3.0",
+    "@inglorious/utils": "3.5.0"
+  },
+  "peerDependencies": {
+    "@inglorious/utils": "3.5.0"
   },
   "devDependencies": {
     "prettier": "^3.6.2",
     "vite": "^7.1.3",
-    "vitest": "^1.6.1"
+    "vitest": "^1.6.1",
+    "@inglorious/eslint-config": "1.0.0"
   },
   "engines": {
     "node": ">= 22"

package/src/middlewares.js

@@ -0,0 +1,47 @@
+import { compose } from "@inglorious/utils/functions/functions.js"
+
+/**
+ * Applies a list of middleware functions to a store's dispatch method.
+ * @param {...Function} middlewares The middleware functions to apply.
+ * @returns {Function} A store enhancer function.
+ */
+export function applyMiddlewares(...middlewares) {
+  return (store, baseApi) => {
+    let dispatch = () => {
+      throw new Error(
+        "Dispatching while constructing your middleware is not allowed.",
+      )
+    }
+
+    // Enhanced store interface that middlewares receive
+    const middlewareStore = {
+      getState: store.getState,
+      setState: store.setState,
+      dispatch: (...args) => dispatch(...args),
+      notify: (type, payload) => dispatch({ type, payload }),
+    }
+
+    // Enhanced API interface that middlewares receive
+    const middlewareApi = {
+      ...baseApi,
+      dispatch: (...args) => dispatch(...args),
+      notify: (type, payload) => dispatch({ type, payload }),
+    }
+
+    // Create middleware chain - each middleware gets the store and can access baseApi
+    const chain = middlewares.map((middleware) =>
+      middleware(middlewareStore, middlewareApi),
+    )
+
+    // Compose the middleware chain to create enhanced dispatch
+    dispatch = compose(...chain)(store.dispatch)
+
+    // Return enhanced API that external code will use
+    return {
+      ...middlewareApi,
+      // Override dispatch/notify with the middleware-enhanced versions
+      dispatch,
+      notify: (type, payload) => dispatch({ type, payload }),
+    }
+  }
+}

package/src/store.js

@@ -1,12 +1,13 @@
-import { produce } from "immer"
+import { create } from "mutative"
 
+import { createApi } from "./api.js"
 import { augmentEntities, augmentEntity } from "./entities.js"
 import { EventMap } from "./event-map.js"
+import { applyMiddlewares } from "./middlewares.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,6 +17,7 @@ export function createStore({
   types: originalTypes,
   entities: originalEntities,
   systems = [],
+  middlewares = [],
 }) {
   const listeners = new Set()
 
@@ -24,11 +26,12 @@ export function createStore({
   let state, eventMap, incomingEvents
   reset()
 
-  return {
+  const baseStore = {
     subscribe,
     update,
     notify,
     dispatch, // needed for compatibility with Redux
+    getApi,
     getTypes,
     getOriginalTypes,
     getState,
@@ -36,9 +39,16 @@ export function createStore({
     reset,
   }
 
+  const baseApi = createApi(baseStore)
+
+  const api = middlewares.length
+    ? applyMiddlewares(...middlewares)(baseStore, baseApi)
+    : baseApi
+
+  return baseStore
+
   /**
    * Subscribes a listener to state updates.
-   *
    * @param {Function} listener - The listener function to call on updates.
    * @returns {Function} A function to unsubscribe the listener.
    */
@@ -52,14 +62,12 @@ 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(api) {
+  function update() {
     const processedEvents = []
 
-    state = produce(state, (state) => {
+    state = create(state, (draft) => {
       while (incomingEvents.length) {
         const event = incomingEvents.shift()
         processedEvents.push(event)
@@ -67,7 +75,7 @@ export function createStore({
         if (event.type === "morph") {
           const { id, type } = event.payload
 
-          const entity = state.entities[id]
+          const entity = draft.entities[id]
           const oldType = types[entity.type]
 
           originalTypes[id] = type
@@ -80,7 +88,7 @@ export function createStore({
 
         if (event.type === "add") {
           const { id, ...entity } = event.payload
-          state.entities[id] = augmentEntity(id, entity)
+          draft.entities[id] = augmentEntity(id, entity)
           const type = types[entity.type]
 
           eventMap.addEntity(id, type)
@@ -89,9 +97,9 @@ export function createStore({
 
         if (event.type === "remove") {
           const id = event.payload
-          const entity = state.entities[id]
+          const entity = draft.entities[id]
           const type = types[entity.type]
-          delete state.entities[id]
+          delete draft.entities[id]
 
           eventMap.removeEntity(id, type)
           incomingEvents.unshift({ type: "destroy", payload: id })
@@ -99,7 +107,7 @@ export function createStore({
 
         const entityIds = eventMap.getEntitiesForEvent(event.type)
         for (const id of entityIds) {
-          const entity = state.entities[id]
+          const entity = draft.entities[id]
           const type = types[entity.type]
           const handle = type[event.type]
           handle(entity, event.payload, api)
@@ -107,7 +115,7 @@ export function createStore({
 
         systems.forEach((system) => {
           const handle = system[event.type]
-          handle?.(state, event.payload, api)
+          handle?.(draft, event.payload, api)
         })
       }
     })
@@ -119,7 +127,6 @@ 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.
    */
@@ -129,7 +136,6 @@ 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.
@@ -138,10 +144,17 @@ export function createStore({
     incomingEvents.push(event)
   }
 
+  /**
+   * Retrieves the store's API, which includes methods for interacting with the store.
+   * @returns {Object} The API object for the store.
+   */
+  function getApi() {
+    return api
+  }
+
   /**
    * Retrieves the augmented types configuration.
    * This includes composed behaviors and event handlers wrapped for immutability.
-   *
    * @returns {Object} The augmented types configuration.
    */
   function getTypes() {
@@ -150,7 +163,6 @@ export function createStore({
 
   /**
    * Retrieves the original, un-augmented types configuration.
-   *
    * @returns {Object} The original types configuration.
    */
   function getOriginalTypes() {
@@ -159,7 +171,6 @@ export function createStore({
 
   /**
    * Retrieves the current state.
-   *
    * @returns {Object} The current state.
    */
   function getState() {
@@ -169,7 +180,6 @@ export function createStore({
   /**
    * 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) {