feat(return): add distinct option

Return now supports an additional options parameter that contains a `distinct` flag. Setting it to
true will cause the return clause to only return unique rows. In addition, the `returnDistinct`
method was added to the query interface as a shortcut to `return(..., { distinct: true }).

fix #90

src/builder.ts

@@ -14,6 +14,7 @@ import { AnyConditions } from './clauses/where-utils';
 import { Clause } from './clause';
 import { RemoveProperties } from './clauses/remove';
 import { Union } from './clauses/union';
+import { ReturnOptions } from './clauses/return';
 
 /**
  * @internal
@@ -619,13 +620,24 @@ export abstract class Builder<Q> extends SetBlock<Q> {
    *
    * You can also pass an array of any of the above methods.
    *
-   * @param {_.Many<Term>} terms
-   * @returns {Q}
+   * The return method also accepts a `distinct` option which will cause a `RETURN DISTINCT` to be
+   * emitted instead.
+   * ```javascript
+   * query.return('people', { distinct: true })
+   * // RETURN DISTINCT people
+   * ```
    */
-  return(terms: Many<Term>) {
+  return(terms: Many<Term>, options?: ReturnOptions) {
     return this.continueChainClause(new Return(terms));
   }
 
+  /**
+   * Shorthand for `return(terms, { distinct: true });
+   */
+  returnDistinct(terms: Many<Term>) {
+    return this.return(terms, { distinct: true });
+  }
+
   /**
    * Adds a [skip]{@link https://neo4j.com/docs/developer-manual/current/cypher/clauses/skip}
    * clause to the query.

src/clauses/return.spec.ts

@@ -7,5 +7,10 @@ describe('Return', () => {
       const query = new Return('node');
       expect(query.build()).to.equal('RETURN node');
     });
+
+    it('should start with RETURN DISTINCT', () => {
+      const query = new Return('node', { distinct: true });
+      expect(query.build()).to.equal('RETURN DISTINCT node');
+    });
   });
 });

src/clauses/return.ts

@@ -1,16 +1,17 @@
 import { Many } from 'lodash';
 import { Term, TermListClause } from './term-list-clause';
 
+export interface ReturnOptions {
+  distinct?: boolean;
+}
+
 export class Return extends TermListClause {
-  /**
-   * Creates a return clause
-   * @param  {string|object|array<string|object>|} terms [description]
-   */
-  constructor(terms: Many<Term>) {
+  constructor(terms: Many<Term>, protected options: ReturnOptions = {}) {
     super(terms);
   }
 
   build() {
-    return `RETURN ${super.build()}`;
+    const distinct = this.options.distinct ? ' DISTINCT' : '';
+    return `RETURN${distinct} ${super.build()}`;
   }
 }

tests/connection.test.ts

@@ -234,6 +234,7 @@ describe('Connection', () => {
       createNode: () => connection.createNode('Node'),
       create: () => connection.create(new NodePattern('Node')),
       return: () => connection.return('node'),
+      returnDistinct: () => connection.returnDistinct('node'),
       remove: () => connection.remove({ properties: { node: ['prop1', 'prop2'] } }),
       removeProperties: () => connection.removeProperties({ node: ['prop1', 'prop2'] }),
       removeLabels: () => connection.removeLabels({ node: 'label' }),