search-engine-for-typesense 1.0.0

data/lib/search_engine/base/deletion.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module SearchEngine
+  class Base
+    # Instance-level deletion for a single hydrated record.
+    #
+    # Provides {#delete} that deletes the current document from the backing
+    # 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 Deletion
+      extend ActiveSupport::Concern
+
+      # Delete this record from the collection.
+      #
+      # Accepts the same optional knobs as relation-level {Relation::Deletion#delete_all}
+      # for consistency.
+      #
+      # @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
+      # @return [Integer] number of deleted documents (0 or 1)
+      # @raise [SearchEngine::Errors::InvalidParams] when the record id is unavailable
+      def delete(into: nil, partition: nil, timeout_ms: nil)
+        id_value = __se_effective_document_id_for_deletion
+        if id_value.nil? || id_value.to_s.strip.empty?
+          raise SearchEngine::Errors::InvalidParams,
+                "Cannot delete without document id; include 'id' in selection or provide identifiable attributes"
+        end
+
+        # Resolve target collection (alias or physical) consistently with relation/model helpers
+        collection = SearchEngine::Deletion.resolve_into(
+          klass: self.class,
+          partition: partition,
+          into: into
+        )
+
+        # Apply same timeout fallback policy as delete_by
+        effective_timeout = if timeout_ms&.to_i&.positive?
+                              timeout_ms.to_i
+                            else
+                              begin
+                                SearchEngine.config.stale_deletes&.timeout_ms
+                              rescue StandardError
+                                nil
+                              end
+                            end
+
+        resp = SearchEngine.client.delete_document(
+          collection: collection,
+          id: id_value,
+          timeout_ms: effective_timeout
+        )
+        # The client returns a Hash or nil when 404; normalize to numeric 0/1
+        resp.nil? ? 0 : 1
+      end
+
+      private
+
+      # Determine the effective document id for deletion, preferring hydrated
+      # `@id` when present and falling back to the class-level identify_by.
+      # @return [String, nil]
+      def __se_effective_document_id_for_deletion
+        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/display_coercions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module SearchEngine
+  class Base
+    # Internal helpers for coercing values for display/formatting.
+    #
+    # This concern provides shared instance-level utilities used by
+    # hydration and pretty-printing. No business logic changes.
+    module DisplayCoercions
+      extend ActiveSupport::Concern
+
+      private
+
+      # Convert integer epoch seconds to a Time in the current zone for display.
+      # Falls back gracefully when value is not an Integer.
+      def __se_coerce_doc_updated_at_for_display(value)
+        int_val = begin
+          Integer(value)
+        rescue StandardError
+          nil
+        end
+        return value if int_val.nil?
+
+        if defined?(Time) && defined?(Time.zone) && Time.zone
+          Time.zone.at(int_val)
+        else
+          Time.at(int_val)
+        end
+      rescue StandardError
+        value
+      end
+    end
+  end
+end

data/lib/search_engine/base/hydration.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module SearchEngine
+  class Base
+    # Hydration helpers for building instances from Typesense documents and
+    # providing attribute readers and views.
+    module Hydration
+      extend ActiveSupport::Concern
+
+      include SearchEngine::Base::DisplayCoercions
+
+      class_methods do
+        # Build a new instance from a Typesense document assigning only declared
+        # attributes and capturing any extra keys in {#unknown_attributes}.
+        #
+        # Unknown keys are preserved as a String-keyed Hash to avoid symbol bloat.
+        #
+        # @param doc [Hash] a document as returned by Typesense
+        # @return [Object] hydrated instance
+        def from_document(doc)
+          obj = new
+          declared = __se_declared_attributes
+          declared_joins = __se_declared_joins
+
+          hidden_local = __se_hidden_local_fields
+          hidden_join = __se_hidden_join_fields
+
+          unknown = __se_assign_declared_or_unknown(
+            obj,
+            doc || {},
+            declared: declared,
+            declared_joins: declared_joins,
+            hidden_local: hidden_local,
+            hidden_join: hidden_join
+          )
+
+          __se_apply_default_joins!(obj, declared_joins: declared_joins, declared: declared)
+          __se_freeze_unknown!(obj, unknown)
+          obj
+        end
+      end
+
+      class_methods do
+        # Fetch declared attributes; resilient to missing DSL
+        def __se_declared_attributes
+          attributes
+        rescue StandardError
+          {}
+        end
+
+        # Fetch join declarations; keep existing behavior (use self.class) to avoid logic change
+        def __se_declared_joins
+          if respond_to?(:joins_config)
+            joins_config || {}
+          else
+            {}
+          end
+        rescue StandardError
+          {}
+        end
+
+        private :__se_declared_attributes, :__se_declared_joins
+      end
+
+      class_methods do
+        # Build the list of hidden local fields (e.g., name_empty)
+        def __se_hidden_local_fields
+          attr_opts = begin
+            respond_to?(:attribute_options) ? attribute_options : {}
+          rescue StandardError
+            {}
+          end
+
+          hidden = []
+          attr_opts.each do |fname, opts|
+            next unless opts.is_a?(Hash)
+
+            hidden << "#{fname}_empty" if opts[:empty_filtering]
+            hidden << "#{fname}_blank" if opts[:optional]
+          end
+          hidden
+        end
+
+        private :__se_hidden_local_fields
+      end
+
+      class_methods do
+        # Build the list of hidden join fields (e.g., $assoc.field_empty)
+        def __se_hidden_join_fields
+          hidden = []
+          joins_cfg = begin
+            respond_to?(:joins_config) ? joins_config : {}
+          rescue StandardError
+            {}
+          end
+
+          joins_cfg.each do |assoc_name, cfg|
+            collection = cfg[:collection]
+            next if collection.nil? || collection.to_s.strip.empty?
+
+            begin
+              target_klass = SearchEngine.collection_for(collection)
+              next unless target_klass.respond_to?(:attribute_options)
+
+              opts = target_klass.attribute_options || {}
+              opts.each do |field_sym, o|
+                next unless o.is_a?(Hash)
+
+                hidden << "#$#{assoc_name}.#{field_sym}_empty".sub('#$', '$') if o[:empty_filtering]
+                hidden << "#$#{assoc_name}.#{field_sym}_blank".sub('#$', '$') if o[:optional]
+              end
+            rescue StandardError
+              # Best-effort; skip when registry/metadata unavailable
+            end
+          end
+
+          hidden
+        rescue StandardError
+          []
+        end
+
+        private :__se_hidden_join_fields
+      end
+
+      class_methods do
+        # Assign declared and join attributes; collect unknowns (filtering hidden fields)
+        def __se_assign_declared_or_unknown(obj, doc, declared:, declared_joins:, hidden_local:, hidden_join:)
+          unknown = {}
+          doc.each do |k, v|
+            key_str = k.to_s
+            key_sym = key_str.to_sym
+            if declared.key?(key_sym) || declared_joins.key?(key_sym)
+              obj.instance_variable_set("@#{key_sym}", v)
+            else
+              next if hidden_local.include?(key_str) || hidden_join.include?(key_str)
+
+              unknown[key_str] = v
+              obj.instance_variable_set('@id', v) if key_str == 'id'
+            end
+          end
+          unknown
+        end
+
+        # Ensure default values for missing join attributes based on local_key type
+        def __se_apply_default_joins!(obj, declared_joins:, declared:)
+          declared_joins.each do |assoc_name, cfg|
+            ivar = "@#{assoc_name}"
+            next if obj.instance_variable_defined?(ivar)
+
+            lk = cfg[:local_key]
+            lk_type = declared[lk]
+            default_val = nil
+            default_val = [] if lk_type.is_a?(Array) && lk_type.size == 1
+            obj.instance_variable_set(ivar, default_val)
+          end
+        end
+
+        def __se_freeze_unknown!(obj, unknown)
+          obj.instance_variable_set(:@__unknown_attributes__, unknown.freeze) unless unknown.empty?
+        end
+
+        private :__se_assign_declared_or_unknown, :__se_apply_default_joins!, :__se_freeze_unknown!
+      end
+
+      # Return a shallow copy of unknown attributes captured during hydration.
+      # Keys are Strings and values are as returned by the backend.
+      # @return [Hash{String=>Object}]
+      def unknown_attributes
+        h = instance_variable_get(:@__unknown_attributes__)
+        h ? h.dup : {}
+      end
+
+      # Return the document update timestamp coerced to Time.
+      #
+      # Prefers a declared attribute reader (when present). Falls back to the
+      # unknown attributes payload (as returned by the backend) when the field
+      # was not declared via the DSL. The value is coerced using the same logic
+      # used for console rendering.
+      #
+      # @return [Time, nil]
+      def doc_updated_at
+        value = if instance_variable_defined?(:@doc_updated_at)
+                  instance_variable_get(:@doc_updated_at)
+                else
+                  raw = instance_variable_get(:@__unknown_attributes__)
+                  if raw&.key?('doc_updated_at')
+                    raw['doc_updated_at']
+                  elsif raw&.key?(:doc_updated_at)
+                    raw[:doc_updated_at]
+                  end
+                end
+
+        return nil if value.nil?
+
+        __se_coerce_doc_updated_at_for_display(value)
+      rescue StandardError
+        nil
+      end
+
+      # Return a symbol-keyed Hash of attributes for this record.
+      #
+      # - Includes declared attributes in declaration order
+      # - Ensures :doc_updated_at is present and coerced to Time when available
+      # - Includes unknown fields under :unknown_attributes (String-keyed), with
+      #   "doc_updated_at" removed to avoid duplication
+      #
+      # @return [Hash{Symbol=>Object}]
+      # rubocop:disable Metrics/PerceivedComplexity
+      def attributes
+        declared = begin
+          self.class.respond_to?(:attributes) ? self.class.attributes : {}
+        rescue StandardError
+          {}
+        end
+
+        out = {}
+
+        declared.each_key do |name|
+          # Skip non-base (dotted) attribute names when reading ivars
+          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
+
+          var = "@#{name}"
+          val = instance_variable_get(var)
+          out[name] =
+            if name.to_s == 'doc_updated_at' && !val.nil?
+              __se_coerce_doc_updated_at_for_display(val)
+            else
+              val
+            end
+        end
+
+        raw_unknowns = instance_variable_get(:@__unknown_attributes__)
+        unknowns = raw_unknowns ? raw_unknowns.dup : {}
+
+        # Ensure :id is present when available (source may be an ivar or unknowns)
+        unless out.key?(:id)
+          raw_id = if instance_variable_defined?(:@id)
+                     instance_variable_get(:@id)
+                   else
+                     unknowns['id'] || unknowns[:id]
+                   end
+          out[:id] = raw_id unless raw_id.nil?
+        end
+
+        unless out.key?(:doc_updated_at)
+          raw_val = unknowns['doc_updated_at']
+          raw_val = unknowns[:doc_updated_at] if raw_val.nil?
+          out[:doc_updated_at] = __se_coerce_doc_updated_at_for_display(raw_val) unless raw_val.nil?
+        end
+
+        # Remove duplicate source of doc_updated_at from nested unknowns
+        unknowns.delete('doc_updated_at')
+        unknowns.delete(:doc_updated_at)
+
+        out[:unknown_attributes] = unknowns unless unknowns.empty?
+        out
+      end
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # Return the Typesense document id if available.
+      #
+      # @return [Object, nil]
+      def id
+        value = instance_variable_defined?(:@id) ? instance_variable_get(:@id) : nil
+        return value unless value.nil?
+
+        raw = instance_variable_get(:@__unknown_attributes__)
+        return nil unless raw
+
+        raw['id'] || raw[:id]
+      rescue StandardError
+        nil
+      end
+
+      # Attribute lookup by key with indifferent access semantics.
+      # Supports symbol or string keys and falls back to unknown attributes.
+      #
+      # @param key [#to_s, #to_sym]
+      # @return [Object, nil]
+      def [](key)
+        attrs = attributes
+        return attrs.with_indifferent_access[key] if attrs.respond_to?(:with_indifferent_access)
+
+        return nil if key.nil?
+
+        # Fast path: exact match
+        value = attrs[key]
+        return value unless value.nil?
+
+        # Symbol/string coercions without depending on ActiveSupport
+        if key.respond_to?(:to_sym)
+          sym = key.to_sym
+          return attrs[sym] if attrs.key?(sym)
+        end
+
+        if key.respond_to?(:to_s)
+          str = key.to_s
+          return attrs[str] if attrs.key?(str)
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/search_engine/base/index_maintenance/cleanup.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module SearchEngine
+  class Base
+    module IndexMaintenance
+      # Cleanup-related helpers for the SearchEngine DSL.
+      module Cleanup
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Return a chainable Relation of stale documents compiled from `stale` rules.
+          #
+          # Compiles all `stale` entries declared in the indexing DSL for the
+          # given partition and returns a Relation for the merged filter (OR semantics).
+          # When no rules are present or the effective filter resolves to blank,
+          # returns an empty relation.
+          #
+          # @param partition [Object, nil] optional partition token passed to the filter block
+          # @return [SearchEngine::Relation]
+          def stale(partition: nil)
+            filters = SearchEngine::StaleRules.compile_filters(self, partition: partition)
+            merged = SearchEngine::StaleRules.merge_filters(filters)
+
+            if merged.nil? || merged.to_s.strip.empty?
+              # Impossible but valid predicate to ensure an empty Relation when there are no stale rules
+              return all.where('id:="__se_none__" && id:!="__se_none__"')
+            end
+
+            all.where(merged)
+          end
+
+          # Delete stale documents from the collection according to DSL rules.
+          #
+          # Evaluates all stale definitions declared via the indexing DSL,
+          # building a filter that deletes matching documents
+          # using {SearchEngine::Deletion.delete_by}. When no stale configuration
+          # is present, the method logs a skip message and returns 0.
+          #
+          # @param into [String, nil] optional physical collection override
+          # @param partition [Object, nil] optional partition token forwarded to resolvers
+          # @param clear_cache [Boolean] clear Typesense cache after cleanup
+          # @return [Integer] number of deleted documents
+          def cleanup(into: nil, partition: nil, clear_cache: false)
+            logical = respond_to?(:collection) ? collection.to_s : name.to_s
+            puts
+            puts(%(>>>>>> Cleanup Collection "#{logical}"))
+
+            filters = SearchEngine::StaleRules.compile_filters(self, partition: partition)
+            filters.compact!
+            filters.reject! { |f| f.to_s.strip.empty? }
+            if filters.empty?
+              puts('Cleanup — skip (no stale configuration)')
+              return 0
+            end
+
+            merged_filter = SearchEngine::StaleRules.merge_filters(filters)
+            puts("Cleanup — filter=#{merged_filter.inspect}")
+
+            deleted = SearchEngine::Deletion.delete_by(
+              klass: self,
+              filter: merged_filter,
+              into: into,
+              partition: partition
+            )
+
+            puts("Cleanup — deleted=#{deleted}")
+            deleted
+          rescue StandardError => error
+            warn(
+              "Cleanup — error=#{error.class}: #{error.message.to_s[0, 200]}"
+            )
+            0
+          ensure
+            if clear_cache
+              begin
+                puts('Cleanup — cache clear')
+                SearchEngine::Cache.clear
+              rescue StandardError => error
+                warn(
+                  "Cleanup — cache clear error=#{error.class}: #{error.message.to_s[0, 200]}"
+                )
+              end
+            end
+            puts(%(>>>>>> Cleanup Done))
+          end
+
+          private
+
+          def build_scope_filters(entries, partition: nil)
+            filters = entries
+                      .select { |entry| entry[:type] == :scope }
+                      .map do |entry|
+                        scope = entry[:name]
+                        next unless respond_to?(scope)
+
+                        rel = invoke_scope(scope, partition)
+                        next unless rel.is_a?(SearchEngine::Relation)
+
+                        rel.filter_params
+                      end
+            filters.compact
+          rescue StandardError
+            []
+          end
+
+          def build_attribute_filters(entries)
+            filters = entries
+                      .select { |entry| entry[:type] == :attribute }
+                      .map do |entry|
+                        attr = entry[:name]
+                        val = entry[:value]
+                        relation_for({ attr => val })&.filter_params
+                      end
+            filters.compact
+          rescue StandardError
+            []
+          end
+
+          def build_hash_filters(entries)
+            filters = entries
+                      .select { |entry| entry[:type] == :hash }
+                      .map { |entry| relation_for(entry[:hash])&.filter_params }
+            filters.compact
+          rescue StandardError
+            []
+          end
+
+          def build_raw_filters(entries, partition: nil)
+            raw = entries.select { |entry| %i[filter relation block].include?(entry[:type]) }
+
+            filters = raw.flat_map do |entry|
+              case entry[:type]
+              when :filter then entry[:value]
+              when :relation then entry[:relation]&.filter_params
+              when :block
+                evaluate_block_entry(entry[:block], partition: partition)
+              end
+            end
+            Array(filters).compact
+          rescue StandardError
+            []
+          end
+
+          def merge_filters(filters)
+            return filters.first if filters.size == 1
+
+            fragments = filters.map do |filter|
+              next if filter.to_s.strip.empty?
+
+              "(#{filter})"
+            end.compact
+
+            fragments.join(' || ')
+          end
+
+          def relation_for(hash)
+            SearchEngine::Relation.new(self).where(hash)
+          end
+
+          def evaluate_block_entry(block, partition: nil)
+            params = block.parameters
+            result = if params.any? { |(kind, name)| %i[key keyreq].include?(kind) && name == :partition }
+                       instance_exec(partition: partition, &block)
+                     elsif block.arity.positive?
+                       instance_exec(partition, &block)
+                     else
+                       instance_exec(&block)
+                     end
+
+            case result
+            when String then result
+            when Hash then relation_for(result)&.filter_params
+            when SearchEngine::Relation then result.filter_params
+            end
+          rescue StandardError
+            nil
+          end
+
+          def invoke_scope(scope, partition)
+            method_obj = method(scope)
+            params = method_obj.parameters
+            if params.empty?
+              public_send(scope)
+            elsif params.any? do |(kind, name)|
+              %i[key keyreq].include?(kind) && %i[partition _partition].include?(name)
+            end
+              public_send(scope, partition: partition)
+            elsif params.first && %i[req opt].include?(params.first.first)
+              public_send(scope, partition)
+            else
+              public_send(scope)
+            end
+          rescue ArgumentError
+            public_send(scope)
+          end
+        end
+      end
+    end
+  end
+end