paginated 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 25d6612ba23cb5271d1e3f372038e6561367ca5d89fa3b3954459bb12d745e69
+  data.tar.gz: 3a8251026ddc43e08426263df219db39fabbf8127a71059cc21a165afa2649e2
+SHA512:
+  metadata.gz: 1a16eda994f3d8ce357367ecb016a0aeacb0b45c16c10519c1be03865a382fa42b2239014b1dbc6d8453ee58db0fc9065d1a2c319f90f568e4a3b26bf5130747
+  data.tar.gz: 7007c621aa8deb8a343cf8aca640d1fcb7bc8aa4710a2ef7fb142c317b04b86b00bfb9c1009fe4df16d6490541ff24915ae422d104d44d51ed84c3274bdae9f5

data/README.md

@@ -0,0 +1,57 @@
+# Paginated
+
+Гем для пагинации и фильтрации записей.
+
+## Установка
+
+Добавить в Gemfile
+
+```
+gem 'paginated'
+```
+
+И выполнить:
+
+```
+bundle
+```
+
+## Использование
+
+Использование с помощью вызова метода `.collection` и передачи в него необходимых опций:
+```
+Paginated.new.collection()
+```
+
+Опции (с примерами):
+
+`model: 'User'` - название модели, записи которой нужно обработать.
+
+`fields: %i[...]` - список полей, которые должны присутствовать в списке записей (передается вместо `serializer`).
+
+`serializer: 'UserSerializer'` - название сериалайзера, который обработает каждую запись (передается вместо `fields`).
+
+`params:` - передаваемые параметры для фильтрации записей.
+
+`order: :name` - название поля, по которому должна осуществляться сортировка.
+
+`search: %w[...]` - список полей, по которым должна осуществляться фильтрация (поиск).
+
+Например:
+
+```
+Paginated.new.collection(
+  model: 'User',
+  fields: %i[
+    email
+    name
+  ],
+  search: %w[
+    email
+    name|ilike
+    role|custom_search.for_role
+  ],
+  params:,
+  order: :name,
+)
+```

data/lib/paginated/search.rb

@@ -0,0 +1,109 @@
+module Search
+
+  extend ActiveSupport::Concern
+
+  private
+
+  def search
+    @attrs[:search]&.each do |field|
+      # коллекция записей для дальнейшей фильтрации
+      entity = @objects || @model.unscoped.merge(@scopes)
+
+      # оператор и значение для поиска
+      operator, value = search_operands(field)
+
+      # пропускаем, если параметр для поиска не передан
+      next if value.blank? || value == 'null'
+
+      # кастомный поиск
+      if operator.include?('custom_search') && value.present?
+        # название скоупа из модели, который нужно применить
+        scope_name = operator.split('.')[1]
+        # применение скоупа
+        @objects = entity.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_association, field = field.split('.')
+        table = join_association.tableize
+        entity = entity.joins(join_association.to_sym)
+      else
+        table = @model.table_name
+        field = field.split('|')[0]
+      end
+
+      query = where_query(table, field, operator, value)
+      @objects = entity.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 : '='
+
+    # check for ILIKE operator
+    value = "%#{value}%" if operator == 'ilike' && value.present?
+
+    # check if multi-filter search enabled
+    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 { |p| p.split('|')[0] }
+      value = @params["#{range_field}_#{operator}"]
+      operator = operator == 'min' ? '>=' : '<='
+    end
+
+    # check array operator
+    if operator == 'array' && !value.blank?
+      operator = '='
+      value = "{#{value}}"
+    end
+
+    [operator, value]
+  end
+
+  def default_param_value(field)
+    key =
+      if field.include?('|')
+        # название ключа-поля без оператора (напр. ilike)
+        field.split('|')[0]
+      else
+        field
+      end
+
+    @params[key]
+  end
+
+  def where_query(table, field, operator, value)
+    if field.include?('_at')
+      # фильтрация по дате/времени
+      "EXTRACT(epoch FROM #{field}) #{operator} #{value}"
+    else
+      "#{table}.#{field} #{operator} #{value}"
+    end
+  end
+
+  def quotations_formatting(string)
+    # удаление одинарных кавычек (напр. внутри строки)
+    value = string.to_s.gsub(/'/, '')
+
+    # добавление одинарных кавычек вокруг строки
+    "'#{value}'"
+  end
+
+end

data/lib/paginated/serialization.rb

@@ -0,0 +1,79 @@
+module Serialization
+
+  extend ActiveSupport::Concern
+
+  private
+
+  def serialize
+    # коллекция записей / сущность для применения аггрегирования
+    entity = @objects || @model.unscoped.merge(@scopes)
+
+    # применение сортировки и пагинации (если необходимо) к коллекции записей
+    @objects =
+      if @paginate
+        entity.offset(@offset).merge(sort_proc).limit(@limit)
+      else
+        entity.merge(sort_proc)
+      end
+
+    # сериализация с помощью переданных полей или сериалайзера
+    if @fields
+      serialize_with_fields
+    elsif @attrs[:serializer]
+      serialize_with_serializer
+    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_serializer
+    serializer = @attrs[:serializer].constantize
+    @objects = @objects.map { |i| serializer.new(i, root: false) }
+  end
+
+  def sort_proc
+    # сортировка не задана явно, не передан параметр
+    # или значение переданного параметра не совпадает с ожидаемым
+    if @sort.blank? || @sort.map { |i| i.split('|')[0] }.exclude?(@params[:sort])
+      field = @order
+      return proc { order("#{field} DESC") }
+    end
+
+    @sort.each do |sort_option|
+      sort, field = sort_option.split('|')
+
+      # пропускаем, если поле для сортировки не совпадает с переданным параметром
+      next if @params[:sort] != sort
+
+      # если поле для сортировки совпадает с ключом переданного параметра
+      field = sort if field.blank?
+
+      sort_order = "#{@params[:sort_order]} NULLS LAST"
+
+      order_proc =
+        if field.split('.').count > 1
+          # сортировка по связанной таблице
+          relation, column = field.split('.')
+          proc { eager_load(relation).order("#{relation.tableize}.#{column} #{sort_order}") }
+        else
+          proc { order("#{field} #{sort_order}") }
+        end
+
+      return order_proc
+    end
+  end
+
+  def obtain_fields_values(object)
+    @fields.map { |f| object.send(f) }
+  end
+
+end

data/lib/paginated.rb

@@ -0,0 +1,58 @@
+require 'paginated/search'
+require 'paginated/serialization'
+
+class Paginated
+
+  include Search
+  include Serialization
+
+  def collection(**attrs)
+    @attrs = attrs
+    @fields = attrs[:fields]
+    @scopes = attrs[:scopes] || {}
+    @params = attrs[:params].stringify_keys
+    @offset = @params['offset'].to_i
+    @limit = @params['limit'] || 20
+    @order = attrs[:order] || :id
+    @sort = attrs[:sort]
+    @model = attrs[:model].constantize
+    @root = @params.key?('root') ? @params['root'] : false
+    @paginate = @params.key?('paginate') ? @params['paginate'].to_s == 'true' : true
+    @objects_count = records_count(attrs[:model])
+
+    if @objects_count > 0
+      search
+      serialize
+    else
+      @objects = []
+    end
+
+    if @root
+      # записи в корне
+      @objects
+    else
+      # результат с пагинацией
+      { count: @objects_count, objects: @objects }
+    end
+  end
+
+  private
+
+  def records_count(model_name)
+    # получение кол-ва записей из кеша
+    cache_key = "#{model_name}_records_count"
+    cached_value = Rails.cache.read(cache_key)
+    return cached_value if cached_value
+
+    # получение кол-ва записей из запроса к БД
+    db_value = @model.unscoped.merge(@scopes).count(:id)
+
+    # кеширование кол-ва записей при превышении порогового значения
+    if db_value >= 1_000
+      Rails.cache.write(cache_key, db_value, expires_in: 30.minutes)
+    end
+
+    db_value
+  end
+
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: paginated
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Павел Бабин
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-11-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Простая пагинация записей и поиск для Rails-приложений
+email: babin359@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/paginated.rb
+- lib/paginated/search.rb
+- lib/paginated/serialization.rb
+homepage:
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.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: Пагинация для Rails-приложений
+test_files: []