Add support for HABTM writes

Adds `disassociate` method to resource/adapter, which mirrors
`associate`. This will be helpful in other contexts as well.

Author: Lee Richmond

lib/jsonapi_compliable/adapters/abstract.rb

@@ -237,6 +237,46 @@ def associate(parent, child, association_name, association_type)
         raise 'you must override #associate in an adapter subclass'
       end
 
+      # Remove the association without destroying objects
+      #
+      # This is NOT needed in the standard use case. The standard use case would be:
+      #
+      #   def update(attrs)
+      #     # attrs[:the_foreign_key] is nil, so updating the record disassociates
+      #   end
+      #
+      # However, sometimes you need side-effect or elsewise non-standard behavior. Consider
+      # using {{https://github.com/mbleigh/acts-as-taggable-on acts_as_taggable_on}} gem:
+      #
+      #   # Not actually needed, just an example
+      #   def disassociate(parent, child, association_name, association_type)
+      #     parent.tag_list.remove(child.name)
+      #   end
+      #
+      # @example Basic accessor
+      #   def disassociate(parent, child, association_name, association_type)
+      #     if association_type == :has_many
+      #       parent.send(association_name).delete(child)
+      #     else
+      #       child.send(:"#{association_name}=", nil)
+      #     end
+      #   end
+      #
+      # +association_name+ and +association_type+ come from your sideload
+      # configuration:
+      #
+      #   allow_sideload :the_name, type: the_type do
+      #     # ... code.
+      #   end
+      #
+      # @param parent The parent object (via the JSONAPI 'relationships' graph)
+      # @param child The child object (via the JSONAPI 'relationships' graph)
+      # @param association_name The 'relationships' key we are processing
+      # @param association_type The Sideload type (see Sideload#type). Usually :has_many/:belongs_to/etc
+      def disassociate(parent, child, association_name, association_type)
+        raise 'you must override #disassociate in an adapter subclass'
+      end
+
       # This module gets mixed in to Sideload classes
       # This is where you define methods like has_many,
       # belongs_to etc that wrap the lower-level Sideload#allow_sideload

lib/jsonapi_compliable/adapters/active_record.rb

@@ -75,11 +75,24 @@ def associate(parent, child, association_name, association_type)
         if association_type == :has_many
           parent.association(association_name).loaded!
           parent.association(association_name).add_to_target(child, :skip_callbacks)
+        elsif association_type == :habtm
+          parent.send(association_name) << child
         else
           child.send("#{association_name}=", parent)
         end
       end
 
+      # When a has_and_belongs_to_many relationship, we don't have a foreign
+      # key that can be null'd. Instead, go through the ActiveRecord API.
+      # @see Adapters::Abstract#disassociate
+      def disassociate(parent, child, association_name, association_type)
+        if association_type == :habtm
+          parent.send(association_name).delete(child)
+        else
+          # Nothing to do here, happened when we merged foreign key
+        end
+      end
+
       # (see Adapters::Abstract#create)
       def create(model_class, create_params)
         instance = model_class.new(create_params)

lib/jsonapi_compliable/resource.rb

@@ -543,10 +543,28 @@ def destroy(id)
       adapter.destroy(model, id)
     end
 
+    # Delegates #associate to adapter. Built for overriding.
+    #
+    # @see .use_adapter
+    # @see Adapters::Abstract#associate
+    # @see Adapters::ActiveRecord#associate
+    def associate(parent, child, association_name, type)
+      adapter.associate(parent, child, association_name, type)
+    end
+
+    # Delegates #disassociate to adapter. Built for overriding.
+    #
+    # @see .use_adapter
+    # @see Adapters::Abstract#disassociate
+    # @see Adapters::ActiveRecord#disassociate
+    def disassociate(parent, child, association_name, type)
+      adapter.disassociate(parent, child, association_name, type)
+    end
+
     # @api private
-    def persist_with_relationships(meta, attributes, relationships)
+    def persist_with_relationships(meta, attributes, relationships, caller_model = nil)
       persistence = JsonapiCompliable::Util::Persistence \
-        .new(self, meta, attributes, relationships)
+        .new(self, meta, attributes, relationships, caller_model)
       persistence.run
     end
 

lib/jsonapi_compliable/sideload.rb

@@ -170,24 +170,25 @@ def assign(&blk)
     end
 
     # Configure how to associate parent and child records.
-    #
-    # @example Basic attr_accessor
-    #   def associate(parent, child)
-    #     if type == :has_many
-    #       parent.send(:"#{name}").push(child)
-    #     else
-    #       child.send(:"#{name}=", parent)
-    #     end
-    #   end
+    # Delegates to #resource
     #
     # @see #name
     # @see #type
+    # @api private
     def associate(parent, child)
       association_name = @parent ? @parent.name : name
-      resource_class.config[:adapter].associate parent,
-        child,
-        association_name,
-        type
+      resource.associate(parent, child, association_name, type)
+    end
+
+    # Configure how to disassociate parent and child records.
+    # Delegates to #resource
+    #
+    # @see #name
+    # @see #type
+    # @api private
+    def disassociate(parent, child)
+      association_name = @parent ? @parent.name : name
+      resource.disassociate(parent, child, association_name, type)
     end
 
     # Define an attribute that groups the parent records. For instance, with

lib/jsonapi_compliable/util/persistence.rb

@@ -5,11 +5,12 @@ class JsonapiCompliable::Util::Persistence
   # @param [Hash] meta see (Deserializer#meta)
   # @param [Hash] attributes see (Deserializer#attributes)
   # @param [Hash] relationships see (Deserializer#relationships)
-  def initialize(resource, meta, attributes, relationships)
+  def initialize(resource, meta, attributes, relationships, caller_model)
     @resource      = resource
     @meta          = meta
     @attributes    = attributes
     @relationships = relationships
+    @caller_model  = caller_model
   end
 
   # Perform the actual save logic.
@@ -37,7 +38,7 @@ def run
     assign_temp_id(persisted, @meta[:temp_id])
     associate_parents(persisted, parents)
 
-    children = process_has_many(@relationships) do |x|
+    children = process_has_many(@relationships, persisted) do |x|
       update_foreign_key(persisted, x[:attributes], x)
     end
 
@@ -49,7 +50,11 @@ def run
 
   # The child's attributes should be modified to nil-out the
   # foreign_key when the parent is being destroyed or disassociated
+  #
+  # This is not the case for HABTM, whose "foreign key" is a join table
   def update_foreign_key(parent_object, attrs, x)
+    return if x[:sideload].type == :habtm
+
     if [:destroy, :disassociate].include?(x[:meta][:method])
       attrs[x[:foreign_key]] = nil
       update_foreign_type(attrs, x, null: true) if x[:is_polymorphic]
@@ -72,33 +77,45 @@ def update_foreign_key_for_parents(parents)
 
   def associate_parents(object, parents)
     parents.each do |x|
-      x[:sideload].associate(x[:object], object) if x[:object] && object
+      if x[:object] && object
+        if x[:meta][:method] == :disassociate
+          x[:sideload].disassociate(x[:object], object)
+        else
+          x[:sideload].associate(x[:object], object)
+        end
+      end
     end
   end
 
   def associate_children(object, children)
     children.each do |x|
-      x[:sideload].associate(object, x[:object]) if x[:object] && object
+      if x[:object] && object
+        if x[:meta][:method] == :disassociate
+          x[:sideload].disassociate(object, x[:object])
+        else
+          x[:sideload].associate(object, x[:object])
+        end
+      end
     end
   end
 
   def persist_object(method, attributes)
     case method
       when :destroy
-        @resource.destroy(attributes[:id])
-      when :disassociate, nil
-        @resource.update(attributes)
+        call_resource_method(:destroy, attributes[:id], @caller_model)
+      when :update, nil, :disassociate
+        call_resource_method(:update, attributes, @caller_model)
       else
-        @resource.send(method, attributes)
+        call_resource_method(:create, attributes, @caller_model)
     end
   end
 
-  def process_has_many(relationships)
+  def process_has_many(relationships, caller_model)
     [].tap do |processed|
       iterate(except: [:polymorphic_belongs_to, :belongs_to]) do |x|
         yield x
         x[:object] = x[:sideload].resource
-          .persist_with_relationships(x[:meta], x[:attributes], x[:relationships])
+          .persist_with_relationships(x[:meta], x[:attributes], x[:relationships], caller_model)
         processed << x
       end
     end
@@ -128,4 +145,23 @@ def iterate(only: [], except: [])
       yield x
     end
   end
+
+  # In the Resource, we want to allow:
+  #
+  # def create(attrs)
+  #
+  # and
+  #
+  # def create(attrs, parent = nil)
+  #
+  # 'parent' is an optional parameter that should not be part of the
+  # method signature in most use cases.
+  def call_resource_method(method_name, attributes, caller_model)
+    method = @resource.method(method_name)
+    if [2,-2].include?(method.arity)
+      method.call(attributes, caller_model)
+    else
+      method.call(attributes)
+    end
+  end
 end

spec/fixtures/employee_directory.rb

@@ -11,6 +11,15 @@
     t.string :address
   end
 
+  create_table :teams do |t|
+    t.string :name
+  end
+
+  create_table :employee_teams do |t|
+    t.integer :team_id
+    t.integer :employee_id
+  end
+
   create_table :employees do |t|
     t.string :workspace_type
     t.integer :workspace_id
@@ -40,6 +49,16 @@ class Classification < ApplicationRecord
   validates :description, presence: true
 end
 
+class Team < ApplicationRecord
+  has_many :employee_teams
+  has_many :employees, through: :employee_teams
+end
+
+class EmployeeTeam < ApplicationRecord
+  belongs_to :team
+  belongs_to :employee
+end
+
 class Office < ApplicationRecord
   has_many :employees, as: :workspace
 end
@@ -53,6 +72,9 @@ class Employee < ApplicationRecord
   belongs_to :classification
   has_many :positions
   validates :first_name, presence: true
+
+  has_many :employee_teams
+  has_many :teams, through: :employee_teams
 end
 
 class Position < ApplicationRecord
@@ -73,6 +95,11 @@ class ClassificationResource < ApplicationResource
   model Classification
 end
 
+class TeamResource < ApplicationResource
+  type :teams
+  model Team
+end
+
 class DepartmentResource < ApplicationResource
   type :departments
   model Department
@@ -110,6 +137,11 @@ class EmployeeResource < ApplicationResource
     scope: -> { Position.all },
     foreign_key: :employee_id,
     resource: PositionResource
+  has_and_belongs_to_many :teams,
+    resource: TeamResource,
+    scope: -> { Team.all },
+    foreign_key: { employee_teams: :employee_id }
+
   polymorphic_belongs_to :workspace,
     group_by: :workspace_type,
     groups: {
@@ -135,6 +167,12 @@ class SerializableClassification < SerializableAbstract
   attribute :description
 end
 
+class SerializableTeam < SerializableAbstract
+  type 'teams'
+
+  attribute :name
+end
+
 class SerializableEmployee < SerializableAbstract
   type 'employees'
 
@@ -144,6 +182,7 @@ class SerializableEmployee < SerializableAbstract
 
   belongs_to :classification
   has_many :positions
+  has_many :teams
 end
 
 class SerializablePosition < SerializableAbstract