search-engine-for-typesense 1.0.0

data/lib/generators/search_engine/model/model_generator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/named_base'
+
+begin
+  require 'did_you_mean'
+rescue LoadError
+  # did_you_mean is optional; suggestions will be skipped if unavailable
+end
+
+module SearchEngine
+  module Generators
+    # Model generator that creates a minimal SearchEngine model mapping to a
+    # Typesense collection.
+    #
+    # @example
+    #   rails g search_engine:model Product --collection products --attrs id:integer name:string
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx
+    class ModelGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      class_option :collection, type: :string, desc: 'Logical Typesense collection name (required)'
+      class_option :attrs,
+                   type: :string,
+                   default: nil,
+                   desc: 'Attribute declarations as key:type pairs (space/comma-separated)'
+
+      def validate_options!
+        return if options[:collection].to_s.strip.present?
+
+        raise Thor::Error,
+              '--collection is required. See ' \
+              'https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/dx#generators--console-helpers'
+      end
+
+      def create_model
+        @collection_name = options[:collection].to_s.strip
+        @attributes = parse_attrs(options[:attrs])
+        template 'model.rb.tt', File.join(search_engine_models_path, "#{file_name}.rb")
+      end
+
+      private
+
+      ALLOWED_TYPES = %w[string integer float boolean datetime json].freeze
+
+      def parse_attrs(raw)
+        return [] if raw.nil?
+
+        tokens = raw.split(/[\s,]+/).map(&:strip).reject(&:empty?)
+        tokens.map do |pair|
+          name, type = pair.split(':', 2)
+          raise Thor::Error, "invalid attribute token: #{pair.inspect} (expected name:type)" unless name
+
+          type = (type || 'string').to_s
+          normalized = normalize_type(type)
+          [name.to_s.underscore, normalized]
+        end
+      end
+
+      def normalize_type(type)
+        t = type.to_s.strip.downcase
+        return t if ALLOWED_TYPES.include?(t)
+
+        suggestion = suggest_type(t)
+        hint = suggestion ? "; did you mean #{suggestion.inspect}?" : ''
+        raise Thor::Error, "Unknown attribute type #{t.inspect}; allowed: #{ALLOWED_TYPES.join(', ')}#{hint}"
+      end
+
+      def suggest_type(token)
+        return nil unless defined?(DidYouMean::SpellChecker)
+
+        DidYouMean::SpellChecker.new(dictionary: ALLOWED_TYPES).correct(token).first
+      end
+
+      def search_engine_models_path
+        cfg = SearchEngine.respond_to?(:config) ? SearchEngine.config : nil
+        raw = cfg.respond_to?(:search_engine_models) ? cfg.search_engine_models : nil
+        return 'app/search_engine' if raw.nil? || raw == false
+
+        path = raw.to_s.strip
+        path.empty? ? 'app/search_engine' : path
+      end
+    end
+  end
+end

data/lib/generators/search_engine/model/templates/model.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Minimal SearchEngine model generated by `search_engine:model`.
+# Docs:
+# - https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/quickstart
+# - https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/field-selection#guardrails--errors
+class SearchEngine::<%= class_name %> < SearchEngine::Base
+  collection "<%= @collection_name %>"
+<% Array(@attributes).each do |(name, type)| -%>
+  attribute :<%= name %>, :<%= type %>
+<% end -%>
+end

data/lib/search-engine-for-typesense.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Compatibility shim for Bundler's `require: true` auto-require using the
+# gem name `search-engine-for-typesense`.
+#
+# This file must not define any constants. It simply requires the proper
+# entrypoint so that `SearchEngine` and its engine/config are loaded.
+#
+# It is intentionally ignored by the engine's Zeitwerk loader to avoid
+# attempts to constantize the hyphenated filename.
+
+require 'search_engine'

data/lib/search_engine/active_record_syncable.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module SearchEngine
+  # ActiveRecord concern to keep a Typesense collection in sync.
+  #
+  # Include into an AR model and call {.search_engine_syncable} to install
+  # lifecycle callbacks that upsert on create/update and delete on destroy.
+  #
+  # @example
+  #   class Product < ApplicationRecord
+  #     include SearchEngine::ActiveRecordSyncable
+  #     search_engine_syncable on: %i[create update destroy], collection: :products
+  #   end
+  module ActiveRecordSyncable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Configure SearchEngine synchronization for this ActiveRecord model.
+      #
+      # - collection: defaults to the AR class tableized name (snake_case, plural)
+      # - on: one or many of :create, :update, :destroy (strings or symbols)
+      #
+      # Validates that either a physical Typesense collection exists for the
+      # given name or a SearchEngine model is registered for it. Mapping for
+      # create/update requires a SearchEngine model; when missing, an error is
+      # raised with guidance.
+      #
+      # @param collection [Symbol, String, nil]
+      # @param on [Array<Symbol,String>, Symbol, String, nil]
+      # @return [Class] self (for macro chaining)
+      def search_engine_syncable(collection: nil, on: nil)
+        effective_actions = on
+
+        cfg = SearchEngine::ActiveRecordSyncable.__normalize_config_for(
+          self,
+          collection: collection,
+          actions: effective_actions
+        )
+
+        # Store config on the AR class (used by instance methods)
+        instance_variable_set(:@__se_syncable_cfg__, cfg)
+
+        SearchEngine::ActiveRecordSyncable.__register_callbacks_for(self, cfg)
+        self
+      end
+    end
+
+    # Upsert this record into the configured Typesense collection using the
+    # mapping defined on the corresponding SearchEngine model.
+    # @return [void]
+    def __se_syncable_upsert!
+      cfg = self.class.instance_variable_get(:@__se_syncable_cfg__) || {}
+      se_klass = cfg[:se_klass]
+      unless se_klass
+        # Lazy-resolve the SearchEngine model to avoid boot-time ordering issues
+        begin
+          se_klass = SearchEngine.collection_for(cfg[:logical])
+          cfg[:se_klass] = se_klass if se_klass
+        rescue StandardError
+          se_klass = nil
+        end
+      end
+      unless se_klass
+        SearchEngine.config.logger&.warn(
+          "search_engine_syncable: no SearchEngine model registered for '#{cfg[:logical]}'; skip upsert"
+        )
+        return
+      end
+
+      se_klass.upsert(record: self)
+    rescue StandardError => error
+      SearchEngine.config.logger&.error("search_engine_syncable upsert failed: #{error}")
+    end
+
+    # Delete this record's document from the configured Typesense collection.
+    # Uses the SearchEngine model's identity strategy when available.
+    # @return [void]
+    def __se_syncable_delete!
+      cfg = self.class.instance_variable_get(:@__se_syncable_cfg__) || {}
+      logical = cfg[:logical]
+      se_klass = cfg[:se_klass]
+
+      document_id = if se_klass
+                      se_klass.compute_document_id(self)
+                    else
+                      respond_to?(:id) ? id.to_s : nil
+                    end
+
+      if document_id.nil? || document_id.strip.empty?
+        SearchEngine.config.logger&.warn(
+          "search_engine_syncable: cannot delete without id for '#{logical}'"
+        )
+        return
+      end
+
+      client = SearchEngine.client
+      into = client.resolve_alias(logical) || logical
+      client.delete_document(collection: into, id: document_id)
+    rescue StandardError => error
+      SearchEngine.config.logger&.error("search_engine_syncable delete failed: #{error}")
+    end
+
+    # Return the associated SearchEngine record for this ActiveRecord instance.
+    #
+    # Resolves the SearchEngine model lazily when necessary and computes the
+    # document id via the model's `identify_by` strategy. Returns nil when the
+    # model mapping is unavailable or the id cannot be determined.
+    #
+    # @return [Object, nil] hydrated SearchEngine model instance or nil when not found
+    def search_engine_record
+      cfg = self.class.instance_variable_get(:@__se_syncable_cfg__) || {}
+      se_klass = cfg[:se_klass]
+      if se_klass.nil?
+        begin
+          logical = cfg[:logical] || self.class.name.to_s
+          se_klass = SearchEngine.collection_for(logical)
+          cfg[:se_klass] = se_klass if se_klass
+        rescue StandardError
+          return nil
+        end
+      end
+
+      doc_id = begin
+        se_klass.compute_document_id(self)
+      rescue StandardError => error
+        # When a custom identify_by is configured on the SearchEngine model,
+        # do not fall back to the ActiveRecord id on computation errors as it
+        # may point to a different document. Only fall back to AR id when
+        # identify_by is not defined at all.
+        if se_klass.instance_variable_defined?(:@identify_by_proc)
+          SearchEngine.config.logger&.warn(
+            "search_engine_syncable: identify_by failed to compute id for '#{cfg[:logical]}' (#{error.class})"
+          )
+          nil
+        else
+          respond_to?(:id) ? id.to_s : nil
+        end
+      end
+      return nil if doc_id.nil? || doc_id.to_s.strip.empty?
+
+      se_klass.find(doc_id)
+    rescue StandardError
+      nil
+    end
+
+    # Map this ActiveRecord instance using the associated SearchEngine model and
+    # upsert it into the collection.
+    #
+    # @return [Integer] number of upserted documents (0 or 1)
+    def sync_search_engine_record
+      cfg = self.class.instance_variable_get(:@__se_syncable_cfg__) || {}
+      se_klass = cfg[:se_klass]
+      if se_klass.nil?
+        begin
+          logical = cfg[:logical] || self.class.name.to_s
+          se_klass = SearchEngine.collection_for(logical)
+          cfg[:se_klass] = se_klass if se_klass
+        rescue StandardError => error
+          SearchEngine.config.logger&.warn(
+            "search_engine_syncable: cannot resolve model for sync (#{error.class})"
+          )
+          return 0
+        end
+      end
+
+      se_klass.upsert(record: self)
+    rescue StandardError => error
+      SearchEngine.config.logger&.error("search_engine_syncable sync failed: #{error}")
+      0
+    end
+
+    module_function
+
+    # @api private
+    # @param ar_klass [Class]
+    # @param collection [String,Symbol,nil]
+    # @param actions [Array<String,Symbol>, String, Symbol, nil]
+    # @return [Hash]
+    def __normalize_config_for(ar_klass, collection:, actions:)
+      require 'active_support/inflector'
+
+      logical = (collection || ActiveSupport::Inflector.tableize(ar_klass.name)).to_s
+      normalized_actions = __normalize_actions(actions)
+
+      # Best-effort resolve SearchEngine model now; fall back to lazy resolution
+      se_klass = begin
+        SearchEngine.collection_for(logical)
+      rescue StandardError
+        nil
+      end
+
+      if se_klass.nil? && (normalized_actions.include?(:create) || normalized_actions.include?(:update))
+        SearchEngine.config.logger&.warn(
+          "search_engine_syncable: mapping for '#{logical}' not found at boot; will resolve lazily at runtime"
+        )
+      end
+
+      {
+        logical: logical,
+        actions: normalized_actions,
+        se_klass: se_klass
+      }
+    end
+
+    # @api private
+    # @param actions [Array<String,Symbol>, String, Symbol, nil]
+    # @return [Array<Symbol>]
+    def __normalize_actions(actions)
+      allowed = %i[create update destroy]
+      list =
+        if actions.nil?
+          allowed
+        else
+          Array(actions).map { |a| a.to_s.downcase.strip.to_sym }
+        end
+
+      invalid = list - allowed
+      raise ArgumentError, "search_engine_syncable: actions must be within #{allowed.inspect}" unless invalid.empty?
+
+      list.uniq
+    end
+
+    # (no-op placeholder kept for backwards compatibility of method table in case of reloads)
+
+    # @api private
+    # @param ar_klass [Class]
+    # @param cfg [Hash]
+    # @return [void]
+    def __register_callbacks_for(ar_klass, cfg)
+      if ar_klass.instance_variable_defined?(:@__se_syncable_callbacks_installed__) &&
+         ar_klass.instance_variable_get(:@__se_syncable_callbacks_installed__)
+        return
+      end
+
+      actions = cfg[:actions]
+
+      ar_klass.after_create :__se_syncable_upsert! if actions.include?(:create)
+      ar_klass.after_update :__se_syncable_upsert! if actions.include?(:update)
+      ar_klass.after_destroy :__se_syncable_delete! if actions.include?(:destroy)
+
+      ar_klass.instance_variable_set(:@__se_syncable_callbacks_installed__, true)
+      nil
+    end
+  end
+end

data/lib/search_engine/admin/stopwords.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  module Admin
+    # Manage stopword sets for a collection.
+    #
+    # @since 0.1.0
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/synonyms-stopwords#management
+    # @see `https://typesense.org/docs/latest/api/stopwords.html`
+    module Stopwords
+      class << self
+        # Upsert a stopword set by ID.
+        #
+        # @param collection [String]
+        # @param id [String]
+        # @param terms [Array<#to_s>]
+        # @return [Hash] summary { status: :created|:updated, id:, terms_count: Integer }
+        # @example
+        #   SearchEngine::Admin::Stopwords.upsert!(collection: "products", id: "common", terms: %w[the and])
+        # @see SearchEngine::Admin::Synonyms.upsert!
+        # @see `https://typesense.org/docs/latest/api/stopwords.html#upsert-a-stopwords`
+        def upsert!(collection:, id:, terms:)
+          c = normalize_collection!(collection)
+          sid = normalize_id!(id)
+          list = normalize_terms!(terms)
+
+          existed = exists?(c, sid)
+          ts_res = client.stopwords_upsert(collection: c, id: sid, terms: list)
+          status = existed ? :updated : :created
+          instrument(:upsert, collection: c, id: sid, terms_count: list.size)
+          { status: status, id: sid, terms_count: list.size, response: ts_res }
+        end
+
+        # Retrieve a stopword set by ID.
+        # @param collection [String]
+        # @param id [String]
+        # @return [Hash, nil] { id:, terms: [] } or nil when not found
+        # @see `https://typesense.org/docs/latest/api/stopwords.html#retrieve-a-stopword`
+        def get(collection:, id:)
+          c = normalize_collection!(collection)
+          sid = normalize_id!(id)
+          res = client.stopwords_get(collection: c, id: sid)
+          return nil unless res
+
+          { id: sid, terms: Array(res[:stopwords] || res['stopwords']).map(&:to_s) }
+        rescue SearchEngine::Errors::Api => error
+          return nil if error.status.to_i == 404
+
+          raise
+        end
+
+        # List all stopword sets for a collection.
+        # @param collection [String]
+        # @return [Array<Hash>] list of { id:, terms: [] }
+        # @see `https://typesense.org/docs/latest/api/stopwords.html#list-all-stopwords-of-a-collection`
+        def list(collection:)
+          c = normalize_collection!(collection)
+          res = client.stopwords_list(collection: c)
+          Array(res).map do |item|
+            { id: (item[:id] || item['id']).to_s, terms: Array(item[:stopwords] || item['stopwords']).map(&:to_s) }
+          end
+        end
+
+        # Delete a stopword set by ID (idempotent).
+        # @param collection [String]
+        # @param id [String]
+        # @return [true]
+        # @see `https://typesense.org/docs/latest/api/stopwords.html#delete-a-stopword`
+        def delete!(collection:, id:)
+          c = normalize_collection!(collection)
+          sid = normalize_id!(id)
+          client.stopwords_delete(collection: c, id: sid)
+          instrument(:delete, collection: c, id: sid)
+          true
+        rescue SearchEngine::Errors::Api => error
+          return true if error.status.to_i == 404
+
+          raise
+        end
+
+        private
+
+        def client
+          @client ||= SearchEngine.client
+        end
+
+        def normalize_collection!(value)
+          s = value.to_s
+          raise ArgumentError, 'collection must be a non-empty String' if s.strip.empty?
+
+          s
+        end
+
+        def normalize_id!(value)
+          s = value.to_s
+          raise ArgumentError, 'id must be a non-empty String' if s.strip.empty?
+          raise ArgumentError, 'id too long (max 256)' if s.length > 256
+          raise ArgumentError, 'id contains invalid characters' unless s.match?(/\A[\w\-:.]+\z/)
+
+          s
+        end
+
+        def normalize_terms!(list)
+          arr = Array(list).flatten.compact.map { |t| t.to_s.strip.downcase }.reject(&:empty?)
+          arr.uniq!
+          raise ArgumentError, 'terms must include at least one non-empty String' if arr.empty?
+
+          arr
+        end
+
+        def exists?(collection, id)
+          !!client.stopwords_get(collection: collection, id: id)
+        rescue SearchEngine::Errors::Api => error
+          return false if error.status.to_i == 404
+
+          raise
+        end
+
+        def instrument(action, payload)
+          SearchEngine::Instrumentation.instrument("search_engine.admin.stopwords.#{action}", payload) {}
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/admin/synonyms.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  module Admin
+    # Manage synonym sets for a collection.
+    #
+    # @since 0.1.0
+    # @see https://nikita-shkoda.mintlify.app/projects/search-engine-for-typesense/synonyms-stopwords#management
+    # @see `https://typesense.org/docs/latest/api/synonyms.html`
+    module Synonyms
+      class << self
+        # Upsert a synonym set by ID.
+        #
+        # @param collection [String]
+        # @param id [String]
+        # @param terms [Array<#to_s>]
+        # @return [Hash] summary { status: :created|:updated, id:, terms_count: Integer }
+        # @example
+        #   SearchEngine::Admin::Synonyms.upsert!(collection: "products", id: "colors", terms: %w[color colour])
+        # @see SearchEngine::Admin::Stopwords.upsert!
+        # @see `https://typesense.org/docs/latest/api/synonyms.html#upsert-a-synonym`
+        def upsert!(collection:, id:, terms:)
+          c = normalize_collection!(collection)
+          sid = normalize_id!(id)
+          list = normalize_terms!(terms)
+
+          existed = exists?(c, sid)
+          ts_res = client.synonyms_upsert(collection: c, id: sid, terms: list)
+          status = existed ? :updated : :created
+          instrument(:upsert, collection: c, id: sid, terms_count: list.size)
+          { status: status, id: sid, terms_count: list.size, response: ts_res }
+        end
+
+        # Retrieve a synonym set by ID.
+        # @param collection [String]
+        # @param id [String]
+        # @return [Hash, nil] { id:, terms: [] } or nil when not found
+        # @see `https://typesense.org/docs/latest/api/synonyms.html#retrieve-a-synonym`
+        def get(collection:, id:)
+          c = normalize_collection!(collection)
+          sid = normalize_id!(id)
+          res = client.synonyms_get(collection: c, id: sid)
+          return nil unless res
+
+          { id: sid, terms: Array(res[:synonyms] || res['synonyms']).map(&:to_s) }
+        rescue SearchEngine::Errors::Api => error
+          return nil if error.status.to_i == 404
+
+          raise
+        end
+
+        # List all synonym sets for a collection.
+        # @param collection [String]
+        # @return [Array<Hash>] list of { id:, terms: [] }
+        # @see `https://typesense.org/docs/latest/api/synonyms.html#list-all-synonyms-of-a-collection`
+        def list(collection:)
+          c = normalize_collection!(collection)
+          res = client.synonyms_list(collection: c)
+          Array(res).map do |item|
+            { id: (item[:id] || item['id']).to_s, terms: Array(item[:synonyms] || item['synonyms']).map(&:to_s) }
+          end
+        end
+
+        # Delete a synonym set by ID (idempotent).
+        # @param collection [String]
+        # @param id [String]
+        # @return [true]
+        # @see `https://typesense.org/docs/latest/api/synonyms.html#delete-a-synonym`
+        def delete!(collection:, id:)
+          c = normalize_collection!(collection)
+          sid = normalize_id!(id)
+          client.synonyms_delete(collection: c, id: sid)
+          instrument(:delete, collection: c, id: sid)
+          true
+        rescue SearchEngine::Errors::Api => error
+          return true if error.status.to_i == 404
+
+          raise
+        end
+
+        private
+
+        def client
+          @client ||= SearchEngine.client
+        end
+
+        def normalize_collection!(value)
+          s = value.to_s
+          raise ArgumentError, 'collection must be a non-empty String' if s.strip.empty?
+
+          s
+        end
+
+        def normalize_id!(value)
+          s = value.to_s
+          raise ArgumentError, 'id must be a non-empty String' if s.strip.empty?
+          raise ArgumentError, 'id too long (max 256)' if s.length > 256
+          raise ArgumentError, 'id contains invalid characters' unless s.match?(/\A[\w\-:.]+\z/)
+
+          s
+        end
+
+        def normalize_terms!(list)
+          arr = Array(list).flatten.compact.map { |t| t.to_s.strip.downcase }.reject(&:empty?)
+          arr.uniq!
+          raise ArgumentError, 'terms must include at least one non-empty String' if arr.empty?
+
+          arr
+        end
+
+        def exists?(collection, id)
+          !!client.synonyms_get(collection: collection, id: id)
+        rescue SearchEngine::Errors::Api => error
+          return false if error.status.to_i == 404
+
+          raise
+        end
+
+        def instrument(action, payload)
+          SearchEngine::Instrumentation.instrument("search_engine.admin.synonyms.#{action}", payload) {}
+        end
+      end
+    end
+  end
+end

data/lib/search_engine/admin.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  # Admin namespace for management APIs (synonyms/stopwords).
+  #
+  # Provides thin, validated wrappers over Typesense admin endpoints and
+  # emits structured instrumentation. Pure stdlib + typesense gem only.
+  module Admin; end
+end
+
+require 'search_engine/admin/synonyms'
+require 'search_engine/admin/stopwords'

data/lib/search_engine/ast/and.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SearchEngine
+  module AST
+    # Boolean conjunction over one or more child nodes.
+    class And < Node
+      attr_reader :children
+
+      def initialize(*nodes)
+        super()
+        normalized = normalize(nodes)
+        raise ArgumentError, 'and_ requires at least one child node' if normalized.empty?
+
+        @children = deep_freeze_array(normalized)
+        freeze
+      end
+
+      def type = :and
+
+      def to_s
+        "and(#{children.map(&:to_s).join(', ')})"
+      end
+
+      protected
+
+      def equality_key
+        [:and, @children]
+      end
+
+      def inspect_payload
+        inner = children.map(&:to_s).join(', ')
+        truncate_for_inspect(inner)
+      end
+
+      private
+
+      def normalize(nodes)
+        flat = []
+        Array(nodes).flatten.compact.each do |n|
+          next unless n.is_a?(Node)
+
+          if n.is_a?(And)
+            flat.concat(n.children)
+          else
+            flat << n
+          end
+        end
+        flat
+      end
+    end
+  end
+end