@inglorious/store 11.1.0 → 11.3.0

package/README.md

@@ -400,6 +400,9 @@ The practical use is a world whose rules change with its state — a keyboard wh
 mean one thing on a menu and another in play:
 
 ```javascript
+import { fsm } from "@inglorious/store/fsm"
+import { scenes } from "@inglorious/store/scenes"
+
 const types = {
   Keyboard: { keyDown: (entity, key) => report(key) },
   Game: [
@@ -730,7 +733,7 @@ Inglorious Store now provides utilities to **gradually migrate from RTK slices a
 ### Converting Async Thunks
 
 ```javascript
-import { convertAsyncThunk } from "@inglorious/store/rtk"
+import { convertAsyncThunk } from "@inglorious/store/migration/rtk"
 
 const fetchTodos = async (userId) => {
   const res = await fetch(`/api/users/${userId}/todos`)
@@ -765,7 +768,7 @@ const todoList = {
 ### Converting Slices
 
 ```javascript
-import { convertSlice } from "@inglorious/store/rtk"
+import { convertSlice } from "@inglorious/store/migration/rtk"
 
 const todoListType = convertSlice(todosSlice, {
   asyncThunks: {
@@ -806,7 +809,7 @@ dispatch({ type: "todos/addTodo", payload: "Buy milk" })
 ### Migration Guide
 
 ```javascript
-import { createMigrationGuide } from "@inglorious/store/rtk"
+import { createMigrationGuide } from "@inglorious/store/migration/rtk"
 
 const guide = createMigrationGuide(todosSlice)
 console.log(guide)
@@ -968,7 +971,108 @@ const withLoading = (type) => ({
 const form = [resettable, validated, withLoading]
 ```
 
-When multiple behaviors define the same event, they all run in order. This allows you to build middleware-like patterns: validation, logging, error handling, loading states, etc.
+When multiple behaviors define the same event, the later one replaces the earlier: a type has one handler per event. That is why a wrapper like `validated` receives the type built so far and calls `type.submit?.(...)` itself, which is how you build middleware-like patterns: validation, logging, error handling, loading states, etc.
+
+### 🚦 State Machines
+
+Some entities answer the same event differently depending on the state they are in: a door
+opens when it is closed and does nothing when it is locked. `fsm()` turns a type into a
+finite state machine in the manner of the OOP State pattern, where each state says what it
+answers and the entity's `state` field says which state is in charge:
+
+```javascript
+import { fsm } from "@inglorious/store/fsm"
+
+const types = {
+  Door: [
+    {
+      // What every state does, unless a state says otherwise
+      knock(entity) {
+        entity.knocks++
+      },
+    },
+    fsm({
+      closed: {
+        open(entity) {
+          entity.state = "open"
+        },
+        lock(entity) {
+          entity.state = "locked"
+        },
+      },
+      open: {
+        close(entity) {
+          entity.state = "closed"
+        },
+      },
+      locked: {
+        // Takes over knock while locked
+        knock(entity, _, api) {
+          api.notify("bark")
+        },
+        unlock(entity) {
+          entity.state = "closed"
+        },
+      },
+    }),
+  ],
+}
+
+const entities = { door: { type: "Door", state: "closed", knocks: 0 } }
+```
+
+- A state's handler **replaces** the type's handler for the same event, so the type's
+  handler is the default and a state takes it over by naming the event. An event that
+  neither the current state nor the type answers is ignored.
+- A handler moves the entity by assigning `entity.state`. An entity with no `state` starts
+  in `"default"`.
+- When a handler has actually moved the entity, `fsm` broadcasts
+  `stateChange` with `{ entityId, from, to }`. It is broadcast rather than addressed to the
+  entity, because what wants to hear it is usually something else, so a listener checks
+  `entityId`.
+
+Typical uses: request and connection status, wizards, editors that are viewing, editing or
+saving, media players, drag and drop, and the screens of a game.
+
+#### Scenes
+
+`scenes()` is the usual partner of `fsm()`: the machine says when it moves, and `scenes()`
+says which entities stand in each state. On `create` and on its own `stateChange` it `add`s
+what the new state has, `remove`s what only the old one had, and `patch`es what both have
+but configure differently, comparing entities by `id`:
+
+```javascript
+import { fsm } from "@inglorious/store/fsm"
+import { scenes } from "@inglorious/store/scenes"
+
+const types = {
+  Wizard: [
+    scenes({
+      account: () => [{ id: "accountForm", type: "AccountForm" }],
+      billing: (wizard) => [
+        { id: "billingForm", type: "BillingForm", plan: wizard.plan },
+      ],
+    }),
+    fsm({
+      account: {
+        next(entity) {
+          entity.state = "billing"
+        },
+      },
+    }),
+  ],
+}
+
+const entities = { wizard: { type: "Wizard", state: "account", plan: "pro" } }
+```
+
+The entity running the machine keeps what it has up in `scene`.
+
+The name comes from games, where each screen is a scene, but nothing about it is game-specific.
+In a web app it gives entities a lifetime tied to a state: a page's forms and lists exist only
+while you are on it (their `create` and `destroy` can open and close subscriptions), each wizard
+step has its own form, and a logged-out app has a `loginForm` that a logged-in one does not —
+while anything both states share, like a header or a cart, survives the move untouched.
 
 ### ⏱️ Batched Mode
 
@@ -1325,6 +1429,7 @@ Each handler receives three arguments:
 - **`patch` / `replace`** - change a thing that is already standing, the first touching only
   what it names and the second installing all of it
 - **`update`** - the frame tick, disabled while the world is paused
+- **`stateChange`** - broadcast by `fsm()` when an entity moves, with `{ entityId, from, to }`
 
 #### Pausing the world
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "11.1.0",
+  "version": "11.3.0",
   "description": "A state manager for real-time, collaborative apps, inspired by game development patterns and compatible with Redux.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -40,9 +40,29 @@
       "types": "./types/migration/rtk.d.ts",
       "import": "./src/migration/rtk.js"
     },
+    "./async": {
+      "types": "./types/behaviors/async.d.ts",
+      "import": "./src/behaviors/async.js"
+    },
+    "./optimistic": {
+      "types": "./types/behaviors/optimistic.d.ts",
+      "import": "./src/behaviors/optimistic.js"
+    },
+    "./fsm": {
+      "types": "./types/behaviors/state-machine/fsm.d.ts",
+      "import": "./src/behaviors/state-machine/fsm.js"
+    },
+    "./scenes": {
+      "types": "./types/behaviors/state-machine/scenes.d.ts",
+      "import": "./src/behaviors/state-machine/scenes.js"
+    },
+    "./*.js": {
+      "types": "./types/*.d.ts",
+      "import": "./src/*.js"
+    },
     "./*": {
       "types": "./types/*.d.ts",
-      "import": "./src/*"
+      "import": "./src/*.js"
     }
   },
   "files": [

package/src/{async.js → behaviors/async.js}

@@ -5,7 +5,7 @@
  * success, error, and finally. The lifecycle events are automatically scoped based
  * on the provided options.
  *
- * @template {import('./store').BaseEntity} TEntity - The entity type
+ * @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
  *
@@ -13,19 +13,19 @@
  *   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]
+ * @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
+ * @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]
+ * @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]
+ * @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]
+ * @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)
  *

package/src/{optimistic.js → behaviors/optimistic.js}

@@ -8,15 +8,16 @@ const START = 0
  * Pass either a static shallow patch object or a factory that returns one.
  * The wrapper applies the patch during `Start` and rolls it back during `Error`.
  *
- * @template {import('./store').BaseEntity} TEntity
+ * @template {import('../store').BaseEntity} TEntity
  * @template TPayload
  * @template TResult
+ * @template {string} TType
  *
- * @param {import('./async').AsyncEventHandlers<TEntity, TPayload, TResult>} behavior
- * @param {Record<string, any> | ((entity: TEntity, payload: TPayload, api: import('./store').Api) => Record<string, any> | null | undefined)} optimistic
+ * @param {import('./async').AsyncEvents<TType, TEntity, TPayload, TResult>} behavior
+ * @param {Record<string, any> | ((entity: TEntity, payload: TPayload, api: import('../store').Api) => Record<string, any> | null | undefined)} optimistic
  *   Shallow patch applied optimistically on start, or a factory that returns it.
  *
- * @returns {import('./async').AsyncEventHandlers<TEntity, TPayload, TResult>}
+ * @returns {import('./async').AsyncEvents<TType, TEntity, TPayload, TResult>}
  *
  * @example
  * const saveItem = optimistic(
@@ -108,9 +109,9 @@ export function optimistic(behavior, optimistic) {
       behavior[errorEvent]?.(entity, error, api)
     },
 
-    [finallyEvent](entity, api) {
+    [finallyEvent](entity, payload, api) {
       try {
-        behavior[finallyEvent]?.(entity, api)
+        behavior[finallyEvent]?.(entity, payload, api)
       } finally {
         snapshots.delete(getEntityKey(entity))
       }

package/src/behaviors/state-machine/fsm.js

@@ -0,0 +1,55 @@
+const DEFAULT_STATE = "default"
+
+export function fsm(states) {
+  const uniqueEventNames = [
+    ...new Set(Object.values(states).flatMap(Object.keys)),
+  ]
+
+  return (type) => {
+    return {
+      create(entity, payload, api) {
+        type.create?.(entity, payload, api)
+
+        entity.state ??= DEFAULT_STATE
+      },
+
+      ...uniqueEventNames.reduce(
+        (acc, eventName) => ({
+          ...acc,
+
+          [eventName](entity, event, api) {
+            const from = entity.state
+
+            // A state answers for itself, and what it has to say replaces what the type
+            // would have said. The type-stage handler is the default -- the thing every
+            // state would otherwise do -- and a state takes it over by naming the same
+            // event, which is how a state can take the way out for itself rather than
+            // being quit by, without whatever answers by default having to know that
+            // state exists.
+            const handler = states[entity.state]?.[eventName] ?? type[eventName]
+
+            handler?.(entity, event, api)
+
+            announce(entity, from, api)
+          },
+        }),
+        {},
+      ),
+    }
+  }
+}
+
+/**
+ * A machine announces where it has landed, but only when it has actually moved: a
+ * handler that reads the state without changing it should not wake anything up.
+ *
+ * The announcement is broadcast and carries the id, rather than being addressed to
+ * this entity, because what wants to hear it is usually something else.
+ */
+function announce(entity, from, api) {
+  const to = entity.state
+
+  if (to === from) return
+
+  api.notify("stateChange", { entityId: entity.id, from, to })
+}

package/src/behaviors/state-machine/scenes.js

@@ -0,0 +1,89 @@
+import { isDeepEqual } from "@inglorious/utils/object.js"
+
+/**
+ * Puts an entity up, and takes down whatever the state before it had up.
+ *
+ * A state machine says when it moves; this says what each state is made of, and is
+ * usually the pair to `fsm`. Together they cover the ordinary case of a game that is a
+ * few screens and a world that survives the move between them -- a menu has nothing on it
+ * that the play has, and two states of the same play have all of it in common.
+ *
+ * Only the difference between two states is touched. Anything they have in common is
+ * left standing as it is, which is what carries whatever the two share from one into the
+ * next without rebuilding it, and so without losing whatever the world has already done
+ * to it.
+ *
+ * A thing that stands on both sides but is not configured the same way is patched rather
+ * than rebuilt, so one state may take over part of it -- a keyboard whose keys mean
+ * something else there -- without the rest of it being torn up to make room.
+ *
+ * @example
+ * ```js
+ * import { fsm } from "@inglorious/store/fsm"
+ * import { scenes } from "@inglorious/store/scenes"
+ *
+ * const SCENES = {
+ *   title: () => [createTitleEntity(), createMenuEntity()],
+ *   play: () => [createPaddleEntity(), createBallEntity()],
+ * }
+ *
+ * const types = {
+ *   Game: [scenes(SCENES), fsm({ title: { start(e) { e.state = "play" } } })],
+ * }
+ *
+ * const entities = { game: { type: "Game", state: "title" } }
+ * ```
+ *
+ * @param {object} scenesByState - What stands in each state, given the state and the
+ *   entity asking. Returns the entity configurations to have standing.
+ * @returns {object} The behaviour.
+ */
+export function scenes(scenesByState) {
+  function build(entity, state, api) {
+    const leaving = entity.scene ?? []
+    const arriving = scenesByState[state]?.(entity) ?? []
+
+    const leavingIds = leaving.map(({ id }) => id)
+    const arrivingIds = arriving.map(({ id }) => id)
+
+    for (const { id } of leaving) {
+      if (arrivingIds.includes(id)) continue
+
+      api.notify("remove", id)
+    }
+
+    for (const added of arriving) {
+      if (!leavingIds.includes(added.id)) {
+        api.notify("add", added)
+
+        continue
+      }
+
+      // The same thing stands on both sides of the move, so it is neither added nor
+      // removed -- but it may be wanted to be a different thing now, and then only what
+      // has actually changed is merged over it. That is what leaves a shared thing where
+      // the world had put it when the next state says nothing different about it.
+      const previous = leaving.find(({ id }) => id === added.id)
+
+      if (!isDeepEqual(previous, added)) {
+        api.notify("patch", added)
+      }
+    }
+
+    entity.scene = arriving
+  }
+
+  return {
+    create(entity, payload, api) {
+      build(entity, entity.state, api)
+    },
+
+    // The announcement is broadcast and carries the id, so that anything else listening
+    // for it can tell which machine moved. This one is only interested in its own.
+    stateChange(entity, { entityId, to }, api) {
+      if (entityId !== entity.id) return
+
+      build(entity, to, api)
+    },
+  }
+}

package/src/migration/rtk.js

@@ -7,7 +7,7 @@
 
 import { extend } from "@inglorious/utils/object.js"
 
-import { handleAsync } from "../async"
+import { handleAsync } from "../behaviors/async.js"
 
 const SEP_LENGTH = 50
 const INDENT_SPACES = 2

package/types/{async.d.ts → behaviors/async.d.ts}

@@ -1,5 +1,5 @@
-import { Api } from "./api"
-import { BaseEntity } from "./store"
+import { Api } from "../api"
+import { BaseEntity } from "../store"
 
 /**
  * Scope option for async handler events
@@ -27,57 +27,83 @@ export interface AsyncHandlers<
   TEntity extends BaseEntity = BaseEntity,
   TPayload = any,
   TResult = any,
+  TApi extends Api = Api,
 > {
   /**
    * Called synchronously before the async operation starts
    * Use for setting loading states
    */
-  start?: (entity: TEntity, payload: TPayload, api: Api) => void
+  start?: (entity: TEntity, payload: TPayload, api: TApi) => 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
+  run: (payload: TPayload, api: TApi) => 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
+  success?: (entity: TEntity, result: TResult, api: TApi) => void
 
   /**
    * Called when the operation fails
    * Receives the entity, the error, and api
    */
-  error?: (entity: TEntity, error: any, api: Api) => void
+  error?: (entity: TEntity, error: any, api: TApi) => void
 
   /**
    * Called after the operation completes (success or failure)
    * Use for cleanup, resetting loading states, etc.
    */
-  finally?: (entity: TEntity, api: Api) => void
+  finally?: (entity: TEntity, api: TApi) => void
 }
 
 /**
- * Generated event handlers returned by handleAsync
- * Contains handlers for all lifecycle stages
+ * The events `handleAsync(type, ...)` generates, by name: `type`, `typeRun`,
+ * `typeSuccess`, `typeError`, `typeFinally` and, when a `start` handler is
+ * given, `typeStart`. A type alias can list them all in one go:
+ *
+ * ```ts
+ * type TodoListType = {
+ *   render: (entity: TodoListEntity, api: AppApi) => TemplateResult
+ * } & AsyncEvents<"fetchTodos", TodoListEntity, void, Todo[], AppApi>
+ * ```
+ *
+ * The `scope` option changes where the events are sent, not their names.
  */
-export interface AsyncEventHandlers<
+export type AsyncEvents<
+  TType extends string,
   TEntity extends BaseEntity = BaseEntity,
   TPayload = any,
   TResult = any,
-> {
-  /**
-   * Main trigger handler
-   * Dispatches start (if defined) and run events
-   */
-  [key: string]: (
+  TApi extends Api = Api,
+> = {
+  [K in TType]: (entity: TEntity, payload: TPayload, api: TApi) => void
+} & {
+  [K in `${TType}Start`]?: (
     entity: TEntity,
     payload: TPayload,
-    api: Api,
-  ) => void | Promise<void>
+    api: TApi,
+  ) => void
+} & {
+  [K in `${TType}Run`]: (
+    entity: TEntity,
+    payload: TPayload,
+    api: TApi,
+  ) => Promise<void>
+} & {
+  [K in `${TType}Success`]: (
+    entity: TEntity,
+    result: TResult,
+    api: TApi,
+  ) => void
+} & {
+  [K in `${TType}Error`]: (entity: TEntity, error: any, api: TApi) => void
+} & {
+  [K in `${TType}Finally`]: (entity: TEntity, payload: void, api: TApi) => void
 }
 
 /**
@@ -86,9 +112,16 @@ export interface AsyncEventHandlers<
  * Generates handlers for: trigger, start, run, success, error, finally
  * These can be spread into an entity type definition.
  *
+ * The event name, the entity, the payload, the result and the api are inferred
+ * from `type` and from the handlers' parameters, or from the type the handlers
+ * are spread into (`satisfies EntityType<TodoListEntity, AppApi>`). Explicit
+ * type arguments still work, but the event names are then plain strings.
+ *
  * @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
+ * @template TApi - The api the handlers receive, such as the app's own
+ * @template TType - The base event name, inferred from `type`
  *
  * @param type - The base event name (e.g., 'fetchTodos')
  * @param handlers - Handler functions for each lifecycle stage
@@ -104,23 +137,23 @@ export interface AsyncEventHandlers<
  * }
  *
  * interface TodoListEntity extends BaseEntity {
- *   type: 'todoList'
+ *   type: 'TodoList'
  *   todos: Todo[]
  *   status: 'idle' | 'loading' | 'success' | 'error'
  *   error?: string
  * }
  *
- * const todoList = {
- *   init(entity: TodoListEntity) {
+ * const TodoList = {
+ *   create(entity) {
  *     entity.todos = []
  *     entity.status = 'idle'
  *   },
  *
- *   ...handleAsync<TodoListEntity, void, Todo[]>('fetchTodos', {
+ *   ...handleAsync('fetchTodos', {
  *     start(entity) {
  *       entity.status = 'loading'
  *     },
- *     async run(_, api) {
+ *     async run(_: void, api): Promise<Todo[]> {
  *       const response = await fetch('/api/todos')
  *       return response.json()
  *     },
@@ -133,15 +166,17 @@ export interface AsyncEventHandlers<
  *       entity.error = error.message
  *     }
  *   })
- * }
+ * } satisfies EntityType<TodoListEntity, AppApi>
  * ```
  */
 export function handleAsync<
   TEntity extends BaseEntity = BaseEntity,
   TPayload = any,
   TResult = any,
+  TApi extends Api = Api,
+  TType extends string = string,
 >(
-  type: string,
-  handlers: AsyncHandlers<TEntity, TPayload, TResult>,
+  type: TType,
+  handlers: AsyncHandlers<TEntity, TPayload, TResult, TApi>,
   options?: AsyncOptions,
-): AsyncEventHandlers<TEntity, TPayload, TResult>
+): AsyncEvents<TType, TEntity, TPayload, TResult, TApi>

package/types/{optimistic.d.ts → behaviors/optimistic.d.ts}

@@ -1,6 +1,6 @@
-import { Api } from "./api"
-import { AsyncEventHandlers } from "./async"
-import { BaseEntity } from "./store"
+import { Api } from "../api"
+import { AsyncEvents } from "./async"
+import { BaseEntity } from "../store"
 
 /**
  * Decorates an async behavior with optimistic update boilerplate.
@@ -8,18 +8,29 @@ import { BaseEntity } from "./store"
  * Pass either a static shallow patch object or a factory that returns one.
  * The wrapper snapshots the current values for those keys, applies the patch
  * on start, and restores the previous values automatically if the operation fails.
+ *
+ * The behavior keeps the events `handleAsync` named and typed, and always has
+ * a start event.
  */
 export function optimistic<
   TEntity extends BaseEntity = BaseEntity,
   TPayload = any,
   TResult = any,
+  TApi extends Api = Api,
+  TType extends string = string,
 >(
-  behavior: AsyncEventHandlers<TEntity, TPayload, TResult>,
+  behavior: AsyncEvents<TType, TEntity, TPayload, TResult, TApi>,
   optimistic:
     | Record<string, any>
     | ((
         entity: TEntity,
         payload: TPayload,
-        api: Api,
+        api: TApi,
       ) => Record<string, any> | null | undefined),
-): AsyncEventHandlers<TEntity, TPayload, TResult>
+): AsyncEvents<TType, TEntity, TPayload, TResult, TApi> & {
+  [K in `${TType}Start`]: (
+    entity: TEntity,
+    payload: TPayload,
+    api: TApi,
+  ) => void
+}

package/types/behaviors/state-machine/fsm.d.ts

@@ -0,0 +1,109 @@
+import type { Api } from "../../api"
+import type { BaseEntity, EntityType, EventHandler } from "../../store"
+
+/** The state an entity is in until a handler moves it. */
+export type DefaultState = "default"
+
+/**
+ * The states an entity can be in: the values of its `state` field, as declared
+ * on its interface. An entity that declares no `state` can be in any.
+ */
+export type StateOf<TEntity extends BaseEntity> = TEntity extends {
+  state?: infer TState extends string
+}
+  ? TState
+  : string
+
+/**
+ * What one state answers to: its handlers, by event name. A handler moves the
+ * entity by assigning `entity.state`.
+ */
+export type FsmState<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api = Api,
+> = {
+  [eventName: string]: EventHandler<TEntity, TApi> | undefined
+}
+
+/**
+ * Each state's handlers, by state name. A state that answers nothing of its
+ * own can be left out, and then it answers what the type does.
+ */
+export type FsmStates<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api = Api,
+> = {
+  [TState in StateOf<TEntity> | DefaultState]?: FsmState<TEntity, TApi>
+}
+
+/**
+ * The payload of `stateChange`, which `fsm` broadcasts whenever a handler has
+ * moved the entity: the entity's id, the state it left and the one it is in.
+ */
+export interface StateChangePayload<TState extends string = string> {
+  entityId: string
+  from: TState
+  to: TState
+}
+
+/**
+ * Makes a type a finite state machine, in the manner of the OOP State pattern:
+ * what the entity does on an event depends on the state it is in.
+ *
+ * Each state names the events it answers. A state's handler replaces the
+ * type's handler for the same event, so the type's handler is what every state
+ * does by default and a state takes it over by naming the event. A handler
+ * moves the entity by assigning `entity.state`; the entity starts in its own
+ * `state`, or in `"default"` when it has none.
+ *
+ * After a handler has moved the entity, the machine broadcasts `stateChange`
+ * with a `StateChangePayload`. A handler that leaves the state as it was
+ * announces nothing.
+ *
+ * The entity and the api are inferred from where the behavior is used, such as
+ * `types: { Door: [Door, fsm({ ... })] }` in a typed store. Declaring `state`
+ * on the entity's interface checks the state names as well.
+ *
+ * @example
+ * ```typescript
+ * interface DoorEntity extends BaseEntity {
+ *   type: "Door"
+ *   state: "closed" | "open" | "locked"
+ * }
+ *
+ * const types = {
+ *   Door: [
+ *     { knock: (entity) => console.log("Nobody's home") },
+ *     fsm({
+ *       closed: {
+ *         open(entity) {
+ *           entity.state = "open"
+ *         },
+ *         lock(entity) {
+ *           entity.state = "locked"
+ *         },
+ *       },
+ *       open: {
+ *         close(entity) {
+ *           entity.state = "closed"
+ *         },
+ *       },
+ *       locked: {
+ *         unlock(entity) {
+ *           entity.state = "closed"
+ *         },
+ *       },
+ *     }),
+ *   ],
+ * }
+ * ```
+ *
+ * @param states - Each state's handlers, by state name
+ * @returns A behavior that wraps the type it is applied to
+ */
+export function fsm<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api = Api,
+>(
+  states: FsmStates<TEntity, TApi>,
+): (type: EntityType<TEntity, TApi>) => EntityType<TEntity, TApi>

package/types/behaviors/state-machine/scenes.d.ts

@@ -0,0 +1,53 @@
+import type { Api } from "../../api"
+import type { StateOf } from "./fsm"
+import type { BaseEntity, EntityType, Stored } from "../../store"
+
+/**
+ * An entity a scene puts up. It needs its `id`, which is how two scenes tell
+ * what they have in common.
+ */
+export type SceneEntity = BaseEntity & {
+  id: string
+  [field: string]: unknown
+}
+
+/**
+ * What stands in each state, by state name: a function of the entity running
+ * the machine that returns the entities to have standing. A state left out has
+ * nothing standing.
+ */
+export type ScenesByState<TEntity extends BaseEntity = BaseEntity> = {
+  [TState in StateOf<TEntity>]?: (entity: Stored<TEntity>) => SceneEntity[]
+}
+
+/**
+ * Puts a state's entities up and takes down whatever the state before it had
+ * up. It is usually paired with `fsm`, which says when the state moves: on
+ * `create` it builds the entity's current state, and on its own `stateChange`
+ * it builds the state it moved to.
+ *
+ * Only the difference between two states is touched: an entity that is in
+ * both is left standing, and is patched rather than rebuilt when the next
+ * state configures it differently. Entities are compared by `id`, and the
+ * entity running the machine keeps what it has up in `scene`.
+ *
+ * @example
+ * ```typescript
+ * const types = {
+ *   Game: [
+ *     scenes({
+ *       title: () => [{ id: "menu", type: "Menu" }],
+ *       play: () => [{ id: "board", type: "Board" }],
+ *     }),
+ *     fsm({ title: { start(entity) { entity.state = "play" } } }),
+ *   ],
+ * }
+ * ```
+ *
+ * @param scenesByState - What stands in each state
+ * @returns A behavior handling `create` and `stateChange`
+ */
+export function scenes<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api = Api,
+>(scenesByState: ScenesByState<TEntity>): EntityType<TEntity, TApi>

package/types/index.d.ts

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

package/types/store.d.ts

@@ -41,7 +41,7 @@ export interface Event<T = any> {
  */
 export type EventHandler<
   TEntity extends BaseEntity = BaseEntity,
-  TApi extends Api<any, any> = Api,
+  TApi extends Api = Api,
 > = (entity: Stored<TEntity>, payload: any, api: TApi) => unknown
 
 /**
@@ -75,7 +75,7 @@ export type EventHandler<
  */
 export type EntityType<
   TEntity extends BaseEntity = BaseEntity,
-  TApi extends Api<any, any> = Api,
+  TApi extends Api = Api,
 > = {
   /** Draws the entity. Unlike an event handler, it receives the api second. */
   render?: Renderer<TEntity, TApi>
@@ -85,7 +85,7 @@ export type EntityType<
 /** A type's `render`: it receives the entity and the api. */
 export type Renderer<
   TEntity extends BaseEntity = BaseEntity,
-  TApi extends Api<any, any> = Api,
+  TApi extends Api = Api,
 > = (entity: Stored<TEntity>, api: TApi) => unknown
 
 /**
@@ -94,7 +94,7 @@ export type Renderer<
  */
 export type Behavior<
   TEntity extends BaseEntity = BaseEntity,
-  TApi extends Api<any, any> = Api,
+  TApi extends Api = Api,
 > =
   | EntityType<TEntity, TApi>
   | ((type: EntityType<TEntity, TApi>) => EntityType<TEntity, TApi>)
@@ -102,7 +102,7 @@ export type Behavior<
 /** What the store's `types` holds for one type name: a behavior, or several. */
 export type TypeDefinition<
   TEntity extends BaseEntity = BaseEntity,
-  TApi extends Api<any, any> = Api,
+  TApi extends Api = Api,
 > = Behavior<TEntity, TApi> | Behavior<TEntity, TApi>[]
 
 /**