Track Optimistic Status Per Record for Local-Only Query Differentiation #20
Send to my agentProblem#
Currently, there is no explicit way to distinguish between records that exist optimistically on the client and those that have been confirmed by the server. This can cause ambiguity in UI rendering, state reconciliation, and user feedback flows.
Proposed Solution#
Introduce a system-reserved field __optimistic on each record.
- When a record is created optimistically, set
__optimistic: true. - Upon successful server confirmation, set
__optimistic: false. - Records without an explicit
__optimisticflag or with__optimistic: falseare treated as fully server-validated.
Example record shape:
interface Record {
id: string;
fields: Record<string, any>;
__optimistic: boolean;
}
Usage#
- UI components can render badges or indicators for optimistic records.
- Query results can filter or partition between optimistic and confirmed records if necessary.
- Developers gain fine-grained control over UX during optimistic phases without needing to manage separate metadata.
Design Principles#
- __optimistic is internal and system-controlled.
- It should not be included in API payloads unless explicitly configured.
- It should be treated as read-only by default in developer-facing APIs.
Future Work#
- Potential future support for batch-level query optimistic status summaries.
- Optional utilities to filter or style optimistic records at the query layer.
Sign in to join this conversation.
Decided on a different approach after discussion:
Rather than adding
__optimisticto record data (which modifies user data and risks namespace conflicts), we're implementingcollection.getOptimisticInfo(id)that returns rich metadata:Benefits:
Usage: