feat: cache for toPlainText in Document to avoid unnecessary text computing (#2482)

feat: cache for toPlainText in Document to avoid unnecessary text computing (#2482)

test: basic unit tests

---------

Co-authored-by: CatHood0 <[email protected]>
Co-authored-by: Ellet <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -10,6 +10,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added 
+
+- Cache for `toPlainText` in `Document` class to avoid unnecessary text computing [#2482](https://github.com/singerdmx/flutter-quill/pull/2482).
+
 ## [11.1.2] - 2025-03-24
 
 ### Fixed

lib/src/document/document.dart

@@ -25,19 +25,26 @@ import 'style.dart';
 class Document {
   /// Creates new empty document.
   Document() : _delta = Delta()..insert('\n') {
-    _loadDocument(_delta);
+    loadDocument(_delta);
   }
 
   /// Creates new document from provided JSON `data`.
   Document.fromJson(List data) : _delta = _transform(Delta.fromJson(data)) {
-    _loadDocument(_delta);
+    loadDocument(_delta);
   }
 
   /// Creates new document from provided `delta`.
   Document.fromDelta(Delta delta) : _delta = delta {
-    _loadDocument(delta);
+    loadDocument(delta);
   }
 
+  /// Stores the plain text content of the entire document in memory for quick access.
+  ///
+  /// It acts as a cache to avoid repeatedly extracting or generating the plain text.
+  @visibleForTesting
+  @internal
+  String? cachedPlainText;
+
   /// The root node of the document tree
   final Root _root = Root();
 
@@ -465,16 +472,19 @@ class Document {
       throw StateError('_delta compose failed');
     }
     assert(_delta == _root.toDelta(), 'Compose failed');
+    cachedPlainText = null;
     final change = DocChange(originalDelta, delta, changeSource);
     documentChangeObserver.add(change);
     history.handleDocChange(change);
   }
 
   HistoryChanged undo() {
+    cachedPlainText = null;
     return history.undo(this);
   }
 
   HistoryChanged redo() {
+    cachedPlainText = null;
     return history.redo(this);
   }
 
@@ -539,11 +549,13 @@ class Document {
     Iterable<EmbedBuilder>? embedBuilders,
     EmbedBuilder? unknownEmbedBuilder,
   ]) =>
-      _root.children
+      cachedPlainText ??= _root.children
           .map((e) => e.toPlainText(embedBuilders, unknownEmbedBuilder))
           .join();
 
-  void _loadDocument(Delta doc) {
+  @visibleForTesting
+  @internal
+  void loadDocument(Delta doc) {
     if (doc.isEmpty) {
       throw ArgumentError.value(
           doc.toString(), 'Document Delta cannot be empty.');
@@ -570,6 +582,7 @@ class Document {
         _root.childCount > 1) {
       _root.remove(node);
     }
+    cachedPlainText = null;
   }
 
   bool isEmpty() {

test/document/document_test.dart

@@ -182,4 +182,79 @@ void main() {
           reason: 'start of blank line');
     });
   });
+  group('cachedPlainText', () {
+    late Document document;
+
+    setUp(() {
+      document = Document();
+    });
+
+    test('is null initially', () {
+      expect(document.cachedPlainText, isNull);
+    });
+
+    test('updates to null when undo is called', () {
+      document.cachedPlainText = 'Non-null cached plain text';
+      expect(document.cachedPlainText, isNotNull);
+
+      document.undo();
+      expect(document.cachedPlainText, isNull);
+    });
+
+    test('updates to null when redo is called', () {
+      final document = Document()
+        ..cachedPlainText = 'Non-null cached plain text';
+      expect(document.cachedPlainText, isNotNull);
+
+      document.redo();
+      expect(document.cachedPlainText, isNull);
+    });
+
+    test('returns cachedPlainText if not null', () {
+      const example = 'Hello, World!';
+      document.cachedPlainText = example;
+
+      expect(document.cachedPlainText, example);
+    });
+
+    test('sets cachedPlainText if null when toPlainText is called', () {
+      document.toPlainText();
+      expect(document.cachedPlainText, isNotNull);
+    });
+
+    test('sets cachedPlainText correctly when toPlainText is called', () {
+      const example = 'Hello\n';
+      document = Document.fromDelta(Delta()..insert(example))..toPlainText();
+
+      expect(document.cachedPlainText, isNotNull);
+      expect(document.cachedPlainText, example);
+    });
+
+    test('sets cachedPlainText to null when loadDocument is called', () {
+      document.cachedPlainText = 'Not null';
+      expect(document.cachedPlainText, isNotNull);
+
+      document.loadDocument(Delta()..insert('Hello\n'));
+
+      expect(document.cachedPlainText, isNull);
+    });
+
+    test('sets cachedPlainText to null when compose is called', () {
+      document.cachedPlainText = 'Not null';
+      expect(document.cachedPlainText, isNotNull);
+
+      document.compose(Delta()..insert('Hello\n'), ChangeSource.local);
+
+      expect(document.cachedPlainText, isNull);
+    });
+
+    test('sets cachedPlainText correctly', () {
+      // This test is useful in case this property has a getter and setter.
+      document.cachedPlainText = 'Not null';
+      expect(document.cachedPlainText, isNotNull);
+
+      document.cachedPlainText = null;
+      expect(document.cachedPlainText, isNull);
+    });
+  });
 }