ranked-model 0.4.0 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 116f5fc0aeafe231cddba562c5135e868ba06604
-  data.tar.gz: c720ee45d4532e3c96fb2d829788a2c43cdd7f8f
+SHA256:
+  metadata.gz: 8dac9a4acefc5a44cfe74e77931854bb8edd031cc986f3bc0bd8232f543dc0f9
+  data.tar.gz: 9bd6120114a23ef47ae08581b860cd0cb4fa18779fb237b9b9570d94a889cc75
 SHA512:
-  metadata.gz: 00ca1355412ab2cc161edc2831bc685862f4996b33903a7bf5a65077e2a638e2f385d665db6e20bdfe50f59d93c8517cdf68c8e694a325680c4a2314e4adb677
-  data.tar.gz: 72dbeebd7402e29238fb7219c0037f04ba588dba79e06ecbabf6ee9962cee67131b0b96246945639271b7585c63ebf6edb09274c7ba779ca864a336ba576af72
+  metadata.gz: dc8d0ad9348de7596934a2eab69da78228c3351bd4d16303eae592b3893ecfedc28ff4620997977e8a88dc9d26dc27999c99e6e2abddc7ab6fe1f24aeb108527
+  data.tar.gz: 03a77db0fc8e9f59b4ffaccf24c966a54125141ab07a931046387e30cf62b7bf0577d9d983d268322dc69a7004c68c001168083d428cffff118832085afe3d21

data/.gitignore

@@ -4,3 +4,5 @@ pkg/*
 *.un~
 
 Gemfile.lock
+*.gemfile.lock
+.ruby-version

data/.rspec

@@ -1,2 +1,3 @@
 --color
+--warnings
 --format documentation

data/.travis.yml

@@ -1,82 +1,51 @@
 language: ruby
+cache: bundler
+before_install:
+  - gem update --system
+  - gem install bundler
 before_script:
   - mysql -e 'create database ranked_model_test;'
   - psql -c 'create database ranked_model_test;' -U postgres
 rvm:
-  - "1.9.2"
-  - "1.9.3"
-  - "2.0.0"
-  - "2.1.0"
-  - "jruby-19mode"
-  - "rbx"
+  - 2.4
+  - 2.5
+  - 2.6
+  - 2.7
+  - 3.0
+  - jruby-9.1.17.0
 env:
-  - "ACTIVERECORD_VERSION=4.1.0.beta1"
-  - "ACTIVERECORD_VERSION=4.1.0.beta1 DB=mysql_travis"
-  - "ACTIVERECORD_VERSION=4.1.0.beta1 DB=postgresql_travis"
-  - "ACTIVERECORD_VERSION=4.0.2"
-  - "ACTIVERECORD_VERSION=4.0.2 DB=mysql_travis"
-  - "ACTIVERECORD_VERSION=4.0.2 DB=postgresql_travis"
-  - "ACTIVERECORD_VERSION=3.2.16"
-  - "ACTIVERECORD_VERSION=3.2.16 DB=mysql_travis"
-  - "ACTIVERECORD_VERSION=3.2.16 DB=postgresql_travis"
-  - "ACTIVERECORD_VERSION=3.1.12"
-  - "ACTIVERECORD_VERSION=3.1.12 DB=mysql_travis"
-  - "ACTIVERECORD_VERSION=3.1.12 DB=postgresql_travis"
-  - "ACTIVERECORD_VERSION=master"
-  - "ACTIVERECORD_VERSION=master DB=mysql_travis"
-  - "ACTIVERECORD_VERSION=master DB=postgresql_travis"
+  - DB=sqlite
+  - DB=mysql
+  - DB=postgresql
+services:
+  - mysql
+  - postgresql
+gemfile:
+  - gemfiles/rails_4_2.gemfile
+  - gemfiles/rails_5_0.gemfile
+  - gemfiles/rails_5_1.gemfile
+  - gemfiles/rails_5_2.gemfile
+  - gemfiles/rails_6_0.gemfile
 matrix:
   exclude:
-    - env: "ACTIVERECORD_VERSION=4.1.0.beta1"
-      rvm: "1.9.2"
-    - env: "ACTIVERECORD_VERSION=4.1.0.beta1 DB=mysql_travis"
-      rvm: "1.9.2"
-    - env: "ACTIVERECORD_VERSION=4.1.0.beta1 DB=postgresql_travis"
-      rvm: "1.9.2"
-    - env: "ACTIVERECORD_VERSION=4.1.0.beta1"
-      rvm: "1.9.3"
-    - env: "ACTIVERECORD_VERSION=4.1.0.beta1 DB=mysql_travis"
-      rvm: "1.9.3"
-    - env: "ACTIVERECORD_VERSION=4.1.0.beta1 DB=postgresql_travis"
-      rvm: "1.9.3"
-    - env: "ACTIVERECORD_VERSION=4.1.0.beta1"
-      rvm: "jruby-19mode"
-    - env: "ACTIVERECORD_VERSION=4.1.0.beta1 DB=mysql_travis"
-      rvm: "jruby-19mode"
-    - env: "ACTIVERECORD_VERSION=4.1.0.beta1 DB=postgresql_travis"
-      rvm: "jruby-19mode"
-    - env: "ACTIVERECORD_VERSION=master"
-      rvm: "jruby-19mode"
-    - env: "ACTIVERECORD_VERSION=master DB=mysql_travis"
-      rvm: "jruby-19mode"
-    - env: "ACTIVERECORD_VERSION=master DB=postgresql_travis"
-      rvm: "jruby-19mode"
-    - env: "ACTIVERECORD_VERSION=4.0.2"
-      rvm: "1.9.2"
-    - env: "ACTIVERECORD_VERSION=4.0.2 DB=mysql_travis"
-      rvm: "1.9.2"
-    - env: "ACTIVERECORD_VERSION=4.0.2 DB=postgresql_travis"
-      rvm: "1.9.2"
-    - env: "ACTIVERECORD_VERSION=master"
-      rvm: "1.9.2"
-    - env: "ACTIVERECORD_VERSION=master DB=mysql_travis"
-      rvm: "1.9.2"
-    - env: "ACTIVERECORD_VERSION=master DB=postgresql_travis"
-      rvm: "1.9.2"
-    - env: "ACTIVERECORD_VERSION=master"
-      rvm: "1.9.3"
-    - env: "ACTIVERECORD_VERSION=master DB=mysql_travis"
-      rvm: "1.9.3"
-    - env: "ACTIVERECORD_VERSION=master DB=postgresql_travis"
-      rvm: "1.9.3"
-  allow_failures:
-    # Master may or may not pass
-    - env: "ACTIVERECORD_VERSION=master"
-    - env: "ACTIVERECORD_VERSION=master DB=mysql_travis"
-    - env: "ACTIVERECORD_VERSION=master DB=postgresql_travis"
-    # Rails 3.1 is incompatible with database cleaner 1.2
-    - env: "ACTIVERECORD_VERSION=3.1.12 DB=mysql_travis"
-    - env: "ACTIVERECORD_VERSION=3.1.12 DB=postgresql_travis"
-    # Postgres is not supported before Rails 4.0.
-    - env: "ACTIVERECORD_VERSION=3.1.12 DB=postgresql_travis"
-    - env: "ACTIVERECORD_VERSION=3.2.16 DB=postgresql_travis"
+    # Rails <6 does not support Ruby 3, see:
+    # https://github.com/rails/rails/issues/40938#issuecomment-751898275
+    - rvm: 3.0
+      gemfile: gemfiles/rails_4_2.gemfile
+    - rvm: 3.0
+      gemfile: gemfiles/rails_5_0.gemfile
+    - rvm: 3.0
+      gemfile: gemfiles/rails_5_1.gemfile
+    - rvm: 3.0
+      gemfile: gemfiles/rails_5_2.gemfile
+    # Ruby ≥2.7 uses a `bigdecimal` version that doesn't support BigDecimal.new
+    # that Rails 4.2 uses. See also:
+    # https://github.com/ruby/bigdecimal#which-version-should-you-select
+    - rvm: 2.7
+      gemfile: gemfiles/rails_4_2.gemfile
+    - rvm: jruby-9.1.17.0
+      gemfile: gemfiles/rails_5_2.gemfile
+    - rvm: 2.4
+      gemfile: gemfiles/rails_6_0.gemfile
+    - rvm: jruby-9.1.17.0
+      gemfile: gemfiles/rails_6_0.gemfile

data/Appraisals

@@ -0,0 +1,72 @@
+appraise "rails-4-2" do
+  group :sqlite do
+    gem "activerecord-jdbcsqlite3-adapter", "~> 1.3.24", platform: :jruby
+  end
+  group :mysql do
+    gem "mysql2", "~> 0.4.0", platform: :ruby
+    gem "jdbc-mysql", "~> 5.1.47", platform: :jruby
+    gem "activerecord-jdbcmysql-adapter", "~> 1.3.24", platform: :jruby
+  end
+  group :postgresql do
+    gem "pg", "~> 0.18.4", platform: :ruby
+    gem "activerecord-jdbcpostgresql-adapter", "~> 1.3.24", platform: :jruby
+  end
+
+  gem "activerecord", "~> 4.2.0"
+end
+
+appraise "rails-5-0" do
+  group :sqlite do
+    gem "activerecord-jdbcsqlite3-adapter", "~> 50.0", platform: :jruby
+  end
+  group :mysql do
+    gem "activerecord-jdbcmysql-adapter", "~> 50.0", platform: :jruby
+  end
+  group :postgresql do
+    gem "activerecord-jdbcpostgresql-adapter", "~> 50.0", platform: :jruby
+  end
+
+  gem "activerecord", "~> 5.0.0"
+end
+
+appraise "rails-5-1" do
+  group :sqlite do
+    gem "activerecord-jdbcsqlite3-adapter", "~> 51.0", platform: :jruby
+  end
+  group :mysql do
+    gem "activerecord-jdbcmysql-adapter", "~> 51.0", platform: :jruby
+  end
+  group :postgresql do
+    gem "activerecord-jdbcpostgresql-adapter", "~> 51.0", platform: :jruby
+  end
+
+  gem "activerecord", "~> 5.1.0"
+end
+
+appraise "rails-5-2" do
+  group :sqlite do
+    gem "activerecord-jdbcsqlite3-adapter", "~> 52.0", platform: :jruby
+  end
+  group :mysql do
+    gem "activerecord-jdbcmysql-adapter", "~> 52.0", platform: :jruby
+  end
+  group :postgresql do
+    gem "activerecord-jdbcpostgresql-adapter", "~> 52.0", platform: :jruby
+  end
+
+  gem "activerecord", "~> 5.2.0"
+end
+
+appraise "rails-6-0" do
+  group :sqlite do
+    gem "sqlite3", "~> 1.4", platform: :ruby
+    gem "activerecord-jdbcsqlite3-adapter", "~> 60.0", platform: :jruby
+  end
+  group :mysql do
+    gem "activerecord-jdbcmysql-adapter", "~> 60.0", platform: :jruby
+  end
+  group :postgresql do
+    gem "activerecord-jdbcpostgresql-adapter", "~> 60.0", platform: :jruby
+  end
+  gem "activerecord", "~> 6.0.0"
+end

data/Gemfile

@@ -3,30 +3,14 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in ranked-model.gemspec
 gemspec
 
-ar_version = ENV["ACTIVERECORD_VERSION"] || "default"
-
-ar_gem_version = case ar_version
-when "master"
-  gem "activerecord", {github: "rails/rails"}
-when "default"
-  # Allow the gemspec to specify
-else
-  gem "activerecord", "~> #{ar_version}"
+group :sqlite do
+  gem "sqlite3", "~> 1.3.13", platform: :ruby
 end
 
-platforms :rbx do
-  gem 'rubysl', '~> 2.0'
-  gem 'rubinius-developer_tools'
+group :postgresql do
+  gem "pg", "~> 1.2.0", platform: :ruby
 end
 
-# SQLite
-gem "activerecord-jdbcsqlite3-adapter", ">= 1.3.0", platforms: :jruby
-gem "sqlite3", platforms: :ruby
-
-# Postgres
-gem "activerecord-jdbcpostgresql-adapter", platforms: :jruby
-gem "pg", platforms: :ruby
-
-# MySQL
-gem "activerecord-jdbcmysql-adapter", platforms: :jruby
-gem "mysql", platforms: :ruby
+group :mysql do
+  gem "mysql2", "~> 0.5.0", platform: :ruby
+end

data/Readme.mkd

@@ -1,13 +1,11 @@
-**ranked-model** is a modern row sorting library built for Rails 3 & 4.  It uses ARel aggressively and is better optimized than most other libraries.
+**ranked-model** is a modern row sorting library built for Rails 4.2+.  It uses ARel aggressively and is better optimized than most other libraries.
 
 [![Build Status](https://travis-ci.org/mixonic/ranked-model.png)](https://travis-ci.org/mixonic/ranked-model)
 
 Installation
 ------------
 
-ranked-model passes specs with Rails 3.1, 3.2, 4.0, and 4.1-beta for MySQL, Postgres, and SQLite on Ruby 1.9.2, 1.9.3, 2.0, 2.1, jruby-19mode, and rubinius where Rails supports the platform. This is with the exception of Postgres before Rails 4.0 on all platforms, which is unsupported (I'd gladly accept a PR to fix this).
-
-TL;DR, if you are using Rails 4 and up you are 100% good to go. Before Rails 4, be wary of Postgres.
+ranked-model passes specs with Rails 4.2, 5.0, 5.1, 5.2 and 6.0 for MySQL, Postgres, and SQLite on Ruby 2.4 through 3.0 (with exceptions, please check the CI setup for supported combinations), and jruby-9.1.17.0 where Rails supports the platform.
 
 To install ranked-model, just add it to your `Gemfile`:
 
@@ -16,7 +14,7 @@ gem 'ranked-model'
 
 # Or pin ranked-model to git
 # gem 'ranked-model',
-#   :git => 'git@github.com:mixonic/ranked-model.git'
+#   git: 'git@github.com:mixonic/ranked-model.git'
 ```
 
 Then use `bundle install` to update your `Gemfile.lock`.
@@ -31,6 +29,18 @@ class Duck < ActiveRecord::Base
 end
 ```
 
+Give them an order (integer column):
+
+```bash
+rails g migration AddRowOrderToDucks row_order:integer
+rails db:migrate
+```
+
+**IMPORTANT: The `_order` table column MUST allow null values. For the reason behind this requirement see [issue#167](https://github.com/mixonic/ranked-model/issues/167)**
+
+
+
+
 Put your ducks in a row:
 
 ``` ruby
@@ -42,7 +52,7 @@ class Duck < ActiveRecord::Base
 end
 ```
 
-This simple example assumes an integer column called `row_order`.  To order Ducks by this order:
+Order the Ducks by this order:
 
 ``` ruby
 Duck.rank(:row_order).all
@@ -52,9 +62,11 @@ The ranking integers stored in the `row_order` column will be big and spaced apa
 implement a sorting UI, just update the resource by appending the column name with `_position` and indicating the desired position:
 
 ``` ruby
-@duck.update_attribute :row_order_position, 0  # or 1, 2, 37. :first, :last, :up and :down are also valid
+@duck.update row_order_position: 0  # or 1, 2, 37. :first, :last, :up and :down are also valid
 ```
 
+**IMPORTANT: Note that you MUST append _position to the column name when setting a new position on an instance. This is a fake column that can take relative as well as absolute index-based values for position.**
+
 Position numbers begin at zero.  A position number greater than the number of records acts the
 same as :last. :up and :down move the record up/down the ladder by one step.
 
@@ -70,27 +82,47 @@ $.ajax({
 });
 ```
 
+If you need to find the rank of an item with respect to other ranked items, you can use the `{column_name}_rank` method on the model instance. `{column_name}` is your resource ranking column.
+
+Following on from our examples above, the `row_order_rank` method will return the position of the duck object in the list with respect to the order defined by the row_order column.
+
+``` ruby
+Duck.rank(:row_order).first.row_order_rank # => 0
+Duck.rank(:row_order).third.row_order_rank # => 2
+```
+
 Complex Use
 -----------
 
-The `ranks` method takes serveral arguments:
+The `ranks` method takes several arguments:
 
 ``` ruby
 class Duck < ActiveRecord::Base
 
   include RankedModel
 
-  ranks :row_order,           # Name this ranker, used with rank()
-    :column => :sort_order    # Override the default column, which defaults to the name
-  
+  ranks :row_order,                  # Name this ranker, used with rank()
+    column: :sort_order              # Override the default column, which defaults to the name
+
   belongs_to :pond
   ranks :swimming_order,
-    :with_same => :pond_id    # Ducks belong_to Ponds, make the ranker scoped to one pond
-  
-  scope :walking, where(:walking => true )
+    with_same: :pond_id              # Ducks belong_to Ponds, make the ranker scoped to one pond
+
+  ranks :row_order,
+    with_same: [:pond_id, :breed]    # Lets rank them by breed
+
+  scope :walking, where(walking: true )
   ranks :walking_order,
-    :scope => :walking        # Narrow this ranker to a scope
+    scope: :walking                  # Narrow this ranker to a scope
 
+  belongs_to :parent, class_name: 'Duck', optional: true
+  ranks :child_order,
+    unless: :has_no_parent?,         # Rank only ducks that have a parent. Alternatively a Proc or lambda can be passed, e.g. proc { parent.nil? }
+    with_same: :parent_id
+
+  def has_no_parent?
+    parent.nil?
+  end
 end
 ```
 
@@ -104,12 +136,95 @@ Pond.first.ducks.rank(:swimming_order)
 Duck.walking.rank(:walking)
 ```
 
+Single Table Inheritance (STI)
+------------------------------
+
+ranked-model scopes your records' positions based on the class name of the object. If you have
+a STI `type` column set in your model, ranked-model will reference that class for positioning.
+
+Consider this example:
+
+``` ruby
+class Vehicle < ActiveRecord::Base
+  ranks :row_order
+end
+
+class Car < Vehicle
+end
+
+class Truck < Vehicle
+end
+
+car = Car.create!
+truck = Truck.create!
+
+car.row_order
+=> 0
+truck.row_order
+=> 0
+```
+
+In this example, the `row_order` for both `car` and `truck` will be set to `0` because they have
+different class names (`Car` and `Truck`, respectively).
+
+If you would like for both `car` and `truck` to be ranked together based on the base `Vehicle`
+class instead, use the `class_name` option:
+
+``` ruby
+class Vehicle < ActiveRecord::Base
+  ranks :row_order, class_name: 'Vehicle'
+end
+
+class Car < Vehicle
+end
+
+class Truck < Vehicle
+end
+
+car = Car.create!
+truck = Truck.create!
+
+car.row_order
+=> 0
+truck.row_order
+=> 4194304
+```
+
+Migrations for existing data
+----------------------------
+
+If you use `ranked_model` with existing data, the following migration (for Rails
+6) can be a starting point. Make sure to declare `include RankedModel` and
+`ranks :row_order` in your `Duck` before running the migration.
+
+```bash
+rails g migration AddRowOrderToDucks row_order:integer
+```
+
+Then, adjust the migration:
+```ruby
+# e.g. file db/migrate/20200325095038_add_row_order_to_ducks.rb
+class AddRowOrderToDucks < ActiveRecord::Migration[6.0]
+  def change
+    add_column :ducks, :row_order, :integer
+
+    # Newest Duck shall rank "highest"" (be last).
+    Duck.update_all('row_order = EXTRACT(EPOCH FROM created_at)')
+
+    # Alternatively, implement any other sorting default
+    # Duck.order(created_at: :desc).desc.each do |duck|
+    #   duck.update!(row_order: duck.created_at.to_i + duck.age / 2)
+    # end
+  end
+end
+```
+
 Internals
 ---------
 
-This libarary is written using ARel from the ground-up.  This leaves the code much cleaner
+This library is written using ARel from the ground-up.  This leaves the code much cleaner
 than many implementations.  ranked-model is also optimized to write to the database as little
-as possible: ranks are stored as a number between -8388607 and 8388607 (the MEDIUMINT range in MySQL).
+as possible: ranks are stored as a number between -2147483648 and 2147483647 (the INT range in MySQL).
 When an item is given a new position, it assigns itself a rank number between two neighbors.
 This allows several movements of items before no digits are available between two neighbors. When
 this occurs, ranked-model will try to shift other records out of the way. If items can't be easily
@@ -121,13 +236,17 @@ Contributing
 
 Fork, clone, write a test, write some code, commit, push, send a pull request.  Github FTW!
 
+The code is published under the [MIT License](LICENSE).
+
 The specs can be run with sqlite, postgres, and mysql:
 
 ```
-DB=postgres bundle exec rake
+bundle
+appraisal install
+DB=postgresql bundle exec appraisal rake
 ```
 
-Is no DB is specified, the tests run against sqlite.
+If no DB is specified (`sqlite`, `mysql`, or `postgresql`), the tests run against sqlite.
 
 RankedModel is mostly the handiwork of Matthew Beale:
 
@@ -149,3 +268,4 @@ A hearty thanks to these contributors:
 * [jguyon](https://github.com/jguyon)
 * [pehrlich](https://github.com/pehrlich)
 * [petergoldstein](https://github.com/petergoldstein)
+* [brendon](https://github.com/brendon)