Ryan Di
126 lines
4.8 KiB
Plaintext
126 lines
4.8 KiB
Plaintext
# Transactions
|
|
|
|
Transactions let many live scene updates render immediately while still committing a single durable history entry.
|
|
|
|
Typical use case:
|
|
|
|
- AI streaming emits many `NEVER` updates for real-time feedback.
|
|
- Those updates advance the live scene and store snapshot, but do not create undo history.
|
|
- A transaction records the intended logical delta separately, then commits one synthetic durable increment at the end.
|
|
|
|
## Key Files
|
|
|
|
### `packages/excalidraw/transaction/`
|
|
|
|
- `transaction.ts`
|
|
- `Transaction` is the per-tx instance.
|
|
- `updateScene()` applies live updates with `captureUpdate: NEVER`.
|
|
- `updateElements()` is a typed partial-patch helper over `updateScene()`.
|
|
- `commit()` builds synthetic snapshots and commits one durable entry.
|
|
- `cancel()` ends the tx without committing history.
|
|
- `ledger.ts`
|
|
- `TransactionLedger` keeps per-element baseline, target, and touched props across tx steps.
|
|
- `buildSyntheticSnapshots()` reconciles tx intent with the live scene using `live-wins-per-prop`.
|
|
- `undoOverridePlanner.ts`
|
|
- Tracks tx intermediate values.
|
|
- Produces undo override candidates for regular user history entries that were recorded while a tx was active.
|
|
- `manager.ts`
|
|
- Owns tx lifecycle state and active-tx priority.
|
|
- Injects tx undo markers into durable deltas at record time.
|
|
- Resolves effective history deltas at undo/redo time.
|
|
- `diff.ts` / `types.ts`
|
|
- Shared diff helpers and transaction-specific types.
|
|
|
|
### `packages/element/src/store.ts`
|
|
|
|
- `store.commitSyntheticIncrement()`
|
|
- Builds `StoreSnapshot -> StoreChange -> StoreDelta` from logical before/after snapshots.
|
|
- Commits the synthetic durable increment immediately through an isolated path.
|
|
- Does not flush unrelated pending micro actions.
|
|
- `StoreDelta.markers`
|
|
- Carries extra history markers such as `txUndoOverrides`.
|
|
|
|
### `packages/excalidraw/history.ts`
|
|
|
|
- `onBeforeRecord()`
|
|
- Lets the transaction manager attach markers before a durable delta becomes a history entry.
|
|
- `setEffectiveDeltaResolver()`
|
|
- Lets the transaction manager rewrite a history delta at undo/redo time before it is applied.
|
|
|
|
## Flow
|
|
|
|
1. Caller creates a transaction.
|
|
2. `tx.updateScene()` applies live updates with `NEVER`.
|
|
3. The ledger records net element changes; appState intent is accumulated separately.
|
|
4. Regular user durable edits that happen while the tx is active may receive tx undo markers.
|
|
5. `tx.commit()` asks the ledger for logical before/after snapshots and calls `store.commitSyntheticIncrement()`.
|
|
6. Undo/redo later uses the manager's effective-delta resolver to decide whether ended tx markers should patch the baseline of a regular history entry.
|
|
|
|
Result:
|
|
|
|
- live rendering stays immediate;
|
|
- one tx still produces one durable history entry;
|
|
- interleaved regular edits can undo back to the correct pre-tx baseline.
|
|
|
|
## Undo Examples
|
|
|
|
### Interleaved Regular Edit
|
|
|
|
1. Baseline: `rect = (x: 0, stroke: black)`
|
|
2. Tx updates it live to `(x: 200, stroke: red)` with `NEVER`
|
|
3. User makes a regular durable edit: `(x: 200, stroke: purple)`
|
|
4. Tx commits; live stays purple
|
|
|
|
The user history entry was recorded while the tx was active, so its local baseline is `red`.
|
|
If undo later runs after the tx has ended, restoring `red` is wrong: the correct pre-tx baseline is `black`.
|
|
|
|
To fix this:
|
|
|
|
- record-time attaches a tx undo marker to the user history entry
|
|
- perform-time checks whether the tx has already ended
|
|
- if ended, the effective delta is patched so undo restores `black` instead of `red`
|
|
|
|
### Active Tx vs Ended Tx
|
|
|
|
Using the same example:
|
|
|
|
- if the user undoes while the tx is still active, the marker stays inactive and undo restores the tx intermediate value (`red`)
|
|
- if the user undoes after the tx has ended, the marker becomes active and undo restores the pre-tx baseline (`black`)
|
|
|
|
So markers are recorded early, but applied conditionally.
|
|
|
|
## AppState
|
|
|
|
Elements use ledger snapshots. AppState does not.
|
|
|
|
The transaction instead keeps:
|
|
|
|
- `initialAppState`: observed appState at tx start
|
|
- `accumulatedAppState`: merged caller intent from `tx.updateScene({ appState })`
|
|
|
|
At commit, the transaction computes the final appState patch and passes it into `store.commitSyntheticIncrement()`.
|
|
|
|
## Example
|
|
|
|
```ts
|
|
const tx = app.transactionManager.create();
|
|
|
|
tx.updateScene({ elements: updatedElementsA });
|
|
tx.updateScene({ elements: updatedElementsB });
|
|
tx.updateElements({
|
|
elements: [
|
|
{ id: "rect-1", type: "rectangle", updates: { strokeColor: "#f00" } },
|
|
{ id: "rect-2", type: "rectangle", updates: { x: 120 } },
|
|
],
|
|
});
|
|
|
|
tx.commit();
|
|
```
|
|
|
|
## Notes
|
|
|
|
- `commit()` and `cancel()` are idempotent.
|
|
- `updateScene()` and `updateElements()` throw after the tx has ended.
|
|
- Conflict handling inside synthetic snapshots is fixed to `live-wins-per-prop`.
|
|
- Multi-tx interleaving is supported through manager-owned lifecycle tracking and active-tx priority.
|