typesensual 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc8cd0a5b5f24e00ac86366e5f12f3e717314791ed421a1864b94204e42445af
-  data.tar.gz: 226590b10f36c0bb4f4ea583d9080b153629e5359189f4cd2f360da1891cb9b4
+  metadata.gz: d9fa2afbbada09440e9505cc8f26a67214ae8400489174d396afc9d10b2c2c5a
+  data.tar.gz: 92efdf121fd63031670750d0b3fc200343df494d6a7192f298d267d635aef2a7
 SHA512:
-  metadata.gz: 0cc692009e32572a18a8506abd5125ce3841f6c444ba15b36ed7a5b07afb095ffb03199aece5f755a8c2b72d1df135429daccf956474df9f92f5be51dc99dab0
-  data.tar.gz: 3c7f8c3081de258e431b9135cc671a6bda03113804e6e48693616f0f492502fb4594ec81e913d708a1af8b6c2c1135b5527dd88f4e8b8541ba7d162b76e882b6
+  metadata.gz: f9994f3f96fb7b84fe5360cb676f9c4cc049f1e3265d7be1f336cb2a673872672a899d71ff6f3402efffbbc277baf03923c70041b0e290f853b05fbe7f504e03
+  data.tar.gz: a67ae00d0e893f3fa57f70838b893959c25447efaf33e7d735b2d818407beec71b96e3aacb1cc62f8846a0bfa342a89706827d3a08e87fa2a102e2118ef8f6f7

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    typesensual (0.5.0)
+    typesensual (1.0.0)
       activesupport (>= 6.1.5)
       paint (>= 2.0.0)
       typesense (>= 0.13.0)
@@ -15,18 +15,20 @@ GEM
       minitest (>= 5.1)
       tzinfo (~> 2.0)
     ast (2.4.2)
+    bigdecimal (3.1.7)
     commonmarker (0.23.10)
-    concurrent-ruby (1.2.2)
+    concurrent-ruby (1.2.3)
     diff-lcs (1.5.0)
     docile (1.4.0)
     ethon (0.16.0)
       ffi (>= 1.15.0)
-    ffi (1.15.5)
+    ffi (1.16.3)
     i18n (1.14.1)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
-    minitest (5.20.0)
-    oj (3.16.1)
+    minitest (5.22.3)
+    oj (3.16.3)
+      bigdecimal (>= 3.0)
     paint (2.3.0)
     parallel (1.23.0)
     parser (3.2.2.1)

data/README.md

@@ -117,13 +117,8 @@ Once you have defined your index, you can load data into it and update the alias
 indexed data. Typesensual provides rake tasks for this purpose if you use ActiveRecord:
 
 ```console
-$ bundle exec rake typesensual:load[MoviesIndex,Movie]
-==> Indexing Movie into MoviesIndex (Version 1690076097)
-
-$ bundle exec rake typesensual:update_alias[MoviesIndex,1690076097]
-==> Alias for MoviesIndex
-Old: None (N/A)
-New: 1690076097 (2023-05-07 18:01:37)
+$ bundle exec rake typesensual:reindex[MoviesIndex,Movie]
+==> Reindexing Movie into MoviesIndex (Version 1690076097)
 ```
 
 Otherwise you can do similar to the following:

data/lib/tasks/typesensual.rake

@@ -24,6 +24,14 @@ namespace :typesensual do
     )
   end
 
+  desc 'Index all records from a model into a new version then update the alias of the index'
+  task :reindex, %i[index model] => :environment do |_, args|
+    Typesensual::RakeHelper.reindex(
+      index: args[:index],
+      model: args[:model]
+    )
+  end
+
   desc 'Delete a version of an index'
   task :drop_version, %i[index version] => :environment do |_, args|
     Typesensual::RakeHelper.drop_version(

data/lib/typesensual/collection.rb

@@ -32,6 +32,7 @@ class Typesensual
     #     * `num_documents` [Integer] the number of documents in the collection
     #     * `symbols_to_index` [String] the symbols to index
     #     * `token_separators` [String] the token separators
+    #
     # @overload initialize(name)
     #   Initialize a new collection, loading info from Typesense
     #

data/lib/typesensual/index.rb

@@ -96,8 +96,6 @@ class Typesensual
     # @return [Collection] the collection that the alias points to
     def self.collection
       @collection ||= Collection.new(alias_name)
-    rescue Typesense::Error::ObjectNotFound
-      nil
     end
 
     # Define the schema for the collection

data/lib/typesensual/rake_helper.rb

@@ -68,6 +68,35 @@ class Typesensual
         end
       end
 
+      # Index all records from a model into a new collection, then update the alias to point to it.
+      #
+      # @param index [String] The name of the index to index into
+      # @param model [String] The name of the model to index from
+      # @example
+      #   take typesensual:reindex[FooIndex,Foo]
+      def reindex(index:, model:, output: $stdout)
+        index = index.safe_constantize
+        model = model.safe_constantize
+
+        collection = index.create!
+        output.printf(
+          Paint["==> Reindexing %<model>s into %<index>s (Version %<version>s)\n", :bold],
+          model: model.name,
+          index: index.name,
+          version: collection.version
+        )
+        failures = index.index_many(
+          model.ids,
+          collection: collection
+        )
+
+        index.update_alias!(collection)
+
+        failures.each do |failure|
+          output.puts(failure.to_json)
+        end
+      end
+
       # Update the alias for an index to point to a specific version
       #
       # @param index [String] The name of the index to update
@@ -76,7 +105,11 @@ class Typesensual
       #   rake typesensual:update_alias[FooIndex,1]
       def update_alias(index:, version:, output: $stdout)
         index = index.safe_constantize
-        old_coll = index.collection
+        old_coll = begin
+          index.collection
+        rescue Typesense::Error::ObjectNotFound
+          nil
+        end
         new_coll = index.collection_for(version: version)
 
         unless new_coll

data/lib/typesensual/search/facet.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Typesensual
+  class Search
+    # Represents a facet returned with search results
+    class Facet
+      attr_reader :key
+
+      def initialize(key, facet)
+        @key = key
+        @facet = facet
+      end
+
+      def count
+        @facet['count']
+      end
+
+      def value
+        @facet['value']
+      end
+
+      def highlighted
+        @facet['highlighted']
+      end
+    end
+  end
+end

data/lib/typesensual/search/results.rb

@@ -3,8 +3,9 @@
 class Typesensual
   class Search
     class Results
-      def initialize(results)
+      def initialize(results, search:)
         @results = results
+        @search = search
       end
 
       def hits
@@ -43,12 +44,22 @@ class Typesensual
         current_page + 1 unless last_page?
       end
 
+      def per_page
+        @results['request_params']['per_page'].to_i
+      end
+
       def search_time_ms
         @results['search_time_ms']
       end
 
       def total_pages
-        (@results['found'] / @results['per_page'].to_f).ceil
+        (@results['found'] / per_page.to_f).ceil
+      end
+
+      def facets
+        @search.facet_keys.zip(@results['facet_counts']).to_h do |(key, facet)|
+          [key, Facet.new(key, facet)]
+        end
       end
     end
   end

data/lib/typesensual/search.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'typesensual/search/facet'
 require 'typesensual/search/hit'
 require 'typesensual/search/grouped_hit'
 require 'typesensual/search/results'
@@ -8,6 +9,11 @@ class Typesensual
   class Search
     include StateHelpers
 
+    # The keys of all the facets (used for re-keying the facets in the results)
+    # @return [Array<String>]
+    # @!visibility private
+    attr_reader :facet_keys
+
     # Initialize a new search object for a collection
     #
     # @param collection [Typesensual::Collection] the Typesensual collection object
@@ -21,6 +27,9 @@ class Typesensual
       @sort_by = []
       @facet_by = []
       @facet_query = []
+      # this is just used by the Results class to determine names for facets
+      @facet_keys = []
+      @facet_return_parent = []
       @include_fields = []
       @exclude_fields = []
       @group_by = []
@@ -41,12 +50,14 @@ class Typesensual
 
     # Set the number of results to return per page
     # @param count [Integer] the number of results to return per page
+    # @return [self]
     def per(count)
       set(per_page: count)
     end
 
     # Set the page number to return
     # @param number [Integer] the page number to return
+    # @return [self]
     def page(number)
       set(page: number)
     end
@@ -55,9 +66,12 @@ class Typesensual
     # @param filter [String, Symbol, Hash<String, Symbol>] the filter to add. If a hash is
     #   provided, the keys are the fields and the values are the values to filter by. If a
     #   string is provided, it is added directly as a filter. All filters are ANDed together.
+    # @return [self]
     def filter(filter)
       if filter.is_a?(Hash)
         @filter_by += filter.map { |key, value| "#{key}:#{value}" }
+      elsif filter.is_a?(Array)
+        @filter_by += filter.map(&:to_s)
       else
         @filter_by << filter.to_s
       end
@@ -68,6 +82,7 @@ class Typesensual
     # @param value [String, Symbol, Hash<String, Symbol>] the sort to add to the search. If
     #   a hash is provided, the keys are the fields and the values are the directions to sort.
     #   If a string is provided, it is added directly as a sort.
+    # @return [self]
     def sort(value)
       if value.is_a?(Hash)
         @sort_by += value.map { |key, direction| "#{key}:#{direction}" }
@@ -77,20 +92,108 @@ class Typesensual
       self
     end
 
-    # Add a field to facet to the seach
-    # @param facets [String, Symbol, Array<String, Symbol>, Hash<String, Symbol>] the fields to
-    #   facet by. If a hash is provided, the keys are the fields and the values are strings to
-    #   query each facet. If an Array is provided, the values are fields to facet by. If a string
-    #   is provided, it is added directly as a facet.
+    # Add a field to facet to the search
+    # @return [self]
+    # @overload facet(facets: Symbol, String, Array)
+    #   Basic faceting with just a list of fields
+    #   @param facets [String, Symbol, Array<String, Symbol>] the fields to facet on
+    #   @example Facet by type
+    #     # Generates `facet_by=type`
+    #     .facet(:type)
+    #   @example Facet by type and year
+    #     # Generates `facet_by=type,year`
+    #     .facet(['type', 'year'])
+    #
+    # @overload facet(facets: Hash)
+    #   Advanced faceting with sort, ranges, return_parent, and query
+    #   @param facets [Hash{String, Symbol => String}, Hash{String, Symbol => Hash}] the fields to
+    #     facet by and their configuration. If a string is passed as the value, it is used to query
+    #     the facet. If a hash is passed, each value is used to configure the facet using the
+    #     following options:
+    #
+    #     * **`facets[key][:sort]`** (`String, Symbol, Hash{String, Symbol => Symbol}`) — the
+    #       field to sort by, and the direction to sort it in. If you pass a string or symbol, it is
+    #       used as the sort direction for alphabetical sorting. Typesense only supports sorting by
+    #       a single field, and passing more than one field will raise an ArgumentError.
+    #     * **`facets[key][:ranges]`** (`Hash{String, Symbol => Range, Array}`) — the ranges to
+    #       facet by, for numerical facets. For each key, you can pass a Range or an Array with two
+    #       elements. Ranges MUST be end-exclusive and Arrays MUST have two elements, or else an
+    #       ArgumentError will be raised.
+    #     * **`facets[key][:return_parent]`** (`Boolean`) — if true, the parent object of the field
+    #       will be returned, which can be useful for nested fields.
+    #     * **`facets[key][:query]`** (`String`) — the query to facet by, equivalent to passing a
+    #       string instead of a hash.
+    #   @example Facet by category, sorted by category size, and return the parent
+    #     # Generates `facet_by=categories.id(categories.size:desc)&facet_return_parent=categories.id`
+    #     .facet('categories.id' => { sort: { 'categories.size' => :desc }, return_parent: true })
+    #   @example Facet by decade
+    #     # Generates `facet_by=year(1990s:[1990,2000],2000s:[2000,2010])`
+    #     .facet('year' => { ranges: { '1990s' => 1990...2000, '2000s' => [2000, 2010] })
     def facet(facets)
       if facets.is_a?(Hash)
         facets.each do |key, value|
-          @facet_by << key.to_s
-          @facet_query << "#{key}:#{value}" if value
+          @facet_keys << key.to_s
+          if value.is_a?(String)
+            # Basic facet searching with a string query
+            @facet_by << key.to_s
+            @facet_query << "#{key}:#{value}" if value
+          elsif value.is_a?(Hash)
+            # Advanced faceting with sort, ranges, return_parent, and query
+            facet_string = key.to_s
+            facet_params = {}
+
+            # Sort parameters
+            case value[:sort]
+            when Hash
+              raise ArgumentError, 'Facet sort_by must have one key' if value[:sort].count != 1
+              sort_key, sort_direction = value[:sort].first
+              facet_params[:sort_by] = "#{sort_key}:#{sort_direction}"
+            when Symbol
+              facet_params[:sort_by] = "_alpha:#{value[:sort]}"
+            when String
+              facet_params[:sort_by] = value[:sort]
+            when nil
+              nil
+            else
+              raise ArgumentError, 'Facet sort_by must be a Hash, Symbol, or String'
+            end
+
+            # Range parameters
+            if value[:ranges].is_a?(Hash)
+              ranges = value[:ranges].transform_values do |range|
+                case range
+                when Range
+                  raise ArgumentError, 'Facet ranges must exclude end' unless range.exclude_end?
+                  "[#{range.begin},#{range.end}]"
+                when Array
+                  raise ArgumentError, 'Facet ranges must have two elements' unless range.count == 2
+                  "[#{range.first},#{range.last}]"
+                else
+                  raise ArgumentError, 'Facet ranges must be a Range or Array'
+                end
+              end
+              facet_params.merge!(ranges)
+            elsif !value[:ranges].nil?
+              raise ArgumentError, 'Facet ranges must be a Hash'
+            end
+
+            # Format facet params
+            unless facet_params.empty?
+              facet_string += "(#{facet_params.map { |k, v| "#{k}:#{v}" }.join(',')})"
+            end
+
+            @facet_return_parent << key.to_s if value[:return_parent]
+            @facet_query << "#{key}:#{value[:query]}" if value[:query]
+            @facet_by << facet_string
+          else
+            @facet_by << key.to_s
+          end
         end
       elsif facets.is_a?(Array)
+        @facet_keys += facets.map(&:to_s)
         @facet_by += facets.map(&:to_s)
       else
+        @facet_keys << facets.to_s
         @facet_by << facets.to_s
       end
       self
@@ -98,6 +201,7 @@ class Typesensual
 
     # Add fields to include in the search result documents
     # @param fields [String, Symbol, Array<String, Symbol>] the fields to include
+    # @return [self]
     def include_fields(*fields)
       @include_fields += fields.map(&:to_s)
       self
@@ -105,11 +209,15 @@ class Typesensual
 
     # Add fields to exclude from the search result documents
     # @param fields [String, Symbol, Array<String, Symbol>] the fields to exclude
+    # @return [self]
     def exclude_fields(*fields)
       @exclude_fields += fields.map(&:to_s)
       self
     end
 
+    # Add fields to group the search results by
+    # @param fields [String, Symbol, Array<String, Symbol>] the fields to group by
+    # @return [self]
     def group_by(*fields)
       @group_by += fields.map(&:to_s)
       self
@@ -117,6 +225,7 @@ class Typesensual
 
     # Set additional parameters to pass to the search
     # @param values [Hash] the parameters to set
+    # @return [self]
     def set(values)
       @params.merge!(values)
       self
@@ -133,6 +242,7 @@ class Typesensual
         query_by_weights: @query_by_weights&.join(','),
         sort_by: @sort_by&.join(','),
         facet_by: @facet_by&.join(','),
+        facet_return_parent: @facet_return_parent&.join(','),
         facet_query: @facet_query&.join(','),
         include_fields: @include_fields&.join(','),
         exclude_fields: @exclude_fields&.join(','),
@@ -143,7 +253,9 @@ class Typesensual
     # Load the results from the search query
     # @return [Typesensual::Search::Results] the results of the search
     def load
-      Results.new(@collection.typesense_collection.documents.search(query))
+      result = self.class.multi(self).first
+      raise result if result.is_a?(StandardError)
+      result
     end
 
     # Perform multiple searches in one request. There are two variants of this method, one which
@@ -179,7 +291,9 @@ class Typesensual
 
       # Wrap our results in Result objects
       wrapped_results = results['results'].map do |result|
-        Results.new(result)
+        exception = exception_for(result) if result['code']
+
+        exception || Results.new(result, search: self)
       end
 
       # If we're doing named searches, re-key the results
@@ -189,5 +303,19 @@ class Typesensual
         wrapped_results
       end
     end
+
+    # Roughly duplicates the logic from Typesense::ApiCall#custom_exception_klass_for
+    private_class_method def self.exception_for(result)
+      case result['code']
+      when 400 then Typesense::Error::RequestMalformed.new(result['message'])
+      when 401 then Typesense::Error::RequestUnauthorized.new(result['message'])
+      when 404 then Typesense::Error::ObjectNotFound.new(result['message'])
+      when 409 then Typesense::Error::ObjectAlreadyExists.new(result['message'])
+      when 422 then Typesense::Error::ObjectUnprocessable.new(result['message'])
+      when 500..599 then Typesense::Error::ServerError.new(result['message'])
+      when 100..399, nil then nil
+      else Typesense::Error.new(result['message'])
+      end
+    end
   end
 end

data/lib/typesensual/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Typesensual
-  VERSION = '0.5.0'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typesensual
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Emma Lejeck
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-09 00:00:00.000000000 Z
+date: 2024-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -52,9 +52,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.13.0
-description: 
+description:
 email:
-- nuck@kitsu.io
+- nuck@kitsu.app
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -80,6 +80,7 @@ files:
 - lib/typesensual/rake_helper.rb
 - lib/typesensual/schema.rb
 - lib/typesensual/search.rb
+- lib/typesensual/search/facet.rb
 - lib/typesensual/search/grouped_hit.rb
 - lib/typesensual/search/hit.rb
 - lib/typesensual/search/results.rb
@@ -93,7 +94,7 @@ metadata:
   source_code_uri: https://github.com/hummingbird-me/typesensual
   changelog_uri: https://github.com/hummingbird-me/typesensual/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -109,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.3.26
-signing_key: 
+signing_key:
 specification_version: 4
 summary: A simple, sensual wrapper around Typesense for Ruby
 test_files: []