typesense_model 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0396e88e835a9892f58864d4598ec27ece27f4fc749b31df76639d4c71fbd34d'
-  data.tar.gz: 81028cc019492513b25c0628cbbd960693698fc6ba46add32e2f35f36c440d2b
+  metadata.gz: 5ca8300fbc0ea8d083208fe48333fae67c3bba9eadfd97e6041caf9c0717d361
+  data.tar.gz: e0dfdcdd67c114ebbf7fd036a9d28751c50a78c429ccacb877705b3b41fe0863
 SHA512:
-  metadata.gz: 7a056ab185ce24fa77e3419d9ec3bf3584dedafffd7a268fc0602fb785b8efea3c352e44d5831f013d0533535235246fa2d371c0a5548e8abee5372660931fbd
-  data.tar.gz: 82a7412801f57a83b001e6f4f8ff3a6d1e0ee40ecbd225424baa149d2968f60d80b66cbeb6be0a5715eee4a1ad66440c097617df64966e0c69e6f0ce11ac3506
+  metadata.gz: 3b7a4f1590e40d57bc31ea9c5f68d553a979b2d52da2d2e0ca0240654d0ee7e049215242f4f6d6cc0e2043c91e827f07fafe69f437a20774114eed731f2a96fa
+  data.tar.gz: c0ade3dcec5121716a425aa12f864c41275e3f1f29d3e88792459ae81dce7313fd98eb454bd0642f8b35a9d2b7b3f89967a8139f4033f13db02937aaf0d481ec

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- RSpec test suite covering schema, search, base (including the
+  `update_collection` schema-diff logic) and the ActiveRecord extension.
+- GitHub Actions CI: unit specs across Ruby 3.1–3.3 plus an integration job
+  against a live Typesense service container.
+- `Gemfile`, `Rakefile` and `.rspec` for a standard Bundler/RSpec dev workflow.
+- Highlighting and match metadata on search results (`highlights`, `text_match`,
+  `hits_with_meta`) and grouped results support (`grouped_hits`).
+- `Base.multi_search` for issuing several searches in a single request.
+- Configurable `TypesenseModel.logger` used by the sync callbacks.
+
+### Changed
+- `activesupport` requirement raised to `>= 6.0`; minimum Ruby raised to `3.1`.
+- Sync/remove callbacks now log failures via `TypesenseModel.logger` even outside
+  Rails (previously errors were silently swallowed in non-Rails contexts) and
+  rescue `Typesense::Error` specifically instead of all exceptions.
+- `Configuration#client` and `TypesenseProxy.for` memoization are now
+  thread-safe.
+
+### Fixed
+- The gem now requires ActiveSupport string inflections, so standalone (non-Rails)
+  usage of `collection_name` defaults no longer raises `NoMethodError`.
+- The instance `#delete` method was defined under `private` and silently returned
+  `nil` via `method_missing`; it is now public and returns a proper boolean.
+- Gemspec `homepage`/`source_code_uri`/`changelog_uri` corrected to the real
+  repository; added `rubygems_mfa_required` metadata.
+
+## [0.2.0]
+
+- ActiveRecord integration via `uses_typesense` with auto-sync callbacks.
+- Standalone `TypesenseModel::Base` models.
+- Schema definition, diff-based `update_collection`, bulk import and search with
+  Pagy-compatible results.

data/README.md

@@ -202,6 +202,102 @@ results = Product.import_all_to_typesense(
 # results => { success: 500, failed: 0, errors: [...] }
 ```
 
+## Advanced search
+
+### Highlights, scores and grouped results
+
+`search` returns a `SearchResults` that, beyond enumerating records, exposes the
+search metadata Typesense returns:
+
+```ruby
+results = Product.search("running shoe")
+
+# Each record paired with its highlights and relevance score
+results.hits_with_meta.each do |hit|
+  hit[:record]      # => Product-like document
+  hit[:highlights]  # => [{ "field" => "title", ... }]
+  hit[:text_match]  # => relevance score
+end
+
+# When searching with group_by:
+grouped = Product.search("shoe", group_by: "brand")
+grouped.grouped_hits.each do |group|
+  group[:group_key] # => ["Nike"]
+  group[:hits]      # => [records...]
+end
+```
+
+Geo and vector search parameters are passed straight through as options, e.g.
+`Product.search("*", filter_by: "location:(48.8,2.3,5 km)")`.
+
+### Multi-search
+
+Issue several queries in a single request:
+
+```ruby
+results = Product.multi_search([
+  { q: "shoe" },
+  { q: "boot", filter_by: "price:>100" }
+])
+results.first.total_hits
+```
+
+### Synonyms and overrides (curation)
+
+```ruby
+Product.upsert_synonym("coat-synonyms", synonyms: %w[coat jacket parka])
+Product.upsert_override("promote-nike", rule: { query: "shoe", match: "exact" },
+                                        includes: [{ id: "1", position: 1 }])
+```
+
+## Async syncing
+
+Pass `async: true` to perform the Typesense write in an ActiveJob instead of
+inline in the `after_save`/`after_destroy` callbacks:
+
+```ruby
+class Product < ApplicationRecord
+  uses_typesense collection: "products", async: true do |s|
+    s.field :id, :string
+    s.field :title, :string
+  end
+end
+```
+
+Requires ActiveJob; the job (`TypesenseModel::SyncJob`) reloads the record and
+syncs it on whatever queue adapter your app is configured with.
+
+## Configuration
+
+Failures in the background sync callbacks are logged rather than raised. By
+default they go to `Rails.logger` (or `$stderr` outside Rails); override with:
+
+```ruby
+TypesenseModel.logger = MyLogger.new
+```
+
+## Development
+
+After checking out the repo, install dependencies and run the test suite:
+
+```bash
+bundle install
+bundle exec rake          # runs the unit specs (Typesense client is mocked)
+```
+
+Integration specs talk to a real Typesense server and are skipped by default.
+To run them, start a local Typesense instance and set `TYPESENSE_INTEGRATION`:
+
+```bash
+TYPESENSE_INTEGRATION=1 TYPESENSE_API_KEY=test-key bundle exec rspec --tag integration
+```
+
+To build the gem locally:
+
+```bash
+gem build typesense_model.gemspec
+```
+
 ## License
 
 Available as open source under the MIT License.

data/lib/typesense_model/active_record_extension.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module TypesenseModel
   module ActiveRecordExtension
     def self.included(base)
@@ -6,9 +8,10 @@ module TypesenseModel
 
     module ClassMethods
       # Usage: uses_typesense collection: 'plugs', model_json: :as_json, schema: ->(s) { s.field :id, :string }
-      def uses_typesense(collection: nil, model_json: :as_json_typesense, schema: nil, &block)
+      def uses_typesense(collection: nil, model_json: :as_json_typesense, schema: nil, async: false, &block)
         @_typesense_collection_name = collection || name.underscore.pluralize
         @_typesense_model_json_method = model_json
+        @_typesense_async = async
 
         if schema
           @_typesense_schema = Schema.new
@@ -30,6 +33,10 @@ module TypesenseModel
           @_typesense_model_json_method
         end
 
+        define_singleton_method(:typesense_async?) do
+          @_typesense_async
+        end
+
         define_singleton_method(:search) do |query, options = {}|
           proxy = TypesenseProxy.for(self)
           proxy.search(query, options)
@@ -59,10 +66,30 @@ module TypesenseModel
       end
     end
 
+    # Enqueue an async sync via ActiveJob. Kept as a module method so it can be
+    # stubbed in tests and so the job lookup lives in one place.
+    def self.enqueue_sync(class_name, id, action)
+      unless defined?(ActiveJob::Base) && defined?(TypesenseModel::SyncJob)
+        raise TypesenseModel::Error, "async: true requires ActiveJob to be available"
+      end
+      TypesenseModel::SyncJob.perform_later(class_name, id, action.to_s)
+    end
+
     # Instance methods for callbacks
     def sync_to_typesense
       return unless self.class.respond_to?(:typesense_model_json_method)
-      
+
+      if self.class.respond_to?(:typesense_async?) && self.class.typesense_async?
+        ActiveRecordExtension.enqueue_sync(self.class.name, id.to_s, :upsert)
+      else
+        sync_to_typesense_now
+      end
+    end
+
+    # Synchronously write this record's document to Typesense.
+    def sync_to_typesense_now
+      return unless self.class.respond_to?(:typesense_model_json_method)
+
       json_method = self.class.typesense_model_json_method
       document_data = if json_method.is_a?(Proc)
         json_method.call(self)
@@ -73,17 +100,28 @@ module TypesenseModel
       proxy = TypesenseProxy.for(self.class)
       sanitized = proxy.send(:sanitize_document, stringify_keys(document_data))
       proxy.client.collections[proxy.collection_name].documents.upsert(sanitized)
-    rescue => e
-      Rails.logger.error "Failed to sync #{self.class.name}##{id} to Typesense: #{e.message}" if defined?(Rails)
+    rescue Typesense::Error => e
+      TypesenseModel.logger.error("Failed to sync #{self.class.name}##{id} to Typesense: #{e.message}")
     end
 
     def remove_from_typesense
       return unless self.class.respond_to?(:typesense_model_json_method)
-      
+
+      if self.class.respond_to?(:typesense_async?) && self.class.typesense_async?
+        ActiveRecordExtension.enqueue_sync(self.class.name, id.to_s, :remove)
+      else
+        remove_from_typesense_now
+      end
+    end
+
+    # Synchronously delete this record's document from Typesense.
+    def remove_from_typesense_now
+      return unless self.class.respond_to?(:typesense_model_json_method)
+
       proxy = TypesenseProxy.for(self.class)
       proxy.client.collections[proxy.collection_name].documents[id].delete
-    rescue => e
-      Rails.logger.error "Failed to remove #{self.class.name}##{id} from Typesense: #{e.message}" if defined?(Rails)
+    rescue Typesense::Error => e
+      TypesenseModel.logger.error("Failed to remove #{self.class.name}##{id} from Typesense: #{e.message}")
     end
 
     # Default JSON method for Typesense
@@ -98,27 +136,49 @@ module TypesenseModel
       hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
     end
 
-    # Simple adapter that maps an AR model class into a TypesenseModel::Base-like class
+    # Adapter that maps an AR model class into a TypesenseModel::Base-like class.
+    #
+    # A dedicated proxy subclass is built and memoized per AR model so that the
+    # collection name and schema never clobber each other across models or
+    # threads -- each subclass carries its own class-level state.
     class TypesenseProxy < TypesenseModel::Base
       class << self
+        PROXY_MUTEX = Mutex.new
+
         def for(ar_class)
-          @ar_class = ar_class
-          collection_name(ar_class.respond_to?(:typesense_collection_name) ? ar_class.typesense_collection_name : ar_class.name.underscore.pluralize)
+          @proxies ||= {}
+          return @proxies[ar_class.name] if @proxies.key?(ar_class.name)
 
-          if ar_class.respond_to?(:typesense_schema) && ar_class.typesense_schema
-            @_schema_definition = ar_class.typesense_schema
+          PROXY_MUTEX.synchronize do
+            @proxies[ar_class.name] ||= build_proxy(ar_class)
           end
-
-          self
-        end
-
-        def ar_class
-          @ar_class
         end
 
         def client
           TypesenseModel.configuration.client
         end
+
+        private
+
+        def build_proxy(ar_class)
+          resolved_collection =
+            if ar_class.respond_to?(:typesense_collection_name)
+              ar_class.typesense_collection_name
+            else
+              ar_class.name.underscore.pluralize
+            end
+          resolved_schema = ar_class.typesense_schema if ar_class.respond_to?(:typesense_schema)
+
+          Class.new(self) do
+            @ar_class = ar_class
+            collection_name(resolved_collection)
+            @_schema_definition = resolved_schema
+
+            class << self
+              attr_reader :ar_class
+            end
+          end
+        end
       end
     end
   end

data/lib/typesense_model/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module TypesenseModel
   class Base
     class << self
@@ -35,6 +37,39 @@ module TypesenseModel
         Search.new(self, query, options).execute
       end
 
+      # Perform several searches in a single request.
+      #
+      # @param searches [Array<Hash>] each a set of Typesense search params;
+      #   `collection` defaults to this model's collection, and `q`/`query_by`
+      #   fall back the same way as #search (pass `query_by` explicitly when
+      #   targeting a different collection).
+      # @param common_params [Hash] params applied to every search.
+      # @return [Array<SearchResults>] one result set per search, in order.
+      def multi_search(searches, common_params = {})
+        payload = Array(searches).map do |params|
+          params = params.transform_keys(&:to_sym)
+          {
+            collection: params[:collection] || collection_name,
+            q: params[:q] || '*',
+            query_by: params[:query_by] || default_query_by
+          }.merge(params.except(:collection, :q, :query_by))
+        end
+
+        response = client.multi_search.perform({ searches: payload }, common_params)
+        (response['results'] || []).map { |result| SearchResults.new(result, self) }
+      end
+
+      # Comma-separated list of indexed string fields (excluding id) used as the
+      # default `query_by` when a search doesn't specify one.
+      def default_query_by
+        return '' unless schema_definition
+
+        schema_definition.fields
+          .select { |f| f[:index] && f[:type] == 'string' && f[:name] != 'id' }
+          .map { |f| f[:name] }
+          .join(',')
+      end
+
       # Create the collection in Typesense
       def create_collection(force = false)
         delete_collection if force
@@ -60,18 +95,50 @@ module TypesenseModel
         false
       end
 
-      # Update the collection schema in Typesense
+      # Update the collection schema in Typesense to match the model schema.
+      #
+      # Typesense only accepts a `fields` diff on update: a field can be added,
+      # or dropped (`drop: true`), and a change is expressed as a drop followed
+      # by a re-add. Re-sending an existing, unchanged field raises an error, so
+      # we diff the desired schema against the live collection and send only the
+      # additions, modifications, and removals. The implicit `id` field cannot
+      # be altered and is always skipped.
       def update_collection
         return create_collection unless collection_exists?
 
-        # Typesense only allows updating `fields` (and `metadata`).
-        # Do not send `name` or `default_sorting_field` on update.
-        # Exclude the implicit `id` field from updates (Typesense does not allow altering it)
-        updated_fields = (schema_definition.to_hash[:fields] || []).reject { |f| f[:name] == 'id' || f['name'] == 'id' }
+        live_fields = (retrieve_collection&.dig('fields') || []).each_with_object({}) do |f, h|
+          h[f['name'].to_s] = f
+        end
+
+        desired_fields = (schema_definition.to_hash[:fields] || []).reject do |f|
+          (f[:name] || f['name']).to_s == 'id'
+        end
+
+        changes = []
+        desired_names = []
 
-        update_payload = { fields: updated_fields }.compact
+        desired_fields.each do |field|
+          name = (field[:name] || field['name']).to_s
+          desired_names << name
+          existing = live_fields[name]
 
-        client.collections[collection_name].update(update_payload)
+          if existing.nil?
+            changes << field
+          elsif field_changed?(field, existing)
+            changes << { 'name' => name, 'drop' => true }
+            changes << field
+          end
+        end
+
+        # Drop fields that exist in Typesense but are no longer in the schema.
+        live_fields.each_key do |name|
+          next if name == 'id' || name == '.*'
+          changes << { 'name' => name, 'drop' => true } unless desired_names.include?(name)
+        end
+
+        return retrieve_collection if changes.empty?
+
+        client.collections[collection_name].update(fields: changes)
       end
 
       # Create or update collection
@@ -105,6 +172,14 @@ module TypesenseModel
           .documents
           .import(sanitized_documents, options)
 
+        # Typesense returns one result hash per document. Guard against an
+        # unexpected non-array shape (e.g. an error payload) so we never blow up
+        # in the tally below.
+        unless response.is_a?(Array)
+          return { success: 0, failed: sanitized_documents.size,
+                   errors: [{ code: nil, error: "Unexpected import response: #{response.inspect}", document: nil }] }
+        end
+
         results = response.each_with_object({ success: 0, failed: 0, errors: [] }) do |result, counts|
           if result['success']
             counts[:success] += 1
@@ -129,7 +204,7 @@ module TypesenseModel
       # @param import_options [Hash] Options to pass to the import method
       # @return [Hash] { success: Integer, failed: Integer }
       def import_from_model(model_class, batch_size, transform_method = :as_json, preloads = nil, import_options = {})
-        total_results = { success: 0, failed: 0 }
+        total_results = { success: 0, failed: 0, errors: [] }
 
         transformer = transform_method.is_a?(Proc) ? transform_method : ->(record) { record.send(transform_method) }
 
@@ -139,12 +214,10 @@ module TypesenseModel
         relation.find_in_batches(batch_size: batch_size) do |batch|
           documents = batch.map(&transformer)
           results = import(documents, import_options)
-          
+
           total_results[:success] += results[:success]
           total_results[:failed] += results[:failed]
-          if results[:errors].is_a?(Array) && results[:errors].any?
-            (total_results[:errors] ||= []).concat(results[:errors])
-          end
+          total_results[:errors].concat(results[:errors]) if results[:errors].is_a?(Array)
         end
 
         total_results
@@ -159,11 +232,47 @@ module TypesenseModel
         false
       end
 
-      # Delete multiple records by query
+      # Delete multiple records by query. Returns the Typesense response
+      # (e.g. { "num_deleted" => N }); when the collection is missing, returns
+      # { "num_deleted" => 0 } for symmetry with the singular #delete.
       def delete_by(filter_by)
         client.collections[collection_name]
           .documents
           .delete({ filter_by: filter_by })
+      rescue Typesense::Error::ObjectNotFound
+        { "num_deleted" => 0 }
+      end
+
+      # --- Synonyms -------------------------------------------------------
+      # Thin wrappers over the Typesense synonyms API for this collection.
+      def upsert_synonym(id, synonym)
+        client.collections[collection_name].synonyms.upsert(id, synonym)
+      end
+
+      def synonyms
+        client.collections[collection_name].synonyms.retrieve
+      end
+
+      def delete_synonym(id)
+        client.collections[collection_name].synonyms[id].delete
+      rescue Typesense::Error::ObjectNotFound
+        false
+      end
+
+      # --- Overrides (curation) ------------------------------------------
+      # Thin wrappers over the Typesense overrides API for this collection.
+      def upsert_override(id, override)
+        client.collections[collection_name].overrides.upsert(id, override)
+      end
+
+      def overrides
+        client.collections[collection_name].overrides.retrieve
+      end
+
+      def delete_override(id)
+        client.collections[collection_name].overrides[id].delete
+      rescue Typesense::Error::ObjectNotFound
+        false
       end
 
       private
@@ -181,6 +290,38 @@ module TypesenseModel
         sanitized['id'] = sanitized['id'].to_s if sanitized.key?('id')
         sanitized
       end
+
+      # Field attributes that meaningfully affect the Typesense schema. Used to
+      # decide whether a live field differs from the desired definition.
+      FIELD_DIFF_ATTRS = %i[type facet optional index sort].freeze
+
+      # Numeric/boolean types are sortable by default in Typesense; strings are not.
+      DEFAULT_SORTABLE_TYPES = %w[int32 int64 float bool].freeze
+
+      def field_changed?(desired, existing)
+        FIELD_DIFF_ATTRS.any? do |attr|
+          desired_field_value(desired, attr) != existing_field_value(existing, attr)
+        end
+      end
+
+      def desired_field_value(field, attr)
+        value = field.fetch(attr) { field[attr.to_s] }
+        attr == :type ? value.to_s : value
+      end
+
+      # Resolve a live field's attribute, applying Typesense defaults when the
+      # retrieved schema omits the key, so unchanged fields don't look modified.
+      def existing_field_value(field, attr)
+        type = field['type'].to_s
+        return type if attr == :type
+        return field[attr.to_s] if field.key?(attr.to_s)
+
+        case attr
+        when :facet, :optional then false
+        when :index then true
+        when :sort then DEFAULT_SORTABLE_TYPES.include?(type)
+        end
+      end
     end
 
     attr_accessor :attributes
@@ -200,6 +341,15 @@ module TypesenseModel
       attributes['id']
     end
 
+    # Delete the current record from Typesense. Returns true if a document was
+    # removed, false if there was no id or nothing to delete.
+    def delete
+      return false unless id
+
+      response = self.class.delete(id)
+      !response.nil? && response != false
+    end
+
     def method_missing(method_name, *args)
       attribute_name = method_name.to_s
       
@@ -233,13 +383,5 @@ module TypesenseModel
     def client
       self.class.send(:client)
     end
-
-    # Instance method to delete the current record
-    def delete
-      return false unless id
-      
-      response = self.class.delete(id)
-      !response.nil?
-    end
   end
 end 

data/lib/typesense_model/configuration.rb

@@ -1,24 +1,32 @@
+# frozen_string_literal: true
+
 module TypesenseModel
   class Configuration
-    attr_accessor :api_key, :host, :port, :protocol
+    attr_accessor :api_key, :host, :port, :protocol, :connection_timeout_seconds
 
     def initialize
       @api_key = nil
       @host = 'localhost'
       @port = 8108
       @protocol = 'http'
+      @connection_timeout_seconds = 5
+      @client_mutex = Mutex.new
     end
 
     def client
-      @client ||= Typesense::Client.new(
-        api_key: api_key,
-        nodes: [{
-          host: host,
-          port: port,
-          protocol: protocol
-        }],
-        connection_timeout_seconds: 5
-      )
+      return @client if @client
+
+      @client_mutex.synchronize do
+        @client ||= Typesense::Client.new(
+          api_key: api_key,
+          nodes: [{
+            host: host,
+            port: port,
+            protocol: protocol
+          }],
+          connection_timeout_seconds: connection_timeout_seconds
+        )
+      end
     end
   end
-end 
+end

data/lib/typesense_model/schema.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module TypesenseModel
   class Schema
     attr_reader :fields, :collection_name, :default_sorting_field
@@ -29,11 +31,5 @@ module TypesenseModel
         default_sorting_field: @default_sorting_field
       }.compact
     end
-
-    private
-
-    def default_sorting_field
-      @fields.find { |f| f[:name] == 'id' }&.dig(:name)
-    end
   end
 end 

data/lib/typesense_model/search.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module TypesenseModel
   class Search
     def initialize(model_class, query, options = {})
@@ -25,12 +27,7 @@ module TypesenseModel
     private
 
     def default_queryable_fields
-      @model_class.schema_definition.fields
-        .select { |f| f[:index] }
-        .select { |f| f[:type] == 'string' }
-        .reject { |f| f[:name] == 'id' }
-        .map { |f| f[:name] }
-        .join(',')
+      @model_class.default_query_by
     end
   end
 
@@ -60,6 +57,33 @@ module TypesenseModel
       @raw_response['hits'] || []
     end
 
+    # Each hit paired with its search metadata: the model record, the per-field
+    # highlight snippets, and the relevance score Typesense computed.
+    #
+    # @return [Array<Hash>] { record:, highlights:, highlight:, text_match: }
+    def hits_with_meta
+      hits.map do |hit|
+        {
+          record: @model_class.new(hit['document']),
+          highlights: hit['highlights'] || [],
+          highlight: hit['highlight'] || {},
+          text_match: hit['text_match']
+        }
+      end
+    end
+
+    # Grouped results, populated only when the search used `group_by`.
+    #
+    # @return [Array<Hash>] { group_key:, hits: [records] }
+    def grouped_hits
+      (@raw_response['grouped_hits'] || []).map do |group|
+        {
+          group_key: group['group_key'],
+          hits: (group['hits'] || []).map { |h| @model_class.new(h['document']) }
+        }
+      end
+    end
+
     def size
       total_hits
     end
@@ -68,13 +92,13 @@ module TypesenseModel
       @raw_response['found'] || 0
     end
     # PAGY COMPATIBILITY
-    def count(_)
+    def count(*)
       total_hits
     end
-    def offset(_)
+    def offset(*)
       self
     end
-    def limit(_)
+    def limit(*)
       self
     end
 

data/lib/typesense_model/sync_job.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Loaded only when ActiveJob is available (see typesense_model.rb). Performs the
+# Typesense sync/remove off the request cycle when a model opts into
+# `uses_typesense(async: true)`.
+module TypesenseModel
+  class SyncJob < ActiveJob::Base
+    def perform(class_name, id, action)
+      klass = class_name.constantize
+
+      case action.to_s
+      when "remove"
+        proxy = ActiveRecordExtension::TypesenseProxy.for(klass)
+        proxy.delete(id)
+      else
+        record = klass.respond_to?(:find_by) ? klass.find_by(id: id) : nil
+        record&.sync_to_typesense_now
+      end
+    rescue Typesense::Error => e
+      TypesenseModel.logger.error("Async Typesense #{action} failed for #{class_name}##{id}: #{e.message}")
+    end
+  end
+end

data/lib/typesense_model/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module TypesenseModel
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end 

data/lib/typesense_model.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: true
+
+require "logger"
 require "typesense"
+require "active_support/core_ext/string/inflections"
 require "typesense_model/version"
 require "typesense_model/base"
 require "typesense_model/search"
@@ -11,15 +15,39 @@ module TypesenseModel
   
   class << self
     attr_accessor :configuration
+    attr_writer :logger
   end
 
   def self.configure
     self.configuration ||= Configuration.new
     yield(configuration) if block_given?
   end
+
+  # Logger used for non-fatal failures (e.g. background sync errors). Defaults to
+  # Rails.logger when available, otherwise a STDERR logger. Assign your own with
+  # TypesenseModel.logger = ...
+  def self.logger
+    @logger ||= if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+      Rails.logger
+    else
+      Logger.new($stderr)
+    end
+  end
 end 
 
-# Auto-include into ActiveRecord if available
-if defined?(ActiveRecord::Base)
+# Auto-include into ActiveRecord. Prefer the Rails load hook so this works
+# regardless of gem load order; fall back to a direct include if ActiveRecord
+# is already loaded (e.g. non-Rails usage).
+if defined?(ActiveSupport)
+  ActiveSupport.on_load(:active_record) do
+    include TypesenseModel::ActiveRecordExtension
+  end
+
+  # Define the async sync job only once ActiveJob is loaded, so we never depend
+  # on it at load time (it's optional — only needed for `async: true`).
+  ActiveSupport.on_load(:active_job) do
+    require "typesense_model/sync_job"
+  end
+elsif defined?(ActiveRecord::Base)
   ActiveRecord::Base.include(TypesenseModel::ActiveRecordExtension)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typesense_model
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Emanuel Comsa
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +65,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
 description: A Ruby gem that provides an ActiveModel-like interface for working with
   Typesense search engine
 email:
@@ -73,6 +87,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - lib/typesense_model.rb
@@ -81,14 +96,15 @@ files:
 - lib/typesense_model/configuration.rb
 - lib/typesense_model/schema.rb
 - lib/typesense_model/search.rb
+- lib/typesense_model/sync_job.rb
 - lib/typesense_model/version.rb
 homepage: https://github.com/rubydevro/typesense_model
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://www.rubydev.ro
   source_code_uri: https://github.com/rubydevro/typesense_model
-  changelog_uri: https://github.com/rubydevro/typesense_model/blob/main/CHANGELOG.md
+  changelog_uri: https://github.com/rubydevro/typesense_model/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -96,14 +112,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.10
 specification_version: 4
 summary: ActiveModel-like interface for Typesense
 test_files: []