Change parameter order

Author: wooorm

lib/index.js

@@ -24,18 +24,17 @@ import {location} from 'vfile-location'
 
 const search = /\r?\n|\r/g
 
-// To do: change parameter order, to allow `value` to be missing.
 /**
  * Get the source of a node or at a position.
  *
- * @param {Node | NodeLike | Position | PositionLike | null | undefined} value
- *   Value to get.
  * @param {VFile | VFileValue} file
  *   File in which `value` exists.
+ * @param {Node | NodeLike | Position | PositionLike | null | undefined} value
+ *   Value to get.
  * @returns {string | undefined}
  *   Source of `value` in `doc`, if available.
  */
-export function source(value, file) {
+export function source(file, value) {
   const doc = String(file)
   const loc = location(file)
   const position =

readme.md

@@ -17,7 +17,7 @@
 *   [Install](#install)
 *   [Use](#use)
 *   [API](#api)
-    *   [`source(value, file)`](#sourcevalue-file)
+    *   [`source(file[, value])`](#sourcefile-value)
 *   [Types](#types)
 *   [Compatibility](#compatibility)
 *   [Contribute](#contribute)
@@ -67,15 +67,15 @@ Say our document `example.md` contains:
 …and our module `example.js` looks as follows:
 
 ```js
-import {read} from 'to-vfile'
 import {fromMarkdown} from 'mdast-util-from-markdown'
+import {read} from 'to-vfile'
 import {source} from 'unist-util-source'
 
 const file = await read('example.md')
 const tree = fromMarkdown(String(file))
 
 const strong = tree.children[0].children[0].children[0].children[0].children[0]
-console.log(source(strong, file))
+console.log(source(file, strong))
 ```
 
 …now running `node example.js` yields:
@@ -89,16 +89,16 @@ console.log(source(strong, file))
 This package exports the identifier [`source`][source].
 There is no default export.
 
-### `source(value, file)`
+### `source(file[, value])`
 
 Get the source of a node or at a position.
 
 ###### Parameters
 
-*   `value` ([`Node`][node] or [`Position`][position])
-    — value to get
 *   `file` ([`VFile`][vfile] or `string`)
     — file in which `value` exists
+*   `value` ([`Node`][node], [`Position`][position], optional)
+    — value to get
 
 ###### Returns
 
@@ -189,4 +189,4 @@ abide by its terms.
 
 [vfile]: https://github.com/vfile/vfile
 
-[source]: #sourcevalue-file
+[source]: #sourcefile-value

test.js

@@ -26,42 +26,42 @@ test('source', async function (t) {
   assert(text.type === 'text')
 
   await t.test('should support a root', async function () {
-    assert.equal(source(tree, file), '> + **[Hello](./example)**\n> world.')
+    assert.equal(source(file, tree), '> + **[Hello](./example)**\n> world.')
   })
 
   await t.test('should support a block quote', async function () {
     assert.equal(
-      source(blockquote, file),
+      source(file, blockquote),
       '> + **[Hello](./example)**\n> world.'
     )
   })
 
   await t.test('should support a list', async function () {
-    assert.equal(source(list, file), '+ **[Hello](./example)**\n> world.')
+    assert.equal(source(file, list), '+ **[Hello](./example)**\n> world.')
   })
 
   await t.test('should support a list item', async function () {
-    assert.equal(source(listItem, file), '+ **[Hello](./example)**\n> world.')
+    assert.equal(source(file, listItem), '+ **[Hello](./example)**\n> world.')
   })
 
   await t.test('should support a paragraph', async function () {
-    assert.equal(source(paragraph, file), '**[Hello](./example)**\n> world.')
+    assert.equal(source(file, paragraph), '**[Hello](./example)**\n> world.')
   })
 
   await t.test('should support strong', async function () {
-    assert.equal(source(strong, file), '**[Hello](./example)**')
+    assert.equal(source(file, strong), '**[Hello](./example)**')
   })
 
   await t.test('should support a link', async function () {
-    assert.equal(source(link, file), '[Hello](./example)')
+    assert.equal(source(file, link), '[Hello](./example)')
   })
 
   await t.test('should support a text', async function () {
-    assert.equal(source(text, file), 'Hello')
+    assert.equal(source(file, text), 'Hello')
   })
 
   await t.test('should support a position', async function () {
-    assert.equal(source(text.position, file), 'Hello')
+    assert.equal(source(file, text.position), 'Hello')
   })
 
   await t.test('should support out of bounds data', async function () {
@@ -70,44 +70,44 @@ test('source', async function (t) {
       value: 'qwe',
       position: {start: {line: 0, column: 0}, end: {line: 0, column: 0}}
     }
-    assert.equal(source(text, file), undefined)
+    assert.equal(source(file, text), undefined)
   })
 
   await t.test('should support a generated node', async function () {
     const text = {type: 'text', value: 'qwe'}
-    assert.equal(source(text, file), undefined)
+    assert.equal(source(file, text), undefined)
   })
 
   await t.test('should support a nullish node', async function () {
-    assert.equal(source(null, file), undefined)
+    assert.equal(source(file, null), undefined)
   })
 
   await t.test('should support cr + lf', async function () {
     const file = new VFile('a\r\nb')
     const node = fromMarkdown(String(file))
     const paragraph = node.children[0]
-    assert.equal(source(paragraph, file), 'a\r\nb')
+    assert.equal(source(file, paragraph), 'a\r\nb')
   })
 
   await t.test('should support cr', async function () {
     const file = new VFile('a\rb')
     const node = fromMarkdown(String(file))
     const paragraph = node.children[0]
 
-    assert.equal(source(paragraph, file), 'a\rb')
+    assert.equal(source(file, paragraph), 'a\rb')
   })
 
   await t.test('should support an eof eol', async function () {
     const file = new VFile('a\n')
     const node = fromMarkdown(String(file))
 
-    assert.equal(source(node, file), 'a\n')
+    assert.equal(source(file, node), 'a\n')
   })
 
   await t.test('should support an lf + cr (a blank line)', async function () {
     const file = new VFile('a\n\rb')
     const node = fromMarkdown(String(file))
 
-    assert.equal(source(node, file), 'a\n\rb')
+    assert.equal(source(file, node), 'a\n\rb')
   })
 })