Rename Boilerplate#toHTML to toHTMLStream and deprecate toHTML.

PR #9343 changed the return type of Boilerplate#toHTML from String to
Stream, which is likely to break existing code that expects a string.

In order to make the change in return type more obvious, I have renamed
the method to toHTMLStream, and I have attempted to update all call sites
appropriately. However, because this change comes in the release candidate
phase of Meteor 1.6.1 testing, it seemed important to preserve the
string-returning behavior of toHTML, with a deprecation notice.

Unless third-party code is using the Boilerplate class directly, I don't
think the toHTML method will ever be called, and we can remove it in
Meteor 1.6.2.

Thanks to @macrozone for tracking this problem down.

Fixes #9521.

History.md

@@ -176,6 +176,13 @@
   field). [PR #9311](https://github.com/meteor/meteor/pull/9311) [Issue
   #6890](https://github.com/meteor/meteor/issues/6890)
 
+* The `Boilerplate#toHTML` method from the `boilerplate-generator` package
+  has been deprecated in favor of `toHTMLAsync` (which returns a `Promise`
+  that resolves to a string of HTML) or `toHTMLStream` (which returns a
+  `Stream` of HTML). Although direct usage of `toHTML` is unlikely, please
+  update any code that calls this method if you see deprecation warnings
+  in development. [Issue #9521](https://github.com/meteor/meteor/issues/9521).
+
 * The `npm` package has been upgraded to version 5.6.0, and our fork of
   its `pacote` dependency has been rebased against version 7.0.2.
 

packages/boilerplate-generator-tests/test-lib.js

@@ -52,5 +52,5 @@ export async function generateHTMLForArch(arch) {
     },
   });
 
-  return streamToString(boilerplate.toHTML());
+  return streamToString(boilerplate.toHTMLStream());
 }

packages/boilerplate-generator/generator.js

@@ -18,6 +18,8 @@ function appendToStream(chunk, stream) {
   }
 }
 
+let shouldWarnAboutToHTMLDeprecation = ! Meteor.isProduction;
+
 export class Boilerplate {
   constructor(arch, manifest, options = {}) {
     const { headTemplate, closeTemplate } = _getTemplate(arch);
@@ -31,12 +33,39 @@ export class Boilerplate {
     );
   }
 
+  toHTML(extraData) {
+    if (shouldWarnAboutToHTMLDeprecation) {
+      shouldWarnAboutToHTMLDeprecation = false;
+      console.error(
+        "The Boilerplate#toHTML method has been deprecated. " +
+          "Please use Boilerplate#toHTMLStream instead."
+      );
+      console.trace();
+    }
+
+    // Calling .await() requires a Fiber.
+    return toHTMLAsync(extraData).await();
+  }
+
+  // Returns a Promise that resolves to a string of HTML.
+  toHTMLAsync(extraData) {
+    return new Promise((resolve, reject) => {
+      const stream = this.toHTMLStream(extraData);
+      const chunks = [];
+      stream.on("data", chunk => chunks.push(chunk));
+      stream.on("end", () => {
+        resolve(Buffer.concat(chunks).toString("utf8"));
+      });
+      stream.on("error", reject);
+    });
+  }
+
   // The 'extraData' argument can be used to extend 'self.baseData'. Its
   // purpose is to allow you to specify data that you might not know at
   // the time that you construct the Boilerplate object. (e.g. it is used
   // by 'webapp' to specify data that is only known at request-time).
   // this returns a stream
-  toHTML(extraData) {
+  toHTMLStream(extraData) {
     if (!this.baseData || !this.headTemplate || !this.closeTemplate) {
       throw new Error('Boilerplate did not instantiate correctly.');
     }

packages/webapp/webapp_server.js

@@ -306,7 +306,7 @@ function getBoilerplateAsync(request, arch) {
   });
 
   return promise.then(() => ({
-    stream: boilerplate.toHTML(data),
+    stream: boilerplate.toHTMLStream(data),
     statusCode: data.statusCode,
     headers: data.headers,
   }));

packages/webapp/webapp_tests.js

@@ -158,7 +158,7 @@ Tinytest.addAsync(
       { runtimeConfigOverrides: { WEBAPP_TEST_KEY: true } }
     );
 
-    const stream = boilerplate.toHTML();
+    const stream = boilerplate.toHTMLStream();
     const boilerplateHtml = await streamToString(stream)
     test.isFalse(boilerplateHtml.indexOf("WEBAPP_TEST_KEY") === -1);
 

tools/cordova/builder.js

@@ -406,7 +406,10 @@ export class CordovaBuilder {
     // Write program.json
     files.writeFile(programJsonPath, JSON.stringify(program), 'utf8');
 
-    const bootstrapPage = this.generateBootstrapPage(applicationPath, program, publicSettings);
+    const bootstrapPage = this.generateBootstrapPage(
+      applicationPath, program, publicSettings
+    ).await();
+
     files.writeFile(files.pathJoin(applicationPath, 'index.html'),
       bootstrapPage, 'utf8');
   }
@@ -460,7 +463,7 @@ export class CordovaBuilder {
       }
     });
 
-    return boilerplate.toHTML();
+    return boilerplate.toHTMLAsync();
   }
 
   copyBuildOverride() {