@inglorious/store 11.0.4 → 11.1.0

package/README.md

@@ -1381,75 +1381,145 @@ store.dispatch({ type: "eventName", payload }) // Redux-compatible alternative
 
 ### 🧩 Type Safety
 
-Inglorious Store is written in JavaScript but comes with powerful TypeScript support out of the box, allowing for a fully type-safe experience similar to Redux Toolkit, but with less boilerplate.
+Inglorious Store is written in JavaScript but comes with TypeScript types that check your whole app with no casts: each type against its entity, each handler's parameters, and every entity read through the api.
 
-You can achieve strong type safety by defining an interface for your `types` configuration. This allows you to statically define the shape of your entity handlers, ensuring that all required handlers are present and correctly typed.
+**1. Describe your entities and state**
 
-Here’s how you can set it up for a TodoMVC-style application:
+```typescript
+// types/index.d.ts
+import type {
+  Api,
+  BaseEntity,
+  EntitiesState,
+  EntityType,
+} from "@inglorious/store"
+
+export interface CounterEntity extends BaseEntity {
+  type: "Counter"
+  value: number
+}
+
+export interface LabelEntity extends BaseEntity {
+  type: "Label"
+  text: string
+}
+
+export type AppEntity = CounterEntity | LabelEntity
+
+// The entities by id
+export interface AppState extends EntitiesState<AppEntity> {
+  counter: CounterEntity
+  label: LabelEntity
+}
+
+export type AppApi = Api<AppEntity, AppState>
+
+// A type for one of the app's entities
+export type AppType<TEntity extends AppEntity> = EntityType<TEntity, AppApi>
+```
 
-**1. Define Your Types**
+Every field of an entity is declared, so a misspelled one is an error. The store gives each entity its key in the state as `id`: leave it out of the initial entities, and handlers receive it as a `string`. With `@inglorious/web`, import `Api` from there instead: it is the same type, with `render`.
 
-First, create an interface that describes your entire `types` configuration. This interface will enforce the structure of your event handlers.
+**2. Write your types**
+
+Declare each type's events and their payloads, then write the type against that declaration:
 
 ```typescript
-// src/store/types.ts
-import type {
-  FormEntity,
-  ListEntity,
-  FooterEntity,
-  // ... other payload types
-} from "../../types"
-
-// Define the static shape of the types configuration
-interface TodoListTypes {
-  form: {
-    inputChange: (entity: FormEntity, value: string) => void
-    formSubmit: (entity: FormEntity) => void
-  }
-  list: {
-    formSubmit: (entity: ListEntity, value: string) => void
-    toggleClick: (entity: ListEntity, id: number) => void
-    // ... other handlers
-  }
-  footer: {
-    filterClick: (entity: FooterEntity, id: string) => void
-  }
+// types/index.d.ts
+export type CounterType = {
+  increment: (entity: CounterEntity) => void
+  add: (entity: CounterEntity, amount: number) => void
+  copyLabel: (entity: CounterEntity, payload: void, api: AppApi) => void
 }
+```
 
-export const types: TodoListTypes = {
-  form: {
-    inputChange(entity, value) {
-      entity.value = value
-    },
-    formSubmit(entity) {
-      entity.value = ""
-    },
+```typescript
+// src/store/counter.ts
+import type { CounterType } from "../../types"
+
+export const Counter: CounterType = {
+  increment(entity) {
+    entity.value++
+  },
+
+  add(entity, amount) {
+    entity.value += amount
+  },
+
+  copyLabel(entity, _payload, api) {
+    entity.value = api.getEntity("label")?.text.length ?? 0
   },
-  // ... other type implementations
 }
 ```
 
-With `TodoListTypes`, TypeScript will throw an error if you forget a handler (e.g., `formSubmit`) or if its signature is incorrect.
+The parameters are inferred from `CounterType`, and TypeScript checks the type against it: a misspelled or missing handler is an error, and so is `Counter.add(counter, "2")`. Declare it with `type`, not `interface`: an interface does not fit the store's `types`.
 
-**2. Create the Store**
+For less rigour with less to write, skip the declaration and use the shorthand, `satisfies`. It still infers the entity and the api, but it neither lists the events nor types a payload you do not annotate:
 
-When creating your store, you'll pass the `types` object. To satisfy the store's generic `TypesConfig`, you may need to use a double cast (`as unknown as`). This is a safe and intentional way to bridge your specific, statically-checked configuration with the store's more generic type.
+```typescript
+export const Counter = {
+  increment(entity) {
+    entity.value++
+  },
+  add(entity, amount: number) {
+    entity.value += amount
+  },
+} satisfies AppType<CounterEntity>
+```
+
+**3. Create the store**
 
 ```typescript
 // src/store/index.ts
-import { createStore, type TypesConfig } from "@inglorious/store"
-import { types } from "./types"
-import type { TodoListEntity, TodoListState } from "../../types"
+import { createStore } from "@inglorious/store"
 
-export const store = createStore<TodoListEntity, TodoListState>({
-  types: types as unknown as TypesConfig<TodoListEntity>,
-  // ... other store config
+import type { AppEntity, AppState } from "../../types"
+import { Counter } from "./counter"
+import { Label } from "./label"
+
+export const store = createStore<AppEntity, AppState>({
+  types: { Counter, Label },
+  entities: {
+    counter: { type: "Counter", value: 0 },
+    label: { type: "Label", text: "Hello" },
+  },
 })
 ```
 
-**3. Enjoy Full Type Safety**
+Each type is checked against the entities of its name: `Counter` against `CounterEntity`. A name no entity has, such as a page rendered by name, takes any type. Behaviors type the same way: `Live: [Chart, withRealtime]`.
+
+**4. Use types from libraries**
+
+An entity drawn by a library type extends that type's entity interface:
+
+```typescript
+import type { ChartEntity } from "@inglorious/charts"
+import type { RouterEntity } from "@inglorious/web/router"
+
+interface AppRouterEntity extends RouterEntity {
+  type: "Router"
+}
+
+interface SalesEntity extends ChartEntity {
+  type: "Sales"
+}
+
+// types: { Router, Sales: Chart }
+```
+
+**5. Test your handlers**
+
+```typescript
+import { trigger } from "@inglorious/store/test"
+
+const { entity, events } = trigger(counter, Counter.add, 2)
+```
+
+`trigger` checks the payload against the handler, and returns the updated entity, typed.
+
+**Upgrading from casts**
 
-Now, your store is fully type-safe. The hooks provided by `@inglorious/react-store` will also be correctly typed.
+Older apps passed `types` as `types as unknown as TypesConfig<AppEntity>` and described each type with an interface. Drop the cast, turn each `interface CounterType {` into `type CounterType = {`, and declare every entity field, which `BaseEntity` no longer allows by default. An entity that extended `BaseEntity, Omit<RouterEntity, "id">` now just extends `RouterEntity`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "11.0.4",
+  "version": "11.1.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",
@@ -62,9 +62,10 @@
     "@inglorious/utils": "5.0.0"
   },
   "devDependencies": {
-    "@inglorious/eslint-config": "1.1.2",
+    "@inglorious/eslint-config": "1.1.4",
     "@reduxjs/toolkit": "^2.12.0",
     "prettier": "^3.9.6",
+    "typescript": "~7.0.2",
     "vite": "^8.2.2",
     "vitest": "^5.0.0"
   },
@@ -75,6 +76,7 @@
     "format": "prettier --write .",
     "lint": "eslint .",
     "test:watch": "vitest",
-    "test": "vitest run"
+    "test": "vitest run && tsc -p type-tests",
+    "test:types": "tsc -p type-tests"
   }
 }

package/src/test.js

@@ -130,7 +130,7 @@ export function createMockApi(entities) {
  * expect(entity.value).toBe(10)
  */
 export function trigger(entity, eventHandler, eventPayload, api) {
-  api ??= createMockApi({ entities: { [entity.id]: entity } })
+  api ??= createMockApi({ [entity.id]: entity })
 
   return {
     entity: create(entity, (draft) => {

package/types/api.d.ts

@@ -1,30 +1,37 @@
 import type {
+  AnyTypeDefinition,
   BaseEntity,
   EntitiesState,
   EntityType,
   Event,
   Store,
-  TypesConfig,
+  Stored,
 } from "./store"
 
 /**
- * API object exposed to handlers
+ * API object exposed to handlers.
+ *
+ * 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.
  */
 export interface Api<
   TEntity extends BaseEntity = BaseEntity,
   TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
 > {
-  getTypes: () => TypesConfig<TEntity>
-  getType: (typeName: string) => EntityType<TEntity>
-  setType: (typeName: string, type: EntityType<TEntity>) => void
+  getTypes: () => Record<string, EntityType>
+  getType: (typeName: string) => EntityType
+  setType: (typeName: string, type: AnyTypeDefinition) => void
   getEntities: {
     (): TState
-    (typeName: string): TEntity[]
+    (typeName: string): Stored<TEntity>[]
   }
   /** A known id gives that entity's own type; any other id, the union. */
   getEntity: {
-    <TId extends keyof TState & string>(id: TId): TState[TId] | undefined
-    (id: string): TEntity | undefined
+    <TId extends keyof TState & string>(
+      id: TId,
+    ): Stored<TState[TId]> | undefined
+    (id: string): Stored<TEntity> | undefined
   }
   select: <TResult>(selector: (state: TState) => TResult) => TResult
   dispatch: (event: Event) => void

package/types/select.d.ts

@@ -12,9 +12,36 @@ export type OutputSelector<TState = any, TResult = any> = (
   state: TState,
 ) => TResult
 
+/** Any input selector, whatever state it reads. */
+type AnySelector = (state: never) => unknown
+
+/** What the input selectors return, in order: the result function's arguments. */
+type SelectedValues<TSelectors extends readonly AnySelector[]> = {
+  [K in keyof TSelectors]: ReturnType<TSelectors[K]>
+}
+
+/** The state every input selector can read: the intersection of theirs. */
+type SelectorsState<TSelectors extends readonly AnySelector[]> =
+  UnionToIntersection<Parameters<TSelectors[number]>[0]>
+
+type UnionToIntersection<TUnion> = (
+  TUnion extends unknown ? (value: TUnion) => void : never
+) extends (value: infer TIntersection) => void
+  ? TIntersection
+  : never
+
 /**
- * Creates a memoized derived computation from input selectors.
+ * Creates a memoized derived computation from input selectors. Everything is
+ * inferred: the result function's arguments, and the state the selector reads.
  */
+export function compute<
+  const TSelectors extends readonly AnySelector[],
+  TResult,
+>(
+  resultFunc: (...args: SelectedValues<TSelectors>) => TResult,
+  inputSelectors: TSelectors,
+): OutputSelector<SelectorsState<TSelectors>, TResult>
+/** With explicit type arguments: the state, the selected values and the result. */
 export function compute<TState, TInputs extends readonly unknown[], TResult>(
   resultFunc: (...args: TInputs) => TResult,
   inputSelectors: {
@@ -26,6 +53,14 @@ export function compute<TState, TInputs extends readonly unknown[], TResult>(
  * Redux-compatible alias for `compute`.
  * Prefer `compute` in new code.
  */
+export function createSelector<
+  const TSelectors extends readonly AnySelector[],
+  TResult,
+>(
+  inputSelectors: TSelectors,
+  resultFunc: (...args: SelectedValues<TSelectors>) => TResult,
+): OutputSelector<SelectorsState<TSelectors>, TResult>
+/** With explicit type arguments: the state, the selected values and the result. */
 export function createSelector<
   TState,
   TInputs extends readonly unknown[],

package/types/store.d.ts

@@ -1,13 +1,33 @@
 import type { Api } from "./api"
 
 /**
- * Base entity structure
+ * What every entity has. Declare an entity's other fields on its own interface:
+ *
+ * ```ts
+ * interface CounterEntity extends BaseEntity {
+ *   type: "Counter"
+ *   value: number
+ * }
+ * ```
+ *
+ * The store gives each entity its key in the state as `id`, so it can be left
+ * out of the initial entities; handlers always receive it (see `Stored`).
  */
 export interface BaseEntity {
   type: string
-  [key: string]: any
+  id?: string
+  /**
+   * Opts the entity out of a pause: the store stops handing out `update`
+   * events while the world is halted, and an entity that says this keeps
+   * receiving them. It is for overlays and menus; anything that moves should
+   * leave it off so that it stops.
+   */
+  updatesWhilePaused?: boolean
 }
 
+/** An entity as the store holds it, and as handlers receive it: with its id. */
+export type Stored<TEntity extends BaseEntity> = TEntity & { id: string }
+
 /**
  * Event structure
  */
@@ -17,17 +37,80 @@ export interface Event<T = any> {
 }
 
 /**
- * Entity type definition with event handlers.
+ * An event handler: it receives the entity, the event's payload and the api.
+ */
+export type EventHandler<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api<any, any> = Api,
+> = (entity: Stored<TEntity>, payload: any, api: TApi) => unknown
+
+/**
+ * Any type for one kind of entity: its event handlers, by event name, and its
+ * `render`. The store checks `types` against it.
  *
- * `updatesWhilePaused` opts the type out of a pause: the store stops handing out
- * `update` events while the world is halted, and a type that says this keeps
- * receiving them. It is for overlays and menus; anything that moves should leave it
- * off so that it stops.
+ * For rigour, declare a type's events and payloads with a `type` alias (an
+ * interface does not fit `types`) and write the type against it:
+ *
+ * ```ts
+ * type CounterType = {
+ *   add: (entity: CounterEntity, amount: number) => void
+ * }
+ * const Counter: CounterType = {
+ *   add(entity, amount) {
+ *     entity.value += amount
+ *   },
+ * }
+ * ```
+ *
+ * As a shorthand, `satisfies` infers the entity and the api without the
+ * declaration, but neither lists the events nor types unannotated payloads:
+ *
+ * ```ts
+ * const Counter = {
+ *   add(entity, amount: number) {
+ *     entity.value += amount
+ *   },
+ * } satisfies EntityType<CounterEntity, AppApi>
+ * ```
  */
-export type EntityType<TEntity extends BaseEntity = BaseEntity> = {
-  [K: string]: (entity: TEntity, payload: any, api: Api) => void
+export type EntityType<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api<any, any> = Api,
+> = {
+  /** Draws the entity. Unlike an event handler, it receives the api second. */
+  render?: Renderer<TEntity, TApi>
+  [member: string]: EventHandler<TEntity, TApi> | undefined
 }
 
+/** A type's `render`: it receives the entity and the api. */
+export type Renderer<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api<any, any> = Api,
+> = (entity: Stored<TEntity>, api: TApi) => unknown
+
+/**
+ * A behavior: a type, or a function that extends the type it is given. A type
+ * can also be an array of behaviors, applied in order: `[Chart, withRealtime]`.
+ */
+export type Behavior<
+  TEntity extends BaseEntity = BaseEntity,
+  TApi extends Api<any, any> = Api,
+> =
+  | EntityType<TEntity, TApi>
+  | ((type: EntityType<TEntity, TApi>) => EntityType<TEntity, TApi>)
+
+/** 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,
+> = Behavior<TEntity, TApi> | Behavior<TEntity, TApi>[]
+
+/**
+ * A type definition for any entity. A handler that accepts some entity also
+ * accepts `never`, so every type fits here, whatever entity it is for.
+ */
+export type AnyTypeDefinition = TypeDefinition<never, never>
+
 /**
  * System definition with event handlers
  */
@@ -43,11 +126,23 @@ export type EntitiesState<TEntity extends BaseEntity = BaseEntity> = {
 }
 
 /**
- * Types configuration
+ * The store's `types`. In a typed store, each entity's type name takes a type
+ * for that entity, so `types: { Counter }` checks `Counter` against
+ * `CounterEntity`. Names no entity has, such as a page rendered by name, take
+ * any type.
  */
-export type TypesConfig<TEntity extends BaseEntity = BaseEntity> = {
-  [typeName: string]: EntityType<TEntity>
-}
+export type TypesConfig<
+  TEntity extends BaseEntity = BaseEntity,
+  TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
+> = string extends TEntity["type"]
+  ? { [typeName: string]: AnyTypeDefinition }
+  : {
+      [TName in TEntity["type"]]?: TypeDefinition<
+        Extract<TEntity, { type: TName }>,
+        Api<TEntity, TState>
+      >
+    } & { [typeName: string]: unknown }
+
 /**
  * Whether each event triggers an update, or updates are batched until `update()` is called.
  */
@@ -78,7 +173,9 @@ export interface StoreConfig<
   TEntity extends BaseEntity = BaseEntity,
   TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
 > {
-  types?: TypesConfig<TEntity>
+  // The entity type comes from the type arguments, `entities` or
+  // `middlewares`, never from `types`, which are checked against it.
+  types?: NoInfer<TypesConfig<TEntity, TState>>
   /** The initial entities. With `autoCreateEntities`, those the store creates itself can be left out. */
   entities?: Partial<TState>
   systems?: System<TState>[]
@@ -109,13 +206,15 @@ export interface Store<
   update: () => Event[]
   notify: (type: string, payload?: any) => void
   dispatch: (event: Event) => void
-  getTypes: () => TypesConfig<TEntity>
-  getType: (typeName: string) => EntityType<TEntity>
-  setType: (typeName: string, type: EntityType<TEntity>) => void
+  getTypes: () => Record<string, EntityType>
+  getType: (typeName: string) => EntityType
+  setType: (typeName: string, type: AnyTypeDefinition) => void
   getState: () => TState
   getEntity: {
-    <TId extends keyof TState & string>(id: TId): TState[TId] | undefined
-    (id: string): TState[string] | undefined
+    <TId extends keyof TState & string>(
+      id: TId,
+    ): Stored<TState[TId]> | undefined
+    (id: string): Stored<TEntity> | undefined
   }
   setState: (nextState: TState) => void
   reset: () => void

package/types/test.d.ts

@@ -1,4 +1,4 @@
-import type { BaseEntity, EntitiesState } from "./store"
+import type { BaseEntity, EntitiesState, Event, Stored } from "./store"
 
 /**
  * Mock API for testing (subset of full API)
@@ -9,28 +9,33 @@ export interface MockApi<
 > {
   getEntities: {
     (): TState
-    (typeName: string): TEntity[]
+    (typeName: string): Stored<TEntity>[]
   }
+  /** A known id gives that entity's own type; any other id, the union. */
   getEntity: {
-    <TId extends keyof TState & string>(id: TId): TState[TId] | undefined
-    (id: string): TEntity | undefined
+    <TId extends keyof TState & string>(
+      id: TId,
+    ): Stored<TState[TId]> | undefined
+    (id: string): Stored<TEntity> | undefined
   }
   select: <TResult>(selector: (state: TState) => TResult) => TResult
   dispatch: (event: Event) => void
   notify: (type: string, payload?: any) => void
+  /** The events dispatched so far. */
   getEvents: () => Event[]
 }
 
 /**
- * Result of trigger function
+ * Result of trigger function: the entity after the handler ran, and the
+ * events it dispatched.
  */
-export interface TriggerResult<TState extends EntitiesState = EntitiesState> {
-  entities: TState
+export interface TriggerResult<TEntity extends BaseEntity = BaseEntity> {
+  entity: TEntity
   events: Event[]
 }
 
 /**
- * Creates a mock API for testing event handlers
+ * Creates a mock API for testing event handlers, over the given entities.
  */
 export function createMockApi<
   TEntity extends BaseEntity = BaseEntity,
@@ -38,19 +43,24 @@ export function createMockApi<
 >(entities: TState): MockApi<TEntity, TState>
 
 /**
- * Triggers an event handler in isolation for testing
+ * Runs an event handler on a copy of an entity, as the store would, and
+ * returns the updated copy with the events it dispatched. Without an api, the
+ * handler gets a mock one holding just this entity.
+ *
+ * Any type's handler fits, whatever api it is typed with: it receives a
+ * `MockApi`, which covers reading entities and dispatching events.
+ *
+ * ```ts
+ * const { entity, events } = trigger(counter, Counter.increment, 5)
+ * ```
  */
-export function trigger<
-  TEntity extends BaseEntity = BaseEntity,
-  TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
-  TPayload = any,
->(
-  entities: TState,
+export function trigger<TEntity extends BaseEntity, TPayload = any>(
+  entity: TEntity,
   eventHandler: (
-    state: TState,
+    entity: Stored<TEntity>,
     payload: TPayload,
-    api: MockApi<TEntity, TState>,
-  ) => void,
-  eventPayload: TPayload,
-  api?: MockApi<TEntity, TState>,
-): TriggerResult<TState>
+    api: never,
+  ) => unknown,
+  eventPayload?: TPayload,
+  api?: MockApi,
+): TriggerResult<TEntity>