add select.one

Author: eush77

README.md

@@ -4,7 +4,9 @@
 
 [![Build Status][travis-badge]][travis] [![Dependency Status][david-badge]][david]
 
-Select unist nodes using css-like selectors.
+Select [Unist] nodes with CSS-like selectors.
+
+[unist]: https://github.com/wooorm/unist
 
 [travis]: https://travis-ci.org/eush77/unist-util-select
 [travis-badge]: https://travis-ci.org/eush77/unist-util-select.svg?branch=master
@@ -84,6 +86,12 @@ All the relevant parts of [Selectors Level 3][spec]:
 
 Applies `selector` to `ast`, returns array of matching nodes.
 
+#### `select.one(ast, selector)`
+
+Returns a single node matching `selector`.
+
+Throws an error if node is not found or not unique.
+
 ## Install
 
 ```

index.js

@@ -1,15 +1,32 @@
 'use strict';
 
 var parseSelector = require('./lib/selector'),
-    select = require('./lib/select');
+    matchSelector = require('./lib/select');
 
 var debug = require('debug')('unist-util-select');
 
 
-module.exports = function (ast, selector) {
+var select = function select (ast, selector) {
   debug('Selector: %j', selector);
   selector = parseSelector(selector);
   debug('AST: %s',
         JSON.stringify(selector, null, 2).replace(/(^|\n)/g, '\n    '));
-  return selector ? select[selector.type](selector, ast) : [];
+  return selector ? matchSelector[selector.type](selector, ast) : [];
 };
+
+
+select.one = function selectOne (ast, selector) {
+  var nodes = select(ast, selector);
+
+  if (!nodes.length) {
+    throw Error('Node not found by ' + JSON.stringify(selector));
+  }
+  if (nodes.length > 1) {
+    throw Error('Node matched by ' + JSON.stringify(selector) + ' is not unique');
+  }
+
+  return nodes[0];
+};
+
+
+module.exports = select;

test/select-one.js

@@ -0,0 +1,18 @@
+'use strict';
+
+var select = require('..'),
+    select1 = select.one,
+    ast = require('./lib/ast')(),
+    path = require('./lib/path');
+
+var test = require('tape');
+
+
+test('select.one', function (t) {
+  t.equal(select1(ast, 'root'), ast);
+  t.equal(select1(ast, 'blockquote'), select(ast, 'blockquote')[0]);
+  t.equal(select1(ast, 'table'), select(ast, 'table')[0]);
+  t.throws(select1.bind(null, ast, 'math'), 'throws when node is not found');
+  t.throws(select1.bind(null, ast, 'text'), 'throws when node is not unique');
+  t.end();
+});