feat(builder): accept array for include, append and orderBy (#148)

Accept array of strings for `include`, `append` and `orderBy`.

Author: JoaoPedroAS51

docs/content/en/api/query-builder-methods.md

@@ -15,14 +15,30 @@ Eager load relationships.
 await Model.include('user', 'category')
 ```
 
+#### Array
+
+<alert type="success">Available in version >= v1.8.0</alert>
+
+```js
+await Model.include(['user', 'category'])
+```
+
 ## `append`
 - Arguments: `(...args)`
 - Returns: `self`
 
 Append attributes.
 
 ```js
-await Model.append('likes')
+await Model.append('likes', 'shares')
+```
+
+#### Array
+
+<alert type="success">Available in version >= v1.8.0</alert>
+
+```js
+await Model.append(['likes', 'shares'])
 ```
 
 ## `select`
@@ -31,12 +47,12 @@ await Model.append('likes')
 
 Set the columns to be selected.
 
-**Single entity:**
+#### Single entity
 ```js
 await Model.select(['title', 'content'])
 ```
 
-**Related entities:**
+#### Related entities
 ```js
 await Post.select({
   posts: ['title', 'content'],
@@ -50,13 +66,11 @@ await Post.select({
 
 Add a basic where clause to the query.
 
-**Simple:**
-
 ```js
 await Model.where('status', 'active')
 ```
 
-**Nested:**
+#### Nested
 
 <alert type="success">Available in version >= v1.8.0</alert>
 
@@ -70,13 +84,11 @@ await Model.where(['user', 'status'], 'active')
 
 Add a "where in" clause to the query.
 
-**Simple:**
-
 ```js
 await Model.whereIn('id', [1, 2, 3])
 ```
 
-**Nested:**
+#### Nested
 
 <alert type="success">Available in version >= v1.8.0</alert>
 
@@ -94,6 +106,14 @@ Add an "order by" clause to the query.
 await Model.orderBy('-created_at', 'category_id')  
 ```
 
+#### Array
+
+<alert type="success">Available in version >= v1.8.0</alert>
+
+```js
+await Model.orderBy(['-created_at', 'category_id'])  
+```
+
 ## `page`
 - Arguments: `(value)`
 - Returns: `self`

docs/content/en/building-the-query.md

@@ -334,7 +334,7 @@ We also need to sort our queries, so let's do this now!
 The method we want to use now is `orderBy`. The arguments are the names of the properties we want to sort.
 We can pass as many arguments as we want. 
 
-**Single Sort**
+#### Single Sort
 
 We can sort our **Posts** by the `created_at` date:
 
@@ -355,7 +355,7 @@ We can sort our **Posts** by the `created_at` date:
   </code-block>
 </code-group>
 
-**Multiple Sort**
+#### Multiple Sort
 
 And we can sort by their `title` too:
 
@@ -380,27 +380,73 @@ And we can sort by their `title` too:
   Sorting is ascending by default and can be reversed by adding a hyphen (-) to the start of the property name.
 </alert>
 
+#### Using an Array
+
+<alert type="success">Available in version >= v1.8.0</alert>
+
+The first argument of `orderBy` also accepts an array of string.
+
+<code-group>
+  <code-block label="Query" active>
+
+  ```js
+  const posts = await Post.orderBy(['-created_at', 'title']).get()
+  ```
+
+  </code-block>
+  <code-block label="Request">
+
+  ```http request
+  GET /posts?sort=-created_at
+  ```
+
+  </code-block>
+</code-group>
+
 ## Including Relationships
 
 See the [API reference](/api/query-builder-methods#include)
 
 Sometimes, we will want to eager load a relationship, and to do so, we can use the `include` method.
 The arguments are the names of the relationships we want to include. We can pass as many arguments as we want.
 
-Let's eager load the `category` relationship of our **Post**:
+Let's eager load the relationships `category` and `tags` of our **Post**:
+
+<code-group>
+  <code-block label="Query" active>
+
+  ```js
+  const posts = await Post.include('category', 'tags').get()
+  ```
+
+  </code-block>
+  <code-block label="Request">
+
+  ```http request
+  GET /posts?include=category,tags
+  ```
+
+  </code-block>
+</code-group>
+
+#### Using an Array
+
+<alert type="success">Available in version >= v1.8.0</alert>
+
+The first argument of `include` also accepts an array of string.
 
 <code-group>
   <code-block label="Query" active>
 
   ```js
-  const posts = await Post.include('category').get()
+  const posts = await Post.include(['category', 'tags']).get()
   ```
 
   </code-block>
   <code-block label="Request">
 
   ```http request
-  GET /posts?include=category
+  GET /posts?include=category,tags
   ```
 
   </code-block>
@@ -413,20 +459,43 @@ See the [API reference](/api/query-builder-methods#append)
 We can also append attributes to our queries using the `append` method.
 The arguments are the names of the attributes we want to append. We can pass as many arguments as we want.
 
-Let's append the `likes` attribute of our **Post**:
+Let's append the attribute `likes` and `shares` of our **Post**:
+
+<code-group>
+  <code-block label="Query" active>
+
+  ```js
+  const posts = await Post.append('likes', 'shares').get()
+  ```
+
+  </code-block>
+  <code-block label="Request">
+
+  ```http request
+  GET /posts?append=likes,shares
+  ```
+
+  </code-block>
+</code-group>
+
+#### Using an Array
+
+<alert type="success">Available in version >= v1.8.0</alert>
+
+The first argument of `append` also accepts an array of string.
 
 <code-group>
   <code-block label="Query" active>
 
   ```js
-  const posts = await Post.append('likes').get()
+  const posts = await Post.append(['likes', 'shares']).get()
   ```
 
   </code-block>
   <code-block label="Request">
 
   ```http request
-  GET /posts?append=likes
+  GET /posts?append=likes,shares
   ```
 
   </code-block>

src/Builder.js

@@ -63,14 +63,16 @@ export default class Builder {
    * Query builder
    */
 
-  include(...args) {
-    this.includes = args
+  include(...relationships) {
+    relationships = Array.isArray(relationships[0]) ? relationships[0] : relationships
+    this.includes = relationships
 
     return this
   }
 
-  append(...args) {
-    this.appends = args
+  append(...attributes) {
+    attributes = Array.isArray(attributes[0]) ? attributes[0] : attributes
+    this.appends = attributes
 
     return this
   }
@@ -131,8 +133,9 @@ export default class Builder {
     return this
   }
 
-  orderBy(...args) {
-    this.sorts = args
+  orderBy(...fields) {
+    fields = Array.isArray(fields[0]) ? fields[0] : fields
+    this.sorts = fields
 
     return this
   }

tests/builder.test.js

@@ -64,6 +64,10 @@ describe('Query builder', () => {
     post = Post.include('user', 'category')
 
     expect(post._builder.includes).toEqual(['user', 'category'])
+
+    post = Post.include(['user', 'category'])
+
+    expect(post._builder.includes).toEqual(['user', 'category'])
   })
 
   test('append() sets properly the builder', () => {
@@ -74,6 +78,10 @@ describe('Query builder', () => {
     post = Post.append('likes', 'visits')
 
     expect(post._builder.appends).toEqual(['likes', 'visits'])
+
+    post = Post.append(['likes', 'visits'])
+
+    expect(post._builder.appends).toEqual(['likes', 'visits'])
   })
 
   test('orderBy() sets properly the builder', () => {
@@ -84,6 +92,10 @@ describe('Query builder', () => {
     post = Post.orderBy('created_at', '-visits')
 
     expect(post._builder.sorts).toEqual(['created_at', '-visits'])
+
+    post = Post.orderBy(['created_at', '-visits'])
+
+    expect(post._builder.sorts).toEqual(['created_at', '-visits'])
   })
 
   test('where() sets properly the builder', () => {
@@ -141,7 +153,6 @@ describe('Query builder', () => {
     expect(errorModel).toThrow('The second argument on whereIn() method must be an array.')
   })
 
-
   test('page() sets properly the builder', () => {
     let post = Post.page(3)