search-engine-for-typesense 30.1.0 → 30.1.1

data/lib/search_engine/config.rb

@@ -305,13 +305,13 @@ module SearchEngine
     # Controls validation rules and list limits.
     class CurationConfig
       # @return [Integer] maximum number of pinned IDs allowed (default: 50)
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/curation
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/curation
       attr_accessor :max_pins
       # @return [Integer] maximum number of hidden IDs allowed (default: 200)
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/curation
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/curation
       attr_accessor :max_hidden
       # @return [Regexp] allowed curated ID pattern (used for IDs and override tags)
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/curation
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/curation
       attr_accessor :id_regex
 
       def initialize
@@ -393,7 +393,7 @@ module SearchEngine
 
     # Expose presets configuration.
     # @return [SearchEngine::Config::PresetsConfig]
-    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/presets
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/presets
     def presets
       @presets ||= PresetsConfig.new
     end
@@ -403,7 +403,7 @@ module SearchEngine
     # Normalizes values on assignment.
     # @param value [Object]
     # @return [void]
-    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/presets#config-default-preset
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/presets#config-default-preset
     def presets=(value)
       cfg = presets
       if value.is_a?(PresetsConfig)

data/lib/search_engine/console_helpers.rb

@@ -38,7 +38,7 @@ module SearchEngine
       # @example
       #   SE.q('milk').per(5)
       #   SE.q.where(category: 'dairy')
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/dx
       def q(query = nil, **opts)
         model = default_model!
         rel = model.all
@@ -91,7 +91,7 @@ module SearchEngine
           raise ArgumentError,
                 'No default model configured. Set SearchEngine.config.default_console_model ' \
                 'or define a single SearchEngine::Base model. See ' \
-                'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx#generators--console-helpers.'
+                'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/dx#generators--console-helpers.'
         end
 
         uniq_klasses = mapping.values.uniq
@@ -100,7 +100,7 @@ module SearchEngine
         names = uniq_klasses.map { |k| k.respond_to?(:name) && k.name ? k.name : k.to_s }.sort
         raise ArgumentError,
               "Ambiguous default model: #{names.join(', ')}. Set SearchEngine.config.default_console_model. " \
-              'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx#generators--console-helpers.'
+              'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/dx#generators--console-helpers.'
       end
 
       def resolve_model_class(value)
@@ -121,7 +121,7 @@ module SearchEngine
       rescue NameError
         raise ArgumentError,
               "Unknown model constant #{name.inspect} for default_console_model. Ensure it's loaded. " \
-              'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx#generators--console-helpers.'
+              'See https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/dx#generators--console-helpers.'
       end
 
       private_class_method :resolve_model_class

data/lib/search_engine/dispatcher.rb

@@ -20,14 +20,14 @@ module SearchEngine
       unless klass.is_a?(Class)
         raise SearchEngine::Errors::InvalidParams.new(
           'klass must be a Class',
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#troubleshooting',
           details: { arg: :klass }
         )
       end
       unless klass.ancestors.include?(SearchEngine::Base)
         raise SearchEngine::Errors::InvalidParams.new(
           'klass must inherit from SearchEngine::Base',
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer#troubleshooting',
           details: { klass: klass.to_s }
         )
       end

data/lib/search_engine/dsl/parser.rb

@@ -189,7 +189,7 @@ module SearchEngine
         unless m
           raise SearchEngine::Errors::InvalidOperator.new(
             "invalid template '#{template}'. Supported: =, !=, >, >=, <, <=, IN, NOT IN, MATCHES, PREFIX",
-            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/query-dsl#troubleshooting',
+            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
             details: { template: template }
           )
         end
@@ -272,7 +272,7 @@ module SearchEngine
 
         raise SearchEngine::Errors::InvalidOperator.new(
           "expected #{needed} args for #{needed} placeholders in template '#{template}', got #{provided}.",
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/query-dsl#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
           details: { needed: needed, provided: provided, template: template }
         )
       end
@@ -337,7 +337,7 @@ module SearchEngine
 
         raise SearchEngine::Errors::InvalidType.new(
           invalid_type_message(field: field, klass: klass, expectation: 'a non-empty Array', got: values),
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/query-dsl#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
           details: { field: field, got_class: values.class.name }
         )
       end
@@ -394,7 +394,7 @@ module SearchEngine
 
         raise SearchEngine::Errors::InvalidType.new(
           invalid_type_message(field: nil, klass: nil, expectation: 'boolean', got: value),
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/query-dsl#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
           details: { got: value }
         )
       end
@@ -426,7 +426,7 @@ module SearchEngine
       rescue StandardError
         raise SearchEngine::Errors::InvalidType.new(
           invalid_type_message(field: field, klass: klass, expectation: 'time', got: value),
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/query-dsl#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
           details: { field: field, got: value }
         )
       end
@@ -443,7 +443,7 @@ module SearchEngine
             rescue StandardError
               raise SearchEngine::Errors::InvalidType.new(
                 invalid_type_message(field: field, klass: klass, expectation: 'integer', got: value),
-                doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/query-dsl#troubleshooting',
+                doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
                 details: { field: field, got: value }
               )
             end
@@ -452,7 +452,7 @@ module SearchEngine
           if value.is_a?(Numeric)
             raise SearchEngine::Errors::InvalidType.new(
               invalid_type_message(field: field, klass: klass, expectation: 'integer', got: value),
-              doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/query-dsl#troubleshooting',
+              doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
               details: { field: field, got: value }
             )
           end
@@ -470,7 +470,7 @@ module SearchEngine
             rescue StandardError
               raise SearchEngine::Errors::InvalidType.new(
                 invalid_type_message(field: field, klass: klass, expectation: 'numeric', got: value),
-                doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/query-dsl#troubleshooting',
+                doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#troubleshooting',
                 details: { field: field, got: value }
               )
             end
@@ -573,7 +573,7 @@ module SearchEngine
 
         raise SearchEngine::Errors::JoinNotApplied.new(
           "Call .joins(:#{assoc_name}) before filtering/sorting on #{assoc_name} fields",
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#troubleshooting',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#troubleshooting',
           details: { assoc: assoc_name, used_for: 'filtering' }
         )
       end

data/lib/search_engine/errors.rb

@@ -15,7 +15,7 @@ module SearchEngine
     # @!attribute [r] hint
     #   @return [String, nil] short actionable suggestion (no secrets)
     # @!attribute [r] doc
-    #   @return [String, nil] docs URL with optional anchor (e.g., "https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/query-dsl#operators")
+    #   @return [String, nil] docs URL with optional anchor (e.g., "https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/query-dsl#operators")
     # @!attribute [r] details
     #   @return [Object, nil] machine-readable context (JSON-serializable)
     # @!attribute [r] code
@@ -240,21 +240,21 @@ module SearchEngine
 
     # Raised when a curated ID does not match the configured pattern.
     #
-    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/curation
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/curation
     # @example
     #   raise SearchEngine::Errors::InvalidCuratedId, 'InvalidCuratedId: "foo bar" is not a valid curated ID. Expected pattern: /\A[\w\-:\.]+\z/. Try removing illegal characters.'
     class InvalidCuratedId < Error; end
 
     # Raised when pinned/hidden lists exceed configured limits after normalization.
     #
-    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/curation
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/curation
     # @example
     #   raise SearchEngine::Errors::CurationLimitExceeded, 'CurationLimitExceeded: pinned list exceeds max_pins=50 (attempted 51). Reduce inputs or raise the limit in SearchEngine.config.curation.'
     class CurationLimitExceeded < Error; end
 
     # Raised when an override tag is blank or invalid per allowed pattern.
     #
-    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/curation
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/curation
     # @example
     #   raise SearchEngine::Errors::InvalidOverrideTag, 'InvalidOverrideTag: "" is invalid. Use non-blank strings that match the allowed pattern.'
     class InvalidOverrideTag < Error; end
@@ -269,7 +269,7 @@ module SearchEngine
     #   raise SearchEngine::Errors::InvalidOption.new(
     #     'InvalidOption: tag must be a simple HTML-like token',
     #     hint: 'Use a simple tag like <em> or <mark>',
-    #     doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/highlighting#options'
+    #     doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/highlighting#options'
     #   )
     class InvalidOption < Error; end
 
@@ -282,7 +282,7 @@ module SearchEngine
     #   raise SearchEngine::Errors::HitLimitExceeded.new(
     #     'HitLimitExceeded: 12000 results exceed max=10000',
     #     hint: 'Increase `validate_hits!(max:)` or narrow your filters.',
-    #     doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/hit-limits#validation',
+    #     doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/hit-limits#validation',
     #     details: { total_hits: 12_000, max: 10_000, collection: 'products' }
     #   )
     class HitLimitExceeded < Error; end

data/lib/search_engine/filters/sanitizer.rb

@@ -22,31 +22,13 @@ module SearchEngine
       # @return [String]
       def quote(value)
         case value
-        when NilClass
-          'null'
-        when TrueClass
-          'true'
-        when FalseClass
-          'false'
-        when Numeric
-          value.to_s
         when String
           %("#{escape_string(value)}")
-        when Time
-          %("#{value.iso8601}")
-        when DateTime
-          %("#{value.iso8601}")
-        when Date
-          %("#{value.iso8601}")
         when Array
           elements = value.flatten(1).map { |el| quote(el) }
           "[#{elements.join(', ')}]"
         else
-          if value.respond_to?(:to_time)
-            %("#{value.to_time.iso8601}")
-          else
-            %("#{escape_string(value.to_s)}")
-          end
+          quote_non_string(value)
         end
       end
 
@@ -64,37 +46,14 @@ module SearchEngine
         return quote(value) if value.is_a?(Array)
 
         case value
-        when NilClass
-          'null'
-        when TrueClass
-          'true'
-        when FalseClass
-          'false'
-        when Numeric
-          value.to_s
         when String, Symbol
           str = value.to_s
           lc = str.strip.downcase
-          # Avoid ambiguity with special literals when user passes them as strings
           return %("#{escape_string(str)}") if %w[true false null].include?(lc)
 
-          if safe_bare_string?(str)
-            str
-          else
-            %("#{escape_string(str)}")
-          end
-        when Time
-          %("#{value.iso8601}")
-        when DateTime
-          %("#{value.iso8601}")
-        when Date
-          %("#{value.iso8601}")
+          safe_bare_string?(str) ? str : %("#{escape_string(str)}")
         else
-          if value.respond_to?(:to_time)
-            %("#{value.to_time.iso8601}")
-          else
-            %("#{escape_string(value.to_s)}")
-          end
+          quote_non_string(value)
         end
       end
 
@@ -160,6 +119,27 @@ module SearchEngine
         count
       end
 
+      # Shared quoting logic for non-String, non-Array values.
+      # @param value [Object]
+      # @return [String]
+      # @api private
+      def quote_non_string(value)
+        case value
+        when NilClass then 'null'
+        when TrueClass then 'true'
+        when FalseClass then 'false'
+        when Numeric then value.to_s
+        when Time, DateTime then %("#{value.iso8601}")
+        when Date then %("#{value.iso8601}")
+        else
+          if value.respond_to?(:to_time)
+            %("#{value.to_time.iso8601}")
+          else
+            %("#{escape_string(value.to_s)}")
+          end
+        end
+      end
+
       # Escape a raw string for inclusion inside double quotes.
       # @param str [String]
       # @return [String]

data/lib/search_engine/hydration/materializers.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module SearchEngine
   module Hydration
     # Centralized executors for materialization: to_a/each/count/ids/pluck/pick.
@@ -505,7 +507,7 @@ module SearchEngine
         if orders.any? { |o| o.start_with?('$') }
           raise SearchEngine::Errors::InvalidOption.new(
             'Sorting by joined fields is not supported by client-side join fallback',
-            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#client-side-fallback'
+            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#client-side-fallback'
           )
         end
         include_str = begin
@@ -516,7 +518,7 @@ module SearchEngine
         if include_str&.split(',')&.any? { |seg| seg.strip.start_with?('$') }
           raise SearchEngine::Errors::InvalidOption.new(
             'Selecting joined fields is not supported by client-side join fallback',
-            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#client-side-fallback'
+            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#client-side-fallback'
           )
         end
 
@@ -569,7 +571,7 @@ module SearchEngine
                 # Unsupported node type for fallback (e.g., ranges, not_eq, etc.)
                 raise SearchEngine::Errors::InvalidOption.new(
                   'Only equality and IN predicates on joined fields are supported by client-side join fallback',
-                  doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#client-side-fallback'
+                  doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#client-side-fallback'
                 )
               end
             end
@@ -627,7 +629,7 @@ module SearchEngine
             # Fallback does not support OR with joined nodes; reject early
             raise SearchEngine::Errors::InvalidOption.new(
               'OR with joined predicates is not supported by client-side join fallback',
-              doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/joins#client-side-fallback'
+              doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/joins#client-side-fallback'
             )
           else
             if node.respond_to?(:field)
@@ -715,7 +717,10 @@ module SearchEngine
       end
 
       def coerce_pluck_field_names(fields)
-        Array(fields).flatten.compact.map(&:to_s).map(&:strip).reject(&:empty?)
+        Array(fields).flatten.filter_map do |f|
+          s = f.to_s.strip
+          s unless s.empty?
+        end
       end
       module_function :coerce_pluck_field_names
 
@@ -744,7 +749,7 @@ module SearchEngine
         raise SearchEngine::Errors::InvalidSelection.new(
           msg,
           hint: hint,
-          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/field-selection#guardrails--errors',
+          doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/field-selection#guardrails--errors',
           details: { requested: names, include_base: include_base, exclude_base: exclude_base }
         )
       end
@@ -755,8 +760,9 @@ module SearchEngine
         if exclude_base.include?(field)
           "InvalidSelection: field :#{field} not in effective selection. Remove exclude(:#{field})."
         else
+          seen = Set.new(include_base)
           suggestion_fields = include_base.dup
-          requested.each { |f| suggestion_fields << f unless suggestion_fields.include?(f) }
+          requested.each { |f| suggestion_fields << f if seen.add?(f) }
           symbols = suggestion_fields.map { |t| ":#{t}" }.join(',')
           "InvalidSelection: field :#{field} not in effective selection. Use `reselect(#{symbols})`."
         end

data/lib/search_engine/indexer/batch_planner.rb

@@ -19,20 +19,15 @@ module SearchEngine
       # @param buffer [String] a reusable String buffer to encode into
       # @return [Array(Integer, Integer)] [docs_count, bytes_sent]
       # @raise [SearchEngine::Errors::InvalidParams] when a document is not a Hash or missing :id
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer
       def self.encode_jsonl!(docs, buffer)
         count = 0
         buffer.clear
         size = docs.size
+        now_i = defined?(Time.zone) && Time.zone ? Time.zone.now.to_i : Time.now.to_i
         docs.each_with_index do |raw, idx|
           doc = ensure_hash_document(raw)
           ensure_id!(doc)
-          # Force system timestamp field prior to serialization to Typesense
-          now_i = if defined?(Time) && defined?(Time.zone) && Time.zone
-                    Time.zone.now.to_i
-                  else
-                    Time.now.to_i
-                  end
           doc[:doc_updated_at] = now_i if doc.is_a?(Hash)
           buffer << JSON.generate(doc)
           buffer << "\n" if idx < (size - 1)
@@ -62,7 +57,7 @@ module SearchEngine
             raise SearchEngine::Errors::InvalidParams,
                   'Indexer requires batches of Hash-like documents with at least an :id key. ' \
                   'Mapping DSL is not available yet. See ' \
-                  'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer.'
+                  'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer.'
           end
         end
 

data/lib/search_engine/indexer/import_dispatcher.rb

@@ -28,7 +28,7 @@ module SearchEngine
         # @param dry_run [Boolean] when true, do not perform network call
         # @return [Hash] stats payload: { index:, docs_count:, success_count:, failure_count:, attempts:, http_status:, duration_ms:, bytes_sent:, errors_sample: [] }
         # @raise [SearchEngine::Errors::Api] when the underlying client raises an API error (propagated)
-        # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer
+        # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer
         if dry_run
           # Emit instrumentation parity without network
           http_status = 200

data/lib/search_engine/indexer/retry_policy.rb

@@ -39,7 +39,7 @@ module SearchEngine
       # Build a policy from a config-like Hash.
       # @param cfg [Hash]
       # @return [RetryPolicy]
-      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/indexer
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/v30.1/indexer
       def self.from_config(cfg)
         c = cfg || {}
         new(
@@ -72,7 +72,6 @@ module SearchEngine
       # @param error [Exception]
       # @return [Float]
       def next_delay(attempt, _error)
-        # Exponential backoff with bounded jitter
         exp = [@base * (2 ** (attempt - 1)), @max].min
         jitter = exp * @jitter_fraction
         delta = random_in_range(-jitter..jitter)
@@ -80,13 +79,17 @@ module SearchEngine
         sleep_time.positive? ? sleep_time : 0.0
       end
 
+      # Whether an HTTP status code represents a transient/retryable error.
+      # @param code [Integer]
+      # @return [Boolean]
+      def self.transient_status?(code)
+        code == 429 || (code >= 500 && code <= 599)
+      end
+
       private
 
       def transient_status?(code)
-        return true if code == 429
-        return true if code >= 500 && code <= 599
-
-        false
+        self.class.transient_status?(code)
       end
 
       def random_in_range(range)