Set file.result when processing to non-text

wooorm · web-flow · commit c3ba172708e7 · 2020-03-29T19:18:29.000+02:00
unified is typically, but not always, used to *serialize* when it compiles. Compilers don’t always return such a serialized `string` or `Buffer` though. The previous behavior was to place the result of the stringify phase when processing on `file.contents`. This doesn’t make sense for non-text. This change places non-text results on `file.result`. Closes vfile/vfile#45. Closes GH-87.
diff --git a/index.js b/index.js
@@ -1,10 +1,11 @@
 'use strict'
 
-var extend = require('extend')
 var bail = require('bail')
-var vfile = require('vfile')
-var trough = require('trough')
+var buffer = require('is-buffer')
+var extend = require('extend')
 var plain = require('is-plain-obj')
+var trough = require('trough')
+var vfile = require('vfile')
 
 // Expose a frozen processor.
 module.exports = unified().freeze()
@@ -37,7 +38,16 @@ function pipelineRun(p, ctx, next) {
 }
 
 function pipelineStringify(p, ctx) {
-  ctx.file.contents = p.stringify(ctx.tree, ctx.file)
+  var result = p.stringify(ctx.tree, ctx.file)
+  var file = ctx.file
+
+  if (result === undefined || result === null) {
+    // Empty.
+  } else if (typeof result === 'string' || buffer(result)) {
+    file.contents = result
+  } else {
+    file.result = result
+  }
 }
 
 // Function to create the first processor.
diff --git a/package.json b/package.json
@@ -45,6 +45,7 @@
   "dependencies": {
     "bail": "^1.0.0",
     "extend": "^3.0.0",
+    "is-buffer": "^2.0.0",
     "is-plain-obj": "^2.0.0",
     "trough": "^1.0.0",
     "vfile": "^4.0.0"
diff --git a/readme.md b/readme.md
@@ -461,7 +461,7 @@ return a [`Node`][node].
 
 ### `processor.stringify(node[, file])`
 
-Compile a [*syntax tree*][syntax-tree] to text.
+Compile a [*syntax tree*][syntax-tree].
 
 ###### Parameters
 
@@ -471,7 +471,7 @@ Compile a [*syntax tree*][syntax-tree] to text.
 
 ###### Returns
 
-`string` (see notes) — Textual representation of the [*syntax
+`string` or `Buffer` (see notes) — Textual representation of the [*syntax
 tree*][syntax-tree]
 
 ###### Note
@@ -481,10 +481,11 @@ tree*][syntax-tree]
 `stringify` performs the [*stringify phase*][description], not the *run phase*
 or other phases.
 
-Be aware that [*compiler*][compiler]s typically, but not always, return
-`string`.
+unified typically compiles by serializing: most [*compiler*][compiler]s return
+`string` (or `Buffer`).
 Some compilers, such as the one configured with [`rehype-react`][rehype-react],
 return other values (in this case, a React tree).
+If you’re using a compiler doesn’t serialize, expect different result values.
 When using TypeScript, cast the type on your side.
 
 ###### Example
@@ -632,7 +633,7 @@ The returned promise is rejected with a fatal error, or resolved with the
 processed [*file*][file].
 
 The parsed, transformed, and compiled value is exposed on
-[`file.contents`][vfile-contents].
+[`file.contents`][vfile-contents] or `file.result` (see notes).
 
 ###### Note
 
@@ -647,6 +648,14 @@ return other values (in this case, a React tree).
 When using TypeScript, cast the type of [`file.contents`][vfile-contents] on
 your side.
 
+unified typically compiles by serializing: most [*compiler*][compiler]s return
+`string` (or `Buffer`).
+Some compilers, such as the one configured with [`rehype-react`][rehype-react],
+return other values (in this case, a React tree).
+If you’re using a compiler that serializes, the result is available at
+`file.contents`.
+Otherwise, the result is available at `file.result`.
+
 ###### Example
 
 The below example shows how `process` can be used to process a file, whether
@@ -750,19 +759,23 @@ An error is thrown if asynchronous [*plugin*][plugin]s are configured.
 
 ([`VFile`][vfile]) — Processed [*file*][file]
 
+The parsed, transformed, and compiled value is exposed on
+[`file.contents`][vfile-contents] or `file.result` (see notes).
+
 ###### Note
 
 `processSync` freezes the processor if not already [*frozen*][freeze].
 
 `processSync` performs the [*parse*, *run*, and *stringify*
 phases][description].
 
-Be aware that [*compiler*][compiler]s typically, but not always, return
-`string`.
+unified typically compiles by serializing: most [*compiler*][compiler]s return
+`string` (or `Buffer`).
 Some compilers, such as the one configured with [`rehype-react`][rehype-react],
 return other values (in this case, a React tree).
-When using TypeScript, cast the type of [`file.contents`][vfile-contents] on
-your side.
+If you’re using a compiler that serializes, the result is available at
+`file.contents`.
+Otherwise, the result is available at `file.result`.
 
 ###### Example
 
diff --git a/test/process.js b/test/process.js
@@ -204,3 +204,80 @@ test('processSync(file)', function (t) {
     'should pass the result file'
   )
 })
+
+test('compilers', function (t) {
+  t.plan(4)
+
+  t.equal(
+    unified()
+      .use(function () {
+        this.Parser = simple.Parser
+        this.Compiler = string
+      })
+      .processSync('alpha').contents,
+    'bravo',
+    'should compile strings'
+  )
+
+  t.deepEqual(
+    unified()
+      .use(function () {
+        this.Parser = simple.Parser
+        this.Compiler = buffer
+      })
+      .processSync('alpha').contents,
+    Buffer.from('bravo'),
+    'should compile buffers'
+  )
+
+  t.deepEqual(
+    unified()
+      .use(function () {
+        this.Parser = simple.Parser
+        this.Compiler = nully
+      })
+      .processSync('alpha').contents,
+    'alpha',
+    'should compile null'
+  )
+
+  t.deepEqual(
+    unified()
+      .use(function () {
+        this.Parser = simple.Parser
+        this.Compiler = nonText
+      })
+      .processSync('alpha').result,
+    {
+      _owner: null,
+      type: 'p',
+      ref: null,
+      key: 'h-1',
+      props: {children: ['bravo']}
+    },
+    'should compile non-text'
+  )
+
+  function nully() {
+    return null
+  }
+
+  function string() {
+    return 'bravo'
+  }
+
+  function buffer() {
+    return Buffer.from('bravo')
+  }
+
+  function nonText() {
+    // Somewhat like a React node.
+    return {
+      _owner: null,
+      type: 'p',
+      ref: null,
+      key: 'h-1',
+      props: {children: ['bravo']}
+    }
+  }
+})
