Support Non-Optimistic Mutations Within Transactions

[KyleAMathews]

Problem

Currently, all insert, update, and delete mutations immediately modify the local optimistic store upon transaction creation.
There is no way to mark a mutation as "non-optimistic" — meaning it should only apply locally after server confirmation.

This limits developer control in cases where immediate speculative updates are undesirable:

• Inserts that depend on complex server-side generation (e.g., cascading foreign keys).
• Deletes where UX should wait for confirmation before removing data.
• Updates where backend-side validation or side-effects must be confirmed first.

Proposed Solution

Extend mutation methods to accept an optimistic option.

Example usage:

tx.collection('posts').insert({ title: 'New' }, { optimistic: true });
tx.collection('comments').delete('commentId', { optimistic: false });

Behavior

• optimistic: true (default):

  • Immediately apply mutation to the local store.
  • Speculative view updates.
  • Rollback required if server rejects.

• optimistic: false:

  • Do not modify local store immediately.
  • Queue mutation for server persistence.
  • Apply to store only after server confirmation.
  • No rollback necessary if server rejects (no state change was staged).

Design Principles

• Unified transaction model: both optimistic and non-optimistic mutations live within the same transaction scope.
• No new transaction modes.
• No separate mutation API.
• Explicit developer control per mutation.

Constraints

• optimistic defaults to true for backward compatibility.
• Non-optimistic mutations may still fail server-side; appropriate error handling must be surfaced.
• No speculative local store impact for optimistic: false mutations.

Future Work

• Potential support for mixed optimistic/non-optimistic batching strategies.
• Extended tooling to visually distinguish speculative vs confirmed data if desired.