Added explanation for wait until available #57

Author: FlorianRappl

README.md

@@ -33,6 +33,24 @@ var config = Configuration.Default
 
 in the previous example `MyConsoleLogger` refers to a class implementing the `IConsoleLogger` interface. Examples of classes implementing this interface are available in our [samples repository](https://github.com/AngleSharp/AngleSharp.Samples).
 
+## Extension Methods
+
+This plugin also delivers some extension methods to be used together with elements from AngleSharp, e.g., `IDocument` or `IElement`.
+
+For instance, the following waits until a stable point has been reached (and the document is fully available):
+
+```cs
+var context = BrowsingContext.New(config);
+var document = await context.OpenAsync(address)
+    .WaitUntilAvailable();
+```
+
+Scripts can also be run in the context of the document, where the result of the last expression is returned:
+
+```cs
+var numEntries = document.ExecuteScript("document.querySelectorAll('div').length");
+```
+
 ## Vision and Status
 
 The repository contains DOM bindings for the *Jint* JavaScript engine. *Jint* is fully ECMAScript 5 compatible and provides the basis for evaluating JavaScripts in the context of the AngleSharp DOM representation.

src/AngleSharp.Js/JsDocumentExtensions.cs

@@ -3,6 +3,7 @@ namespace AngleSharp.Dom
     using AngleSharp.Browser;
     using AngleSharp.Js;
     using System;
+    using System.Threading;
     using System.Threading.Tasks;
 
     /// <summary>
@@ -92,5 +93,39 @@ public static Task<IDocument> WhenStable(this IDocument document) =>
         /// <returns>A task that is finished when the enqueued tasks completed.</returns>
         public static Task<IDocument> WhenStable(this Task<IDocument> documentTask) =>
             documentTask.Then(_ => { });
+
+        /// <summary>
+        /// Waits until the document from the task is fully available.
+        /// This includes that the document is completed and that a stable
+        /// point has been reached.
+        /// </summary>
+        /// <param name="documentTask">The document task to await.</param>
+        /// <param name="cancellation">The timeout cancellation, if any.</param>
+        /// <returns>A task that is finished when the document is available.</returns>
+        public static async Task WaitUntilAvailable(this Task<IDocument> documentTask, CancellationToken cancellation = default)
+        {
+            var document = await documentTask.ConfigureAwait(false);
+            await document.WaitUntilAvailable(cancellation).ConfigureAwait(false);
+        }
+
+        /// <summary>
+        /// Waits until the document is fully available. This includes
+        /// that the document is completed and that a stable point has
+        /// been reached.
+        /// </summary>
+        /// <param name="document">The document to await.</param>
+        /// <param name="cancellation">The timeout cancellation, if any.</param>
+        /// <returns>A task that is finished when the document is available.</returns>
+        public static async Task WaitUntilAvailable(this IDocument document, CancellationToken cancellation = default)
+        {
+            if (document.ReadyState != DocumentReadyState.Complete)
+            {
+                var abort = new TaskCompletionSource<object>();
+                cancellation.Register(() => abort.TrySetCanceled());
+                await Task.WhenAny(document.AwaitEventAsync("load"), abort.Task).ConfigureAwait(false);
+            }
+
+            await document.WhenStable().ConfigureAwait(false);
+        }
     }
 }