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)