prioritize 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 396834d7951d62b0cc6d2b49704e85ca61b360cd673d19173db5ef7766f26f8f
-  data.tar.gz: 16391da63996a8867e26db9336e6617f1669df344b3f91d111a63f95174f8c6d
+  metadata.gz: 84063454a547cceae27c20081b6ad0f833cd352a2393a8a1670f2eabeca59ae2
+  data.tar.gz: 5ac4d9025cd9eb0f0de80cd1e89bb011e73df2a2886cf97fde2a801ab6221f14
 SHA512:
-  metadata.gz: 857fec8198e0c39d35b529a9d5b42ab3109ca7c0f902aded72b8a5b6579e0a31802d9e1e18274c874ec02272596f866247c04fb6b8341b690280dfb938b37d57
-  data.tar.gz: 8bc036e52af40fec4c6e75aada313bdbc5ca26a997bf358bf9da558aa98a45245880ea7d6176fe77efa217b2c53bca223545a4c516f1f3e554da5626a1856c71
+  metadata.gz: d7a789c449df198afe50c8d72de196fd2ada1b82451945901b725ebb9dbb4dd8558efa60dbc4e588815575fccc307a14d2f15ff48656d1a3aefde9f6dc3227f9
+  data.tar.gz: b2dff65570402d3618231ac5dc9cd70d20d2bd759ec749600692b63f523d7b1d8d86aa51122fde3025d138993197a8a8c2db73b2c26bae51dc9f253461858ef8

data/.rubocop.yml

@@ -0,0 +1,61 @@
+# Игнорировать отсутствие магического комментария:
+# frozen_string_literal: true
+# 
+# Надо понимать что мы теряем производительность если не используем замороженные
+# строки там где это возможно, применяйте!: ` -"неизменяемая строка" `
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Надо понимать что есть качественное различие между
+# 
+# module Foo
+#   class Bar
+#   end
+# end
+# 
+# и
+# 
+# class Foo::Bar
+# end
+# 
+# Если где то в модуль вынесен код:
+# 
+# module Foo
+#   X = 42
+# end
+# 
+# то следует инициализировать модуль До класса-потомка, иначе ошибка. Как выход,
+# рубокоп предлагает везде использовать первый синтаксис, а это некрасиво)
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Корячить пустые методы с точка-запятой, нет уж извините!
+Style/EmptyMethod:
+  Enabled: false
+
+# Не даёт сравнимать с нуль (... == 0), заставляет переписывать на `.zero?`, как-то вообще не согласен!
+Style/NumericPredicate:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/ClassLength:
+  Max: 300
+
+# fail обычно бросает исключение, raise пребрасывает после отлова при необходимости.
+Style/SignalException:
+  Enabled: false
+
+# Что может быть более привычным чем простой if
+Style/NegatedIf:
+  Enabled: false
+
+# Assignment - присвоения, в том числе +=...
+# Branch - явное прямое ветвление программы (вызов методов).
+# Condition - логические выражения
+# AbcSize = Math.sqrt(A * A + B * B + C * C)
+Metrics/AbcSize:
+  # Enabled: false
+  Max: 30
+  CountRepeatedAttributes: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    prioritize (0.1.0)
+    prioritize (1.0.0)
 
 GEM
   remote: https://rubygems.org/

data/README-ru.md

@@ -0,0 +1,175 @@
+# Prioritize
+
+Позволяет сортировать как простые так и вложенные списки (например списки на основе гема closure_tree).
+
+__Выбрать язык README.md__
+
+-   en [English](README.md)
+-   ru [Русский](README-ru.md)
+
+__Важно!__ Работает только с PostgreSQL бд. Обновление данных происходит за 1
+  запрос, Пока что нет "ActiveRecord" алгоритма, на подобии: выбрать данные ->
+  перебрать-преобразовать -> сохранить. Только SQL, только хардкор.
+
+_Prioritize_ добавляет следующие возможности:
+
+1.   Добавляет в класс и экземпляр класса метод
+`.priority_after(prev_id, moved_id)`, который обновит значения колонки
+`my_column` (указанной в настройках) так, чтобы при
+`Section.order(my_column: :asc)` элемент `moved` следавал за `prev`.
+
+2.   Если при сохранении экземпляра модели в дополнительном поле `priority_prev`
+указать идентификатор предыдущего элемента или строку '^' (при перемещении в
+начало), тогда сработает поведение и значения колонки `my_column` обновятся в
+соответствии с перемещением.
+
+
+
+
+## Установка
+
+Добавьте эту строку в Gemfile вашего приложения:
+
+```ruby
+gem 'prioritize', '~> 1.0'
+```
+
+Затем выполните:
+
+```sh    
+bundle install
+```
+
+Или установить его самостоятельно как:
+
+```sh    
+gem install prioritize
+```
+
+
+
+
+## Использование
+
+Выполните подобную миграцию для вашей модели, если это необходимо:
+
+```rb
+add_column :sections, "order", :integer , null: false, default: 0
+add_index :sections, "order"
+```
+
+Добавте настроечный метод в код класса:
+
+```rb
+class Section < ApplicationRecord
+  prioritize_column(:order)
+end
+```
+
+Настройка окончена, наблюдаем результат в консоли:
+
+```sh
+# Создадим несколько экземпляров
+Section.create
+=> #<Section... id: 1, order: 0...>
+Section.create
+=> #<Section... id: 2, order: 0...>
+
+# Выведем идентификаторы с необходимым порядком.
+Section.order(order: :asc).pluck(:id)
+=> [1, 2]
+
+# Приоритет: после 2 следует 1
+Section.priority_after(2, 1)
+Section.order(order: :asc).pluck(:id)
+=> [2, 1]
+
+# Переместим элемент 1 в начало
+Section.find(1).priority_after(nil)
+Section.order(order: :asc).pluck(:id)
+=> [1, 2]
+```
+
+При перемещении элементов на фронтэнде (например с jquery-ui) нам необходимо отправить на контроллер
+PATCH запрос примерно следующего характера с дополнительным полем `priority_prev`:
+
+```js
+$.ajax({
+  url: "/sections/1.json",
+  type: "PATCH",
+  data: {
+    section: {
+      priority_prev: 2
+    }
+  }
+})
+```
+
+В контроллере необходимо разрешить параметр `priority_prev`:
+
+```rb
+  def section_params
+    params.require(:section).permit(
+      ...
+      :order,
+      :priority_prev
+    )
+  end
+```
+
+При присутствии значения в поле `priority_prev` будет срабатывать обратный вызов, в котором
+вызывается `.priority_after` метод.
+
+
+
+
+### Использование при сортировки древовидных структур
+
+Модель
+
+```rb
+class Catalog < ApplicationRecord
+  prioritize_column(:order, nested: true)
+end
+```
+
+При обновлении значений колонки :order используются только элементы с тем же
+предком что и перемещаемый элемент.
+
+
+
+
+## Разработка
+
+При желании протестировать изменения гема с вашим приложением необходимо перенастроить Gemfile:
+
+```ruby
+# Сортировка
+# gem 'prioritize', '~> 1.0'
+gem 'prioritize', path: '/home/username/path/to/cloned/prioritize'
+```
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to [rubygems.org]
+(https://rubygems.org).
+
+```sh
+bundle
+rake spec
+```
+
+## Содействие
+
+Отчеты об ошибках и запросы на включение приветствуются на GitHub https://github.com/Zlatov/prioritize.
+
+
+## Лицензия
+
+Гем доступен с открытым исходным кодом в соответствии с условиями
+[MIT License](https://opensource.org/licenses/MIT).

data/README.md

@@ -1,18 +1,38 @@
 # Prioritize
 
-Welcome to your new gem! In this directory, you'll find the files you need to be
-able to package up your Ruby library into a gem. Put your Ruby code in the file
-`lib/prioritize`. To experiment with that code, run `bin/console` for an
-interactive prompt.
+Allows you to sort both simple and nested lists (for example, lists based on the
+closure_tree gem).
+
+__Select language README.md__
+
+-   en [English](README.md)
+-   ru [Русский](README-ru.md)
+
+__Important!__ Only works with PostgreSQL databases. Updating data occurs in 1
+  request, So far there is no "ActiveRecord" algorithm, like: select data ->
+  sort-transform data -> save. Only SQL, only hardcore.
+
+_Prioritize_ adds the following features:
+
+1. Adds a method `.priority_after(prev_id, moved_id)` to the class and class
+instance, which will update the values of the `my_column` column (specified in
+the settings) so that when `Section.order(my_column: :asc)` the `moved` element
+followed the `prev`.
+
+2. If, when saving a model instance, in the additional field `priority_prev`
+specify the identifier of the previous element or the string '^' (when moving
+to the beginning), then the behavior will work and the values of the
+`my_column` column will be updated in accordance with the movement.
+
+
 
-TODO: Delete this and the text above, and describe your gem
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'prioritize'
+gem 'prioritize', '~> 1.0'
 ```
 
 And then execute:
@@ -23,9 +43,83 @@ Or install it yourself as:
 
     $ gem install prioritize
 
+
+
+
 ## Usage
 
-TODO: Write usage instructions here
+Perform a similar migration for your model if necessary:
+
+```rb
+add_column :sections, "order", :integer , null: false, default: 0
+add_index :sections, "order"
+```
+
+Add a setup method to the class code:
+
+```rb
+class Section < ApplicationRecord
+  prioritize_column(:order)
+end
+```
+
+The setup is over, we observe the result in the console:
+
+```sh
+# Let's create multiple instances
+Section.create
+=> #<Section... id: 1, order: 0...>
+Section.create
+=> #<Section... id: 2, order: 0...>
+
+# Let's derive the identifiers with the required order.
+Section.order(order: :asc).pluck(:id)
+=> [1, 2]
+
+# Priority: 2 followed by 1
+Section.priority_after(2, 1)
+Section.order(order: :asc).pluck(:id)
+=> [2, 1]
+
+# Move element 1 to the beginning
+Section.find(1).priority_after(nil)
+Section.order(order: :asc).pluck(:id)
+=> [1, 2]
+```
+
+When moving elements on the frontend (for example, with jquery-ui), we need to
+send a PATCH request to the controller of the following nature with an
+additional `priority_prev` field:
+
+```js
+$.ajax({
+  url: "/sections/1.json",
+  type: "PATCH",
+  data: {
+    section: {
+      priority_prev: 2
+    }
+  }
+})
+```
+
+In the controller, the `priority_prev` parameter must be enabled:
+
+```rb
+  def section_params
+    params.require(:section).permit(
+      ...
+      :order,
+      :priority_prev
+    )
+  end
+```
+
+If there is a value in the `priority_prev` field, a callback will be fired in
+which the `.priority_after` method is called.
+
+
+
 
 ## Development
 
@@ -46,7 +140,7 @@ rake spec
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/prioritize.
+Bug reports and pull requests are welcome on GitHub at https://github.com/Zlatov/prioritize.
 
 
 ## License

data/lib/prioritize/version.rb

@@ -1,3 +1,3 @@
 module Prioritize
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

data/lib/prioritize.rb

@@ -1,89 +1,150 @@
-require "prioritize/version"
+require 'prioritize/version'
 
+# Корневой модуль отделяющий пространство имён Классов и Модулей гема от
+# приложения.
 module Prioritize
-  class Error < StandardError; end
+  # Собственные ошибки TODO: разработать список частых ошибок при использовании
+  # гема с описанием исправления.
+  class Error < StandardError
+  end
 
-  def self.included base
+  # Можно сказать точка входа, включаем гем в базовый класс ActiveRecord::Base,
+  # после чего в любой модели унаследованной от этого класса появится метод
+  # prioritize_column(...).
+  # Метод расширяет конкретный класс дополнительными методами гема и
+  # настройками.
+  def self.included(base)
     base.extend ClassMethods
   end
 
+  # Все Модели унаследованные от ActiveRecord::Base буду обладать указанным
+  # настроечным методом класса prioritize_column(...)
   module ClassMethods
-    def prioritize_column
-      self.include PriorityAfter
+    # При вызове настроечного метода
+    def prioritize_column(column, nested: false, parent_column: :parent_id)
+      # Класс расширяется модулем PriorityAfter
+      include PriorityAfter
+
+      # fail Error.new('') if column.blank?
+
+      # Настраиваем конкретную колонку для текущей модели.
+      self.priority_column = column.to_s
+      self.priority_nested = nested
+      self.priority_parent = parent_column.to_s
     end
   end
 
+  # Модуль которым расширяем Модели использовавшие в себе метод
+  # prioritize_column(...)
   module PriorityAfter
-    def self.included base
+    def self.included(base)
       base.extend ClassMethods
+      # К экземпляру класса добавим поле, в которое необходимо записать значение
+      # если необходимо выполнить сортировку.
+      # После обновления экземпляра если в поле установлено значение - сработает
+      # поведение.
+      attr_accessor :priority_prev
+      # Навесим поведение модели.
+      base.after_update :priority_callback
     end
-    def priority_after before_id
-      self.class.priority_after before_id, self.id
+
+    # При заполннном поле priority_prev запустим запрос на обновление
+    # сортировочного поля. В данном поле должен быть записан идентификатор
+    # элемента ЗА которым должен слеовать перемещаемый элемент. Если такого
+    # элемента нет (тоесть перемещаемый элемент переносится в начало списка),
+    # тогда в поле необходимо записать строку '^'.
+    def priority_callback
+      if priority_prev.present?
+        prev_id = priority_prev == '^' ? nil : priority_prev
+        priority_after prev_id
+      end
     end
+
+    def priority_after(prev_id)
+      self.class.priority_after prev_id, id
+    end
+
+    # Методы класса после расширения модулем PriorityAfter перечислены в этом
+    # подмодуле.
     module ClassMethods
-      def priority_after before_id, moved_id
+      def priority_after(prev_id, moved_id)
         connection.exec_query(
-          <<-SQL,
-            UPDATE #{table_name} o
-            SET #{priority_column} = ordered.rn
-            FROM (
-              SELECT *, ROW_NUMBER() OVER() AS rn
-              FROM (
-                (
-                  SELECT o.*
-                  FROM #{table_name} o
-                  LEFT JOIN #{table_name} ai ON ai.id = $1
-                  WHERE
-                    (o.#{priority_column} < ai.#{priority_column} OR ai.#{priority_column} IS NULL) AND
-                    o.id <> $2
-                  ORDER BY o.#{priority_column} ASC
-                )
-                UNION ALL
-                (
-                  SELECT o.*
-                  FROM #{table_name} o
-                  WHERE o.id = $2
-                )
-                UNION ALL
-                (
-                  SELECT o.*
-                  FROM #{table_name} o
-                  LEFT JOIN #{table_name} ai ON ai.id = $1
-                  WHERE
-                    o.#{priority_column} >= ai.#{priority_column} AND
-                    o.id <> $2
-                  ORDER BY o.#{priority_column} ASC
-                )
-              ) numbered
-            ) ordered
-            WHERE  o.id = ordered.id
-          SQL
+          priority_sql,
           'priority_after',
-          [[nil,before_id], [nil,moved_id]]
+          [[nil, prev_id], [nil, moved_id]]
         )
       end
-      attr_accessor :priority_column
-      def priority_column
-        @priority_column.to_s
+
+      def priority_sql
+        sql = <<-SQL
+          UPDATE #{table_name} o
+          SET "#{priority_column}" = ordered.rn
+          FROM (
+            SELECT *, ROW_NUMBER() OVER() AS rn
+            FROM (
+              -- Выбрать записи от начала и до предыдущего (включая его),
+              -- конечно исключая перемещаемую запись.
+              (
+                SELECT o.*
+                FROM #{table_name} o
+                LEFT JOIN #{table_name} prev ON prev.id IS NOT DISTINCT FROM $1
+                LEFT JOIN #{table_name} moved ON moved.id IS NOT DISTINCT FROM $2
+                WHERE
+                  o."#{priority_column}" <= prev."#{priority_column}"
+                  AND o.id <> $2
+                  nested_condition
+                ORDER BY o."#{priority_column}" ASC
+              )
+              UNION ALL
+              -- Выбрать перемещаемую запись.
+              (
+                SELECT o.*
+                FROM #{table_name} o
+                WHERE o.id = $2
+              )
+              UNION ALL
+              -- Выбрать от предыдущего (не включая его) и до конца, так же
+              -- исключая перемещаемую запись.
+              (
+                SELECT o.*
+                FROM #{table_name} o
+                LEFT JOIN #{table_name} prev ON prev.id IS NOT DISTINCT FROM $1
+                LEFT JOIN #{table_name} moved ON moved.id IS NOT DISTINCT FROM $2
+                WHERE
+                  (o."#{priority_column}" > prev."#{priority_column}" OR prev."#{priority_column}" IS NULL)
+                  AND o.id <> $2
+                  nested_condition
+                ORDER BY o."#{priority_column}" ASC
+              )
+            ) numbered
+          ) ordered
+          WHERE  o.id = ordered.id
+        SQL
+        nested_condition = priority_nested ?
+          %Q(AND o."#{priority_parent}" IS NOT DISTINCT FROM moved."#{priority_parent}") :
+          ''
+        sql.gsub! 'nested_condition', nested_condition
+        sql
       end
-      def self.extended base
+
+      # def priority_column
+      #   @priority_column.to_s
+      # end
+
+      # def priority_column=(value)
+      #   @priority_column = value
+      # end
+
+      attr_accessor :priority_column, :priority_nested, :priority_parent
+
+      def self.extended(base)
         base.class_eval do
-          @priority_column = :priority
+          # @priority_column = :priority
         end
       end
     end
   end
 end
 
-ActiveRecord::Base.send(:include, Prioritize)
-
-
-# byebug
-
-# Кто после кого
-# PostSection.priority_after 1, 2
-# post_section.priority_after 2
-# 
-# 
-# self.implicit_order_column = "updated_at"
-# 
+# ActiveRecord::Base.send(:include, Prioritize)
+ActiveRecord::Base.include Prioritize

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prioritize
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Zlatov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-25 00:00:00.000000000 Z
+date: 2022-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -68,11 +68,13 @@ files:
 - ".byebug_history"
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
+- README-ru.md
 - README.md
 - Rakefile
 - bin/console