Track Optimistic Status Per Record for Local-Only Query Differentiation

[KyleAMathews]

Problem

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 __optimistic flag or with __optimistic: false are 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.

[KyleAMathews]

Decided on a different approach after discussion:

Rather than adding __optimistic to record data (which modifies user data and risks namespace conflicts), we're implementing collection.getOptimisticInfo(id) that returns rich metadata:

collection.getOptimisticInfo(id)
// Returns:
{
  isOptimistic: boolean
  original?: T          // Pre-mutation state (undefined if optimistic insert or not optimistic)
  modified: T           // Current state
  changes?: Partial<T>  // Delta (only for optimistic updates)
  mutations: PendingMutation[]  // All active mutations affecting this key
}

Benefits:

• Keeps records pure (no system fields polluting user data)
• Mirrors the existing transaction mutation data structure
• Provides everything needed for complex UI states (badges, diff views, rollback UI)
• No risk of namespace conflicts
• Optimistic state is transitional metadata, not an inherent property of data

Usage:

const info = collection.getOptimisticInfo(todoId)
if (info.isOptimistic) {
  return <Badge>Saving...</Badge>
}

// Or for diff views:
if (info.changes) {
  showDiff(info.original, info.modified, info.changes)
}