Use WeakRef if available to allow GC to collect Range instances

Author: bwrrp

README.md

@@ -43,7 +43,7 @@ const xml = slimdom.serializeToWellFormedString(document);
 
 Some DOM API's, such as the `DocumentFragment` constructor, require the presence of a global document, for instance to set their initial `ownerDocument` property. In these cases, slimdom will use the instance exposed through `slimdom.document`. Although you could mutate this document, it is recommended to always create your own documents (using the `Document` constructor) to avoid conflicts with other code using slimdom in your application.
 
-When using a `Range`, make sure to call `detach` when you don't need it anymore. As we do not have a way to detect when a Range is no longer used, this library needs to be notified when it can stop updating the range for mutations to the surrounding nodes.
+When using a `Range`, make sure to call `detach` when you don't need it anymore. Unless you are only targeting environments that implement the WeakRef proposal, we do not have a way to detect when we can stop updating the range for mutations to the surrounding nodes. In environments that support WeakRef, calling detach is optional.
 
 ## Features and limitations
 

api/slimdom.api.json

@@ -9301,7 +9301,7 @@
             {
               "kind": "Method",
               "canonicalReference": "slimdom!Range#detach:member(1)",
-              "docComment": "/**\n * Stops tracking the range.\n *\n * (non-standard) According to the spec, this method must do nothing. However, as it is not possible to rely on garbage collection to determine when to stop updating a range for node mutations, this implementation requires calling detach to stop such updates from affecting the range.\n */\n",
+              "docComment": "/**\n * Stops tracking the range.\n *\n * (non-standard) According to the spec, this method must do nothing. However, it is not yet possible in all browsers to allow garbage collection while keeping track of active ranges to be updated by mutations. Therefore, unless your code will only run in environments that implement the WeakRef proposal (https://github.com/tc39/proposal-weakrefs), make sure to call this method to stop updating the range and free up its resources.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",

src/CharacterData.ts

@@ -251,7 +251,7 @@ export function replaceData(
 	(node as any)._data = newData;
 
 	const context = getContext(node);
-	context._ranges.forEach((range) => {
+	context.forEachRange((range) => {
 		// 8. For each live range whose start node is node and start offset is greater than offset
 		// but less than or equal to offset plus count, set its start offset to offset.
 		if (

src/Node.ts

@@ -188,7 +188,7 @@ export default abstract class Node {
 				const currentNode = siblingsToRemove[i];
 				const currentNodeIndex = index + i + 1;
 
-				context._ranges.forEach((range) => {
+				context.forEachRange((range) => {
 					// 6.1. For each live range whose start node is currentNode, add length to its
 					// start offset and set its start node to node.
 					if (range.startContainer === currentNode) {

src/Range.ts

@@ -1,4 +1,3 @@
-import Document from './Document';
 import Node from './Node';
 import { getContext } from './context/Context';
 import {
@@ -12,7 +11,6 @@ import { NodeType, isNodeOfType } from './util/NodeType';
 import {
 	determineLengthOfNode,
 	getInclusiveAncestors,
-	getNodeDocument,
 	getNodeIndex,
 	getRootOfNode,
 } from './util/treeHelpers';
@@ -98,7 +96,7 @@ export default class Range implements AbstractRange {
 		this.startOffset = 0;
 		this.endContainer = context.document;
 		this.endOffset = 0;
-		context._ranges.push(this);
+		context.addRange(this);
 	}
 
 	/**
@@ -443,17 +441,15 @@ export default class Range implements AbstractRange {
 	/**
 	 * Stops tracking the range.
 	 *
-	 * (non-standard) According to the spec, this method must do nothing. However, as it is not
-	 * possible to rely on garbage collection to determine when to stop updating a range for node
-	 * mutations, this implementation requires calling detach to stop such updates from affecting
-	 * the range.
+	 * (non-standard) According to the spec, this method must do nothing. However, it is not yet
+	 * possible in all browsers to allow garbage collection while keeping track of active ranges to
+	 * be updated by mutations. Therefore, unless your code will only run in environments that
+	 * implement the WeakRef proposal (https://github.com/tc39/proposal-weakrefs), make sure to call
+	 * this method to stop updating the range and free up its resources.
 	 */
 	detach(): void {
 		const context = getContext(this);
-		const index = context._ranges.indexOf(this);
-		if (index >= 0) {
-			context._ranges.splice(index, 1);
-		}
+		context.removeRange(this);
 	}
 
 	/**

src/Text.ts

@@ -140,7 +140,7 @@ function splitText(node: Text, offset: number): Text {
 
 		const indexOfNodePlusOne = getNodeIndex(node) + 1;
 		const context = getContext(node);
-		context._ranges.forEach((range) => {
+		context.forEachRange((range) => {
 			// 7.2. For each live range whose start node is node and start offset is greater than
 			// offset, set its start node to new node and decrease its start offset by offset.
 			if (range.startContainer === node && range.startOffset > offset) {

src/context/Context.ts

@@ -13,7 +13,8 @@ import Text from '../Text';
 import XMLDocument from '../XMLDocument';
 
 import NotifySet from '../mutation-observer/NotifyList';
-import { NodeType } from '../util/NodeType';
+
+import { createWeakRef, WeakRef } from './WeakRef';
 
 export type AttrConstructor = new (
 	namespace: string | null,
@@ -49,7 +50,6 @@ export interface Context {
 	document: Document;
 
 	_notifySet: NotifySet;
-	_ranges: Range[];
 
 	Attr: AttrConstructor;
 	CDATASection: CDATASectionConstructor;
@@ -63,6 +63,10 @@ export interface Context {
 	Range: RangeConstructor;
 	Text: TextConstructor;
 	XMLDocument: XMLDocumentConstructor;
+
+	forEachRange(cb: (range: Range) => void): void;
+	addRange(range: Range): void;
+	removeRange(range: Range): void;
 }
 
 /**
@@ -79,7 +83,6 @@ export class DefaultContext implements Context {
 	 * invoking their callbacks when control returns to the event loop.
 	 */
 	public _notifySet: NotifySet = new NotifySet();
-	public _ranges: Range[] = [];
 
 	public Attr!: AttrConstructor;
 	public CDATASection!: CDATASectionConstructor;
@@ -93,6 +96,39 @@ export class DefaultContext implements Context {
 	public Range!: RangeConstructor;
 	public Text!: TextConstructor;
 	public XMLDocument!: XMLDocumentConstructor;
+
+	private _ranges: WeakRef<Range>[] = [];
+
+	public forEachRange(cb: (range: Range) => void): void {
+		let numRanges = this._ranges.length;
+		for (let i = numRanges - 1; i >= 0; --i) {
+			const r = this._ranges[i].deref();
+			if (r === undefined) {
+				// Weak ref lost, remove
+				this._ranges[i] = this._ranges[numRanges - 1];
+				this._ranges.pop();
+				numRanges -= 1;
+			} else {
+				cb(r);
+			}
+		}
+	}
+
+	public addRange(range: Range): void {
+		this._ranges.push(createWeakRef(range));
+	}
+
+	public removeRange(range: Range): void {
+		let numRanges = this._ranges.length;
+		for (let i = numRanges - 1; i >= 0; --i) {
+			const r = this._ranges[i].deref();
+			if (r === undefined || r === range) {
+				this._ranges[i] = this._ranges[numRanges - 1];
+				this._ranges.pop();
+				numRanges -= 1;
+			}
+		}
+	}
 }
 
 // TODO: make it possible to create multiple contexts by binding constructors to each instance

src/context/WeakRef.ts

@@ -0,0 +1,28 @@
+// TODO: remove when interface is included in dom.d.ts typings
+export interface WeakRef<T> {
+	deref(): T | undefined;
+}
+interface WeakRefConstructor<T> {
+	new (target: T): WeakRef<T>;
+}
+declare var WeakRef: WeakRefConstructor<any>;
+
+class FakeWeakRef<T> implements WeakRef<T> {
+	private _target: T;
+
+	constructor(target: T) {
+		this._target = target;
+	}
+
+	public deref(): T {
+		return this._target;
+	}
+}
+
+export function createWeakRef<T>(target: T): WeakRef<T> {
+	if (typeof WeakRef === 'function') {
+		return new WeakRef(target);
+	}
+
+	return new FakeWeakRef(target);
+}

src/util/mutationAlgorithms.ts

@@ -213,7 +213,7 @@ export function insertNode(
 	if (child !== null) {
 		const childIndex = getNodeIndex(child);
 		const context = getContext(node);
-		context._ranges.forEach((range) => {
+		context.forEachRange((range) => {
 			// 2.1. For each live range whose start node is parent and start offset is greater than
 			// child’s index, increase its start offset by count.
 			if (range.startContainer === parent && range.startOffset > childIndex) {
@@ -581,7 +581,7 @@ export function removeNode(node: Node, parent: Node, suppressObservers: boolean
 	const index = getNodeIndex(node);
 
 	const context = getContext(node);
-	context._ranges.forEach((range) => {
+	context.forEachRange((range) => {
 		// 2. For each live range whose start node is an inclusive descendant of node, set its start
 		// to (parent, index).
 		if (node.contains(range.startContainer)) {

test/Range.tests.ts

@@ -389,4 +389,60 @@ describe('Range', () => {
 			});
 		});
 	});
+
+	describe('WeakRef', () => {
+		describe('fallback for older environments', () => {
+			let oldWeakRef: any;
+			beforeAll(() => {
+				oldWeakRef = (global as any).WeakRef;
+				delete (global as any).WeakRef;
+			});
+			afterAll(() => {
+				(global as any).WeakRef = oldWeakRef;
+			});
+
+			it('still works in older environments that do not support WeakRef', () => {
+				range.selectNode(element);
+				document.removeChild(element);
+				expect(range.startOffset).toBe(0);
+				expect(range.endOffset).toBe(0);
+				range.detach();
+			});
+		});
+
+		describe('automatic cleanup', () => {
+			// We can't force GC, so let's do the next best thing and stub WeakRef instead so we can
+			// at least test the code that handles the deref returning undefined
+			let oldWeakRef: any;
+			let isFakeGarbageCollected: boolean;
+			beforeAll(() => {
+				oldWeakRef = (global as any).WeakRef;
+				(global as any).WeakRef = class StubWeakRef<T> {
+					constructor(private target: T) {}
+					deref(): T | undefined {
+						if (isFakeGarbageCollected) {
+							return undefined;
+						}
+						return this.target;
+					}
+				};
+			});
+			afterAll(() => {
+				(global as any).WeakRef = oldWeakRef;
+			});
+
+			beforeEach(() => {
+				isFakeGarbageCollected = false;
+			});
+
+			it('uses WeakRef if available to automatically clean up', () => {
+				range.selectNode(element);
+				isFakeGarbageCollected = true;
+				document.removeChild(element);
+				// Range should not have been updated because our fake WeakRef said it was GC'ed
+				expect(range.startOffset).toBe(0);
+				expect(range.endOffset).toBe(1);
+			});
+		});
+	});
 });