Source: client/filtering-request.js

  1. /*
  2.  * Copyright 2023, TeamDev. All rights reserved.
  3.  *
  4.  * Licensed under the Apache License, Version 2.0 (the "License");
  5.  * you may not use this file except in compliance with the License.
  6.  * You may obtain a copy of the License at
  7.  *
  8.  * http://www.apache.org/licenses/LICENSE-2.0
  9.  *
  10.  * Redistribution and use in source and/or binary forms, with or without
  11.  * modification, must retain the above copyright notice and the following
  12.  * disclaimer.
  13.  *
  14.  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  15.  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  16.  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  17.  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  18.  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  19.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  20.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21.  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22.  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23.  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  24.  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25.  */
  27. import {ClientRequest} from "./client-request";
  29. /**
  30.  * An abstract base for client requests that filter messages by certain criteria.
  31.  *
  32.  * @abstract
  33.  *
  34.  * @template <B> the type of the builder wrapped by this request
  35.  * @template <T> the type of the messages that store the request data
  36.  */
  37. export class FilteringRequest extends ClientRequest {
  39.   /**
  40.    * @param {!Class<Message>} targetType the target type of the request
  41.    * @param {!Client} client the client which initiated the request
  42.    * @param {!ActorRequestFactory} actorRequestFactory the request factory
  43.    *
  44.    * @protected
  45.    */
  46.   constructor(targetType, client, actorRequestFactory) {
  47.     super(client, actorRequestFactory);
  48.     this.targetType = targetType;
  49.   }
  51.   /**
  52.    * Adds filtering by IDs to the built request.
  53.    *
  54.    * @param ids {!Message|Number|String|Message[]|Number[]|String[]}
  55.    *        the IDs of interest
  56.    * @return {this} self for method chaining
  57.    */
  58.   byId(ids) {
  59.     ids = FilteringRequest._ensureArray(ids);
  60.     this._builder().byIds(ids);
  61.     return this._self();
  62.   }
  64.   /**
  65.    * Adds filtering by predicates to the built request.
  66.    *
  67.    * Filters specified in a list are considered to be joined using `AND` operator.
  68.    *
  69.    * @param {!Filter|CompositeFilter|Filter[]|CompositeFilter[]} predicates the filters
  70.    * @return {this} self for method chaining
  71.    */
  72.   where(predicates) {
  73.     predicates = FilteringRequest._ensureArray(predicates);
  74.     this._builder().where(predicates);
  75.     return this._self();
  76.   }
  78.   /**
  79.    * Applies a field mask to the request results.
  80.    *
  81.    * The names of the fields must be formatted according to the `google.protobuf.FieldMask`
  82.    * specification.
  83.    *
  84.    * @param {!String|String[]} fieldPaths the fields to include in the mask
  85.    * @return {this} self for method chaining
  86.    */
  87.   withMask(fieldPaths) {
  88.     fieldPaths = FilteringRequest._ensureArray(fieldPaths);
  89.     this._builder().withMask(fieldPaths);
  90.     return this._self();
  91.   }
  93.   /**
  94.    * Returns the builder for messages that store request data.
  95.    *
  96.    * @return {AbstractTargetBuilder<Message>} the builder instance
  97.    *
  98.    * @protected
  99.    */
  100.   _builder() {
  101.     if (!this._builderInstance) {
  102.       const newBuilderFn = this._newBuilderFn();
  103.       this._builderInstance = newBuilderFn(this._requestFactory);
  104.     }
  105.     return this._builderInstance;
  106.   }
  108.   /**
  109.    * @callback _NewBuilderFn
  110.    *
  111.    * @param {ActorRequestFactory}
  112.    * @return {AbstractTargetBuilder}
  113.    */
  115.   /**
  116.    * Returns the function with which the {@link _builderInstance} can be created.
  117.    *
  118.    * @abstract
  119.    * @return {_NewBuilderFn}
  120.    *
  121.    * @protected
  122.    */
  123.   _newBuilderFn() {
  124.     throw new Error('Not implemented in abstract base.');
  125.   }
  127.   /**
  128.    * @abstract
  129.    * @return {this}
  130.    *
  131.    * @protected
  132.    */
  133.   _self() {
  134.     throw new Error('Not implemented in abstract base.');
  135.   }
  137.   /**
  138.    * Wraps the passed argument into array if it's not an array already.
  139.    *
  140.    * The `null` values are converted into an empty array.
  141.    *
  142.    * @return {Array} the passed argument as an array
  143.    *
  144.    * @private
  145.    */
  146.   static _ensureArray(values) {
  147.     if (!values) {
  148.       return [];
  149.     }
  150.     if (!(values instanceof Array)) {
  151.       return [values]
  152.     }
  153.     return values;
  154.   }
  155. }