text_document/streaming.rs
1// SPDX-License-Identifier: MPL-2.0
2// SPDX-FileCopyrightText: 2026 FernTech
3
4//! Append-only streaming: the log/console path.
5//!
6//! A view tailing output does two things in a loop — append a line at the end,
7//! and drop the oldest once it is over its scrollback cap. Both are expressible
8//! with the ordinary editing API, and both are O(N) that way: appending one line
9//! to a 10 000-line document costs ~15.9 ms, and evicting 20 lines ~55 ms
10//! (`docs/streaming-baseline.md`). Neither cost is inherent — it comes from
11//! general-purpose machinery that a tail-append does not need:
12//!
13//! * `character_count()` / `cursor_at()` each run `get_document_stats`, which
14//! materializes every block's text to compute a word count the caller never
15//! asked for — just to locate the end of the document.
16//! * `insert_block` fetches *every* block entity (via
17//! `collect_block_ids_recursive` and `get_block_multi`) before it can find
18//! the insertion point. `insert_text` has an O(log n) rope fast path;
19//! `insert_block` never received one.
20//! * `delete_text` walks the whole `child_order` refreshing every block's stored
21//! position, with a rope lookup per block, regardless of how little was
22//! deleted.
23//!
24//! None of that is needed when the insertion point is, by construction, the end:
25//! the rope already knows where the end is, nothing after it needs shifting, and
26//! no block above it is touched. This module takes that shortcut directly, via
27//! the `rope_helpers` primitives (`rope_append_block` is a rope insert at the
28//! tail plus an O(1) amortized `push_block` — nothing shifts, because appending
29//! at the end shifts nothing).
30//!
31//! # Not undoable — and not an oversight
32//!
33//! **Nothing in this module participates in undo/redo.** An appended or evicted
34//! line cannot be brought back with [`TextDocument::undo`](crate::TextDocument::undo), does not appear on
35//! the undo stack, and does not affect [`TextDocument::can_undo`](crate::TextDocument::can_undo).
36//!
37//! That is deliberate on both counts. A million streamed lines must not become a
38//! million undo entries — the stack is unbounded, so that is a leak, not a
39//! feature. And the alternative escape hatch the rest of the crate uses for
40//! non-undoable work (perform, then `clear_stack`, as `set_plain_text` does)
41//! would throw away the *user's* history every time a line arrived from a
42//! background thread.
43//!
44//! So the entity writes are routed through a private stack of their own, cleared
45//! as they go. Note that passing `None` as the stack id would not have achieved
46//! this: `add_command_to_stack` resolves `None` to stack 0 rather than skipping,
47//! so it is not an opt-out.
48//!
49//! Consequences worth being deliberate about:
50//!
51//! * **The document's own undo stack is untouched.** A user's edits stay
52//! undoable across any amount of streaming, and undo will never surface or
53//! swallow a streamed line. This is covered by a test.
54//! * **Streaming is not reversible.** Content that arrived from elsewhere is not
55//! the user's to undo; if a caller needs to drop it, that is
56//! [`truncate_front`](TextDocument::truncate_front), not undo.
57//! * **`modified` is still set**, and change events are still emitted, so views
58//! and dirty-tracking behave normally.
59//!
60//! Mixing streaming with ordinary editing on one document works and is tested
61//! (the rope and the block index stay coherent), but it is not the intended
62//! shape: these are for buffers whose content arrives from elsewhere.
63//!
64//! # All-or-nothing
65//!
66//! Every entry point here is atomic: it either lands completely or leaves the
67//! document exactly as it was. That needs saying because it does not come for
68//! free. These paths hand-maintain four things that must agree — the rope, the
69//! block offset index, the frame's `child_order`, and the document's cached
70//! counts — across several fallible calls, and the unit-of-work layer that
71//! normally guarantees that is precisely what they bypass for speed. Without
72//! care, any early `?` would leave text in the rope that no block owns, or a
73//! block the frame never references, or counts describing a document that no
74//! longer exists — none of which surfaces as an error, only as a document that
75//! quietly disagrees with itself.
76//!
77//! So each operation takes a savepoint first and rolls back on any failure,
78//! including a panic. A savepoint is a whole-store snapshot, but a cheap one:
79//! the rope is persistent and the entity tables are `im::HashMap`s, so it is
80//! pointer copies, not a deep clone.
81//!
82//! Note that a rolled-back append still consumes the entity ids it allocated —
83//! the store's counters are deliberately not rewound — so ids may show gaps.
84//! Nothing depends on them being contiguous.
85//!
86//! # This is still O(N) — know the ceiling before using it
87//!
88//! Measured, appending one line (`docs/streaming-baseline.md`):
89//!
90//! | lines in document | ordinary editing path | this |
91//! |---|---|---|
92//! | 1 000 | 986 µs | 174 µs |
93//! | 10 000 | 28.1 ms | 2.90 ms |
94//!
95//! Roughly 10× cheaper — but 174 µs → 2.90 ms is 16.7× for 10× the document, so
96//! **this is still O(N), not O(1)**. It moves the ceiling; it does not remove it.
97//! Around 10 000 lines an append costs ~2.9 ms (~345 lines/second), which suits
98//! an application's own event log. It does not suit `tail -f` of a large file:
99//! at 100 000 lines the cost extrapolates to ~29 ms per line. Cap the buffer
100//! accordingly, and evict with [`truncate_front`](TextDocument::truncate_front).
101//!
102//! `truncate_front` is barely better than the ordinary path (1.19× at 10 000)
103//! and is *slower* below a few thousand lines, because the ordinary path makes a
104//! single bulk `delete_text` call where this makes one entity removal per evicted
105//! block. It exists for the coherence of the streaming API — appending without
106//! being able to evict is useless — not because it is fast.
107//!
108//! The rope is not the reason. `rope_append_block` is O(log n) as intended; the
109//! residual is the generic entity-update path. `UndoableUpdateUseCase::
110//! execute_multi` fetches the old entity for undo and stashes it on every write,
111//! so each `update_frame` clones the `Frame` — its whole `child_order: Vec<i64>`
112//! included — several times over. Every appended line therefore touches the
113//! entire `child_order`, whatever the rope does.
114//!
115//! Reaching O(1) means `child_order` no longer being an N-element `Vec` cloned
116//! per write. That reshapes a core entity the whole engine and its property tests
117//! depend on, and is deliberately out of scope here.
118
119use std::sync::Arc;
120
121use frontend::block::dtos::CreateBlockDto;
122use frontend::commands::{block_commands, document_commands, frame_commands, undo_redo_commands};
123use frontend::common::types::EntityId;
124use frontend::document::dtos::UpdateDocumentDto;
125use frontend::frame::dtos::UpdateFrameDto;
126
127use crate::document::get_main_frame_id;
128use crate::events::DocumentEvent;
129use crate::inner::TextDocumentInner;
130use crate::{DocumentError, Result, TextDocument};
131
132impl TextDocument {
133 /// Append `text` as a new block at the end, returning the document's new
134 /// block count.
135 ///
136 /// The append half of a streaming buffer. Costs the rope insert and one
137 /// entity write, whatever the buffer already holds — against ~15.9 ms per
138 /// line at 10 000 lines through the ordinary editing path
139 /// (`docs/streaming-baseline.md`).
140 ///
141 /// The returned count is what a scrollback cap is checked against, so a
142 /// caller never needs a separate count call — which matters, because
143 /// [`block_count`](Self::block_count) walks the whole document:
144 ///
145 /// ```ignore
146 /// let count = doc.append_line(line)?;
147 /// if count > CAP {
148 /// doc.truncate_front(count - CAP)?;
149 /// }
150 /// ```
151 ///
152 /// `text` is taken as a single line: it must not contain `\n`, since a block
153 /// is one line by construction here (embedded newlines would desynchronize
154 /// the rope from the block index). Returns [`DocumentError::InvalidArgument`]
155 /// if it does.
156 ///
157 /// **Not undoable**, by design — see the module docs.
158 pub fn append_line(&self, text: &str) -> Result<usize> {
159 if text.contains('\n') {
160 return Err(DocumentError::InvalidArgument(
161 "append_line takes a single line; text must not contain '\\n'".into(),
162 ));
163 }
164 // After the argument is checked: a refused append leaves a composition shown.
165 let _settled = self.settle_transient_edits();
166
167 let mut inner = self.inner.lock();
168 let frame_id = get_main_frame_id(&inner);
169 if frame_id == 0 {
170 return Err(DocumentError::InvalidArgument(
171 "document has no main frame".into(),
172 ));
173 }
174
175 // Everything below either all lands or none of it does.
176 let atomic = Atomic::begin(&inner)?;
177 let appended = append_one(&mut inner, frame_id, text)?;
178 let new_count = commit_counts(&mut inner, 1, text.chars().count() as i64)?;
179 atomic.commit();
180
181 finish(&mut inner, appended.edit_pos, appended.chars_added, 1);
182
183 inner.queue_event(DocumentEvent::BlockCountChanged(new_count));
184 // A pure tail append: the new element lands at the end of the flow, so
185 // the index is the previous count. Emitted directly rather than through
186 // the generic `check_flow_changed`, which diffs the whole `child_order`
187 // on every edit — O(N) again, to rediscover what is known here.
188 inner.queue_event(DocumentEvent::FlowElementsInserted {
189 flow_index: new_count - 1,
190 count: 1,
191 });
192
193 // Notify `on_change` subscribers, like every other mutation — the poll
194 // path alone would leave callback-based observers (a reactive view) blind
195 // to appends. Dispatch outside the lock: a callback may re-enter.
196 let queued = inner.take_queued_events();
197 drop(inner);
198 crate::inner::dispatch_queued_events(queued);
199 Ok(new_count)
200 }
201
202 /// Append several lines in one go, returning the document's new block count.
203 ///
204 /// Equivalent to [`append_line`](Self::append_line) per line, but pays the
205 /// document-count write and the throwaway-stack clear once for the batch
206 /// rather than per line. A view draining a channel once per frame should
207 /// prefer this.
208 ///
209 /// No line may contain `\n`.
210 ///
211 /// **Not undoable**, by design — see the module docs.
212 pub fn append_lines<I, S>(&self, lines: I) -> Result<usize>
213 where
214 I: IntoIterator<Item = S>,
215 S: AsRef<str>,
216 {
217 let lines: Vec<String> = lines.into_iter().map(|s| s.as_ref().to_owned()).collect();
218 if lines.iter().any(|l| l.contains('\n')) {
219 return Err(DocumentError::InvalidArgument(
220 "append_lines takes single lines; none may contain '\\n'".into(),
221 ));
222 }
223 if lines.is_empty() {
224 let inner = self.inner.lock();
225 return Ok(current_block_count(&inner)? as usize);
226 }
227 // After the arguments are checked: a refused or empty append leaves a composition
228 // shown.
229 let _settled = self.settle_transient_edits();
230
231 let mut inner = self.inner.lock();
232 let frame_id = get_main_frame_id(&inner);
233 if frame_id == 0 {
234 return Err(DocumentError::InvalidArgument(
235 "document has no main frame".into(),
236 ));
237 }
238
239 // The batch is one unit: a line failing halfway would otherwise leave
240 // its predecessors appended with the document's counts never updated,
241 // since those are written once at the end.
242 let atomic = Atomic::begin(&inner)?;
243 let mut edit_pos = None;
244 let mut chars_added = 0usize;
245 for line in &lines {
246 let appended = append_one(&mut inner, frame_id, line)?;
247 // The batch's edit starts where its first line did.
248 edit_pos.get_or_insert(appended.edit_pos);
249 chars_added += appended.chars_added;
250 }
251 let edit_pos = edit_pos.unwrap_or(0);
252
253 let chars: i64 = lines.iter().map(|l| l.chars().count() as i64).sum();
254 let new_count = commit_counts(&mut inner, lines.len() as i64, chars)?;
255 atomic.commit();
256
257 finish(&mut inner, edit_pos, chars_added, lines.len());
258
259 inner.queue_event(DocumentEvent::BlockCountChanged(new_count));
260 inner.queue_event(DocumentEvent::FlowElementsInserted {
261 flow_index: new_count - lines.len(),
262 count: lines.len(),
263 });
264
265 // Dispatch to `on_change` subscribers (outside the lock — a callback may
266 // re-enter), the same as an ordinary edit.
267 let queued = inner.take_queued_events();
268 drop(inner);
269 crate::inner::dispatch_queued_events(queued);
270 Ok(new_count)
271 }
272
273 /// Drop the first `n` blocks, returning how many were actually removed.
274 ///
275 /// The eviction half of a streaming buffer. Returns less than `n` when the
276 /// document holds fewer blocks; a document is never emptied completely —
277 /// one block always remains, since an empty document is not a valid state
278 /// here (it is created with one block, and the rest of the API assumes at
279 /// least one exists).
280 ///
281 /// **Not undoable**, by design — see the module docs.
282 pub fn truncate_front(&self, n: usize) -> Result<usize> {
283 let _settled = self.settle_transient_edits();
284 if n == 0 {
285 return Ok(0);
286 }
287
288 let mut inner = self.inner.lock();
289 let frame_id = get_main_frame_id(&inner);
290 if frame_id == 0 {
291 return Err(DocumentError::InvalidArgument(
292 "document has no main frame".into(),
293 ));
294 }
295
296 let stack = streaming_stack(&mut inner);
297
298 // Which blocks to drop, capped so that at least one always survives.
299 let (victims, chars_removed) = {
300 let frame = frame_commands::get_frame(&inner.ctx, &frame_id)?
301 .ok_or_else(|| DocumentError::InvalidArgument("main frame missing".into()))?;
302 let block_ids: Vec<EntityId> = frame
303 .child_order
304 .iter()
305 .filter(|e| **e > 0)
306 .map(|e| *e as EntityId)
307 .collect();
308 let take = n.min(block_ids.len().saturating_sub(1));
309 let victims: Vec<EntityId> = block_ids.into_iter().take(take).collect();
310
311 // Every victim's length must be counted, so a lookup that fails is
312 // an error rather than a silent zero: swallowing it would subtract
313 // too little from `character_count`, and since all later deltas are
314 // relative, the document's count would stay wrong forever with
315 // nothing reporting it.
316 let mut chars: i64 = 0;
317 for id in &victims {
318 let block = block_commands::get_block(&inner.ctx, id)?.ok_or_else(|| {
319 DocumentError::InvalidArgument(format!(
320 "block {id} is referenced by the frame but does not exist"
321 ))
322 })?;
323 let entity: common::entities::Block = block.into();
324 let store = inner.ctx.db_context.get_store();
325 chars += common::database::rope_helpers::block_char_length(&entity, store);
326 }
327 (victims, chars)
328 };
329
330 if victims.is_empty() {
331 return Ok(0);
332 }
333
334 // Everything below either all lands or none of it does. Without this,
335 // a failure partway through the entity loop would leave the rope
336 // already stripped of victims whose blocks still exist and are still
337 // referenced by the frame.
338 let atomic = Atomic::begin(&inner)?;
339
340 // Unmirror from the rope first: `rope_remove_block` resolves each block
341 // through the offset index, which the entity must still exist for.
342 {
343 let store = inner.ctx.db_context.get_store();
344 for id in &victims {
345 common::database::rope_helpers::rope_remove_block(store, *id);
346 }
347 }
348
349 // Drop the entities, then the frame's references to them in one write.
350 for id in &victims {
351 block_commands::remove_block(&inner.ctx, Some(stack), id)?;
352 }
353 {
354 let frame = frame_commands::get_frame(&inner.ctx, &frame_id)?
355 .ok_or_else(|| DocumentError::InvalidArgument("main frame missing".into()))?;
356 let mut update: UpdateFrameDto = frame.into();
357 // Drop exactly the evicted ids, rather than the first N entries:
358 // `remove_block` may already have pruned them, and `child_order`
359 // can hold negative entries (sub-frames) that are not blocks, so
360 // positional removal would take out survivors.
361 let evicted: std::collections::HashSet<i64> =
362 victims.iter().map(|id| *id as i64).collect();
363 let before = update.child_order.len();
364 update.child_order.retain(|e| !evicted.contains(e));
365 if update.child_order.len() != before {
366 frame_commands::update_frame(&inner.ctx, Some(stack), &update)?;
367 }
368 }
369
370 let removed = victims.len();
371 let new_count = commit_counts(&mut inner, -(removed as i64), -chars_removed)?;
372 atomic.commit();
373
374 undo_redo_commands::clear_stack(&inner.ctx, stack);
375
376 // Everything shifts down by what was cut off the front.
377 inner.invalidate_text_cache();
378 inner.adjust_cursors(0, chars_removed as usize + removed, 0);
379 inner.modified = true;
380 inner.queue_event(DocumentEvent::ContentsChanged {
381 position: 0,
382 chars_removed: chars_removed as usize + removed,
383 chars_added: 0,
384 blocks_affected: removed,
385 });
386 inner.queue_event(DocumentEvent::BlockCountChanged(new_count));
387 inner.queue_event(DocumentEvent::FlowElementsRemoved {
388 flow_index: 0,
389 count: removed,
390 });
391
392 // Dispatch to `on_change` subscribers (outside the lock — a callback may
393 // re-enter), the same as an ordinary edit.
394 let queued = inner.take_queued_events();
395 drop(inner);
396 crate::inner::dispatch_queued_events(queued);
397 Ok(removed)
398 }
399}
400
401/// The document's block count, read straight off the entity.
402///
403/// [`TextDocument::block_count`](crate::TextDocument::block_count) answers the same question via
404/// `get_document_stats`, which also computes a word count by materializing every
405/// block's text — 3.18 ms at 10 000 lines. This is the cached value the entity
406/// already carries, which is what `inner.rs`'s own `check_block_count_changed`
407/// reads for exactly the same reason.
408fn current_block_count(inner: &TextDocumentInner) -> Result<i64> {
409 let doc = document_commands::get_document(&inner.ctx, &inner.document_id)?
410 .ok_or_else(|| DocumentError::InvalidArgument("document missing".into()))?;
411 Ok(doc.block_count)
412}
413
414/// A private undo stack for streaming writes, created on first use.
415///
416/// The entity commands always push an undo command — passing `None` does not
417/// opt out, it resolves to stack 0 (`add_command_to_stack`). Routing these
418/// writes to a stack of their own, cleared as they go, keeps them off the
419/// document's real history without bounding-problems or clearing what the user
420/// did.
421fn streaming_stack(inner: &mut TextDocumentInner) -> u64 {
422 if let Some(id) = inner.streaming_stack_id {
423 return id;
424 }
425 let id = undo_redo_commands::create_new_stack(&inner.ctx);
426 inner.streaming_stack_id = Some(id);
427 id
428}
429
430/// All-or-nothing around a streaming mutation.
431///
432/// These paths hand-maintain four things that must agree — the rope, the block
433/// offset index, the frame's `child_order`, and the document's cached counts —
434/// across several fallible calls. The ordinary editing path gets that
435/// consistency from the unit-of-work layer; taking the shortcut past it takes
436/// the shortcut past its atomicity too, so every early `?` would otherwise be a
437/// chance to leave the four disagreeing: text in the rope that no block owns, a
438/// block absent from `child_order`, counts describing a document that no longer
439/// exists.
440///
441/// A savepoint is a whole-store snapshot, but a cheap one — the rope is a
442/// persistent structure and the entity tables are `im::HashMap`s, so it is
443/// pointer-copies rather than a deep clone. Restoring it undoes everything
444/// since, the inner commands' own writes included, because each savepoint is an
445/// independent snapshot rather than a stack position.
446///
447/// Deliberately not `Transaction`, which is the same savepoint plus an
448/// O(N) `recompute_all_frame_byte_ranges` on commit — a cost this path exists
449/// to avoid, and one the inner commands' own transactions already pay.
450///
451/// Rolls back on drop unless [`commit`](Self::commit) ran, so an early `?` — or
452/// a panic — cannot leave the document half-written.
453struct Atomic {
454 /// Owned rather than borrowed: holding a reference would borrow the
455 /// document's interior for the guard's whole lifetime, which is exactly the
456 /// span in which the work needs `&mut` access to it.
457 store: Arc<common::database::Store>,
458 savepoint: Option<u64>,
459}
460
461impl Atomic {
462 /// Begun as every write to the store is (`RopeStore::check_write_allowed`): refused
463 /// over transient edits made since the append reverted them, and counted open until
464 /// its savepoint is discarded.
465 fn begin(inner: &TextDocumentInner) -> Result<Self> {
466 let store = Arc::clone(inner.ctx.db_context.get_store());
467 store.check_write_allowed()?;
468 let savepoint = Some(store.create_savepoint());
469 Ok(Self { store, savepoint })
470 }
471
472 /// Keep the mutations and drop the snapshot.
473 fn commit(mut self) {
474 if let Some(sp) = self.savepoint.take() {
475 self.store.discard_savepoint(sp);
476 }
477 }
478}
479
480impl Drop for Atomic {
481 fn drop(&mut self) {
482 // Still holding the savepoint means `commit` never ran: the operation
483 // left early, so put the document back exactly as it was.
484 if let Some(sp) = self.savepoint.take() {
485 self.store.restore_savepoint(sp);
486 self.store.discard_savepoint(sp);
487 }
488 }
489}
490
491/// What one appended line did to the document, as the caller's bookkeeping
492/// needs to describe it.
493struct Appended {
494 /// Document position the insertion began at.
495 edit_pos: usize,
496 /// Characters inserted there — the text, plus the separator when one was
497 /// needed. Not derivable from the text alone, which is the whole reason
498 /// this is reported rather than recomputed.
499 chars_added: usize,
500}
501
502/// Create one block, mirror it into the rope at the tail, and reference it from
503/// the frame.
504fn append_one(inner: &mut TextDocumentInner, frame_id: EntityId, text: &str) -> Result<Appended> {
505 let stack = streaming_stack(inner);
506
507 // Read the frame *before* creating the block: the generic create path adds
508 // the block to the junction table but not to `child_order`, so this sees
509 // exactly the blocks that already existed.
510 let frame = frame_commands::get_frame(&inner.ctx, &frame_id)?
511 .ok_or_else(|| DocumentError::InvalidArgument("main frame missing".into()))?;
512
513 // Blocks after the first in a frame are separated by a `\n` sentinel, and
514 // `rope_append_block` does not add one itself.
515 //
516 // The condition is "does the frame already hold a block", NOT "is the rope
517 // non-empty". A freshly created document already holds one *empty* block,
518 // registered at byte 0, with an empty rope — so keying off the rope would
519 // skip the separator and register the new block at byte 0 as well, leaving
520 // two blocks at the same offset with no `\n` between them. That is not a
521 // hypothetical: `TextDocument::new()` followed by `append_line` is the most
522 // direct way to use this API.
523 let needs_boundary = frame.child_order.iter().any(|entry| *entry > 0);
524
525 let block = block_commands::create_block(
526 &inner.ctx,
527 Some(stack),
528 &CreateBlockDto::default(),
529 frame_id,
530 -1,
531 )?;
532
533 let appended = {
534 let store = inner.ctx.db_context.get_store();
535 // Where the insertion begins — captured before it, so it covers the
536 // separator too when one is written.
537 let edit_pos = store.rope.read().len_chars();
538 if needs_boundary {
539 common::database::rope_helpers::rope_insert_block_boundary(store);
540 }
541 common::database::rope_helpers::rope_append_block(store, block.id, text);
542 Appended {
543 edit_pos,
544 chars_added: text.chars().count() + usize::from(needs_boundary),
545 }
546 };
547
548 // The generic create path adds the block to the junction table but not to
549 // `child_order`, which is what `flow()` reads — `initialize` notes the same.
550 let mut update: UpdateFrameDto = frame.into();
551 update.child_order.push(block.id as i64);
552 frame_commands::update_frame(&inner.ctx, Some(stack), &update)?;
553
554 Ok(appended)
555}
556
557/// Apply deltas to the document's cached counts, returning the new block count.
558fn commit_counts(
559 inner: &mut TextDocumentInner,
560 block_delta: i64,
561 char_delta: i64,
562) -> Result<usize> {
563 let doc = document_commands::get_document(&inner.ctx, &inner.document_id)?
564 .ok_or_else(|| DocumentError::InvalidArgument("document missing".into()))?;
565 let stack = streaming_stack(inner);
566 let mut update: UpdateDocumentDto = doc.into();
567 update.block_count = (update.block_count + block_delta).max(0);
568 update.character_count = (update.character_count + char_delta).max(0);
569 let new_count = update.block_count as usize;
570 document_commands::update_document(&inner.ctx, Some(stack), &update)?;
571 Ok(new_count)
572}
573
574/// Post-append bookkeeping shared by the append entry points.
575///
576/// `blocks_affected` is passed rather than assumed: a batch adds as many blocks
577/// as it has lines, and consumers size work off that number.
578fn finish(inner: &mut TextDocumentInner, edit_pos: usize, added: usize, blocks_affected: usize) {
579 let stack = streaming_stack(inner);
580 // Discard the throwaway history: these writes are not undoable, and letting
581 // it grow would leak a command per appended line.
582 undo_redo_commands::clear_stack(&inner.ctx, stack);
583
584 // The document's text just changed, so the lazily-built plain-text cache no
585 // longer describes it. Every ordinary edit clears this; bypassing the
586 // editing path means bypassing that too, and a stale cache is silent —
587 // `blocks()` reads the live document while `to_plain_text()` keeps serving
588 // whatever the text was when it was last asked.
589 inner.invalidate_text_cache();
590 inner.adjust_cursors(edit_pos, 0, added);
591 inner.modified = true;
592 inner.queue_event(DocumentEvent::ContentsChanged {
593 position: edit_pos,
594 chars_removed: 0,
595 chars_added: added,
596 blocks_affected,
597 });
598}
599
600#[cfg(test)]
601mod tests {
602 use super::*;
603
604 /// A streaming append that finds transient edits made since its revert (another
605 /// thread's, between the revert and its lock) is refused before it writes the rope.
606 #[test]
607 fn an_append_finding_transient_edits_is_refused_before_it_writes() {
608 let doc = TextDocument::new();
609 doc.append_line("first").unwrap();
610 doc.cursor_at(2).insert_text_transient("n").unwrap();
611 let shown = doc.to_plain_text().unwrap();
612 let refused = {
613 let inner = doc.inner.lock();
614 Atomic::begin(&inner).err()
615 };
616 assert!(matches!(
617 refused,
618 Some(DocumentError::TransientEdits(
619 crate::TransientRefusal::LayerOutstanding
620 ))
621 ));
622 assert_eq!(doc.to_plain_text().unwrap(), shown);
623 assert!(doc.has_transient_edits());
624 // Once they are reverted the append is begun, and counted open until it ends.
625 doc.revert_transient_edits();
626 let inner = doc.inner.lock();
627 let atomic = Atomic::begin(&inner).expect("nothing outstanding");
628 let store = inner.ctx.db_context.get_store();
629 assert!(store.begin_transient_write().is_err(), "the append is open");
630 atomic.commit();
631 assert!(store.begin_transient_write().is_ok());
632 }
633}