Ryan Di
94 lines
4.3 KiB
Plaintext
94 lines
4.3 KiB
Plaintext
# Transactions
|
|
|
|
## Transaction + Ledger System
|
|
|
|
This system lets many canvas mutations over a time window (for example AI streaming patch/action/create) render immediately, while still producing a single undoable durable history entry.
|
|
|
|
- AI streaming typically emits many `NEVER` updates (for real-time visual feedback).
|
|
- `NEVER` updates advance Store snapshots, but do not write undo/redo history.
|
|
- If we only do a final "one IMMEDIATELY at the end", we often miss the intended delta because snapshots may already be aligned.
|
|
- Transaction + Ledger creates synthetic logical before/after snapshots, then commits one durable increment with correct undo semantics.
|
|
|
|
## Key Files
|
|
|
|
### `packages/excalidraw/transaction.ts`
|
|
|
|
- `TransactionLedger`: keeps net mutation state across steps.
|
|
- `recordStep()`: folds multiple updates into per-element baseline/target/touchedProps.
|
|
- `buildSyntheticSnapshots()`: reconciles ledger state with live scene using fixed `live-wins-per-prop` behavior and returns `elementsBefore` / `elementsAfter` for history commit.
|
|
- `TransactionManager`: thin factory holding the app reference. `create()` returns a `Transaction`.
|
|
- `Transaction` (class):
|
|
- `tx.updateScene(data)`: wraps `app.updateScene` with `captureUpdate: NEVER`. Snapshots elements before/after and records the diff into the ledger. Accumulates appState intent.
|
|
- `tx.updateElements({ elements })`: convenience API for partial updates (`[{ id, strokeColor }, { id, x, y }]`). It materializes a next elements array and delegates to `tx.updateScene(...)`.
|
|
- `tx.commit()`: builds synthetic before/after snapshots from the ledger, calls `store.commitSyntheticIncrement()`, returns a summary.
|
|
- `tx.cancel()`: finalizes without committing history.
|
|
|
|
### `packages/element/src/store.ts`
|
|
|
|
- `store.commitSyntheticIncrement()`: builds `StoreSnapshot -> StoreChange -> StoreDelta` from logical before/after element maps and optional appState patches. Schedules a micro IMMEDIATELY so the delta is flushed on the next `componentDidUpdate -> store.commit()`.
|
|
|
|
## How They Work Together
|
|
|
|
1. Caller creates a transaction (`excalidrawAPI.createTransaction()` or `app.transactionManager.create()`).
|
|
2. `tx.updateScene()` applies mutations with `NEVER` for real-time visual feedback.
|
|
3. Ledger records element diffs on each `updateScene()` call; appState intent is auto-accumulated.
|
|
4. On `tx.commit()`:
|
|
- Ledger builds `logicalBefore/logicalAfter` reconciled against live scene
|
|
- `store.commitSyntheticIncrement()` computes change/delta and schedules micro IMMEDIATELY
|
|
5. Next `componentDidUpdate -> store.commit()` flushes the micro and emits a durable increment to the undo stack.
|
|
|
|
Result:
|
|
|
|
- streaming visuals stay immediate;
|
|
- history remains one entry per transaction;
|
|
- synthetic durable commit is scheduled via micro IMMEDIATELY, flushed naturally by the next commit cycle.
|
|
|
|
## AppState Strategy
|
|
|
|
The ledger tracks elements per-id per-property. AppState cannot use the same snapshot approach because `setState` is batched.
|
|
|
|
Instead, the transaction auto-accumulates caller intent: each `tx.updateScene({ appState })` call merges the passed `appState` patch into `accumulatedAppState`. The transaction saves `initialAppState` at creation time. At commit: `appStateBefore = initialAppState`, `appStateAfter = initialAppState + accumulatedAppState`.
|
|
|
|
## Sample Usage
|
|
|
|
### Short Session
|
|
|
|
```ts
|
|
const tx = app.transactionManager.create();
|
|
|
|
tx.updateScene({ elements: updatedElementsA });
|
|
tx.updateScene({ elements: updatedElementsB });
|
|
tx.updateElements({
|
|
elements: [{ id: "rect-1", strokeColor: "#f00" }, { id: "rect-2", x: 120 }],
|
|
});
|
|
|
|
tx.commit();
|
|
```
|
|
|
|
### Long Session (multi-step with error handling)
|
|
|
|
```ts
|
|
const tx = app.transactionManager.create();
|
|
|
|
try {
|
|
tx.updateScene({ elements: step1Elements });
|
|
tx.updateScene({ elements: step2Elements });
|
|
tx.updateScene({
|
|
elements: step3Elements,
|
|
appState: { selectedElementIds: nextSelectedIds },
|
|
});
|
|
|
|
tx.commit();
|
|
} catch (error) {
|
|
tx.cancel();
|
|
throw error;
|
|
}
|
|
```
|
|
|
|
## Notes
|
|
|
|
- `commit()` and `cancel()` are idempotent (repeated calls return the same summary).
|
|
- `updateScene()` / `updateElements()` throw after `commit()` or `cancel()`.
|
|
- Element conflict handling is fixed to `live-wins-per-prop`.
|
|
- Multi-transaction concurrency works naturally — each tx has its own ledger.
|