Update some documentation

This commit is contained in:
Timothy Warren 2016-01-26 20:23:52 -05:00
parent da8b473bc7
commit ea15044d13
5 changed files with 991 additions and 31 deletions

479
API.md Normal file
View File

@ -0,0 +1,479 @@
# NodeQuery
Class for connection management
## getQuery
Return an existing query builder instance
Returns **QueryBuilder** The Query Builder object
## init
Create a query builder object
**Parameters**
- `driverType` **String** The name of the database type, eg. mysql or pg
- `connObject` **Object** A connection object from the database library you are connecting with
- `connLib` **[String]** The name of the db connection library you are using, eg. mysql or mysql2. Optional if the same as driverType
Returns **QueryBuilder** The Query Builder object
# QueryBuilder
Main object that builds SQL queries.
**Parameters**
- `Driver` **Driver** The syntax driver for the database
- `Adapter` **Adapter** The database module adapter for running queries
## delete
Run the generated delete query
**Parameters**
- `table` **String** The table to insert into
- `where` **[Object]** Where clause for delete statement
- `callback` **[Function]** Callback for handling response from the database
Returns **void or Promise** If no callback is passed, a promise is returned
## end
Closes the database connection for the current adapter
Returns **void**
## from
Specify the database table to select from
**Parameters**
- `tableName` **String** The table to use for the current query
**Examples**
```javascript
query.from('tableName');
```
```javascript
query.from('tableName t'); // Select the table with an alias
```
Returns **QueryBuilder** The Query Builder object, for chaining
## get
Get the results of the compiled query
**Parameters**
- `table` **[String]** The table to select from
- `limit` **[Number]** A limit for the query
- `offset` **[Number]** An offset for the query
- `callback` **[Function]** A callback for receiving the result
**Examples**
```javascript
query.get('table_name').then(promiseCallback); // Get all the rows in the table
```
```javascript
query.get('table_name', 5, callback); // Get 5 rows from the table
```
```javascript
query.get(callback); // Get the results of a query generated with other methods
```
Returns **void or Promise** If no callback is passed, a promise is returned
## getCompiledDelete
Return generated delete query SQL
**Parameters**
- `table` **String** the name of the table to delete from
- `reset` **[Boolean]** Whether to reset the query builder so another query can be built (optional, default `true`)
Returns **String** The compiled sql statement
## getCompiledInsert
Return generated insert query SQL
**Parameters**
- `table` **String** the name of the table to insert into
- `reset` **[Boolean]** Whether to reset the query builder so another query can be built (optional, default `true`)
Returns **String** The compiled sql statement
## getCompiledSelect
Return generated select query SQL
**Parameters**
- `table` **[String]** the name of the table to retrieve from
- `reset` **[Boolean]** Whether to reset the query builder so another query can be built (optional, default `true`)
Returns **String** The compiled sql statement
## getCompiledUpdate
Return generated update query SQL
**Parameters**
- `table` **String** the name of the table to update
- `reset` **[Boolean]** Whether to reset the query builder so another query can be built (optional, default `true`)
Returns **String** The compiled sql statement
## groupBy
Group the results by the selected field(s)
**Parameters**
- `field` **String or Array** The name of the field to group by
Returns **QueryBuilder** The Query Builder object, for chaining
## groupEnd
Ends a logical grouping started with one of the groupStart methods
Returns **QueryBuilder** The Query Builder object, for chaining
## groupStart
Adds an open paren to the current query for logical grouping
Returns **QueryBuilder** The Query Builder object, for chaining
## having
Add a 'having' clause
**Parameters**
- `key` **String or Object** The name of the field and the comparision operator, or an object
- `val` **[String or Number]** The value to compare if the value of key is a string
Returns **QueryBuilder** The Query Builder object, for chaining
## insert
Run the generated insert query
**Parameters**
- `table` **String** The table to insert into
- `data` **[Object]** Data to insert, if not already added with the 'set' method
- `callback` **[Function]** Callback for handling response from the database
Returns **void or Promise** If no callback is passed, a promise is returned
## insertBatch
Insert multiple sets of rows at a time
**Parameters**
- `table` **String** The table to insert into
- `data` **Array** The array of objects containing data rows to insert
- `callback` **[Function]** Callback for handling database response
**Examples**
```javascript
query.insertBatch('foo',[{id:1,val:'bar'},{id:2,val:'baz'}], callbackFunction);
```
```javascript
query.insertBatch('foo',[{id:1,val:'bar'},{id:2,val:'baz'}])
.then(promiseCallback);
```
Returns **void or Promise** If no callback is passed, a promise is returned
## join
Add a join clause to the query
**Parameters**
- `table` **String** The table you are joining
- `cond` **String** The join condition.
- `type` **[String]** The type of join, which defaults to inner (optional, default `'inner'`)
Returns **QueryBuilder** The Query Builder object, for chaining
## like
Add a 'like/ and like' clause to the query
**Parameters**
- `field` **String** The name of the field to compare to
- `val` **String** The value to compare to
- `pos` **[String]** The placement of the wildcard character(s): before, after, or both (optional, default `both`)
Returns **QueryBuilder** The Query Builder object, for chaining
## limit
Put a limit on the query
**Parameters**
- `limit` **Number** The maximum number of rows to fetch
- `offset` **[Number]** The row number to start from
Returns **QueryBuilder** The Query Builder object, for chaining
## notLike
Add a 'not like/ and not like' clause to the query
**Parameters**
- `field` **String** The name of the field to compare to
- `val` **String** The value to compare to
- `pos` **[String]** The placement of the wildcard character(s): before, after, or both (optional, default `both`)
Returns **QueryBuilder** The Query Builder object, for chaining
## orGroupStart
Adds an open paren to the current query for logical grouping,
prefixed with 'OR'
Returns **QueryBuilder** The Query Builder object, for chaining
## orHaving
Add an 'or having' clause
**Parameters**
- `key` **String or Object** The name of the field and the comparision operator, or an object
- `val` **[String or Number]** The value to compare if the value of key is a string
Returns **QueryBuilder** The Query Builder object, for chaining
## orLike
Add an 'or like' clause to the query
**Parameters**
- `field` **String** The name of the field to compare to
- `val` **String** The value to compare to
- `pos` **[String]** The placement of the wildcard character(s): before, after, or both (optional, default `both`)
Returns **QueryBuilder** The Query Builder object, for chaining
## orNotGroupStart
Adds an open paren to the current query for logical grouping,
prefixed with 'OR NOT'
Returns **QueryBuilder** The Query Builder object, for chaining
## orNotLike
Add an 'or not like' clause to the query
**Parameters**
- `field` **String** The name of the field to compare to
- `val` **String** The value to compare to
- `pos` **[String]** The placement of the wildcard character(s): before, after, or both (optional, default `both`)
Returns **QueryBuilder** The Query Builder object, for chaining
## orWhere
Set a 'or where' clause
**Parameters**
- `key` **String or Object** The name of the field and the comparision operator, or an object
- `val` **[String or Number]** The value to compare if the value of key is a string
Returns **QueryBuilder** The Query Builder object, for chaining
## orWhereIn
Set a 'or where in' clause
**Parameters**
- `key` **String** the field to search
- `values` **Array** the array of items to search in
Returns **QueryBuilder** The Query Builder object, for chaining
## orWhereIsNotNull
Field is not null prefixed with 'OR'
**Parameters**
- `field` **String** The name of the field
Returns **QueryBuilder** The Query Builder object, for chaining
## orWhereIsNull
Field is null prefixed with 'OR'
**Parameters**
- `field` **String** The name of the field
Returns **QueryBuilder** The Query Builder object, for chaining
## orWhereNotIn
Set a 'or where not in' clause
**Parameters**
- `key` **String** the field to search
- `values` **Array** the array of items to search in
Returns **QueryBuilder** The Query Builder object, for chaining
## orderBy
Order the results by the selected field(s)
**Parameters**
- `field` **String** The field(s) to order by
- `type` **[String]** The order direction, ASC or DESC (optional, default `'ASC'`)
Returns **QueryBuilder** The Query Builder object, for chaining
## resetQuery
Reset the object state for a new query
Returns **void**
## select
Specify rows to select in the query
**Parameters**
- `fields` **String or Array** The fields to select from the current table
**Examples**
```javascript
query.select('foo, bar'); // Select multiple fields with a string
```
```javascript
query.select(['foo', 'bar']); // Select multiple fileds with an array
```
Returns **QueryBuilder** The Query Builder object, for chaining
## set
Set values for insertion or updating
**Parameters**
- `key` **String or Object** The key or object to use
- `val` **[String]** The value if using a scalar key
**Examples**
```javascript
query.set('foo', 'bar'); // Set a key, value pair
```
```javascript
query.set({foo:'bar'}); // Set with an object
```
Returns **QueryBuilder** The Query Builder object, for chaining
## update
Run the generated update query
**Parameters**
- `table` **String** The table to insert into
- `data` **[Object]** Data to insert, if not already added with the 'set' method
- `callback` **[Function]** Callback for handling response from the database
Returns **void or Promise** If no callback is passed, a promise is returned
## where
Set a 'where' clause
**Parameters**
- `key` **String or Object** The name of the field and the comparision operator, or an object
- `val` **[String or Number]** The value to compare if the value of key is a string
Returns **QueryBuilder** The Query Builder object, for chaining
## whereIn
Set a 'where in' clause
**Parameters**
- `key` **String** the field to search
- `values` **Array** the array of items to search in
Returns **QueryBuilder** The Query Builder object, for chaining
## whereIsNotNull
Specify that a field IS NOT NULL
**Parameters**
- `field` **String** The name so the field that is not to be null
Returns **QueryBuilder** The Query Builder object, for chaining
## whereIsNull
Select a field that is Null
**Parameters**
- `field` **String** The name of the field that has a NULL value
Returns **QueryBuilder** The Query Builder object, for chaining
## whereNotIn
Set a 'where not in' clause
**Parameters**
- `key` **String** the field to search
- `values` **Array** the array of items to search in
Returns **QueryBuilder** The Query Builder object, for chaining

View File

@ -1,6 +1,6 @@
#CI-Node-query #CI-Node-query
A node query builder for various SQL databases, based on CodeIgniter's query builder. A node query builder for various SQL databases, based on [CodeIgniter](http://www.codeigniter.com/user_guide/database/query_builder.html)'s query builder.
[![Build Status](https://jenkins.timshomepage.net/buildStatus/icon?job=node-query)](https://jenkins.timshomepage.net/job/node-query/) [![Build Status](https://jenkins.timshomepage.net/buildStatus/icon?job=node-query)](https://jenkins.timshomepage.net/job/node-query/)
[![Build Status](https://travis-ci.org/timw4mail/node-query.svg?branch=master)](https://travis-ci.org/timw4mail/node-query) [![Build Status](https://travis-ci.org/timw4mail/node-query.svg?branch=master)](https://travis-ci.org/timw4mail/node-query)
@ -13,12 +13,13 @@ A node query builder for various SQL databases, based on CodeIgniter's query bui
* mysql2 * mysql2
* pg * pg
* dblite * dblite
* node-firebird * node-firebird (Not supported as of version 3.1.0, as the adapter is very difficult to test)
### Installation ### Installation
npm install ci-node-query npm install ci-node-query
[![NPM](https://nodei.co/npm/ci-node-query.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/ci-node-query/)
[![NPM](https://nodei.co/npm/ci-node-query.png?downloads=true&downloadRank=true)](https://nodei.co/npm/ci-node-query/)
### Basic use ### Basic use
@ -48,6 +49,20 @@ A node query builder for various SQL databases, based on CodeIgniter's query bui
// Database module result handling // Database module result handling
}); });
// As of version 3.1.0, you can also get promises
var queryPromise = query.select('foo')
.from('bar')
.where('x', 3)
.orWhere({y: 2})
.join('baz', 'baz.boo = bar.foo', 'left')
.orderBy('x', 'DESC')
.limit(2, 3)
.get();
queryPromise.then(function(res) {
// Handle query results
});
### Security notes ### Security notes
As of version 2, `where` and `having` type methods parse the values passed to look for function calls. While values passed are still passed as query parameters, take care to avoid passing these kinds of methods unfiltered input. SQL function arguments are not currently parsed, so they need to be properly escaped for the current database. As of version 2, `where` and `having` type methods parse the values passed to look for function calls. While values passed are still passed as query parameters, take care to avoid passing these kinds of methods unfiltered input. SQL function arguments are not currently parsed, so they need to be properly escaped for the current database.
@ -55,6 +70,7 @@ As of version 2, `where` and `having` type methods parse the values passed to lo
### Additional help ### Additional help
* Generated documentation is in the docs/ folder * Generated documentation is in the docs/ folder
* The API is documented in [API.md](./API.md)
* `tests/query-builder-base.js` contains a lot of usage examples * `tests/query-builder-base.js` contains a lot of usage examples
* The `tests/adapters` folder contains examples of how to set up a connection for the appropriate database library * The `tests/adapters` folder contains examples of how to set up a connection for the appropriate database library
* The documentation generated for the latest dev build is also [Available](https://github.timshomepage.net/node-query/docs/) * The documentation generated for the latest dev build is also [Available](https://github.timshomepage.net/node-query/docs/)

View File

@ -22,6 +22,16 @@
class='col12 block field' class='col12 block field'
type='text' /> type='text' />
<div id='toc'> <div id='toc'>
<a
href='#Firebird'
class='block bold'>
Firebird
</a>
<a
href='#Mysql'
class='block bold'>
Mysql
</a>
<a <a
href='#NodeQuery' href='#NodeQuery'
class='block bold'> class='block bold'>
@ -37,6 +47,11 @@
class='regular block'> class='regular block'>
#init #init
</a> </a>
<a
href='#Pg'
class='block bold'>
Pg
</a>
<a <a
href='#QueryBuilder' href='#QueryBuilder'
class='block bold'> class='block bold'>
@ -232,12 +247,86 @@
class='regular block'> class='regular block'>
#whereNotIn #whereNotIn
</a> </a>
<a
href='#Sqlite'
class='block bold'>
Sqlite
</a>
<a
href='#close'
class='block bold'>
close
</a>
<a
href='#close'
class='block bold'>
close
</a>
<a
href='#execute'
class='block bold'>
execute
</a>
<a
href='#execute'
class='block bold'>
execute
</a>
<a
href='#execute'
class='block bold'>
execute
</a>
<a
href='#execute'
class='block bold'>
execute
</a>
<a
href='#execute'
class='block bold'>
execute
</a>
<a
href='#insertBatch'
class='block bold'>
insertBatch
</a>
<a
href='#insertBatch'
class='block bold'>
insertBatch
</a>
<a
href='#limit'
class='block bold'>
limit
</a>
<a
href='#limit'
class='block bold'>
limit
</a>
</div> </div>
</div> </div>
</div> </div>
<div class='fix-margin-3'> <div class='fix-margin-3'>
<div class='px2'> <div class='px2'>
<div class='py1'><section class='py2 clearfix'> <div class='py1'><section class='py2 clearfix'>
<h2 id='Firebird' class='mt0'>
Firebird<span class='gray'></span>
</h2>
<p>Driver for Firebird databases</p>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='Mysql' class='mt0'>
Mysql<span class='gray'></span>
</h2>
<p>Driver for MySQL databases</p>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='NodeQuery' class='mt0'> <h2 id='NodeQuery' class='mt0'>
NodeQuery<span class='gray'></span> NodeQuery<span class='gray'></span>
</h2> </h2>
@ -323,6 +412,13 @@
</div> </div>
</div> </div>
</section> </section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='Pg' class='mt0'>
Pg<span class='gray'></span>
</h2>
<p>Driver for PostgreSQL databases</p>
</section>
</div><div class='py1'><section class='py2 clearfix'> </div><div class='py1'><section class='py2 clearfix'>
<h2 id='QueryBuilder' class='mt0'> <h2 id='QueryBuilder' class='mt0'>
QueryBuilder<span class='gray'>(Driver, Adapter)</span> QueryBuilder<span class='gray'>(Driver, Adapter)</span>
@ -458,6 +554,8 @@
<p>The Query Builder object, for chaining</p> <p>The Query Builder object, for chaining</p>
</div> </div>
<h4>Examples</h4>
<pre class='overflow-auto'>query.from(<span class="hljs-string">'tableName'</span>);</pre><pre class='overflow-auto'>query.from(<span class="hljs-string">'tableName t'</span>); <span class="hljs-comment">// Select the table with an alias</span></pre>
</section> </section>
</div> </div>
</div> </div>
@ -516,6 +614,8 @@
<p>If no callback is passed, a promise is returned</p> <p>If no callback is passed, a promise is returned</p>
</div> </div>
<h4>Examples</h4>
<pre class='overflow-auto'>query.get(<span class="hljs-string">'table_name'</span>).then(promiseCallback); <span class="hljs-comment">// Get all the rows in the table</span></pre><pre class='overflow-auto'>query.get(<span class="hljs-string">'table_name'</span>, <span class="hljs-number">5</span>, callback); <span class="hljs-comment">// Get 5 rows from the table</span></pre><pre class='overflow-auto'>query.get(callback); <span class="hljs-comment">// Get the results of a query generated with other methods</span></pre>
</section> </section>
</div> </div>
</div> </div>
@ -934,7 +1034,8 @@
</div> </div>
<h4>Examples</h4> <h4>Examples</h4>
<pre class='overflow-auto'>query.insertBatch(<span class="hljs-string">'foo'</span>,[{id:<span class="hljs-number">1</span>,val:<span class="hljs-string">'bar'</span>},{id:<span class="hljs-number">2</span>,val:<span class="hljs-string">'baz'</span>}], callbackFunction);</pre> <pre class='overflow-auto'>query.insertBatch(<span class="hljs-string">'foo'</span>,[{id:<span class="hljs-number">1</span>,val:<span class="hljs-string">'bar'</span>},{id:<span class="hljs-number">2</span>,val:<span class="hljs-string">'baz'</span>}], callbackFunction);</pre><pre class='overflow-auto'>query.insertBatch(<span class="hljs-string">'foo'</span>,[{id:<span class="hljs-number">1</span>,val:<span class="hljs-string">'bar'</span>},{id:<span class="hljs-number">2</span>,val:<span class="hljs-string">'baz'</span>}])
.then(promiseCallback);</pre>
</section> </section>
</div> </div>
</div> </div>
@ -1391,7 +1492,7 @@ prefixed with &apos;OR NOT&apos;</p>
<div class='collapsible' id='QueryBuilder.orWhereIn'> <div class='collapsible' id='QueryBuilder.orWhereIn'>
<a href='#QueryBuilder.orWhereIn'> <a href='#QueryBuilder.orWhereIn'>
<code> <code>
#orWhereIn<span class='gray'>(key, val)</span> #orWhereIn<span class='gray'>(key, values)</span>
</code> </code>
<div class='force-inline'> <div class='force-inline'>
<p>Set a &apos;or where in&apos; clause</p> <p>Set a &apos;or where in&apos; clause</p>
@ -1401,7 +1502,7 @@ prefixed with &apos;OR NOT&apos;</p>
<div class='collapser border px2'> <div class='collapser border px2'>
<section class='py2 clearfix'> <section class='py2 clearfix'>
<h2 id='QueryBuilder.orWhereIn' class='mt0'> <h2 id='QueryBuilder.orWhereIn' class='mt0'>
orWhereIn<span class='gray'>(key, val)</span> orWhereIn<span class='gray'>(key, values)</span>
</h2> </h2>
<p>Set a &apos;or where in&apos; clause</p> <p>Set a &apos;or where in&apos; clause</p>
@ -1414,7 +1515,7 @@ prefixed with &apos;OR NOT&apos;</p>
</div> </div>
</li> </li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>val</strong> <li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>values</strong>
: :
<div class='force-inline'> <div class='force-inline'>
<p>the array of items to search in</p> <p>the array of items to search in</p>
@ -1509,7 +1610,7 @@ prefixed with &apos;OR NOT&apos;</p>
<div class='collapsible' id='QueryBuilder.orWhereNotIn'> <div class='collapsible' id='QueryBuilder.orWhereNotIn'>
<a href='#QueryBuilder.orWhereNotIn'> <a href='#QueryBuilder.orWhereNotIn'>
<code> <code>
#orWhereNotIn<span class='gray'>(key, val)</span> #orWhereNotIn<span class='gray'>(key, values)</span>
</code> </code>
<div class='force-inline'> <div class='force-inline'>
<p>Set a &apos;or where not in&apos; clause</p> <p>Set a &apos;or where not in&apos; clause</p>
@ -1519,7 +1620,7 @@ prefixed with &apos;OR NOT&apos;</p>
<div class='collapser border px2'> <div class='collapser border px2'>
<section class='py2 clearfix'> <section class='py2 clearfix'>
<h2 id='QueryBuilder.orWhereNotIn' class='mt0'> <h2 id='QueryBuilder.orWhereNotIn' class='mt0'>
orWhereNotIn<span class='gray'>(key, val)</span> orWhereNotIn<span class='gray'>(key, values)</span>
</h2> </h2>
<p>Set a &apos;or where not in&apos; clause</p> <p>Set a &apos;or where not in&apos; clause</p>
@ -1532,7 +1633,7 @@ prefixed with &apos;OR NOT&apos;</p>
</div> </div>
</li> </li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>val</strong> <li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>values</strong>
: :
<div class='force-inline'> <div class='force-inline'>
<p>the array of items to search in</p> <p>the array of items to search in</p>
@ -1655,6 +1756,8 @@ prefixed with &apos;OR NOT&apos;</p>
<p>The Query Builder object, for chaining</p> <p>The Query Builder object, for chaining</p>
</div> </div>
<h4>Examples</h4>
<pre class='overflow-auto'>query.select(<span class="hljs-string">'foo, bar'</span>); <span class="hljs-comment">// Select multiple fields with a string</span></pre><pre class='overflow-auto'>query.select([<span class="hljs-string">'foo'</span>, <span class="hljs-string">'bar'</span>]); <span class="hljs-comment">// Select multiple fileds with an array</span></pre>
</section> </section>
</div> </div>
</div> </div>
@ -1699,6 +1802,8 @@ prefixed with &apos;OR NOT&apos;</p>
<p>The Query Builder object, for chaining</p> <p>The Query Builder object, for chaining</p>
</div> </div>
<h4>Examples</h4>
<pre class='overflow-auto'>query.set(<span class="hljs-string">'foo'</span>, <span class="hljs-string">'bar'</span>); <span class="hljs-comment">// Set a key, value pair</span></pre><pre class='overflow-auto'>query.set({foo:<span class="hljs-string">'bar'</span>}); <span class="hljs-comment">// Set with an object</span></pre>
</section> </section>
</div> </div>
</div> </div>
@ -1800,7 +1905,7 @@ prefixed with &apos;OR NOT&apos;</p>
<div class='collapsible' id='QueryBuilder.whereIn'> <div class='collapsible' id='QueryBuilder.whereIn'>
<a href='#QueryBuilder.whereIn'> <a href='#QueryBuilder.whereIn'>
<code> <code>
#whereIn<span class='gray'>(key, val)</span> #whereIn<span class='gray'>(key, values)</span>
</code> </code>
<div class='force-inline'> <div class='force-inline'>
<p>Set a &apos;where in&apos; clause</p> <p>Set a &apos;where in&apos; clause</p>
@ -1810,7 +1915,7 @@ prefixed with &apos;OR NOT&apos;</p>
<div class='collapser border px2'> <div class='collapser border px2'>
<section class='py2 clearfix'> <section class='py2 clearfix'>
<h2 id='QueryBuilder.whereIn' class='mt0'> <h2 id='QueryBuilder.whereIn' class='mt0'>
whereIn<span class='gray'>(key, val)</span> whereIn<span class='gray'>(key, values)</span>
</h2> </h2>
<p>Set a &apos;where in&apos; clause</p> <p>Set a &apos;where in&apos; clause</p>
@ -1823,7 +1928,7 @@ prefixed with &apos;OR NOT&apos;</p>
</div> </div>
</li> </li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>val</strong> <li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>values</strong>
: :
<div class='force-inline'> <div class='force-inline'>
<p>the array of items to search in</p> <p>the array of items to search in</p>
@ -1918,7 +2023,7 @@ prefixed with &apos;OR NOT&apos;</p>
<div class='collapsible' id='QueryBuilder.whereNotIn'> <div class='collapsible' id='QueryBuilder.whereNotIn'>
<a href='#QueryBuilder.whereNotIn'> <a href='#QueryBuilder.whereNotIn'>
<code> <code>
#whereNotIn<span class='gray'>(key, val)</span> #whereNotIn<span class='gray'>(key, values)</span>
</code> </code>
<div class='force-inline'> <div class='force-inline'>
<p>Set a &apos;where not in&apos; clause</p> <p>Set a &apos;where not in&apos; clause</p>
@ -1928,7 +2033,7 @@ prefixed with &apos;OR NOT&apos;</p>
<div class='collapser border px2'> <div class='collapser border px2'>
<section class='py2 clearfix'> <section class='py2 clearfix'>
<h2 id='QueryBuilder.whereNotIn' class='mt0'> <h2 id='QueryBuilder.whereNotIn' class='mt0'>
whereNotIn<span class='gray'>(key, val)</span> whereNotIn<span class='gray'>(key, values)</span>
</h2> </h2>
<p>Set a &apos;where not in&apos; clause</p> <p>Set a &apos;where not in&apos; clause</p>
@ -1941,7 +2046,7 @@ prefixed with &apos;OR NOT&apos;</p>
</div> </div>
</li> </li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>val</strong> <li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>values</strong>
: :
<div class='force-inline'> <div class='force-inline'>
<p>the array of items to search in</p> <p>the array of items to search in</p>
@ -1960,6 +2065,354 @@ prefixed with &apos;OR NOT&apos;</p>
</div> </div>
</div> </div>
</section> </section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='Sqlite' class='mt0'>
Sqlite<span class='gray'></span>
</h2>
<p>Driver for Sqlite databases</p>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='close' class='mt0'>
close<span class='gray'></span>
</h2>
<p>Close the current database connection</p>
<h4>Returns</h4>
<code><code>void</code></code>
<div class='force-inline'>
</div>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='close' class='mt0'>
close<span class='gray'></span>
</h2>
<p>Close the current database connection</p>
<h4>Returns</h4>
<code><code>void</code></code>
<div class='force-inline'>
</div>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='execute' class='mt0'>
execute<span class='gray'>(sql, params, [callback])</span>
</h2>
<p>Run the sql query as a prepared statement</p>
<h4>Parameters</h4>
<ul class='suppress-p-margin'>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code> <strong>sql</strong>
:
<div class='force-inline'>
<p>The sql with placeholders</p>
</div>
</li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>params</strong>
:
<div class='force-inline'>
<p>The values to insert into the query</p>
</div>
</li>
<li><code>[<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function">Function</a></code>]</code> <strong>callback</strong>
:
<div class='force-inline'>
<p>Callback to run when a response is recieved</p>
</div>
</li>
</ul>
<h4>Returns</h4>
<code><code>void</code> or <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code></code>
:
<div class='force-inline'>
<p>Returns a promise if no callback is provided</p>
</div>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='execute' class='mt0'>
execute<span class='gray'>(sql, params, [callback])</span>
</h2>
<p>Run the sql query as a prepared statement</p>
<h4>Parameters</h4>
<ul class='suppress-p-margin'>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code> <strong>sql</strong>
:
<div class='force-inline'>
<p>The sql with placeholders</p>
</div>
</li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>params</strong>
:
<div class='force-inline'>
<p>The values to insert into the query</p>
</div>
</li>
<li><code>[<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function">Function</a></code>]</code> <strong>callback</strong>
:
<div class='force-inline'>
<p>Callback to run when a response is recieved</p>
</div>
</li>
</ul>
<h4>Returns</h4>
<code><code>void</code> or <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code></code>
:
<div class='force-inline'>
<p>Returns a promise if no callback is provided</p>
</div>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='execute' class='mt0'>
execute<span class='gray'>(sql, params, [callback])</span>
</h2>
<p>Run the sql query as a prepared statement</p>
<h4>Parameters</h4>
<ul class='suppress-p-margin'>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code> <strong>sql</strong>
:
<div class='force-inline'>
<p>The sql with placeholders</p>
</div>
</li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>params</strong>
:
<div class='force-inline'>
<p>The values to insert into the query</p>
</div>
</li>
<li><code>[<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function">Function</a></code>]</code> <strong>callback</strong>
:
<div class='force-inline'>
<p>Callback to run when a response is recieved</p>
</div>
</li>
</ul>
<h4>Returns</h4>
<code><code>void</code> or <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code></code>
:
<div class='force-inline'>
<p>Returns a promise if no callback is provided</p>
</div>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='execute' class='mt0'>
execute<span class='gray'>(sql, params, [callback])</span>
</h2>
<p>Run the sql query as a prepared statement</p>
<h4>Parameters</h4>
<ul class='suppress-p-margin'>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code> <strong>sql</strong>
:
<div class='force-inline'>
<p>The sql with placeholders</p>
</div>
</li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>params</strong>
:
<div class='force-inline'>
<p>The values to insert into the query</p>
</div>
</li>
<li><code>[<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function">Function</a></code>]</code> <strong>callback</strong>
:
<div class='force-inline'>
<p>Callback to run when a response is recieved</p>
</div>
</li>
</ul>
<h4>Returns</h4>
<code><code>void</code> or <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code></code>
:
<div class='force-inline'>
<p>Returns a promise if no callback is provided</p>
</div>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='execute' class='mt0'>
execute<span class='gray'>(sql, params, [callback])</span>
</h2>
<p>Run the sql query as a prepared statement</p>
<h4>Parameters</h4>
<ul class='suppress-p-margin'>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code> <strong>sql</strong>
:
<div class='force-inline'>
<p>The sql with placeholders</p>
</div>
</li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code> <strong>params</strong>
:
<div class='force-inline'>
<p>The values to insert into the query</p>
</div>
</li>
<li><code>[<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function">Function</a></code>]</code> <strong>callback</strong>
:
<div class='force-inline'>
<p>Callback to run when a response is recieved</p>
</div>
</li>
</ul>
<h4>Returns</h4>
<code><code>void</code> or <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code></code>
:
<div class='force-inline'>
<p>Returns a promise if no callback is provided</p>
</div>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='insertBatch' class='mt0'>
insertBatch<span class='gray'>(table, [data])</span>
</h2>
<p>SQL to insert a group of rows
Override default to have better compatibility</p>
<h4>Parameters</h4>
<ul class='suppress-p-margin'>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code> <strong>table</strong>
:
<div class='force-inline'>
<p>The table to insert to</p>
</div>
</li>
<li><code>[<code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a></code>]</code> <strong>data</strong>
:
<div class='force-inline'>
<p>The array of object containing data to insert</p>
</div>
</li>
</ul>
<h4>Returns</h4>
<code><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code></code>
:
<div class='force-inline'>
<p>The generated sql statement</p>
</div>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='insertBatch' class='mt0'>
insertBatch<span class='gray'></span>
</h2>
<p>SQL to insert a group of rows</p>
<h4>Returns</h4>
<code><code>void</code></code>
<div class='force-inline'>
</div>
<h4>Throws</h4>
<ul>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error">Error</a></code>: <div class='force-inline'></div></li>
</ul>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='limit' class='mt0'>
limit<span class='gray'>(origSql, limit, offset)</span>
</h2>
<p>Set the limit clause</p>
<h4>Parameters</h4>
<ul class='suppress-p-margin'>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code> <strong>origSql</strong>
:
<div class='force-inline'>
<p>SQL statement to modify</p>
</div>
</li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a></code> <strong>limit</strong>
:
<div class='force-inline'>
<p>Maximum number of rows to fetch</p>
</div>
</li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a></code> or <strong>offset</strong>
:
<div class='force-inline'>
<p>Number of rows to skip</p>
</div>
</li>
</ul>
<h4>Returns</h4>
<code><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code></code>
:
<div class='force-inline'>
<p>Modified SQL statement</p>
</div>
</section>
</div><div class='py1'><section class='py2 clearfix'>
<h2 id='limit' class='mt0'>
limit<span class='gray'>(sql, limit, offset)</span>
</h2>
<p>Set the limit clause</p>
<h4>Parameters</h4>
<ul class='suppress-p-margin'>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code> <strong>sql</strong>
:
<div class='force-inline'>
<p>SQL statement to modify</p>
</div>
</li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a></code> <strong>limit</strong>
:
<div class='force-inline'>
<p>Maximum number of rows to fetch</p>
</div>
</li>
<li><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">Number</a></code> or <strong>offset</strong>
:
<div class='force-inline'>
<p>Number of rows to skip</p>
</div>
</li>
</ul>
<h4>Returns</h4>
<code><code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">String</a></code></code>
:
<div class='force-inline'>
<p>Modified SQL statement</p>
</div>
</section>
</div> </div>
</div> </div>
</div> </div>

View File

@ -89,9 +89,12 @@ gulp.task('sloc', () => gulp.src(SRC_FILES).pipe(sloc()));
gulp.task('test-sloc', () => gulp.src(TEST_FILES).pipe(sloc())); gulp.task('test-sloc', () => gulp.src(TEST_FILES).pipe(sloc()));
gulp.task('docs', () => { gulp.task('docs', () => {
gulp.src(['lib/*.js']) gulp.src(['lib/**/*.js'])
.pipe(documentation({format: 'html'})) .pipe(documentation({format: 'html'}))
.pipe(gulp.dest('docs')); .pipe(gulp.dest('docs'));
gulp.src(['lib/*.js'])
.pipe(documentation({format: 'md'}))
.pipe(gulp.dest('.'));
}); });
gulp.task('mocha', ['lint-tests', 'sloc'], () => { gulp.task('mocha', ['lint-tests', 'sloc'], () => {

View File

@ -298,7 +298,6 @@ class QueryBuilder {
/** /**
* Reset the object state for a new query * Reset the object state for a new query
* *
* @memberOf QueryBuilder
* @return {void} * @return {void}
*/ */
resetQuery() { resetQuery() {
@ -331,8 +330,9 @@ class QueryBuilder {
/** /**
* Specify rows to select in the query * Specify rows to select in the query
* *
* @memberOf QueryBuilder
* @param {String|Array} fields - The fields to select from the current table * @param {String|Array} fields - The fields to select from the current table
* @example query.select('foo, bar'); // Select multiple fields with a string
* @example query.select(['foo', 'bar']); // Select multiple fileds with an array
* @return {QueryBuilder} - The Query Builder object, for chaining * @return {QueryBuilder} - The Query Builder object, for chaining
*/ */
select(fields) { select(fields) {
@ -367,6 +367,8 @@ class QueryBuilder {
* Specify the database table to select from * Specify the database table to select from
* *
* @param {String} tableName - The table to use for the current query * @param {String} tableName - The table to use for the current query
* @example query.from('tableName');
* @example query.from('tableName t'); // Select the table with an alias
* @return {QueryBuilder} - The Query Builder object, for chaining * @return {QueryBuilder} - The Query Builder object, for chaining
*/ */
from(tableName) { from(tableName) {
@ -535,11 +537,11 @@ class QueryBuilder {
* Set a 'where in' clause * Set a 'where in' clause
* *
* @param {String} key - the field to search * @param {String} key - the field to search
* @param {Array} val - the array of items to search in * @param {Array} values - the array of items to search in
* @return {QueryBuilder} - The Query Builder object, for chaining * @return {QueryBuilder} - The Query Builder object, for chaining
*/ */
whereIn(key, val) { whereIn(key, values) {
this._whereIn(key, val, 'IN', 'AND'); this._whereIn(key, values, 'IN', 'AND');
return this; return this;
} }
@ -547,11 +549,11 @@ class QueryBuilder {
* Set a 'or where in' clause * Set a 'or where in' clause
* *
* @param {String} key - the field to search * @param {String} key - the field to search
* @param {Array} val - the array of items to search in * @param {Array} values - the array of items to search in
* @return {QueryBuilder} - The Query Builder object, for chaining * @return {QueryBuilder} - The Query Builder object, for chaining
*/ */
orWhereIn(key, val) { orWhereIn(key, values) {
this._whereIn(key, val, 'IN', 'OR'); this._whereIn(key, values, 'IN', 'OR');
return this; return this;
} }
@ -559,11 +561,11 @@ class QueryBuilder {
* Set a 'where not in' clause * Set a 'where not in' clause
* *
* @param {String} key - the field to search * @param {String} key - the field to search
* @param {Array} val - the array of items to search in * @param {Array} values - the array of items to search in
* @return {QueryBuilder} - The Query Builder object, for chaining * @return {QueryBuilder} - The Query Builder object, for chaining
*/ */
whereNotIn(key, val) { whereNotIn(key, values) {
this._whereIn(key, val, 'NOT IN', 'AND'); this._whereIn(key, values, 'NOT IN', 'AND');
return this; return this;
} }
@ -571,11 +573,11 @@ class QueryBuilder {
* Set a 'or where not in' clause * Set a 'or where not in' clause
* *
* @param {String} key - the field to search * @param {String} key - the field to search
* @param {Array} val - the array of items to search in * @param {Array} values - the array of items to search in
* @return {QueryBuilder} - The Query Builder object, for chaining * @return {QueryBuilder} - The Query Builder object, for chaining
*/ */
orWhereNotIn(key, val) { orWhereNotIn(key, values) {
this._whereIn(key, val, 'NOT IN', 'OR'); this._whereIn(key, values, 'NOT IN', 'OR');
return this; return this;
} }
@ -584,6 +586,8 @@ class QueryBuilder {
* *
* @param {String|Object} key - The key or object to use * @param {String|Object} key - The key or object to use
* @param {String} [val] - The value if using a scalar key * @param {String} [val] - The value if using a scalar key
* @example query.set('foo', 'bar'); // Set a key, value pair
* @example query.set({foo:'bar'}); // Set with an object
* @return {QueryBuilder} - The Query Builder object, for chaining * @return {QueryBuilder} - The Query Builder object, for chaining
*/ */
set(/* $key, [$val] */) { set(/* $key, [$val] */) {
@ -750,6 +754,9 @@ class QueryBuilder {
* @param {Number} [limit] - A limit for the query * @param {Number} [limit] - A limit for the query
* @param {Number} [offset] - An offset for the query * @param {Number} [offset] - An offset for the query
* @param {Function} [callback] - A callback for receiving the result * @param {Function} [callback] - A callback for receiving the result
* @example query.get('table_name').then(promiseCallback); // Get all the rows in the table
* @example query.get('table_name', 5, callback); // Get 5 rows from the table
* @example query.get(callback); // Get the results of a query generated with other methods
* @return {void|Promise} - If no callback is passed, a promise is returned * @return {void|Promise} - If no callback is passed, a promise is returned
*/ */
get(/* [table], [limit], [offset], [callback] */) { get(/* [table], [limit], [offset], [callback] */) {
@ -793,6 +800,8 @@ class QueryBuilder {
* @param {Array} data - The array of objects containing data rows to insert * @param {Array} data - The array of objects containing data rows to insert
* @param {Function} [callback] - Callback for handling database response * @param {Function} [callback] - Callback for handling database response
* @example query.insertBatch('foo',[{id:1,val:'bar'},{id:2,val:'baz'}], callbackFunction); * @example query.insertBatch('foo',[{id:1,val:'bar'},{id:2,val:'baz'}], callbackFunction);
* @example query.insertBatch('foo',[{id:1,val:'bar'},{id:2,val:'baz'}])
*.then(promiseCallback);
* @return {void|Promise} - If no callback is passed, a promise is returned * @return {void|Promise} - If no callback is passed, a promise is returned
*/ */
insertBatch(/* table, data, callback */) { insertBatch(/* table, data, callback */) {