@inglorious/store 9.1.0 → 9.3.0

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/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/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"