@inglorious/store 9.6.0 → 11.0.0

package/README.md

@@ -118,8 +118,8 @@ const types = {
 
 // Define initial entities
 const entities = {
-  work: { type: "todoList", todos: [] },
-  personal: { type: "todoList", todos: [] },
+  work: { type: "TodoList", todos: [] },
+  personal: { type: "TodoList", todos: [] },
 }
 
 // Create store
@@ -171,9 +171,9 @@ const types = {
 }
 
 const entities = {
-  workTodos: { type: "todoList", todos: [], priority: "high" },
-  personalTodos: { type: "todoList", todos: [], priority: "low" },
-  settings: { type: "settings", theme: "dark", language: "en" },
+  workTodos: { type: "TodoList", todos: [], priority: "high" },
+  personalTodos: { type: "TodoList", todos: [], priority: "low" },
+  settings: { type: "Settings", theme: "dark", language: "en" },
 }
 ```
 
@@ -241,7 +241,7 @@ const types = {
 
 // 2. Define initial entities
 const entities = {
-  counter1: { type: "counter", value: 0 },
+  counter1: { type: "Counter", value: 0 },
 }
 
 // 3. Create the store
@@ -352,12 +352,12 @@ const types = {
 }
 
 const entities = {
-  counter1: { type: "counter", value: 0 },
-  counter2: { type: "counter", value: 0 },
-  counter3: { type: "counter", value: 0 },
+  counter1: { type: "Counter", value: 0 },
+  counter2: { type: "Counter", value: 0 },
+  counter3: { type: "Counter", value: 0 },
 }
 
-store.notify("add", { id: "counter4", type: "counter", value: 0 })
+store.notify("add", { id: "counter4", type: "Counter", value: 0 })
 ```
 
 Inglorious Store has a few built-in events that you can use:
@@ -508,27 +508,39 @@ The `handleAsync` helper generates a set of event handlers representing the life
 handleAsync(type, handlers, options?)
 ```
 
+Think of the flow like a newspaper article:
+
+- `start` writes the headline and sets the scene
+- `run` gathers the reporting
+- `success` publishes the story
+- `error` prints the correction
+- `finally` archives the notes
+
 Example:
 
 ```ts
-handleAsync("fetchTodos", {
-  async run(payload) {
-    const res = await fetch("/api/todos")
-    return res.json()
-  },
+import { handleAsync } from "@inglorious/store/async"
 
-  success(entity, todos) {
-    entity.todos = todos
-  },
+const todoList = {
+  ...handleAsync("fetchTodos", {
+    async run(payload) {
+      const res = await fetch("/api/todos")
+      return res.json()
+    },
 
-  error(entity, error) {
-    entity.error = error.message
-  },
+    success(entity, todos) {
+      entity.todos = todos
+    },
 
-  finally(entity) {
-    entity.loading = false
-  },
-})
+    error(entity, error) {
+      entity.error = error.message
+    },
+
+    finally(entity) {
+      entity.loading = false
+    },
+  }),
+}
 ```
 
 ---
@@ -565,6 +577,61 @@ handleAsync("save", {
 
 If omitted, no `Start` event is generated.
 
+### `optimistic`
+
+Wrap an async behavior to apply a shallow optimistic patch on `Start` and roll it back on `Error`.
+
+This helper lives at `@inglorious/store/optimistic`, so only users who need it import it.
+
+```ts
+import { handleAsync } from "@inglorious/store/async"
+import { optimistic } from "@inglorious/store/optimistic"
+
+const saveItem = optimistic(
+  handleAsync("saveItem", {
+    async run(payload) {
+      const res = await fetch("/api/items", {
+        method: "POST",
+        body: JSON.stringify(payload),
+      })
+      if (!res.ok) throw new Error("Failed")
+      return res.json()
+    },
+    success(entity, result) {
+      entity.items = entity.items.map((item) =>
+        item.id === result.tempId ? result : item,
+      )
+    },
+  }),
+  (entity, payload) => ({
+    items: [
+      ...entity.items,
+      {
+        id: payload.tempId,
+        title: payload.title,
+        completed: payload.completed,
+        pending: true,
+      },
+    ],
+  }),
+)
+```
+
+If the optimistic state does not depend on the payload, use a static patch instead:
+
+```ts
+const saveSettings = optimistic(
+  handleAsync("saveSettings", {
+    async run(payload) {
+      return api.save(payload)
+    },
+  }),
+  { status: "saving" },
+)
+```
+
+The wrapper snapshots the keys in the patch, applies them in `Start`, restores the previous values in `Error`, and leaves `Success`/`Finally` handlers in control of cleanup.
+
 ---
 
 ### Event scoping
@@ -707,7 +774,7 @@ function increment(entity, payload, api) {
 
 // Test it
 const { entity, events } = trigger(
-  { type: "counter", id: "counter1", value: 99 },
+  { type: "Counter", id: "counter1", value: 99 },
   increment,
   { amount: 5 },
 )
@@ -725,8 +792,8 @@ 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 },
+  counter1: { type: "Counter", value: 10 },
+  counter2: { type: "Counter", value: 20 },
 })
 
 // A handler that copies a value from another entity
@@ -737,7 +804,7 @@ function copyValue(entity, payload, api) {
 
 // Trigger the handler with the custom mock API
 const { entity } = trigger(
-  { type: "counter", id: "counter2", value: 20 },
+  { type: "Counter", id: "counter2", value: 20 },
   copyValue,
   { sourceId: "counter1" },
   api,
@@ -1042,15 +1109,15 @@ const types = {
 
 // Without autoCreateEntities (default)
 const entities = {
-  settings: { type: "settings", theme: "dark" },
-  analytics: { type: "analytics", events: [] },
+  settings: { type: "Settings", theme: "dark" },
+  analytics: { type: "Analytics", events: [] },
 }
 
 // With autoCreateEntities: true
 const entities = {
   // settings and analytics will be auto-created as:
-  // settings: { type: "settings" }
-  // analytics: { type: "analytics" }
+  // settings: { type: "Settings" }
+  // analytics: { type: "Analytics" }
 }
 
 const store = createStore({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/store",
-  "version": "9.6.0",
+  "version": "11.0.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",
@@ -56,10 +56,10 @@
   "sideEffects": false,
   "dependencies": {
     "mutative": "^1.3.0",
-    "@inglorious/utils": "3.7.3"
+    "@inglorious/utils": "3.8.0"
   },
   "peerDependencies": {
-    "@inglorious/utils": "3.7.3"
+    "@inglorious/utils": "3.8.0"
   },
   "devDependencies": {
     "@reduxjs/toolkit": "^2.11.2",

package/src/async.js

@@ -146,7 +146,7 @@ export function handleAsync(type, handlers, options = {}) {
     }
   }
 
-  return {
+  const asyncHandlers = {
     [type](entity, payload, api) {
       if (handlers.start) {
         notify(api, entity, `${type}Start`, payload)
@@ -184,4 +184,13 @@ export function handleAsync(type, handlers, options = {}) {
       handlers.finally?.(entity, api)
     },
   }
+
+  Object.defineProperty(asyncHandlers, ASYNC_META, {
+    value: { type, scope },
+    enumerable: false,
+  })
+
+  return asyncHandlers
 }
+
+export const ASYNC_META = Symbol.for("@inglorious/store/asyncMeta")

package/src/optimistic.js

@@ -0,0 +1,195 @@
+import { ASYNC_META } from "./async.js"
+
+const START = 0
+
+/**
+ * Decorates an async behavior with optimistic update boilerplate.
+ *
+ * Pass either a static shallow patch object or a factory that returns one.
+ * The wrapper applies the patch during `Start` and rolls it back during `Error`.
+ *
+ * @template {import('./store').BaseEntity} TEntity
+ * @template TPayload
+ * @template TResult
+ *
+ * @param {import('./async').AsyncEventHandlers<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>}
+ *
+ * @example
+ * const saveItem = optimistic(
+ *   handleAsync("saveItem", {
+ *     async run(payload) {
+ *       return fetch("/api/items", {
+ *         method: "POST",
+ *         body: JSON.stringify(payload),
+ *       }).then((res) => res.json())
+ *     },
+ *     success(entity, result) {
+ *       entity.data = result
+ *     },
+ *   }),
+ *   { status: "saving" },
+ * )
+ *
+ * @example
+ * const saveDraft = optimistic(
+ *   handleAsync("saveDraft", {
+ *     async run(payload) {
+ *       return api.save(payload)
+ *     },
+ *   }),
+ *   (entity, payload) => ({
+ *     data: { ...entity.data, ...payload },
+ *   }),
+ * )
+ */
+export function optimistic(behavior, optimistic) {
+  const { type, scope } = resolveAsyncMeta(behavior)
+
+  const startEvent = `${type}Start`
+  const runEvent = `${type}Run`
+  const errorEvent = `${type}Error`
+  const finallyEvent = `${type}Finally`
+
+  const snapshots = new Map()
+
+  function notify(api, entity, event, payload) {
+    switch (scope) {
+      case "entity":
+        api.notify(`#${entity.id}:${event}`, payload)
+        break
+      case "type":
+        api.notify(`${entity.type}:${event}`, payload)
+        break
+      case "global":
+        api.notify(event, payload)
+        break
+    }
+  }
+
+  const wrapped = {
+    ...behavior,
+
+    [type](entity, payload, api) {
+      notify(api, entity, startEvent, payload)
+      notify(api, entity, runEvent, payload)
+    },
+
+    [startEvent](entity, payload, api) {
+      const patch = toPatch(optimistic, entity, payload, api)
+
+      if (!patch) {
+        behavior[startEvent]?.(entity, payload, api)
+        return
+      }
+
+      if (typeof patch !== "object") {
+        throw new TypeError(
+          "optimistic expects the patch to be an object or a factory that returns an object",
+        )
+      }
+
+      const key = getEntityKey(entity)
+      const currentEntity = api.getEntity?.(key) ?? entity
+      snapshots.set(key, snapshotPatch(currentEntity, patch))
+      Object.assign(entity, patch)
+
+      behavior[startEvent]?.(entity, payload, api)
+    },
+
+    [runEvent]: behavior[runEvent],
+
+    [errorEvent](entity, error, api) {
+      const key = getEntityKey(entity)
+      restorePatch(entity, snapshots.get(key))
+      behavior[errorEvent]?.(entity, error, api)
+    },
+
+    [finallyEvent](entity, api) {
+      try {
+        behavior[finallyEvent]?.(entity, api)
+      } finally {
+        snapshots.delete(getEntityKey(entity))
+      }
+    },
+  }
+
+  Object.defineProperty(wrapped, ASYNC_META, {
+    value: { type, scope },
+    enumerable: false,
+  })
+
+  return wrapped
+}
+
+function resolveAsyncMeta(behavior) {
+  const meta = behavior?.[ASYNC_META]
+  if (meta?.type) {
+    return meta
+  }
+
+  const runHandlers = Object.keys(behavior ?? {}).filter(
+    (key) => key.endsWith("Run") && typeof behavior[key] === "function",
+  )
+
+  const [runHandler, ...rest] = runHandlers
+
+  if (!runHandler && rest.length) {
+    throw new Error(
+      "optimistic expects a single handleAsync result or one '*Run' handler",
+    )
+  }
+
+  return {
+    type: runHandler.slice(START, -"Run".length),
+    scope: "entity",
+  }
+}
+
+function getEntityKey(entity) {
+  const id = entity?.id
+  if (id == null) {
+    throw new Error("optimistic requires entities to have a stable `id`")
+  }
+
+  return id
+}
+
+function toPatch(optimistic, entity, payload, api) {
+  if (typeof optimistic === "function") {
+    return optimistic(entity, payload, api)
+  }
+
+  return optimistic
+}
+
+function snapshotPatch(entity, patch) {
+  const entries = []
+
+  for (const key of Object.keys(patch)) {
+    entries.push([
+      key,
+      Object.prototype.hasOwnProperty.call(entity, key),
+      entity[key],
+    ])
+  }
+
+  return entries
+}
+
+function restorePatch(entity, entries) {
+  if (!entries) {
+    return
+  }
+
+  for (const [key, existed, value] of entries) {
+    if (existed) {
+      entity[key] = value
+    } else {
+      delete entity[key]
+    }
+  }
+}

package/src/store.js

@@ -1,3 +1,4 @@
+import { toCamelCase } from "@inglorious/utils/data-structures/string.js"
 import { create } from "mutative"
 
 import { createApi } from "./api.js"
@@ -118,8 +119,19 @@ export function createStore({
           const type = types[entity.type]
           const handle = type[handlerName]
 
-          if (handle) {
-            handle(entity, event.payload, api)
+          handle?.(entity, event.payload, api)
+        }
+
+        if (event.type.endsWith(":destroy")) {
+          const [target] = event.type.split(":")
+          const [, id] = target.split("#")
+          const entity = draft[id]
+          if (entity) {
+            const type = types[entity.type]
+            const typeName = entity.type
+            delete draft[id]
+
+            eventMap.removeEntity(id, type, typeName)
           }
         }
 
@@ -197,9 +209,10 @@ export function createStore({
       }
     }
 
-    if (autoCreateEntities && !state[typeName]) {
+    const entityId = toCamelCase(typeName)
+    if (autoCreateEntities && !state[entityId]) {
       notify("add", {
-        id: typeName,
+        id: entityId,
         type: typeName,
       })
     }
@@ -248,12 +261,13 @@ export function createStore({
 
     if (autoCreateEntities) {
       for (const typeName of Object.keys(types)) {
+        const entityId = toCamelCase(typeName)
         const hasEntity = Object.values(state).some(
           (entity) => entity.type === typeName,
         )
 
         if (!hasEntity) {
-          addEntity(state, { id: typeName, type: typeName })
+          addEntity(state, { id: entityId, type: typeName })
         }
       }
     }
@@ -277,12 +291,7 @@ export function createStore({
 
   function removeEntity(draft, payload) {
     const id = payload
-    const entity = draft[id]
-    const type = types[entity.type]
-    const typeName = entity.type
-    delete draft[id]
 
-    eventMap.removeEntity(id, type, typeName)
     incomingEvents.unshift({ type: `#${id}:destroy` })
   }
 }

package/types/optimistic.d.ts

@@ -0,0 +1,25 @@
+import { Api } from "./api"
+import { AsyncEventHandlers } from "./async"
+import { BaseEntity } from "./store"
+
+/**
+ * Decorates an async behavior with optimistic update boilerplate.
+ *
+ * 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.
+ */
+export function optimistic<
+  TEntity extends BaseEntity = BaseEntity,
+  TPayload = any,
+  TResult = any,
+>(
+  behavior: AsyncEventHandlers<TEntity, TPayload, TResult>,
+  optimistic:
+    | Record<string, any>
+    | ((
+        entity: TEntity,
+        payload: TPayload,
+        api: Api,
+      ) => Record<string, any> | null | undefined),
+): AsyncEventHandlers<TEntity, TPayload, TResult>