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.
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.
npm install optimistic-reconcileNode.js 20 or newer is supported. The package is ESM-only and has no runtime dependencies.
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 lifetimeIf 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.
| 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.
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.
See CONTRIBUTING.md. Bug reports and small, focused pull requests are welcome.
MIT