@inglorious/store 6.1.2 → 6.2.0

package/README.md

@@ -480,6 +480,74 @@ Notice: you don't need pending/fulfilled/rejected actions. You stay in control o
 
 All events triggered via `api.notify()` enter the queue and process together, maintaining predictability and testability.
 
+### 🧪 Testing
+
+Event handlers are pure functions (or can be treated as such), making them easy to test in isolation, much like Redux reducers. The `@inglorious/store/test` module provides utility functions to make this even simpler.
+
+#### `trigger(entity, handler, payload, api?)`
+
+The `trigger` function executes an event handler on a single entity and returns the new state and any events that were dispatched.
+
+```javascript
+import { trigger } from "@inglorious/store/test"
+
+// Define your entity handler
+function increment(entity, payload, api) {
+  entity.value += payload.amount
+  if (entity.value > 100) {
+    api.notify("overflow", { id: entity.id })
+  }
+}
+
+// Test it
+const { entity, events } = trigger(
+  { type: "counter", id: "counter1", value: 99 },
+  increment,
+  { amount: 5 },
+)
+
+expect(entity.value).toBe(104)
+expect(events).toEqual([{ type: "overflow", payload: { id: "counter1" } }])
+```
+
+#### `createMockApi(entities)`
+
+If your handler needs to interact with other entities via the `api`, you can create a mock API. This is useful for testing handlers that read from other parts of the state.
+
+```javascript
+import { createMockApi, trigger } from "@inglorious/store/test"
+
+// Create a mock API with some initial entities
+const api = createMockApi({
+  counter1: { type: "counter", value: 10 },
+  counter2: { type: "counter", value: 20 },
+})
+
+// A handler that copies a value from another entity
+function copyValue(entity, payload, api) {
+  const source = api.getEntity(payload.sourceId)
+  entity.value = source.value
+}
+
+// Trigger the handler with the custom mock API
+const { entity } = trigger(
+  { type: "counter", id: "counter2", value: 20 },
+  copyValue,
+  { sourceId: "counter1" },
+  api,
+)
+
+expect(entity.value).toBe(10)
+```
+
+The mock API provides:
+
+- `getEntities()`: Returns all entities (frozen).
+- `getEntity(id)`: Returns a specific entity by ID (frozen).
+- `dispatch(event)`: Records an event for later assertions.
+- `notify(type, payload)`: A convenience wrapper around `dispatch`.
+- `getEvents()`: Returns all events that were dispatched.
+
 ### 🌍 Systems for Global Logic
 
 When you need to coordinate updates across multiple entities (not just respond to individual events), use systems. Systems run after all entity handlers for the same event, ensuring global consistency, and have write access to the entire state. This concept is the 'S' in the ECS Architecture (Entity-Component-System)!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "6.1.2",
+  "version": "6.2.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/test.js

@@ -0,0 +1,130 @@
+import { create } from "mutative"
+
+/**
+ * Creates a mock API for testing event handlers in isolation.
+ *
+ * The mock API provides read-only access to entities and tracks all events
+ * dispatched during handler execution. The entities are frozen to prevent
+ * accidental mutations - handlers should only mutate the draft state passed
+ * to them, not entities retrieved via `getEntity()` or `getEntities()`.
+ *
+ * @param {Object} entities - The entities state (will be frozen)
+ *
+ * @returns {Object} A mock API object with methods:
+ *   - `getEntities()`: Returns all entities (frozen)
+ *   - `getEntity(id)`: Returns a specific entity by ID (frozen)
+ *   - `dispatch(event)`: Records an event (for assertions)
+ *   - `notify(type, payload)`: Convenience method that calls dispatch
+ *   - `getEvents()`: Returns all events that were dispatched
+ *
+ * @example
+ * const api = createMockApi({
+ *   counter1: { type: 'counter', value: 0 }
+ * })
+ *
+ * // In your handler
+ * const entity = api.getEntity('counter1')
+ * api.notify('increment', { id: 'counter1' })
+ *
+ * // In your test
+ * expect(api.getEvents()).toEqual([
+ *   { type: 'increment', payload: { id: 'counter1' } }
+ * ])
+ */
+export function createMockApi(entities) {
+  const frozenEntities = Object.freeze(entities)
+  const events = []
+
+  return {
+    getEntities() {
+      return frozenEntities
+    },
+    getEntity(id) {
+      return frozenEntities[id]
+    },
+    dispatch(event) {
+      events.push(event)
+    },
+    notify(type, payload) {
+      this.dispatch({ type, payload })
+    },
+    getEvents() {
+      return events
+    },
+  }
+}
+
+/**
+ * Triggers an event handler on a single entity for testing purposes.
+ *
+ * This function executes an event handler on a single entity with the given
+ * payload, using Mutative to provide a mutable draft. The handler can read
+ * other entities via the API (frozen, immutable) and mutate the draft entity.
+ * All events dispatched during execution are captured and returned.
+ *
+ * Use this for unit testing individual entity handlers. For integration testing
+ * of event cascades and the full event queue, use the actual store.
+ *
+ * @param {Object} entity - The entity to operate on
+ * @param {Function} eventHandler - The handler function to test. Should accept
+ *   (draft, payload, api) where draft is the mutable entity
+ * @param {*} eventPayload - The payload to pass to the handler
+ * @param {Object} [api] - Optional custom mock API. If not provided, a default
+ *   mock API will be created automatically with the entity as the only entity
+ *
+ * @returns {Object} An object containing:
+ *   - `entity`: The new immutable entity after the handler executed
+ *   - `events`: Array of all events dispatched during handler execution
+ *
+ * @example
+ * // Define your entity handler
+ * const increment = (entity, payload, api) => {
+ *   entity.value += payload.amount
+ *   if (entity.value > 100) {
+ *     api.notify('overflow', { id: entity.id })
+ *   }
+ * }
+ *
+ * // Test it
+ * const { entity, events } = trigger(
+ *   { type: 'counter', id: 'counter1', value: 99 },
+ *   increment,
+ *   { amount: 5 }
+ * )
+ *
+ * expect(entity.value).toBe(104)
+ * expect(events).toEqual([
+ *   { type: 'overflow', payload: { id: 'counter1' } }
+ * ])
+ *
+ * @example
+ * // With custom mock API to access other entities
+ * const api = createMockApi({
+ *   counter1: { type: 'counter', value: 10 },
+ *   counter2: { type: 'counter', value: 20 }
+ * })
+ *
+ * const copyValue = (entity, payload, api) => {
+ *   const source = api.getEntity(payload.sourceId)
+ *   entity.value = source.value
+ * }
+ *
+ * const { entity } = trigger(
+ *   { type: 'counter', id: 'counter2', value: 20 },
+ *   copyValue,
+ *   { sourceId: 'counter1' },
+ *   api
+ * )
+ *
+ * expect(entity.value).toBe(10)
+ */
+export function trigger(entity, eventHandler, eventPayload, api) {
+  api ??= createMockApi({ entities: { [entity.id]: entity } })
+
+  return {
+    entity: create(entity, (draft) => {
+      eventHandler(draft, eventPayload, api)
+    }),
+    events: api.getEvents(),
+  }
+}

package/src/test.test.js

@@ -0,0 +1,272 @@
+import { describe, expect, it } from "vitest"
+
+import { createMockApi, trigger } from "./test"
+
+describe("createMockApi", () => {
+  it("should create a mock API with all required methods", () => {
+    const entities = { counter1: { type: "counter", value: 0 } }
+
+    const api = createMockApi(entities)
+
+    expect(api.getEntities).toBeDefined()
+    expect(api.getEntity).toBeDefined()
+    expect(api.dispatch).toBeDefined()
+    expect(api.notify).toBeDefined()
+    expect(api.getEvents).toBeDefined()
+  })
+
+  it("should return all entities via getEntities()", () => {
+    const entities = {
+      counter1: { type: "counter", value: 5 },
+      counter2: { type: "counter", value: 10 },
+    }
+
+    const api = createMockApi(entities)
+
+    expect(api.getEntities()).toEqual(entities)
+  })
+
+  it("should return a specific entity via getEntity()", () => {
+    const entities = {
+      counter1: { type: "counter", value: 5 },
+      counter2: { type: "counter", value: 10 },
+    }
+
+    const api = createMockApi(entities)
+
+    expect(api.getEntity("counter1")).toEqual({ type: "counter", value: 5 })
+    expect(api.getEntity("counter2")).toEqual({ type: "counter", value: 10 })
+  })
+
+  it("should return undefined for non-existent entity", () => {
+    const entities = {
+      counter1: { type: "counter", value: 5 },
+    }
+
+    const api = createMockApi(entities)
+
+    expect(api.getEntity("nonexistent")).toBeUndefined()
+  })
+
+  it("should track dispatched events", () => {
+    const entities = {
+      counter1: { type: "counter", value: 0 },
+    }
+
+    const api = createMockApi(entities)
+
+    api.dispatch({ type: "increment", payload: { id: "counter1" } })
+    api.dispatch({ type: "decrement", payload: { id: "counter1" } })
+
+    expect(api.getEvents()).toEqual([
+      { type: "increment", payload: { id: "counter1" } },
+      { type: "decrement", payload: { id: "counter1" } },
+    ])
+  })
+
+  it("should track events dispatched via notify()", () => {
+    const entities = {
+      counter1: { type: "counter", value: 0 },
+    }
+
+    const api = createMockApi(entities)
+
+    api.notify("increment", { id: "counter1", amount: 5 })
+    api.notify("overflow")
+
+    expect(api.getEvents()).toEqual([
+      { type: "increment", payload: { id: "counter1", amount: 5 } },
+      { type: "overflow", payload: undefined },
+    ])
+  })
+
+  it("should freeze entities to prevent mutations", () => {
+    const entities = {
+      counter1: { type: "counter", value: 0 },
+    }
+
+    const api = createMockApi(entities)
+    const allEntities = api.getEntities()
+
+    expect(() => {
+      allEntities.counter1 = { type: "counter", value: 999 }
+    }).toThrow()
+  })
+
+  it("should start with empty events array", () => {
+    const entities = {
+      counter1: { type: "counter", value: 0 },
+    }
+
+    const api = createMockApi(entities)
+
+    expect(api.getEvents()).toEqual([])
+  })
+})
+
+describe("trigger", () => {
+  it("should execute handler and return new entity", () => {
+    const entityBefore = { type: "counter", value: 0 }
+    const entityAfter = { type: "counter", value: 5 }
+
+    function increment(entity, amount) {
+      entity.value += amount
+    }
+
+    const { entity } = trigger(entityBefore, increment, 5)
+
+    expect(entity).toStrictEqual(entityAfter)
+  })
+
+  it("should not mutate original entity", () => {
+    const entityBefore = { type: "counter", value: 0 }
+
+    function increment(entity, amount) {
+      entity.value += amount
+    }
+
+    trigger(entityBefore, increment, 5)
+
+    expect(entityBefore.value).toBe(0)
+  })
+
+  it("should capture events dispatched during handler execution", () => {
+    const entityBefore = { type: "counter", value: 99 }
+    const entityAfter = { type: "counter", value: 104 }
+    const eventsAfter = [{ type: "overflow", payload: 104 }]
+
+    function increment(entity, amount, api) {
+      entity.value += amount
+
+      if (entity.value > 100) {
+        api.notify("overflow", entity.value)
+      }
+    }
+
+    const { entity, events } = trigger(entityBefore, increment, 5)
+
+    expect(entity).toStrictEqual(entityAfter)
+    expect(events).toStrictEqual(eventsAfter)
+  })
+
+  it("should work with handlers that do not dispatch events", () => {
+    const entityBefore = { type: "todo", text: "Buy milk", completed: false }
+    const entityAfter = { type: "todo", text: "Buy milk", completed: true }
+    const eventsAfter = []
+
+    function toggle(entity) {
+      entity.completed = !entity.completed
+    }
+
+    const { entity, events } = trigger(entityBefore, toggle)
+
+    expect(entity).toStrictEqual(entityAfter)
+    expect(events).toStrictEqual(eventsAfter)
+  })
+
+  it("should allow handler to read other entities via API", () => {
+    const entityBefore = { id: "counter2", type: "counter", value: 20 }
+    const entityAfter = { id: "counter2", type: "counter", value: 30 }
+
+    const mockApi = createMockApi({
+      counter1: { id: "counter1", type: "counter", value: 10 },
+      counter2: { id: "counter2", type: "counter", value: 20 },
+    })
+
+    function addFromSource(entity, sourceId, api) {
+      const source = api.getEntity(sourceId)
+      if (source) {
+        entity.value += source.value
+      }
+    }
+
+    const { entity } = trigger(entityBefore, addFromSource, "counter1", mockApi)
+
+    expect(entity).toStrictEqual(entityAfter)
+  })
+
+  it("should accept custom mock API", () => {
+    const entityBefore = { type: "counter", value: 0 }
+    const entityAfter = { type: "counter", value: 5 }
+    const eventsAfter = [{ type: "incremented", payload: undefined }]
+
+    const customApi = createMockApi(entityBefore)
+
+    function increment(entity, amount, api) {
+      entity.value += amount
+      api.notify("incremented")
+    }
+
+    const { entity } = trigger(entityBefore, increment, 5, customApi)
+
+    expect(entity).toStrictEqual(entityAfter)
+    expect(customApi.getEvents()).toStrictEqual(eventsAfter)
+  })
+
+  it("should handle multiple dispatched events", () => {
+    const entityBefore = { type: "counter", value: 50 }
+    const entityAfter = { type: "counter", value: 110 }
+    const eventsAfter = [
+      { type: "increment:start", payload: undefined },
+      { type: "milestone:hundred", payload: undefined },
+      { type: "increment:complete", payload: 110 },
+    ]
+
+    function increment(entity, amount, api) {
+      api.notify("increment:start")
+
+      entity.value += amount
+
+      if (entity.value >= 100) {
+        api.notify("milestone:hundred")
+      }
+
+      api.notify("increment:complete", entity.value)
+    }
+
+    const { entity, events } = trigger(entityBefore, increment, 60)
+
+    expect(entity).toStrictEqual(entityAfter)
+    expect(events).toStrictEqual(eventsAfter)
+  })
+
+  it("should work without payload", () => {
+    const entityBefore = { type: "counter", value: 5 }
+    const entityAfter = { type: "counter", value: 0 }
+
+    function reset(entity) {
+      entity.value = 0
+    }
+
+    const { entity } = trigger(entityBefore, reset)
+
+    expect(entity).toStrictEqual(entityAfter)
+  })
+
+  it("should work with complex entity mutations", () => {
+    const entityBefore = {
+      type: "player",
+      name: "Alice",
+      inventory: ["sword", "shield"],
+      stats: { health: 100, mana: 50 },
+    }
+    const entityAfter = {
+      type: "player",
+      name: "Alice",
+      inventory: ["sword", "shield", "potion"],
+      stats: { health: 100, mana: 50 },
+    }
+
+    function addItem(entity, item, api) {
+      entity.inventory.push(item)
+      api.notify("item:added", { item })
+    }
+
+    const { entity, events } = trigger(entityBefore, addItem, "potion")
+
+    expect(entity).toStrictEqual(entityAfter)
+    expect(events).toEqual([
+      { type: "item:added", payload: { item: "potion" } },
+    ])
+  })
+})