search-engine-for-typesense 1.0.0

data/lib/search_engine/base/pretty_printer.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module SearchEngine
+  class Base
+    # Pretty printing and inspect helpers for console output.
+    # Extracted from Base with identical behavior.
+    module PrettyPrinter
+      extend ActiveSupport::Concern
+
+      include SearchEngine::Base::DisplayCoercions
+
+      # Human-friendly inspect that lists declared attributes and, when present,
+      # unknown attributes captured during hydration.
+      # @return [String]
+      def inspect
+        pairs = __attribute_pairs_for_render
+        hex_id = begin
+          # Mimic Ruby's default hex object id formatting
+          format('0x%014x', object_id << 1)
+        rescue StandardError
+          object_id
+        end
+        return "#<#{self.class.name}:#{hex_id}>" if pairs.empty?
+
+        lines = pairs.map do |(k, v)|
+          rendered = if v.is_a?(Array) || v.is_a?(Hash)
+                       __se_symbolize_for_inspect(v).inspect
+                     else
+                       v.inspect
+                     end
+          "#{k}: #{rendered}"
+        end
+        "#<#{self.class.name}:#{hex_id}\n  #{lines.join(",\n  ")}>"
+      end
+
+      # Pretty-print with attributes on separate lines for readability in consoles.
+      # Integrates with PP so arrays of models render multiline.
+      # @param pp [PP]
+      # @return [void]
+      def pretty_print(pp)
+        hex_id = begin
+          format('0x%014x', object_id << 1)
+        rescue StandardError
+          object_id
+        end
+        pairs = __attribute_pairs_for_render
+        pp.group(2, "#<#{self.class.name}:#{hex_id} ", '>') do
+          if pairs.empty?
+            pp.breakable ''
+          else
+            pp.breakable ''
+            pairs.each_with_index do |(k, v), idx|
+              if v.is_a?(Array) || v.is_a?(Hash)
+                pp.text("#{k}:")
+                pp.nest(2) do
+                  pp.breakable ' '
+                  pp.pp(__se_symbolize_for_inspect(v))
+                end
+              else
+                pp.text("#{k}: ")
+                pp.pp(v)
+              end
+              if idx < pairs.length - 1
+                pp.text(',')
+                pp.breakable ' '
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      # Build ordered list of attribute pairs for rendering:
+      # - Declared attributes in declaration order (with id rendered first when present)
+      # - Followed by unknown attributes (when present)
+      # @return [Array<[String, Object]>]
+      def __attribute_pairs_for_render
+        declared = __se_declared_attributes
+        pairs = []
+
+        __se_append_declared_id!(pairs, declared)
+        __se_render_present_declared_attributes!(pairs, declared)
+
+        join_names = __se_declared_join_names
+        __se_render_present_declared_joins!(pairs, join_names)
+
+        __se_append_unknown_attribute_pairs(pairs, declared)
+      end
+
+      # Return declared attribute map with resilience to missing APIs.
+      def __se_declared_attributes
+        self.class.respond_to?(:attributes) ? (self.class.attributes || {}) : {}
+      rescue StandardError
+        {}
+      end
+
+      # Render id first if declared and present in the hydrated document
+      def __se_append_declared_id!(pairs, declared)
+        return unless declared.key?(:id) && instance_variable_defined?('@id')
+
+        pairs << ['id', __se_coerce_id_for_display(instance_variable_get('@id'))]
+      end
+
+      # Render only declared attributes that were present in the hydrated document
+      def __se_render_present_declared_attributes!(pairs, declared)
+        declared.each_key do |name|
+          next if name.to_s == 'id'
+
+          begin
+            next unless self.class.respond_to?(:valid_attribute_reader_name?) &&
+                        self.class.valid_attribute_reader_name?(name)
+          rescue StandardError
+            next if name.to_s.include?('.')
+          end
+
+          ivar_name = "@#{name}"
+          next unless instance_variable_defined?(ivar_name)
+
+          raw_value = instance_variable_get(ivar_name)
+          value_for_render = if name.to_s == 'doc_updated_at' && !raw_value.nil?
+                               __se_coerce_doc_updated_at_for_display(raw_value)
+                             else
+                               raw_value
+                             end
+          pairs << [name.to_s, value_for_render]
+        end
+      end
+
+      # Collect declared join names as strings.
+      def __se_declared_join_names
+        joins = self.class.respond_to?(:joins_config) ? (self.class.joins_config || {}) : {}
+        joins.keys.map(&:to_s)
+      rescue StandardError
+        []
+      end
+
+      # Render declared joined attributes that were present in the hydrated document
+      def __se_render_present_declared_joins!(pairs, join_names)
+        join_names.each do |join_name|
+          ivar_name = "@#{join_name}"
+          next unless instance_variable_defined?(ivar_name)
+
+          value = instance_variable_get(ivar_name)
+          next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+          pairs << [join_name, value]
+        end
+      end
+
+      # Group "$assoc.field" unknown attributes into a nested Hash under "$assoc" for rendering.
+      # Prefers existing shapes when "$assoc" key already exists in the payload (Hash/Array).
+      # Returns [passthrough(Map<key->val>), grouped(Map<assoc->Hash>), assoc_order(Array<String>)].
+      def __se_group_join_fields_for_render(extras)
+        grouped = {}
+        assoc_order = []
+        passthrough = {}
+
+        extras.each do |k, v|
+          key = k.to_s
+          if key.start_with?('$') && key.include?('.') && !v.is_a?(Hash) && !v.is_a?(Array)
+            assoc_key, field = key.split('.', 2)
+            assoc = assoc_key.delete_prefix('$')
+            # Respect existing nested shape if present
+            if extras.key?(assoc)
+              passthrough[key] = v
+            else
+              unless grouped.key?(assoc)
+                grouped[assoc] = {}
+                assoc_order << assoc
+              end
+              grouped[assoc][field] = v
+            end
+          else
+            passthrough[key] = v
+          end
+        end
+
+        [passthrough, grouped, assoc_order]
+      end
+
+      # Append unknown attributes, grouping join fields and preserving nested shapes.
+      def __se_append_unknown_attribute_pairs(pairs, declared)
+        extras = unknown_attributes
+        return pairs if extras.empty?
+
+        __se_maybe_render_unknown_id_first!(pairs, declared, extras)
+
+        selected_nested = __se_selected_nested_assocs_for_render
+        __se_render_existing_nested_assoc_pairs!(pairs, extras, selected_nested)
+
+        passthrough, grouped, assoc_order = __se_group_join_fields_for_render(extras)
+        __se_render_grouped_scalar_assoc_pairs!(pairs, assoc_order, grouped)
+        __se_render_passthrough_unknowns!(pairs, passthrough)
+        pairs
+      end
+
+      # Ensure id appears first when not declared but present in unknowns
+      def __se_maybe_render_unknown_id_first!(pairs, declared, extras)
+        return if declared.key?(:id)
+
+        id_v = extras['id'] || extras[:id]
+        pairs.unshift(['id', __se_coerce_id_for_display(id_v)]) unless id_v.nil?
+      end
+
+      # Return selection context for nested assocs used during render
+      # @return [Array<String>]
+      def __se_selected_nested_assocs_for_render
+        Array(
+          instance_variable_defined?(:@__se_selected_nested_assocs__) &&
+          instance_variable_get(:@__se_selected_nested_assocs__)
+        ).map(&:to_s)
+      end
+
+      # Render already nested structures for assoc keys (either "$assoc" or plain assoc)
+      def __se_render_existing_nested_assoc_pairs!(pairs, extras, selected_nested)
+        declared_joins = begin
+          self.class.respond_to?(:joins_config) ? (self.class.joins_config || {}) : {}
+        rescue StandardError
+          {}
+        end
+        assoc_names = declared_joins.keys.map(&:to_s)
+
+        extras.each do |k, v|
+          key = k.to_s
+          next unless v.is_a?(Array) || v.is_a?(Hash)
+
+          assoc = key.start_with?('$') ? key.delete_prefix('$') : key
+          next unless assoc_names.include?(assoc)
+
+          already = pairs.any? { |(name, _)| name == assoc }
+          next if already
+          next if selected_nested.any? && !selected_nested.include?(assoc)
+
+          pairs << [assoc, __se_symbolize_for_inspect(v)]
+        end
+      end
+
+      # Render grouped scalar $assoc.field maps under assoc as an array-of-hashes
+      def __se_render_grouped_scalar_assoc_pairs!(pairs, assoc_order, grouped)
+        assoc_order.each do |assoc|
+          next if pairs.any? { |(name, _)| name == assoc }
+
+          pairs << [assoc.to_s, [__se_symbolize_for_inspect(grouped[assoc])]]
+        end
+      end
+
+      # Render remaining passthrough unknowns with special handling for doc_updated_at
+      def __se_render_passthrough_unknowns!(pairs, passthrough)
+        passthrough.each do |k, v|
+          key = k.to_s
+          next if key == 'id' || key.start_with?('$', '.')
+          # Avoid duplicating assoc entries already rendered
+          next if pairs.any? { |(name, _)| name == key }
+
+          rendered = key == 'doc_updated_at' && !v.nil? ? __se_coerce_doc_updated_at_for_display(v) : v
+          pairs << [key, rendered]
+        end
+      end
+
+      # Symbolize keys for inspect to avoid symbol bloat (deep).
+      def __se_symbolize_for_inspect(value)
+        case value
+        when Array
+          value.map { |element| __se_symbolize_for_inspect(element) }
+        when Hash
+          value.each_with_object({}) do |(k, v), acc|
+            key = k.is_a?(String) || k.is_a?(Symbol) ? k.to_sym : k
+            acc[key] = __se_symbolize_for_inspect(v)
+          end
+        else
+          value
+        end
+      end
+
+      # Coerce id for display: if it's a numeric-looking string and model's id source is integer-like,
+      # render as Integer; otherwise render as-is. This does not mutate underlying value.
+      def __se_coerce_id_for_display(value)
+        v = value
+        return v if v.nil?
+
+        # Determine if this collection is ActiveRecord-sourced with integer/bigint PK and no custom identify_by
+        begin
+          dsl = self.class.instance_variable_get(:@__mapper_dsl__)
+          src = dsl&.dig(:source, :type)
+          if src.to_s == 'active_record' && !self.class.instance_variable_defined?(:@identify_by_proc)
+            model = dsl&.dig(:source, :options, :model)
+            if model.respond_to?(:columns_hash)
+              pk = begin
+                model.primary_key
+              rescue StandardError
+                'id'
+              end
+              col = begin
+                model.columns_hash[pk.to_s]
+              rescue StandardError
+                nil
+              end
+              if col && %i[integer bigint].include?(col.type) && v.is_a?(String) && v.match?(/^[-+]?\d+$/)
+                # Try to display numeric-looking strings as Integer
+                return Integer(v)
+              end
+            end
+          end
+        rescue StandardError
+          # fall through
+        end
+
+        v
+      end
+    end
+  end
+end

data/lib/search_engine/base/relation_delegation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module SearchEngine
+  class Base
+    # Delegates class-level query methods to `.all` relation instance.
+    module RelationDelegation
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Return a fresh, immutable relation bound to this model class.
+        # @return [SearchEngine::Relation]
+        def all
+          SearchEngine::Relation.new(self)
+        end
+
+        # Delegate materializers and query dsl to `.all` so callers can do `Model.first` etc.
+        %i[
+          where rewhere merge order preset ranking prefix search
+          pin hide curate clear_curation
+          facet_by facet_query group_by unscope
+          limit offset page per_page per options cache
+          joins use_synonyms use_stopwords
+          select include_fields exclude reselect
+          limit_hits validate_hits!
+          first last take pluck pick exists? count find_by all!
+          delete_all update_all
+          raw
+        ].each { |method| delegate method, to: :all }
+
+        # Find a record by its document id (model-level only).
+        # Equivalent to `find_by(id: id)`.
+        # @param id [#to_s] Document id
+        # @return [Object, nil]
+        def find(id)
+          find_by(id: id)
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/base/scopes.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module SearchEngine
+  class Base
+    # ActiveRecord-like named scopes for SearchEngine models.
+    #
+    # Scopes are defined on the model class and must return a
+    # {SearchEngine::Relation}. They are evaluated against a fresh
+    # relation (`all`) and are therefore fully chainable.
+    #
+    # Examples:
+    #   class Product < SearchEngine::Base
+    #     scope :active, -> { where(active: true) }
+    #     scope :by_store, ->(id) { where(store_id: id) }
+    #   end
+    #
+    #   Product.active.by_store(1).search("shoes")
+    module Scopes
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Internal registry of declared scopes for this model.
+        # Used to apply scopes against an existing Relation (AR parity).
+        #
+        # @api private
+        # @return [Hash{Symbol=>Proc}]
+        def __search_engine_scope_registry__
+          @__search_engine_scope_registry__ ||= {}
+        end
+
+        # Normalize scope arguments to preserve Ruby 3 keyword behavior.
+        # When the scope expects keyword args only, accept a single Hash
+        # positional argument by converting it into kwargs.
+        #
+        # @api private
+        # @return [Array<Array, Hash>] normalized [args, kwargs]
+        def __se_normalize_scope_args(impl, args, kwargs)
+          return [args, kwargs] unless kwargs.empty? && args.length == 1 && args.first.is_a?(Hash)
+
+          params = impl.parameters
+          expects_keywords = params.any? { |(type, _)| %i[key keyreq keyrest].include?(type) }
+          expects_positional = params.any? { |(type, _)| %i[req opt rest].include?(type) }
+          return [args, kwargs] if expects_positional || !expects_keywords
+
+          raw = args.first
+          coerced = raw.each_with_object({}) do |(k, v), acc|
+            key = k.respond_to?(:to_sym) ? k.to_sym : k
+            acc[key] = v
+          end
+
+          [[], coerced]
+        end
+        private :__se_normalize_scope_args
+
+        # Define a named, chainable scope.
+        #
+        # @param name [#to_sym] public method name for the scope
+        # @param body [#call, nil] a Proc/lambda evaluated against a fresh Relation
+        # @yield evaluated as the scope body when +body+ is nil (AR-style)
+        # @return [void]
+        #
+        # The scope body is executed with `self` set to a fresh
+        # {SearchEngine::Relation} bound to the model. It must return a
+        # Relation (or nil, which is treated as `all`).
+        #
+        # Reserved names: scope names must not conflict with core query or
+        # materializer methods (e.g., :all, :first, :last, :find_by, :pluck, :pick).
+        def scope(name, body = nil, &block)
+          raise ArgumentError, 'scope requires a name' if name.nil?
+
+          impl = body || block
+          raise ArgumentError, 'scope requires a callable (Proc/lambda)' if impl.nil? || !impl.respond_to?(:call)
+
+          method_name = name.to_sym
+
+          # Avoid overriding core query methods and relation materializers.
+          reserved = %i[
+            all first last take count exists? find find_by pluck pick delete_all update_all
+            where rewhere merge order select include_fields exclude reselect joins preset ranking prefix search
+            limit offset page per_page per options cache
+          ]
+          if reserved.include?(method_name)
+            raise ArgumentError, "scope :#{method_name} conflicts with a reserved query method"
+          end
+
+          define_singleton_method(method_name) do |*args, **kwargs, &_unused_block|
+            base = all
+
+            # Evaluate scope body directly against the fresh relation, so `self`
+            # inside the scope is a Relation and chaining behaves predictably.
+            norm_args, norm_kwargs = __se_normalize_scope_args(impl, args, kwargs)
+            result = base.instance_exec(*norm_args, **norm_kwargs, &impl)
+
+            # Coerce common mistakes to a usable Relation:
+            # - nil (AR parity) -> return a fresh relation
+            # - model class returned by accident -> return a fresh relation
+            return base if result.nil? || result.equal?(base.klass)
+            return result if result.is_a?(SearchEngine::Relation)
+
+            raise ArgumentError,
+                  "scope :#{method_name} must return a SearchEngine::Relation (got #{result.class})"
+          end
+
+          __search_engine_scope_registry__[method_name] = impl
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/base/updating.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module SearchEngine
+  class Base
+    # Instance-level updating for a single hydrated record.
+    #
+    # Provides {#update} that partially updates the current document in the
+    # Typesense collection using its document id. The id is obtained from the
+    # hydrated payload when available, and falls back to computing it via the
+    # class-level `identify_by` strategy.
+    module Updating
+      extend ActiveSupport::Concern
+
+      # Partially update this record in the collection.
+      #
+      # @param attributes [Hash, nil] fields to update (or pass as kwargs)
+      # @param into [String, nil] override physical collection name
+      # @param partition [Object, nil] partition token for resolvers
+      # @param timeout_ms [Integer, nil] optional read timeout override in ms
+      # @param cascade [Boolean, nil] when true, trigger cascade reindex for referencing collections
+      # @return [Integer] number of updated documents (0 or 1)
+      # @raise [SearchEngine::Errors::InvalidParams] when the record id is unavailable
+      def update(attributes = nil, into: nil, partition: nil, timeout_ms: nil, cascade: nil, **kwattrs)
+        attrs = __se_coalesce_update_attributes(attributes, kwattrs)
+        raise SearchEngine::Errors::InvalidParams, 'attributes must be a non-empty Hash' if attrs.nil? || attrs.empty?
+
+        id_value = __se_effective_document_id_for_update
+        if id_value.nil? || id_value.to_s.strip.empty?
+          raise SearchEngine::Errors::InvalidParams,
+                "Cannot update without document id; include 'id' in selection or provide identifiable attributes"
+        end
+
+        collection = SearchEngine::Deletion.resolve_into(
+          klass: self.class,
+          partition: partition,
+          into: into
+        )
+
+        resp = SearchEngine.client.update_document(
+          collection: collection,
+          id: id_value,
+          fields: attrs,
+          timeout_ms: timeout_ms
+        )
+        updated = resp ? 1 : 0
+
+        # Best-effort cascade when requested
+        if updated.positive? && cascade
+          begin
+            SearchEngine::Cascade.cascade_reindex!(source: self.class, ids: [id_value], context: :update)
+          rescue StandardError
+            # swallow cascade errors to keep update semantics stable
+          end
+        end
+
+        updated
+      end
+
+      private
+
+      # Prefer explicit Hash argument when provided; fall back to kwargs.
+      # @param attributes [Hash, nil]
+      # @param kwattrs [Hash]
+      # @return [Hash, nil]
+      def __se_coalesce_update_attributes(attributes, kwattrs)
+        return attributes if attributes.is_a?(Hash) && !attributes.empty?
+        return kwattrs if kwattrs && !kwattrs.empty?
+
+        nil
+      end
+
+      # Determine the effective document id for update, preferring hydrated
+      # `@id` when present and falling back to the class-level identify_by.
+      # @return [String, nil]
+      def __se_effective_document_id_for_update
+        v = instance_variable_defined?(:@id) ? instance_variable_get(:@id) : nil
+        return v unless v.nil? || v.to_s.strip.empty?
+
+        begin
+          computed = self.class.compute_document_id(self)
+          return computed unless computed.nil? || computed.to_s.strip.empty?
+        rescue StandardError
+          # best-effort; nil means we cannot determine id
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/search_engine/base.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'base/display_coercions'
+require_relative 'base/hydration'
+require_relative 'base/index_maintenance'
+require_relative 'base/indexing_dsl'
+require_relative 'base/creation'
+require_relative 'base/scopes'
+require_relative 'base/joins'
+require_relative 'base/model_dsl'
+require_relative 'base/presets'
+require_relative 'base/pretty_printer'
+require_relative 'base/updating'
+require_relative 'base/deletion'
+require_relative 'base/relation_delegation'
+
+module SearchEngine
+  # Base class for SearchEngine models.
+  #
+  # Provides lightweight macros to declare the backing Typesense collection and
+  # a schema-like list of attributes for future hydration. Attributes declared in
+  # a parent class are inherited by subclasses. Redefining an attribute in a
+  # subclass overwrites only at the subclass level.
+  class Base
+    include SearchEngine::Base::Hydration
+    include SearchEngine::Base::PrettyPrinter
+    include SearchEngine::Base::ModelDsl
+    include SearchEngine::Base::RelationDelegation
+    include SearchEngine::Base::Scopes
+    include SearchEngine::Base::IndexingDsl
+    include SearchEngine::Base::Joins
+    include SearchEngine::Base::Presets
+    include SearchEngine::Base::IndexMaintenance
+    include SearchEngine::Base::Updating
+    include SearchEngine::Base::Deletion
+    include SearchEngine::Base::Creation
+  end
+end