base state
→ optimistic patch
→ pending action
→ server result
→ reconciliation
→ rollback / compensate / confirm

baseState = data terakhir yang sudah confirmed

optimisticState = baseState + pending optimistic patches

Optimistic state bukan source of truth.
Optimistic state adalah speculative overlay.

const [optimisticState, addOptimistic] = useOptimistic(state, reducer);

value:
  state dasar ketika tidak ada action pending

reducer:
  pure function untuk menghitung optimistic state dari current state + optimistic action

optimisticState:
  state yang dirender sekarang

addOptimistic:
  function untuk menambahkan optimistic update selama Action berlangsung

function LikeButton({
  liked,
  updateLiked,
}: {
  liked: boolean;
  updateLiked: (liked: boolean) => Promise<void>;
}) {
  const [optimisticLiked, setOptimisticLiked] = useOptimistic(liked);

  async function submitAction() {
    setOptimisticLiked(!optimisticLiked);
    await updateLiked(!optimisticLiked);
  }

  return (
    <form action={submitAction}>
      <button type="submit">
        {optimisticLiked ? "Unlike" : "Like"}
      </button>
    </form>
  );
}

type Todo = {
  id: string;
  text: string;
  completed: boolean;
  optimistic?: boolean;
};

type OptimisticTodoAction =
  | { type: "add"; todo: Todo }
  | { type: "toggle"; id: string }
  | { type: "remove"; id: string };

function optimisticTodoReducer(
  todos: Todo[],
  action: OptimisticTodoAction
): Todo[] {
  switch (action.type) {
    case "add":
      return [action.todo, ...todos];

    case "toggle":
      return todos.map((todo) =>
        todo.id === action.id
          ? { ...todo, completed: !todo.completed }
          : todo
      );

    case "remove":
      return todos.filter((todo) => todo.id !== action.id);
  }
}

function TodoList({
  todos,
  createTodo,
}: {
  todos: Todo[];
  createTodo: (input: { text: string; clientId: string }) => Promise<Todo>;
}) {
  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
    todos,
    optimisticTodoReducer
  );

  async function createTodoAction(formData: FormData) {
    const text = String(formData.get("text") ?? "").trim();

    if (!text) {
      return;
    }

    const clientId = crypto.randomUUID();

    addOptimisticTodo({
      type: "add",
      todo: {
        id: clientId,
        text,
        completed: false,
        optimistic: true,
      },
    });

    await createTodo({ text, clientId });
  }

  return (
    <>
      <form action={createTodoAction}>
        <input name="text" />
        <button>Add</button>
      </form>

      <ul>
        {optimisticTodos.map((todo) => (
          <li key={todo.id} aria-busy={todo.optimistic}>
            {todo.text}
            {todo.optimistic && " (saving...)"}
          </li>
        ))}
      </ul>
    </>
  );
}

deterministic
testable
composable
independent dari stale closure

- success rate tinggi
- action reversible atau failure mudah dijelaskan
- user intent jelas
- server conflict jarang atau bisa direconcile
- action latency terasa mengganggu
- UI bisa menandai pending/speculative state

like/unlike
mark as read
add comment
rename draft
toggle preference
reorder local list
archive notification
save lightweight setting

payment
approval workflow legal/regulatory
permission-sensitive action
inventory reservation
case status transition
delete irreversible record
multi-actor conflict-heavy edit

precondition
expected version
audit event
server rejection rendering
compensation path
clear pending indicator

optimistic state ≈ confirmed state

optimistic add comment
→ server rejects
→ remove optimistic comment
→ show error

user clicks Approve
UI shows Approved pending
server says case already escalated

"This case was escalated by another reviewer before your approval was applied."

const clientId = crypto.randomUUID();

addOptimisticComment({
  type: "add",
  comment: {
    id: clientId,
    clientId,
    body,
    status: "pending",
  },
});

const saved = await createComment({
  clientId,
  body,
});

- duplicate request bisa dedupe
- response bisa dikaitkan ke optimistic item
- retry tidak membuat item ganda

type CreateCommentResponse = {
  clientId: string;
  commentId: string;
  body: string;
  createdAt: string;
};

clientId temp-123 → server id comment-987

Jika optimistic state hanya diperlukan di satu component/form:
  useOptimistic

Jika optimistic update harus terlihat di banyak subscriber server-state:
  cache-level optimistic update

Jika workflow punya banyak step/conflict:
  state machine + server-state cache + explicit compensation

type Comment = {
  id: string;
  body: string;
  authorName: string;
  status: "confirmed" | "pending" | "failed";
};

type OptimisticCommentAction =
  | { type: "add-pending"; comment: Comment }
  | { type: "mark-failed"; id: string };

function optimisticCommentsReducer(
  comments: Comment[],
  action: OptimisticCommentAction
): Comment[] {
  switch (action.type) {
    case "add-pending":
      return [action.comment, ...comments];

    case "mark-failed":
      return comments.map((comment) =>
        comment.id === action.id
          ? { ...comment, status: "failed" }
          : comment
      );
  }
}

function CommentsPanel({
  comments,
  currentUser,
  createComment,
}: {
  comments: Comment[];
  currentUser: { name: string };
  createComment: (input: { body: string; clientId: string }) => Promise<void>;
}) {
  const [optimisticComments, addOptimisticComment] = useOptimistic(
    comments,
    optimisticCommentsReducer
  );

  async function addCommentAction(formData: FormData) {
    const body = String(formData.get("body") ?? "").trim();

    if (!body) {
      return;
    }

    const clientId = crypto.randomUUID();

    addOptimisticComment({
      type: "add-pending",
      comment: {
        id: clientId,
        body,
        authorName: currentUser.name,
        status: "pending",
      },
    });

    try {
      await createComment({ body, clientId });
    } catch {
      addOptimisticComment({
        type: "mark-failed",
        id: clientId,
      });
    }
  }

  return (
    <section>
      <form action={addCommentAction}>
        <textarea name="body" />
        <button>Post comment</button>
      </form>

      <ul>
        {optimisticComments.map((comment) => (
          <li key={comment.id} aria-busy={comment.status === "pending"}>
            <p>{comment.body}</p>
            <small>
              {comment.authorName}
              {comment.status === "pending" && " · sending"}
              {comment.status === "failed" && " · failed"}
            </small>
          </li>
        ))}
      </ul>
    </section>
  );
}

This example shows local failure marking.
In many real apps, failed state should be separate from confirmed comments.

setOptimisticLiked(!liked);
await updateLiked(!liked);

liked bisa stale
dua klik cepat bisa menghasilkan urutan salah
server bisa punya state berbeda

type LikeState = {
  liked: boolean;
  count: number;
  version: number;
};

type OptimisticLikeAction = {
  type: "set-liked";
  liked: boolean;
};

function optimisticLikeReducer(
  state: LikeState,
  action: OptimisticLikeAction
): LikeState {
  if (state.liked === action.liked) {
    return state;
  }

  return {
    ...state,
    liked: action.liked,
    count: state.count + (action.liked ? 1 : -1),
  };
}

function LikeButton({
  value,
  saveLike,
}: {
  value: LikeState;
  saveLike: (input: { liked: boolean; expectedVersion: number }) => Promise<void>;
}) {
  const [optimisticValue, addOptimistic] = useOptimistic(
    value,
    optimisticLikeReducer
  );

  async function setLikedAction(formData: FormData) {
    const liked = formData.get("liked") === "true";

    addOptimistic({
      type: "set-liked",
      liked,
    });

    await saveLike({
      liked,
      expectedVersion: value.version,
    });
  }

  return (
    <form action={setLikedAction}>
      <input
        type="hidden"
        name="liked"
        value={String(!optimisticValue.liked)}
      />
      <button type="submit">
        {optimisticValue.liked ? "Unlike" : "Like"} · {optimisticValue.count}
      </button>
    </form>
  );
}

base comments: [A, B]
pending optimistic: [C*, D*, E*]

base + patch1 + patch2 + patch3

- response server datang tidak berurutan
- temp ID mapping bentrok
- rollback patch lama menghapus patch baru
- invalidation refetch menghapus optimistic overlay terlalu cepat

- gunakan clientId unik per command
- jangan rollback berdasarkan posisi list
- reconcile berdasarkan identity
- response harus membawa clientId/idempotency key
- jangan mengandalkan urutan network response

item hilang
server gagal
item muncul lagi
user bingung

mark item as "deleting..."
disable interactions
hide visually after short delay
allow undo
remove after confirmed success

type Row = {
  id: string;
  name: string;
  status: "active" | "deleting";
};

type OptimisticRowAction =
  | { type: "mark-deleting"; id: string }
  | { type: "remove"; id: string };

function optimisticRowsReducer(rows: Row[], action: OptimisticRowAction): Row[] {
  switch (action.type) {
    case "mark-deleting":
      return rows.map((row) =>
        row.id === action.id ? { ...row, status: "deleting" } : row
      );

    case "remove":
      return rows.filter((row) => row.id !== action.id);
  }
}

Klik Approve → langsung tampil Approved final

Klik Approve → tampil "Approval pending..."
server success → tampil Approved
server rejects → tampil reason + current server state

type CaseStatusView =
  | { tag: "draft" }
  | { tag: "pending_approval"; optimistic: true; submittedAt: string }
  | { tag: "approved"; version: number }
  | { tag: "rejected"; reason: string; serverStatus: string };

Semakin tinggi consequence domain, semakin eksplisit optimistic marker.

- pending badge
- dimmed row
- spinner inline kecil
- "sending..." text
- disable destructive secondary actions
- allow cancel/undo bila mungkin
- show "sync failed" state jika perlu persist

<li data-status={comment.status}>
  <p>{comment.body}</p>

  {comment.status === "pending" && (
    <small aria-live="polite">Sending...</small>
  )}

  {comment.status === "failed" && (
    <button type="button">Retry</button>
  )}
</li>

Apa yang gagal?
Apakah data saya hilang?
Apakah bisa retry?
Apakah server state berubah?

client tidak tahu command berhasil atau gagal

CreateComment(postId)
  - invalidate ["post", postId, "comments"]
  - maybe update ["post", postId, "summary"]
  - maybe invalidate ["feed"]

LikePost(postId)
  - update ["post", postId]
  - maybe invalidate ["feed"]
  - maybe not refetch immediately if count can be reconciled later

const { data: comments } = useQuery(...);

const [optimisticComments, addOptimisticComment] = useOptimistic(
  comments ?? [],
  reducer
);

Optimistic reducer harus pure dan identity-based.

base count = 10
other user already liked, server count = 11
you optimistic like → 11
server confirmed count → 12

- show approximate count while pending
- server response returns authoritative aggregate
- refetch after success
- use expected version for conflict-sensitive actions

type OptimisticCommand = {
  clientCommandId: string;
  type: "create-comment";
  payload: {
    body: string;
  };
};

- dedupe duplicate submit
- correlate server response
- retry safely
- audit user intent
- debug optimistic mismatch

clientCommandId → command result

type Patch<S, A> = {
  id: string;
  action: A;
};

function applyOptimisticPatches<S, A>(
  base: S,
  patches: Patch<S, A>[],
  reducer: (state: S, action: A) => S
): S {
  return patches.reduce(
    (state, patch) => reducer(state, patch.action),
    base
  );
}

base state changes when parent/server/cache updates
patch queue exists while action pending
render uses base + patches
patch removed/reconciled when action resolves

it("optimistically appends comment", () => {
  const result = optimisticCommentsReducer([], {
    type: "add-pending",
    comment: {
      id: "client-1",
      body: "Hello",
      authorName: "Ari",
      status: "pending",
    },
  });

  expect(result).toEqual([
    {
      id: "client-1",
      body: "Hello",
      authorName: "Ari",
      status: "pending",
    },
  ]);
});

it("shows pending comment immediately", async () => {
  const createComment = vi.fn(
    () => new Promise<void>((resolve) => setTimeout(resolve, 1000))
  );

  render(
    <CommentsPanel
      comments={[]}
      currentUser={{ name: "Ari" }}
      createComment={createComment}
    />
  );

  await user.type(screen.getByRole("textbox"), "Hello");
  await user.click(screen.getByRole("button", { name: /post/i }));

  expect(screen.getByText("Hello")).toBeInTheDocument();
  expect(screen.getByText(/sending/i)).toBeInTheDocument();
});

it("shows recovery UI when optimistic command fails", async () => {
  const createComment = vi.fn().mockRejectedValue(new Error("Network error"));

  render(
    <CommentsPanel
      comments={[]}
      currentUser={{ name: "Ari" }}
      createComment={createComment}
    />
  );

  await user.type(screen.getByRole("textbox"), "Hello");
  await user.click(screen.getByRole("button", { name: /post/i }));

  expect(await screen.findByText(/failed/i)).toBeInTheDocument();
});

given case version 10
when user submits approve with expectedVersion 10
and server returns stale_version with current version 11
then UI shows conflict message and authoritative server status

optimistic_command_created
optimistic_command_sent
optimistic_command_confirmed
optimistic_command_rejected
optimistic_command_reconciled
optimistic_command_timeout

type OptimisticEvent = {
  clientCommandId: string;
  commandType: string;
  entityType: string;
  entityId?: string;
  optimisticPatchType: string;
  startedAt: string;
  completedAt?: string;
  result: "confirmed" | "rejected" | "timeout" | "unknown";
};

UI menampilkan pending approval karena user menekan approve pada 10:12:03,
tetapi server menolak pada 10:12:04 karena case version sudah berubah.

[ ] Optimistic state clearly separated from confirmed state
[ ] Reducer is pure and identity-based
[ ] Pending/speculative UI is visible when domain requires it
[ ] Every optimistic command has clientCommandId/idempotency key when needed
[ ] Temp ID maps to server ID
[ ] Rollback/reconciliation handles out-of-order responses
[ ] Domain conflict has explicit UI
[ ] Failure state tells user what happened and what to do
[ ] Cache impact map is defined
[ ] Server response returns enough data to reconcile
[ ] Destructive actions are not over-optimistic
[ ] Tests cover success, failure, race, and conflict
[ ] Observability records optimistic lifecycle

useOptimistic gives React a native way to render speculative state during async actions.

source of truth discipline
identity
idempotency
reconciliation
rollback/compensation
conflict handling
accessibility
observability

Optimistic UI boleh cepat.
Authoritative state tetap harus benar.