@inglorious/store 9.1.0 → 9.2.0

package/README.md

@@ -794,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "9.1.0",
+  "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/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/store.d.ts

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