ActiveRecordCustomPreloader

Custom preloader for ActiveRecord model.

Gem version 2.X.X and master branch compatible with Rails 6.X.X and upper. For Rails 5.X.X see branch rails-5 and gem version 1.X.X.

Installation

Add this line to your application's Gemfile:

gem 'active_record_custom_preloader'

if you use Rails you should require railtie.rb file like this in config/application.rb:

require 'active_record_custom_preloader/railtie'

or like this in Gemfile

gem 'active_record_custom_preloader', require: 'active_record_custom_preloader/railtie'

And then execute:

$ bundle

Or install it yourself as:

$ gem install active_record_custom_preloader

Usage

require 'active_record_custom_preloader/railtie'

class Person < ActiveRecord::Base
  add_custom_loader :_stats, class_name: 'StatsPreloader'
end

class ApplicationPreloader < ActiveRecordCustomPreloader::Preloader
end

class StatsPreloader < ApplicationPreloader
  def preload(records)
    ids = records.map(&:id)
    values = CustomApi.fetch_stats_for(ids)
    records.each do |record|
      value = OpenStruct.new(values[record.id])
      record._set_custom_preloaded_value(name, value)
    end
  end
end

people = Person.all.preload(:_stats)
people.first._stats # will return value that was preloaded earlier

person = Person.find(1)
person._stats # will preload and return value
person._stats # will return value that was preloaded earlier
person.clear_custom_preloaded_value(:_stats) # will clear preloaded value for _stats
person._stats # will preload again and return value

you can use ActiveRecordCustomPreloader::WithMultipleForeignKeysLoading module for preloading active_record models which are related to parent record by multiple keys

require 'active_record_custom_preloader/railtie'

class Employee < ActiveRecord::Base
  # columns: id, name, department_id, position_id
  add_custom_loader :_contract, class_name: 'EmployeeContractPreloader'
end

class Contract < ActiveRecord::Base
  # columns: id, text, employee_department_id, position_id
end

class EmployeeContractPreloader < ActiveRecordCustomPreloader::Preloader
  include ActiveRecordCustomPreloader::WithMultipleForeignKeysLoading
  self.model_class_name = 'Contract'
  self.association_foreign_keys_names = [:employee_department_id, :position_id]

  def record_foreign_keys(record)
    [record.department_id, record.position_id]
  end
end

also you can use ActiveRecordCustomPreloader::WithContextDependentLoading module for preloading active_record models which should be filtered by some external context

require 'active_record_custom_preloader/railtie'

class User < ActiveRecord::Base
  # columns: id, name, pricelist_id
end

class Discount < ActiveRecord::Base
  # columns id, user_pricelist_id, product_id, percentage
end

class Product < ActiveRecord::Base
  # columns: id, name, price
  add_loader :_discount, class_name: 'ProductDiscountPreloader'
end

class ProductDiscountPreloader < ActiveRecordCustomPreloader::Preloader
  include ActiveRecordCustomPreloader::WithContextDependentLoading
  self.to_many = true
  self.association_group_key = :user_pricelist_id
  self.record_group_key = :pricelist_id

  def scoped_collection(records)
    product_ids = records.map(&:id)
    pricelist_id = args.fetch(:pricelist_id)
    Discount.where(user_pricelist_id: pricelist_id, product_id: product_ids)
  end
end

user = User.first
products = Product.limit(10).custom_preload(:_discount, pricelist_id: user.pricelist_id)
products.first._discount # will return array with zero or more Discount records

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/senid231/active_record_custom_preloader. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the ActiveRecordCustomPreloader project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.