mongoid_orderable 6.0.5 → 6.0.7

data/README.md

@@ -1,275 +1,296 @@
-[![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.
-
-### Disable Ordering
-
-You can disable position tracking for specific documents using the `:if` and `:unless` options.
-This is in advanced scenarios where you want to control position manually for certain documents.
-In general, the disable condition should match a specific scope.
-**Warning:** If used improperly, this will cause your documents to become out-of-order.
-
-```ruby
-class Book
-  include Mongoid::Document
-  include Mongoid::Orderable
-
-  field :track_position, type: Boolean
-  
-  orderable if: :track_position, unless: -> { created_at < Date.parse('2020-01-01') }
-end
-```
-
-## 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.
-Lock collections use a TTL index which auto-deletes objects older than 1 day.
-
-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.
+[![Gem Version](https://badge.fury.io/rb/mongoid_orderable.svg)](https://badge.fury.io/rb/mongoid_orderable)
+[![Test](https://github.com/mongoid/mongoid_orderable/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/mongoid/mongoid_orderable/actions/workflows/test.yml?query=branch%3Amaster)
+[![Coverage Status](https://coveralls.io/repos/github/mongoid/mongoid_orderable/badge.svg?branch=master)](https://coveralls.io/github/mongoid/mongoid_orderable?branch=master)
+
+# Mongoid Orderable
+
+The Ruby 4.0 CI job measures all library files with SimpleCov and submits `coverage/.resultset.json` through the official Coveralls action using GitHub's automatic token. Other matrix jobs do not upload duplicate reports. Run `COVERAGE=true bundle install` and `COVERAGE=true bundle exec rake spec` to measure coverage locally. An accepted upstream default-branch build is required for the badge; this workflow alone does not activate the external service.
+
+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
+
+See [UPGRADING](UPGRADING.md) for migration notes, including embedded position assignment changes in 6.0.7.
+
+### 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.
+
+Assigning an embedded document's position reorders its siblings when either the child or its parent is saved:
+
+```ruby
+survey = Survey.create!
+3.times { survey.questions.create! }
+question = survey.questions.last
+
+question.position = 1
+survey.save! # question.save! also works
+survey.reload.questions.map(&:position) # => [2, 3, 1]
+```
+
+Positions below the top or above the bottom are clamped to the list bounds. Assigning `nil` moves an existing child to the bottom. New children with a position are inserted at that position, shifting later siblings. Existing `move_to`, `move_to!`, and their helper methods remain supported; an explicit movement request takes precedence over a direct position assignment.
+
+This changes the previous behavior where assigning an existing embedded child's position could leave duplicate positions instead of shifting its siblings. See [UPGRADING](UPGRADING.md).
+
+### Disable Ordering
+
+You can disable position tracking for specific documents using the `:if` and `:unless` options.
+This is in advanced scenarios where you want to control position manually for certain documents.
+In general, the disable condition should match a specific scope.
+**Warning:** If used improperly, this will cause your documents to become out-of-order.
+
+```ruby
+class Book
+  include Mongoid::Document
+  include Mongoid::Orderable
+
+  field :track_position, type: Boolean
+  
+  orderable if: :track_position, unless: -> { created_at < Date.parse('2020-01-01') }
+end
+```
+
+## 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.
+Lock collections use a TTL index which auto-deletes objects older than 1 day.
+
+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.

data/Rakefile

@@ -1,24 +1,24 @@
-# frozen_string_literal: true
-
-require 'bundler'
-
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  warn e.message
-  warn 'Run `bundle install` to install missing gems'
-  exit e.status_code
-end
-
-Bundler::GemHelper.install_tasks
-
-require 'rspec/core'
-require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec) do |spec|
-  spec.pattern = FileList['spec/**/*_spec.rb']
-end
-
-require 'rubocop/rake_task'
-RuboCop::RakeTask.new(:rubocop)
-
-task default: %i[rubocop spec]
+# frozen_string_literal: true
+
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+task default: %i[rubocop spec]

data/lib/config/locales/en.yml

@@ -1,12 +1,12 @@
-en:
-  mongoid:
-    errors:
-      messages:
-        invalid_target_position:
-          message: "`%{value}` is not an acceptable value for target position."
-          summary: "Mongoid::Orderable accepts: a Numeric, a numeric string, :top, :bottom, or nil."
-          resolution: "You must give an acceptable value for target position."
-        transaction_failed:
-          message: "Transaction failed due to a database-level conflict."
-          summary: ""
-          resolution: "Please retry the transaction."
+en:
+  mongoid:
+    errors:
+      messages:
+        invalid_target_position:
+          message: "`%{value}` is not an acceptable value for target position."
+          summary: "Mongoid::Orderable accepts: a Numeric, a numeric string, :top, :bottom, or nil."
+          resolution: "You must give an acceptable value for target position."
+        transaction_failed:
+          message: "Transaction failed due to a database-level conflict."
+          summary: ""
+          resolution: "Please retry the transaction."