grape-listing 1.4.9 → 2.0.0.pre.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7592347db2557ed4440d1a1f3aba6c5f689b3bafd51283a0700415fc19ffac63
-  data.tar.gz: 4356d99acc0afe7dd2b7aba09251eb353a972c057bdcbfd587ce60ad407633ac
+  metadata.gz: 9d7ddb2edcb994044872c61a3c15c2ae58394f620b19d4486b833ae7f5f57e7d
+  data.tar.gz: 4bb801340d2f4f73af813e50008f002518ff3826bc67a30b81c9a46a4690b1c2
 SHA512:
-  metadata.gz: 108cb395525e600c10922475215f8ef63d6ec195ac6da6c444bace446010e2abf0429c8b363eee269f8d5ee066ac89234efb5f24a2e0e3a8e9de534b6d2368d1
-  data.tar.gz: db57306ef8b287b44a57414d84479a34410a0063714b690b8e58c5bbfb5e6910d4d18f448d7796b3aaf509b876e85bcf0af251fcb9cf661d009c7ce702c3a476
+  metadata.gz: 1953a65f504b4911a82ae5f3520ea3100dd4b3c1aff9e28e17eecdc03bf6d26e34a0e505a5c70499ffd0e4d246348ea5cedb432176252e95e36016072ba2b639
+  data.tar.gz: dc1de49e752f69467e502c34ef2531f9f583115c2563f675cca0f995202bd2f42945ad1a4aa9443b646f4e5c94b14ceb05263397b7013fc8a40c3e7766ff6300

data/README.md

@@ -43,9 +43,9 @@ end
 
 `fields: %i[...]` - список полей, которые должны присутствовать в списке записей (передается вместо `entity`)
 
-`search: %w[...]` - список полей, по которым должна осуществляться фильтрация (поиск)
+`custom_search: %w[...]` - список параметров, по которым должна осуществляться специальная фильтрация с применением индивидуальных Rails-скоупов
 
-`sortable: %w[...]` - список полей, по которым может осуществляться сортировка
+`custom_sort: %w[...]` - список параметров, по которым может осуществляться специальная сортировка с применением индивидуальных Rails-скоупов
 
 `paginate: false` - отдавать результат без пагинации, сразу всей коллекцией (по умолчанию - с пагинацией)
 
@@ -53,26 +53,187 @@ end
 
 Некоторые функции, такие, как поиск (фильтрация), сортировка и формирование эл. таблиц осуществляется путем обработки параметров HTTP запроса.
 
-### Поиск
-
-Для возможности поиска необходимо передать названия полей, по которым может осуществляться поиск, в виде массива в опции `search`.
-
-Для осуществления фильтрации необходимо передать параметры в запросе в виде `?field=value`. Для поиска по нескольким полям, параметры должны быть перечислены через `&`, например: `?field_1=value&field_2=value`.
-
-В общем случае, названия полей соответствуют названиями параметров (например поле `name` и параметр `name`).
-
-Пример использования с осуществлением поиска по полю `name` с полным совпадением:
-
+### Фильтрация
+
+Для фильтрации требуется передать параметры в соответствующем формате.
+
+<table>
+  <thead>
+    <tr>
+      <th colspan=3>Строки</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Заполнено</td>
+      <td>param.is.present</td>
+    </tr>
+    <tr>
+      <td>Не заполнено</td>
+      <td>param.not.present</td>
+    </tr>
+    <tr>
+      <td>Содержит</td>
+      <td>param.is.contain</td>
+    </tr>
+    <tr>
+      <td>Не содержит</td>
+      <td>param.not.contain</td>
+    </tr>
+    <tr>
+      <td>Равно</td>
+      <td>param.is.equal</td>
+    </tr>
+    <tr>
+      <td>Не равно</td>
+      <td>param.not.equal</td>
+    </tr>
+    <tr>
+      <td>Начинается с</td>
+      <td>param.is.start_with</td>
+    </tr>
+    <tr>
+      <td>Заканчивается на</td>
+      <td>param.is.end_with</td>
+    </tr>
+  </tbody>
+  <thead>
+    <tr>
+      <th colspan=3>Числа</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Заполнено</td>
+      <td>param.is.present</td>
+    </tr>
+    <tr>
+      <td>Не заполнено</td>
+      <td>param.not.present</td>
+    </tr>
+    <tr>
+      <td>Равно</td>
+      <td>param.is.equal</td>
+    </tr>
+    <tr>
+      <td>Не равно</td>
+      <td>param.not.equal</td>
+    </tr>
+    <tr>
+      <td>Больше</td>
+      <td>param.is.gt</td>
+    </tr>
+    <tr>
+      <td>Больше или равно</td>
+      <td>param.is.gte</td>
+    </tr>
+    <tr>
+      <td>Меньше</td>
+      <td>param.is.lt</td>
+    </tr>
+    <tr>
+      <td>Меньше или равно</td>
+      <td>param.is.lte</td>
+    </tr>
+    <tr>
+      <td>В диапазоне</td>
+      <td>param.is.range=[]</td>
+    </tr>
+    <tr>
+      <td>Вне диапазона</td>
+      <td>param.not.range=[]</td>
+    </tr>
+    <tr>
+      <td>В перечне</td>
+      <td>param.is.in=[]</td>
+    </tr>
+    <tr>
+      <td>Вне перечня</td>
+      <td>param.not.in=[]</td>
+    </tr>
+  </tbody>
+  <thead>
+    <tr>
+      <th colspan=3>Даты</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Заполнено</td>
+      <td>param.is.present</td>
+    </tr>
+    <tr>
+      <td>Не заполнено</td>
+      <td>param.not.present</td>
+    </tr>
+    <tr>
+      <td>Равно</td>
+      <td>param.is.equal</td>
+    </tr>
+    <tr>
+      <td>Не равно</td>
+      <td>param.not.equal</td>
+    </tr>
+    <tr>
+      <td>Больше</td>
+      <td>param.is.gt</td>
+    </tr>
+    <tr>
+      <td>Больше или равно</td>
+      <td>param.is.gte</td>
+    </tr>
+    <tr>
+      <td>Меньше</td>
+      <td>param.is.lt</td>
+    </tr>
+    <tr>
+      <td>Меньше или равно</td>
+      <td>param.is.lte</td>
+    </tr>
+    <tr>
+      <td>В диапазоне</td>
+      <td>param.is.range=[]</td>
+    </tr>
+    <tr>
+      <td>Вне диапазона</td>
+      <td>param.not.range=[]</td>
+    </tr>
+    <tr>
+      <td>В перечне</td>
+      <td>param.is.in=[]</td>
+    </tr>
+    <tr>
+      <td>Вне перечня</td>
+      <td>param.not.in=[]</td>
+    </tr>
+  </tbody>
+  <thead>
+    <tr>
+      <th colspan=3>Флаги</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Равно</td>
+      <td>param.is.equal</td>
+    </tr>
+    <tr>
+      <td>Не равно</td>
+      <td>param.not.equal</td>
+    </tr>
+  </tbody>
+</table>
+
+Для фильтрации по полям, отсутствующим в таблице, либо для применения специальной фильтрации, не предусмотренной условиями, описанными выше, требуется передать опцию `custom_search` со списком параметров и соответствующим им скоупам Rails:
 ```ruby
 get 'users' do
   listing model: User,
           entity: UserEntity,
-          search: %w[name]
+          custom_search: %w[
+            name|for_name
+          ]
 end
 ```
-```
-GET http://localhost:3000/api/users?name=Ivan
-```
 
 ### Сортировка
 

data/lib/grape/dsl.rb

@@ -4,13 +4,13 @@ module Grape
   module DSL
     module InsideRoute
 
-      def listing(model:, entity: nil, fields: nil, scopes: nil, search: nil, sortable: nil, paginate: true, cache: nil, preload: nil)
+      def listing(model:, entity: nil, fields: nil, scopes: nil, custom_search: nil, custom_sort: nil, paginate: true, cache: nil, preload: nil)
         # параметры запроса API
         request_method = request.env['REQUEST_METHOD']
         request_uri = request.env['REQUEST_URI']
 
         # опции для сервиса
-        opts = listing_opts(model, entity, fields, scopes, search, sortable, cache, request_method, request_uri, preload)
+        opts = listing_opts(model, entity, fields, scopes, custom_search, custom_sort, cache, request_method, request_uri, preload)
 
         if params[:spreadsheet]
           listing_spreadsheet(**opts)
@@ -23,7 +23,7 @@ module Grape
 
       private
 
-      def listing_opts(model, entity, fields, scopes, search, sortable, cache, request_method, request_uri, preload)
+      def listing_opts(model, entity, fields, scopes, custom_search, custom_sort, cache, request_method, request_uri, preload)
         # стандартные опции
         opts = {
           model:,
@@ -31,8 +31,8 @@ module Grape
           entity:,
           fields:,
           scopes:,
-          search:,
-          sortable:,
+          custom_search:,
+          custom_sort:,
           params:,
           current_user:,
           cache:,

data/lib/grape_listing/version.rb

@@ -1,3 +1,3 @@
 module GrapeListing
-  VERSION = '1.4.9'.freeze
+  VERSION = '2.0.0-beta.2'.freeze
 end

data/lib/listing_service/args_handling.rb

@@ -6,6 +6,7 @@ module GrapeListing
     def handle_args(**args)
       # обрабатываемая модель
       @model = args[:model]
+      @model_cols = @model.columns_hash
 
       # список связей, необходимых для подгрузки eager load
       @preload = args[:preload] || []
@@ -19,7 +20,17 @@ module GrapeListing
       @current_user = args[:current_user]
 
       # поля, по которым возможен поиск
-      @search_fields = args[:search]
+      @search_params = @params.except('offset', 'limit', 'sort_by', 'sort_order')
+
+      # настройки кастомного поиска
+      if args[:custom_search]
+        @custom_search = args[:custom_search].map { |i| i.split('|') }.to_h
+      end
+
+      # настройки кастомной сортировки
+      if args[:custom_sort]
+        @custom_sort = args[:custom_sort].map { |i| i.split('|') }.to_h
+      end
 
       # сериализация - через Grape Entity или список полей
       @grape_entity = args[:entity]
@@ -40,9 +51,6 @@ module GrapeListing
       # требуемый список полей для коллекции
       @only_columns = args[:only_columns]
 
-      # сортировка
-      @sortable = args[:sortable]
-
       # временная директория (для генерации файлов)
       @tempdir = args[:tempdir]
 

data/lib/listing_service/pagination.rb

@@ -10,8 +10,8 @@ module GrapeListing
 
       # результат с пагинацией
       {
-        sort_by: @params['sort_by'] || 'id',
-        sort_order: @sort_order || 'desc',
+        sort_by: @sort_by,
+        sort_order: @sort_order,
         count: @objects_count,
         objects: @objects
       }

data/lib/listing_service/search.rb

@@ -1,90 +1,315 @@
 module GrapeListing
   module Search
 
+    # условия
+    IS  = 'is'.freeze
+    NOT = 'not'.freeze
+
+    # операторы
+    PRESENT    = 'present'.freeze
+    CONTAIN    = 'contain'.freeze
+    EQUAL      = 'equal'.freeze
+    START_WITH = 'start_with'.freeze
+    END_WITH   = 'end_with'.freeze
+    GT         = 'gt'.freeze
+    GTE        = 'gte'.freeze
+    LT         = 'lt'.freeze
+    LTE        = 'lte'.freeze
+    RANGE      = 'range'.freeze
+    IN         = 'in'.freeze
+
     private
 
     def search
-      @search_fields&.each do |field|
+      @search_params&.each do |param, value|
         # коллекция записей для дальнейшей фильтрации
         list = @objects || @model.preload(@preload).merge(@scopes)
 
-        # оператор и значение для поиска
-        operator, value = search_operands(field)
-
-        # пропускаем, если параметр для поиска не передан
-        next if value.nil? || value == '' || value == 'null'
+        # обработка параметра
+        column, condition, operator = param.split('.')
+        next unless [column, condition, operator].all?
 
-        # кастомный поиск
-        if operator.include?('custom') && value.present?
-          # название скоупа из модели, который нужно применить
-          scope_name = operator.split('.')[1]
-          # применение скоупа
-          @objects = list.send(scope_name, value).distinct
+        # применение кастомного скоупа (при наличии)
+        custom_scope = @custom_search[column]
+        if custom_scope
+          @objects = list.send(custom_scope, value)
           next
         end
 
-        # форматирование кавычек
-        if operator != 'IN'
-          value = quotations_formatting(value)
-        end
+        # формирование запроса для фильтрации
+        type = @model_cols[column].type
+        subject = "#{@model.table_name}.#{column}"
 
-        if field.include?('.')
-          # нужно приджойнить таблицу
-          join_assoc, field = field.split('.')
-          table = join_assoc.tableize
-          list = list.joins(join_assoc.to_sym)
-        else
-          table = @model.table_name
-          field = field.split('|')[0]
+        clause = case type
+        when :string, :text
+          string_clause(subject, condition, operator, value)
+        when :integer, :float
+          number_clause(subject, condition, operator, value)
+        when :date, :datetime
+          date_clause(subject, condition, operator, value)
+        when :boolean
+          boolean_clause(subject, condition, operator, value)
         end
 
-        query = where_query(table, field, operator, value)
-        @objects = list.where(query)
+         # применение запроса для фильтрации
+        @objects = list.where(clause)
+      end
+    end
+
+    def string_clause(subject, condition, operator, value)
+      case operator
+      when PRESENT
+        string_present(subject, condition)
+      when CONTAIN
+        string_contain(subject, condition, value)
+      when EQUAL
+        string_equal(subject, condition, value)
+      when START_WITH
+        string_start(subject, condition, value)
+      when END_WITH
+        string_end(subject, condition, value)
+      end
+    end
+
+    def number_clause(subject, condition, operator, value)
+      case operator
+      when PRESENT
+        number_present(subject, condition)
+      when EQUAL
+        number_equal(subject, condition, value)
+      when GT
+        number_gt(subject, condition, value)
+      when GTE
+        number_gte(subject, condition, value)
+      when LT
+        number_lt(subject, condition, value)
+      when LTE
+        number_lte(subject, condition, value)
+      when RANGE
+        number_range(subject, condition, value)
+      when IN
+        number_in(subject, condition, value)
+      end
+    end
+
+    def date_clause(subject, condition, operator, value)
+      case operator
+      when PRESENT
+        date_present(subject, condition)
+      when EQUAL
+        date_equal(subject, condition, value)
+      when GT
+        date_gt(subject, condition, value)
+      when GTE
+        date_gte(subject, condition, value)
+      when LT
+        date_lt(subject, condition, value)
+      when LTE
+        date_lte(subject, condition, value)
+      when RANGE
+        date_range(subject, condition, value)
+      when IN
+        date_in(subject, condition, value)
+      end
+    end
+
+    def boolean_clause(subject, condition, operator, value)
+      case operator
+      when EQUAL
+        boolean_equal(subject, condition, value)
+      end
+    end
+
+    def string_present(subject, condition)
+      case condition
+      when IS
+        "#{subject} IS NOT NULL AND #{subject} != ''"
+      when NOT
+        "#{subject} IS NULL OR #{subject} = ''"
+      end
+    end
+
+    def string_contain(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} ILIKE %#{value}%"
+      when NOT
+        "#{subject} NOT ILIKE %#{value}%"
+      end
+    end
+
+    def string_equal(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} = '#{value}'"
+      when NOT
+        "#{subject} != '#{value}'"
+      end
+    end
+
+    def string_start(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} ILIKE #{value}%"
+      when NOT
+        "#{subject} NOT ILIKE #{value}%"
+      end
+    end
+
+    def string_end(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} ILIKE %#{value}"
+      when NOT
+        "#{subject} NOT ILIKE %#{value}"
+      end
+    end
+
+    def number_present(subject, condition)
+      case condition
+      when IS
+        "#{subject} IS NOT NULL"
+      when NOT
+        "#{subject} IS NULL"
+      end
+    end
+
+    def number_equal(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} = #{value}"
+      when NOT
+        "#{subject} != #{value}"
       end
     end
 
-    def search_operands(field)
-      value = default_param_value(field)
+    def number_gt(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} > #{value}"
+      end
+    end
 
-      # WHERE query operator
-      operator = field.split('|').size > 1 ? field.split('|').last : '='
+    def number_gte(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} >= #{value}"
+      end
+    end
 
-      # условие для поиска ILIKE
-      value = "%#{value}%" if operator == 'ilike' && value.present?
+    def number_lt(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} < #{value}"
+      end
+    end
 
-      # проверка мульти-поиска по параметру с массивом
-      if value.is_a?(Array) && operator.exclude?('custom')
-        operator = 'IN'
-        value = "(#{value.map { |i| "'#{i}'" }.join(', ')})"
+    def number_lte(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} <= #{value}"
       end
+    end
 
-      # проверка диапазона (MIN/MAX)
-      if %w[min max].include?(operator)
-        range_field = field.split('.').last.split(':')[0].try { |i| i.split('|')[0] }
-        value = @params["#{range_field}_#{operator}"]
-        operator = operator == 'min' ? '>=' : '<='
+    def number_range(subject, condition, value)
+      min, max = value
+
+      case condition
+      when IS
+        "#{subject} >= #{min} AND #{subject} <= #{max}"
+      when NOT
+        "#{subject} < #{min} OR #{subject} > #{max}"
       end
+    end
+
+    def number_in(subject, condition, value)
+      opts = value.join(',')
 
-      [operator, value]
+      case condition
+      when IS
+        "#{subject} IN (#{opts})"
+      when NOT
+        "#{subject} NOT IN (#{opts})"
+      end
     end
 
-    def default_param_value(field)
-      # название ключа-поля без оператора (напр. ilike)
-      key = field.split('|')[0]
+    def date_present(subject, condition)
+      case condition
+      when IS
+        "#{subject} IS NOT NULL"
+      when NOT
+        "#{subject} IS NULL"
+      end
+    end
 
-      @params[key]
+    def date_equal(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} = '#{value}'"
+      when NOT
+        "#{subject} != '#{value}'"
+      end
     end
 
-    def where_query(table, field, operator, value)
-      "#{table}.#{field} #{operator} #{value}"
+    def date_gt(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} > '#{value}'"
+      end
     end
 
-    def quotations_formatting(string)
-      # удаление одинарных кавычек (напр. внутри строки)
-      value = string.to_s.gsub("'", '')
+    def date_gte(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} >= '#{value}'"
+      end
+    end
 
-      # добавление одинарных кавычек вокруг строки
-      "'#{value}'"
+    def date_lt(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} < '#{value}'"
+      end
+    end
+
+    def date_lte(subject, condition, value)
+      case condition
+      when IS
+        "#{subject} <= '#{value}'"
+      end
+    end
+
+    def date_range(subject, condition, value)
+      min, max = value
+
+      case condition
+      when IS
+        "#{subject} >= '#{min}' AND #{subject} <= '#{max}'"
+      when NOT
+        "#{subject} < '#{min}' OR #{subject} > '#{max}'"
+      end
+    end
+
+    def date_in(subject, condition, value)
+      opts = value.join(',')
+
+      case condition
+      when IS
+        "#{subject} IN (#{opts})"
+      when NOT
+        "#{subject} NOT IN (#{opts})"
+      end
+    end
+
+    def boolean_equal(subject, condition, value)
+      flag = value.to_s == 'true' ? 't' : 'f'
+
+      case condition
+      when IS
+        "#{subject} = #{flag}"
+      when NOT
+        "#{subject} != #{flag}"
+      end
     end
 
   end

data/lib/listing_service/sorting.rb

@@ -4,28 +4,18 @@ module GrapeListing
     private
 
     def sort_proc
-      # проверка необходимости нестандартной сортировки
-      if !@sortable.is_a?(Array) || @sortable.empty? || custom_sorting_field.blank?
-        return proc { order('id desc') }
-      end
-
+      @sort_by = @params['sort_by'] || 'id'
       @sort_order = @params['sort_order'] || 'desc'
-      sorting_scope = custom_sorting_field.split('|')[1]
+      custom_scope = @custom_sort[@sort_by]
 
-      if sorting_scope
-        direction = @sort_order
-        proc { send(sorting_scope, direction) }
+      if custom_scope
+        proc { send(custom_scope, @sort_order) }
       else
         nulls_order = @sort_order.to_s.downcase == 'desc' ? 'LAST' : 'FIRST'
-        query = Arel.sql("#{custom_sorting_field} #{@sort_order} NULLS #{nulls_order}")
+        query = Arel.sql("#{@sort_by} #{@sort_order} NULLS #{nulls_order}")
         proc { order(query) }
       end
     end
 
-    # поиск поля для индивидуальной сортировки среди допустимых
-    def custom_sorting_field
-      @custom_sorting_field ||= @sortable.select { |i| i.split('|')[0] == @params['sort_by'] }.first
-    end
-
   end
 end

data/lib/listing_service/spreadsheet.rb

@@ -97,7 +97,6 @@ module GrapeListing
     def spreadsheet_titles
       values = []
       entity_doc = @grape_entity.documentation
-      model_cols = @model.columns_hash
 
       spreadsheet_cols.each do |column|
         # исключение: колонка с ИД
@@ -107,7 +106,7 @@ module GrapeListing
         end
 
         # поиск описания среди комментариев к таблице БД
-        db_col = model_cols[column.to_s]
+        db_col = @model_cols[column.to_s]
         if db_col&.comment&.present?
           values << db_col.comment
           next

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grape-listing
 version: !ruby/object:Gem::Version
-  version: 1.4.9
+  version: 2.0.0.pre.beta.2
 platform: ruby
 authors:
 - Павел Бабин
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-04-28 00:00:00.000000000 Z
+date: 2025-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -100,12 +100,12 @@ files:
 - lib/listing_service/serialization.rb
 - lib/listing_service/sorting.rb
 - lib/listing_service/spreadsheet.rb
-homepage:
+homepage: 
 licenses:
 - Copyright
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -116,12 +116,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.0.6
-signing_key:
+rubygems_version: 3.3.3
+signing_key: 
 specification_version: 4
 summary: Формирование списков записей для API на базе Grape
 test_files: []