@inglorious/store 9.1.0 → 9.3.0

package/README.md

@@ -433,6 +433,26 @@ store.notify("toggle", "todo1")
 // Each list's toggle handler runs; only the one with todo1 actually updates
 ```
 
+Alternatively, you can use the **targeted notification syntax** to filter events at the dispatch level:
+
+- `notify("type:event")`: notifies only entities of a specific type.
+- `notify("#id:event")`: notifies only a specific entity by ID.
+- `notify("type#id:event")`: notifies a specific entity of a specific type.
+
+```javascript
+const types = {
+  todoList: {
+    toggle(entity) {
+      const todo = entity.todos.find((t) => t.id === entity.id)
+      if (todo) todo.completed = !todo.completed
+    },
+  },
+}
+
+// Notify only the entity with ID 'work'
+store.notify("#todo1:toggle")
+```
+
 ### ⚡ Async Operations
 
 In **Redux/RTK**, logic should be written inside pure functions as much as possible — specifically in reducers, not action creators. But what if I need to access some other part of the state that is not visible to the reducer? What if I need to combine async behavior with sync behavior? This is where the choice of "where does my logic live?" matters.
@@ -478,6 +498,192 @@ Notice: you don't need pending/fulfilled/rejected actions. You stay in control o
 
 All events triggered via `api.notify()` enter the queue and process together, maintaining predictability and testability.
 
+### `handleAsync`
+
+The `handleAsync` helper generates a set of event handlers representing the lifecycle of an async operation.
+
+```ts
+handleAsync(type, handlers, options?)
+```
+
+Example:
+
+```ts
+handleAsync("fetchTodos", {
+  async run(payload) {
+    const res = await fetch("/api/todos")
+    return res.json()
+  },
+
+  success(entity, todos) {
+    entity.todos = todos
+  },
+
+  error(entity, error) {
+    entity.error = error.message
+  },
+
+  finally(entity) {
+    entity.loading = false
+  },
+})
+```
+
+---
+
+### Lifecycle events
+
+Triggering `fetchTodos` emits the following events:
+
+```
+fetchTodos
+fetchTodosRun
+fetchTodosSuccess | fetchTodosError
+fetchTodosFinally
+```
+
+Each step is an **event handler**, not an implicit callback.
+
+---
+
+### Optional `start` handler
+
+Use `start` for synchronous setup (loading flags, resets, optimistic state):
+
+```ts
+handleAsync("save", {
+  start(entity) {
+    entity.loading = true
+  },
+  async run(payload) {
+    return api.save(payload)
+  },
+})
+```
+
+If omitted, no `Start` event is generated.
+
+---
+
+### Event scoping
+
+By default, lifecycle events are **scoped to the triggering entity**:
+
+```
+#entityId:fetchTodosSuccess
+```
+
+You can override this behavior:
+
+```ts
+handleAsync("bootstrap", handlers, { scope: "global" })
+```
+
+Available scopes:
+
+- `"entity"` (default)
+- `"type"`
+- `"global"`
+
+---
+
+> **Key rule:** Async code must not access entities after `await`. All updates happen in event handlers.
+
+---
+
+## 🧩 Migrating from Redux Toolkit (RTK)
+
+Inglorious Store now provides utilities to **gradually migrate from RTK slices and thunks**, leveraging `handleAsync` to simplify async logic.
+
+### Converting Async Thunks
+
+```javascript
+import { convertAsyncThunk } from "@inglorious/store/rtk"
+
+const fetchTodos = async (userId) => {
+  const res = await fetch(`/api/users/${userId}/todos`)
+  return res.json()
+}
+
+const todoHandlers = convertAsyncThunk("fetchTodos", fetchTodos, {
+  onPending: (entity) => {
+    entity.status = "loading"
+  },
+  onFulfilled: (entity, todos) => {
+    entity.status = "success"
+    entity.todos = todos
+  },
+  onRejected: (entity, error) => {
+    entity.status = "error"
+    entity.error = error.message
+  },
+})
+```
+
+```javascript
+const todoList = {
+  init(entity) {
+    entity.todos = []
+    entity.status = "idle"
+  },
+  ...todoHandlers,
+}
+```
+
+### Converting Slices
+
+```javascript
+import { convertSlice } from "@inglorious/store/rtk"
+
+const todoListType = convertSlice(todosSlice, {
+  asyncThunks: {
+    fetchTodos: {
+      onPending: (entity) => {
+        entity.status = "loading"
+      },
+      onFulfilled: (entity, todos) => {
+        entity.items = todos
+      },
+      onRejected: (entity, error) => {
+        entity.error = error.message
+      },
+    },
+  },
+})
+```
+
+- Reducers become event handlers automatically.
+- Async thunks become `handleAsync` events.
+- Initial state is applied via an `init` handler.
+- Extra handlers can be added if needed.
+
+---
+
+### RTK-Style Dispatch Compatibility
+
+```javascript
+const dispatch = createRTKCompatDispatch(api, "todos")
+dispatch({ type: "todos/addTodo", payload: "Buy milk" })
+// becomes: api.notify('#todos:addTodo', 'Buy milk')
+```
+
+> Thunks are **not supported** in compat mode; convert them using `convertAsyncThunk`.
+
+---
+
+### Migration Guide
+
+```javascript
+import { createMigrationGuide } from "@inglorious/store/rtk"
+
+const guide = createMigrationGuide(todosSlice)
+console.log(guide)
+```
+
+Outputs a readable guide mapping RTK calls to Inglorious events.
+
+---
+
 ### 🧪 Testing
 
 Event handlers are pure functions (or can be treated as such), making them easy to test in isolation, much like Redux reducers. The `@inglorious/store/test` module provides utility functions to make this even simpler.
@@ -794,12 +1000,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.3.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",
@@ -36,6 +36,10 @@
       "types": "./types/client/devtools.d.ts",
       "import": "./src/client/devtools.js"
     },
+    "./migration/rtk": {
+      "types": "./types/migration/rtk.d.ts",
+      "import": "./src/migration/rtk.js"
+    },
     "./*": {
       "types": "./types/*.d.ts",
       "import": "./src/*"

package/src/async.js

@@ -0,0 +1,187 @@
+/**
+ * Creates a set of event handlers for managing an asynchronous operation lifecycle.
+ *
+ * This helper generates handlers for all stages of an async operation: start, run,
+ * success, error, and finally. The lifecycle events are automatically scoped based
+ * on the provided options.
+ *
+ * @template {import('./store').BaseEntity} TEntity - The entity type
+ * @template TPayload - The payload type passed to the operation
+ * @template TResult - The result type returned by the async operation
+ *
+ * @param {string} type - The base event name (e.g., 'fetchTodos').
+ *   Generated handlers will be named: `type`, `typeStart`, `typeRun`, `typeSuccess`, `typeError`, `typeFinally`
+ *
+ * @param {Object} handlers - The handler functions for each lifecycle stage.
+ * @param {(entity: TEntity, payload: TPayload, api: import('./store').Api) => void} [handlers.start]
+ *   Called synchronously before the async operation starts.
+ *   Use for setting loading states. Receives: (entity, payload, api)
+ * @param {(payload: TPayload, api: import('./store').Api) => Promise<TResult> | TResult} handlers.run
+ *   The async operation to perform. Must return a Promise or value.
+ *   **Note:** Receives (payload, api) - NOT entity. Entity state should be modified in other handlers.
+ * @param {(entity: TEntity, result: TResult, api: import('./store').Api) => void} [handlers.success]
+ *   Called when the operation succeeds.
+ *   Receives: (entity, result, api) where result is the resolved value from run()
+ * @param {(entity: TEntity, error: any, api: import('./store').Api) => void} [handlers.error]
+ *   Called when the operation fails.
+ *   Receives: (entity, error, api) where error is the caught exception
+ * @param {(entity: TEntity, api: import('./store').Api) => void} [handlers.finally]
+ *   Called after the operation completes (success or failure).
+ *   Use for cleanup, resetting loading states. Receives: (entity, api)
+ *
+ * @param {Object} [options] - Configuration options.
+ * @param {"entity" | "type" | "global"} [options.scope="entity"]
+ *   Controls how lifecycle events are routed:
+ *   - "entity": notify `#entityId:event` (default, safest - events only affect the triggering entity)
+ *   - "type": notify `typeName:event` (broadcasts to all entities of this type)
+ *   - "global": notify `event` (global broadcast to any listener)
+ *
+ * @returns {Object} An object containing the generated event handlers that can be spread into a type:
+ *   - `[type]`: Main trigger - dispatches Start (if defined) and Run events
+ *   - `[typeStart]`: (if start handler provided) Executes the start handler
+ *   - `[typeRun]`: Executes the async operation, then dispatches Success or Error, then Finally
+ *   - `[typeSuccess]`: Executes the success handler
+ *   - `[typeError]`: Executes the error handler
+ *   - `[typeFinally]`: Executes the finally handler
+ *
+ * @example
+ * // Basic usage - fetch todos with loading state
+ * const todoList = {
+ *   init(entity) {
+ *     entity.todos = []
+ *     entity.status = 'idle'
+ *   },
+ *
+ *   ...handleAsync('fetchTodos', {
+ *     start(entity) {
+ *       entity.status = 'loading'
+ *     },
+ *     async run(payload, api) {
+ *       const response = await fetch('/api/todos')
+ *       return response.json()
+ *     },
+ *     success(entity, todos) {
+ *       entity.status = 'success'
+ *       entity.todos = todos
+ *     },
+ *     error(entity, error) {
+ *       entity.status = 'error'
+ *       entity.error = error.message
+ *     },
+ *     finally(entity) {
+ *       entity.lastFetched = Date.now()
+ *     }
+ *   })
+ * }
+ *
+ * // Trigger from UI
+ * api.notify('#todoList:fetchTodos')
+ *
+ * @example
+ * // With type scope - affects all entities of this type
+ * const counter = {
+ *   ...handleAsync('sync', {
+ *     async run(payload, api) {
+ *       const response = await fetch('/api/sync')
+ *       return response.json()
+ *     },
+ *     success(entity, result) {
+ *       entity.synced = true
+ *       entity.lastSync = result.timestamp
+ *     }
+ *   }, { scope: 'type' })
+ * }
+ *
+ * // Triggers sync for ALL counter entities
+ * api.notify('counter:sync')
+ *
+ * @example
+ * // Minimal - just run and success
+ * const user = {
+ *   ...handleAsync('login', {
+ *     async run({ username, password }, api) {
+ *       const response = await fetch('/api/login', {
+ *         method: 'POST',
+ *         body: JSON.stringify({ username, password })
+ *       })
+ *       return response.json()
+ *     },
+ *     success(entity, user) {
+ *       entity.currentUser = user
+ *       entity.isAuthenticated = true
+ *     }
+ *   })
+ * }
+ *
+ * @example
+ * // Without start handler
+ * const data = {
+ *   ...handleAsync('fetch', {
+ *     async run(payload, api) {
+ *       return fetch(`/api/data/${payload.id}`).then(r => r.json())
+ *     },
+ *     success(entity, result) {
+ *       entity.data = result
+ *     },
+ *     error(entity, error) {
+ *       console.error('Fetch failed:', error)
+ *     }
+ *   })
+ * }
+ */
+export function handleAsync(type, handlers, options = {}) {
+  const { scope = "entity" } = options
+
+  function notify(api, entity, event, payload) {
+    switch (scope) {
+      case "entity":
+        api.notify(`#${entity.id}:${event}`, payload)
+        break
+      case "type":
+        api.notify(`${entity.type}:${event}`, payload)
+        break
+      case "global":
+        api.notify(event, payload)
+        break
+    }
+  }
+
+  return {
+    [type](entity, payload, api) {
+      if (handlers.start) {
+        notify(api, entity, `${type}Start`, payload)
+      }
+
+      notify(api, entity, `${type}Run`, payload)
+    },
+
+    ...(handlers.start && {
+      [`${type}Start`](entity, payload, api) {
+        handlers.start(entity, payload, api)
+      },
+    }),
+
+    async [`${type}Run`](entity, payload, api) {
+      try {
+        const result = await handlers.run(payload, api)
+        notify(api, entity, `${type}Success`, result)
+      } catch (error) {
+        notify(api, entity, `${type}Error`, error)
+      } finally {
+        notify(api, entity, `${type}Finally`)
+      }
+    },
+
+    [`${type}Success`](entity, result, api) {
+      handlers.success?.(entity, result, api)
+    },
+
+    [`${type}Error`](entity, error, api) {
+      handlers.error?.(entity, error, api)
+    },
+
+    [`${type}Finally`](entity, _, api) {
+      handlers.finally?.(entity, api)
+    },
+  }
+}