@inglorious/store 10.0.0 → 11.0.0

package/README.md

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

package/package.json

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

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