@inglorious/store 9.2.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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "9.2.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)
+    },
+  }
+}

package/src/migration/rtk.js

@@ -0,0 +1,326 @@
+/**
+ * @fileoverview Adapter for migrating Redux Toolkit code to Inglorious Store
+ *
+ * This module provides utilities to convert RTK slices and async thunks into
+ * Inglorious types, enabling gradual migration from RTK to Inglorious Store.
+ */
+
+import { handleAsync } from "../async"
+
+const SEP_LENGTH = 50
+const INDENT_SPACES = 2
+const SLICE_PLUS_ACTION = 2
+
+/**
+ * Converts an RTK createAsyncThunk to Inglorious handleAsync handlers
+ *
+ * @param {string} name - The thunk name (e.g., 'fetchTodos')
+ * @param {Function} payloadCreator - The async function that performs the operation
+ * @param {Object} [options] - Options for the conversion
+ * @param {Function} [options.onPending] - Handler for pending state (maps to start)
+ * @param {Function} [options.onFulfilled] - Handler for fulfilled state (maps to success)
+ * @param {Function} [options.onRejected] - Handler for rejected state (maps to error)
+ * @param {Function} [options.onSettled] - Handler called after completion (maps to finally)
+ * @param {"entity"|"type"|"global"} [options.scope] - Event scope
+ *
+ * @returns {Object} Inglorious handleAsync handlers
+ *
+ * @example
+ * // RTK async thunk
+ * const fetchTodos = createAsyncThunk(
+ *   'todos/fetch',
+ *   async (userId) => {
+ *     const response = await fetch(`/api/users/${userId}/todos`)
+ *     return response.json()
+ *   }
+ * )
+ *
+ * // Convert to Inglorious
+ * const todoHandlers = convertAsyncThunk('fetchTodos', fetchTodos.payloadCreator, {
+ *   onPending: (entity) => { entity.status = 'loading' },
+ *   onFulfilled: (entity, todos) => {
+ *     entity.status = 'success'
+ *     entity.todos = todos
+ *   },
+ *   onRejected: (entity, error) => {
+ *     entity.status = 'error'
+ *     entity.error = error.message
+ *   }
+ * })
+ *
+ * // Use in type
+ * const todoList = {
+ *   init(entity) { entity.todos = []; entity.status = 'idle' },
+ *   ...todoHandlers
+ * }
+ */
+export function convertAsyncThunk(name, payloadCreator, options = {}) {
+  const {
+    onPending,
+    onFulfilled,
+    onRejected,
+    onSettled,
+    scope = "entity",
+  } = options
+
+  return handleAsync(
+    name,
+    {
+      start: onPending
+        ? (entity, payload, api) => {
+            onPending(entity, payload, api)
+          }
+        : undefined,
+
+      run: async (payload, api) => {
+        // RTK payloadCreator signature: (arg, thunkAPI)
+        // We need to adapt it to our simpler signature
+        return await payloadCreator(payload, { dispatch: api.notify })
+      },
+
+      success: onFulfilled
+        ? (entity, result, api) => {
+            onFulfilled(entity, result, api)
+          }
+        : undefined,
+
+      error: onRejected
+        ? (entity, error, api) => {
+            onRejected(entity, error, api)
+          }
+        : undefined,
+
+      finally: onSettled
+        ? (entity, api) => {
+            onSettled(entity, api)
+          }
+        : undefined,
+    },
+    { scope },
+  )
+}
+
+/**
+ * Converts an RTK slice to an Inglorious type
+ *
+ * This is a helper for gradual migration. It converts RTK reducers to Inglorious
+ * event handlers while preserving the same mutation-based syntax (both use Immer/Mutative).
+ *
+ * @param {Object} slice - RTK slice created with createSlice
+ * @param {Object} [options] - Conversion options
+ * @param {Object} [options.asyncThunks] - Map of async thunk handlers
+ *   Keys are thunk names, values are objects with onPending/onFulfilled/onRejected
+ * @param {Object} [options.extraHandlers] - Additional event handlers not from the slice
+ *
+ * @returns {Object} Inglorious type definition
+ *
+ * @example
+ * // RTK slice
+ * const todosSlice = createSlice({
+ *   name: 'todos',
+ *   initialState: { items: [], filter: 'all' },
+ *   reducers: {
+ *     addTodo: (state, action) => {
+ *       state.items.push({ id: Date.now(), text: action.payload })
+ *     },
+ *     toggleTodo: (state, action) => {
+ *       const todo = state.items.find(t => t.id === action.payload)
+ *       if (todo) todo.completed = !todo.completed
+ *     },
+ *     setFilter: (state, action) => {
+ *       state.filter = action.payload
+ *     }
+ *   }
+ * })
+ *
+ * const fetchTodos = createAsyncThunk('todos/fetch', async () => {
+ *   const response = await fetch('/api/todos')
+ *   return response.json()
+ * })
+ *
+ * // Convert to Inglorious
+ * const todoList = convertSlice(todosSlice, {
+ *   asyncThunks: {
+ *     fetchTodos: {
+ *       onPending: (entity) => { entity.status = 'loading' },
+ *       onFulfilled: (entity, todos) => { entity.items = todos },
+ *       onRejected: (entity, error) => { entity.error = error.message }
+ *     }
+ *   }
+ * })
+ *
+ * // Use in store
+ * const store = createStore({
+ *   types: { todoList },
+ *   entities: { todos: { type: 'todoList', id: 'todos' } }
+ * })
+ */
+export function convertSlice(slice, options = {}) {
+  const { asyncThunks = {}, extraHandlers = {} } = options
+
+  const type = {
+    // Convert initialState to init handler
+    init(entity) {
+      const initialState = slice.getInitialState()
+      Object.assign(entity, initialState)
+    },
+  }
+
+  // Convert each reducer to an event handler
+  for (const [actionName, reducer] of Object.entries(slice.caseReducers)) {
+    type[actionName] = (entity, payload) => {
+      // Create a mock action object for the RTK reducer
+      const action = { type: `${slice.name}/${actionName}`, payload }
+
+      // RTK reducers expect to mutate state directly (via Immer)
+      // Inglorious handlers do the same (via Mutative)
+      // So we can call the reducer directly on the entity
+      reducer(entity, action)
+    }
+  }
+
+  // Convert async thunks
+  for (const [thunkName, thunkHandlers] of Object.entries(asyncThunks)) {
+    const asyncHandlers = convertAsyncThunk(
+      thunkName,
+      thunkHandlers.payloadCreator || (async () => {}),
+      {
+        onPending: thunkHandlers.onPending,
+        onFulfilled: thunkHandlers.onFulfilled,
+        onRejected: thunkHandlers.onRejected,
+        onSettled: thunkHandlers.onSettled,
+        scope: thunkHandlers.scope,
+      },
+    )
+
+    Object.assign(type, asyncHandlers)
+  }
+
+  // Add any extra handlers
+  Object.assign(type, extraHandlers)
+
+  return type
+}
+
+/**
+ * Creates a migration guide for a slice
+ *
+ * Analyzes an RTK slice and generates a readable migration guide showing
+ * the equivalent Inglorious code.
+ *
+ * @param {Object} slice - RTK slice
+ * @returns {string} Migration guide text
+ *
+ * @example
+ * const guide = createMigrationGuide(todosSlice)
+ * console.log(guide)
+ * // Outputs:
+ * // Migration Guide for 'todos' slice
+ * //
+ * // RTK:
+ * //   dispatch(addTodo('Buy milk'))
+ * //
+ * // Inglorious:
+ * //   api.notify('#todos:addTodo', 'Buy milk')
+ */
+export function createMigrationGuide(slice) {
+  const lines = []
+
+  lines.push(`Migration Guide for '${slice.name}' slice`)
+  lines.push("")
+  lines.push("=".repeat(SEP_LENGTH))
+  lines.push("")
+
+  // Show state structure
+  lines.push("STATE STRUCTURE:")
+  lines.push("RTK:")
+  lines.push(
+    `  state.${slice.name} = ${JSON.stringify(slice.getInitialState(), null, INDENT_SPACES)}`,
+  )
+  lines.push("")
+  lines.push("Inglorious:")
+  lines.push(`  entities.${slice.name} = {`)
+  lines.push(`    type: '${slice.name}',`)
+  lines.push(`    id: '${slice.name}',`)
+  const initialState = slice.getInitialState()
+  for (const [key, value] of Object.entries(initialState)) {
+    lines.push(`    ${key}: ${JSON.stringify(value)},`)
+  }
+  lines.push("  }")
+  lines.push("")
+  lines.push("=".repeat(SEP_LENGTH))
+  lines.push("")
+
+  // Show each reducer conversion
+  lines.push("ACTIONS / EVENTS:")
+  for (const actionName of Object.keys(slice.caseReducers)) {
+    lines.push("")
+    lines.push(`${actionName}:`)
+    lines.push("  RTK:")
+    lines.push(`    dispatch(${actionName}(payload))`)
+    lines.push("  Inglorious:")
+    lines.push(`    api.notify('#${slice.name}:${actionName}', payload)`)
+  }
+
+  lines.push("")
+  lines.push("=".repeat(SEP_LENGTH))
+  lines.push("")
+
+  // Show selector conversion
+  lines.push("SELECTORS:")
+  lines.push("RTK:")
+  lines.push(
+    `  const data = useSelector(state => state.${slice.name}.someField)`,
+  )
+  lines.push("Inglorious:")
+  lines.push(`  const { someField } = api.getEntity('${slice.name}')`)
+  lines.push("  // or")
+  lines.push(
+    `  const data = useSelector(state => state.entities.${slice.name}.someField)`,
+  )
+
+  return lines.join("\n")
+}
+
+/**
+ * Helper to create a compatibility layer for existing RTK code
+ *
+ * This allows RTK-style dispatch calls to work with Inglorious Store
+ * during the migration period.
+ *
+ * @param {Object} api - Inglorious API
+ * @param {string} entityId - The entity ID to target
+ * @returns {Function} A dispatch function compatible with RTK actions
+ *
+ * @example
+ * const dispatch = createRTKCompatDispatch(api, 'todos')
+ *
+ * // RTK-style action
+ * dispatch({ type: 'todos/addTodo', payload: 'Buy milk' })
+ *
+ * // Translates to:
+ * // api.notify('#todos:addTodo', 'Buy milk')
+ */
+export function createRTKCompatDispatch(api, entityId) {
+  return (action) => {
+    if (typeof action === "function") {
+      // Thunk - not supported in compat mode
+      console.warn("Thunks are not supported in RTK compat mode")
+      return
+    }
+
+    // Extract action type and payload
+    const { type, payload } = action
+
+    // Convert RTK action type to Inglorious event
+    // RTK: 'todos/addTodo' -> Inglorious: '#todos:addTodo'
+    const parts = type.split("/")
+    if (parts.length === SLICE_PLUS_ACTION) {
+      const [, actionName] = parts
+      api.notify(`#${entityId}:${actionName}`, payload)
+    } else {
+      // Fallback for non-standard action types
+      api.notify(`#${entityId}:${type}`, payload)
+    }
+  }
+}

package/types/async.d.ts

@@ -0,0 +1,146 @@
+import { Api, BaseEntity } from "./store"
+
+/**
+ * Scope option for async handler events
+ * - "entity": Events scoped to specific entity (#entityId:event)
+ * - "type": Events scoped to entity type (typeName:event)
+ * - "global": Global events (event)
+ */
+export type AsyncScope = "entity" | "type" | "global"
+
+/**
+ * Configuration options for async handlers
+ */
+export interface AsyncOptions {
+  /**
+   * Controls how lifecycle events are routed
+   * @default "entity"
+   */
+  scope?: AsyncScope
+}
+
+/**
+ * Handler functions for async operation lifecycle
+ */
+export interface AsyncHandlers<
+  TEntity extends BaseEntity = BaseEntity,
+  TPayload = any,
+  TResult = any,
+> {
+  /**
+   * Called synchronously before the async operation starts
+   * Use for setting loading states
+   */
+  start?: (entity: TEntity, payload: TPayload, api: Api) => void
+
+  /**
+   * The async operation to perform
+   * Receives payload and api (NOT entity - entity state should be modified in other handlers)
+   * @returns Promise or synchronous result
+   */
+  run: (payload: TPayload, api: Api) => Promise<TResult> | TResult
+
+  /**
+   * Called when the operation succeeds
+   * Receives the entity, the result from run(), and api
+   */
+  success?: (entity: TEntity, result: TResult, api: Api) => void
+
+  /**
+   * Called when the operation fails
+   * Receives the entity, the error, and api
+   */
+  error?: (entity: TEntity, error: any, api: Api) => void
+
+  /**
+   * Called after the operation completes (success or failure)
+   * Use for cleanup, resetting loading states, etc.
+   */
+  finally?: (entity: TEntity, api: Api) => void
+}
+
+/**
+ * Generated event handlers returned by handleAsync
+ * Contains handlers for all lifecycle stages
+ */
+export interface AsyncEventHandlers<
+  TEntity extends BaseEntity = BaseEntity,
+  TPayload = any,
+  TResult = any,
+> {
+  /**
+   * Main trigger handler
+   * Dispatches start (if defined) and run events
+   */
+  [key: string]: (
+    entity: TEntity,
+    payload: TPayload,
+    api: Api,
+  ) => void | Promise<void>
+}
+
+/**
+ * Creates a set of event handlers for managing an asynchronous operation lifecycle.
+ *
+ * Generates handlers for: trigger, start, run, success, error, finally
+ * These can be spread into an entity type definition.
+ *
+ * @template TEntity - The entity type (must extend BaseEntity)
+ * @template TPayload - The payload type passed to the operation
+ * @template TResult - The result type returned by the async operation
+ *
+ * @param type - The base event name (e.g., 'fetchTodos')
+ * @param handlers - Handler functions for each lifecycle stage
+ * @param options - Configuration options
+ * @returns Object containing all generated event handlers
+ *
+ * @example
+ * ```typescript
+ * interface Todo {
+ *   id: number
+ *   text: string
+ *   completed: boolean
+ * }
+ *
+ * interface TodoListEntity extends BaseEntity {
+ *   type: 'todoList'
+ *   todos: Todo[]
+ *   status: 'idle' | 'loading' | 'success' | 'error'
+ *   error?: string
+ * }
+ *
+ * const todoList = {
+ *   init(entity: TodoListEntity) {
+ *     entity.todos = []
+ *     entity.status = 'idle'
+ *   },
+ *
+ *   ...handleAsync<TodoListEntity, void, Todo[]>('fetchTodos', {
+ *     start(entity) {
+ *       entity.status = 'loading'
+ *     },
+ *     async run(_, 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
+ *     }
+ *   })
+ * }
+ * ```
+ */
+export function handleAsync<
+  TEntity extends BaseEntity = BaseEntity,
+  TPayload = any,
+  TResult = any,
+>(
+  type: string,
+  handlers: AsyncHandlers<TEntity, TPayload, TResult>,
+  options?: AsyncOptions,
+): AsyncEventHandlers<TEntity, TPayload, TResult>

package/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./async"
 export * from "./select"
 export * from "./store"
 export * from "./test"

package/types/migration/rtk.d.ts

@@ -0,0 +1,402 @@
+import { Api, BaseEntity } from "../store"
+
+/**
+ * RTK-compatible thunk API
+ * Minimal subset needed for payload creators
+ */
+export interface ThunkAPI {
+  dispatch: Api["notify"]
+  // Add other thunk API properties as needed
+  // getState, extra, requestId, signal, rejectWithValue, fulfillWithValue
+}
+
+/**
+ * RTK async thunk payload creator function
+ */
+export type PayloadCreator<TPayload = any, TResult = any> = (
+  arg: TPayload,
+  thunkAPI: ThunkAPI,
+) => Promise<TResult> | TResult
+
+/**
+ * Options for converting an async thunk
+ */
+export interface ConvertAsyncThunkOptions<
+  TEntity extends BaseEntity = BaseEntity,
+  TPayload = any,
+  TResult = any,
+> {
+  /**
+   * Handler for pending state (RTK: addCase(thunk.pending))
+   * Maps to handleAsync 'start'
+   */
+  onPending?: (entity: TEntity, payload: TPayload, api: Api) => void
+
+  /**
+   * Handler for fulfilled state (RTK: addCase(thunk.fulfilled))
+   * Maps to handleAsync 'success'
+   */
+  onFulfilled?: (entity: TEntity, result: TResult, api: Api) => void
+
+  /**
+   * Handler for rejected state (RTK: addCase(thunk.rejected))
+   * Maps to handleAsync 'error'
+   */
+  onRejected?: (entity: TEntity, error: any, api: Api) => void
+
+  /**
+   * Handler called after operation completes (success or failure)
+   * Maps to handleAsync 'finally'
+   */
+  onSettled?: (entity: TEntity, api: Api) => void
+
+  /**
+   * Event scope for lifecycle handlers
+   * @default "entity"
+   */
+  scope?: "entity" | "type" | "global"
+}
+
+/**
+ * RTK slice reducer function
+ */
+export type SliceReducer<TState = any, TPayload = any> = (
+  state: TState,
+  action: { type: string; payload: TPayload },
+) => void
+
+/**
+ * RTK slice structure (minimal subset)
+ */
+export interface RTKSlice<TState = any> {
+  /**
+   * Slice name (used in action types)
+   */
+  name: string
+
+  /**
+   * Function that returns initial state
+   */
+  getInitialState: () => TState
+
+  /**
+   * Map of case reducers
+   */
+  caseReducers: Record<string, SliceReducer<TState, any>>
+
+  /**
+   * Optional: The combined reducer function
+   */
+  reducer?: (state: TState, action: any) => TState
+}
+
+/**
+ * Async thunk configuration for slice conversion
+ */
+export interface AsyncThunkConfig<
+  TEntity extends BaseEntity = BaseEntity,
+  TPayload = any,
+  TResult = any,
+> {
+  /**
+   * The async operation to perform
+   */
+  payloadCreator?: PayloadCreator<TPayload, TResult>
+
+  /**
+   * Handler for pending state
+   */
+  onPending?: (entity: TEntity, payload: TPayload, api: Api) => void
+
+  /**
+   * Handler for fulfilled state
+   */
+  onFulfilled?: (entity: TEntity, result: TResult, api: Api) => void
+
+  /**
+   * Handler for rejected state
+   */
+  onRejected?: (entity: TEntity, error: any, api: Api) => void
+
+  /**
+   * Handler called after completion
+   */
+  onSettled?: (entity: TEntity, api: Api) => void
+
+  /**
+   * Event scope
+   */
+  scope?: "entity" | "type" | "global"
+}
+
+/**
+ * Options for converting a slice
+ */
+export interface ConvertSliceOptions<TEntity extends BaseEntity = BaseEntity> {
+  /**
+   * Map of async thunks to convert
+   * Key is the thunk name, value is the thunk configuration
+   */
+  asyncThunks?: Record<string, AsyncThunkConfig<TEntity, any, any>>
+
+  /**
+   * Additional event handlers not from the slice
+   * These will be merged into the resulting type
+   */
+  extraHandlers?: Record<
+    string,
+    (entity: TEntity, payload?: any, api?: Api) => void
+  >
+}
+
+/**
+ * Inglorious type definition (minimal structure)
+ */
+export interface InglorisousType<TEntity extends BaseEntity = BaseEntity> {
+  /**
+   * Initialization handler
+   */
+  init?: (entity: TEntity, payload?: any, api?: Api) => void
+
+  /**
+   * Other event handlers
+   */
+  [key: string]:
+    | ((entity: TEntity, payload?: any, api?: Api) => void | Promise<void>)
+    | undefined
+}
+
+/**
+ * Converts an RTK createAsyncThunk to Inglorious handleAsync handlers
+ *
+ * This function adapts RTK's pending/fulfilled/rejected lifecycle to
+ * Inglorious's start/run/success/error/finally lifecycle.
+ *
+ * @template TEntity - The entity type
+ * @template TPayload - The payload type
+ * @template TResult - The result type returned by the async operation
+ *
+ * @param name - The thunk name (e.g., 'fetchTodos')
+ * @param payloadCreator - The async function that performs the operation
+ * @param options - Lifecycle handlers and configuration
+ * @returns Inglorious handleAsync event handlers
+ *
+ * @example
+ * ```typescript
+ * interface User {
+ *   id: number
+ *   name: string
+ * }
+ *
+ * interface UserEntity extends BaseEntity {
+ *   type: 'user'
+ *   currentUser: User | null
+ *   loading: boolean
+ *   error: string | null
+ * }
+ *
+ * const userHandlers = convertAsyncThunk<UserEntity, number, User>(
+ *   'fetchUser',
+ *   async (userId, thunkAPI) => {
+ *     const response = await fetch(`/api/users/${userId}`)
+ *     return response.json()
+ *   },
+ *   {
+ *     onPending: (entity) => {
+ *       entity.loading = true
+ *       entity.error = null
+ *     },
+ *     onFulfilled: (entity, user) => {
+ *       entity.loading = false
+ *       entity.currentUser = user
+ *     },
+ *     onRejected: (entity, error) => {
+ *       entity.loading = false
+ *       entity.error = error.message
+ *     }
+ *   }
+ * )
+ * ```
+ */
+export function convertAsyncThunk<
+  TEntity extends BaseEntity = BaseEntity,
+  TPayload = any,
+  TResult = any,
+>(
+  name: string,
+  payloadCreator: PayloadCreator<TPayload, TResult>,
+  options?: ConvertAsyncThunkOptions<TEntity, TPayload, TResult>,
+): InglorisousType<TEntity>
+
+/**
+ * Converts an RTK slice to an Inglorious type
+ *
+ * This function converts RTK reducers to Inglorious event handlers while
+ * preserving the same mutation-based syntax (both use Immer/Mutative).
+ * The resulting type can be used directly in an Inglorious store.
+ *
+ * @template TEntity - The entity type (should match slice state + BaseEntity fields)
+ * @template TState - The slice state type
+ *
+ * @param slice - RTK slice created with createSlice
+ * @param options - Async thunks and additional handlers
+ * @returns Inglorious type definition
+ *
+ * @example
+ * ```typescript
+ * interface Todo {
+ *   id: number
+ *   text: string
+ *   completed: boolean
+ * }
+ *
+ * interface TodoState {
+ *   items: Todo[]
+ *   filter: 'all' | 'active' | 'completed'
+ *   status: 'idle' | 'loading' | 'success' | 'error'
+ * }
+ *
+ * interface TodoListEntity extends BaseEntity, TodoState {
+ *   type: 'todoList'
+ * }
+ *
+ * // RTK slice
+ * const todosSlice = createSlice({
+ *   name: 'todos',
+ *   initialState: { items: [], filter: 'all', status: 'idle' } as TodoState,
+ *   reducers: {
+ *     addTodo: (state, action: PayloadAction<string>) => {
+ *       state.items.push({
+ *         id: Date.now(),
+ *         text: action.payload,
+ *         completed: false
+ *       })
+ *     },
+ *     toggleTodo: (state, action: PayloadAction<number>) => {
+ *       const todo = state.items.find(t => t.id === action.payload)
+ *       if (todo) todo.completed = !todo.completed
+ *     }
+ *   }
+ * })
+ *
+ * // Convert to Inglorious
+ * const todoList = convertSlice<TodoListEntity, TodoState>(todosSlice, {
+ *   asyncThunks: {
+ *     fetchTodos: {
+ *       payloadCreator: async () => {
+ *         const response = await fetch('/api/todos')
+ *         return response.json()
+ *       },
+ *       onPending: (entity) => {
+ *         entity.status = 'loading'
+ *       },
+ *       onFulfilled: (entity, todos: Todo[]) => {
+ *         entity.status = 'success'
+ *         entity.items = todos
+ *       },
+ *       onRejected: (entity, error) => {
+ *         entity.status = 'error'
+ *       }
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export function convertSlice<
+  TEntity extends BaseEntity = BaseEntity,
+  TState = any,
+>(
+  slice: RTKSlice<TState>,
+  options?: ConvertSliceOptions<TEntity>,
+): InglorisousType<TEntity>
+
+/**
+ * Creates a migration guide for a slice
+ *
+ * Analyzes an RTK slice and generates a readable migration guide showing
+ * the equivalent Inglorious code. Useful for documentation and planning.
+ *
+ * @param slice - RTK slice
+ * @returns Migration guide as formatted text
+ *
+ * @example
+ * ```typescript
+ * const guide = createMigrationGuide(todosSlice)
+ * console.log(guide)
+ * ```
+ */
+export function createMigrationGuide(slice: RTKSlice): string
+
+/**
+ * Creates a compatibility layer for existing RTK code
+ *
+ * This allows RTK-style dispatch calls to work with Inglorious Store
+ * during the migration period. The returned dispatch function translates
+ * RTK action objects to Inglorious notify calls.
+ *
+ * @param api - Inglorious API
+ * @param entityId - The entity ID to target
+ * @returns A dispatch function compatible with RTK actions
+ *
+ * @example
+ * ```typescript
+ * const dispatch = createRTKCompatDispatch(api, 'todos')
+ *
+ * // RTK-style action still works
+ * dispatch({
+ *   type: 'todos/addTodo',
+ *   payload: 'Buy milk'
+ * })
+ *
+ * // Translates to: api.notify('#todos:addTodo', 'Buy milk')
+ * ```
+ */
+export function createRTKCompatDispatch(
+  api: Api,
+  entityId: string,
+): (action: { type: string; payload?: any } | Function) => void
+
+/**
+ * RTK Action type for type safety
+ */
+export interface RTKAction<TPayload = any> {
+  type: string
+  payload?: TPayload
+  error?: any
+  meta?: any
+}
+
+/**
+ * Helper type to extract state from RTK slice
+ */
+export type SliceState<T extends RTKSlice> = ReturnType<T["getInitialState"]>
+
+/**
+ * Helper type to create entity from slice state
+ */
+export type EntityFromSlice<
+  T extends RTKSlice,
+  TType extends string = string,
+> = SliceState<T> & BaseEntity & { type: TType }
+
+/**
+ * Type-safe wrapper for convertSlice with inferred types
+ *
+ * @example
+ * ```typescript
+ * const todosSlice = createSlice({ ... })
+ *
+ * // Type is automatically inferred
+ * const todoList = convertSliceTyped(todosSlice, 'todoList', {
+ *   asyncThunks: { ... }
+ * })
+ * ```
+ */
+export function convertSliceTyped<
+  TSlice extends RTKSlice,
+  TType extends string,
+>(
+  slice: TSlice,
+  typeName: TType,
+  options?: ConvertSliceOptions<EntityFromSlice<TSlice, TType>>,
+): InglorisousType<EntityFromSlice<TSlice, TType>>

package/types/store.d.ts

@@ -146,3 +146,15 @@ export function createApi<
   store: Store<TEntity, TState>,
   extras?: Record<string, any>,
 ): Api<TEntity, TState>
+
+/**
+ * Helper to create a set of handlers for an async operation
+ */
+export function handleAsync<
+  TEntity extends BaseEntity = BaseEntity,
+  TPayload = any,
+  TResult = any,
+>(
+  type: string,
+  handlers: AsyncHandlers<TEntity, TPayload, TResult>,
+): EntityType<TEntity>