@inglorious/store 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 Inglorious Coderz Srl.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# Inglorious Store
+
+[![NPM version](https://img.shields.io/npm/v/@inglorious/store.svg)](https://www.npmjs.com/package/@inglorious/store)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+The core, environment-agnostic state management library for the [Inglorious Engine](https://github.com/IngloriousCoderz/inglorious-engine).
+
+This package provides a powerful and predictable state container based on an **Entity-Component-System (ECS)** architecture, inspired by **[Redux](https://redux.js.org/)** but tailored for game development. It can be used in any JavaScript environment, including Node.js servers and browsers.
+
+---
+
+## Installation
+
+```bash
+npm install @inglorious/store
+```
+
+---
+
+## Core Concepts
+
+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.
+
+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.
+    - **Systems** are objects that contain event handlers to operate on the global state or manage interactions between entities.
+
+3.  **Events and State Updates**: The only way to change the state is by issuing an **event**. An event is a plain object describing what happened (e.g., `{ type: 'move', payload: { id: 'player1', dx: 1 } }`).
+    - 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.
+
+---
+
+## API
+
+### `createStore(options)`
+
+Creates a new store instance.
+
+**Parameters:**
+
+- `options` (object):
+  - `types` (object): A map of entity types. Keys are type names (e.g., `'player'`), and values are arrays of behaviors.
+  - `entities` (object): A map of initial entities. Keys are entity IDs, and values are objects containing the entity's properties.
+  - `systems` (array, optional): An array of system objects, which define behaviors for the whole state.
+
+**Returns:**
+
+- A `store` object with the following methods:
+  - `subscribe(listener)`: Subscribes a `listener` to state changes. The listener is called after `store.update()` is complete. Returns an `unsubscribe` function.
+  - `update(dt, api)`: Processes the event queue and updates the state. This is typically called once per frame. `dt` is the time elapsed since the last frame, and `api` is the engine's public API.
+  - `notify(type, payload)`: Adds a new event to the queue to be processed on the next `update` call.
+  - `dispatch(event)`: A Redux-compatible alias for `notify`.
+  - `getState()`: Returns the current, immutable state.
+  - `setState(newState)`: Replaces the entire state with a new one. Use with caution.
+  - `getTypes()`: Returns the augmented types configuration. Augmenting here means that the array of behaviors is merged into one single behavior.
+  - `getOriginalTypes()`: Returns the original, un-augmented behavior arrays.
+  - `reset()`: Resets the state to its initial configuration.
+
+---
+
+### `createSelector(inputSelectors, resultFunc)`
+
+Creates a memoized selector to efficiently compute derived data from the state. It only recomputes the result if the inputs to the `resultFunc` have changed.
+
+**Parameters:**
+
+- `inputSelectors` (array of functions): An array of selector functions that take the state and return a slice of it.
+- `resultFunc` (function): A function that takes the results of the `inputSelectors` and returns the final computed value.
+
+**Returns:**
+
+- A memoized selector function that takes the `state` as its only argument and returns the selected data.
+
+---
+
+### `createApi(store)`
+
+Creates a convenient API object that encapsulates the store's methods and provides common utility functions for accessing state.
+
+**Parameters:**
+
+- `store` (object): The store instance created with `createStore`.
+
+**Returns:**
+
+- 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.
+  - `notify(type, payload)`, `dispatch(action)`: Aliases to the store's event dispatching methods.
+
+---
+
+## Basic Usage
+
+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"
+
+// 1. Define the behaviors
+const transform = {
+  // The second parameter of an event handler is the payload
+  move: (entity, payload) => {
+    entity.position[0] += payload.dx || 0
+    entity.position[1] += payload.dy || 0
+    entity.position[2] += payload.dz || 0
+  },
+}
+
+const kinematic = {
+  update: (entity, dt) => {
+    // You can use utility functions for easy vector operations
+    entity.position = add(entity.position, scale(entity.velocity, dt))
+  },
+}
+
+// 2. Define the entity types by composing behaviors
+const types = {
+  player: [
+    // Composed behaviors
+    transform,
+    kinematic,
+  ],
+}
+
+// 3. Define the initial entities
+const entities = {
+  player1: {
+    type: "player",
+    position: [0, 0, 0],
+    velocity: [0.0625, 0, 0],
+  },
+}
+
+// 4. Create the store and a unified API
+const store = createStore({ types, entities })
+const api = createApi(store)
+
+// 5. Create selectors to get data from the state
+const selectPlayerPosition = api.createSelector(
+  [(state) => state.entities.player1],
+  (player) => player.position,
+)
+
+// 6. Subscribe to changes
+store.subscribe(() => {
+  console.log("State updated!", selectPlayerPosition())
+})
+
+// 7. Notify the store of an event
+console.log("Initial player position:", selectPlayerPosition()) // => [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]
+
+// 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.log("Final position:", selectPlayerPosition()) // => [6, 0, 5]
+```

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@inglorious/store",
+  "version": "1.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IngloriousCoderz/inglorious-engine.git"
+  },
+  "homepage": "https://inglorious-engine.vercel.app/",
+  "bugs": {
+    "url": "https://github.com/IngloriousCoderz/inglorious-engine/issues"
+  },
+  "keywords": [
+    "functional-programming",
+    "gamedev",
+    "game-engine",
+    "inglorious-engine",
+    "state-manager",
+    "redux",
+    "store"
+  ],
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./*": "./src/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "immer": "^10.1.1",
+    "@inglorious/utils": "1.1.0"
+  },
+  "devDependencies": {
+    "prettier": "^3.6.2",
+    "vite": "^7.1.3",
+    "vitest": "^1.6.1"
+  },
+  "engines": {
+    "node": ">= 22"
+  },
+  "scripts": {
+    "format": "prettier --write '**/*.{js,jsx}'",
+    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
+    "test:watch": "vitest",
+    "test": "vitest run"
+  }
+}

package/src/api.js

@@ -0,0 +1,34 @@
+import { createSelector as _createSelector } from "./select.js"
+
+export function createApi(store) {
+  const createSelector = (inputSelectors, resultFunc) => {
+    const selector = _createSelector(inputSelectors, resultFunc)
+    return () => selector(store.getState())
+  }
+
+  const getTypes = () => store.getTypes()
+
+  const getEntities = () => store.getState().entities
+
+  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,
+  }
+}

package/src/select.js

@@ -0,0 +1,26 @@
+/**
+ * Creates a memoized selector function.
+ * NB: this implementation does not support spreading the input selectors for clarity, please just put them in an array.
+ * @param {Array<Function>} inputSelectors - An array of input selector functions.
+ * @param {Function} resultFunc - A function that receives the results of the input selectors and returns a computed value.
+ * @returns {Function} A memoized selector function that, when called, returns the selected state.
+ */
+export function createSelector(inputSelectors, resultFunc) {
+  let lastInputs = []
+  let lastResult = null
+
+  return (state) => {
+    const nextInputs = inputSelectors.map((selector) => selector(state))
+    const inputsChanged =
+      lastInputs.length !== nextInputs.length ||
+      nextInputs.some((input, index) => input !== lastInputs[index])
+
+    if (!inputsChanged) {
+      return lastResult
+    }
+
+    lastInputs = nextInputs
+    lastResult = resultFunc(...nextInputs)
+    return lastResult
+  }
+}

package/src/store.js

@@ -0,0 +1,178 @@
+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"
+
+/**
+ * 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.
+ * @returns {Object} The store with methods to interact with state and events.
+ */
+export function createStore({
+  types: originalTypes,
+  entities: originalEntities,
+  systems = [],
+}) {
+  const listeners = new Set()
+  let incomingEvents = []
+
+  let types = augmentTypes(originalTypes)
+  let entities = augmentEntities(originalEntities)
+
+  const initialState = { entities }
+  let state = initialState
+
+  return {
+    subscribe,
+    update,
+    notify,
+    dispatch, // needed for compatibility with Redux
+    getTypes,
+    getOriginalTypes,
+    getState,
+    setState,
+    reset,
+  }
+
+  /**
+   * Subscribes a listener to state updates.
+   * @param {Function} listener - The listener function to call on updates.
+   * @returns {Function} A function to unsubscribe the listener.
+   */
+  function subscribe(listener) {
+    listeners.add(listener)
+
+    return function unsubscribe() {
+      listeners.delete(listener)
+    }
+  }
+
+  /**
+   * 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) {
+    const processedEvents = []
+
+    state = produce(state, (state) => {
+      incomingEvents.push({ type: "update", payload: dt })
+
+      while (incomingEvents.length) {
+        const event = incomingEvents.shift()
+        processedEvents.push(event)
+
+        if (event.type === "morph") {
+          const { id, type } = event.payload
+          originalTypes[id] = type
+          types = augmentTypes(originalTypes)
+        }
+
+        if (event.type === "add") {
+          const { id, ...entity } = event.payload
+          state.entities[id] = augmentEntity(id, entity)
+        }
+
+        if (event.type === "remove") {
+          const id = event.payload
+          delete state.entities[id]
+        }
+
+        for (const id in state.entities) {
+          const entity = state.entities[id]
+          const type = types[entity.type]
+          const handle = type[event.type]
+          handle?.(entity, event.payload, api)
+        }
+
+        systems.forEach((system) => {
+          const handle = system[event.type]
+          handle?.(state, event.payload, api)
+        })
+      }
+    })
+
+    listeners.forEach((onUpdate) => onUpdate())
+
+    return processedEvents
+  }
+
+  /**
+   * 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.
+   */
+  function notify(type, payload) {
+    dispatch({ type, payload })
+  }
+
+  /**
+   * 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.
+   */
+  function dispatch(event) {
+    incomingEvents.push(event)
+  }
+
+  /**
+   * Retrieves the augmented types configuration.
+   * This includes composed behaviors and event handlers wrapped for immutability.
+   * @returns {Object} The augmented types configuration.
+   */
+  function getTypes() {
+    return types
+  }
+
+  /**
+   * Retrieves the original, un-augmented types configuration.
+   * @returns {Object} The original types configuration.
+   */
+  function getOriginalTypes() {
+    return originalTypes
+  }
+
+  /**
+   * 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
+  }
+}
+
+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

@@ -0,0 +1,110 @@
+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
+        },
+        update(entity) {
+          entity.isMeowing = true
+        },
+      },
+    },
+    entities: {
+      kitty1: { type: "kitty" },
+    },
+  }
+  const afterState = {
+    entities: {
+      kitty1: {
+        id: "kitty1",
+        type: "kitty",
+        isFed: true,
+        isMeowing: true,
+      },
+    },
+  }
+
+  const store = createStore(config)
+  store.notify("feed")
+  store.update(0, {})
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})
+
+test("it should send an event from an entity and process it in the same update cycle", () => {
+  const config = {
+    types: {
+      doggo: {
+        update(entity, dt, api) {
+          api.notify("bark")
+        },
+      },
+      kitty: {
+        bark(entity) {
+          entity.position = "far"
+        },
+      },
+    },
+    entities: {
+      doggo1: { type: "doggo" },
+      kitty1: { type: "kitty", position: "near" },
+    },
+  }
+  const afterState = {
+    entities: {
+      doggo1: { id: "doggo1", type: "doggo" },
+      kitty1: { id: "kitty1", type: "kitty", position: "far" },
+    },
+  }
+
+  const store = createStore(config)
+  const api = { notify: store.notify }
+  store.update(0, api)
+
+  const state = store.getState()
+  expect(state).toStrictEqual(afterState)
+})
+
+test("it should add an entity via an 'add' event", () => {
+  const config = {
+    types: {
+      kitty: {},
+    },
+    entities: {},
+  }
+  const newEntity = { id: "kitty1", type: "kitty" }
+
+  const store = createStore(config)
+  store.notify("add", newEntity)
+  store.update(0, {})
+
+  const state = store.getState()
+  expect(state).toStrictEqual({
+    entities: {
+      kitty1: { id: "kitty1", type: "kitty" },
+    },
+  })
+})
+
+test("it should remove an entity via a 'remove' event", () => {
+  const config = {
+    types: {},
+    entities: {
+      kitty1: { type: "kitty" },
+    },
+  }
+  const store = createStore(config)
+
+  store.notify("remove", "kitty1")
+
+  store.update(0, {})
+
+  const state = store.getState()
+  expect(state.entities.kitty1).toBeUndefined()
+})