trekoon 0.2.8 → 0.3.0

package/src/board/assets/state/api.js

@@ -1,15 +1,167 @@
+/**
+ * API layer with serial mutation queue.
+ *
+ * Replaces the boolean isMutating gate with a proper queue that processes
+ * mutations sequentially, applies optimistic updates immediately, and
+ * reverts on error.
+ */
+
 function cloneSnapshot(snapshot) {
   if (typeof structuredClone === "function") {
     return structuredClone(snapshot);
   }
-
   return JSON.parse(JSON.stringify(snapshot));
 }
 
+async function readJsonPayload(response) {
+  const text = await response.text();
+  if (text.length === 0) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    const error = new Error(`Board API returned malformed JSON (${response.status} ${response.statusText || "unknown"})`);
+    error.code = "invalid_response";
+    error.status = response.status;
+    error.statusText = response.statusText;
+    error.details = {
+      responseText: text.slice(0, 240),
+    };
+    throw error;
+  }
+}
+
+function buildRequestError(method, path, response, payload) {
+  const code = payload?.error?.code;
+  const routeMessage = payload?.error?.message;
+  const message = routeMessage
+    ? `${method} ${path} failed (${response.status}${code ? ` ${code}` : ""}): ${routeMessage}`
+    : `${method} ${path} failed with ${response.status} ${response.statusText || "unknown error"}`;
+  const error = new Error(message);
+  error.code = code;
+  error.status = response.status;
+  error.statusText = response.statusText;
+  error.details = payload?.error?.details;
+  return error;
+}
+
+/**
+ * Create a serial mutation queue.
+ *
+ * Mutations are enqueued and processed one at a time in FIFO order.
+ * Each mutation can apply an optimistic update, make an async request,
+ * and handle success or error.
+ *
+ * @returns {{
+ *   enqueue: (mutation: object) => void,
+ *   isPending: boolean,
+ *   flush: () => Promise<void>,
+ * }}
+ */
+export function createMutationQueue(model, rerender) {
+  /** @type {Array<{ optimistic?: function, request: function, onSuccess?: function, onError?: function, successMessage?: string }>} */
+  const queue = [];
+  let processing = false;
+  /** @type {Array<() => void>} */
+  let flushResolvers = [];
+
+  function resolveFlushes() {
+    if (processing || queue.length > 0 || flushResolvers.length === 0) {
+      return;
+    }
+
+    const pendingResolvers = flushResolvers;
+    flushResolvers = [];
+    pendingResolvers.forEach((resolve) => resolve());
+  }
+
+  async function processNext() {
+    if (processing || queue.length === 0) return;
+    processing = true;
+    model.store.isMutating = true;
+
+    while (queue.length > 0) {
+      const mutation = queue.shift();
+      const previousSnapshot = cloneSnapshot(model.store.snapshot);
+      model.store.notice = null;
+
+      // Apply optimistic update
+      if (typeof mutation.optimistic === "function") {
+        model.store.snapshot = mutation.optimistic(cloneSnapshot(model.store.snapshot));
+        rerender();
+      }
+
+      try {
+        const data = await mutation.request();
+
+        if (data?.snapshot) {
+          model.replaceSnapshot(data.snapshot);
+        }
+
+        if (typeof mutation.onSuccess === "function") {
+          mutation.onSuccess(data);
+        }
+
+        model.store.notice = mutation.successMessage
+          ? { type: "success", message: mutation.successMessage }
+          : null;
+      } catch (error) {
+        // Revert to pre-optimistic snapshot
+        model.replaceSnapshot(previousSnapshot);
+
+        const message = error instanceof Error ? error.message : String(error);
+        model.store.notice = { type: "error", message };
+
+        if (typeof mutation.onError === "function") {
+          mutation.onError(error);
+        }
+
+        // Clear remaining queue on error to prevent cascading failures
+        queue.length = 0;
+      }
+    }
+
+    processing = false;
+    model.store.isMutating = false;
+    rerender();
+    resolveFlushes();
+  }
+
+  return {
+    enqueue(mutation) {
+      queue.push(mutation);
+      processNext();
+    },
+
+    get isPending() {
+      return processing || queue.length > 0;
+    },
+
+    flush() {
+      if (!processing && queue.length === 0) return Promise.resolve();
+      return new Promise((resolve) => {
+        flushResolvers.push(resolve);
+      });
+    },
+  };
+}
+
+/**
+ * Create the API layer with mutation queue.
+ *
+ * @param {object} model - Store model from createStore
+ * @param {object} options
+ * @param {string} options.sessionToken - Auth token for API requests
+ * @param {function} options.rerender - Trigger a UI rerender
+ * @returns {object} API methods: patchTask, patchSubtask, createSubtask, deleteSubtask, addDependency, removeDependency
+ */
 export function createApi(model, options) {
   const { sessionToken, rerender } = options;
 
   async function request(path, requestOptions = {}) {
+    const method = typeof requestOptions.method === "string" ? requestOptions.method.toUpperCase() : "GET";
     const headers = new Headers(requestOptions.headers || {});
     if (sessionToken.length > 0) {
       headers.set("authorization", `Bearer ${sessionToken}`);
@@ -18,54 +170,41 @@ export function createApi(model, options) {
       headers.set("content-type", "application/json");
     }
 
-    const response = await fetch(path, { ...requestOptions, headers });
-    const payload = await response.json();
-    if (!payload?.ok) {
-      const message = payload?.error?.message || "Board request failed";
-      const error = new Error(message);
-      error.code = payload?.error?.code;
-      error.details = payload?.error?.details;
-      throw error;
-    }
-
-    return payload.data;
-  }
-
-  async function runMutation({ optimistic, request: mutationRequest, successMessage }) {
-    if (model.store.isMutating) {
-      return;
+    let response;
+    try {
+      response = await fetch(path, { ...requestOptions, headers });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const requestError = new Error(`${method} ${path} failed before a response was received: ${message}`);
+      requestError.code = "network_error";
+      requestError.cause = error;
+      throw requestError;
     }
 
-    const previousSnapshot = cloneSnapshot(model.store.snapshot);
-    model.store.notice = null;
-    model.store.isMutating = true;
-
-    if (typeof optimistic === "function") {
-      model.store.snapshot = optimistic(cloneSnapshot(model.store.snapshot));
-      rerender();
+    const payload = await readJsonPayload(response);
+    if (!response.ok || !payload?.ok) {
+      throw buildRequestError(method, path, response, payload);
     }
 
-    try {
-      const data = await mutationRequest();
-      if (data?.snapshot) {
-        model.replaceSnapshot(data.snapshot);
-      }
-      model.store.notice = successMessage ? { type: "success", message: successMessage } : null;
-    } catch (error) {
-      model.replaceSnapshot(previousSnapshot);
-      model.store.notice = {
-        type: "error",
-        message: error instanceof Error ? error.message : String(error),
-      };
-    } finally {
-      model.store.isMutating = false;
-      rerender();
-    }
+    return payload.data;
   }
 
+  const queue = createMutationQueue(model, rerender);
+
   return {
+    patchEpic(epicId, updates, optimistic) {
+      queue.enqueue({
+        optimistic,
+        successMessage: "Epic saved.",
+        request: () => request(`/api/epics/${encodeURIComponent(epicId)}`, {
+          method: "PATCH",
+          body: JSON.stringify(updates),
+        }),
+      });
+    },
+
     patchTask(taskId, updates, optimistic) {
-      return runMutation({
+      queue.enqueue({
         optimistic,
         successMessage: "Task saved.",
         request: () => request(`/api/tasks/${encodeURIComponent(taskId)}`, {
@@ -74,8 +213,9 @@ export function createApi(model, options) {
         }),
       });
     },
+
     patchSubtask(subtaskId, updates, optimistic) {
-      return runMutation({
+      queue.enqueue({
         optimistic,
         successMessage: "Subtask saved.",
         request: () => request(`/api/subtasks/${encodeURIComponent(subtaskId)}`, {
@@ -84,8 +224,20 @@ export function createApi(model, options) {
         }),
       });
     },
+
+    cascadeEpicStatus(epicId, status, optimistic) {
+      queue.enqueue({
+        optimistic,
+        successMessage: "Epic cascade status updated.",
+        request: () => request(`/api/epics/${encodeURIComponent(epicId)}/cascade`, {
+          method: "PATCH",
+          body: JSON.stringify({ status }),
+        }),
+      });
+    },
+
     createSubtask(input, optimistic) {
-      return runMutation({
+      queue.enqueue({
         optimistic,
         successMessage: "Subtask added.",
         request: () => request("/api/subtasks", {
@@ -94,8 +246,9 @@ export function createApi(model, options) {
         }),
       });
     },
+
     deleteSubtask(subtaskId, optimistic) {
-      return runMutation({
+      queue.enqueue({
         optimistic,
         successMessage: "Subtask removed.",
         request: () => request(`/api/subtasks/${encodeURIComponent(subtaskId)}`, {
@@ -103,8 +256,9 @@ export function createApi(model, options) {
         }),
       });
     },
+
     addDependency(sourceId, dependsOnId, optimistic) {
-      return runMutation({
+      queue.enqueue({
         optimistic,
         successMessage: "Dependency added.",
         request: () => request("/api/dependencies", {
@@ -113,8 +267,9 @@ export function createApi(model, options) {
         }),
       });
     },
+
     removeDependency(sourceId, dependsOnId, optimistic) {
-      return runMutation({
+      queue.enqueue({
         optimistic,
         successMessage: "Dependency removed.",
         request: () => request(`/api/dependencies?sourceId=${encodeURIComponent(sourceId)}&dependsOnId=${encodeURIComponent(dependsOnId)}`, {