💎 Add :typesense_rails paginator (See typesense/typesense-rails#17)

Author: ddnexus

README.md

@@ -124,12 +124,14 @@ search           = Product.pagy_search(params[:q])
 @pagy, @response = pagy(:elasticsearch_rails, search)
 @pagy, @results  = pagy(:meilisearch, search)
 @pagy, @results  = pagy(:searchkick, search)
+@pagy, @results  = pagy(:typesense_rails, search)
 
 # Or get pagy from paginated results:
 @results = Product.search(params[:q])
 @pagy    = pagy(:elasticsearch_rails, @results)
 @pagy    = pagy(:meilisearch, @results)
 @pagy    = pagy(:searchkick, @results)
+@pagy    = pagy(:typesense_rails, @results)
 ```
 
 ##### Calendar pagination

docs/guides/chose_wisely.md

@@ -106,7 +106,7 @@ This hybrid technique filters by a specific time period (Year, Month, Day, etc.)
 
 ### Search platforms
 
-Pagy supports Elasticsearch, Meilisearch, and Searchkick.
+Pagy supports Elasticsearch, Meilisearch, Searchkick, and TypesenseRails.
 
 These paginators get the count, limit and results provided by the search platform. Pagy acts as an interface to these underlying gems, using the `:offset` paginator (whithout the shortcomings).
 
@@ -116,6 +116,7 @@ These paginators get the count, limit and results provided by the search platfor
 - [:icon-search: :elasticsearch_rails](../toolbox/paginators/elasticsearch_rails.md) 
 [:icon-search: :meilisearch](../toolbox/paginators/meilisearch.md) 
 [:icon-search: :searchkick](../toolbox/paginators/searchkick.md)
+[:icon-search: :typesense_rails](../toolbox/paginators/typesense_rails.md)
   - :icon-check-circle-24: **Best for**: Search Results
   - :icon-thumbsup-24:     **Pros**: Leverages the engine's native response
   - :icon-thumbsdown-24:   **Cons**: None (simple interface with search platform gems)

docs/guides/how-to.md

@@ -204,8 +204,9 @@ You can send selected `@pagy` instance data to the client as JSON using the [dat
 See these paginators:
 
 - [elasticsearch_rails](../toolbox/paginators/elasticsearch_rails)
-- [searchkick](../toolbox/paginators/searchkick)
 - [meilisearch](../toolbox/paginators/meilisearch)
+- [searchkick](../toolbox/paginators/searchkick)
+- [typesense_rails](../toolbox/paginators/typesense_rails)
 
 ==- Paginate by date
 

docs/toolbox/paginators/typesense_rails.md

@@ -0,0 +1,72 @@
+---
+label: :typesense_rails
+icon: search
+order: 20
+categories:
+  - Paginators
+  - Search
+---
+
+#
+
+## :icon-search: :typesense_rails
+
+---
+
+`:typesense` is a paginator designed for `Typesense::Rails` results.
+
+#### Configuration
+
+Ensure `Typesense.configuration[:pagination_backend] == nil`.
+
++++ Active mode
+
+!!!success Pagy searches and paginates
+
+You use the `pagy_search` method in place of the `search` method.
+!!!
+
+```ruby Model
+extend Pagy::Search
+```
+
+```ruby Controller
+# Get the collection in one of the following ways
+search = Article.pagy_search(params[:q], to_query)
+# Paginate it
+@pagy, @response = pagy(:typesense_rails, search, **options)
+```
+
++++ Passive Mode
+
+!!!success You search and paginate
+
+Pagy creates its object out of your result.
+!!!
+
+```ruby Controller
+# Standard results (already paginated)
+@results = Model.search(params[:q], to_query, { per_page: 10, page: 10, ...})
+# Get the pagy object out of it
+@pagy    = pagy(:typesense_rails, @results, **options)
+```
+
++++
+
+!!!
+
+Search paginators don't query a DB, but use the same positional technique as [:offset](offset.md) paginators, with shared options and readers.
+!!!
+
+==- Options
+
+- `search_method: :my_search`
+  - Customize the name of the search method (default `:search`)
+
+See also [Offset Options](offset#options)
+
+==- Readers
+
+See [Offset Readers](offset#readers)
+
+===

gem/lib/pagy.rb

@@ -28,6 +28,7 @@ class Pagy
   autoload :ElasticsearchRails, path.join('classes/offset/search')
   autoload :Meilisearch,        path.join('classes/offset/search')
   autoload :Searchkick,         path.join('classes/offset/search')
+  autoload :TypesenseRails,     path.join('classes/offset/search')
   autoload :Keyset,             path.join('classes/keyset/keyset')
 
   OPTIONS = {} # rubocop:disable Style/MutableConstant

gem/lib/pagy/classes/offset/search.rb

@@ -29,4 +29,6 @@ class Meilisearch < SearchBase
   end
 
   class Searchkick < SearchBase; end
+
+  class TypesenseRails < SearchBase; end
 end

gem/lib/pagy/toolbox/paginators/method.rb

@@ -11,7 +11,8 @@ class Pagy
                  calendar:            :CalendarPaginator,
                  elasticsearch_rails: :ElasticsearchRailsPaginator,
                  meilisearch:         :MeilisearchPaginator,
-                 searchkick:          :SearchkickPaginator }.freeze
+                 searchkick:          :SearchkickPaginator,
+                 typesense_rails:     :TypesenseRailsPaginator }.freeze
 
   path = Pathname.new(__dir__)
   paginators.each { |symbol, name| autoload name, path.join(symbol.to_s) }

gem/lib/pagy/toolbox/paginators/typesense_rails.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../../modules/searcher'
+
+class Pagy
+  module TypesenseRailsPaginator
+    module_function
+
+    # Paginate from the search object
+    def paginate(search, options)
+      if search.is_a?(Search::Arguments) # Active mode
+
+        Searcher.wrap(search, options) do
+          model, arguments, search_options = search
+
+          search_options[:per_page] = options[:limit]
+          search_options[:page]     = options[:page]
+
+          method          = options[:search_method] || TypesenseRails::DEFAULT[:search_method]
+          results         = model.send(method, *arguments, search_options)
+          options[:count] = results.raw_answer['found']
+
+          [TypesenseRails.new(**options), results]
+        end
+
+      else # Passive mode
+        options[:limit] = search.raw_answer['request_params']['per_page']
+        options[:page]  = search.raw_answer['page']
+        options[:count] = search.raw_answer['found']
+
+        TypesenseRails.new(**options)
+      end
+    end
+  end
+end

test/unit/mocks/typesense_rails.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'pagy/classes/offset/search'
+
+module MockTypesenseRails
+  RESULTS = {
+    '*' => (1..1000).map { |n| "doc-#{n}" },
+    'a' => (1..1000).map { |n| "a-#{n}" },
+    'b' => (1..1000).map { |n| "b-#{n}" }
+  }.freeze
+
+  class Results
+    attr_reader :term, :options
+
+    def initialize(term, options = {})
+      @term    = term
+      @options = options
+      @page    = options[:page] || 1
+      @limit   = options[:per_page] || 20
+    end
+
+    def raw_answer
+      all_results = RESULTS[@term] || []
+      offset      = (@page - 1) * @limit
+      hits        = all_results[offset, @limit] || []
+
+      {
+        'found'          => all_results.size,
+        'page'           => @page,
+        'request_params' => { 'per_page' => @limit },
+        'hits'           => hits
+      }
+    end
+  end
+
+  class Model
+    extend Pagy::Search
+
+    def self.search(term, _query_by = nil, options = {})
+      Results.new(term, options)
+    end
+  end
+end

test/unit/pagy/toolbox/paginators/typesense_rails_test.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'unit/test_helper'
+require 'pagy/toolbox/paginators/typesense_rails'
+require 'mocks/app'
+require 'mocks/typesense_rails'
+
+describe 'Pagy::TypesenseRailsPaginator' do
+  let(:app) { MockApp.new }
+
+  describe '#paginate' do
+    describe 'Active Mode (pagy_search)' do
+      it 'paginates with defaults' do
+        args = MockTypesenseRails::Model.pagy_search('a', 'name')
+
+        pagy, results = app.pagy(:typesense_rails, args, page: 1, limit: 10)
+
+        _(pagy).must_be_kind_of Pagy::TypesenseRails
+        _(pagy.count).must_equal 1000
+        _(pagy.page).must_equal 1
+        _(pagy.limit).must_equal 10
+        _(results).must_be_kind_of MockTypesenseRails::Results
+        _(results.raw_answer['hits'].first).must_equal 'a-1'
+        _(results.raw_answer['hits'].size).must_equal 10
+      end
+
+      it 'paginates with custom options' do
+        args = MockTypesenseRails::Model.pagy_search('b', 'name')
+
+        pagy, results = app.pagy(:typesense_rails, args, page: 2, limit: 20)
+
+        _(pagy.page).must_equal 2
+        _(pagy.limit).must_equal 20
+        _(results.raw_answer['page']).must_equal 2
+        _(results.raw_answer['hits'].first).must_equal 'b-21'
+        _(results.raw_answer['hits'].last).must_equal 'b-40'
+      end
+    end
+
+    describe 'Passive Mode (Results object)' do
+      it 'paginates from existing results' do
+        results = MockTypesenseRails::Results.new('a', page: 3, per_page: 15)
+
+        pagy = app.pagy(:typesense_rails, results)
+
+        _(pagy).must_be_kind_of Pagy::TypesenseRails
+        _(pagy.page).must_equal 3
+        _(pagy.limit).must_equal 15
+        _(pagy.count).must_equal 1000
+      end
+    end
+  end
+end