integrative 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a841fed65f619a6170d26d8816ff8f697d39c463
+  data.tar.gz: 906a568cf159349a97f435714a0989f1c1dc36db
+SHA512:
+  metadata.gz: 034c141465f37b82b4b4449f97cef1ced395a367d52fe9109d172e9c36a199f3baf068d618c527722cbcb8b32aded0b2e916ade2f511a509d4ab30368d9c6c74
+  data.tar.gz: 77c8c554abe0adcb2edfb661677c7e8200e78734c365256c1dc1d324437ff8d8a4641f2cf3045fa59a3d1164a2b82e19cf627d30cb2d561c885fb9cefaae3e99

data/README.md

@@ -0,0 +1,191 @@
+# Integrative
+
+Integrative is a library for integrating external resources into ActiveRecord models.
+
+Now, however you interpret "external" - this library is exactly for that ;-)
+
+Cosider few exaples of what can be integrated into ActiveRecord model:
+* ActiveResource model
+* a custom object that fetches data from external websites
+* an object fetching data from Redis
+* another ActiveRecord model
+
+You may ask
+
+> :triumph:: ok, but why would I use Integrative? I can easily implement that on my own.
+
+> :sunglasses:: I'm glad you asked. The best reason is that **it helps to fetch a lot of data at once**, and by that it significantly improves performance.
+
+## Examples
+### Example 1: Another data store
+
+Imagine the following context:
+
+```ruby
+  class User < ApplicationRecord
+    include Integrative::Integrator
+
+    integrates :user_flag
+  end
+
+  class UserFlag < SomeRedisObject
+    include Integrative::Integrated
+
+    attr_accessor :user_id
+    attr_accessor :name
+
+    def self.find(ids)
+      # Have in mind it's a simplification.
+      # `find` should return array of hashes
+      # with (in this case) `name` and `user_id`
+      # so you'd need to store hashes
+      # and convert data accordingly
+      @redis.mget(*ids)
+    end
+  end
+```
+
+Now let's say you would like to see the list of all users with their flags. Try this:
+
+```ruby
+  users = User.limit(1000).integrate(:user_flag).to_a
+```
+
+**the above code will call redis only once** and will fetch user_flag for all 1000 users,
+so now you can access all the flags like this:
+
+```ruby
+  users.map { |user| user.user_flag.name }
+```
+
+### Example 2: Prefetching another Active Record model
+
+You can use Integrative also when you want to eager-load certain models to collection of other models when `ActiveRecord` doesn't make it easy.
+Let's say you have the following situation:
+
+```ruby
+  class User < ApplicationRecord
+    include Integrative::Integrator
+
+    integrates :relation, requires: [:with]
+  end
+
+  class Relation
+    include Integrative::Integrated
+
+    def self.integrative_find(ids, integration)
+      Relation.where(user_id: integration.call_options[:with].id, other_user_id: ids)
+    end
+  end
+```
+Now you want to fetch some Users and have already prefatched information about their relation with the current user.
+
+With `Integrative` you just do:
+
+```ruby
+  User.where(public: true).integrate(:relation, with: current_user).limit(1000)
+```
+
+Boom. Pretty cool, ha?
+
+## Treating integrated object as primary type value (string, int, ...)
+
+Now check this out:
+
+```ruby
+  class User < ApplicationRecord
+    integrates :is_admin, as: :primary
+  end
+
+  User.integrate(:is_admin).first.is_admin # that would be `true` or `false`
+```
+
+Of course for that you'd need to take care for preparing data properly in the integrated object:
+
+```ruby
+  class IsAdmin
+    include Integrative::Integrated
+
+    def self.integrative_find(ids, integration)
+      # this should return a list of hashes
+      # with a key (e.g. user_id) and a `value`,
+      # for example:
+      # [
+      #   {user_id: 1, value: true}
+      #   {user_id: 2, value: false}
+      # ]
+      response = find(ids)
+      response.map { |item| OpenStruct.new(item) }
+    end
+  end
+```
+
+## Integrating objects with `1-to-many` relation
+
+Like with `has_one` and `has_many` relations, sometimes you want to assign one external object
+per model, but sometimes you want to assign an array of external objects per model. In such moments use `array: true` as an option parameter of integration
+
+```ruby
+  class User < ApplicationRecord
+    integrates :flags, array: true
+  end
+
+  User.first.flags # this is an array
+```
+
+## Using `Integrative` on a single instance
+
+So what if you'd like to prefetch something not for a list of users, but for a single user?
+Well, it works exactly how you would think:
+
+```ruby
+  user = User.first
+  user.flags # yes, that's gonna fetch and return a list of flags of the user.
+```
+
+## Using `Integrative` on an array
+
+Sometimes you just want to prefetch certain data for an array of objects (and not for `ActiveRecord::Relation`). In such case just do:
+
+```ruby
+   users_with_flags = Integrative.integrate_into(users, :user_flags)
+```
+
+## Working with external resources
+
+While working with external resources you need to implement the code that fetches external data and then assigns parts of it to the right models. Now it's all up to you how you'll do this but there is a pattern that fits well into `Integrative`. Take a look:
+
+```ruby
+  # file app/models/integrative_record.rb
+  class IntegrativeRecord
+    include Integrative::Integrated
+
+    def url_base
+      'http://external.service.com'
+    end
+
+    def full_url(ids)
+      url_base + path(ids)
+    end
+  end
+
+  # file app/models/avatar.rb
+  class Avatar < IntegrativeRecord
+
+    def path(ids)
+      "avatars?user_ids=#{ids.join(',')}"
+    end
+
+    def find(ids)
+      response = RestClient.get full_path(ids)
+      response_hash = HashWithIndifferentAccess.new(JSON.parse(response.body))
+      response_hash[:results]
+    end
+  end
+```
+
+## Contributing
+
+If you feel like contributing to this project, feel free to create a bug report or send a pull request, but if you want to increase chances that I'll find time for taking care for your contribution, please make sure to make it easy for me - for pull requests write tests, for bug reports attach code that will let me reproduce the issue.
+
+Have fun ;-)

data/Rakefile

@@ -0,0 +1,34 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Integrative'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/lib/integrative.rb

@@ -0,0 +1,35 @@
+#  Integrative lets you add objects to ActiveRecord relation or to an array
+#
+#   class User < ApplicationRecord
+#     integrates :relation, require: [:with]
+#   end
+#
+#   class Relation
+#     include Integrative::Integrated
+#
+#     attr_accessor :user_id
+#     attr_accessor :kind
+#
+#     ...
+#   end
+#
+# Now let's say you would like to have the list of all users with their relations.
+# Try this:
+#
+#   users = User.limit(1000).integrate(:relation, with: current_user).to_a
+#
+# and the integration of relations will happen for the whole collection and not
+# just for individual users.
+require 'integrative/utils'
+
+module Integrative
+  extend Utils
+
+  autoload :Integrator,  'integrative/integrator'
+  autoload :Integrated,  'integrative/integrated'
+  autoload :Integration, 'integrative/integration'
+  autoload :Errors,      'integrative/errors'
+  autoload :Extensions,  'integrative/extensions'
+end
+
+

data/lib/integrative/errors.rb

@@ -0,0 +1,76 @@
+module Integrative
+  module Errors
+    class IntegrationError < StandardError
+      attr_accessor :integration
+
+      def initialize(message, integration)
+        @integration = integration
+        super(message)
+      end
+    end
+
+    class RuntimeOptionMissingError < IntegrationError
+      def initialize(integration)
+        message = "You used 'integrate' for #{integration.name} without options," +
+          " but the following options are required: " +
+          " #{integration.init_options[:requires]}"
+        super(message, integration)
+      end
+    end
+
+    class UnexpectedRuntimeOptionError < IntegrationError
+      def initialize(integration)
+        required = integration.call_options.keys
+        message = "You used 'integrate' for #{integration.name} with unexpected options," +
+          " you should define integration like this:" +
+          " 'integrates :#{integration.name}, requires: [:#{required.join(", :")}]'"
+        super(message, integration)
+      end
+    end
+
+    class TooManyRuntimeOptionsError < IntegrationError
+      def initialize(integration, unexpected_options)
+        message = "You used 'integrate' for :#{integration.name}" +
+          " on #{integration.integrator_class.name}" +
+          " with too many options: #{unexpected_options}"
+        super(message, integration)
+      end
+    end
+
+    class TooLittleRuntimeOptionsError < IntegrationError
+      def initialize(integration, missing_options)
+        message = "You used 'integrate' for :#{integration.name}" +
+          " on #{integration.integrator_class.name}" +
+          " with too little options: #{missing_options}"
+        super(message, integration)
+      end
+    end
+
+    class IntegratorError < StandardError
+      attr_accessor :integration
+
+      def initialize(message, integrator)
+        @integrator = integrator
+        super(message)
+      end
+    end
+
+    class MethodAlreadyExistsError < IntegratorError
+      def initialize(integrator, name)
+        message = "Method '#{name}' is already defined on #{integrator.name}." +
+          " You can not define integration with this name."
+        super(message, integrator)
+      end
+    end
+
+    class IntegrationDefinitionMissingError < IntegratorError
+      def initialize(integrator, names)
+        message = "You tried to call `integrate` on a class #{integrator.name}" +
+          " but this class doesn't have this integration." +
+          " add the following line to the class #{integrator.name}:" +
+          " 'integrates :#{names.join(', :')}'"
+        super(message, integrator)
+      end
+    end
+  end
+end

data/lib/integrative/extensions.rb

@@ -0,0 +1,7 @@
+module Integrative
+  module Extensions
+    autoload :RelationExtension,     'integrative/extensions/relation_extension'
+  end
+end
+
+

data/lib/integrative/extensions/relation_extension.rb

@@ -0,0 +1,37 @@
+module Integrative
+  module Extensions
+    module RelationExtension
+      def integrate(*name_or_names, **options)
+        names = [*name_or_names]
+        names.each do |name|
+          integrate_per_name(name, options)
+        end
+        self
+      end
+
+      def load
+        super
+        if @integrations_used.present?
+          Rails.logger.info "Integrations fetched for #{@records.length} #{klass.name} records."
+          @integrations_used.each do |integration|
+            integration.integrated_class.integrative_find_and_assign(@records, integration)
+          end
+        end
+        self
+      end
+
+      private
+
+      def integrate_per_name(name, options)
+        integration = klass.integrations_defined.find { |i| i.name == name }
+        if integration.nil?
+          raise Errors::IntegrationDefinitionMissingError.new(klass, [name])
+        end
+        integration.call_options = options
+        integration.invalidate
+        @integrations_used ||= []
+        @integrations_used << integration
+      end
+    end
+  end
+end

data/lib/integrative/integrated.rb

@@ -0,0 +1,62 @@
+require 'ostruct'
+
+module Integrative
+  module Integrated
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def integrative_find(ids, options)
+        find(ids)
+      end
+
+      def integrator_ids(integrator_records, integration)
+        integrator_records.map(&integration.integrator_key)
+      end
+
+      def integrative_find_and_assign(integrator_records, integration)
+        ids = integrator_ids(integrator_records, integration)
+        integrated = integrative_find(ids, integration)
+        integrated_by_integrator_id = array_to_hash(integrated, integration)
+        integrator_records.each do |record|
+          record.public_send(integration.setter, integrated_by_integrator_id[record.id])
+        end
+      end
+
+      def integrative_value(object, integration)
+        if [:primary, :value, :simple].include? integration.init_options[:as]
+          object[:value]
+        else
+          object
+        end
+      end
+
+      private
+
+      def array_to_hash(array, integration)
+        if integration.init_options[:array]
+          array_to_hash_as_array(array, integration)
+        else
+          array_to_hash_as_value(array, integration)
+        end
+      end
+
+      def array_to_hash_as_value(array, integration)
+        result = array.map do |object|
+          key = object.public_send(integration.integrated_key)
+          [key, integrative_value(object, integration)]
+        end
+        Hash[result]
+      end
+
+      def array_to_hash_as_array(array, integration)
+        result = {}
+        array.each do |object|
+          key = object.public_send(integration.integrated_key)
+          result[key] ||= []
+          result[key] << integrative_value(object, integration)
+        end
+        result
+      end
+    end
+  end
+end

data/lib/integrative/integration.rb

@@ -0,0 +1,52 @@
+module Integrative
+  class Integration
+    attr_accessor :name
+    attr_accessor :integrator_class
+    attr_accessor :integrated_class
+    attr_accessor :init_options
+    attr_accessor :call_options
+
+    def initialize(name, integrator_class, options)
+      @name = name
+      @integrator_class = integrator_class
+      @integrated_class = name.to_s.camelize.singularize.constantize
+      @init_options = options
+    end
+
+    def invalidate
+      if call_options.blank? && init_options[:requires].present?
+        raise Errors::RuntimeOptionMissingError.new(self)
+      end
+
+      if call_options.present? && init_options[:requires].blank?
+        raise Errors::UnexpectedRuntimeOptionError.new(self)
+      end
+
+      if call_options.present? && init_options[:requires].present?
+        unexpected_options = call_options.keys - init_options[:requires]
+        missing_options = init_options[:requires] - call_options.keys
+
+        if unexpected_options.present?
+          raise Errors::TooManyRuntimeOptionsError.new(self, unexpected_options)
+        end
+
+        if missing_options.present?
+          raise Errors::TooLittleRuntimeOptionsError.new(self, missing_options)
+        end
+      end
+    end
+
+    def setter
+      "#{name}="
+    end
+
+    def integrator_key
+      init_options[:integrator_key] || :id
+    end
+
+    def integrated_key
+      default_integrated_key = "#{integrator_class.name.underscore}_id"
+      init_options[:integrated_key] || default_integrated_key
+    end
+  end
+end

data/lib/integrative/integrator.rb

@@ -0,0 +1,66 @@
+module Integrative
+  module Integrator
+    extend ActiveSupport::Concern
+
+    def integrative_dynamic_method_call(name, integration)
+      ivar = "@#{name}"
+      if instance_variable_defined? ivar
+        instance_variable_get ivar
+      else
+        Rails.logger.info "Integrations fetched for a single #{self.class.name} record."
+        integration.integrated_class.integrative_find_and_assign([self], integration)
+        instance_variable_get ivar
+      end
+    end
+
+    class_methods do
+      def integrates(name, options = {})
+        initialize_integrative(name)
+        define_integration(name, options)
+      end
+
+      def integrate(*name_or_names, **options)
+        if all.public_methods.include? :integrate
+          all.integrate(*name_or_names, **options)
+        else
+          raise Errors::IntegrationDefinitionMissingError.new(self, name_or_names)
+        end
+      end
+
+      def patch_activerecord_relation_for_integrative
+        self::ActiveRecord_Relation.class_eval do
+          include Integrative::Extensions::RelationExtension
+        end
+      end
+
+      private
+
+      def initialize_integrative(name)
+        if self.instance_methods.include? name
+          raise Errors::MethodAlreadyExistsError.new(self, name)
+        end
+        if !defined?(integrations_defined)
+          patch_activerecord_relation_for_integrative
+          class_attribute :integrations_defined
+        end
+      end
+
+      def define_integration(name, options)
+        integration = Integration.new(name, self, options)
+        self.integrations_defined ||= []
+        self.integrations_defined << integration
+        self.class_eval do
+          define_integration_method(name, integration)
+        end
+      end
+
+      def define_integration_method(name, integration)
+        attr_accessor name
+
+        define_method name do
+          integrative_dynamic_method_call(name, integration)
+        end
+      end
+    end
+  end
+end

data/lib/integrative/utils.rb

@@ -0,0 +1,10 @@
+module Integrative
+  module Utils
+    def integrate_into(records, integration_name, options = {})
+      if records.length > 0
+        integration = Integration.new(integration_name, records.first.class, options)
+        integration.integrated_class.integrative_find_and_assign(records, integration)
+      end
+    end
+  end
+end

data/lib/integrative/version.rb

@@ -0,0 +1,3 @@
+module Integrative
+  VERSION = '0.1.0'
+end

data/lib/tasks/integrative_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :integrative do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: integrative
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Krzysiek Herod
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-07-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.0
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: factory_girl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Integrative is a library for integrating external resources into ActiveRecord
+  models.
+email:
+- krzysiek.herod@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/integrative.rb
+- lib/integrative/errors.rb
+- lib/integrative/extensions.rb
+- lib/integrative/extensions/relation_extension.rb
+- lib/integrative/integrated.rb
+- lib/integrative/integration.rb
+- lib/integrative/integrator.rb
+- lib/integrative/utils.rb
+- lib/integrative/version.rb
+- lib/tasks/integrative_tasks.rake
+homepage: https://github.com/netizer/integrative
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.6
+signing_key: 
+specification_version: 4
+summary: Integrative is a library for integrating external resources into ActiveRecord
+  models.
+test_files: []