feat(builder): add when method

Closes #219

Author: JoaoPedroAS51

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

@@ -162,6 +162,20 @@ Add custom parameters to the query.
   </code-block>
 </code-group>
 
+## `when`
+<alert type="success">Available in version >= v1.10.0</alert>
+
+- Arguments: `(value, callback)`
+- Returns: `self`
+
+Add a conditional clause to the query.
+
+```js
+const search = 'foo'
+
+await Model.when(search, (query, value) => query.where('search', value))
+```
+
 ## `custom`
 - Arguments: `(...args)`
 - Returns: `self`

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

@@ -597,11 +597,38 @@ Let's say we are at page 1, and we want 20 **Posts** per page:
   </code-block>
 </code-group>
 
+## Conditional
+
+<alert type="success">Available in version >= v1.10.0</alert>
+
+We may need to add a clause based on a condition, and we can do so by using the `when` method.
+The first argument is the flag, and the second argument is the callback with the clause we want.
+
+
+<code-group>
+  <code-block label="Query" active>
+
+  ```js
+  const search = 'foo'
+  const posts = await Post.when(search, (query, value) => query.where('title', value)).get()
+  ```
+
+  </code-block>
+  <code-block label="Request">
+
+  ```http request
+  GET /posts?filter[title]=foo
+  ```
+
+  </code-block>
+</code-group>
+
+
 ## Applying Custom Parameters
 
 See the [API reference](/api/query-builder-methods#params)
 
-We may need to use parameters that are not provided by [vue-api-query](https://github.com/robsontenorio/vue-api-query),
+We may also need to use parameters that are not provided by [vue-api-query](https://github.com/robsontenorio/vue-api-query),
 and that's when the `params` method comes in to help.
 
 The argument is an object of the parameters to add to the query.

index.d.ts

@@ -202,6 +202,14 @@ declare class StaticModel {
    */
   static params<M extends typeof Model> (this: M, payload: Record<string, string | number | boolean>): InstanceType<M>
 
+  /**
+   * Add a conditional clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#when|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#conditional|Building the Query}
+   */
+  static when<M extends typeof Model, T = any> (this: M, value: T, callback: (query: Builder, value: T) => any): InstanceType<M>
+
   /**
    * Build custom endpoints.
    *
@@ -559,6 +567,14 @@ export class Model extends StaticModel {
    */
   params (payload: Record<string, string | number | boolean>): this
 
+  /**
+   * Add a conditional clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#when|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#conditional|Building the Query}
+   */
+  when<T = any>(value: T, callback: (query: Builder, value: T) => any): this
+
   /**
    * Build custom endpoints.
    *
@@ -705,3 +721,156 @@ export class Model extends StaticModel {
    */
   sync (params: Record<string, any>): Promise<any>
 }
+
+declare class Builder {
+  /**
+   * Query
+   */
+
+  /**
+   * Eager load relationships.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#include|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#including-relationships|Building the Query}
+   */
+  include (...relationships: string[]): this
+
+  /**
+   * Eager load relationships.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#include|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#including-relationships|Building the Query}
+   */
+  include (relationships: string[]): this
+
+  /**
+   * Eager load relationships.
+   *
+   * Alias for the [include()]{@link include} method.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#include|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#including-relationships|Building the Query}
+   */
+  with (...relationships: string[]): this
+
+  /**
+   * Eager load relationships.
+   *
+   * Alias for the [include()]{@link include} method.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#include|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#including-relationships|Building the Query}
+   */
+  with (relationships: string[]): this
+
+  /**
+   * Append attributes.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#append|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#appending-attributes|Building the Query}
+   */
+  append (...attributes: string[]): this
+
+  /**
+   * Append attributes.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#append|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#appending-attributes|Building the Query}
+   */
+  append (attributes: string[]): this
+
+  /**
+   * Set the columns to be selected.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#select|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#selecting-fields|Building the Query}
+   */
+  select (...columns: string[]): this
+
+  /**
+   * Set the columns to be selected.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#select|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#selecting-fields|Building the Query}
+   */
+  select (columns: string[]): this
+
+  /**
+   * Set the columns to be selected.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#select|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#selecting-fields|Building the Query}
+   */
+  select (columns: {
+    [related: string]: string[]
+  }): 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 (field: string | string[], value: 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 (field: string | string[], array: (string | number | boolean)[]): this
+
+  /**
+   * Add an "order by" clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#orderby|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#sorting|Building the Query}
+   */
+  orderBy (...columns: string[]): this
+
+  /**
+   * Add an "order by" clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#orderby|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#sorting|Building the Query}
+   */
+  orderBy (columns: string[]): this
+
+  /**
+   * Set the current page.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#page|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#paginating|Building the Query}
+   */
+  page (number: number): this
+
+  /**
+   * Set the page limit.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#limit|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#paginating|Building the Query}
+   */
+  limit (number: number): this
+
+  /**
+   * Add custom parameters to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#params|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#applying-custom-parameters|Building the Query}
+   */
+  params (payload: Record<string, string | number | boolean>): this
+
+  /**
+   * Add a conditional clause to the query.
+   *
+   * @see {@link https://robsontenorio.github.io/vue-api-query/api/query-builder-methods#when|API Reference}
+   * @see {@link https://robsontenorio.github.io/vue-api-query/building-the-query#conditional|Building the Query}
+   */
+  when<T = any>(value: T, callback: (query: this, value: T) => any): this
+
+  /**
+   * Return parsed query string.
+   */
+  query(): string
+}

src/Builder.js

@@ -173,4 +173,18 @@ export default class Builder {
 
     return this
   }
+
+  when(value, callback) {
+    if (typeof callback !== 'function') {
+      throw new Error(
+        'The CALLBACK is required and must be a function on when() method.'
+      )
+    }
+
+    if (value) {
+      callback(this, value)
+    }
+
+    return this
+  }
 }

src/Model.js

@@ -250,6 +250,12 @@ export default class Model extends StaticModel {
     return this
   }
 
+  when(value, callback) {
+    this._builder.when(value, callback)
+
+    return this
+  }
+
   /**
    * Result
    */

src/StaticModel.js

@@ -81,6 +81,13 @@ export default class StaticModel {
     return self
   }
 
+  static when(value, callback) {
+    let self = this.instance()
+    self.when(value, callback)
+
+    return self
+  }
+
   static custom(...args) {
     let self = this.instance()
     self.custom(...args)

tests/builder.test.js

@@ -276,6 +276,28 @@ describe('Query builder', () => {
     expect(errorModel).toThrow('You must pass a payload/object as param.')
   })
 
+  test('when() sets properly the builder', () => {
+    let search = ''
+    let post = Post.when(search, (query, value) => query.where('title', value))
+
+    expect(post._builder.filters).toEqual({})
+
+    search = 'foo'
+    post = Post.when(search, (query, value) => query.where('title', value))
+
+    expect(post._builder.filters).toEqual({ title: 'foo' })
+  })
+
+  test('when() throws a exception when callback is not a function', () => {
+    errorModel = () => {
+      Post.when()
+    }
+
+    expect(errorModel).toThrow(
+      'The CALLBACK is required and must be a function on when() method.'
+    )
+  })
+
   test('it resets the uri upon query generation when the query is regenerated a second time', () => {
     const post = Post.where('title', 'Cool').page(4)