feat: #508 - Expose Node.forgetDescendants.

docs/manipulation/performance.md

@@ -86,6 +86,9 @@ The main way to improve performance when manipulating, is to "forget" a node whe
 
 ```ts setup: let personInterface: InterfaceDeclaration;
 personInterface.forget();
+
+// or to only forget a node's descendants that are currently in the wrapped cache
+sourceFile.forgetDescendants();
 ```
 
 That will stop tracking the node and all its previously navigated descendants (ex. in this case, `nameProperty` as well).

lib/ts-simple-ast.d.ts

@@ -4191,6 +4191,10 @@ export declare class Node<NodeType extends ts.Node = ts.Node> {
      * This is useful if you want to improve the performance of manipulation by not tracking this node anymore.
      */
     forget(): void;
+    /**
+     * Forgets the descendants of this node.
+     */
+    forgetDescendants(): this;
     /**
      * Gets if the compiler node was forgotten.
      *
@@ -8188,11 +8192,21 @@ export interface StatementedNode {
      * Gets the direct variable statement children.
      */
     getVariableStatements(): VariableStatement[];
+    /**
+     * Gets a variable statement.
+     * @param name - Name of one of the variable statement's declarations.
+     */
+    getVariableStatement(name: string): VariableStatement | undefined;
     /**
      * Gets a variable statement.
      * @param findFunction - Function to use to find the variable statement.
      */
     getVariableStatement(findFunction: (declaration: VariableStatement) => boolean): VariableStatement | undefined;
+    /**
+     * Gets a variable statement or throws if it doesn't exist.
+     * @param name - Name of one of the variable statement's declarations.
+     */
+    getVariableStatementOrThrow(name: string): VariableStatement;
     /**
      * Gets a variable statement or throws if it doesn't exist.
      * @param findFunction - Function to use to find the variable statement.

src/compiler/ast/common/Node.ts

@@ -106,17 +106,18 @@ export class Node<NodeType extends ts.Node = ts.Node> {
         if (this.wasForgotten())
             return;
 
-        this._forgetChildren();
+        this.forgetDescendants();
         this._forgetOnlyThis();
     }
 
     /**
-     * Forgets the children of this node.
-     * @internal
+     * Forgets the descendants of this node.
      */
-    _forgetChildren() {
+    forgetDescendants() {
         for (const child of this._getChildrenInCacheIterator())
             child.forget();
+
+        return this;
     }
 
     /**

src/compiler/ast/module/SourceFile.ts

@@ -736,7 +736,7 @@ export class SourceFile extends SourceFileBase<ts.SourceFile> {
      * @param textChanges - Text changes.
      */
     applyTextChanges(textChanges: ReadonlyArray<TextChange>) {
-        this._forgetChildren();
+        this.forgetDescendants();
         replaceNodeText({
             sourceFile: this._sourceFile,
             start: 0,

src/tests/compiler/common/nodeTests.ts

@@ -1542,6 +1542,17 @@ class MyClass {
         });
     });
 
+    describe(nameof<Node>(n => n.forgetDescendants), () => {
+        it("should only forget the descendants", () => {
+            const { firstChild } = getInfoFromText<EnumDeclaration>("enum MyEnum { member }");
+            const member = firstChild.getMembers()[0];
+            firstChild.forgetDescendants();
+            expect(member.wasForgotten()).to.be.true;
+            expect(firstChild.wasForgotten()).to.be.false;
+            expect(() => member.compilerNode).to.throw(errors.InvalidOperationError, getExpectedForgottenMessage("member"));
+        });
+    });
+
     describe(nameof<Node>(n => n.getNonWhitespaceStart), () => {
         function doTest(text: string, selectNode: (sourceFile: SourceFile) => Node, expected: number) {
             const { sourceFile } = getInfoFromText(text);