documentation for templates, a lot of examples some fixes

.gitignore

@@ -1,2 +1,3 @@
 node_modules/
-coverage/
+coverage/
+npm-debug.log

.npmignore

@@ -1,2 +1,5 @@
-.npmignore
+tests/
-test
+examples/
+coverage/
+docs/
+gulpfile.js

LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2013-2014 Oleg Korobenko <oleg.korobenko@gmail.com>
+Copyright (c) 2013-2015 2do2go team <dev.2do2go@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.md

@@ -142,4 +142,4 @@ $ gulp coverage
 
 ## License
 
-MIT
+[MIT](./LICENSE)

docs/README.md

@@ -53,9 +53,62 @@ Return object with properties:
 | `getValuesArray` | Method to get values as array.<br>Exists only if `separatedValues = true`. |
 | `getValuesObject` | Method to get values as object.<br>Exists only if `separatedValues = true`. |
 
-## Queries
+## Query types
 
 ### select
 
-__template:__ `{with} {withRecursive} select {distinct} {fields} from {from} {table} {query} {select} {expression} {alias} {join} {condition} {group} {sort} {limit} {offset}`
+Template for select queries.
 
+__template:__ `{with} {withRecursive} select {distinct} {fields} from {table} {query} {select} {expression} {alias} {join} {condition} {group} {sort} {limit} {offset}`
+
+### insert
+
+Template for insert queries.
+
+__template:__ `{with} {withRecursive} insert {or} into {table} {values} {condition} {returning}`
+
+### update
+
+Template for update queries.
+
+__template:__ `{with} {withRecursive} update {or} {table} {modifier} {condition} {returning}`
+
+### remove
+
+Template for remove queries.
+
+__template:__ `{with} {withRecursive} delete from {table} {condition} {returning}`
+
+### union / intersect / except
+
+Template for union, intersect and except queries.
+
+__template:__ `{with} {withRecursive} {queries} {sort} {limit} {offset}`
+
+### Auxiliary templates
+
+Templates below are used inside of blocks:
+
+### subQuery
+
+Template is used to build subqueries.
+
+__template:__ `({queryBody})`
+
+### insertValues
+
+Template is used by `values` block.
+
+__template:__ `({fields}) values {fieldValues}`
+
+### joinItem
+
+Template is used by `join` block to build each item.
+
+__template:__ `{type} join {table} {query} {select} {expression} {alias} {on}`
+
+### withItem
+
+Template is used by `with` and `withRecursive` blocks to build each item.
+
+__template:__ `{name} {fields} as {query} {select} {expression}`

examples/common/condition.md

@@ -0,0 +1,49 @@
+# Condition
+
+## Example 1 - array
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    condition: [
+        {a: {$gt: 1}},
+        {b: {$lt: 10}}
+    ]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" where "a" > 1 and "b" < 10;
+
+sql.values
+// {}
+```
+
+## Example 2 - object
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    condition: {
+        a: {$gt: 1},
+        b: {$lt: 10}
+    }
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" where "a" > 1 and "b" < 10;
+
+sql.values
+// {}
+```

examples/common/returning.md

@@ -0,0 +1,22 @@
+# Returning
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'insert',
+    table: 'table',
+    values: {a: 5},
+    returning: ['table.*']
+});
+```
+
+Result:
+
+``` js
+sql.query
+// insert into "table" ("a") values (5) returning "table".*;
+
+sql.values
+// {}
+```

examples/common/table.md

@@ -0,0 +1,19 @@
+# Table
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table";
+
+sql.values
+// {}
+```

examples/common/with.md

@@ -0,0 +1,51 @@
+# With
+
+## Example 1 - array
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    'with': [{
+        name: 'table',
+        select: {table: 'withTable'}
+    }],
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// with "table" as (select * from "withTable") select * from "table";
+
+sql.values
+// {}
+```
+
+
+## Example 2 - object
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    'with': {
+        table: {
+            select: {table: 'withTable'}
+        }
+    },
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// with "table" as (select * from "withTable") select * from "table";
+
+sql.values
+// {}
+```

examples/common/withRecursive.md

@@ -0,0 +1,51 @@
+# With (recursive)
+
+## Example 1 - array
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    withRecursive: [{
+        name: 'table',
+        select: {table: 'withTable'}
+    }],
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// with recursive "table" as (select * from "withTable") select * from "table";
+
+sql.values
+// {}
+```
+
+
+## Example 2 - object
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    withRecursive: {
+        table: {
+            select: {table: 'withTable'}
+        }
+    },
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// with recursive "table" as (select * from "withTable") select * from "table";
+
+sql.values
+// {}
+```

examples/insert/values.md

@@ -0,0 +1,46 @@
+# Values
+
+# Example 1 - values only
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'insert',
+    table: 'table',
+    values: {a: 5, b: 'text'}
+});
+```
+
+Result:
+
+``` js
+sql.query
+// insert into "table" ("a", "b") values (5, $p1);
+
+sql.values
+// {p1: 'text'}
+```
+
+# Example 2 - fields + values
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'insert',
+    table: 'table',
+    fields: ['a', 'b', 'c'],
+    values: {b: 5, c: 'text'}
+});
+```
+
+Result:
+
+``` js
+sql.query
+// insert into "table" ("a", "b", "c") values (null, 5, $p1);
+
+sql.values
+// {p1: 'text'}
+```

examples/remove/remove.md

@@ -0,0 +1,20 @@
+# Basic remove query
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'remove',
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// delete from "test";
+
+sql.values
+// {}
+```

examples/select/alias.md

@@ -0,0 +1,20 @@
+# Alias
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    alias: 'alias'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" as "alias";
+
+sql.values
+// {}
+```

examples/select/distinct.md

@@ -0,0 +1,20 @@
+# Distinct
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    distinct: true,
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select distinct * from "table";
+
+sql.values
+// {}
+```

examples/select/expression.md

@@ -0,0 +1,22 @@
+# Expression
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    expression: {
+        pattern: 'generate_series({start}, {stop})',
+        values: {start: 2, stop: 4}
+    }
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from generate_series(2, 4);
+
+sql.values
+// {}
+```

examples/select/fields.md

@@ -0,0 +1,71 @@
+# Fields
+
+## Example 1 - without fields (*)
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table";
+
+sql.values
+// {}
+```
+
+## Example 2 - array
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    fields: [
+        'a',
+        {b: 'c'},
+        {table: 'd', name: 'e', alias: 'f'},
+        ['g']
+    ],
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select "a", "b" as "c", "d"."e" as "f", "g" from "table";
+
+sql.values
+// {}
+```
+
+## Example 3 - object
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    fields: {
+        a: 'b',
+        d: {table: 'c', alias: 'e'}
+    },
+    table: 'table'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select "a" as "b", "c"."d" as "e" from "table";
+
+sql.values
+// {}
+```

examples/select/group.md

@@ -0,0 +1,43 @@
+# Group
+
+## Example 1 - single column
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    group: 'a'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" group by "a";
+
+sql.values
+// {}
+```
+
+## Example 2 - multiple columns
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    group: ['a', 'b']
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" group by "a", "b";
+
+sql.values
+// {}
+```

examples/select/join.md

@@ -0,0 +1,77 @@
+# Join
+
+## Example 1 - array
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    join: [{
+        type: 'right',
+        table: 'joinTable',
+        on: {'table.a': 'joinTable.b'}
+    }]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" right join "joinTable" on "table"."a" = "joinTable"."b";
+
+sql.values
+// {}
+```
+
+## Example 2 - object
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    join: {
+        joinTable: {
+            type: 'inner',
+            on: {'table.a': 'joinTable.b'}
+        }
+    }]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" inner join "joinTable" on "table"."a" = "joinTable"."b";
+
+sql.values
+// {}
+```
+
+### Example 3 - join with subselect
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    join: [{
+        select: {table: 'joinTable'},
+        alias: 'joinTable',
+        on: {'table.a': 'joinTable.b'}
+    }]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" join (select * from "joinTable") as "joinTable" on "table"."a" = "joinTable"."b";
+
+sql.values
+// {}
+```

examples/select/limit.md

@@ -0,0 +1,20 @@
+# Limit
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    limit: 5
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" limit 5;
+
+sql.values
+// {}
+```

examples/select/offset.md

@@ -0,0 +1,20 @@
+# Offset
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    offset: 5
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" offset 5;
+
+sql.values
+// {}
+```

examples/select/sort.md

@@ -0,0 +1,64 @@
+# Sort
+
+## Example 1 - single column
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    sort: 'a'
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" order by "a";
+
+sql.values
+// {}
+```
+
+## Example 2 - multiple columns
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    sort: ['a', 'b']
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" order by "a", "b";
+
+sql.values
+// {}
+```
+
+## Example 3 - multiple columns with order
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    table: 'table',
+    sort: {a: 1, b: -1}
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from "table" order by "a" asc, "b" desc;
+
+sql.values
+// {}
+```

examples/select/subquery.md

@@ -0,0 +1,19 @@
+# Subquery
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    query: {type: 'select', table: 'table'}
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from (select * from "table");
+
+sql.values
+// {}
+```

examples/select/subselect.md

@@ -0,0 +1,19 @@
+# Subselect
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    select: {table: 'table'}
+});
+```
+
+Result:
+
+``` js
+sql.query
+// select * from (select * from "table");
+
+sql.values
+// {}
+```

examples/union_intersect_except/except.md

@@ -0,0 +1,50 @@
+# Except query
+
+# Example 1 - except
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'except',
+    queries: [
+        {type: 'select', table: 'table1'},
+        {type: 'select', table: 'table2'}
+    ]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// (select * from "table1") except (select * from "table2");
+
+sql.values
+// {}
+```
+
+# Example 2 - except all
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'except',
+    all: true,
+    queries: [
+        {type: 'select', table: 'table1'},
+        {type: 'select', table: 'table2'}
+    ]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// (select * from "table1") except all (select * from "table2");
+
+sql.values
+// {}
+```

examples/union_intersect_except/intersect.md

@@ -0,0 +1,50 @@
+# Intersect query
+
+# Example 1 - intersect
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'intersect',
+    queries: [
+        {type: 'select', table: 'table1'},
+        {type: 'select', table: 'table2'}
+    ]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// (select * from "table1") intersect (select * from "table2");
+
+sql.values
+// {}
+```
+
+# Example 2 - intersect all
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'intersect',
+    all: true,
+    queries: [
+        {type: 'select', table: 'table1'},
+        {type: 'select', table: 'table2'}
+    ]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// (select * from "table1") intersect all (select * from "table2");
+
+sql.values
+// {}
+```

examples/union_intersect_except/union.md

@@ -0,0 +1,50 @@
+# Union query
+
+# Example 1 - union
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'union',
+    queries: [
+        {type: 'select', table: 'table1'},
+        {type: 'select', table: 'table2'}
+    ]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// (select * from "table1") union (select * from "table2");
+
+sql.values
+// {}
+```
+
+# Example 2 - union all
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'union',
+    all: true,
+    queries: [
+        {type: 'select', table: 'table1'},
+        {type: 'select', table: 'table2'}
+    ]
+});
+```
+
+Result:
+
+``` js
+sql.query
+// (select * from "table1") union all (select * from "table2");
+
+sql.values
+// {}
+```

examples/update/modifier.md

@@ -0,0 +1,49 @@
+# Modifier
+
+## Example 1 - default modifier
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'update',
+    table: 'table',
+    modifier: {a: 5}
+});
+```
+
+Result:
+
+``` js
+sql.query
+// update "table" set "a" = 5;
+
+sql.values
+// {}
+```
+
+## Example 2 - specific modifiers
+
+Query:
+
+``` js
+var sql = jsonSql.build({
+    type: 'update',
+    table: 'table',
+    modifier: {
+        $set: {a: 5},
+        $default: {b: true},
+        $inc: {c: 10}
+    }
+});
+```
+
+Result:
+
+``` js
+sql.query
+// update "table" set "a" = 5, "b" = default, "c" = "c" + 10;
+
+sql.values
+// {}
+```

lib/dialects/base/blocks.js

@@ -21,7 +21,7 @@ var hasSome = function(obj, keys) {
 
 var fieldProps = ['select', 'query', 'field', 'value', 'name', 'func', 'expression'];
 var isFieldObject = function(obj) {
-	return hasSome(obj, fieldProps);
+	return _.isObject(obj) && !_.isArray(obj) && hasSome(obj, fieldProps);
 };
 
 var isSimpleValue = function(value) {
@@ -29,7 +29,6 @@ var isSimpleValue = function(value) {
 		_.isString(value) ||
 		_.isNumber(value) ||
 		_.isBoolean(value) ||
-		_.isArray(value) ||
 		_.isNull(value) ||
 		_.isUndefined(value) ||
 		_.isRegExp(value) ||
@@ -46,7 +45,7 @@ module.exports = function(dialect) {
 		var type = params.type || 'name';
 		var field = params.field;
 
-		if (isSimpleValue(field)) {
+		if (isSimpleValue(field) || _.isArray(field)) {
 			field = _.object([_.isString(field) ? type : 'value'], [field]);
 		}
 

lib/dialects/base/templates.js

@@ -63,7 +63,7 @@ module.exports = function(dialect) {
 			checkStringProp('join', params, 'table');
 			checkObjectProp('join', params, 'query');
 			checkObjectProp('join', params, 'select');
-			checkStringProp('join', params, 'expression');
+			// checkStringProp('join', params, 'expression');
 
 			checkStringProp('join', params, 'type');
 			checkCustomProp('join', params, 'type', function(value) {
@@ -87,7 +87,7 @@ module.exports = function(dialect) {
 
 			checkObjectProp('with', params, 'query');
 			checkObjectProp('with', params, 'select');
-			checkStringProp('with', params, 'expression');
+			// checkStringProp('with', params, 'expression');
 		}
 	});
 
@@ -101,7 +101,7 @@ module.exports = function(dialect) {
 			checkStringProp('from', params, 'table');
 			checkObjectProp('from', params, 'query');
 			checkObjectProp('from', params, 'select');
-			checkStringProp('from', params, 'expression');
+			// checkStringProp('from', params, 'expression');
 		}
 	});
 
@@ -122,7 +122,7 @@ module.exports = function(dialect) {
 			checkStringProp(type, params, 'table');
 			checkObjectProp(type, params, 'query');
 			checkObjectProp(type, params, 'select');
-			checkStringProp(type, params, 'expression');
+			// checkStringProp(type, params, 'expression');
 
 			checkOnlyOneOfProps(type, params, availableWithProps);
 
@@ -134,6 +134,8 @@ module.exports = function(dialect) {
 	dialect.templates.add('insert', {
 		pattern: '{with} {withRecursive} insert {or} into {table} {values} {condition} {returning}',
 		validate: function(type, params) {
+			checkArrayProp(type, params, 'fields');
+
 			checkRequiredProp(type, params, 'values');
 			checkObjectProp(type, params, 'values');