@inglorious/store 5.5.0 → 6.0.0

package/README.md

@@ -3,203 +3,180 @@
 [![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)
 
-**Build apps that are already multiplayer-ready.**
+A Redux-compatible state management library inspired by game development architecture.
 
-Inglorious Store uses battle-tested patterns from game development to give you an architecture that scales from simple solo apps to real-time collaboration—without refactoring. Start with a basic todo list today. Add collaborative features next year. Same code, zero rewrites.
-
-Why settle for state management that wasn't designed for real-time sync? Games solved distributed state synchronization decades ago. Now you can use the same proven patterns for your apps.
+**Drop-in replacement for Redux.** Works with `react-redux` and Redux DevTools. Adds entity-based state management (ECS) for simpler, more predictable code.
 
 ---
 
-## Why Video Game Patterns?
-
-Games solved the hardest real-time problems: syncing state across laggy networks with hundreds of players at 60fps. They use:
+## Why Inglorious Store?
 
-- **Deterministic event processing** - same events + same handlers = guaranteed identical state
-- **Event queues** - natural ordering and conflict resolution
-- **Serializable state** - trivial to send over the network
-- **Client-side prediction** - responsive UIs that stay in sync
+Redux is powerful but verbose. You need action creators, reducers, middleware for async operations, and a bunch of decisions about where logic should live. Redux Toolkit cuts the boilerplate, but you're still writing a lot of ceremony.
 
-These patterns aren't just for games. They're perfect for any app that might need:
+Inglorious Store ditches the ceremony entirely with **entity-based architecture** inspired by game engines. The same ECS patterns that power AAA games power your state management.
 
-- Real-time collaboration (like Notion, Figma)
-- Live updates (dashboards, chat)
-- Undo/redo and time-travel debugging
-- Multiplayer features
+**Key benefits:**
 
-**The best part?** You get this architecture from day one, even for simple apps. When you need these features later, they're already built-in.
+- ✅ Drop-in Redux replacement (same API with `react-redux`)
+- ✅ Entity-based state (manage multiple instances effortlessly)
+- ✅ No action creators, thunks, or slices
+- ✅ Predictable, testable, purely functional code
+- ✅ Built-in lifecycle events (`add`, `remove`, `morph`)
+- ✅ 10x faster immutability than Redux Toolkit (Mutative vs Immer)
 
 ---
 
 ## Installation
 
 ```bash
-npm install @inglorious/store
+npm install @inglorious/store react-redux
 ```
 
-**For React apps**, also install the React bindings:
-
-```bash
-npm install @inglorious/react-store
-```
-
-See [@inglorious/react-store](https://github.com/IngloriousCoderz/inglorious-engine/tree/main/packages/react-store) for React-specific documentation.
+**For React:** Works with standard `react-redux` without any extra packages.
 
 ---
 
-## Update Modes
-
-Inglorious Store supports two update modes:
+## Quick Comparison: Redux vs RTK vs Inglorious Store
 
-### Eager Mode (default) - Like Redux
+### Redux
 
 ```javascript
-const store = createStore({ types, entities }) // mode: "eager" is default
-store.notify("addTodo", { text: "Buy milk" })
-// State updates immediately, no need to call update()
-```
-
-**Best for:** Simple apps with synchronous logic.
-
-**Limitation:** If an event handler needs to dispatch another event, only the first event processes. Use batched mode for event chains.
-
-### Batched Mode - Like game engines
+// Action creators
+const addTodo = (text) => ({ type: "ADD_TODO", payload: text })
+
+// Reducer
+const todosReducer = (state = [], action) => {
+  switch (action.type) {
+    case "ADD_TODO":
+      return [...state, { id: Date.now(), text: action.payload }]
+    default:
+      return state
+  }
+}
 
-```javascript
-const store = createStore({ types, entities, mode: "batched" })
-store.notify("addTodo", { text: "Buy milk" })
-store.notify("toggleTodo", "todo1")
-store.update() // Process all queued events at once
+// Store setup
+const store = configureStore({
+  reducer: { todos: todosReducer },
+})
 ```
 
-**Best for:**
+### Redux Toolkit
 
-- Apps with async operations (API calls, data fetching)
-- Event handlers that dispatch other events
-- Games, animations, or high-frequency updates
-- Explicit control over when state updates
+```javascript
+const todosSlice = createSlice({
+  name: "todos",
+  initialState: [],
+  reducers: {
+    addTodo: (state, action) => {
+      state.push({ id: Date.now(), text: action.payload })
+    },
+  },
+  extraReducers: (builder) => {
+    builder.addCase(otherAction, (state, action) => {
+      // Handle action from other slice
+    })
+  },
+})
 
-**Why batched mode for async?**
+const store = configureStore({
+  reducer: { todos: todosSlice.reducer },
+})
+```
 
-When fetching data from an API, you typically need two events: one to initiate the fetch, and another to store the result. Batched mode allows this pattern:
+### Inglorious Store
 
 ```javascript
+// Define entity types and their behavior
 const types = {
   todoList: {
-    async fetchTodos(entity, payload, api) {
-      const response = await fetch("/api/todos")
-      const todos = await response.json()
-
-      // This event will be processed in the same update cycle
-      api.notify("todosReceived", todos)
-    },
-
-    todosReceived(entity, todos) {
-      entity.todos = todos
-      entity.loading = false
+    addTodo(entity, text) {
+      entity.todos.push({ id: Date.now(), text })
     },
   },
 }
 
-// In your app
-store.notify("fetchTodos")
-await store.update() // Both fetchTodos AND todosReceived process together
-```
-
-In eager mode, only `fetchTodos` would process, and `todosReceived` would be ignored.
-
----
-
-## Key Features
-
-### 🎮 **Entity-Based State**
-
-Define behavior once, reuse it across all instances of the same type. Perfect for managing collections (todos, messages, cart items).
-
-```javascript
-// Define behavior for ALL todos
-const todoType = {
-  toggle(todo, id) {
-    if (todo.id !== id) return
-    todo.completed = !todo.completed
-  },
+// Define initial entities
+const entities = {
+  work: { type: "todoList", todos: [] },
+  personal: { type: "todoList", todos: [] },
 }
 
-// Toggle specific todos
-store.notify("toggle", "todo1")
-store.notify("toggle", "todo2")
+// Create store
+const store = createStore({ types, entities })
 ```
 
-> **Important:** `toggle` is not a method—it's an **event handler**. When you notify an event, it's broadcast to **all entities** that have that handler (pub/sub pattern). Use the payload to filter which entities should respond.
-
-### 🔄 **Event Queue with Batching**
+**Key differences:**
 
-Events are queued and processed together in batched mode, preventing cascading updates and enabling predictable state changes.
+- ❌ No action creators
+- ❌ No switch statements or cases
+- ❌ No slice definitions with extraReducers
+- ✅ Define what each entity type can do
+- ✅ Add multiple instances by adding entities, not code
 
-```javascript
-const store = createStore({ types, entities, mode: "batched" })
-
-// Dispatch multiple events
-store.notify("increment", "counter1")
-store.notify("increment", "counter2")
-store.notify("increment", "counter3")
+---
 
-// Process all at once (single React re-render)
-store.update()
-```
+## Core Concepts
 
-### ⏱️ **Time-Travel Debugging**
+### 🎮 Entities and Types
 
-Save and replay state at any point—built-in, not an afterthought.
+State consists of **entities** (instances) that have a **type** (behavior definition). Think of type as a class and entities as instances:
 
 ```javascript
-const snapshot = store.getState()
-// ... user makes changes ...
-store.setState(snapshot) // Instant undo
-```
-
-### 🌐 **Multiplayer-Ready**
+const entities = {
+  workTodos: { type: "todoList", todos: [], priority: "high" },
+  personalTodos: { type: "todoList", todos: [], priority: "low" },
+  settings: { type: "settings", theme: "dark", language: "en" },
+}
 
-Synchronize state across clients by sending serializable events. Same events + same handlers = guaranteed sync.
+const types = {
+  todoList: {
+    addTodo(entity, text) {
+      entity.todos.push({ id: Date.now(), text })
+    },
+    toggle(entity, id) {
+      const todo = entity.todos.find((t) => t.id === id)
+      if (todo) todo.completed = !todo.completed
+    },
+  },
+  settings: {
+    setTheme(entity, theme) {
+      entity.theme = theme
+    },
+  },
+}
+```
 
-```javascript
-// Start building solo
-store.notify("addTodo", { text: "Buy milk" })
+**Why this matters:**
 
-// Add multiplayer later in ~10 lines
-socket.on("remote-event", (event) => {
-  store.notify(event.type, event.payload)
-  // States stay perfectly in sync across all clients
-})
-```
+- Same behavior applies to all instances of that type
+- No need to write separate code for each instance
+- Your mental model matches your code structure
 
-### ✍️ **Ergonomic Immutability**
+### 🔄 Event Handlers (Not Reducers)
 
-Write code that looks mutable, get immutable updates automatically via [Mutative](https://mutative.js.org/).
+Unlike Redux reducers, Inglorious Store uses **event handlers** that mutate directly. Immutability is guaranteed under the hood by Mutative (10x faster than Immer):
 
 ```javascript
-// Looks like mutation, but creates new immutable state
-const todoType = {
-  rename(todo, text) {
-    todo.text = text // So clean!
+const types = {
+  counter: {
+    increment(counter) {
+      counter.value++ // Looks like mutation, immutable in reality
+    },
   },
 }
 ```
 
-### 🔗 **Redux-Compatible**
-
-Works with `react-redux` and Redux DevTools. Provides both `notify()` and `dispatch()` for compatibility.
-
 ---
 
-## Quick Start
+## Installation & Setup
 
-### Simple Counter Example
+### Basic Setup (React)
 
 ```javascript
 import { createStore } from "@inglorious/store"
+import { Provider, useSelector, useDispatch } from "react-redux"
 
-// Types can be a single behavior (not an array) for simplicity
+// 1. Define entity types
 const types = {
   counter: {
     increment(counter) {
@@ -211,674 +188,429 @@ const types = {
   },
 }
 
+// 2. Define initial entities
 const entities = {
   counter1: { type: "counter", value: 0 },
-  counter2: { type: "counter", value: 10 },
 }
 
+// 3. Create store
 const store = createStore({ types, entities })
 
-// One event updates ALL counters
-store.notify("increment")
-store.update()
-
-console.log(store.getState().counter1.value) // => 1
-console.log(store.getState().counter2.value) // => 11
+// 4. Use with react-redux
+function App() {
+  return (
+    <Provider store={store}>
+      <Counter />
+    </Provider>
+  )
+}
 
-// To update just one counter, add filtering logic in the handler
+function Counter() {
+  const dispatch = useDispatch()
+  const count = useSelector((state) => state.counter1.value)
+
+  return (
+    <div>
+      <p>{count}</p>
+      <button onClick={() => dispatch({ type: "increment" })}>+</button>
+      <button onClick={() => dispatch({ type: "decrement" })}>-</button>
+    </div>
+  )
+}
 ```
 
-### Complete Todo App Example
+### With @inglorious/react-store (Recommended)
 
 ```javascript
-import { createStore } from "@inglorious/store"
-import { createSelector } from "@inglorious/store/select"
+import { createReactStore } from "@inglorious/react-store"
 
-// 1. Define types (can be a single behavior or array of behaviors)
-const types = {
-  form: {
-    inputChange(entity, value) {
-      entity.value = value
-    },
-    formSubmit(entity) {
-      entity.value = ""
-    },
-  },
-
-  list: {
-    formSubmit(entity, value) {
-      entity.tasks.push({
-        id: entity.tasks.length + 1,
-        text: value,
-        completed: false,
-      })
-    },
-    toggleClick(entity, id) {
-      const task = entity.tasks.find((task) => task.id === id)
-      task.completed = !task.completed
-    },
-    deleteClick(entity, id) {
-      const index = entity.tasks.findIndex((task) => task.id === id)
-      entity.tasks.splice(index, 1)
-    },
-    clearClick(entity) {
-      entity.tasks = entity.tasks.filter((task) => !task.completed)
-    },
-  },
+export const { Provider, useSelector, useNotify } = createReactStore(store)
 
-  footer: {
-    filterClick(entity, filter) {
-      entity.activeFilter = filter
-    },
-  },
+function App() {
+  return (
+    <Provider>
+      <Counter />
+    </Provider>
+  ) // No store prop needed
 }
 
-// 2. Define initial entities
-const entities = {
-  form: {
-    type: "form",
-    value: "",
-  },
-  list: {
-    type: "list",
-    tasks: [],
-  },
-  footer: {
-    type: "footer",
-    activeFilter: "all",
-  },
+function Counter() {
+  const notify = useNotify()
+  const count = useSelector((state) => state.counter1.value)
+
+  return (
+    <div>
+      <p>{count}</p>
+      <button onClick={() => notify("increment")}>+</button> // cleaner API
+      <button onClick={() => notify("decrement")}>-</button>
+    </div>
+  )
 }
-
-// 3. Create store
-const store = createStore({ types, entities })
-
-// 4. Create selectors
-const selectTasks = (state) => state.list.tasks
-const selectActiveFilter = (state) => state.footer.activeFilter
-
-const selectFilteredTasks = createSelector(
-  [selectTasks, selectActiveFilter],
-  (tasks, activeFilter) => {
-    switch (activeFilter) {
-      case "active":
-        return tasks.filter((t) => !t.completed)
-      case "completed":
-        return tasks.filter((t) => t.completed)
-      default:
-        return tasks
-    }
-  },
-)
-
-// 5. Subscribe to changes
-store.subscribe(() => {
-  console.log("Filtered tasks:", selectFilteredTasks(store.getState()))
-})
-
-// 6. Dispatch events (use notify or dispatch - both work!)
-store.notify("inputChange", "Buy milk")
-store.notify("formSubmit", store.getState().form.value)
-store.notify("toggleClick", 1) // Only task with id=1 will respond
-store.notify("filterClick", "active")
-
-// 7. Process event queue (in eager mode this happens automatically)
-store.update()
 ```
 
 ---
 
-## Core Concepts
+## Core Features
 
-### Pub/Sub Event Architecture
+### 🎮 Entity-Based State
 
-**This is not OOP with methods—it's a pub/sub (publish/subscribe) event system.**
+The real power: add entities dynamically without code changes.
 
-When you call `store.notify('toggle', 'todo1')`, the `toggle` event is broadcast to **all entities**. Any entity that has a `toggle` handler will process the event and decide whether to respond based on the payload.
+**Redux/RTK:** To manage three todo lists, you can reuse a reducer, but you're still managing multiple slices manually:
 
 ```javascript
-const todoType = {
-  // This handler runs for EVERY todo when 'toggle' is notified
-  toggle(todo, id) {
-    if (todo.id !== id) return // Filter: only this todo responds
-    todo.completed = !todo.completed
+// Redux - manual management
+const store = configureStore({
+  reducer: {
+    workTodos: todosReducer,
+    personalTodos: todosReducer,
+    shoppingTodos: todosReducer,
   },
-}
-
-// This broadcasts 'toggle' to all entities
-store.notify("toggle", "todo1") // Only todo1 actually updates
+})
 ```
 
-**Why this matters:**
-
-- ✅ Multiple entities of different types can respond to the same event
-- ✅ Enables reactive, decoupled behavior
-- ✅ Perfect for coordinating related entities
-- ✅ Natural fit for multiplayer/real-time sync
-
-**Example of multiple entities responding:**
+**Inglorious Store:** Same behavior, no duplication:
 
 ```javascript
 const types = {
-  player: {
-    gameOver(player) {
-      player.active = false
-    },
-  },
-  enemy: {
-    gameOver(enemy) {
-      enemy.active = false
-    },
-  },
-  ui: {
-    gameOver(ui) {
-      ui.showGameOverScreen = true
+  todoList: {
+    addTodo(entity, text) {
+      entity.todos.push({ id: Date.now(), text })
     },
   },
 }
 
-// One event, all three entity types respond (if they have the handler)
-store.notify("gameOver")
+const entities = {
+  work: { type: "todoList", todos: [] },
+  personal: { type: "todoList", todos: [] },
+  shopping: { type: "todoList", todos: [] },
+}
 ```
 
-### Entities and Types
-
-Your state is a collection of **entities** (instances) organized by **type** (like classes or models).
+**The kicker:** Add a new list at runtime:
 
 ```javascript
-const entities = {
-  item1: { type: "cartItem", name: "Shoes", quantity: 1, price: 99 },
-  item2: { type: "cartItem", name: "Shirt", quantity: 2, price: 29 },
-}
+// Redux/RTK - would need to restructure the store
+// Inglorious Store - just notify the built-in 'add' event
+store.notify("add", { id: "archive", type: "todoList", todos: [] })
+
+// This triggers the 'create' lifecycle event for the new entity
 ```
 
-### Behaviors
+**Lifecycle events:**
 
-Define how entities respond to events. Behaviors can be a single object or an array of composable objects.
+Inglorious Store provides three built-in lifecycle events that are broadcast like any other event:
 
-```javascript
-// Single behavior (simple)
-const counterType = {
-  increment(counter) {
-    counter.value++
-  },
-  decrement(counter) {
-    counter.value--
-  },
-}
+- **`create`** - triggered when a new entity is added via the `add` event
+- **`destroy`** - triggered when an entity is removed via the `remove` event
+- **`morph`** - change an entity's type on the fly (like Redux's `replaceReducer` for individual entities)
 
-// Array of behaviors (composable)
-const cartItemType = [
-  {
-    incrementQuantity(item) {
-      item.quantity++
+Remember: events are broadcast to all entities. Each handler decides if it should respond:
+
+```javascript
+const types = {
+  todoList: {
+    // Every todoList receives the 'create' event, but only the new one should act on it
+    create(entity, id) {
+      if (entity.id !== id) return
+      entity.createdAt = Date.now()
     },
-    decrementQuantity(item) {
-      if (item.quantity > 1) item.quantity--
+
+    destroy(entity, id) {
+      if (entity.id !== id) return
+      console.log(`Archived list: ${entity.id}`)
     },
-  },
-  {
-    applyDiscount(item, percent) {
-      item.price = item.price * (1 - percent / 100)
+
+    addTodo(entity, text) {
+      entity.todos.push({ id: Date.now(), text })
     },
   },
-]
+}
 ```
 
-### Behavior Composition with Functions
+### 🔊 Event Broadcasting
 
-Behaviors can also be functions that wrap and extend other behaviors. This enables decorator-like patterns and middleware:
+Events are broadcast to all entities via pub/sub. Every entity handler receives every event of that type. Each handler decides whether to respond based on the payload:
 
 ```javascript
-// Base behaviors
-const baseHandlers = {
-  formSubmit(entity, value) {
-    entity.value = value
+const types = {
+  todoList: {
+    toggle(entity, id) {
+      // This runs for EVERY todoList entity, but only acts if it's the right one
+      if (entity.id !== id) return
+      const todo = entity.todos.find((t) => t.id === id)
+      if (todo) todo.completed = !todo.completed
+    },
   },
 }
 
-// Function that adds validation
-const validated = (behavior) => ({
-  formSubmit(entity, value, api) {
-    if (!value.trim()) return // Validate first
-    behavior.formSubmit?.(entity, value, api)
-  },
-})
-
-// Function that adds loading state to async handlers
-const withLoading = (behavior) => ({
-  async fetchData(entity, payload, api) {
-    entity.loading = true
-    try {
-      await behavior.fetchData?.(entity, payload, api)
-    } finally {
-      entity.loading = false
-    }
-  },
-})
-
-// Compose behaviors
-const types = {
-  form: [baseHandlers, validated(baseHandlers), withLoading(baseHandlers)],
-}
+// Broadcast to all todo lists
+store.notify("toggle", "todo1")
+// Each list's toggle handler runs; only the one with todo1 actually updates
 ```
 
-**Why function composition for behaviors:**
-
-- ✅ Add cross-cutting concerns (validation, logging, error handling)
-- ✅ Reuse behavior logic across entities
-- ✅ Create middleware-like wrappers
-- ✅ Cleaner than deep inheritance hierarchies
-- ✅ Works for both apps and games
-
-### Events
-
-Events are broadcast to all relevant handlers in a pub/sub pattern.
+**Multiple types responding to the same event:**
 
 ```javascript
-// Simplest form - just the entity ID
-store.notify("increment", "counter1")
-
-// With additional data
-store.notify("applyDiscount", { id: "item1", percent: 10 })
-
-// Also supports dispatch() for Redux compatibility
-store.dispatch({ type: "increment", payload: "counter1" })
+const types = {
+  todoList: {
+    taskCompleted(entity, taskId) {
+      const task = entity.tasks.find((t) => t.id === taskId)
+      if (task) task.completed = true
+    },
+  },
+  stats: {
+    taskCompleted(entity, taskId) {
+      entity.completedCount++
+    },
+  },
+  notifications: {
+    taskCompleted(entity, taskId) {
+      entity.messages.push("Nice! Task completed.")
+    },
+  },
+}
 
-// Process the queue - this is when handlers actually run
-// (In eager mode, this happens automatically)
-store.update()
+// One notify call, all three entity types respond
+store.notify("taskCompleted", "task123")
 ```
 
-**Key insight:** Events go into a queue and are processed together during `update()`. This enables batching and prevents cascading updates within a single frame.
-
-### Systems (Optional)
+In Redux, you handle this by making multiple reducers listen to the same action—it works by design, but you wire it up manually in each reducer. In RTK, you use `extraReducers` with `builder.addCase()`. In Inglorious Store, it's automatic: if a type has a handler for the event, it receives and processes it.
 
-Systems are global event handlers that can coordinate updates across **multiple entities at once**. Unlike entity handlers (which run once per entity), a system runs **once per event** and has write-access to the entire state.
+### ⚡ Async Operations
 
-**When you need a system:**
+This is where the choice of "where does my logic live?" matters.
 
-- Multiple entities need to update based on relationships between them
-- Updates require looking at all entities together (not individually)
-- Logic that can't be expressed as independent entity handlers
+**Redux/RTK:** Should async logic live in a thunk (where it can access other slices) or in a reducer (where it's pure)? This is a design question you have to answer. Redux thunks are outside the reducer, so they're not deterministic. RTK's `createAsyncThunk` generates pending/fulfilled/rejected actions, spreading your logic across multiple places.
 
-**Example: Inventory Weight Limits**
-
-When adding an item to inventory, you need to check if the **total weight** of all items exceeds the limit. This can't be done in individual item handlers because each item only knows about itself.
+**Inglorious Store:** Your event handlers can be async, and you get deterministic behavior automatically. Inside an async handler, you can access other parts of state (read-only), and you can trigger other events via `api.notify()`. Everything still maintains predictability because of the underlying event queue:
 
 ```javascript
 const types = {
-  item: {
-    addToInventory(item, newItemData) {
-      // Individual items don't know about other items
-      // Can't check total weight here!
+  todoList: {
+    async loadTodos(entity, payload, api) {
+      entity.loading = true
+      try {
+        const todos = await fetch("/api/todos").then((r) => r.json())
+        // Trigger another event—it goes in the queue and runs after this handler
+        api.notify("todosLoaded", todos)
+      } catch (error) {
+        api.notify("loadFailed", error.message)
+      }
     },
-  },
-}
 
-const systems = [
-  {
-    addToInventory(state, newItemData) {
-      // Calculate total weight across ALL items
-      const items = Object.values(state).filter((e) => e.type === "item")
-      const currentWeight = items.reduce((sum, item) => sum + item.weight, 0)
-      const maxWeight = state.player.maxCarryWeight
-
-      // Check if adding this item would exceed the limit
-      if (currentWeight + newItemData.weight > maxWeight) {
-        // Reject the add - drop the heaviest item instead
-        const heaviestItem = items.reduce((max, item) =>
-          item.weight > max.weight ? item : max,
-        )
-        delete state[heaviestItem.id]
-        state.ui.message = `Dropped ${heaviestItem.name} (too heavy!)`
-      }
+    todosLoaded(entity, todos) {
+      entity.todos = todos
+      entity.loading = false
+    },
 
-      // Add the new item
-      const newId = `item${Date.now()}`
-      state[newId] = {
-        id: newId,
-        type: "item",
-        ...newItemData,
-      }
+    loadFailed(entity, error) {
+      entity.error = error
+      entity.loading = false
     },
   },
-]
+}
 ```
 
-**Why this needs a system:**
+Notice: you don't need pending/fulfilled/rejected actions. You control the flow directly. The `api` object passed to handlers provides:
+
+- **`api.getEntities()`** - read entire state
+- **`api.getEntity(id)`** - read one entity
+- **`api.notify(type, payload)`** - trigger other events (queued, not immediate)
+- **`api.getTypes()`** - access type definitions (mainly for middleware/plugins)
+
+All events triggered via `api.notify()` enter the queue and process together, maintaining predictability and testability.
 
-- Requires reading **all items** to calculate total weight
-- Must make a **coordinated decision** (which item to drop)
-- Updates **multiple entities** based on aggregate state (delete one, add another)
-- Can't be split into independent entity handlers
+### 🌍 Systems for Global Logic
 
-**Another example: Multiplayer Turn System**
+When you need to coordinate updates across multiple entities (not just respond to individual events), use systems. A system runs once per event and has write access to the entire state:
 
 ```javascript
 const systems = [
   {
-    endTurn(state, playerId) {
-      // Find current player
-      const players = Object.values(state).filter((e) => e.type === "player")
-      const currentPlayer = players.find((p) => p.id === playerId)
-
-      // Mark current player's turn as ended
-      currentPlayer.isTurn = false
-      currentPlayer.actionsRemaining = 0
-
-      // Find next player
-      const nextPlayerIndex =
-        (players.indexOf(currentPlayer) + 1) % players.length
-      const nextPlayer = players[nextPlayerIndex]
-
-      // Give turn to next player
-      nextPlayer.isTurn = true
-      nextPlayer.actionsRemaining = 3
-
-      // Update round counter if we've cycled through all players
-      if (nextPlayerIndex === 0) {
-        state.gameState.round++
-      }
+    taskCompleted(state, taskId) {
+      // Read from multiple todo lists
+      const allTodos = Object.values(state)
+        .filter((e) => e.type === "todoList")
+        .flatMap((e) => e.todos)
+
+      // Update global stats
+      state.stats.total = allTodos.length
+      state.stats.completed = allTodos.filter((t) => t.completed).length
     },
   },
 ]
-```
-
-**This requires a system because:**
-
-- Must coordinate between multiple player entities
-- Needs to maintain turn order across all players
-- Updates multiple entities in a specific sequence
-- Logic can't be split per-player
-
-**For most apps, you won't need systems.** Use selectors for derived data and entity handlers for individual entity logic.
-
----
-
-## API Reference
-
-### `createStore(options)`
-
-Creates a new store instance.
-
-**Options:**
-
-- `types` (object): Map of type names to behaviors (single object or array)
-- `entities` (object): Initial entities by ID
-- `systems` (array, optional): Global event handlers
-- `middlewares` (array, optional): Middleware functions that enhance store behavior
-- `mode` (`"eager"|"batched"`, optional): Whether `store.update()` is invoked automatically at every `store.notify()` or manually. Defaults to `"eager"`, which makes the store behave like Redux
-
-**Returns:**
-
-- `subscribe(listener)`: Subscribe to state changes
-- `update(dt)`: Process event queue (optional `dt` for time-based logic)
-- `notify(type, payload)`: Queue an event
-- `dispatch(event)`: Redux-compatible event dispatch
-- `getTypes()`: Returns the augmented types configuration
-- `getState()`: Get current immutable state
-- `setState(newState)`: Replace entire state
-- `reset()`: Reset to initial state
-
-### `createApi(store)`
-
-Creates a convenience wrapper with utility methods.
-
-**Returns:**
-
-- `getTypes()`, `getEntities()`, `getEntity(id)`: State accessors
-- `notify(type, payload)`: Dispatch events
-
-### `createSelector(inputSelectors, resultFunc)`
 
-Create memoized, performant selectors.
-
-```javascript
-const selectCompletedTasks = createSelector(
-  [(state) => state.list.tasks],
-  (tasks) => tasks.filter((task) => task.completed),
-)
+const store = createStore({ types, entities, systems })
 ```
 
----
-
-## Use Cases
+Systems receive the entire state and can modify any entity. They're useful for cross-cutting concerns, maintaining derived state, or coordinating complex state updates that can't be expressed as individual entity handlers.
 
-### ✅ Perfect For
+### 🔗 Behavior Composition
 
-- **Apps with async operations** (API calls, data fetching - use batched mode)
-- **Apps that might need collaboration someday** (start simple, scale without refactoring)
-- **Real-time collaboration** (like Figma, Notion, Google Docs)
-- **Chat and messaging apps**
-- **Live dashboards and monitoring**
-- **Interactive data visualizations**
-- **Apps with undo/redo**
-- **Collection-based UIs** (lists, feeds, boards)
-- **...and games!**
+A type can be a single behavior object, or an array of behaviors. A behavior is either an object with event handlers, or a function that takes a behavior and returns an enhanced behavior (decorator pattern):
 
-### 🤔 Maybe Overkill For
-
-- Simple forms with local state only
-- Static marketing pages
-- Apps that will **definitely never** need real-time features
-
-**But here's the thing:** Most successful apps eventually need collaboration, undo/redo, or live updates. With Inglorious Store, you're ready when that happens.
-
----
-
-## Comparison
-
-| Feature                     | Inglorious Store  | Redux            | Redux Toolkit    | Zustand       | Jotai         | Pinia           | MobX            |
-| --------------------------- | ----------------- | ---------------- | ---------------- | ------------- | ------------- | --------------- | --------------- |
-| **Integrated Immutability** | ✅ Mutative       | ❌ Manual        | ✅ Immer         | ❌ Manual     | ✅ Optional   | ✅ Built-in     | ✅ Observables  |
-| **Event Queue/Batching**    | ✅ Built-in       | ❌               | ❌               | ❌            | ❌            | ❌              | ✅ Automatic    |
-| **Dispatch from Handlers**  | ✅ Safe (queued)  | ❌ Not allowed   | ❌ Not allowed   | ✅            | ✅            | ✅              | ✅              |
-| **Redux DevTools**          | ⚠️ Limited        | ✅ Native        | ✅ Native        | ✅ Middleware | ⚠️ Limited    | ✅ Vue DevTools | ⚠️ Limited      |
-| **react-redux Compatible**  | ✅ Yes            | ✅ Yes           | ✅ Yes           | ❌            | ❌            | ❌ Vue only     | ❌              |
-| **Time-Travel Debug**       | ✅ Built-in       | ✅ Via DevTools  | ✅ Via DevTools  | ⚠️ Manual     | ❌            | ⚠️ Limited      | ❌              |
-| **Entity-Based State**      | ✅ First-class    | ⚠️ Manual        | ✅ EntityAdapter | ❌            | ❌            | ❌              | ❌              |
-| **Pub/Sub Events**          | ✅ Core pattern   | ❌               | ❌               | ❌            | ❌            | ❌              | ❌              |
-| **Multiplayer-Ready**       | ✅ Deterministic  | ⚠️ With work     | ⚠️ With work     | ⚠️ With work  | ❌            | ❌              | ❌              |
-| **Testability**             | ✅ Pure functions | ✅ Pure reducers | ✅ Pure reducers | ⚠️ With mocks | ⚠️ With mocks | ⚠️ With mocks   | ❌ Side effects |
-| **Learning Curve**          | Medium            | High             | Medium           | Low           | Medium        | Low             | Medium          |
-| **Bundle Size**             | Small             | Small            | Medium           | Tiny          | Small         | Medium          | Medium          |
-
-### Key Differences
+```javascript
+// Base behavior
+const handlers = {
+  submit(entity, value) {
+    entity.value = ""
+  },
+}
 
-**vs Redux/RTK:**
+// Function that wraps and enhances a behavior
+const validated = (behavior) => ({
+  submit(entity, value, api) {
+    if (!value.trim()) return
+    behavior.submit?.(entity, value, api)
+  },
+})
 
-- Integrated immutability (no manual spreads)
-- Event queue with automatic batching
-- Can dispatch from handlers safely
-- Entity-based architecture built-in
-- Reusable handlers across instances
+// Another wrapper
+const withLoading = (behavior) => ({
+  submit(entity, value, api) {
+    entity.loading = true
+    behavior.submit?.(entity, value, api)
+    entity.loading = false
+  },
+})
 
-**vs Zustand:**
+// Compose them together
+const types = {
+  form: [handlers, validated, withLoading],
+}
+```
 
-- Deterministic event processing (better for multiplayer)
-- Built-in time-travel debugging
-- Entity/type architecture for collections
-- Event queue prevents cascading updates
-- Redux DevTools compatible
+When multiple behaviors define the same event, they all run in order. This allows you to build middleware-like patterns: validation, logging, error handling, loading states, etc.
 
-**vs Jotai:**
+### ⏱️ Batched Mode
 
-- Different paradigm (events vs atoms)
-- Better for entity collections
-- Built-in normalization
-- Explicit event flow
+Process multiple events together before re-rendering:
 
-**vs Pinia:**
+```javascript
+const store = createStore({ types, entities, mode: "batched" })
 
-- React-compatible (Pinia is Vue-only)
-- Event queue system
-- Deterministic updates for multiplayer
+store.notify("playerMoved", { x: 100, y: 50 })
+store.notify("enemyAttacked", { damage: 10 })
+store.notify("particleCreated", { type: "explosion" })
 
-**vs MobX:**
+requestAnimationFrame(() => store.update())
+```
 
-- Explicit events (less magic)
-- Serializable state (easier persistence/sync)
-- Deterministic (better for debugging)
-- Redux DevTools compatible
+Instead of re-rendering after each event, batch them and re-render once. This is what powers high-performance game engines and smooth animations.
 
 ---
 
-**When to choose Inglorious Store:**
-
-- Building real-time/collaborative features
-- Managing collections of similar items
-- Need deterministic state for multiplayer
-- Want built-in time-travel debugging
-- Coming from Redux and want better DX
-
-**When to choose alternatives:**
+## Comparison with Other State Libraries
 
-- **Zustand/Jotai**: Simple apps, prefer minimal API
-- **Redux Toolkit**: Large team, established Redux patterns
-- **Pinia**: Vue ecosystem
-- **MobX**: Prefer reactive/observable patterns
+| Feature                   | Redux        | RTK          | Zustand    | Jotai      | Pinia      | MobX       | Inglorious Store |
+| ------------------------- | ------------ | ------------ | ---------- | ---------- | ---------- | ---------- | ---------------- |
+| **Boilerplate**           | 🔴 High      | 🟡 Medium    | 🟢 Low     | 🟢 Low     | 🟡 Medium  | 🟢 Low     | 🟢 Low           |
+| **Multiple instances**    | 🔴 Manual    | 🔴 Manual    | 🔴 Manual  | 🔴 Manual  | 🟡 Medium  | 🟡 Medium  | 🟢 Built-in      |
+| **Lifecycle events**      | 🔴 No        | 🔴 No        | 🔴 No      | 🔴 No      | 🔴 No      | 🔴 No      | 🟢 Yes           |
+| **Async logic placement** | 🟡 Thunks    | 🟡 Complex   | 🟢 Free    | 🟢 Free    | 🟢 Free    | 🟢 Free    | 🟢 In handlers   |
+| **Redux DevTools**        | 🟢 Yes       | 🟢 Yes       | 🟡 Partial | 🟡 Partial | 🟡 Partial | 🟢 Yes     | 🟢 Yes           |
+| **Time-travel debugging** | 🟢 Yes       | 🟢 Yes       | 🔴 No      | 🔴 No      | 🔴 No      | 🟡 Limited | 🟢 Yes           |
+| **Testability**           | 🟢 Excellent | 🟢 Excellent | 🟡 Good    | 🟡 Good    | 🟡 Good    | 🟡 Medium  | 🟢 Excellent     |
+| **Immutability**          | 🔴 Manual    | 🟢 Immer     | 🔴 Manual  | 🔴 Manual  | 🔴 Manual  | 🔴 Manual  | 🟢 Mutative      |
 
 ---
 
-## Advanced: Real-Time Sync
-
-Adding multiplayer to an existing app is usually a massive refactor. With Inglorious Store, it's an afternoon project.
-
-### Step 1: Your app already works locally
-
-```javascript
-store.notify("movePlayer", { x: 10, y: 20 })
-store.update()
-```
+## API Reference
 
-### Step 2: Add WebSocket (literally ~10 lines)
+### `createStore(options)`
 
 ```javascript
-// Receive events from other clients
-socket.on("remote-event", (event) => {
-  store.notify(event.type, event.payload)
-})
-
-// Send your events to other clients
-const processedEvents = store.update()
-processedEvents.forEach((event) => {
-  socket.emit("event", event)
+const store = createStore({
+  types, // Object: entity type definitions
+  entities, // Object: initial entities
+  systems, // Array (optional): global state handlers
+  mode, // String (optional): 'eager' (default) or 'batched'
 })
 ```
 
-**That's it.** Because your event handlers are pure functions and the state is deterministic, all clients stay perfectly in sync.
-
-### Why This Works
-
-1. **Deterministic:** Same events + same state = same result (always)
-2. **Serializable:** Events are plain objects (easy to send over network)
-3. **Ordered:** Event queue ensures predictable processing
-4. **Conflict-free:** Last write wins, or implement custom merge logic
-
-### Example: Collaborative Todo List
-
-```javascript
-// Client A adds a todo
-store.notify("addTodo", { id: "todo1", text: "Buy milk" })
-
-// Event gets broadcast to all clients
-// All clients process the same event
-// All clients end up with identical state
-
-// Even works offline! Events queue up, sync when reconnected
-```
-
-This is exactly how multiplayer games work. Now your app can too.
-
----
-
-## Advanced: Time-Based Updates
+**Returns:** Redux-compatible store
 
-For animations, games, or any time-dependent logic, you can run a continuous update loop:
+### Types Definition
 
 ```javascript
 const types = {
-  particle: [
+  entityType: [
+    // Behavior objects
     {
-      update(particle, dt) {
-        // dt = delta time in milliseconds
-        particle.x += particle.velocityX * dt
-        particle.y += particle.velocityY * dt
-        particle.life -= dt
+      eventName(entity, payload, api) {
+        entity.value = payload
+        api.notify("otherEvent", data)
       },
     },
+    // Behavior functions (decorators)
+    (behavior) => ({
+      eventName(entity, payload, api) {
+        // Wrap the behavior
+        behavior.eventName?.(entity, payload, api)
+      },
+    }),
   ],
 }
-
-// Run at 30 FPS (good for most UIs)
-setInterval(() => store.update(), 1000 / 30)
-
-// Or 60 FPS (for smooth animations/games)
-function loop() {
-  store.update()
-  requestAnimationFrame(loop)
-}
-loop()
 ```
 
-**For typical apps (todos, forms, dashboards):** Use eager mode (default). No loop needed.
+### Event Handler API
 
-**For real-time apps (games, animations, live data):** Use batched mode with a loop for smooth, consistent updates.
+Each handler receives three arguments:
 
----
+- **`entity`** - the entity instance (mutate freely, immutability guaranteed)
+- **`payload`** - data passed with the event
+- **`api`** - access to store methods:
+  - `getEntities()` - entire state (read-only)
+  - `getEntity(id)` - single entity (read-only)
+  - `notify(type, payload)` - trigger other events (queued)
+  - `getTypes()` - type definitions (for middleware)
 
-## The Path from Solo to Multiplayer
+### Built-in Lifecycle Events
 
-### Week 1: Build a simple todo app
+- **`create(entity, id)`** - triggered when entity added via `add` event
+- **`destroy(entity, id)`** - triggered when entity removed via `remove` event
+- **`morph(entity, newType)`** - triggered when entity type changes
 
-```javascript
-store.notify("addTodo", { text: "Buy milk" })
-```
+### Notify vs Dispatch
 
-_Works great. Clean architecture. Nothing fancy._
-
-### Month 6: Users love it, ask for undo/redo
+Both work (dispatch for Redux compatibility), but `notify` is cleaner:
 
 ```javascript
-const snapshot = store.getState()
-// ... user makes changes ...
-store.setState(snapshot) // Undo!
+store.notify("eventName", payload)
+store.dispatch({ type: "eventName", payload }) // Redux-compatible alternative
 ```
 
-_Already built-in. No refactoring needed._
-
-### Year 1: Competitor launches with real-time collaboration
+---
 
-```javascript
-socket.on("remote-event", (e) => store.notify(e.type, e.payload))
-```
+## Use Cases
 
-_Add multiplayer in an afternoon. You win._
+### Perfect For
 
----
+- 🎮 Apps with multiple instances of the same entity type
+- 🎯 Real-time collaborative features
+- ⚡ Complex state coordination and async operations
+- 📊 High-frequency updates (animations, games)
+- 🔄 Undo/redo, time-travel debugging
 
-## Part of the Inglorious Engine
+### Still Great For
 
-This store powers the [Inglorious Engine](https://github.com/IngloriousCoderz/inglorious-engine), a functional game engine. But you don't need to build games to benefit from game development patterns!
+- Any Redux use case (true drop-in replacement)
+- Migration path from Redux (keep using react-redux)
 
 ---
 
-## What's Next?
+## Part of the Inglorious Engine
 
-- 📖 **[@inglorious/react-store](https://github.com/IngloriousCoderz/inglorious-engine/tree/main/packages/react-store)** - React integration with hooks
-- 🎮 **[@inglorious/engine](https://github.com/IngloriousCoderz/inglorious-engine)** - Full game engine built on this store
-- 🌐 **[@inglorious/server](https://github.com/IngloriousCoderz/inglorious-engine/tree/main/packages/server)** - Server-side multiplayer support
-- 💬 **[GitHub Discussions](https://github.com/IngloriousCoderz/inglorious-engine/discussions)** - Get help and share what you're building
+This store powers the [Inglorious Engine](https://github.com/IngloriousCoderz/inglorious-engine), a functional game engine. The same patterns that power games power your web apps.
 
 ---
 
 ## License
 
-**MIT License - Free and open source**
-
-Created by [Matteo Antony Mistretta](https://github.com/IngloriousCoderz)
+MIT © [Matteo Antony Mistretta](https://github.com/IngloriousCoderz)
 
-You're free to use, modify, and distribute this software. See [LICENSE](../../LICENSE) for details.
+Free to use, modify, and distribute.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "5.5.0",
+  "version": "6.0.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/api.js

@@ -1,14 +1,8 @@
 export function createApi(store, extras) {
-  const getTypes = () => store.getTypes()
-
-  const getEntities = () => store.getState()
-
-  const getEntity = (id) => getEntities()[id]
-
   return {
-    getTypes,
-    getEntities,
-    getEntity,
+    getTypes: store.getTypes,
+    getEntities: store.getState,
+    getEntity: (id) => store.getState()[id],
     dispatch: store.dispatch,
     notify: store.notify,
     ...extras,

package/src/client/dev-tools.js

@@ -16,6 +16,16 @@ export function connectDevTools(store, config = {}) {
   const name = config.name ?? document.title
   const skippedEvents = config.skippedEvents ?? []
 
+  if (config.mode !== "batched") {
+    const baseDispatch = store.dispatch
+    store.dispatch = (action) => {
+      baseDispatch(action)
+      if (!skippedEvents.includes(action.type)) {
+        sendAction(action, store.getState())
+      }
+    }
+  }
+
   devToolsInstance = window.__REDUX_DEVTOOLS_EXTENSION__.connect({
     name,
     predicate: (state, action) => !skippedEvents.includes(action.type),

package/src/store.js

@@ -45,6 +45,7 @@ export function createStore({
     ? applyMiddlewares(...middlewares)(baseStore)
     : baseStore
   const api = createApi(store, store.extras)
+  store._api = api
   return store
 
   /**
@@ -135,7 +136,8 @@ export function createStore({
    * @param {any} payload - The event object payload to notify.
    */
   function notify(type, payload) {
-    dispatch({ type, payload })
+    // NOTE: it's important to invoke store.dispatch instead of dispatch, otherwise we cannot override it
+    store.dispatch({ type, payload })
   }
 
   /**