search-engine-for-typesense 1.0.0

data/lib/search_engine/console_helpers.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+begin
+  require 'active_support/inflector'
+rescue LoadError
+  # ActiveSupport may not be available outside Rails; constant lookup will fallback
+end
+
+module SearchEngine
+  # Console-only helpers and installer for the `SE` top-level shortcut.
+  #
+  # In Rails console, the engine installs `::SE` so you can quickly build and
+  # run queries interactively.
+  module ConsoleHelpers
+    # Install the top-level `SE` constant unless already defined.
+    # @return [void]
+    def self.install!
+      return if Object.const_defined?(:SE)
+
+      Object.const_set(:SE, HelpersModule)
+      nil
+    end
+
+    # Internal module backing the `SE` constant.
+    module HelpersModule
+      module_function
+
+      # Run a simple search on a default model with optional overrides.
+      #
+      # Default model resolution:
+      # - Prefer `SearchEngine.config.default_console_model` (Class or String)
+      # - Fallback to the sole registered model in the collection registry
+      # - Raise a helpful error if ambiguous or none are found
+      #
+      # @param query [String, nil]
+      # @param opts [Hash] common options (e.g., select:, per:, page:, where:, query_by:, ...)
+      # @return [SearchEngine::Relation]
+      # @example
+      #   SE.q('milk').per(5)
+      #   SE.q.where(category: 'dairy')
+      # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx
+      def q(query = nil, **opts)
+        model = default_model!
+        rel = model.all
+        rel = rel.options(q: query) unless query.nil?
+
+        select_opt = opts.delete(:select)
+        rel = rel.select(*Array(select_opt)) if select_opt
+
+        where_opt = opts.delete(:where)
+        rel = rel.where(where_opt) if where_opt
+
+        per_opt = opts.delete(:per) || opts.delete(:per_page)
+        rel = rel.per(per_opt) if per_opt
+
+        page_opt = opts.delete(:page)
+        rel = rel.page(page_opt) if page_opt
+
+        # Pass remaining options (e.g., query_by:, preset:, grouping)
+        rel.options(opts)
+      end
+
+      # Multi-search convenience wrapper that delegates to SearchEngine.multi_search.
+      # @param common [Hash]
+      # @yieldparam m [SearchEngine::Multi]
+      # @return [SearchEngine::Multi::ResultSet]
+      # @example
+      #   SE.ms { |m| m.add :products, SE.q('milk').per(5) }
+      def ms(common: {}, &block)
+        SearchEngine.multi_search(common: common, &block)
+      end
+
+      # Return a base relation for the default (or provided) model.
+      # @param model [Class, nil]
+      # @return [SearchEngine::Relation]
+      def rel(model = nil)
+        (model || default_model!).all
+      end
+
+      # Resolve the default model, honoring configuration and registry.
+      # @return [Class]
+      # @raise [ArgumentError] with hint and docs link when ambiguous or missing
+      def default_model!
+        cfg = SearchEngine.config
+        if cfg.respond_to?(:default_console_model) && cfg.default_console_model
+          return resolve_model_class(cfg.default_console_model)
+        end
+
+        mapping = SearchEngine::Registry.mapping
+        if mapping.empty?
+          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.'
+        end
+
+        uniq_klasses = mapping.values.uniq
+        return uniq_klasses.first if uniq_klasses.size == 1
+
+        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.'
+      end
+
+      def resolve_model_class(value)
+        return value if value.is_a?(Class) && value < SearchEngine::Base
+
+        name =
+          case value
+          when Symbol then value.to_s
+          when String then value
+          else value.to_s
+          end
+
+        if defined?(ActiveSupport::Inflector)
+          Object.const_get(name)
+        else
+          name.split('::').reduce(Object) { |mod, part| mod.const_get(part) }
+        end
+      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.'
+      end
+
+      private_class_method :resolve_model_class
+    end
+  end
+end

data/lib/search_engine/deletion.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Shared deletion helpers for building filters and deleting documents
+  # across both the mapper DSL and model-level APIs.
+  module Deletion
+    module_function
+
+    # Delete documents by filter string or hash from the physical collection
+    # resolved for the given klass and optional partition.
+    #
+    # @param klass [Class] a SearchEngine::Base subclass
+    # @param filter [String, nil] Typesense filter string (takes precedence over hash)
+    # @param hash [Hash, nil] Hash converted to a filter string via Sanitizer
+    # @param into [String, nil] explicit physical collection name override
+    # @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 as reported by Typesense
+    def delete_by(klass:, filter: nil, hash: nil, into: nil, partition: nil, timeout_ms: nil)
+      filter_str = build_filter(filter, hash)
+      collection = resolve_into(klass: klass, partition: partition, into: into)
+
+      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_documents_by_filter(
+        collection: collection,
+        filter_by: filter_str,
+        timeout_ms: effective_timeout
+      )
+      (resp && (resp[:num_deleted] || resp[:deleted] || resp[:numDeleted])).to_i
+    end
+
+    # Build a Typesense filter string from either a string or a hash.
+    # @param filter [String, nil]
+    # @param hash [Hash, nil]
+    # @return [String]
+    def build_filter(filter, hash)
+      if filter && !filter.to_s.strip.empty?
+        filter.to_s
+      elsif hash.is_a?(Hash) && !hash.empty?
+        fragments = SearchEngine::Filters::Sanitizer.build_from_hash(hash)
+        fragments.join(' && ')
+      else
+        raise ArgumentError, 'delete_by requires a filter string or a non-empty hash'
+      end
+    end
+
+    # Resolve the physical collection name using the same logic as the indexer.
+    # @param klass [Class]
+    # @param partition [Object, nil]
+    # @param into [String, nil]
+    # @return [String]
+    def resolve_into(klass:, partition:, into:)
+      return into if into && !into.to_s.strip.empty?
+
+      # Prefer a context-provided target collection when present (e.g., inside
+      # indexer apply/partial runs). This ensures that delete_by calls inside
+      # before/after hooks target the correct physical collection, avoiding 404s
+      # during the initial apply before the alias exists.
+      begin
+        ctx_into = SearchEngine::Instrumentation.context[:into]
+        return ctx_into if ctx_into && !ctx_into.to_s.strip.empty?
+      rescue StandardError
+        # fall through to default resolution
+      end
+
+      resolver = begin
+        SearchEngine.config.partitioning&.default_into_resolver
+      rescue StandardError
+        nil
+      end
+
+      if resolver.respond_to?(:arity)
+        case resolver.arity
+        when 1
+          val = resolver.call(klass)
+          return val if val && !val.to_s.strip.empty?
+        when 2, -1
+          val = resolver.call(klass, partition)
+          return val if val && !val.to_s.strip.empty?
+        end
+      elsif resolver
+        val = resolver.call(klass)
+        return val if val && !val.to_s.strip.empty?
+      end
+
+      name = if klass.respond_to?(:collection)
+               klass.collection
+             else
+               klass.name.to_s
+             end
+      name.to_s
+    end
+  end
+end

data/lib/search_engine/dispatcher.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Dispatcher routes per-partition rebuilds either synchronously (inline) or via ActiveJob.
+  #
+  # Public API:
+  # - {.dispatch!(klass, partition:, into: nil, mode: nil, queue: nil, metadata: {})}
+  #   Returns a descriptor of what happened (enqueued job id / inline summary, mode used).
+  module Dispatcher
+    # Dispatch a single partition rebuild.
+    #
+    # @param klass [Class] model class inheriting from {SearchEngine::Base}
+    # @param partition [Object] opaque partition key
+    # @param into [String, nil] optional target collection (physical or alias)
+    # @param mode [Symbol, String, nil] :active_job or :inline; falls back to config
+    # @param queue [String, nil] ActiveJob queue override
+    # @param metadata [Hash] small, JSON-safe tracing values
+    # @return [Hash] descriptor of the action performed
+    def self.dispatch!(klass, partition:, into: nil, mode: nil, queue: nil, metadata: {})
+      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',
+          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',
+          details: { klass: klass.to_s }
+        )
+      end
+
+      effective_mode = resolve_mode(mode)
+      case effective_mode
+      when :active_job
+        dispatch_active_job!(klass, partition: partition, into: into, queue: queue, metadata: metadata)
+      else
+        dispatch_inline!(klass, partition: partition, into: into, metadata: metadata)
+      end
+    end
+
+    class << self
+      private
+
+      def resolve_mode(override)
+        m = (override || SearchEngine.config.indexer.dispatch || :inline).to_sym
+        return :active_job if m == :active_job && defined?(::ActiveJob::Base)
+
+        :inline
+      end
+
+      def dispatch_active_job!(klass, partition:, into:, queue:, metadata:)
+        q = (queue || SearchEngine.config.indexer.queue_name || 'search_index').to_s
+        class_name = klass.name.to_s
+        job = SearchEngine::IndexPartitionJob
+              .set(queue: q)
+              .perform_later(class_name, partition, into: into, metadata: metadata || {})
+        payload = {
+          collection: safe_collection_name(klass),
+          partition: partition,
+          into: into,
+          queue: q,
+          job_id: job.job_id
+        }
+        instrument('search_engine.dispatcher.enqueued', payload)
+        {
+          mode: :active_job,
+          collection: payload[:collection],
+          partition: partition,
+          into: into,
+          queue: q,
+          job_id: job.job_id
+        }
+      end
+
+      def dispatch_inline!(klass, partition:, into:, metadata:)
+        started = monotonic_ms
+        payload = {
+          collection: safe_collection_name(klass),
+          partition: partition,
+          into: into,
+          metadata: metadata
+        }
+        instrument('search_engine.dispatcher.inline_started', payload)
+        summary = nil
+        SearchEngine::Instrumentation.with_context(dispatch_mode: :inline) do
+          summary = SearchEngine::Indexer.rebuild_partition!(klass, partition: partition, into: into)
+        end
+        duration = (monotonic_ms - started).round(1)
+        instrument(
+          'search_engine.dispatcher.inline_finished',
+          payload.merge(duration_ms: duration, status: summary.status)
+        )
+        {
+          mode: :inline,
+          collection: payload[:collection],
+          partition: partition,
+          into: into,
+          indexer_summary: summary,
+          duration_ms: duration
+        }
+      rescue StandardError => error
+        instrument(
+          'search_engine.dispatcher.inline_error',
+          payload.merge(error_class: error.class.name, message_truncated: error.message.to_s[0, 200])
+        )
+        raise
+      end
+
+      def instrument(event, payload)
+        SearchEngine::Instrumentation.instrument(event, payload) {}
+      end
+
+      def safe_collection_name(klass)
+        klass.respond_to?(:collection) ? klass.collection.to_s : klass.name.to_s
+      end
+
+      def monotonic_ms
+        SearchEngine::Instrumentation.monotonic_ms
+      end
+    end
+  end
+end