@inglorious/store 12.1.1 → 12.3.0

package/src/migration/rtk.js

@@ -76,8 +76,6 @@ export function convertAsyncThunk(name, payloadCreator, options = {}) {
         : undefined,
 
       run: async (payload, api) => {
-        // RTK payloadCreator signature: (arg, thunkAPI)
-        // Use dispatch for action compatibility, with notify fallback in tests/minimal APIs.
         const dispatch = api.dispatch
           ? api.dispatch.bind(api)
           : (action) => {
@@ -170,15 +168,12 @@ export function convertSlice(slice, options = {}) {
   const { asyncThunks = {}, extraHandlers = {}, extraActions = [] } = options
 
   const type = {
-    // Convert initialState to create handler.
-    // Preserve explicitly preloaded fields from entities (common in tests/SSR hydration).
     create(entity) {
       const initialState = slice.getInitialState()
       Object.assign(entity, extend(initialState, entity))
     },
   }
 
-  // Convert each reducer to an event handler
   for (const [actionName, reducer] of Object.entries(slice.caseReducers)) {
     const thunkConfig = asyncThunks[actionName]
     const isAsyncThunkReducer =
@@ -249,22 +244,15 @@ export function convertSlice(slice, options = {}) {
     }
 
     const handler = (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)
     }
 
-    // Expose both Inglorious-style event names and RTK action-type aliases.
-    // This enables direct dispatch of RTK slice actions without extra bridge wiring.
     type[actionName] = handler
     type[`${slice.name}/${actionName}`] = handler
   }
 
-  // Convert explicitly configured async thunks that are not embedded in slice reducers.
   for (const [thunkName, thunkHandlers] of Object.entries(asyncThunks)) {
     if (thunkHandlers?.payloadCreator && !type[thunkName]) {
       const asyncHandlers = convertAsyncThunk(
@@ -283,9 +271,6 @@ export function convertSlice(slice, options = {}) {
     }
   }
 
-  // Register additional RTK action types (e.g. createAction + extraReducers).
-  // RTK does not expose extraReducers through slice.caseReducers, so callers can
-  // provide the action creators/types explicitly and we route them through slice.reducer.
   for (const action of extraActions) {
     const actionType = typeof action === "string" ? action : action?.type
     if (typeof actionType !== "string" || type[actionType]) continue
@@ -295,7 +280,6 @@ export function convertSlice(slice, options = {}) {
     }
   }
 
-  // Add any extra handlers
   Object.assign(type, extraHandlers)
 
   return type
@@ -330,7 +314,6 @@ export function createMigrationGuide(slice) {
   lines.push("=".repeat(SEP_LENGTH))
   lines.push("")
 
-  // Show state structure
   lines.push("STATE STRUCTURE:")
   lines.push("RTK:")
   lines.push(
@@ -350,7 +333,6 @@ export function createMigrationGuide(slice) {
   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("")
@@ -365,7 +347,6 @@ export function createMigrationGuide(slice) {
   lines.push("=".repeat(SEP_LENGTH))
   lines.push("")
 
-  // Show selector conversion
   lines.push("SELECTORS:")
   lines.push("RTK:")
   lines.push(
@@ -403,22 +384,17 @@ export function createMigrationGuide(slice) {
 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

@@ -72,7 +72,7 @@ export function createStore({
     subscribe,
     update,
     notify,
-    dispatch, // needed for compatibility with Redux
+    dispatch,
     getTypes,
     getType,
     setType,
@@ -119,10 +119,6 @@ export function createStore({
       return []
     }
 
-    // Nothing queued means nothing to apply and nothing to publish: skipping the draft
-    // entirely, rather than copying the world just to arrive back where it started.
-    // This is what keeps a loop that pumps every animation frame cheap on the frames
-    // where neither the game nor the player had anything to say.
     if (!incomingEvents.length) {
       return []
     }
@@ -172,9 +168,6 @@ export function createStore({
         const event = incomingEvents.shift()
         processedEvents.push(event)
 
-        // Pausing and resuming are the store's own, and they keep dispatching like any
-        // other event, so the game behaviour still sees them and anything else that
-        // wants to react gets the same notification.
         if (event.type === "pause") {
           isHalted = true
         }
@@ -183,24 +176,6 @@ export function createStore({
           isHalted = false
         }
 
-        // Handle special system events
-        // `add` and `remove` change the world and are then dispatched like any
-        // other event, so that whatever is watching can hear about it. They are
-        // broadcast: the entity named by the payload is not the only one that wants
-        // to know, and something counting down what it put up needs to hear about
-        // each of them going.
-        //
-        // They are not the counterpart to `create` and `destroy`, which reach only
-        // the entity they are about so that those read as a constructor and a
-        // destructor without every handler beginning by checking whether it is the
-        // one being talked about.
-        //
-        // The two carry different payloads, and that is on purpose: a payload
-        // carries the least that can be had. A removal needs only the id, because
-        // everything else about the entity can still be looked up by it. An
-        // addition carries the entity itself, because there is nothing yet to look
-        // it up by -- the same asymmetry as removing a user by id but updating one
-        // by the patched user.
         if (event.type === "add") {
           addEntity(draft, event.payload)
         }
@@ -209,21 +184,6 @@ export function createStore({
           removeEntity(draft, event.payload)
         }
 
-        // A thing that stands through a change of state can still be told a different
-        // configuration, in either of the two ways the world offers.
-        //
-        // `patch` changes some of it and leaves the rest alone, which is how a screen
-        // takes over one field of something it shares with the screen before it. A field
-        // named as `undefined` is set to nothing rather than being left alone, which is
-        // how a key is taken off a mapping.
-        //
-        // `replace` installs what it is given and drops everything it does not mention,
-        // which is how the whole of something is said to be different.
-        //
-        // Neither takes the thing out of the world, so neither runs `create` or `destroy`:
-        // it never stopped standing, and a thing that was never removed cannot have been
-        // destroyed. This is the same pair the world has to hand for anything else --
-        // `add` and `remove` beside them, and post/delete/put/patch before that.
         if (event.type === "patch") {
           patchEntity(draft, event.payload)
         }
@@ -232,10 +192,8 @@ export function createStore({
           replaceEntity(draft, event.payload)
         }
 
-        // Parse the event to get handler name
         const { event: handlerName } = parseEvent(event.type)
 
-        // Get entities that should handle this event (filtered by EventMap)
         const entityIds = eventMap.getEntitiesForEvent(event.type)
 
         // A halted world stops handing out updates, because anything that moves by
@@ -248,8 +206,6 @@ export function createStore({
         const halted = isHalted && handlerName === "update"
 
         for (const id of entityIds) {
-          // Looked at before it is taken, because an entity the pause holds back is
-          // not going to be written to, and taking it would copy it for nothing.
           const entity = draft.entities[id]
           const type = types[entity.type]
 
@@ -273,7 +229,6 @@ export function createStore({
           }
         }
 
-        // Systems process events by handler name (not scoped)
         systems.forEach((system) => {
           const handle = system[handlerName]
           handle?.(draft.forSystems, event.payload, api)
@@ -338,7 +293,8 @@ export function createStore({
    * Sets an augmented type configuration given its name. Replacing a type, as
    * hot module reloading does, notifies subscribers, since what its entities
    * render may have changed. Adding a type does not: the store is unchanged,
-   * and a type can be added while rendering.
+   * and a type can be added while rendering. Entities already of a type being
+   * added get their `create` now: when they were added, it reached no handler.
    * @param {string} typeName - The name of the type to set.
    * @param {Type} type - The type configuration.
    * @returns {void}
@@ -354,6 +310,7 @@ export function createStore({
       if (entity.type === typeName) {
         eventMap.removeEntity(id, oldType, typeName)
         eventMap.addEntity(id, newType, typeName)
+        if (!oldType) notify(`#${id}:create`)
       }
     }
 
@@ -516,9 +473,6 @@ export function createStore({
     // does not mention, and what it keeps must not be shared with the previous state.
     const existing = draft.take(id)
 
-    // Configuring something that is not there is not a thing that can be done. The world
-    // is built in one pass, so a scene naming a thing another scene is yet to put up is
-    // ordinary rather than a mistake, and is not worth failing over.
     if (!existing) return
 
     draft.put(id, augmentEntity(id, { ...existing, ...config }))
@@ -561,6 +515,22 @@ export function createStore({
   }
 }
 
+/**
+ * Defines a behavior for an entity. It does nothing at runtime: it hands back
+ * the behavior it is given, and JavaScript apps never need it.
+ *
+ * It is for TypeScript apps, like Vue's `defineComponent` or Vite's
+ * `defineConfig`: its declaration in `types/store.d.ts` checks each member of
+ * the behavior by its name, so that a template's sub-renderers can take props
+ * while the handlers still get the entity, which a plain annotation cannot
+ * express. See that declaration for why.
+ *
+ * @returns {(behavior: object) => object} A function that returns the behavior it is given.
+ */
+export function defineType() {
+  return (behavior) => behavior
+}
+
 /**
  * A draft that writes straight into the entities it is given.
  *

package/types/api.d.ts

@@ -7,6 +7,7 @@ import type {
   Store,
   Stored,
 } from "./store"
+import type { AnyEvents, Notify } from "./events"
 
 /**
  * API object exposed to handlers.
@@ -14,10 +15,14 @@ import type {
  * An app's own `Api<AppEntity, AppState>` is an `Api`: a component typed with
  * the plain `Api` accepts it. So the members that read types give the plain
  * `EntityType`, rather than one typed for the app's entities.
+ *
+ * Told the app's events, `Api<AppEntity, AppState, AppEvents>` checks what
+ * `notify` sends (see `EventsOf`), and is still an `Api`.
  */
 export interface Api<
   TEntity extends BaseEntity = BaseEntity,
   TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
+  TEvents = AnyEvents,
 > {
   getTypes: () => Record<string, EntityType>
   getType: (typeName: string) => EntityType
@@ -35,8 +40,8 @@ export interface Api<
   }
   select: <TResult>(selector: (state: TState) => TResult) => TResult
   dispatch: (event: Event) => void
-  notify: (type: string, payload?: any) => void
-  [key: string]: any // For middleware extras
+  notify: Notify<TEvents, TEntity>
+  [key: string]: any
 }
 
 /**
@@ -45,7 +50,8 @@ export interface Api<
 export function createApi<
   TEntity extends BaseEntity = BaseEntity,
   TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
+  TEvents = AnyEvents,
 >(
-  store: Store<TEntity, TState>,
+  store: Store<TEntity, TState, TEvents>,
   extras?: Record<string, any>,
-): Api<TEntity, TState>
+): Api<TEntity, TState, TEvents>

package/types/behaviors/async.d.ts

@@ -73,6 +73,9 @@ export interface AsyncHandlers<
  * ```
  *
  * The `scope` option changes where the events are sent, not their names.
+ *
+ * Each call gets a `callId` that all its events carry, so that a wrapper such
+ * as `optimistic` can tell overlapping calls apart.
  */
 export type AsyncEvents<
   TType extends string,
@@ -85,27 +88,38 @@ export type AsyncEvents<
 } & {
   [K in `${TType}Start`]?: (
     entity: TEntity,
-    payload: TPayload,
+    event: AsyncCall<{ payload: TPayload }>,
     api: TApi,
   ) => void
 } & {
   [K in `${TType}Run`]: (
     entity: TEntity,
-    payload: TPayload,
+    event: AsyncCall<{ payload: TPayload }>,
     api: TApi,
   ) => Promise<void>
 } & {
   [K in `${TType}Success`]: (
     entity: TEntity,
-    result: TResult,
+    event: AsyncCall<{ result: TResult }>,
     api: TApi,
   ) => void
 } & {
-  [K in `${TType}Error`]: (entity: TEntity, error: any, api: TApi) => void
+  [K in `${TType}Error`]: (
+    entity: TEntity,
+    event: AsyncCall<{ error: any }>,
+    api: TApi,
+  ) => void
 } & {
-  [K in `${TType}Finally`]: (entity: TEntity, payload: void, api: TApi) => void
+  [K in `${TType}Finally`]: (
+    entity: TEntity,
+    event: AsyncCall,
+    api: TApi,
+  ) => void
 }
 
+/** What an event of one call of an async behavior carries: its `callId`. */
+export type AsyncCall<T = {}> = T & { callId: number }
+
 /**
  * Creates a set of event handlers for managing an asynchronous operation lifecycle.
  *

package/types/behaviors/optimistic.d.ts

@@ -1,5 +1,5 @@
 import { Api } from "../api"
-import { AsyncEvents } from "./async"
+import { AsyncCall, AsyncEvents } from "./async"
 import { BaseEntity } from "../store"
 
 /**
@@ -9,6 +9,10 @@ import { BaseEntity } from "../store"
  * The wrapper snapshots the current values for those keys, applies the patch
  * on start, and restores the previous values automatically if the operation fails.
  *
+ * Each call keeps its own snapshot, so calls can overlap. Give `rollback` to
+ * undo a failed call's change yourself, such as removing the temporary item it
+ * added to a list, in place of restoring the snapshot.
+ *
  * The behavior keeps the events `handleAsync` named and typed, and always has
  * a start event.
  */
@@ -27,10 +31,13 @@ export function optimistic<
         payload: TPayload,
         api: TApi,
       ) => Record<string, any> | null | undefined),
+  options?: {
+    rollback?: (entity: TEntity, payload: TPayload, api: TApi) => void
+  },
 ): AsyncEvents<TType, TEntity, TPayload, TResult, TApi> & {
   [K in `${TType}Start`]: (
     entity: TEntity,
-    payload: TPayload,
+    event: AsyncCall<{ payload: TPayload }>,
     api: TApi,
   ) => void
 }

package/types/events.d.ts

@@ -0,0 +1,149 @@
+// The events a store answers, so that `notify` can check them: the event's
+// name, wherever it is sent, and its payload.
+
+import type { BaseEntity, Stored } from "./store"
+
+declare const anyEvents: unique symbol
+
+/**
+ * The events of an api or a store that has not been told its events: any
+ * name, any payload. It is the default, so an untyped app type-checks as
+ * before.
+ */
+export type AnyEvents = { readonly [anyEvents]: true }
+
+/**
+ * The events a store's types answer, by name, with their payloads, read from
+ * the types' own declarations: the second parameter of each handler is its
+ * payload, and a handler that takes none has no payload. `render` and the
+ * other `render…` members are renderers, not events, so they are left out.
+ *
+ * ```ts
+ * type CounterType = {
+ *   add: (entity: CounterEntity, amount: number) => void
+ *   reset: (entity: CounterEntity) => void
+ * }
+ *
+ * type AppEvents = EventsOf<CounterType | LabelType>
+ * // { add: number; reset: void; ...the label's events }
+ *
+ * type AppApi = Api<AppEntity, AppState, AppEvents>
+ * ```
+ *
+ * An event two types answer takes either type's payload.
+ */
+export type EventsOf<TTypes> = {
+  [TEvent in HandlerName<TTypes>]: TTypes extends unknown
+    ? TEvent extends keyof TTypes
+      ? PayloadOf<TTypes[TEvent]>
+      : never
+    : never
+}
+
+/**
+ * The events the store answers itself, whatever its types: an entity
+ * arriving, leaving or changing, and the world pausing and resuming.
+ */
+export type BuiltInEvents<TEntity extends BaseEntity = BaseEntity> = {
+  add: TEntity & { id: string }
+  remove: string
+  patch: Partial<TEntity> & { id: string }
+  replace: Stored<TEntity>
+  pause: void
+  resume: void
+  update: number | undefined
+}
+
+/**
+ * How an event is sent: by its name alone, broadcast to whoever answers it,
+ * or after a target that narrows it down to a type (`Type:event`), an entity
+ * (`#id:event`) or both (`Type#id:event`). Only the event's name is checked:
+ * the target is usually built at runtime, such as `` `#${entity.id}:submit` ``.
+ */
+export type EventType<TEvents> =
+  EventName<TEvents> | `${string}:${EventName<TEvents>}`
+
+/**
+ * Sends an event. Told the store's events, it checks the event's name and
+ * its payload: `notify("#debate:lineAdd", line)` must name an event the
+ * store's types answer, and `line` must be that event's payload. An event
+ * with no payload takes none. Otherwise any name and payload go.
+ */
+export type Notify<
+  TEvents = AnyEvents,
+  TEntity extends BaseEntity = BaseEntity,
+> = AnyEvents extends TEvents
+  ? (type: string, payload?: any) => void
+  : TypedNotify<WithBuiltIns<TEvents, BuiltInEvents<TEntity>>>
+
+type EventName<TEvents> = keyof TEvents & string
+
+/**
+ * The app's events and the store's own, by name. An app event named like a
+ * built-in one, such as an `add` that takes an amount, takes either payload,
+ * because its handlers hear both: the store broadcasts entities as `add` too.
+ */
+type WithBuiltIns<TEvents, TBuiltIns> = {
+  [K in keyof TEvents | keyof TBuiltIns]:
+    | (K extends keyof TEvents ? TEvents[K] : never)
+    | (K extends keyof TBuiltIns ? TBuiltIns[K] : never)
+}
+
+/** The event a sent type names: what follows its target, if it has one. */
+type EventOf<TType extends string> = TType extends `${string}:${infer TEvent}`
+  ? TEvent
+  : TType
+
+/** The payload as `notify`'s last parameters: none, optional or required. */
+type PayloadArgs<TPayload> = [TPayload] extends [void]
+  ? [payload?: undefined]
+  : undefined extends TPayload
+    ? [payload?: TPayload]
+    : [payload: TPayload]
+
+/**
+ * A typed `notify`, declared as a method and taken out by name, with an
+ * overload that nothing can call: it only lets a typed api or store fit
+ * where a plain one is expected, such as a component that takes any app's
+ * api. It comes first, so that a call that fits neither is explained by the
+ * typed one.
+ */
+type TypedNotify<TEvents> = {
+  notify(type: never, payload: never): void
+  notify<TType extends EventType<TEvents>>(
+    type: TType,
+    ...payload: PayloadArgs<TEvents[EventOf<TType> & keyof TEvents]>
+  ): void
+}["notify"]
+
+/**
+ * The handlers' names of each type: every function but the renderers. Only
+ * named members count: a type that also takes any handler, through an index
+ * signature such as `[handler: string]: unknown`, keeps its named events.
+ */
+type HandlerName<TTypes> = TTypes extends unknown
+  ? keyof {
+      [
+        K in keyof TTypes as string extends K
+          ? never
+          : number extends K
+            ? never
+            : K extends `render${string}`
+              ? never
+              : TTypes[K] extends (...args: never[]) => unknown
+                ? K
+                : never
+      ]: true
+    } &
+      string
+  : never
+
+/** A handler's payload: its second parameter, or none if it takes only the entity. */
+type PayloadOf<THandler> = THandler extends (
+  entity: never,
+  ...rest: infer TRest
+) => unknown
+  ? TRest extends []
+    ? void
+    : TRest[0]
+  : never

package/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./api"
 export * from "./behaviors/async"
+export * from "./events"
 export * from "./select"
 export * from "./store"
 export * from "./test"

package/types/migration/rtk.d.ts

@@ -6,8 +6,6 @@ import { Api, BaseEntity } from "../store"
  */
 export interface ThunkAPI {
   dispatch: Api["notify"]
-  // Add other thunk API properties as needed
-  // getState, extra, requestId, signal, rejectWithValue, fulfillWithValue
 }
 
 /**