optimistic-reconcile

Reconcile optimistic entities with canonical server records across HTTP, WebSocket, SSE, and refetch—without changing the key your UI renders.

optimistic-reconcile is a framework-neutral TypeScript library for one narrow problem: a client creates a temporary entity, the server assigns its canonical ID, and several transports may deliver the same entity in different orders.

Why this exists

An optimistic create can become two rows when a push event or refetch returns the saved entity before the original request completes. Replacing a temporary ID with a server ID can also remount UI state. Generic optimistic-state helpers usually handle rollback, but not identity across multiple sources.

This library keeps an immutable viewKey while explicitly linking:

client mutation ID  ─────┐
                         ├── stable view key
canonical server ID ─────┘

It never merges records because their content looks similar. Reconciliation requires a mutation ID echoed by the server, an acknowledgement that maps the mutation to a canonical ID, or an already-known canonical ID.

Install

npm install optimistic-reconcile

Node.js 20 or newer is supported. The package is ESM-only and has no runtime dependencies.

Quick start

import { createReconciler } from "optimistic-reconcile";

type Message = {
  id?: string;
  clientMutationId?: string;
  text: string;
  delivered?: boolean;
};

const messages = createReconciler<Message>({
  getId: (message) => message.id,
  getMutationId: (message) => message.clientMutationId,
  merge: (current, incoming) => ({ ...current, ...incoming }),
});

const mutationId = crypto.randomUUID();
const pending = messages.insertOptimistic(
  { clientMutationId: mutationId, text: "Hello" },
  { mutationId },
);

// A WebSocket or SSE event may arrive first.
messages.observe({
  id: "message-42",
  clientMutationId: mutationId,
  text: "Hello",
  delivered: true,
});

// A late HTTP response is idempotent.
messages.acknowledge(mutationId, { canonicalId: "message-42" });

messages.getSnapshot(); // one entity, not two
messages.canonicalIdFor(mutationId); // "message-42"
pending.viewKey; // unchanged for the entity's UI lifetime

If the server cannot echo clientMutationId, acknowledge the explicit mapping:

messages.acknowledge(mutationId, {
  canonicalId: response.id,
  entity: response,
});

Then later observe() calls with that canonical ID update the same entry.

Lifecycle

| Status | Meaning | | -------------- | ------------------------------------------------------------------------ | | pending | Optimistic entity exists locally. | | acknowledged | The mutation has a canonical ID, but no observed sync event has arrived. | | synced | A canonical entity was observed by any transport. | | failed | An unsettled mutation was rejected. |

A late failure never downgrades an entity that was already observed as synced. Call remove(viewKey) when an entry leaves your cache so its identity mappings can be released.

Integration

getSnapshot() and subscribe() follow the external-store shape used by UI frameworks. For React, for example:

const entities = useSyncExternalStore(
  messages.subscribe,
  messages.getSnapshot,
  messages.getSnapshot,
);

The library does not send requests, own a cache, retry mutations, persist data, or guess identity. Those remain the responsibility of your application or data library.

Documentation

• Getting started
• Identity protocol
• API reference
• Race-condition matrix
• Architecture
• Maintainer guide

Contributing

See CONTRIBUTING.md. Bug reports and small, focused pull requests are welcome.

License

MIT