gilles/excalidraw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Ryan Di
2026-04-24 16:32:46 +10:00
parent 4be8dd9879
commit b2920f0baf
1 changed files with 90 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dev-docs/docs/codebase/transactions.mdx
+90 -58
View File
@@ -1,57 +1,106 @@
# Transactions # Transactions
## Transaction + Ledger System Transactions let many live scene updates render immediately while still committing a single durable history entry.
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. Typical use case:
- AI streaming typically emits many `NEVER` updates (for real-time visual feedback). - AI streaming emits many `NEVER` updates for real-time feedback.
- `NEVER` updates advance Store snapshots, but do not write undo/redo history. - Those updates advance the live scene and store snapshot, but do not create undo history.
- If we only do a final "one IMMEDIATELY at the end", we often miss the intended delta because snapshots may already be aligned. - A transaction records the intended logical delta separately, then commits one synthetic durable increment at the end.
- Transaction + Ledger creates synthetic logical before/after snapshots, then commits one durable increment with correct undo semantics.
## Key Files ## Key Files
### `packages/excalidraw/transaction.ts` ### `packages/excalidraw/transaction/`
- `TransactionLedger`: keeps net mutation state across steps. - `transaction.ts`
- `recordStep()`: folds multiple updates into per-element baseline/target/touchedProps. - `Transaction` is the per-tx instance.
- `buildSyntheticSnapshots()`: reconciles ledger state with live scene using fixed `live-wins-per-prop` behavior and returns `elementsBefore` / `elementsAfter` for history commit. - `updateScene()` applies live updates with `captureUpdate: NEVER`.
- `TransactionManager`: thin factory holding the app reference. `create()` returns a `Transaction`. - `updateElements()` is a typed partial-patch helper over `updateScene()`.
- `Transaction` (class): - `commit()` builds synthetic snapshots and commits one durable entry.
- `tx.updateScene(data)`: wraps `app.updateScene` with `captureUpdate: NEVER`. Snapshots elements before/after and records the diff into the ledger. Accumulates appState intent. - `cancel()` ends the tx without committing history.
- `tx.updateElements({ elements })`: convenience API for partial updates (`[{ id, strokeColor }, { id, x, y }]`). It materializes a next elements array and delegates to `tx.updateScene(...)`. - `ledger.ts`
- `tx.commit()`: builds synthetic before/after snapshots from the ledger, calls `store.commitSyntheticIncrement()`, returns a summary. - `TransactionLedger` keeps per-element baseline, target, and touched props across tx steps.
- `tx.cancel()`: finalizes without committing history. - `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` ### `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()`. - `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`.
## How They Work Together ### `packages/excalidraw/history.ts`
1. Caller creates a transaction (`excalidrawAPI.createTransaction()` or `app.transactionManager.create()`). - `onBeforeRecord()`
2. `tx.updateScene()` applies mutations with `NEVER` for real-time visual feedback. - Lets the transaction manager attach markers before a durable delta becomes a history entry.
3. Ledger records element diffs on each `updateScene()` call; appState intent is auto-accumulated. - `setEffectiveDeltaResolver()`
4. On `tx.commit()`: - Lets the transaction manager rewrite a history delta at undo/redo time before it is applied.
- Ledger builds `logicalBefore/logicalAfter` reconciled against live scene
- `store.commitSyntheticIncrement()` computes change/delta and schedules micro IMMEDIATELY ## Flow
5. Next `componentDidUpdate -> store.commit()` flushes the micro and emits a durable increment to the undo stack.
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: Result:
- streaming visuals stay immediate; - live rendering stays immediate;
- history remains one entry per transaction; - one tx still produces one durable history entry;
- synthetic durable commit is scheduled via micro IMMEDIATELY, flushed naturally by the next commit cycle. - interleaved regular edits can undo back to the correct pre-tx baseline.
## AppState Strategy ## Undo Examples
The ledger tracks elements per-id per-property. AppState cannot use the same snapshot approach because `setState` is batched. ### Interleaved Regular Edit
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`. 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
## Sample Usage 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`.
### Short Session 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 ```ts
const tx = app.transactionManager.create(); const tx = app.transactionManager.create();
@@ -59,35 +108,18 @@ const tx = app.transactionManager.create();
tx.updateScene({ elements: updatedElementsA }); tx.updateScene({ elements: updatedElementsA });
tx.updateScene({ elements: updatedElementsB }); tx.updateScene({ elements: updatedElementsB });
tx.updateElements({ tx.updateElements({
elements: [{ id: "rect-1", strokeColor: "#f00" }, { id: "rect-2", x: 120 }], elements: [
{ id: "rect-1", type: "rectangle", updates: { strokeColor: "#f00" } },
{ id: "rect-2", type: "rectangle", updates: { x: 120 } },
],
}); });
tx.commit(); 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 ## Notes
- `commit()` and `cancel()` are idempotent (repeated calls return the same summary). - `commit()` and `cancel()` are idempotent.
- `updateScene()` / `updateElements()` throw after `commit()` or `cancel()`. - `updateScene()` and `updateElements()` throw after the tx has ended.
- Element conflict handling is fixed to `live-wins-per-prop`. - Conflict handling inside synthetic snapshots is fixed to `live-wins-per-prop`.
- Multi-transaction concurrency works naturally — each tx has its own ledger. - Multi-tx interleaving is supported through manager-owned lifecycle tracking and active-tx priority.