mongoid-scroll 1.0.1 → 2.0.1

data/RELEASING.md

@@ -1,67 +1,48 @@
-Releasing Mongoid::Scroll
-=========================
+# Releasing Mongoid::Scroll
 
-There're no particular rules about when to release mongoid-scroll. Release bug fixes frequently, features not so frequently and breaking API changes rarely.
+Use the upstream checkout on clean `master`, verify `origin` is `mongoid/mongoid-scroll`, and run `git pull --ff-only`. Follow semantic versioning: patch for fixes, minor for backward-compatible features, major for breaking changes.
 
-### Release
+## Prepare
 
-Run tests, check that all tests succeed locally.
+Set `lib/mongoid/scroll/version.rb` to the release version, date its `CHANGELOG.md` section using `YYYY/MM/DD`, and remove the contribution placeholder.
 
-```
+```sh
 bundle install
-rake
-```
-
-Check that the last build succeeded in [Github Actions](https://github.com/mongoid/mongoid-scroll/actions) for all supported platforms.
-
-Increment the version, modify [lib/mongoid/scroll/version.rb](lib/mongoid/scroll/version.rb).
-
-*  Increment the third number if the release has bug fixes and/or very minor features, only (eg. change `0.4.1` to `0.4.2`).
-*  Increment the second number if the release contains major features or breaking API changes (eg. change `0.4.1` to `0.5.0`).
-
-Change "Next Release" in [CHANGELOG.md](CHANGELOG.md) to the new version.
-
-```
-### 0.4.0 (2018/12/24)
-```
-
-Remove the line with "* Your contribution here.", since there will be no more contributions to this release.
-
-Commit your changes.
-
-```
-git add CHANGELOG.md lib/mongoid-scroll/version.rb
-git commit -m "Preparing for release, 0.4.0."
+bundle exec rake
+git add CHANGELOG.md lib/mongoid/scroll/version.rb RELEASING.md
+git commit -m "Preparing for release, 2.0.1."
 git push origin master
 ```
 
-Release.
-
-```
-$ rake release
+## Publish RubyGems and GitHub
 
-mongoid-scroll 0.4.0 built to pkg/mongoid-scroll-0.4.0.gem.
-Tagged v0.4.0.
-Pushed git commits and tags.
-Pushed mongoid-scroll 0.4.0 to rubygems.org.
+```sh
+bundle exec rake release
 ```
 
-### Prepare for the Next Version
+The task builds the gem, pushes its tag, and publishes to RubyGems. Complete MFA when prompted. If interrupted, inspect the tag and RubyGems version before retrying; never move a published tag. If only publication is missing, resume with `gem push pkg/mongoid-scroll-2.0.1.gem`.
 
-Add the next release to [CHANGELOG.md](CHANGELOG.md).
+A tag is not a GitHub release. After confirming RubyGems publication, create the matching GitHub release with changelog notes:
 
+```sh
+version=2.0.1
+notes="$(mktemp)"
+awk -v version="$version" '
+  /^### / {
+    if (found) exit
+    if ($2 == version) found = 1
+    next
+  }
+  found { print }
+' CHANGELOG.md > "$notes"
+gh release create "v$version" --repo mongoid/mongoid-scroll --verify-tag --title "$version" --notes-file "$notes" --latest
+rm "$notes"
+curl --fail --silent --show-error "https://rubygems.org/api/v2/rubygems/mongoid-scroll/versions/$version.json"
+gh release view "v$version" --repo mongoid/mongoid-scroll
 ```
-### 0.4.1 (Next)
 
-* Your contribution here.
-```
-
-Increment the minor version, modify [lib/mongoid-scroll/version.rb](lib/mongoid-scroll/version.rb).
+Verify both the published gem and non-draft GitHub release before declaring completion.
 
-Commit your changes.
+## Prepare the Next Version
 
-```
-git add CHANGELOG.md lib/mongoid-scroll/version.rb
-git commit -m "Preparing for next release, 0.4.1."
-git push origin master
-```
+Increment the development patch version in `lib/mongoid/scroll/version.rb` (for example, `2.0.2`). Add `### 2.0.2 (Next)` with a contribution placeholder above the released changelog section. Commit and push those changes to `master`, leaving the released tag unchanged.

data/Rakefile

@@ -1,13 +1,13 @@
 require 'rubygems'
 require 'bundler/gem_tasks'
 
-require File.expand_path('../lib/mongoid/scroll/version', __FILE__)
+require File.expand_path('lib/mongoid/scroll/version', __dir__)
 
 begin
   Bundler.setup(:default, :development)
 rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts 'Run `bundle install` to install missing gems'
+  warn e.message
+  warn 'Run `bundle install` to install missing gems'
   exit e.status_code
 end
 

data/UPGRADING.md

@@ -1,5 +1,25 @@
 # Upgrading
 
+## Upgrading to >= 2.0.0
+
+The second argument yielded in the block in `Mongoid::Criteria::Scrollable#scroll` and `Mongo::Scrollable#scroll` has changed from a cursor to an instance of `Mongoid::Criteria::Scrollable` which provides `next_cursor` and `previous_cursor`. The `next_cursor` method returns the same cursor as in versions prior to 2.0.0.
+
+For example, this code:
+
+```ruby
+Feed::Item.asc(field_name).limit(2).scroll(cursor) do |_, next_cursor|
+  cursor = next_cursor
+end
+```
+
+Should be updated to:
+
+```
+Feed::Item.asc(field_name).limit(2).scroll(cursor) do |_, iterator|
+  cursor = iterator.next_cursor
+end
+```
+
 ## Upgrading to >= 1.0.0
 
 ### Mismatched Sort Fields
@@ -9,6 +29,6 @@ Both `Mongoid::Criteria::Scrollable#scroll` and `Mongo::Scrollable` now raise a
 For example, the following code will now raise a `MismatchedSortFieldsError` because we set a different field name (`position`) from the `created_at` field used to sort in `scroll`.
 
 ```ruby
-cursor.field_name = "position" 
+cursor.field_name = "position"
 Feed::Item.desc(:created_at).scroll(cursor)
 ```

data/examples/{mongoid_scroll_feed.rb → feed.rb}

@@ -1,11 +1,11 @@
 require 'bundler'
 Bundler.setup(:default, :development)
 
+require 'logger'
 require 'mongoid-scroll'
 require 'faker'
 
 Mongoid.logger.level = Logger::INFO
-Mongo::Logger.logger.level = Logger::INFO if Mongoid::Compatibility::Version.mongoid5?
 Mongoid.connect_to 'mongoid_scroll_demo'
 Mongoid.purge!
 
@@ -24,7 +24,7 @@ total_items = 20
 scroll_by = 7
 
 # insert items with a position out-of-order
-rands = (0..total_items).to_a.sort { rand }[0..total_items]
+rands = (0..total_items).to_a.sort { |_l, _r| rand }[0..total_items]
 total_items.times do |_i|
   Feed::Item.create! title: Faker::Lorem.sentence, position: rands.pop
 end
@@ -38,10 +38,11 @@ loop do
   next_cursor = nil
   Feed::Item.asc(:position).limit(scroll_by).scroll(current_cursor) do |item, cursor|
     puts "#{item.position}: #{item.title}"
-    next_cursor = cursor
+    next_cursor = cursor.next_cursor
     total_shown += 1
   end
   break unless next_cursor
+
   # destroy an item just for the heck of it, scroll is not affected
   Feed::Item.asc(:position).first.destroy
 end

data/lib/config/locales/en.yml

@@ -27,4 +27,7 @@ en:
             message: "Unsupported field type."
             summary: "The type of the field '%{field}' is not supported: %{type}."
             resolution: "Please open a feature request in https://github.com/mongoid/mongoid-scroll."
-
+          unsupported_type:
+            message: "Unsupported type."
+            summary: "The type supplied in the cursor is not supported: %{type}."
+            resolution: "The cursor type can be either ':previous' or ':next'."

data/lib/mongoid/criteria/scrollable/fields.rb

@@ -5,12 +5,18 @@ module Mongoid
       module Fields
         private
 
+        def scroll_model_field(field_name)
+          klass.fields[field_name.to_s] ||
+            raise(Mongoid::Scroll::Errors::NoSuchFieldError.new(field: field_name))
+        end
+
         def raise_mismatched_sort_fields_error!(cursor, criteria_cursor_options)
           diff = cursor.sort_options.reject { |k, v| criteria_cursor_options[k] == v }
           raise Mongoid::Scroll::Errors::MismatchedSortFieldsError.new(diff: diff)
         end
 
         def different_sort_fields?(cursor, criteria_cursor_options)
+          scroll_model_field(cursor.field_name)
           criteria_cursor_options[:field_type] = criteria_cursor_options[:field_type].to_s
           criteria_cursor_options[:field_name] = criteria_cursor_options[:field_name].to_s
           criteria_cursor_options != cursor.sort_options

data/lib/mongoid/criteria/scrollable/iterator.rb

@@ -0,0 +1,19 @@
+module Mongoid
+  class Criteria
+    module Scrollable
+      class Iterator
+        attr_accessor :previous_cursor, :current_cursor, :next_cursor
+
+        def initialize(previous_cursor:, current_cursor:, next_cursor:)
+          @previous_cursor = previous_cursor
+          @current_cursor = current_cursor
+          @next_cursor = next_cursor
+        end
+
+        def first_cursor
+          @first_cursor ||= next_cursor.class.new(nil, next_cursor.sort_options)
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/criteria/scrollable.rb

@@ -10,15 +10,24 @@ module Mongoid
         criteria = dup
         criteria.merge!(default_sort) if no_sort_option?
         cursor_options = build_cursor_options(criteria)
-        cursor = cursor.is_a?(cursor_type) ? cursor : new_cursor(cursor_type, cursor, cursor_options)
+        cursor = new_cursor(cursor_type, cursor, cursor_options) unless cursor.is_a?(cursor_type)
         raise_mismatched_sort_fields_error!(cursor, cursor_options) if different_sort_fields?(cursor, cursor_options)
-        cursor_criteria = build_cursor_criteria(criteria, cursor)
+        records = find_records(criteria, cursor)
         if block_given?
-          cursor_criteria.order_by(_id: scroll_direction(criteria)).each do |record|
-            yield record, cursor_from_record(cursor_type, record, cursor_options)
+          previous_cursor = nil
+          current_cursor = nil
+          records.each do |record|
+            previous_cursor ||= cursor_from_record(cursor_type, record, cursor_options.merge(type: :previous))
+            current_cursor ||= cursor_from_record(cursor_type, record, cursor_options.merge(include_current: true))
+            iterator = Mongoid::Criteria::Scrollable::Iterator.new(
+              previous_cursor: previous_cursor,
+              next_cursor: cursor_from_record(cursor_type, record, cursor_options),
+              current_cursor: current_cursor
+            )
+            yield record, iterator
           end
         else
-          cursor_criteria
+          records
         end
       end
 
@@ -60,10 +69,21 @@ module Mongoid
         cursor_type.new(cursor, cursor_options)
       end
 
-      def build_cursor_criteria(criteria, cursor)
+      def find_records(criteria, cursor)
         cursor_criteria = criteria.dup
         cursor_criteria.selector = { '$and' => [criteria.selector, cursor.criteria] }
-        cursor_criteria
+        if cursor.type == :previous
+          pipeline = [
+            { '$match' => cursor_criteria.selector },
+            { '$sort' => { cursor.field_name => -cursor.direction } },
+            { '$limit' => criteria.options[:limit] },
+            { '$sort' => { cursor.field_name => cursor.direction } }
+          ]
+          aggregation = cursor_criteria.view.aggregate(pipeline)
+          aggregation.map { |record| Mongoid::Factory.from_db(cursor_criteria.klass, record) }
+        else
+          cursor_criteria.order_by(_id: scroll_direction(criteria))
+        end
       end
 
       def cursor_from_record(cursor_type, record, cursor_options)
@@ -72,11 +92,11 @@ module Mongoid
 
       def scroll_field_type(criteria)
         scroll_field = scroll_field(criteria)
-        field = criteria.klass.fields[scroll_field.to_s]
+        field = scroll_model_field(scroll_field)
         field.foreign_key? && field.object_id_field? ? BSON::ObjectId : field.type
       end
     end
   end
 end
 
-Mongoid::Criteria.send(:include, Mongoid::Criteria::Scrollable)
+Mongoid::Criteria.include Mongoid::Criteria::Scrollable

data/lib/mongoid/scroll/base64_encoded_cursor.rb

@@ -10,18 +10,19 @@ module Mongoid
         if value
           begin
             parsed = ::JSON.parse(::Base64.strict_decode64(value))
-          rescue
+          rescue StandardError
             raise Mongoid::Scroll::Errors::InvalidBase64CursorError.new(cursor: value)
           end
-          super parse_field_value(parsed['field_type'], parsed['field_name'], parsed['value']), {
+          super(parse_field_value(parsed['field_type'], parsed['field_name'], parsed['value']), {
             field_type: parsed['field_type'],
             field_name: parsed['field_name'],
             direction: parsed['direction'],
             include_current: parsed['include_current'],
-            tiebreak_id: parsed['tiebreak_id'] && !parsed['tiebreak_id'].empty? ? BSON::ObjectId.from_string(parsed['tiebreak_id']) : nil
-          }
+            tiebreak_id: parsed['tiebreak_id'] && !parsed['tiebreak_id'].empty? ? BSON::ObjectId.from_string(parsed['tiebreak_id']) : nil,
+            type: parsed['type'].try(:to_sym)
+          })
         else
-          super nil, options
+          super(nil, options)
         end
       end
 
@@ -32,7 +33,8 @@ module Mongoid
           field_name: field_name,
           direction: direction,
           include_current: include_current,
-          tiebreak_id: tiebreak_id && tiebreak_id.to_s
+          tiebreak_id: tiebreak_id && tiebreak_id.to_s,
+          type: type
         }.to_json)
       end
     end

data/lib/mongoid/scroll/base_cursor.rb

@@ -1,7 +1,7 @@
 module Mongoid
   module Scroll
     class BaseCursor
-      attr_accessor :value, :tiebreak_id, :field_type, :field_name, :direction, :include_current
+      attr_accessor :value, :tiebreak_id, :field_type, :field_name, :direction, :include_current, :type
 
       def initialize(value, options = {})
         @value = value
@@ -10,17 +10,16 @@ module Mongoid
         @field_name = options[:field_name]
         @direction = options[:direction] || 1
         @include_current = options[:include_current] || false
+        @type = options[:type] || :next
+
+        raise Mongoid::Scroll::Errors::UnsupportedTypeError.new(type: @type) unless %i[previous next].include?(@type)
       end
 
       def criteria
         mongo_value = value.class.mongoize(value) if value
         cursor_criteria = { field_name => { compare_direction => mongo_value } } if mongo_value
         tiebreak_criteria = { field_name => mongo_value, :_id => { tiebreak_compare_direction => tiebreak_id } } if mongo_value && tiebreak_id
-        cursor_selector = if Mongoid::Compatibility::Version.mongoid6_or_newer?
-                            Mongoid::Criteria::Queryable::Selector.new
-                          else
-                            Origin::Selector.new
-                          end
+        cursor_selector = Mongoid::Criteria::Queryable::Selector.new
         cursor_selector['$or'] = [cursor_criteria, tiebreak_criteria].compact if cursor_criteria || tiebreak_criteria
         cursor_selector.__evolve_object_id__
       end
@@ -69,8 +68,7 @@ module Mongoid
         return nil unless value
 
         case field_type.to_s
-        when 'BSON::ObjectId' then value.to_s
-        when 'String' then value.to_s
+        when 'BSON::ObjectId', 'String' then value.to_s
         when 'Date' then Time.utc(value.year, value.month, value.day).to_i
         when 'DateTime', 'Time' then value.utc.to_f.round(3)
         when 'Float' then value.to_f
@@ -86,20 +84,23 @@ module Mongoid
             field_type: field_type.to_s,
             field_name: field_name.to_s,
             direction: options[:direction] || 1,
-            include_current: options[:include_current] || false
+            include_current: options[:include_current] || false,
+            type: options[:type].try(:to_sym) || :next
           }
         elsif options && (field = options[:field])
           {
             field_type: field.type.to_s,
             field_name: field.name.to_s,
             direction: options[:direction] || 1,
-            include_current: options[:include_current] || false
+            include_current: options[:include_current] || false,
+            type: options[:type].try(:to_sym) || :next
           }
         end
       end
 
       def compare_direction
-        direction == 1 ? '$gt' : '$lt'
+        dir = type == :previous ? -direction : direction
+        dir == 1 ? '$gt' : '$lt'
       end
 
       def tiebreak_compare_direction

data/lib/mongoid/scroll/cursor.rb

@@ -4,20 +4,20 @@ module Mongoid
       def initialize(value = nil, options = {})
         options = extract_field_options(options)
         raise ArgumentError.new 'Missing options[:field_name] and/or options[:field_type].' unless options
+
         if value
           parts = value.split(':') if value
-          unless parts && parts.length >= 2
-            raise Mongoid::Scroll::Errors::InvalidCursorError.new(cursor: value)
-          end
+          raise Mongoid::Scroll::Errors::InvalidCursorError.new(cursor: value) unless parts && parts.length >= 2
+
           value = parse_field_value(
             options[:field_type],
             options[:field_name],
             parts[0...-1].join(':')
           )
           options[:tiebreak_id] = BSON::ObjectId.from_string(parts[-1])
-          super value, options
+          super
         else
-          super nil, options
+          super(nil, options)
         end
       end
 

data/lib/mongoid/scroll/errors/base.rb

@@ -21,13 +21,13 @@ module Mongoid
           @resolution = create_resolution(key, attributes)
 
           "\nProblem:\n  #{@problem}" \
-          "\nSummary:\n  #{@summary}" \
-          "\nResolution:\n  #{@resolution}"
+            "\nSummary:\n  #{@summary}" \
+            "\nResolution:\n  #{@resolution}"
         end
 
         private
 
-        BASE_KEY = 'mongoid.scroll.errors.messages'.freeze #:nodoc:
+        BASE_KEY = 'mongoid.scroll.errors.messages'.freeze # :nodoc:
 
         # Given the key of the specific error and the options hash, translate the
         # message.
@@ -38,7 +38,7 @@ module Mongoid
         #
         # Returns a localized error message string.
         def translate(key, options)
-          ::I18n.translate("#{BASE_KEY}.#{key}", **{ locale: :en }.merge(options)).strip
+          ::I18n.translate("#{BASE_KEY}.#{key}", locale: :en, **options).strip
         end
 
         # Create the problem.

data/lib/mongoid/scroll/errors/mismatched_sort_fields_error.rb

@@ -4,9 +4,7 @@ module Mongoid
       # Raised when the original sort params and the cursor sort params are different
       class MismatchedSortFieldsError < Mongoid::Scroll::Errors::Base
         def initialize(opts = {})
-          if opts[:diff] && opts[:diff].is_a?(Hash)
-            opts = opts.merge(diff: opts[:diff].keys.join(', '))
-          end
+          opts = opts.merge(diff: opts[:diff].keys.join(', ')) if opts[:diff] && opts[:diff].is_a?(Hash)
           super(compose_message('mismatched_sort_fields', opts))
         end
       end

data/lib/mongoid/scroll/errors/multiple_sort_fields_error.rb

@@ -3,9 +3,7 @@ module Mongoid
     module Errors
       class MultipleSortFieldsError < Mongoid::Scroll::Errors::Base
         def initialize(opts = {})
-          if opts[:sort] && opts[:sort].is_a?(Hash)
-            opts = opts.merge(sort: opts[:sort].keys.join(', '))
-          end
+          opts = opts.merge(sort: opts[:sort].keys.join(', ')) if opts[:sort] && opts[:sort].is_a?(Hash)
           super(compose_message('multiple_sort_fields', opts))
         end
       end

data/lib/mongoid/scroll/errors/unsupported_type_error.rb

@@ -0,0 +1,11 @@
+module Mongoid
+  module Scroll
+    module Errors
+      class UnsupportedTypeError < Mongoid::Scroll::Errors::Base
+        def initialize(opts = {})
+          super(compose_message('unsupported_type', opts))
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/scroll/errors.rb

@@ -6,3 +6,4 @@ require 'mongoid/scroll/errors/invalid_cursor_error'
 require 'mongoid/scroll/errors/invalid_base64_cursor_error'
 require 'mongoid/scroll/errors/no_such_field_error'
 require 'mongoid/scroll/errors/unsupported_field_type_error'
+require 'mongoid/scroll/errors/unsupported_type_error'

data/lib/mongoid/scroll/version.rb

@@ -1,5 +1,5 @@
 module Mongoid
   module Scroll
-    VERSION = '1.0.1'.freeze
+    VERSION = '2.0.1'.freeze
   end
 end

data/lib/mongoid-scroll.rb

@@ -3,7 +3,6 @@ require 'i18n'
 I18n.load_path << File.join(File.dirname(__FILE__), 'config', 'locales', 'en.yml')
 
 require 'mongoid'
-require 'mongoid-compatibility'
 require 'mongoid/scroll/version'
 require 'mongoid/scroll/errors'
 require 'mongoid/scroll/base_cursor'
@@ -11,5 +10,5 @@ require 'mongoid/scroll/cursor'
 require 'mongoid/scroll/base64_encoded_cursor'
 require 'mongoid/criteria/scrollable/fields'
 require 'mongoid/criteria/scrollable/cursors'
-require 'mongo/scrollable' if Object.const_defined?(:Mongo)
+require 'mongoid/criteria/scrollable/iterator'
 require 'mongoid/criteria/scrollable'

data/mongoid-scroll.gemspec

@@ -1,4 +1,4 @@
-$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+$LOAD_PATH.push File.expand_path('lib', __dir__)
 require 'mongoid/scroll/version'
 
 Gem::Specification.new do |s|
@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.homepage = 'http://github.com/mongoid/mongoid-scroll'
   s.licenses = ['MIT']
   s.summary = 'Mongoid extensions to enable infinite scroll.'
-  s.add_dependency 'mongoid', '>= 3.0'
-  s.add_dependency 'mongoid-compatibility'
   s.add_dependency 'i18n'
+  s.add_dependency 'mongoid', '>= 6.0'
+  s.metadata['rubygems_mfa_required'] = 'true'
 end