feat(builder): add support to pass an object as argument in where and whereIn methods

Closes robsontenorio#205

Author: JoaoPedroAS51

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

@@ -80,6 +80,14 @@ await Model.where('status', 'active')
 await Model.where(['user', 'status'], 'active')
 ```
 
+#### Object
+
+<alert type="success">Available in version >= v1.10.0</alert>
+
+```js
+await Model.where({ user: { status: 'active' } })
+```
+
 ## `whereIn`
 - Arguments: `(field, array)`
 - Returns: `self`
@@ -98,6 +106,14 @@ await Model.whereIn('id', [1, 2, 3])
 await Model.whereIn(['user', 'id'], [1, 2, 3])
 ```
 
+#### Object
+
+<alert type="success">Available in version >= v1.10.0</alert>
+
+```js
+await Model.where({ user: { id: [1, 2, 3] } })
+```
+
 ## `orderBy`
 - Arguments: `(...args)`
 - Returns: `self`

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

@@ -276,6 +276,34 @@ So we can filter our **Posts** to only get results where `status` of `user` is `
   </code-block>
 </code-group>
 
+#### Using an Object
+
+<alert type="success">Available in version >= v1.10.0</alert>
+
+Now is also possible to pass an object.
+
+<code-group>
+  <code-block label="Query" active>
+
+  ```js
+  const posts = await Post.where({
+    status: 'published',
+    user: {
+      status: 'active'
+    }
+  }).get()
+  ```
+
+  </code-block>
+  <code-block label="Request">
+
+  ```http request
+  GET /posts?filter[status]=published&filter[user][status]=active
+  ```
+
+  </code-block>
+</code-group>
+
 ### Evaluating Multiple Values
 
 See the [API reference](/api/query-builder-methods#wherein)
@@ -332,6 +360,34 @@ So we can filter our **Posts** to only get results where `status` of `user` is `
   </code-block>
 </code-group>
 
+#### Using an Object
+
+<alert type="success">Available in version >= v1.10.0</alert>
+
+Now is also possible to pass an object.
+
+<code-group>
+  <code-block label="Query" active>
+
+  ```js
+  const posts = await Post.where({
+    status: ['published', 'archived'],
+    user: {
+      status: ['active', 'inactive']
+    }
+  }).get()
+  ```
+
+  </code-block>
+  <code-block label="Request">
+
+  ```http request
+  GET /posts?filter[status]=published,archived&filter[user][status]=active,inactive
+  ```
+
+  </code-block>
+</code-group>
+
 ## Sorting
 
 See the [API reference](/api/query-builder-methods#orderby)

index.d.ts

@@ -150,6 +150,17 @@ declare class StaticModel {
     value: string | number | boolean
   ): InstanceType<M>
 
+  /**
+   * Add a basic where clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#where|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#evaluating-a-single-value|Building the Query}
+   */
+  static where<M extends typeof Model> (
+    this: M,
+    filter: Record<string, any>
+  ): InstanceType<M>
+
   /**
    * Add a "where in" clause to the query.
    *
@@ -162,6 +173,17 @@ declare class StaticModel {
     values: (string | number | boolean)[]
   ): InstanceType<M>
 
+  /**
+   * Add a "where in" clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#wherein|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#evaluating-multiple-values|Building the Query}
+   */
+  static whereIn<M extends typeof Model> (
+    this: M,
+    filter: Record<string, any>
+  ): InstanceType<M>
+
   /**
    * Add an "order by" clause to the query.
    *
@@ -519,6 +541,14 @@ export class Model extends StaticModel {
    */
   where (field: string | string[], value: string | number | boolean): this
 
+  /**
+   * Add a basic where clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#where|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#evaluating-a-single-value|Building the Query}
+   */
+  where (filter: Record<string, any>): this
+
   /**
    * Add a "where in" clause to the query.
    *
@@ -527,6 +557,14 @@ export class Model extends StaticModel {
    */
   whereIn (field: string | string[], array: (string | number | boolean)[]): this
 
+  /**
+   * Add a "where in" clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#wherein|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#evaluating-multiple-values|Building the Query}
+   */
+  whereIn (filter: Record<string, any>): this
+
   /**
    * Add an "order by" clause to the query.
    *
@@ -813,6 +851,14 @@ declare class Builder {
    */
   where (field: string | string[], value: string | number | boolean): this
 
+  /**
+   * Add a basic where clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#where|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#evaluating-a-single-value|Building the Query}
+   */
+  where (filter: Record<string, any>): this
+
   /**
    * Add a "where in" clause to the query.
    *
@@ -821,6 +867,14 @@ declare class Builder {
    */
   whereIn (field: string | string[], array: (string | number | boolean)[]): this
 
+  /**
+   * Add a "where in" clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#wherein|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#evaluating-multiple-values|Building the Query}
+   */
+  whereIn (filter: Record<string, any>): this
+
   /**
    * Add an "order by" clause to the query.
    *

src/Builder.js

@@ -100,7 +100,7 @@ export default class Builder {
   }
 
   where(key, value) {
-    if (key === undefined || value === undefined) {
+    if (key === undefined || (typeof key !== 'object' && value === undefined)) {
       throw new Error('The KEY and VALUE are required on where() method.')
     }
 
@@ -112,6 +112,11 @@ export default class Builder {
       const [_key, _value] = this._nestedFilter(key, value)
 
       this.filters[_key] = { ...this.filters[_key], ..._value }
+    } else if (typeof key === 'object') {
+      this.filters = {
+        ...this.filters,
+        ...key
+      }
     } else {
       this.filters[key] = value
     }
@@ -120,7 +125,7 @@ export default class Builder {
   }
 
   whereIn(key, array) {
-    if (!Array.isArray(array)) {
+    if (typeof key !== 'object' && !Array.isArray(array)) {
       throw new Error(
         'The second argument on whereIn() method must be an array.'
       )
@@ -130,6 +135,11 @@ export default class Builder {
       const [_key, _value] = this._nestedFilter(key, array)
 
       this.filters[_key] = { ...this.filters[_key], ..._value }
+    } else if (typeof key === 'object') {
+      this.filters = {
+        ...this.filters,
+        ...key
+      }
     } else {
       this.filters[key] = array
     }

tests/builder.test.js

@@ -133,6 +133,18 @@ describe('Query builder', () => {
     expect(post._builder.query()).toEqual(
       '?filter[schedule][start]=2020-11-27&filter[schedule][end]=2020-11-28'
     )
+
+    post = Post.where({ id: 1, title: 'Cool' }).when(true, (query) =>
+      query.where({ user: { status: 'active' } })
+    )
+
+    expect(post._builder.filters).toEqual({
+      id: 1,
+      title: 'Cool',
+      user: {
+        status: 'active'
+      }
+    })
   })
 
   test('where() throws a exception when doest not have params or only first param', () => {
@@ -189,6 +201,17 @@ describe('Query builder', () => {
     expect(post._builder.query()).toEqual(
       '?filter[schedule][start]=2020-11-27,2020-11-28&filter[schedule][end]=2020-11-28,2020-11-29'
     )
+
+    post = Post.where({ status: ['ACTIVE', 'ARCHIVED'] }).when(true, (query) =>
+      query.where({ user: { status: ['active', 'inactive'] } })
+    )
+
+    expect(post._builder.filters).toEqual({
+      status: ['ACTIVE', 'ARCHIVED'],
+      user: {
+        status: ['active', 'inactive']
+      }
+    })
   })
 
   test('whereIn() throws a exception when second parameter is not a array', () => {