@inglorious/store 12.2.0 → 12.3.0

package/README.md

@@ -1659,7 +1659,52 @@ interface SalesEntity extends ChartEntity {
 // types: { Router, Sales: Chart }
 ```
 
-**5. Test your handlers**
+**5. Check the events you send**
+
+The type declarations already list every event and its payload, so the api can check what `notify` sends. Read the events from them with `EventsOf`, and give them to the api as its third type argument:
+
+```typescript
+// types/index.d.ts
+import type { EventsOf } from "@inglorious/store"
+
+export type AppEvents = EventsOf<CounterType | LabelType>
+// { increment: void; add: number; copyLabel: void; ...the label's events }
+
+export type AppApi = Api<AppEntity, AppState, AppEvents>
+```
+
+Now every handler's `api.notify` checks the event's name, wherever it is sent (`"add"`, `"Counter:add"`, `` `#${entity.id}:add` ``), and its payload:
+
+```typescript
+api.notify(`#${entity.id}:add`, 2) // fine
+api.notify(`#${entity.id}:ad`, 2) // error: no type answers `ad`
+api.notify(`#${entity.id}:add`, "2") // error: `add` takes a number
+api.notify(`#${entity.id}:increment`, 1) // error: `increment` takes no payload
+```
+
+The store's own events (`add`, `remove`, `patch`, `replace`, `pause`, `resume`, `update`) are always there. Only the event's name is checked, not the target before it, because the target is usually built at runtime. Pass the events to `createStore<AppEntity, AppState, AppEvents>` too, so that `store.notify` checks them, and `mount` gives them to the root render. A typed api is still an `Api`: components that take any app's api accept it.
+
+Without the third type argument, `notify` takes any name and any payload, as before.
+
+**6. Give sub-renderers their props**
+
+Every render method takes props first: `render(props, api)`, where a type's props are its entity, and sub-renderers that draw one item, `renderX(props, ownProps, api)`, which get the component's props, then the item's own (`renderLine(props, line, api)`). `EntityType` reads every member as a handler, whose first parameter is the entity, so it rejects sub-renderers whose props are not the entity. `defineType` checks each member by its name instead: `render` takes the entity as its props, a sub-renderer keeps the types it declares, and every other member is a handler, whose entity and api are inferred:
+
+```typescript
+import { defineType } from "@inglorious/store"
+
+export const Scoreboard = defineType<ScoreboardEntity, AppApi>()({
+  ...template, // renderScoreboard(props, api), renderContender(props, speaker, api), ...
+  render(props, api) {
+    const debate = api.getEntity("debate")
+    return this.renderScoreboard({ ...props, memory: debate?.memory }, api)
+  },
+})
+```
+
+Inside its methods, `this` is the behavior, so `this.renderScoreboard` is checked too. It takes the entity and the api first, then the behavior, because TypeScript cannot infer one while being told the others. The result is an `EntityType`, so it goes in `types` or in a list of behaviors like any other: `[Chat, handlers, fsm(states), defineType<DebateEntity, AppApi>()({ ...template, render })]`.
+
+**7. Test your handlers**
 
 ```typescript
 import { trigger } from "@inglorious/store/test"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "12.2.0",
+  "version": "12.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",
@@ -78,11 +78,11 @@
     "mutative": "^1.3.0"
   },
   "peerDependencies": {
-    "@inglorious/utils": "^5.1.0"
+    "@inglorious/utils": "^5.2.0"
   },
   "devDependencies": {
     "@inglorious/eslint-config": "1.2.0",
-    "@inglorious/utils": "5.1.0",
+    "@inglorious/utils": "5.2.0",
     "@reduxjs/toolkit": "^2.12.0",
     "prettier": "^3.9.6",
     "typescript": "~7.0.2",

package/src/store.js

@@ -515,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,7 +40,7 @@ export interface Api<
   }
   select: <TResult>(selector: (state: TState) => TResult) => TResult
   dispatch: (event: Event) => void
-  notify: (type: string, payload?: any) => void
+  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/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/store.d.ts

@@ -1,4 +1,5 @@
 import type { Api } from "./api"
+import type { AnyEvents, Notify } from "./events"
 
 /**
  * What every entity has. Declare an entity's other fields on its own interface:
@@ -111,6 +112,68 @@ export type TypeDefinition<
  */
 export type AnyTypeDefinition = TypeDefinition<never, never>
 
+/**
+ * What each member of a type must be, told by its name: `render(props, api)`
+ * draws the type, and a type's props are its entity; any other `render…` is
+ * a sub-renderer, `renderX(props, ownProps, api)`, which keeps the types it
+ * declares; every other member handles an event.
+ */
+export type CheckedType<
+  TType,
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api = Api,
+> = {
+  [K in keyof TType]: K extends "render"
+    ? Renderer<TEntity, TApi>
+    : K extends `render${string}`
+      ? TType[K]
+      : EventHandler<TEntity, TApi>
+}
+
+/**
+ * For TypeScript only. At runtime it hands back the behavior it is given, and
+ * JavaScript apps never need it: it exists so that TypeScript can check a
+ * behavior that a plain annotation cannot describe, the same trick as Vue's
+ * `defineComponent` or Vite's `defineConfig`.
+ *
+ * Why it is needed: an annotation such as `EntityType<ScoreboardEntity, AppApi>`
+ * checks every member as an event handler, `(entity, payload, api)`. That is
+ * wrong for a template's sub-renderers, `renderX(props, ownProps, api)`,
+ * whose first parameter is the component's props rather than the entity, so
+ * the annotation rejects them. TypeScript cannot exempt members by their name
+ * in an annotation; it can only check them one by one after inferring the
+ * object, which takes a generic function. This is that function.
+ *
+ * What it checks, member by member: `render(props, api)` takes the entity as
+ * its props; any other `render…` keeps the types it declares; every other
+ * member is an event handler, whose entity and api are inferred. Inside its
+ * methods, `this` is the behavior itself.
+ *
+ * Use it only for a behavior whose sub-renderers take props; otherwise an
+ * annotation is enough. It takes the entity and the api first, then the
+ * behavior, because TypeScript cannot infer the behavior while being told
+ * the rest:
+ *
+ * ```ts
+ * export const Scoreboard = defineType<ScoreboardEntity, AppApi>()({
+ *   ...template, // renderScoreboard(props, api), renderContender(props, speaker, api), ...
+ *   render(props, api) {
+ *     return this.renderScoreboard({ ...props, memory: readMemory(api) }, api)
+ *   },
+ * })
+ * ```
+ *
+ * The result is an `EntityType` for the entity, so it goes wherever a
+ * behavior goes: in the store's `types`, or in a list of behaviors such as
+ * `[Chat, handlers, fsm(states), defineType<DebateEntity, AppApi>()({ ... })]`.
+ */
+export function defineType<
+  TEntity extends BaseEntity,
+  TApi extends Api = Api,
+>(): <TType>(
+  behavior: CheckedType<TType, TEntity, TApi> & ThisType<TType>,
+) => EntityType<TEntity, TApi>
+
 /**
  * System definition with event handlers
  */
@@ -134,12 +197,13 @@ export type EntitiesState<TEntity extends BaseEntity = BaseEntity> = {
 export type TypesConfig<
   TEntity extends BaseEntity = BaseEntity,
   TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
+  TEvents = AnyEvents,
 > = string extends TEntity["type"]
   ? { [typeName: string]: AnyTypeDefinition }
   : {
       [TName in TEntity["type"]]?: TypeDefinition<
         Extract<TEntity, { type: TName }>,
-        Api<TEntity, TState>
+        Api<TEntity, TState, TEvents>
       >
     } & { [typeName: string]: unknown }
 
@@ -172,10 +236,11 @@ export type UpdateStrategy = "structural-sharing" | "copy-on-dispatch"
 export interface StoreConfig<
   TEntity extends BaseEntity = BaseEntity,
   TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
+  TEvents = AnyEvents,
 > {
   // The entity type comes from the type arguments, `entities` or
   // `middlewares`, never from `types`, which are checked against it.
-  types?: NoInfer<TypesConfig<TEntity, TState>>
+  types?: NoInfer<TypesConfig<TEntity, TState, TEvents>>
   /** The initial entities. With `autoCreateEntities`, those the store creates itself can be left out. */
   entities?: Partial<TState>
   systems?: System<TState>[]
@@ -201,10 +266,12 @@ export type Unsubscribe = () => void
 export interface Store<
   TEntity extends BaseEntity = BaseEntity,
   TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
+  TEvents = AnyEvents,
 > {
   subscribe: (listener: Listener) => Unsubscribe
   update: () => Event[]
-  notify: (type: string, payload?: any) => void
+  /** Sends an event; told the store's events, it checks them (see `Notify`). */
+  notify: Notify<TEvents, TEntity>
   dispatch: (event: Event) => void
   getTypes: () => Record<string, EntityType>
   getType: (typeName: string) => EntityType
@@ -218,7 +285,7 @@ export interface Store<
   }
   setState: (nextState: TState) => void
   reset: () => void
-  _api?: Api<TEntity, TState>
+  _api?: Api<TEntity, TState, TEvents>
   extras?: Record<string, any>
 }
 
@@ -248,9 +315,14 @@ export type AddEventPayload<TEntity extends BaseEntity = BaseEntity> =
 export type RemoveEventPayload = string
 
 /**
- * Creates a store to manage state and events
+ * Creates a store to manage state and events. Told the app's events as a
+ * third type argument, its `notify` and its handlers' api check them:
+ * `createStore<AppEntity, AppState, AppEvents>({ ... })`.
  */
 export function createStore<
   TEntity extends BaseEntity = BaseEntity,
   TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
->(config: StoreConfig<TEntity, TState>): Store<TEntity, TState>
+  TEvents = AnyEvents,
+>(
+  config: StoreConfig<TEntity, TState, TEvents>,
+): Store<TEntity, TState, TEvents>