@inglorious/store 9.0.1 → 9.2.0

package/LICENSE

@@ -1,9 +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.
+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

@@ -651,6 +651,125 @@ Instead of re-rendering after each event, you can batch them and re-render once.
 
 ---
 
+## 🧮 Derived State with `compute`
+
+Inglorious Store is fully compatible with Redux selectors, but it also provides a simpler, more explicit primitive for derived state: **`compute`**.
+
+`compute` lets you derive values from the store state in a predictable and memoized way, without hidden reactivity or dependency graphs.
+
+### Basic example
+
+```js
+import { compute } from "@inglorious/store"
+
+const selectCounter = (state) => state.counter1.value
+const selectMultiplier = (state) => state.settings.multiplier
+
+const selectResult = compute(
+  (count, multiplier) => count * multiplier,
+  [selectCounter, selectMultiplier],
+)
+```
+
+The returned function is a standard selector:
+
+```js
+const result = selectResult(api.getEntities())
+```
+
+And it works seamlessly with `react-redux` or `@inglorious/react-store`:
+
+```js
+const value = useSelector(selectResult)
+```
+
+---
+
+### How `compute` works
+
+- Each **input selector** is called with the current state
+- The results are compared using **strict equality (`===`)**
+- If none of the inputs changed, the **previous result is reused**
+- If at least one input changed, the result is recomputed
+
+There is:
+
+- ❌ no deep comparison
+- ❌ no proxy-based reactivity
+- ❌ no implicit dependency tracking
+
+Memoization is **explicit and predictable**, based purely on the values returned by your selectors.
+
+---
+
+### Why `compute` instead of magic reactivity?
+
+`compute` matches the core philosophy of Inglorious Store:
+
+- derived state is just a function
+- updates are explicit
+- behavior is easy to reason about
+- performance characteristics are obvious
+
+If an input selector returns a new reference, the computation runs again.
+If it doesn’t, it won’t.
+
+No surprises.
+
+---
+
+### Zero or single input selectors
+
+`compute` supports any number of inputs — including zero:
+
+```js
+const selectConstant = compute(() => 42)
+```
+
+Or just one:
+
+```js
+const selectDouble = compute(
+  (count) => count * 2,
+  [(entities) => entities.counter1.value],
+)
+```
+
+---
+
+### `createSelector` (Redux compatibility)
+
+For migration and familiarity, Inglorious Store also exports `createSelector`, which is fully compatible with Redux:
+
+```js
+import { createSelector } from "@inglorious/store"
+
+const selectResult = createSelector(
+  [(state) => state.counter1.value],
+  (count) => count * 2,
+)
+```
+
+Internally, `createSelector` is just an alias for `compute`.
+
+> **Note:** `compute` is the preferred API for new code.
+> `createSelector` exists mainly for Redux compatibility and migration.
+
+---
+
+### When to use `compute`
+
+Use `compute` when:
+
+- you need derived or aggregated state
+- you want memoization without magic
+- you want selectors that are easy to test
+- you want predictable recomputation rules
+
+If you already know Redux selectors, you already know how to use `compute` — just with fewer rules and less ceremony.
+
+---
+
 ## Comparison with Other State Libraries
 
 | Feature                   | Redux        | RTK          | Zustand    | Jotai      | Pinia      | MobX       | Inglorious Store |
@@ -675,12 +794,75 @@ const store = createStore({
   types, // Object: entity type definitions
   entities, // Object: initial entities
   systems, // Array (optional): global state handlers
+  autoCreateEntities, // Boolean (optional): false (default) or true
   updateMode, // String (optional): 'auto' (default) or 'manual'
 })
 ```
 
 **Returns:** A Redux-compatible store
 
+**Options:**
+
+- **`types`** (required) - Object defining entity type behaviors
+- **`entities`** (required) - Object containing initial entity instances
+- **`systems`** (optional) - Array of global state handlers
+- **`autoCreateEntities`** (optional) - Automatically create singleton entities for types not defined in `entities`:
+  - `false` (default) - Only use explicitly defined entities
+  - `true` - Auto-create entities matching their type name
+- **`updateMode`** (optional) - Controls when React components re-render:
+  - `'auto'` (default) - Automatic updates after each event
+  - `'manual'` - Manual control via `api.update()`
+
+#### Auto-Create Entities
+
+When `autoCreateEntities: true`, the store automatically creates singleton entities for any type that doesn't have a corresponding entity defined. This is particularly useful for singleton-type entities that behave like components, eliminating the need to switch between type definitions and entity declarations.
+
+```javascript
+const types = {
+  settings: {
+    setTheme(entity, theme) {
+      entity.theme = theme
+    },
+  },
+  analytics: {
+    track(entity, event) {
+      entity.events.push(event)
+    },
+  },
+}
+
+// Without autoCreateEntities (default)
+const entities = {
+  settings: { type: "settings", theme: "dark" },
+  analytics: { type: "analytics", events: [] },
+}
+
+// With autoCreateEntities: true
+const entities = {
+  // settings and analytics will be auto-created as:
+  // settings: { type: "settings" }
+  // analytics: { type: "analytics" }
+}
+
+const store = createStore({
+  types,
+  entities,
+  autoCreateEntities: true,
+})
+
+// Both approaches work the same way
+store.notify("settings:setTheme", "light")
+store.notify("analytics:track", { action: "click" })
+```
+
+**When to use `autoCreateEntities`:**
+
+- ✅ Building web applications with singleton services (settings, auth, analytics)
+- ✅ Component-like entities that only need one instance
+- ✅ Rapid prototyping where you want to add types without ceremony
+- ❌ Game development with multiple entity instances (players, enemies, items)
+- ❌ When you need fine control over initial entity state
+
 ### Types Definition
 
 ```javascript
@@ -733,6 +915,8 @@ store.notify("eventName", payload)
 store.dispatch({ type: "eventName", payload }) // Redux-compatible alternative
 ```
 
+---
+
 ### 🧩 Type Safety
 
 Inglorious Store is written in JavaScript but comes with powerful TypeScript support out of the box, allowing for a fully type-safe experience similar to Redux Toolkit, but with less boilerplate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "9.0.1",
+  "version": "9.2.0",
   "description": "A state manager for real-time, collaborative apps, inspired by game development patterns and compatible with Redux.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",

package/src/select.js

@@ -1,17 +1,43 @@
 /**
- * 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.
+ * @typedef {import('../types/select').InputSelector} InputSelector
+ * @typedef {import('../types/select').OutputSelector} OutputSelector
  */
-export function createSelector(inputSelectors, resultFunc) {
-  let lastInputs = []
-  let lastResult = null
+
+/**
+ * Creates a memoized derived computation from one or more input selectors.
+ *
+ * `compute` returns a function that, given the application state, will:
+ * - run each input selector with the state
+ * - compare the results with the previous invocation using strict equality
+ * - recompute the result only if at least one input has changed
+ *
+ * This is a simple, explicit memoization utility.
+ * There is no dependency tracking, deep comparison, or reactive graph:
+ * memoization is based solely on referential equality of selector outputs.
+ *
+ * @template TState
+ * @template TResult
+ *
+ * @param {(…inputs: any[]) => TResult} resultFunc
+ * A function that receives the results of the input selectors and returns
+ * the computed value.
+ *
+ * @param {InputSelector<TState, any>[]} inputSelectors
+ * An array of selector functions used to extract inputs from the state (optional).
+ *
+ * @returns {OutputSelector<TState, TResult>}
+ * A memoized function that computes and returns the derived value.
+ */
+export function compute(resultFunc, inputSelectors = []) {
+  let lastInputs
+  let lastResult
+  let initialized = false
 
   return (state) => {
     const nextInputs = inputSelectors.map((selector) => selector(state))
+
     const inputsChanged =
+      !initialized ||
       lastInputs.length !== nextInputs.length ||
       nextInputs.some((input, index) => input !== lastInputs[index])
 
@@ -21,6 +47,30 @@ export function createSelector(inputSelectors, resultFunc) {
 
     lastInputs = nextInputs
     lastResult = resultFunc(...nextInputs)
+    initialized = true
     return lastResult
   }
 }
+
+/**
+ * Redux-compatible alias for {@link compute}.
+ *
+ * This function exists for familiarity and migration purposes.
+ * Prefer using `compute` directly in new code.
+ *
+ * @template TState
+ * @template TResult
+ *
+ * @param {InputSelector<TState, any>[]} inputSelectors
+ * An array of input selector functions.
+ *
+ * @param {(…inputs: any[]) => TResult} resultFunc
+ * A function that receives the results of the input selectors and returns
+ * a computed value.
+ *
+ * @returns {OutputSelector<TState, TResult>}
+ * A memoized selector function.
+ */
+export function createSelector(inputSelectors, resultFunc) {
+  return compute(resultFunc, inputSelectors)
+}

package/src/store.js

@@ -13,6 +13,7 @@ import { augmentType, augmentTypes } from "./types.js"
  * @param {Object} [config.entities] - The initial entities configuration.
  * @param {Array} [config.systems] - The initial systems configuration.
  * @param {Array} [config.middlewares] - The initial middlewares configuration.
+ * @param {boolean} [config.autoCreateEntities] - Creates entities if not defined in `config.entities`.
  * @param {"auto" | "manual"} [config.updateMode] - The update mode (defaults to "auto").
  * @returns {Object} The store with methods to interact with state and events.
  */
@@ -21,6 +22,7 @@ export function createStore({
   entities: originalEntities = {},
   systems = [],
   middlewares = [],
+  autoCreateEntities = false,
   updateMode = "auto",
 } = {}) {
   const listeners = new Set()
@@ -220,8 +222,25 @@ export function createStore({
     const oldEntities = state ?? {}
     const newEntities = augmentEntities(nextState)
 
+    if (autoCreateEntities) {
+      for (const typeName of Object.keys(types)) {
+        // Check if entity already exists
+        const hasEntity = Object.values(newEntities).some(
+          (entity) => entity.type === typeName,
+        )
+
+        if (!hasEntity) {
+          // No entity for this type → auto-create minimal entity
+          newEntities[typeName] = {
+            id: typeName,
+            type: typeName,
+          }
+        }
+      }
+    }
+
     state = newEntities
-    eventMap = new EventMap(types, nextState)
+    eventMap = new EventMap(types, newEntities)
     incomingEvents = []
     isProcessing = false
 

package/types/client/multiplayer-middleware.d.ts

@@ -0,0 +1,55 @@
+import type { BaseEntity, EntitiesState, Middleware } from "../store"
+
+/**
+ * A generic event dispatched through the store.
+ */
+export interface MultiplayerEvent {
+  type: string
+  payload?: unknown
+  fromServer?: boolean
+  [key: string]: unknown
+}
+
+/**
+ * Configuration options for the multiplayer middleware.
+ */
+export interface MultiplayerMiddlewareConfig {
+  /**
+   * WebSocket server URL.
+   * Defaults to ws://<current-hostname>:3000
+   */
+  serverUrl?: string
+
+  /**
+   * Delay (in milliseconds) before attempting to reconnect
+   * after the WebSocket connection is closed.
+   *
+   * @default 1000
+   */
+  reconnectionDelay?: number
+
+  /**
+   * Event types that should NOT be sent to the server.
+   */
+  blacklist?: string[]
+
+  /**
+   * Event types that SHOULD be sent to the server.
+   * If provided, only these events are sent.
+   */
+  whitelist?: string[]
+
+  /**
+   * Custom predicate to decide whether an event
+   * should be sent to the server.
+   */
+  filter?: (event: MultiplayerEvent) => boolean
+}
+
+/**
+ * Creates the multiplayer middleware.
+ */
+export function multiplayerMiddleware<
+  T extends BaseEntity = BaseEntity,
+  S extends EntitiesState<T> = EntitiesState<T>,
+>(config?: MultiplayerMiddlewareConfig): Middleware<T, S>

package/types/select.d.ts

@@ -13,12 +13,26 @@ export type OutputSelector<TState = any, TResult = any> = (
 ) => TResult
 
 /**
- * Creates a memoized selector function.
- * @param inputSelectors - An array of input selector functions.
- * @param resultFunc - A function that receives the results of the input selectors and returns a computed value.
- * @returns A memoized selector function that, when called, returns the selected state.
+ * Creates a memoized derived computation from input selectors.
  */
-export function createSelector<TState = any, TResult = any>(
-  inputSelectors: InputSelector<TState, any>[],
-  resultFunc: (...args: any[]) => TResult,
+export function compute<TState, TInputs extends readonly unknown[], TResult>(
+  resultFunc: (...args: TInputs) => TResult,
+  inputSelectors: {
+    [K in keyof TInputs]: InputSelector<TState, TInputs[K]>
+  },
+): OutputSelector<TState, TResult>
+
+/**
+ * Redux-compatible alias for `compute`.
+ * Prefer `compute` in new code.
+ */
+export function createSelector<
+  TState,
+  TInputs extends readonly unknown[],
+  TResult,
+>(
+  inputSelectors: {
+    [K in keyof TInputs]: InputSelector<TState, TInputs[K]>
+  },
+  resultFunc: (...args: TInputs) => TResult,
 ): OutputSelector<TState, TResult>

package/types/store.d.ts

@@ -53,6 +53,7 @@ export interface StoreConfig<
   entities?: TState
   systems?: System<TState>[]
   middlewares?: Middleware<TEntity, TState>[]
+  autoCreateEntities?: boolean
   mode?: "eager" | "batched"
 }