search-engine-for-typesense 1.0.0

data/lib/search_engine/relation/dx/dry_run.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module SearchEngine
+  class Relation
+    module Dx
+      # Pure helpers for producing redacted previews without I/O.
+      module DryRun
+        # Redact a compiled params hash, preserving only whitelisted keys and
+        # masking sensitive fields. Returns a new Hash.
+        # @param params [Hash]
+        # @return [Hash]
+        def self.redact_params(params)
+          redacted = SearchEngine::Observability.redact(params)
+          return redacted unless params.is_a?(Hash)
+
+          hits = params[:_hits] || params['_hits']
+          return redacted unless hits
+
+          out = redacted.is_a?(Hash) ? redacted.dup : {}
+          out[:_hits] = hits
+          out
+        end
+
+        # Return pretty or compact JSON with stable key ordering when pretty.
+        # @param value [Object]
+        # @param pretty [Boolean]
+        # @return [String]
+        def self.to_json(value, pretty: true)
+          if pretty && value.is_a?(Hash)
+            ordered = value.sort_by { |(k, _v)| k.to_s }.to_h
+            JSON.pretty_generate(ordered)
+          else
+            JSON.generate(value)
+          end
+        end
+
+        # Build a single-line curl string with redacted body.
+        # @param url [String]
+        # @param params [Hash]
+        # @return [String]
+        def self.curl(url, params)
+          body_json = JSON.generate(redact_params(params))
+          %(curl -X POST #{url} -H 'Content-Type: application/json' -H 'X-TYPESENSE-API-KEY: ***' -d '#{body_json}')
+        end
+
+        # Return a structured dry-run payload with redacted JSON body and url options.
+        # @param url [String]
+        # @param params [Hash]
+        # @param url_opts [Hash]
+        # @return [Hash]
+        def self.payload(url:, params:, url_opts: {})
+          { url: url, body: JSON.generate(redact_params(params)), url_opts: url_opts.freeze }
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/relation/dx/friendly_where.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Relation
+    module Dx
+      # Pure helper for human-friendly rendering of Typesense filter strings.
+      # Accepts a String and returns a transformed String without mutating input.
+      module FriendlyWhere
+        # Render a human-friendly `filter_by` string.
+        # @param filter_by [String]
+        # @return [String]
+        def self.render(filter_by)
+          s = filter_by.to_s
+          return s if s.empty?
+
+          s.gsub(' && ', ' AND ')
+           .gsub(' || ', ' OR ')
+           .gsub(':=[', ' IN [')
+           .gsub(':!=[', ' NOT IN [')
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/relation/dx.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'search_engine/relation/dx/friendly_where'
+require 'search_engine/relation/dx/dry_run'
+
+module SearchEngine
+  # Immutable, chainable query relation bound to a model class.
+  # See `lib/search_engine/relation.rb` for full API; DX helpers are mixed in here.
+  class Relation
+    # DX helpers are mixed into `Relation` to offer redaction‑aware, zero‑I/O explain and preview utilities.
+    # These helpers are pure and never mutate relation state.
+    module Dx
+      # Return the request body JSON after compile, fully redacted.
+      # @param pretty [Boolean] pretty-print with stable key ordering when true
+      # @return [String]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx
+      def to_params_json(pretty: true)
+        params = SearchEngine::CompiledParams.from(to_typesense_params)
+        redacted = SearchEngine::Relation::Dx::DryRun.redact_params(params.to_h)
+        SearchEngine::Relation::Dx::DryRun.to_json(redacted, pretty: pretty)
+      end
+
+      # Return a single-line curl command with redacted API key and JSON body.
+      # @return [String]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx
+      def to_curl
+        url = compiled_url
+        params = SearchEngine::CompiledParams.from(to_typesense_params).to_h
+        SearchEngine::Relation::Dx::DryRun.curl(url, params)
+      end
+
+      # Compile and validate without performing network I/O.
+      # Returns a structured hash with URL and post-redaction body.
+      # @return [Hash] { url:, body:, url_opts: }
+      # @raise [SearchEngine::Errors::*] same validation errors as runtime path
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx
+      def dry_run!
+        params = SearchEngine::CompiledParams.from(to_typesense_params).to_h
+        SearchEngine::Relation::Dx::DryRun.payload(url: compiled_url, params: params, url_opts: compiled_url_opts)
+      end
+
+      # Enhanced explain output with overview, parts, conflicts, and predicted events.
+      # Builds a redaction-aware summary without network I/O.
+      # @param to [Symbol, nil]
+      # @return [String]
+      # @since M8
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx#helpers--examples
+      def explain(to: nil)
+        params = SearchEngine::CompiledParams.from(to_typesense_params)
+        lines = []
+
+        lines << header_line
+        append_preset_explain_line(lines, params)
+        append_curation_explain_lines(lines)
+        append_where_line(lines, params)
+        append_order_line(lines, params)
+        append_group_line(lines)
+        append_facets_line(lines, params)
+        append_selection_explain_lines(lines, params)
+        add_effective_selection_tokens!(lines)
+        add_pagination_line!(lines, params)
+        append_hit_limits_line(lines, params)
+        append_ranking_line(lines, params)
+        lines << overview_line(params)
+        append_conflicts_line(lines, params)
+        append_events_line(lines, params)
+
+        out = lines.join("\n")
+        puts(out) if to == :stdout
+        out
+      end
+
+      private
+
+      def redact_body(params)
+        hash = params.dup
+        preview = SearchEngine::Observability.redact(params)
+        hash[:filter_by] = preview[:filter_by] if preview.is_a?(Hash) && preview.key?(:filter_by)
+        hash
+      end
+
+      def predicted_events_for_plan(params)
+        events = []
+        events << 'search_engine.compile' if Array(@state[:ast]).any?
+        events << 'search_engine.joins.compile' if Array(params[:_join] && params[:_join][:assocs]).any?
+        events << 'search_engine.grouping.compile' if params.key?(:group_by)
+        if preset_name
+          events << 'search_engine.preset.apply'
+          events << 'search_engine.preset.conflict' if Array(params[:_preset_conflicts]).any?
+        end
+        events << 'search_engine.search'
+        events
+      end
+
+      def compiled_url
+        collection = collection_name_for_klass
+        cfg = SearchEngine.config
+        proto = cfg.protocol.to_s.strip.presence
+        base = [proto, "#{cfg.host}:#{cfg.port}"].compact.join('://')
+        "#{base}/collections/#{collection}/documents/search"
+      end
+
+      def compiled_url_opts
+        url_opts = ClientOptions.url_options_from_config(SearchEngine.config)
+        overrides = build_url_opts
+        url_opts.merge!(overrides) unless overrides.empty?
+        url_opts
+      end
+
+      def header_line
+        "#{klass_name_for_inspect} Relation"
+      end
+
+      def append_where_line(lines, params)
+        fb = params[:filter_by]
+        return unless fb && !fb.to_s.strip.empty?
+
+        # Render friendly operators first, then redact the final string to preserve
+        # IN/NOT IN tokens while masking literals.
+        friendly = SearchEngine::Relation::Dx::FriendlyWhere.render(fb.to_s)
+        masked = SearchEngine::Observability.redact(friendly)
+        where_str = masked.is_a?(String) ? masked : friendly
+        lines << "  where: #{where_str}" unless where_str.to_s.strip.empty?
+      end
+
+      def append_order_line(lines, params)
+        sb = params[:sort_by]
+        lines << "  order: #{sb}" if sb && !sb.to_s.strip.empty?
+      end
+
+      def append_group_line(lines)
+        g = @state[:grouping]
+        return unless g
+
+        gparts = ["group_by=#{g[:field]}"]
+        gparts << "limit=#{g[:limit]}" if g[:limit]
+        gparts << 'missing_values=true' if g[:missing_values]
+        lines << "  group: #{gparts.join(' ')}"
+      end
+
+      def overview_line(params)
+        parts = []
+        parts << "collection=#{collection_name_for_klass}"
+        if (g = grouping)
+          seg = [g[:field]].compact
+          seg << "limit=#{g[:limit]}" if g[:limit]
+          seg << 'missing_values' if g[:missing_values]
+          parts << "grouping=#{seg.join(':')}"
+        end
+        if params.key?(:page) || params.key?(:per_page)
+          p = params[:page]
+          per = params[:per_page]
+          parts << "page/per=#{p || ''}/#{per || ''}"
+        end
+        parts << (preset_name ? "preset=#{preset_name}(mode=#{preset_mode})" : 'preset=—')
+        parts << "joins=#{Array(joins_list).size}"
+        cid = SearchEngine::Instrumentation.current_correlation_id
+        parts << "cid=#{cid && !cid.to_s.empty? ? cid : '—'}"
+        "Overview: #{parts.join(' ')}"
+      end
+
+      def append_conflicts_line(lines, params)
+        conflicts = Array(params[:_preset_conflicts]).map(&:to_s).sort
+        lines << "Conflicts & Warnings: dropped keys in :lock mode => #{conflicts.join(', ')}" unless conflicts.empty?
+      end
+
+      def append_events_line(lines, params)
+        events = predicted_events_for_plan(params)
+        lines << "Events that would fire: #{events.join(' → ')}" unless events.empty?
+      end
+
+      def append_facets_line(lines, params)
+        fb = params[:facet_by]
+        fq = params[:facet_query]
+        mv = params[:max_facet_values]
+        segs = []
+        segs << "facet_by=#{fb}" if fb && !fb.to_s.strip.empty?
+        segs << "max=#{mv}" if mv
+        segs << "queries=#{fq}" if fq && !fq.to_s.strip.empty?
+        lines << "  facets: #{segs.join(' ')}" unless segs.empty?
+      end
+
+      def append_ranking_line(lines, params)
+        rk = @state[:ranking]
+        has_ranking_param = rk ||
+                            params.key?(:query_by_weights) || params.key?(:num_typos) ||
+                            params.key?(:drop_tokens_threshold) || params.key?(:prioritize_exact_match) ||
+                            params.key?(:infix)
+        return unless has_ranking_param
+
+        parts = []
+        begin
+          plan = SearchEngine::RankingPlan.new(relation: self, query_by: params[:query_by], ranking: rk || {})
+          fields = plan.effective_query_by_fields
+          parts << "query_by=[#{fields.join(', ')}]" unless fields.empty?
+        rescue StandardError
+          # ignore
+        end
+
+        parts << "weights=#{params[:query_by_weights]}" if params[:query_by_weights]
+        parts << "num_typos=#{params[:num_typos]}" if params.key?(:num_typos)
+        parts << "drop_tokens_threshold=#{params[:drop_tokens_threshold]}" if params.key?(:drop_tokens_threshold)
+        parts << "prioritize_exact_match=#{params[:prioritize_exact_match]}" if params.key?(:prioritize_exact_match)
+        parts << "prefix=#{params[:infix]}" if params[:infix]
+
+        lines << "  ranking: #{parts.join(' ')}" unless parts.empty?
+      end
+
+      def append_hit_limits_line(lines, params)
+        hits = params[:_hits]
+        return unless hits.is_a?(Hash) && (hits[:early_limit] || hits[:max])
+
+        segs = []
+        segs << "early_limit=#{hits[:early_limit]}" if hits[:early_limit]
+        if hits[:per_adjusted] == true
+          segs << 'per_adjusted=true'
+        elsif hits.key?(:per_adjusted)
+          segs << 'per_adjusted=false'
+        end
+        segs << "validator_max=#{hits[:max]}" if hits[:max]
+        lines << "  hits: #{segs.join(' ')}" unless segs.empty?
+      end
+    end
+
+    include Dx
+  end
+end

data/lib/search_engine/relation/materializers.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Relation
+    # Materializers delegated to Hydration layer (single network call per Relation instance).
+    module Materializers
+      # Execute the relation and return the memoized Result.
+      # @return [SearchEngine::Result]
+      def execute
+        SearchEngine::Hydration::Materializers.execute(self)
+      end
+
+      # Return a shallow copy of hydrated hits.
+      # @return [Array<Object>]
+      def to_a
+        SearchEngine::Hydration::Materializers.to_a(self)
+      end
+
+      # Iterate over hydrated hits.
+      # @yieldparam obj [Object]
+      # @return [Enumerator] when no block is given
+      def each(&block)
+        SearchEngine::Hydration::Materializers.each(self, &block)
+      end
+
+      # Return the first element or the first N elements from the loaded page.
+      # @param n [Integer, nil]
+      # @return [Object, Array<Object>]
+      def first(n = nil)
+        SearchEngine::Hydration::Materializers.first(self, n)
+      end
+
+      # Return the last element or the last N elements from the currently fetched page.
+      # @param n [Integer, nil]
+      # @return [Object, Array<Object>]
+      def last(n = nil)
+        SearchEngine::Hydration::Materializers.last(self, n)
+      end
+
+      # Take N elements from the head. When N==1, returns a single object.
+      # @param n [Integer]
+      # @return [Object, Array<Object>]
+      def take(n = 1)
+        SearchEngine::Hydration::Materializers.take(self, n)
+      end
+
+      # Return raw Typesense response for this relation.
+      # Executes the query (memoized) and returns Result#raw.
+      # @return [Hash]
+      def raw
+        SearchEngine::Hydration::Materializers.execute(self).raw
+      end
+
+      # Find the first matching record using where-like inputs.
+      # Accepts the same arguments as `.where` (Hash, String, Array, Symbol),
+      # applies them if provided, then limits to a single result and returns it.
+      #
+      # @param args [Array<Object>] where-compatible arguments
+      # @return [Object, nil]
+      # @example
+      #   SearchEngine::Product.find_by(article_code: 12312, store_id: 1031)
+      #   SearchEngine::Product.where(active: true).find_by('price:>100')
+      def find_by(*args)
+        relation = args.nil? || args.empty? ? self : where(*args)
+        relation.per(1).page(1).first
+      end
+
+      # Convenience for plucking :id values.
+      # @return [Array<Object>]
+      def ids
+        SearchEngine::Hydration::Materializers.ids(self)
+      end
+
+      # Pick one or multiple fields from the first matching record.
+      # Returns a single value for one field, or an Array for multiple fields.
+      # Returns nil when no records match.
+      # @param fields [Array<#to_sym,#to_s>]
+      # @return [Object, Array<Object>, nil]
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/materializers#pick
+      def pick(*fields)
+        SearchEngine::Hydration::Materializers.pick(self, *fields)
+      end
+
+      # Fetch and hydrate all matching records across all pages.
+      # Performs a count first, then retrieves pages in batches via multi-search.
+      # Warning: This can be memory and time intensive.
+      # @return [Array<Object>]
+      def all!
+        SearchEngine::Hydration::Materializers.all!(self)
+      end
+
+      # Pluck one or multiple fields.
+      # @param fields [Array<#to_sym,#to_s>]
+      # @return [Array<Object>, Array<Array<Object>>]
+      def pluck(*fields)
+        SearchEngine::Hydration::Materializers.pluck(self, *fields)
+      end
+
+      # Whether any matching documents exist.
+      # @return [Boolean]
+      def exists?
+        SearchEngine::Hydration::Materializers.exists?(self)
+      end
+
+      # Return total number of matching documents.
+      # @return [Integer]
+      def count
+        SearchEngine::Hydration::Materializers.count(self)
+      end
+
+      # Return total number of pages for this relation based on total hits and per-page size.
+      # @return [Integer]
+      def pages_count
+        SearchEngine::Hydration::Materializers.pages_count(self)
+      end
+    end
+  end
+end

data/lib/search_engine/relation/options.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  class Relation
+    # Options and pagination normalization helpers.
+    # Centralizes precedence rules and guards for page/per vs limit/offset.
+    module Options
+      # Compute page/per_page with precedence:
+      # - When page/per are provided, prefer them (fill missing per with nil, page defaults to 1 when only per is set)
+      # - Otherwise, when limit is set, derive page from offset and per_page from limit
+      # - Otherwise, return empty Hash
+      # @return [Hash{Symbol=>Integer}]
+      def compute_pagination
+        page = @state[:page]
+        per = @state[:per_page]
+
+        if page || per
+          out = {}
+          if per && page
+            out[:page] = page
+            out[:per_page] = per
+          elsif per && !page
+            out[:page] = 1
+            out[:per_page] = per
+          elsif page && !per
+            out[:page] = page
+          end
+          return out
+        elsif @state[:limit]
+          limit = @state[:limit]
+          off = @state[:offset] || 0
+          computed_page = (off.to_i / limit.to_i) + 1
+          return { page: computed_page, per_page: limit }
+        end
+
+        {}
+      end
+
+      # Normalize hit limits input into a compact Hash.
+      # Accepts keys :early_limit and :max and coerces to positive Integers when possible.
+      # @param value [Hash]
+      # @return [Hash]
+      def normalize_hit_limits_input(value)
+        unless value.is_a?(Hash)
+          raise SearchEngine::Errors::InvalidOption.new(
+            'InvalidOption: hit_limits expects a Hash of options',
+            doc: 'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/hit-limits'
+          )
+        end
+
+        out = {}
+        if value.key?(:early_limit) || value.key?('early_limit')
+          raw = value[:early_limit] || value['early_limit']
+          begin
+            iv = Integer(raw)
+            out[:early_limit] = iv if iv.positive?
+          rescue StandardError
+            nil
+          end
+        end
+        if value.key?(:max) || value.key?('max')
+          raw = value[:max] || value['max']
+          begin
+            iv = Integer(raw)
+            out[:max] = iv if iv.positive?
+          rescue StandardError
+            nil
+          end
+        end
+        out
+      end
+
+      # Coerce integers with a minimum bound; nil passes through.
+      # @param value [Object]
+      # @param name [Symbol]
+      # @param min [Integer]
+      # @return [Integer, nil]
+      # @raise [ArgumentError] when not coercible or below min
+      def coerce_integer_min(value, name, min)
+        return nil if value.nil?
+
+        integer =
+          case value
+          when Integer then value
+          else Integer(value)
+          end
+
+        raise ArgumentError, "#{name} must be >= #{min}" if integer < min
+
+        integer
+      rescue ArgumentError, TypeError
+        raise ArgumentError, "#{name} must be an Integer or nil"
+      end
+
+      # Strict boolean coercion with helpful errors.
+      # @param value [Object]
+      # @param name [Symbol]
+      # @return [true,false]
+      # @raise [ArgumentError]
+      def coerce_boolean_strict(value, name)
+        case value
+        when true, false
+          value
+        when String
+          s = value.to_s.strip.downcase
+          return true  if %w[1 true yes on t].include?(s)
+          return false if %w[0 false no off f].include?(s)
+
+          raise ArgumentError, "#{name} must be a boolean"
+        when Integer
+          return true  if value == 1
+          return false if value.zero?
+
+          raise ArgumentError, "#{name} must be a boolean"
+        else
+          raise ArgumentError, "#{name} must be a boolean"
+        end
+      end
+
+      # Access indifferent key from Hash
+      def option_value(hash, key)
+        if hash.key?(key)
+          hash[key]
+        else
+          hash[key.to_s]
+        end
+      end
+
+      # Stable truncation for inspect helpers
+      def truncate_for_inspect(str, max = 80)
+        return str unless str.is_a?(String)
+        return str if str.length <= max
+
+        "#{str[0, max]}..."
+      end
+    end
+  end
+end