mongoid_orderable 5.0.0 → 6.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a966ef4b59309d05845a832163936ce54e339a1e
-  data.tar.gz: 16b32ccd0fdb0a2ae9a61424d8842de9eba00d4e
+SHA256:
+  metadata.gz: b3a80c8eb058adeffe1ead4c0fa20ce10660ea49a2df1405d46048419f2af965
+  data.tar.gz: d68f6f64f52f132295e588dfcd59ad27d22a68237e5b29ab7682a37e3c940ca5
 SHA512:
-  metadata.gz: ee3e6de12801d857bb9345dc6035c698c56ee119f9b2e78fc15584caf6108351904487b888fa2091636bc750be62e6076b06bf74f38f44b2bd2fa68bc36611ac
-  data.tar.gz: 5fc8fe3f744fff60b38ac3d0136dcc5c84c069042beda3a7c623c9d6da743e67219e29da920bd983d4a5f506f081cbac9614e14630647dbc58593fa3dfb877d9
+  metadata.gz: 6c2d9da294dda836b17047aaf3ebc6329b3c382fb793c83fe57dd63a07512d2e1da65af3559b12e75ce3924b1edfaaefad8317f4acaa488cb94ad2392d84b474
+  data.tar.gz: 58e8c15554183674cef20639c2cb888cb6e793471ecf7f55ea76360f2ca7de351d218f417e34db220d2daa32c6ab5dc11da23bce7acec0f77a1f99718e713705

data/CHANGELOG.md

@@ -1,22 +1,83 @@
-# master
-
-# 5.0.0
-
-  * Mongoid 5 support (@dblock)
-  * Ruby 1.8 support dropped
-
-# 4.1.1
-
-  * Fix: index should respect scope (@joeyAghion)
-
-# 4.1.0
-
-  * Resolving scope foreign key form passed relation name (@dsci)
-  * Fix: relation metadata quering (@pjkelly)
-  * `previous_items` and `next_items` methods (@mrjlynch)
-
-# 4.0.0
-
-  * Semantic versioning
-  * Added Mongoid 4 support (@dblock)
-  * Fixes by @johnnyshields and @zhengjia
+### 6.0.3 (Next)
+
+* Your contribution here.
+
+### 6.0.2 (2021/01/26)
+
+* [#70](https://github.com/mongoid/mongoid_orderable/pull/70): Fix: Transactions should not use around callbacks - [@johnnyshields](https://github.com/johnnyshields).
+* [#70](https://github.com/mongoid/mongoid_orderable/pull/70): Refactor: Partially reduce code complexity of handler classes - [@johnnyshields](https://github.com/johnnyshields).
+* [#70](https://github.com/mongoid/mongoid_orderable/pull/70): Tests: Run all tests both with and without transactions - [@johnnyshields](https://github.com/johnnyshields).
+
+### 6.0.1 (2021/01/26)
+
+* [#69](https://github.com/mongoid/mongoid_orderable/pull/69): Fix: Transactions should force read from primary - [@johnnyshields](https://github.com/johnnyshields).
+
+### 6.0.0 (2021/01/23)
+
+* [#65](https://github.com/mongoid/mongoid_orderable/pull/65): Feature: Add transaction support with lock table - [@johnnyshields](https://github.com/johnnyshields).
+* [#65](https://github.com/mongoid/mongoid_orderable/pull/65): Feature: Avoid calling position function if neither position nor scope is changing - [@johnnyshields](https://github.com/johnnyshields).
+* [#62](https://github.com/mongoid/mongoid_orderable/pull/62): Feature: Allow scope parameter to be an Array - [@johnnyshields](https://github.com/johnnyshields).
+* [#62](https://github.com/mongoid/mongoid_orderable/pull/62): Feature: Add global configurability - [@johnnyshields](https://github.com/johnnyshields).
+* [#65](https://github.com/mongoid/mongoid_orderable/pull/65): Fix: Do not run embedded destroy callbacks when the root object has been destroyed - [@johnnyshields](https://github.com/johnnyshields).
+* [#62](https://github.com/mongoid/mongoid_orderable/pull/62): Refactor: rename "column" to "field" - [@johnnyshields](https://github.com/johnnyshields).
+* [#60](https://github.com/mongoid/mongoid_orderable/pull/60): Refactor: Drop support for Mongoid 6.x and lower - [@johnnyshields](https://github.com/johnnyshields).
+* [#60](https://github.com/mongoid/mongoid_orderable/pull/60): Refactor: Remove Mongoid Compatibility (no longer needed) - [@johnnyshields](https://github.com/johnnyshields).
+
+### 5.2.0 (2018/05/01)
+
+* [#57](https://github.com/mongoid/mongoid_orderable/pull/57): Compatibility with Mongoid 7 - [@tomasc](https://github.com/tomasc).
+* [#52](https://github.com/mongoid/mongoid_orderable/pull/52): Test against Mongoid 6 - [@dblock](https://github.com/dblock).
+
+### 5.1.0 (2017/06/04)
+
+* [#50](https://github.com/mongoid/mongoid_orderable/pull/50): Added Danger, PR linter - [@dblock](https://github.com/dblock).
+* [#51](https://github.com/mongoid/mongoid_orderable/pull/51): Added RuboCop - [@dblock](https://github.com/dblock).
+* [#49](https://github.com/mongoid/mongoid_orderable/pull/49): Fix orderable on embedded documents inside an inherited model - [@rafaelgaspar](https://github.com/rafaelgaspar).
+
+### 5.0.0 (2015/10/21)
+
+* [#41](https://github.com/mongoid/mongoid_orderable/pull/41): Mongoid 5 support - [@dblock](https://github.com/dblock).
+* [#41](https://github.com/mongoid/mongoid_orderable/pull/41): Dropped support for ruby 1.8 - [@dblock](https://github.com/dblock).
+
+### 4.1.1 (2014/12/19)
+
+* [#34](https://github.com/mongoid/mongoid_orderable/pull/34): Fix: index should respect scope - [@joeyAghion](https://github.com/joeyAghion).
+
+### 4.1.0 (2014/3/19)
+
+* [#30](https://github.com/mongoid/mongoid_orderable/pull/30): Fix: reset a single field when `orderable_scope` changed instead of removing it from list - [@Bharat311](https://github.com/Bharat311).
+* [#29](https://github.com/mongoid/mongoid_orderable/pull/29): Fix: incorrect position when orderable base is set - [@Bharat311](https://github.com/Bharat311).
+* [#28](https://github.com/mongoid/mongoid_orderable/pull/28): Inherited `orderable_configurations` - [@johnny-miyake](https://github.com/johnny-miyake).
+* [#27](https://github.com/mongoid/mongoid_orderable/pull/27): Allowed numeric string to specify a target position - [@johnny-miyake](https://github.com/johnny-miyake).
+* [#26](https://github.com/mongoid/mongoid_orderable/pull/26): Added support for multiple orderable fields - [@Bharat311](https://github.com/Bharat311).
+* [#22](https://github.com/mongoid/mongoid_orderable/pull/22): Added lazy support for scopes with different foreign key names - [@dsci](https://github.com/dsci).
+* [#21](https://github.com/mongoid/mongoid_orderable/pull/21): Accounting for change in Mongoid's metadata API - [@pjkelly](https://github.com/pjkelly).
+* [#20](https://github.com/mongoid/mongoid_orderable/pull/20): Added next and previous item methods - [@mrjlynch](https://github.com/mrjlynch).
+* [#19](https://github.com/mongoid/mongoid_orderable/pull/19): Added lower and higher item methods - [@mrjlynch](https://github.com/mrjlynch).
+
+### 4.0.0 (2013/10/22)
+
+* [#18](https://github.com/mongoid/mongoid_orderable/pull/18): Added Mongoid 4 support - [@dblock](https://github.com/dblock).
+* [#16](https://github.com/mongoid/mongoid_orderable/pull/16): Fix for Mongoid identity map combined with scoped orderable - [@johnnyshields](https://github.com/johnnyshields).
+* [#15](https://github.com/mongoid/mongoid_orderable/pull/15): Support pass-thru of Mongoid field alias (`:as` parameter) - [@johnnyshields](https://github.com/johnnyshields).
+* [#13](https://github.com/mongoid/mongoid_orderable/pull/13): Support inheritance - [@zhengjia](https://github.com/zhengjia).
+
+### 1.2.0 (2013/1/10)
+
+* [#12](https://github.com/mongoid/mongoid_orderable/pull/12): Added support for "base" in config options, in order to do a zero-based position - [@johnnyshields](https://github.com/johnnyshields).
+
+### 1.1.0 (2012/5/23)
+
+* Added Mongoid 3 support - [@pyromaniac](https://github.com/pyromaniac).
+
+### 1.0.0 (2012/2/14)
+
+* [#5](https://github.com/mongoid/mongoid_orderable/pull/5): Allow for use with default scopes - [@mattiassvedhem](https://github.com/mattiassvedhem).
+
+### 0.9.1 (2012/2/3)
+
+### 0.9.0 (2011/11/23)
+
+### 0.0.1 (2011/11/1)
+
+* Initial public release - [@pyromaniac](https://github.com/pyromaniac).

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011-2017 Arkadiy Zabazhanov & Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,149 +1,256 @@
-[![Gem Version](https://badge.fury.io/rb/mongoid_orderable.svg)](https://badge.fury.io/rb/mongoid_orderable)
-[![Build Status](https://travis-ci.org/pyromaniac/mongoid_orderable.svg?branch=master)](https://travis-ci.org/pyromaniac/mongoid_orderable)
-
-# What?
-
-Mongoid::Orderable is a ordered list implementation for your Mongoid 2, 3, 4 and 5 models.
-
-# Why?
-
-* It uses native mongo batch increment feature
-* It supports mutators api
-* It correctly assigns the position while moving document between scopes
-* It supports mongoid 2, 3 and 4
-* It supports specifying multiple orderable columns
-
-# How?
-
-```ruby
-gem 'mongoid_orderable'
-```
-
-Gem has the same api as others. Just include Mongoid::Orderable into your model and call `orderable` method.
-Embedded objects are automatically scoped by their parent.
-
-```ruby
-class Item
-  include Mongoid::Document
-  include Mongoid::Orderable
-
-  # belongs_to :group
-  # belongs_to :drawer, class_name: "Office::Drawer",
-  #            foreign_key: "legacy_drawer_key_id"
-
-  # orderable
-  # orderable scope: :group, column: :pos
-  # orderable scope: :drawer, column: :pos # resolves scope foreign key from relation
-  # orderable scope: 'drawer', column: :pos # but if you pass a string - it will use it as is, as the column name for scope
-  # orderable scope: lambda { |document| where(group_id: document.group_id) }
-  # orderable index: false # this one if you want specify indexes manually
-  # orderable base: 0 # count position from zero as the top-most value (1 is the default value)
-end
-```
-
-# Usage
-
-```ruby
-item.move_to 2 # just change position
-item.move_to! 2 # and save
-item.move_to = 2 # assignable method
-
-# symbol position
-item.move_to :top
-item.move_to :bottom
-item.move_to :higher
-item.move_to :lower
-
-# generated methods
-item.move_to_top
-item.move_to_bottom
-item.move_higher
-item.move_lower
-
-item.next_items # return a collection of items higher on the list
-item.previous_items # return a collection of items lower on the list
-
-item.next_item # returns the next item in the list
-item.previous_item # returns the previous item in the list
-```
-
-# Multiple Columns
-
-You can also define multiple orderable columns for any class including the Mongoid::Orderable module.
-
-```ruby
-class Book
-  include Mongoid::Document
-  include Mongoid::Orderable
-
-  orderable base: 0
-  orderable column: sno, as: :serial_no
-end
-```
-
-The above defines two different orderable_columns on Book - *position* and *serial_no*.
-The following helpers are generated in this case:
-
-```ruby
-item.move_#{column_name}_to
-item.move_#{column_name}_to=
-item.move_#{column_name}_to!
-
-item.move_#{column_name}_to_top
-item.move_#{column_name}_to_bottom
-item.move_#{column_name}_higher
-item.move_#{column_name}_lower
-
-item.next_#{column_name}_items
-item.previous_#{column_name}_items
-
-item.next_#{column_name}_item
-item.previous_#{column_name}_item
-```
-
-*where column_name is either **position** or  **serial_no**.*
-
-When a model defines multiple orderable columns, the original helpers are also available and work on the first orderable column.
-
-```ruby
-  @book1 = Book.create!
-  @book2 = Book.create!
-  @book2                 => #<Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 1>
-  @book2.move_to! :top   # this will change the :position of the book to 0 (not serial_no)
-  @book2                 => #<Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 0>
-```
-
-To specify any other orderable column as default pass the **default: true** option with orderable.
-
-```ruby
-  orderable column: sno, as: :serial_no, default: true
-```
-
-# Embedded documents
-```ruby
-class Question
-  include Mongoid::Document
-  include Mongoid::Orderable
-
-  embedded_in :survey
-
-  orderable
-end
-```
-If you bulk import embedded documents without specifying their position, no field `position` will be written.
-```ruby
-class Survey
-  include Mongoid::Document
-
-  embeds_many :questions, cascade_callbacks: true
-end
-```
-To ensure the position is written correctly, you will need to provide the cascade callbacks option to the relation.
-
-# Contributing
-
-Fork && Patch && Spec && Push && Pull request.
-
-# License
-
-Mongoid::Orderable is released under the MIT license.
+[![Gem Version](https://badge.fury.io/rb/mongoid_orderable.svg)](https://badge.fury.io/rb/mongoid_orderable)
+[![Build Status](https://travis-ci.org/mongoid/mongoid_orderable.svg?branch=master)](https://travis-ci.org/mongoid/mongoid_orderable)
+
+# Mongoid Orderable
+
+Mongoid::Orderable is a ordered list implementation for your Mongoid 7+ projects.
+
+### Core Features
+
+* Sets a position index field on your documents which allows you to sort them in order.
+* Uses MongoDB's `$inc` operator to batch-update position.
+* Supports scope for position index, including changing scopes.
+* Supports multiple position indexes on the same document.
+* (Optional) Uses [MongoDB transactions](https://docs.mongodb.com/manual/core/transactions/) to ensure order integrity during concurrent updates.
+
+### Version Support
+
+As of version 6.0.0, Mongoid::Orderable supports the following dependency versions:
+
+* Ruby 2.6+
+* Mongoid 7.0+
+* Rails 5.2+
+
+For older versions, please use Mongoid::Orderable 5.x and earlier.
+
+Transaction support requires MongoDB 4.2+ (4.4+ recommended.)
+
+## Usage
+
+### Getting Started
+
+```ruby
+gem 'mongoid_orderable'
+```
+
+Include `Mongoid::Orderable` into your model and call `orderable` method.
+Embedded objects are automatically scoped to their parent.
+
+```ruby
+class MyModel
+  include Mongoid::Document
+  include Mongoid::Orderable
+
+  belongs_to :group
+  belongs_to :drawer, class_name: "Office::Drawer",
+             foreign_key: "legacy_drawer_key_id"
+
+  orderable
+
+  # if you set :scope as a symbol, it will resolve the foreign key from relation
+  orderable scope: :drawer, field: :pos
+
+  # if you set :scope as a string, it will use it as the field name for scope
+  orderable scope: 'drawer', field: :pos
+
+  # scope can also be a proc
+  orderable scope: ->(doc) { where(group_id: doc.group_id) }
+
+  # this one if you want specify indexes manually
+  orderable index: false 
+
+  # count position from zero as the top-most value (1 is the default value)
+  orderable base: 0
+end
+```
+
+You can also set default config values in an initializer, which will be
+applied when calling the `orderable` macro in a model.
+
+```ruby
+# configs/initializers/mongoid_orderable.rb
+Mongoid::Orderable.configure do |config|
+  config.field = :pos
+  config.base = 0
+  config.index = false
+end
+```
+
+### Moving Position
+
+```ruby
+item.move_to 2 # just change position
+item.move_to! 2 # and save
+item.move_to = 2 # assignable method
+
+# symbol position
+item.move_to :top
+item.move_to :bottom
+item.move_to :higher
+item.move_to :lower
+
+# generated methods
+item.move_to_top
+item.move_to_bottom
+item.move_higher
+item.move_lower
+
+item.next_items # return a collection of items higher on the list
+item.previous_items # return a collection of items lower on the list
+
+item.next_item # returns the next item in the list
+item.previous_item # returns the previous item in the list
+```
+
+### Multiple Fields
+
+You can also define multiple orderable fields for any class including the Mongoid::Orderable module.
+
+```ruby
+class Book
+  include Mongoid::Document
+  include Mongoid::Orderable
+
+  orderable base: 0
+  orderable field: sno, as: :serial_no
+end
+```
+
+The above defines two different orderable_fields on Book - *position* and *serial_no*.
+The following helpers are generated in this case:
+
+```ruby
+book.move_#{field}_to
+book.move_#{field}_to=
+book.move_#{field}_to!
+
+book.move_#{field}_to_top
+book.move_#{field}_to_bottom
+book.move_#{field}_higher
+book.move_#{field}_lower
+
+book.next_#{field}_items
+book.previous_#{field}_items
+
+book.next_#{field}_item
+book.previous_#{field}_item
+```
+
+where `#{field}` is either `position` or `serial_no`.
+
+When a model defines multiple orderable fields, the original helpers are also available and work on the first orderable field.
+
+```ruby
+  @book1 = Book.create!
+  @book2 = Book.create!
+  @book2                 # => <Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 1>
+  @book2.move_to! :top   # this will change the :position of the book to 0 (not serial_no)
+  @book2                 # => <Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 0>
+```
+
+To specify any other orderable field as default pass the **default: true** option with orderable.
+
+```ruby
+  orderable field: sno, as: :serial_no, default: true
+```
+
+### Embedded Documents
+
+```ruby
+class Question
+  include Mongoid::Document
+  include Mongoid::Orderable
+
+  embedded_in :survey
+
+  orderable
+end
+```
+
+If you bulk import embedded documents without specifying their position,
+no field `position` will be written.
+
+```ruby
+class Survey
+  include Mongoid::Document
+
+  embeds_many :questions, cascade_callbacks: true
+end
+```
+
+To ensure the position is written correctly, you will need to set
+`cascade_callbacks: true` on the relation.
+
+## Transaction Support
+
+By default, Mongoid Orderable does not guarantee ordering consistency
+when doing multiple concurrent updates on documents. This means that
+instead of having positions `1, 2, 3, 4, 5`, after running your system
+in production at scale your position data will become corrupted, e.g.
+`1, 1, 4, 4, 6`. To remedy this, this Mongoid Orderable can use
+[MongoDB transactions](https://docs.mongodb.com/manual/core/transactions/)
+
+### Prerequisites
+
+* MongoDB version 4.2+ (4.4+ recommended.)
+* Requires [MongoDB Replica Set](https://docs.mongodb.com/manual/tutorial/deploy-replica-set/) topology
+
+### Configuration
+
+You may enable transactions on both the global and model configs:
+
+```ruby
+Mongoid::Orderable.configure do |config|
+  config.use_transactions = true       # default: false
+  config.transaction_max_retries = 10  # default: 10
+end
+
+class MyModel
+  orderable :position, use_transactions: false
+end
+```
+
+When two transactions are attempted at the same time, database-level
+`WriteConflict` failures may result and retries will be attempted.
+After `transaction_max_retries` has been exceeded, a
+`Mongoid::Orderable::Errors::TransactionFailed` error will be raised.
+
+### Locks
+
+When using transactions, Mongoid Orderable creates a collection
+`mongoid_orderable_locks` which is used to store temporary lock objects.
+This collection accumulate documents overtime; it is safe to delete it periodically.
+
+You can change the lock collection name globally or per model:
+
+```ruby
+Mongoid::Orderable.configure do |config|
+  config.lock_collection = "my_locks"  # default: "mongoid_orderable_locks"
+end
+
+class MyModel
+  orderable :position, lock_collection: "my_model_locks"
+end
+```
+
+### MongoDB 4.2 Support
+
+In MongoDB 4.2, collections cannot be created within transactions.
+Therefore, you will need to manually run the following command once
+to initialize the lock collection:
+
+```ruby
+Mongoid::Orderable::Models::Lock.create!
+```
+
+This step is not necessary when using MongoDB 4.4+.
+
+### Contributing
+
+Please fork the project on Github and raise a pull request including passing specs.
+
+### Copyright & License
+
+Copyright (c) 2011 Arkadiy Zabazhanov, Johnny Shields, and contributors.
+
+MIT license, see [LICENSE](LICENSE.txt) for details.