feat(index): Add createDocumentStream (#1510)

src/__snapshots__/index.spec.ts.snap

@@ -1,5 +1,21 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`Index createDocumentStream 1`] = `
+Document {
+  "children": [
+    &This is text,
+    <!-- and comments -->,
+    <tags />,
+  ],
+  "endIndex": null,
+  "next": null,
+  "parent": null,
+  "prev": null,
+  "startIndex": null,
+  "type": "root",
+}
+`;
+
 exports[`Index createDomStream 1`] = `
 [
   &This is text,

src/index.spec.ts

@@ -1,6 +1,7 @@
 import {
     parseDocument,
     parseDOM,
+    createDocumentStream,
     createDomStream,
     DomHandler,
     DefaultHandler,
@@ -30,6 +31,21 @@ describe("Index", () => {
         expect(dom).toMatchSnapshot();
     });
 
+    test("createDocumentStream", (done) => {
+        const domStream = createDocumentStream((error, dom) => {
+            expect(error).toBeNull();
+            expect(dom).toMatchSnapshot();
+
+            done();
+        });
+
+        for (const c of "&amp;This is text<!-- and comments --><tags>") {
+            domStream.write(c);
+        }
+
+        domStream.end();
+    });
+
     test("createDomStream", (done) => {
         const domStream = createDomStream((error, dom) => {
             expect(error).toBeNull();

src/index.ts

@@ -24,7 +24,7 @@ export type Options = ParserOptions & DomHandlerOptions;
  * Parses the data, returns the resulting document.
  *
  * @param data The data that should be parsed.
- * @param options Optional options for the parser and DOM builder.
+ * @param options Optional options for the parser and DOM handler.
  */
 export function parseDocument(data: string, options?: Options): Document {
     const handler = new DomHandler(undefined, options);
@@ -38,7 +38,7 @@ export function parseDocument(data: string, options?: Options): Document {
  * Use `parseDocument` to get the `Document` node instead.
  *
  * @param data The data that should be parsed.
- * @param options Optional options for the parser and DOM builder.
+ * @param options Optional options for the parser and DOM handler.
  * @deprecated Use `parseDocument` instead.
  */
 export function parseDOM(data: string, options?: Options): ChildNode[] {
@@ -47,10 +47,30 @@ export function parseDOM(data: string, options?: Options): ChildNode[] {
 /**
  * Creates a parser instance, with an attached DOM handler.
  *
- * @param callback A callback that will be called once parsing has been completed.
- * @param options Optional options for the parser and DOM builder.
+ * @param callback A callback that will be called once parsing has been completed, with the resulting document.
+ * @param options Optional options for the parser and DOM handler.
  * @param elementCallback An optional callback that will be called every time a tag has been completed inside of the DOM.
  */
+export function createDocumentStream(
+    callback: (error: Error | null, document: Document) => void,
+    options?: Options,
+    elementCallback?: (element: Element) => void
+): Parser {
+    const handler: DomHandler = new DomHandler(
+        (error: Error | null) => callback(error, handler.root),
+        options,
+        elementCallback
+    );
+    return new Parser(handler, options);
+}
+/**
+ * Creates a parser instance, with an attached DOM handler.
+ *
+ * @param callback A callback that will be called once parsing has been completed, with an array of root nodes.
+ * @param options Optional options for the parser and DOM handler.
+ * @param elementCallback An optional callback that will be called every time a tag has been completed inside of the DOM.
+ * @deprecated Use `createDocumentStream` instead.
+ */
 export function createDomStream(
     callback: (error: Error | null, dom: ChildNode[]) => void,
     options?: Options,