grape-listing 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f7ada8749162c0e09f2a0dad2712dbd31e3296d302266449e4c5edd7cea9b1d6
+  data.tar.gz: 51afe0e601ad9e8f5d22d4c0d07031078cc9b6d1161cfd092a15dfb18265cd8b
+SHA512:
+  metadata.gz: ff72f5cf03c2394347d8745e8c68429d85f793ce64f29eddc7d808f6b75fb81c4a4cb6d12bf5af8f707a999e2fe90d5269b4b310ebd6794819d65d0bfbeb7fe0
+  data.tar.gz: 98e6cec6b17f9efa1fcbd1890a3d376539d2662240e6dfddb107ae729a96b1f8e2aea569f2adb183fb52639945159a3dcc7b0b24ce7e5ada098d055c2d1b1066

data/README.md

@@ -0,0 +1,83 @@
+# Grape Listing
+[![Gem Version](https://badge.fury.io/rb/paginated.svg)](https://badge.fury.io/rb/paginated)
+
+Гем для пагинации и фильтрации записей с возможностью формирования электронных таблиц (XLSX) на базе Grape.
+
+## Установка
+
+Добавить в Gemfile
+
+```
+gem 'grape-listing'
+```
+
+И выполнить:
+
+```
+bundle
+```
+
+## Использование
+
+Использование с помощью вызова метода-хелпера `listing` и передачи в него необходимых опций.
+
+
+Например:
+
+```
+get 'users' do
+  listing model: User,
+          entity: UserEntity,
+          search: %w[email name|ilike role|custom.for_role]
+end
+
+```
+
+Опции (с примерами):
+
+`model: User` - модель, записи которой нужно обработать.
+
+`entity: UserEntity` - класс Grape Entity, который обработает каждую запись (передается вместо `fields`).
+
+`scopes: proc {...}` - блок кода для применения
+
+`fields: %i[...]` - список полей, которые должны присутствовать в списке записей (передается вместо `entity`).
+
+`search: %w[...]` - список полей, по которым должна осуществляться фильтрация (поиск).
+
+## Параметры HTTP запроса
+
+Некоторые функции, такие, как поиск (фильтрация), сортировка и формирование эл. таблиц осуществляется путем обработки параметров HTTP запроса.
+
+### Поиск
+
+Для поиска по полям необходимо передать их в запросе в виде `?field=value`. Для поиска по нескольким полям, параметры должны быть перечислены через `&`, например: `?field_1=value&field_2=value`.
+
+### Сортировка
+
+Для сортировки выдачи необходимо передать в параметрах запроса:
+
+- `sort_by` - название поля, по которому должна осуществляться сортировка.
+
+- `sort_order` направление, по которому должна осуществляться сортировка (`asc/desc`).
+
+По умолчанию сортировка осуществляется по `id` записей в направлении `DESC`.
+
+### Ограничение полей
+
+При передаче параметра `columns[]=` результаты в ответе ограничиваются переданным массив колонок.
+
+### Формирование эл. таблиц
+
+При передаче параметра `spreadsheet=true` происходит формирование эл. таблицы в виде XLSX файла с учетом всех остальных переданных параметров. Параметр `columns` при этом является обязательным.
+
+Заголовки эл. таблицы будут взяты из описаний полей таблицы БД с соответствующими названиями. Значения будут сформированы путем обработки переданного списка колонок как методов.
+
+## Конфигурация
+
+Добавьте файл конфигурации `config/initializers/grape_listing.rb` с содержимым:
+
+```
+GrapeListing.configure do |config|
+end
+```

data/lib/extensions/object.rb

@@ -0,0 +1,7 @@
+class Object
+
+  def send_chain(arr)
+    Array(arr).inject(self) { |o, a| o.send(*a) }
+  end
+
+end

data/lib/grape/dsl.rb

@@ -0,0 +1,55 @@
+module Grape
+  module DSL
+    module InsideRoute
+
+      def listing(model:, entity:, scopes: nil, search: nil)
+        opts = listing_opts(model, entity, scopes, search)
+
+        if params[:spreadsheet]
+          listing_spreadsheet(**opts)
+        else
+          GrapeListingService.paginated(**opts)
+        end
+      end
+
+      private
+
+      def listing_opts(model, entity, scopes, search)
+        # стандартные опции
+        opts = { model:, entity:, scopes:, search:, params:, current_user: }
+
+        # требуемый список полей (+стандартные) для фильтрации в Grape Entity
+        if params[:columns] && !params[:spreadsheet]
+          opts[:only_columns] = params[:columns] + %w[id deleted_at]
+        end
+
+        opts
+      end
+
+      def listing_spreadsheet(opts)
+        Dir.mktmpdir do |dir|
+          opts[:tempdir] = dir
+          file_path = GrapeListingService.spreadsheet(**opts)
+
+          spreadsheet_file_headers File.basename(file_path)
+          File.read(file_path)
+        end
+      end
+
+      def spreadsheet_file_headers(filename)
+        header['Content-Type'] =
+          case File.extname(filename)
+          when '.csv'
+            'application/csv'
+          when '.xlsx'
+            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+          end
+
+        header['Access-Control-Expose-Headers'] = 'Content-Disposition'
+        header['Content-Disposition'] = "attachment; filename=#{Addressable::URI.escape(filename)}"
+        env['api.format'] = :binary
+      end
+
+    end
+  end
+end

data/lib/grape-listing.rb

@@ -0,0 +1 @@
+require 'grape_listing'

data/lib/grape_listing/configuration.rb

@@ -0,0 +1,14 @@
+module GrapeListing
+  class Configuration
+  end
+
+  def self.configure
+    yield(config)
+    config
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+end

data/lib/grape_listing.rb

@@ -0,0 +1,7 @@
+require 'extensions/object'
+require 'grape/dsl'
+require 'grape_listing/configuration'
+require 'grape_listing_service'
+
+module GrapeListing
+end

data/lib/grape_listing_service.rb

@@ -0,0 +1,27 @@
+require 'listing_service/args_handling'
+require 'listing_service/collection'
+require 'listing_service/search'
+require 'listing_service/sorting'
+require 'listing_service/spreadsheet'
+
+class GrapeListingService
+
+  include GrapeListing::ArgsHandling
+  include GrapeListing::Collection
+  include GrapeListing::Search
+  include GrapeListing::Sorting
+  include GrapeListing::Spreadsheet
+
+  def initialize(**args)
+    handle_args(**args)
+  end
+
+  def self.paginated(**args)
+    new(**args).paginated
+  end
+
+  def self.spreadsheet(**args)
+    new(**args).spreadsheet
+  end
+
+end

data/lib/listing_service/args_handling.rb

@@ -0,0 +1,65 @@
+module GrapeListing
+  module ArgsHandling
+
+    private
+
+    def handle_args(**args)
+      # обрабатываемая Rails модель
+      @model = args[:model]
+
+      # параметры запроса и текущий пользователь
+      @params = args[:params].stringify_keys
+      @current_user = args[:current_user]
+
+      # поля, по которым возможен поиск
+      @search_fields = args[:search]
+
+      # сериализация - через Grape Entity или список полей
+      @grape_entity = args[:entity]
+      @fields = args[:fields]
+
+      # Rails scopes для применения
+      @scopes = args[:scopes] || {}
+
+      # offset / limit
+      @offset = @params['offset'].to_i
+      @limit = @params['limit'] || 20
+
+      # проверка максимального значения лимита
+      if @limit.to_i > 100
+        raise StandardError.new('Лимит слишком большой')
+      end
+
+      # требуемый список полей для коллекции
+      @only_columns = args[:only_columns]
+
+      # сортировка
+      @sort_by = @params['sort_by'] || :id
+      @sort_order = @params['sort_order'] || :desc
+
+      # подсчет кол-ва записей
+      @objects_count = records_count
+
+      # временная директория (для генерации файлов)
+      @tempdir = args[:tempdir]
+    end
+
+    def records_count
+      # получение кол-ва записей из кеша
+      cache_key = "#{@model}_records_count"
+      cached = Rails.cache.read(cache_key)
+      return cached if cached
+
+      # получение кол-ва записей из запроса к БД
+      count = @model.merge(@scopes).count(:id)
+
+      # кеширование кол-ва записей при превышении порогового значения
+      if count >= 1_000
+        Rails.cache.write(cache_key, count, expires_in: 30.minutes)
+      end
+
+      count
+    end
+
+  end
+end

data/lib/listing_service/collection.rb

@@ -0,0 +1,58 @@
+module GrapeListing
+  module Collection
+
+    def paginated
+      if @objects_count > 0
+        search
+        serialize
+      else
+        @objects = []
+      end
+
+      # результат с пагинацией
+      { count: @objects_count, objects: @objects }
+    end
+
+    private
+
+    def serialize
+      # коллекция записей ActiveRecord для применения аггрегирования
+      list = @objects || @model.unscoped.merge(@scopes)
+
+      # применение сортировки и пагинации к коллекции записей
+      @objects = list.offset(@offset).merge(sort_proc).limit(@limit)
+
+      # сериализация с помощью переданных полей или сериалайзера
+      if @fields
+        serialize_with_fields
+      elsif @grape_entity
+        serialize_with_entity
+      end
+    end
+
+    def serialize_with_fields
+      # добавление ID в список полей по умолчанию
+      @fields.push(:id)
+
+      # список массивов значений
+      @objects = @objects.map { |i| obtain_fields_values(i) }
+
+      # трансформация массивов значений в объекты (ключ-значение)
+      @objects = @objects.map { |i| @fields.zip(i).to_h }
+    end
+
+    def serialize_with_entity
+      opts = { current_user: @current_user }
+
+      # требуемый список полей (если был передан)
+      opts[:only] = @only_columns if @only_columns
+
+      @objects = @objects.map { |i| @grape_entity.represent(i, opts).as_json }
+    end
+
+    def obtain_fields_values(record)
+      @fields.map { |i| record.send(i) }
+    end
+
+  end
+end

data/lib/listing_service/search.rb

@@ -0,0 +1,99 @@
+module GrapeListing
+  module Search
+
+    private
+
+    def search
+      @search_fields&.each do |field|
+        # коллекция записей для дальнейшей фильтрации
+        list = @objects || @model.unscoped.merge(@scopes)
+
+        # оператор и значение для поиска
+        operator, value = search_operands(field)
+
+        # пропускаем, если параметр для поиска не передан
+        next if value.blank? || value == 'null'
+
+        # кастомный поиск
+        if operator.include?('custom') && value.present?
+          # название скоупа из модели, который нужно применить
+          scope_name = operator.split('.')[1]
+          # применение скоупа
+          @objects = list.send(scope_name, value)
+          @objects_count = @objects.count
+          next
+        end
+
+        # форматирование кавычек
+        if operator != 'IN' && !@model.defined_enums.key?(field)
+          value = quotations_formatting(value)
+        end
+
+        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]
+        end
+
+        query = where_query(table, field, operator, value)
+        @objects = list.where(query)
+        @objects_count = @objects.count
+      end
+    end
+
+    def search_operands(field)
+      value = default_param_value(field)
+
+      # WHERE query operator
+      operator = field.split('|').size > 1 ? field.split('|').last : '='
+
+      # условие для поиска ILIKE
+      value = "%#{value}%" if operator == 'ilike' && value.present?
+
+      # проверка мульти-поиска по параметру с массивом
+      if operator == 'multi' && !value.blank?
+        operator = 'IN'
+        value = "(#{value.join(', ')})"
+      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' ? '>=' : '<='
+      end
+
+      # check array operator
+      if operator == 'array' && value.present?
+        operator = '='
+        value = "{#{value}}"
+      end
+
+      [operator, value]
+    end
+
+    def default_param_value(field)
+      # название ключа-поля без оператора (напр. ilike)
+      key = field.split('|')[0]
+
+      @params[key]
+    end
+
+    def where_query(table, field, operator, value)
+      "#{table}.#{field} #{operator} #{value}"
+    end
+
+    def quotations_formatting(string)
+      # удаление одинарных кавычек (напр. внутри строки)
+      value = string.to_s.gsub("'", '')
+
+      # добавление одинарных кавычек вокруг строки
+      "'#{value}'"
+    end
+
+  end
+end

data/lib/listing_service/sorting.rb

@@ -0,0 +1,12 @@
+module GrapeListing
+  module Sorting
+
+    private
+
+    def sort_proc
+      query = Arel.sql("#{@sort_by} #{@sort_order} NULLS LAST")
+      proc { order(query) }
+    end
+
+  end
+end

data/lib/listing_service/spreadsheet.rb

@@ -0,0 +1,77 @@
+require 'fast_excel'
+
+module GrapeListing
+  module Spreadsheet
+
+    def spreadsheet
+      # поиск и фильтрация
+      search
+
+      # коллекция записей ActiveRecord для формирования эл. таблицы
+      records = @objects || @model.unscoped.merge(@scopes)
+
+      # ограничение записей
+      records = records.order(:id).offset(@offset).limit(@limit)
+
+      # формирования файла эл. таблицы
+      generate_spreadsheet(records)
+    end
+
+    private
+
+    def generate_spreadsheet(records)
+      filepath = "#{@tempdir}/#{Time.now.strftime('%Y%m%d_%H%M%S')}.xlsx"
+
+      # создание таблицы и ее конфигурация
+      workbook = FastExcel.open(filepath, constant_memory: true)
+      workbook.default_format.set(
+        font_size: 0,
+        font_family: 'Arial'
+      )
+
+      # стили
+      bold = workbook.bold_format
+
+      # лист
+      worksheet = workbook.add_worksheet('Основной')
+      worksheet.auto_width = true
+
+      # заголовки
+      worksheet.append_row(spreadsheet_titles, bold)
+
+      # содержимое
+      cols = spreadsheet_columns
+      records.each do |record|
+        values = cols.map { |col| record.send_chain(col) }
+        worksheet.append_row(values)
+      end
+
+      # закрытие/сохранение файла
+      workbook.close
+
+      # путь до файла для дальнейшей обработки
+      filepath
+    end
+
+    def spreadsheet_titles
+      model_cols = @model.columns.to_h { |i| [i.name, i] }
+
+      @params['columns'].map do |column|
+        db_col = model_cols[column]
+
+        db_col.comment || column
+      end
+    end
+
+    def spreadsheet_columns
+      entity_doc = @grape_entity.documentation
+
+      @params['columns'].map do |column|
+        doc = entity_doc[column.to_sym]
+
+        doc && doc[:sheet_method] ? doc[:sheet_method].split('.') : column
+      end
+    end
+
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: grape-listing
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Павел Бабин
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-03-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fast_excel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: grape
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: grape-entity
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Простая пагинация, поиск и формирование эл. таблиц для API на базе Grape
+email: babin359@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/extensions/object.rb
+- lib/grape-listing.rb
+- lib/grape/dsl.rb
+- lib/grape_listing.rb
+- lib/grape_listing/configuration.rb
+- lib/grape_listing_service.rb
+- lib/listing_service/args_handling.rb
+- lib/listing_service/collection.rb
+- lib/listing_service/search.rb
+- lib/listing_service/sorting.rb
+- lib/listing_service/spreadsheet.rb
+homepage:
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.6
+signing_key:
+specification_version: 4
+summary: Формирование списков записей для API на базе Grape
+test_files: []