@inglorious/store 11.1.0 → 11.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "11.1.0",
+  "version": "11.2.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",

package/src/optimistic.js

@@ -11,12 +11,13 @@ const START = 0
  * @template {import('./store').BaseEntity} TEntity
  * @template TPayload
  * @template TResult
+ * @template {string} TType
  *
- * @param {import('./async').AsyncEventHandlers<TEntity, TPayload, TResult>} behavior
+ * @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/types/async.d.ts

@@ -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

@@ -1,5 +1,5 @@
 import { Api } from "./api"
-import { AsyncEventHandlers } from "./async"
+import { AsyncEvents } from "./async"
 import { BaseEntity } from "./store"
 
 /**
@@ -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/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>[]
 
 /**