quickery 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06ee53003d29d3dfa2bf9cd981c5d6f154bb49a8a07538d846acff0b30adb52d
-  data.tar.gz: 2bf0d7a7e35f9d46ec2fabeacd11f36479f4165c1110b8e75d3336e91329d5f9
+  metadata.gz: 5caca192d074a8aa71dd2c6e9bc06a3051b6f7eaec2bc664618af356d41a250d
+  data.tar.gz: 9acfccf220d83aa4c0d521ba13b4040241273d513160a7e2c4b4afccdb32de8a
 SHA512:
-  metadata.gz: 290d4b4ba0ee7b2f239619231c07ceb848a79d3b858b0b03287644459a67ed5ae826e426b6b291debee23afecaca4221434df1c21fda53bb8d662791f8afda0e
-  data.tar.gz: 1c3b3f6b7817550bf272e342b88c70964ff8955f9bc73fe81e6c234f0036c19d4ed8278cf6b0ec45346d8dee010842060b51d3e17c8593a753ffb6943dc1fc35
+  metadata.gz: 3839d48b10faac8d58778c4373440496781a3c52765478b510b1918441fda4aae743097e65ec4a0841fad599f3dfea3b8279062eb406e4a2a0dd0272885774d5
+  data.tar.gz: 29cb2b61d408b61eee767267dce79538aa8039e1de9f85e111f62bb330ad1b395d7c810f4ae2e0065ef1ac37f70094c3e0f564ddda97cf46dde5921432cad066

data/README.md

@@ -184,6 +184,168 @@ class Employee < ApplicationRecord
 end
 ```
 
+## Advanced Usage
+
+Quickery defines the following for `ActiveRecord::Base` of which you can optionally override in any of your models for advanced usage, i.e:
+
+```ruby
+class Employee < ApplicationRecord
+  belongs_to :branch
+
+  quickery branch: { company: { name: :branch_company_name } }
+
+  # this method will be called before an Employee gets created or updated
+  # new_values is a Hash of quickery-defined attribute changes; say: `{ :branch_company_name => 'Jollibee' }`
+  # i.e. when some_employee.update(branch: some_branch)
+  def self.quickery_before_create_or_update(employee, new_values)
+    employee.assign_attributes(new_values) # default behaviour of this method
+  end
+
+  # this method will be called before any updates happen on any of the association (that a quickery-defined attribute in this model depends on)
+  # i.e. when some_branch.update(company: some_company)
+  # i.e. when some_company.update(name: 'New Company Name')
+  def self.quickery_before_association_update(employees, record_to_be_updated, new_values)
+    employees.update_all(new_values) # default behaviour of this method
+  end
+
+  # this method will be called before any of the association gets destroyed (that a quickery-defined attribute in this model depends on)
+  # i.e. when some_branch.destroy
+  # i.e. when some_company.destroy
+  def self.quickery_before_association_destroy(employees, record_to_be_destroyed, new_values)
+    employees.update_all(new_values) # default behaviour of this method
+  end
+end
+```
+
+### Advanced Usage: Background Job
+
+```ruby
+class Employee < ApplicationRecord
+  belongs_to :branch
+
+  quickery branch: { company: { name: :branch_company_name } }
+
+  def self.quickery_before_create_or_update(employee, new_values)
+    employee.assign_attributes(new_values)
+  end
+
+  # because updates can be slow for a very big DB table, then you can move the update logic into a background job
+  # you can even batch the updates into a job like below
+
+  def self.quickery_before_association_update(employees, record_to_be_updated, new_values)
+    employees.find_in_batches(batch_size: 2000) do |grouped_employees|
+      BatchQuickeryUpdatesJob.perform_later(self.class.to_s, grouped_employees.pluck(:id), new_values)
+    end
+  end
+
+  def self.quickery_before_association_destroy(employees, record_to_be_destroyed, new_values)
+    employees.find_in_batches(batch_size: 2000) do |grouped_employees|
+      BatchQuickeryUpdatesJob.perform_later(self.class.to_s, grouped_employees.pluck(:id), new_values)
+    end
+  end
+end
+
+# app/jobs/batch_quickery_updates_job.rb
+class BatchQuickeryUpdatesJob < ApplicationJob
+  # or probably you have a :low_priority queue?
+  queue_as :default
+
+  def perform(model_str, ids, new_values)
+    model = model_str.safe_constantize
+    model.where(id: ids).update_all(new_values)
+  end
+end
+```
+
+### Advanced Usage: Formatting Values
+
+```ruby
+class Employee < ApplicationRecord
+  belongs_to :branch
+
+  quickery branch: { company: { name: :branch_company_name } }
+
+  def self.quickery_before_create_or_update(employee, new_values)
+    employee.assign_attributes(quickery_format_values(new_values))
+  end
+
+  def self.quickery_before_association_update(employees, record_to_be_updated, new_values)
+    employees.update_all(quickery_format_values(new_values))
+  end
+
+  def self.quickery_before_association_destroy(employees, record_to_be_destroyed, new_values)
+    employees.update_all(quickery_format_values(new_values))
+  end
+
+  private
+
+  # example (you can rename this method):
+  def self.quickery_format_values(values)
+    formatted_values = {}
+
+    :branch_company_name.tap do |attr|
+      # remove trailing white spaces and force-single-space between words, and then capitalise all characters
+      formatted_values[attr] = values[attr].squish.upcase if values.has_key? attr
+    end
+
+    :user_first_name.tap do |attr|
+      # only save the first 30 characters of user_first_name string
+      formatted_values[attr] = values[attr][0...30] if values.has_key? attr
+    end
+
+    formatted_values
+  end
+end
+```
+
+### Advanced Usage: Computed Attributes / Values
+
+```ruby
+class Employee < ApplicationRecord
+  belongs_to :branch
+
+  quickery branch: { company: { name: :branch_company_name } }
+
+  def self.quickery_before_create_or_update(employee, new_values)
+    employee.assign_attributes(quickery_with_computed_values(employee, new_values))
+  end
+
+  def self.quickery_before_association_update(employees, record_to_be_updated, new_values)
+    employee.find_each do |employee|
+      employee.update!(quickery_with_computed_values(employee, new_values))
+    end
+  end
+
+  def self.quickery_before_association_destroy(employees, record_to_be_destroyed, new_values)
+    employee.find_each do |employee|
+      employee.update!(quickery_with_computed_values(employee, new_values))
+    end
+  end
+
+  private
+
+  # example (you can rename this method):
+  def self.quickery_with_computed_values(employee, values)
+    with_computed_values = {}
+
+    if values.has_key?(:user_first_name) || values.has_key?(:user_last_name)
+      # concatenate first name and last name
+      with_computed_values[:user_full_name] = "#{values[:user_first_name]} #{values[:user_last_name]}".strip
+    end
+
+    # you can add logic that specifically depends on the record like the following:
+    if employee.is_current_employee?
+      if values.has_key? :branch_company_name
+        # concatenate a unique code for the employee: i.e. a value of "11-5-1239"
+        with_computed_values[:unique_codename] = "#{employee.branch.company.id}-#{employee.branch.id}-#{employee.id}"
+      end
+    end
+
+    with_computed_values
+  end
+end
+```
+
 ## Gotchas
 * Quickery makes use of Rails model callbacks such as `before_update`. This meant that data-integrity holds unless `update_columns` or `update_column` is used which bypasses model callbacks, or unless any manual SQL update is performed.
 * Quickery does not automatically update old records existing in the database that were created before you integrate Quickery, or before you add new/more Quickery-attributes for that model. One solution is [`recreate_quickery_cache!`](#recreate_quickery_cache) below.
@@ -194,6 +356,8 @@ end
 
 * defines a set of "hidden" Quickery `before_create`, `before_update`, and `before_destroy` callbacks needed by Quickery to perform the "syncing" of attribute values
 
+* can override `self.quickery_before_create_or_update`, `self.quickery_before_association_update`, `self.quickery_before_association_destroy` for advanced usage such as moving the update logic into a background job, or formatting of the quickery-defined attributes, etc...
+
 #### Class Methods:
 
 ##### `quickery(mappings)`
@@ -248,7 +412,6 @@ end
 * Possibly support two-way mapping of attributes? So that you can do, say... `employee.update!(branch_company_name: 'somenewcompanyname')`
 * Support `has_many` as currently only `belongs_to` is supported. This would then allow us to cache Array of values.
 * Support custom-methods-values like [`persistize`](https://github.com/bebanjo/persistize), if it's easy enough to integrate something similar
-* Support background-processing like in [`flattery`](https://github.com/evendis/flattery)
 
 ## Other Similar Gems
 See [my detailed comparisons](other_similar_gems_comparison.md)
@@ -273,6 +436,8 @@ See [my detailed comparisons](other_similar_gems_comparison.md)
 5. Create new Pull Request
 
 ## Changelog
+* 1.2.0
+  * DONE: (TODO) added overrideable methods for custom callback logic (i.e. move update logic instead into a background job)
 * 1.1.0
   * added helper method [`determine_quickery_values`](#determine_quickery_values)
   * fixed `recreate_quickery_cache!` raising `NilClass` error when the immediate association is nil

data/lib/quickery.rb

@@ -3,5 +3,4 @@ Dir[__dir__ + '/quickery/active_record_extensions/*.rb'].each {|file| require fi
 Dir[__dir__ + '/quickery/errors/*.rb'].each {|file| require file }
 
 module Quickery
-  # Your code goes here...
 end

data/lib/quickery/active_record_extensions/callbacks.rb

@@ -24,6 +24,8 @@ module Quickery
           changed_attributes = changes.keys
 
           if model.quickery_association_chain_dependers.present?
+            new_values = {}.with_indifferent_access
+
             model.quickery_association_chain_dependers.each do |association_chain_depender|
               quickery_builder = association_chain_depender.quickery_builder
               depender_column_name = quickery_builder.depender_column_name
@@ -37,9 +39,11 @@ module Quickery
                   new_value = dependee_record.send(dependee_column_name)
                 end
 
-                assign_attributes(depender_column_name => new_value)
+                new_values[depender_column_name] = new_value
               end
             end
+
+            self.class.quickery_before_create_or_update(self, new_values)
           end
         end
 
@@ -48,6 +52,8 @@ module Quickery
           changed_attributes = changes.keys
 
           if model.quickery_association_chain_dependers.present?
+            new_values = {}.with_indifferent_access
+
             model.quickery_association_chain_dependers.each do |association_chain_depender|
               quickery_builder = association_chain_depender.quickery_builder
               depender_column_name = quickery_builder.depender_column_name
@@ -61,12 +67,14 @@ module Quickery
                   new_value = dependee_record.send(dependee_column_name)
                 end
 
-                assign_attributes(depender_column_name => new_value)
+                new_values[depender_column_name] = new_value
               end
             end
+
+            self.class.quickery_before_create_or_update(self, new_values)
           end
 
-          dependent_records_attributes_to_be_updated = {}
+          dependent_records_attributes_to_be_updated = {}.with_indifferent_access
 
           if model.quickery_association_chain_dependees.present?
             model.quickery_association_chain_dependees.each do |association_chain_dependee|
@@ -79,9 +87,9 @@ module Quickery
 
                 dependent_records = association_chain_dependee.dependent_records(self)
                 # use the SQL as the uniqueness identifier, so that multiple quickery-attributes dependent-records are updated in one go, instead of updating each
-                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym] ||= {}
+                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym] ||= {}.with_indifferent_access
                 dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:dependent_records] ||= dependent_records
-                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values] ||= {}
+                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values] ||= {}.with_indifferent_access
                 dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values][depender_column_name.to_sym] = new_value
               end
             end
@@ -103,9 +111,9 @@ module Quickery
 
                 dependent_records = association_chain_intermediary.dependent_records(self)
                 # use the SQL as the uniqueness identifier, so that multiple quickery-attributes dependent-records are updated in one go, instead of updating each
-                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym] ||= {}
+                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym] ||= {}.with_indifferent_access
                 dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:dependent_records] ||= dependent_records
-                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values] ||= {}
+                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values] ||= {}.with_indifferent_access
                 dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values][depender_column_name.to_sym] = new_value
               end
             end
@@ -115,14 +123,14 @@ module Quickery
             dependent_records = hash.fetch(:dependent_records)
             new_values = hash.fetch(:new_values)
 
-            dependent_records.update_all(new_values)
+            dependent_records.model.quickery_before_association_update(dependent_records, self, new_values)
           end
         end
 
         def quickery_before_destroy_callback
           model = self.class
 
-          dependent_records_attributes_to_be_updated = {}
+          dependent_records_attributes_to_be_updated = {}.with_indifferent_access
 
           if model.quickery_association_chain_dependees.present?
             model.quickery_association_chain_dependees.each do |association_chain_dependee|
@@ -135,9 +143,9 @@ module Quickery
 
                 dependent_records = association_chain_dependee.dependent_records(self)
                 # use the SQL as the uniqueness identifier, so that multiple quickery-attributes dependent-records are updated in one go, instead of updating each
-                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym] ||= {}
+                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym] ||= {}.with_indifferent_access
                 dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:dependent_records] ||= dependent_records
-                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values] ||= {}
+                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values] ||= {}.with_indifferent_access
                 dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values][depender_column_name.to_sym] = new_value
               end
             end
@@ -154,9 +162,9 @@ module Quickery
 
                 dependent_records = association_chain_intermediary.dependent_records(self)
                 # use the SQL as the uniqueness identifier, so that multiple quickery-attributes dependent-records are updated in one go, instead of updating each
-                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym] ||= {}
+                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym] ||= {}.with_indifferent_access
                 dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:dependent_records] ||= dependent_records
-                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values] ||= {}
+                dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values] ||= {}.with_indifferent_access
                 dependent_records_attributes_to_be_updated[dependent_records.to_sql.to_sym][:new_values][depender_column_name.to_sym] = new_value
               end
             end
@@ -166,7 +174,7 @@ module Quickery
             dependent_records = hash.fetch(:dependent_records)
             new_values = hash.fetch(:new_values)
 
-            dependent_records.update_all(new_values)
+            dependent_records.model.quickery_before_association_destroy(dependent_records, self, new_values)
           end
         end
       end

data/lib/quickery/active_record_extensions/dsl.rb

@@ -18,6 +18,21 @@ module Quickery
           mappings_builder = MappingsBuilder.new(model: self, mappings: mappings.with_indifferent_access)
           mappings_builder.map_attributes
         end
+
+        # subclass overrideable
+        def quickery_before_create_or_update(dependent_record, new_values)
+          dependent_record.assign_attributes(new_values)
+        end
+
+        # subclass overrideable
+        def quickery_before_association_update(dependent_records, record_to_be_updated, new_values)
+          dependent_records.update_all(new_values)
+        end
+
+        # subclass overrideable
+        def quickery_before_association_destroy(dependent_records, record_to_be_destroyed, new_values)
+          dependent_records.update_all(new_values)
+        end
       end
 
       module InstanceMethods

data/lib/quickery/version.rb

@@ -1,3 +1,3 @@
 module Quickery
-  VERSION = '1.1.0'
+  VERSION = '1.2.0'
 end

data/other_similar_gems_comparison.md

@@ -109,9 +109,6 @@
     * Rails 4 seems to be also not supported. I was getting `ArgumentError (wrong number of arguments (given 1, expected 0))` when doing `User.create` inside rails console.
 
 * [flattery v0.1.0](https://github.com/evendis/flattery) :
-  * Pros against Quickery:
-    * allows custom update method
-    * allows "updates" as a background process
   * Cons against Quickery:
     * Rails 5 is not part of its supported list in their github page. And just to try it out on a Rails 5 app, `Flattery::ValueProvider` did not seem to work, because values are not pushed to the `:notes`'s `:category_name` values.
     * batch-update in one go for multiple quickery-defined attributes instead of updating each

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quickery
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Jules Roman Polidario
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-13 00:00:00.000000000 Z
+date: 2018-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties