Change signature to use node first, test second

Closes GH-6.
Closes GH-8.

Reviewed-by: Christian Murphy <christian.murphy.42@gmail.com>

Author: wooorm

index.js

@@ -6,10 +6,10 @@ module.exports = is
 
 is.convert = convert
 
-// Assert if `test` passes for `node`.   When a `parent` node is known the
-// `index` of node.
+// Assert if `test` passes for `node`.
+// When a `parent` node is known the `index` of node should also be given.
 // eslint-disable-next-line max-params
-function is(test, node, index, parent, context) {
+function is(node, test, index, parent, context) {
   var hasParent = parent !== null && parent !== undefined
   var hasIndex = index !== null && index !== undefined
   var check = convert(test)
@@ -21,7 +21,7 @@ function is(test, node, index, parent, context) {
     throw new Error('Expected positive finite index or child node')
   }
 
-  if (hasParent && (!is(null, parent) || !parent.children)) {
+  if (hasParent && (!is(parent) || !parent.children)) {
     throw new Error('Expected parent node')
   }
 

readme.md

@@ -31,49 +31,49 @@ function test(node, n) {
 }
 
 is() // => false
-is(null, {children: []}) // => false
-is(null, node) // => true
-is('strong', node) // => true
-is('emphasis', node) // => false
+is({children: []}) // => false
+is(node) // => true
+is(node, 'strong') // => true
+is(node, 'emphasis') // => false
 
 is(node, node) // => true
-is({type: 'paragraph'}, parent) // => true
-is({type: 'strong'}, parent) // => false
+is(parent, {type: 'paragraph'}) // => true
+is(parent, {type: 'strong'}) // => false
 
-is(test, node) // => false
-is(test, node, 4, parent) // => false
-is(test, node, 5, parent) // => true
+is(node, test) // => false
+is(node, test, 4, parent) // => false
+is(node, test, 5, parent) // => true
 ```
 
 ## API
 
-### `is(test, node[, index, parent[, context]])`
+### `is(node[, test[, index, parent[, context]]])`
 
 ###### Parameters
 
+*   `node` ([`Node`][node]) — Node to check.
 *   `test` ([`Function`][test], `string`, `Object`, or `Array.<Test>`, optional)
     —  When not given, checks if `node` is a [`Node`][node].
     When `string`, works like passing `node => node.type === test`.
     When `array`, checks if any one of the subtests pass.
     When `object`, checks that all keys in `test` are in `node`,
     and that they have strictly equal values
-*   `node` ([`Node`][node]) — Node to check.  `false` is returned
 *   `index` (`number`, optional) — [Index][] of `node` in `parent`
 *   `parent` ([`Node`][node], optional) — [Parent][] of `node`
 *   `context` (`*`, optional) — Context object to invoke `test` with
 
 ###### Returns
 
-`boolean` — Whether `test` passed *and* `node` is a [`Node`][node] (object
-with `type` set to a non-empty `string`).
+`boolean` — Whether `test` passed *and* `node` is a [`Node`][node] (object with
+`type` set to a non-empty `string`).
 
 #### `function test(node[, index, parent])`
 
 ###### Parameters
 
-*   `node` (`Node`) — Node to test
-*   `index` (`number?`) — Position of `node` in `parent`
-*   `parent` (`Node?`) — Parent of `node`
+*   `node` ([`Node`][node]) — Node to check
+*   `index` (`number?`) — [Index][] of `node` in `parent`
+*   `parent` ([`Node?`][node]) — [Parent][] of `node`
 
 ###### Context
 

test.js

@@ -9,90 +9,88 @@ test('unist-util-is', function(t) {
 
   t.throws(
     function() {
-      is(false)
+      is(null, false)
     },
     /Expected function, string, or object as test/,
     'should throw when `test` is invalid'
   )
 
   t.throws(
     function() {
-      is(null, node, -1, parent)
+      is(node, null, -1, parent)
     },
     /Expected positive finite index or child node/,
     'should throw when `index` is invalid (#1)'
   )
 
   t.throws(
     function() {
-      is(null, node, Infinity, parent)
+      is(node, null, Infinity, parent)
     },
     /Expected positive finite index or child node/,
     'should throw when `index` is invalid (#2)'
   )
 
   t.throws(
     function() {
-      is(null, node, false, parent)
+      is(node, null, false, parent)
     },
     /Expected positive finite index or child node/,
     'should throw when `index` is invalid (#3)'
   )
 
   t.throws(
     function() {
-      is(null, node, 0, {})
+      is(node, null, 0, {})
     },
     /Expected parent node/,
     'should throw when `parent` is invalid (#1)'
   )
 
   t.throws(
     function() {
-      is(null, node, 0, {
-        type: 'paragraph'
-      })
+      is(node, null, 0, {type: 'paragraph'})
     },
     /Expected parent node/,
     'should throw when `parent` is invalid (#2)'
   )
 
   t.throws(
     function() {
-      is(null, node, 0)
+      is(node, null, 0)
     },
     /Expected both parent and index/,
     'should throw `parent` xor `index` are given (#1)'
   )
 
   t.throws(
     function() {
-      is(null, node, null, parent)
+      is(node, null, null, parent)
     },
     /Expected both parent and index/,
     'should throw `parent` xor `index` are given (#2)'
   )
 
   t.notok(is(), 'should not fail without node')
-  t.ok(is(null, node), 'should check if given a node (#1)')
-  t.notok(is(null, {children: []}), 'should check if given a node (#2)')
+  t.ok(is(node), 'should check if given a node (#1)')
+  t.notok(is({children: []}, null), 'should check if given a node (#2)')
 
-  t.ok(is('strong', node), 'should match types (#1)')
-  t.notok(is('emphasis', node), 'should match types (#2)')
+  t.ok(is(node, 'strong'), 'should match types (#1)')
+  t.notok(is(node, 'emphasis'), 'should match types (#2)')
 
   t.ok(is(node, node), 'should match partially (#1)')
-  t.ok(is({type: 'strong'}, node), 'should match partially (#2)')
-  t.ok(is({type: 'paragraph'}, parent), 'should match partially (#3)')
-  t.notok(is({type: 'paragraph'}, node), 'should match partially (#4)')
+  t.ok(is(node, {type: 'strong'}), 'should match partially (#2)')
+  t.ok(is(parent, {type: 'paragraph'}), 'should match partially (#3)')
+  t.notok(is(node, {type: 'paragraph'}), 'should match partially (#4)')
 
   t.test('should accept a test', function(st) {
     function test(node, n) {
       return n === 5
     }
 
-    t.notok(is(test, node))
-    t.notok(is(test, node, 0, parent))
-    st.ok(is(test, node, 5, parent))
+    t.notok(is(node, test))
+    t.notok(is(node, test, 0, parent))
+    st.ok(is(node, test, 5, parent))
 
     st.end()
   })
@@ -109,18 +107,18 @@ test('unist-util-is', function(t) {
       st.equal(c, parent)
     }
 
-    is(test, node, 5, parent, context)
+    is(node, test, 5, parent, context)
   })
 
-  t.ok(is(['strong', 'emphasis'], node), 'should match arrays (#1)')
-  t.notok(is(['b', 'i'], node), 'should match arrays (#2)')
+  t.ok(is(node, ['strong', 'emphasis']), 'should match arrays (#1)')
+  t.notok(is(node, ['b', 'i']), 'should match arrays (#2)')
 
   t.test('should match arrays (#3)', function(st) {
     var context = {foo: 'bar'}
 
     st.plan(5)
 
-    st.ok(is([test, 'strong'], node, 5, parent, context))
+    st.ok(is(node, [test, 'strong'], 5, parent, context))
 
     function test(a, b, c) {
       st.equal(this, context)