Change result to be a single hast root

core.js

@@ -13,9 +13,11 @@
  * @property {Object.<string, string>} attributes
  * @property {string} language
  *
+ * @typedef {import('hast').Root} Root
  * @typedef {import('hast').Element} Element
  * @typedef {import('hast').Text} Text
  * @typedef {Omit<Element, 'children'> & {children: Array.<RefractorElement|Text>}} RefractorElement
+ * @typedef {Omit<Root, 'children'> & {children: Array.<RefractorElement|Text>}} RefractorRoot
  *
  * @typedef {import('prismjs').Languages} Languages
  * @typedef {import('prismjs').Grammar} Grammar Whatever this is, Prism handles it.
@@ -150,7 +152,7 @@ function alias(name, alias) {
  *
  * @param {string} value
  * @param {string|Grammar} nameOrGrammar
- * @returns {Array.<RefractorElement|Text>}
+ * @returns {RefractorRoot}
  */
 function highlight(value, nameOrGrammar) {
   /** @type {Grammar} */
@@ -181,7 +183,10 @@ function highlight(value, nameOrGrammar) {
     }
   }
 
-  return Prism.highlight.call(refractor, value, grammar, name)
+  return {
+    type: 'root',
+    children: Prism.highlight.call(refractor, value, grammar, name)
+  }
 }
 
 /**

index.js

@@ -1,3 +1,10 @@
+/**
+ * @typedef {import('./core.js').RefractorRoot} RefractorRoot
+ * @typedef {import('./core.js').RefractorElement} RefractorElement
+ * @typedef {import('./core.js').Text} Text
+ * @typedef {import('./core.js').Grammar} Grammar
+ * @typedef {import('./core.js').Syntax} Syntax
+ */
 import {refractor} from './core.js'
 import markup from './lang/markup.js'
 import css from './lang/css.js'

package.json

@@ -41,7 +41,8 @@
     "index.js"
   ],
   "dependencies": {
-    "@types/prismjs": "^1.16.5",
+    "@types/hast": "^2.0.0",
+    "@types/prismjs": "^1.0.0",
     "hastscript": "^7.0.0",
     "parse-entities": "^3.0.0",
     "prismjs": "~1.23.0"

readme.md

@@ -54,33 +54,35 @@ npm install refractor
 ```js
 import {refractor} from 'refractor'
 
-var nodes = refractor.highlight('"use strict";', 'js')
+var root = refractor.highlight('"use strict";', 'js')
 
-console.log(nodes)
+console.log(root)
 ```
 
 Yields:
 
 ```js
-[
-  {
-    type: 'element',
-    tagName: 'span',
-    properties: {className: ['token', 'string']},
-    children: [{type: 'text', value: '"use strict"'}]
-  },
-  {
-    type: 'element',
-    tagName: 'span',
-    properties: {className: ['token', 'punctuation']},
-    children: [{type: 'text', value: ';'}]
-  }
-]
+{
+  type: 'root',
+  children: [
+    {
+      type: 'element',
+      tagName: 'span',
+      properties: {className: ['token', 'string']},
+      children: [{type: 'text', value: '"use strict"'}]
+    },
+    {
+      type: 'element',
+      tagName: 'span',
+      properties: {className: ['token', 'punctuation']},
+      children: [{type: 'text', value: ';'}]
+    }
+  ]
+}
 ```
 
-Which serialized with [`rehype`][rehype] or [`hast-util-to-html`][to-html]
-yields (you may have to wrap it into a fragment like so: `{type: 'root',
-children: nodes}`):
+Which serialized with [`hast-util-to-html`][to-html] (or [`rehype`][rehype])
+yields:
 
 ```html
 <span class="token string">"use strict"</span><span class="token punctuation">;</span>
@@ -113,14 +115,12 @@ console.log(refractor.highlight('*Emphasis*', 'markdown'))
 Yields:
 
 ```js
-[
-  {
-    type: 'element',
-    tagName: 'span',
-    properties: {className: [Array]},
-    children: [[Object], [Object], [Object]]
-  }
-]
+{
+  type: 'root',
+  children: [
+    {type: 'element', tagName: 'span', properties: [Object], children: [Array]}
+  ]
+}
 ```
 
 ### `refractor.alias(name[, alias])`
@@ -163,36 +163,31 @@ syntax.
 
 ###### Returns
 
-Virtual nodes representing the highlighted value ([`Array.<Node>`][node]).
+Virtual node representing the highlighted value ([`Root`][root]).
 
 ###### Example
 
 ```js
 import {refractor} from 'refractor/core.js'
+import css from 'refractor/lang/css.js'
 
+refractor.register(css)
 console.log(refractor.highlight('em { color: red }', 'css'))
 ```
 
 Yields:
 
 ```js
-[
-  {
-    type: 'element',
-    tagName: 'span',
-    properties: {className: [Array]},
-    children: [[Object]]
-  },
-  {type: 'text', value: ' '},
-  // …
-  {type: 'text', value: ' red '},
-  {
-    type: 'element',
-    tagName: 'span',
-    properties: {className: [Array]},
-    children: [[Object]]
-  }
-]
+{
+  type: 'root',
+  children: [
+    {type: 'element', tagName: 'span', properties: [Object], children: [Array]},
+    {type: 'text', value: ' '},
+    // …
+    {type: 'text', value: ' red '},
+    {type: 'element', tagName: 'span', properties: [Object], children: [Array]}
+  ]
+}
 ```
 
 ### `refractor.registered(language)`
@@ -203,7 +198,7 @@ Check if a `language` ([name or alias][syntax]) is registered.
 
 ```js
 import {refractor} from 'refractor/core.js'
-import {markdown} from 'refractor/lang/markdown.js'
+import markdown from 'refractor/lang/markdown.js'
 
 console.log(refractor.registered('markdown'))
 
@@ -231,7 +226,7 @@ List all registered languages ([names and aliases][syntax]).
 
 ```js
 import {refractor} from 'refractor/core.js'
-import {markdown} from 'refractor/lang/markdown.js'
+import markdown from 'refractor/lang/markdown.js'
 
 console.log(refractor.listLanguages())
 
@@ -243,19 +238,11 @@ console.log(refractor.listLanguages())
 Yields:
 
 ```js
+[]
 [
-  'markup',
-  'html',
-  // …
-  'javascript',
-  'js'
-]
-[
-  'markup',
+  'markup', // Note that `markup` (a lot of xml based languages) is a dep of markdown.
   'html',
   // …
-  'javascript',
-  'js',
   'markdown',
   'md'
 ]
@@ -605,7 +592,7 @@ syntaxes are made to work with global variables and are not requirable.
 
 [hljs]: https://github.com/isagalaev/highlight.js
 
-[node]: https://github.com/syntax-tree/hast#ast
+[root]: https://github.com/syntax-tree/hast#root
 
 [syntax]: #syntaxes
 

script/list.js

@@ -20,6 +20,13 @@ var names = getLoader(
 fs.writeFile(
   'index.js',
   [
+    '/**',
+    " * @typedef {import('./core.js').RefractorRoot} RefractorRoot",
+    " * @typedef {import('./core.js').RefractorElement} RefractorElement",
+    " * @typedef {import('./core.js').Text} Text",
+    " * @typedef {import('./core.js').Grammar} Grammar",
+    " * @typedef {import('./core.js').Syntax} Syntax",
+    ' */',
     "import {refractor} from './core.js'",
     ...names.map(
       (lang) => 'import ' + camelcase(lang) + " from './lang/" + lang + ".js'"

test/index.js

@@ -1,5 +1,6 @@
 /**
  * @typedef {import('../core.js').Syntax} Syntax
+ * @typedef {import('hast').Node} Node
  */
 
 import fs from 'fs'
@@ -48,13 +49,13 @@ test('.highlight(value, language)', function (t) {
 
   t.deepEqual(
     refractor.highlight('', 'js'),
-    [],
+    {type: 'root', children: []},
     'should return an empty array when given an empty `value`'
   )
 
   t.deepEqual(
     refractor.highlight('# foo', 'js'),
-    [{type: 'text', value: '# foo'}],
+    {type: 'root', children: [{type: 'text', value: '# foo'}]},
     'should silently ignore illegals'
   )
 
@@ -181,8 +182,12 @@ test('fixtures', function (t) {
     ).trim()
 
     t.deepEqual(
-      refractor.highlight(input, lang),
-      removePosition(processor.parse(expected), true).children,
+      Object.assign(refractor.highlight(input, lang), {
+        data: undefined
+      }),
+      Object.assign(removePosition(processor.parse(expected), true), {
+        data: undefined
+      }),
       name
     )
   }