@inglorious/store 9.3.1 → 9.4.0

package/README.md

@@ -207,6 +207,7 @@ const types = {
     increment(counter, value, api) {
       api.getEntities() // access the whole state in read-only mode
       api.getEntity(id) // access some other entity in read-only mode
+      api.select(selector) // run a selector against the whole state
       api.notify(type, payload) // similar to dispatch. Yes, you can dispatch inside of a reducer!
       api.dispatch(action) // optional, if you prefer Redux-style dispatching
     },
@@ -491,6 +492,7 @@ Notice: you don't need pending/fulfilled/rejected actions. You stay in control o
 
 - **`api.getEntities()`** - read entire state
 - **`api.getEntity(id)`** - read one entity
+- **`api.select(selector)`** - run a selector against the state
 - **`api.notify(type, payload)`** - trigger other events (queued, not immediate)
 - **`api.dispatch(action)`** - optional, if you prefer Redux-style dispatching
 - **`api.getTypes()`** - access type definitions (mainly for middleware/plugins)
@@ -748,6 +750,7 @@ The mock API provides:
 
 - `getEntities()`: Returns all entities (frozen).
 - `getEntity(id)`: Returns a specific entity by ID (frozen).
+- `select(selector)`: Runs a selector against the entities.
 - `dispatch(event)`: Records an event for later assertions.
 - `notify(type, payload)`: A convenience wrapper around `dispatch`.
 - `getEvents()`: Returns all events that were dispatched.
@@ -880,7 +883,7 @@ const selectResult = compute(
 The returned function is a standard selector:
 
 ```js
-const result = selectResult(api.getEntities())
+const result = api.select(selectResult)
 ```
 
 And it works seamlessly with `react-redux` or `@inglorious/react-store`:
@@ -1101,6 +1104,7 @@ Each handler receives three arguments:
 - **`api`** - access to store methods:
   - `getEntities()` - entire state (read-only)
   - `getEntity(id)` - single entity (read-only)
+  - `select(selector)` - run a selector against the state
   - `notify(type, payload)` - trigger other events
   - `dispatch(action)` - optional, if you prefer Redux-style dispatching
   - `getTypes()` - type definitions (for middleware)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "9.3.1",
+  "version": "9.4.0",
   "description": "A state manager for real-time, collaborative apps, inspired by game development patterns and compatible with Redux.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",

package/src/api.js

@@ -1,11 +1,54 @@
 export function createApi(store, extras) {
   return {
+    /**
+     * Retrieves all registered type definitions.
+     * @returns {Object}
+     */
     getTypes: store.getTypes,
+    /**
+     * Retrieves a specific type definition by name.
+     * @param {string} typeName
+     * @returns {Object}
+     */
     getType: store.getType,
+    /**
+     * Replaces a type definition at runtime.
+     * @param {string} typeName
+     * @param {Object} type
+     * @returns {void}
+     */
     setType: store.setType,
+    /**
+     * Retrieves the full entities state.
+     * @returns {Object}
+     */
     getEntities: store.getState,
+    /**
+     * Retrieves a single entity by ID.
+     * @param {string} id
+     * @returns {Object | undefined}
+     */
     getEntity: (id) => store.getState()[id],
+    /**
+     * Runs a selector against the current state.
+     *
+     * @template TResult
+     * @param {(state: object) => TResult} selector
+     * @returns {TResult}
+     */
+    select: (selector) => selector(store.getState()),
+    /**
+     * Dispatches an event object to the store.
+     * @param {{ type: string, payload?: any }} event
+     * @returns {void}
+     */
     dispatch: store.dispatch,
+    /**
+     * Notifies the store of an event type and optional payload.
+     * @param {string} type
+     * @param {any} [payload]
+     * @returns {void}
+     */
     notify: store.notify,
     ...extras,
   }

package/src/test.js

@@ -13,6 +13,7 @@ import { create } from "mutative"
  * @returns {Object} A mock API object with methods:
  *   - `getEntities()`: Returns all entities (frozen)
  *   - `getEntity(id)`: Returns a specific entity by ID (frozen)
+ *   - `select(selector)`: Runs a selector against the entities
  *   - `dispatch(event)`: Records an event (for assertions)
  *   - `notify(type, payload)`: Convenience method that calls dispatch
  *   - `getEvents()`: Returns all events that were dispatched
@@ -42,6 +43,9 @@ export function createMockApi(entities) {
     getEntity(id) {
       return frozenEntities[id]
     },
+    select(selector) {
+      return selector(frozenEntities)
+    },
     dispatch(event) {
       events.push(event)
     },

package/types/api.d.ts

@@ -0,0 +1,37 @@
+import type {
+  BaseEntity,
+  EntitiesState,
+  EntityType,
+  Event,
+  Store,
+  TypesConfig,
+} from "./store"
+
+/**
+ * API object exposed to handlers
+ */
+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
+  getEntities: () => TState
+  getEntity: (id: string) => TEntity | undefined
+  select: <TResult>(selector: (state: TState) => TResult) => TResult
+  dispatch: (event: Event) => void
+  notify: (type: string, payload?: any) => void
+  [key: string]: any // For middleware extras
+}
+
+/**
+ * Creates an API object
+ */
+export function createApi<
+  TEntity extends BaseEntity = BaseEntity,
+  TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
+>(
+  store: Store<TEntity, TState>,
+  extras?: Record<string, any>,
+): Api<TEntity, TState>

package/types/async.d.ts

@@ -1,4 +1,5 @@
-import { Api, BaseEntity } from "./store"
+import { Api } from "./api"
+import { BaseEntity } from "./store"
 
 /**
  * Scope option for async handler events

package/types/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./api"
 export * from "./async"
 export * from "./select"
 export * from "./store"

package/types/store.d.ts

@@ -1,3 +1,5 @@
+import type { Api } from "./api"
+
 /**
  * Base entity structure
  */
@@ -67,23 +69,6 @@ export type Listener = () => void
  */
 export type Unsubscribe = () => void
 
-/**
- * API object exposed to handlers
- */
-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
-  getEntities: () => TState
-  getEntity: (id: string) => TEntity | undefined
-  dispatch: (event: Event) => void
-  notify: (type: string, payload?: any) => void
-  [key: string]: any // For middleware extras
-}
-
 /**
  * Base store interface
  */
@@ -135,26 +120,3 @@ export function createStore<
   TEntity extends BaseEntity = BaseEntity,
   TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
 >(config: StoreConfig<TEntity, TState>): Store<TEntity, TState>
-
-/**
- * Creates an API object
- */
-export function createApi<
-  TEntity extends BaseEntity = BaseEntity,
-  TState extends EntitiesState<TEntity> = EntitiesState<TEntity>,
->(
-  store: Store<TEntity, TState>,
-  extras?: Record<string, any>,
-): Api<TEntity, TState>
-
-/**
- * Helper to create a set of handlers for an async operation
- */
-export function handleAsync<
-  TEntity extends BaseEntity = BaseEntity,
-  TPayload = any,
-  TResult = any,
->(
-  type: string,
-  handlers: AsyncHandlers<TEntity, TPayload, TResult>,
-): EntityType<TEntity>

package/types/test.d.ts

@@ -1,3 +1,5 @@
+import type { BaseEntity, EntitiesState } from "./store"
+
 /**
  * Mock API for testing (subset of full API)
  */
@@ -7,6 +9,7 @@ export interface MockApi<
 > {
   getEntities: () => TState
   getEntity: (id: string) => TEntity | undefined
+  select: <TResult>(selector: (state: TState) => TResult) => TResult
   dispatch: (event: Event) => void
   notify: (type: string, payload?: any) => void
   getEvents: () => Event[]