iknow_view_models 2.8.4

data/lib/view_model/active_record/nested_controller_base.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'view_model/active_record/controller_base'
+
+# Controller mixin defining machinery for accessing viewmodels nested under a
+# parent. Used by Singular- and CollectionNestedControllers
+module ViewModel::ActiveRecord::NestedControllerBase
+  extend ActiveSupport::Concern
+
+  protected
+
+  def show_association(scope: nil, serialize_context: new_serialize_context)
+    associated_views = nil
+    pre_rendered = owner_viewmodel.transaction do
+      owner_view = owner_viewmodel.find(owner_viewmodel_id, eager_include: false, serialize_context: serialize_context)
+      ViewModel::Callbacks.wrap_serialize(owner_view, context: serialize_context) do
+        # Association manipulation methods construct child contexts internally
+        associated_views = owner_view.load_associated(association_name, scope: scope, serialize_context: serialize_context)
+
+        associated_views = yield(associated_views) if block_given?
+
+        child_context = owner_view.context_for_child(association_name, context: serialize_context)
+        prerender_viewmodel(associated_views, serialize_context: child_context)
+      end
+    end
+    render_json_string(pre_rendered)
+    associated_views
+  end
+
+  def write_association(serialize_context: new_serialize_context, deserialize_context: new_deserialize_context)
+    association_view = nil
+    pre_rendered = owner_viewmodel.transaction do
+      update_hash, refs = parse_viewmodel_updates
+
+      owner_view = owner_viewmodel.find(owner_viewmodel_id, eager_include: false, serialize_context: serialize_context)
+
+      association_view = owner_view.replace_associated(association_name, update_hash,
+                                                       references: refs,
+                                                       deserialize_context: deserialize_context)
+
+      ViewModel::Callbacks.wrap_serialize(owner_view, context: serialize_context) do
+        child_context = owner_view.context_for_child(association_name, context: serialize_context)
+        ViewModel.preload_for_serialization(association_view, serialize_context: child_context)
+        prerender_viewmodel(association_view, serialize_context: child_context)
+      end
+    end
+    render_json_string(pre_rendered)
+    association_view
+  end
+
+  def destroy_association(collection, serialize_context: new_serialize_context, deserialize_context: new_deserialize_context)
+    empty_update = collection ? [] : nil
+    owner_viewmodel.deserialize_from_view(owner_update_hash(empty_update),
+                                          deserialize_context: deserialize_context)
+    render_viewmodel(empty_update, serialize_context: serialize_context)
+  end
+
+  def association_data
+    owner_viewmodel._association_data(association_name)
+  end
+
+  def owner_update_hash(update)
+    {
+      ViewModel::ID_ATTRIBUTE   => owner_viewmodel_id,
+      ViewModel::TYPE_ATTRIBUTE => owner_viewmodel.view_name,
+      association_name.to_s     => update,
+    }
+  end
+
+  def owner_viewmodel_id(required: true)
+    id_param_name = owner_viewmodel.view_name.downcase + '_id'
+    default = required ? {} : { default: nil }
+    parse_param(id_param_name, **default)
+  end
+
+  included do
+    delegate :owner_viewmodel, :association_name, to: 'self.class'
+  end
+
+  class_methods do
+    attr_accessor :owner_viewmodel, :association_name
+
+    def nested_in(owner, as:)
+      unless owner.is_a?(Class) && owner < ViewModel::Record
+        owner = ViewModel::Registry.for_view_name(owner.to_s.camelize)
+      end
+
+      self.owner_viewmodel = owner
+      raise ArgumentError.new("Could not find owner ViewModel class '#{owner_name}'") if owner_viewmodel.nil?
+      self.association_name = as
+    end
+  end
+end

data/lib/view_model/active_record/singular_nested_controller.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Controller mixin for accessing a root ViewModel which can be accessed
+# individually by a parent model. Enabled by calling `nested_in :parent, as:
+# :child` on the viewmodel controller
+
+# Contributes the following routes:
+# POST   /parents/:parent_id/child   #create_associated  -- deserialize (possibly existing) child, replacing existing child
+# GET    /parents/:parent_id/child   #show_associated    -- show child of parent
+# DELETE /parents/:parent_id/child   #destroy_associated -- delete relationship between parent and its child (possibly garbage-collecting child)
+
+## Inherits the following routes to manipulate children directly:
+# POST   /children      #create -- create or update without parent
+# GET    /children      #index  -- list all child models regardless of parent
+# GET    /children/:id  #show
+# DELETE /children/:id  #destroy
+
+require 'view_model/active_record/nested_controller_base'
+module ViewModel::ActiveRecord::SingularNestedController
+  extend ActiveSupport::Concern
+  include ViewModel::ActiveRecord::NestedControllerBase
+
+  def show_associated(scope: nil, serialize_context: new_serialize_context, deserialize_context: new_deserialize_context)
+    show_association(scope: scope, serialize_context: serialize_context)
+  end
+
+  def create_associated(serialize_context: new_serialize_context, deserialize_context: new_deserialize_context)
+    write_association(serialize_context: serialize_context, deserialize_context: deserialize_context)
+  end
+
+  def destroy_associated(serialize_context: new_serialize_context, deserialize_context: new_deserialize_context)
+    destroy_association(false, serialize_context: serialize_context, deserialize_context: deserialize_context)
+  end
+end

data/lib/view_model/active_record/update_context.rb

@@ -0,0 +1,252 @@
+# Assembles an update operation tree from user input. Handles the interlinking
+# and model of update operations, but does not handle the actual user data nor
+# the mechanism by which it is applied to models.
+class ViewModel::ActiveRecord
+  class UpdateContext
+    ReleaseEntry = Struct.new(:viewmodel, :association_data) do
+      def initialize(*)
+        super
+        @claimed = false
+      end
+
+      def release!
+        model = viewmodel.model
+        case association_data.direct_reflection.options[:dependent]
+        when :delete
+          model.delete
+        when :destroy
+          model.destroy
+        end
+      end
+
+      def claimed!
+        @claimed = true
+      end
+
+      def claimed?
+        @claimed
+      end
+    end
+
+    class ReleasePool
+      def initialize
+        # hash of { ViewModel::Reference => ReleaseEntry } for models
+        # that have been released by nodes we've already visited
+        @released_viewmodels = {}
+      end
+
+      def include?(key)
+        @released_viewmodels.has_key?(key)
+      end
+
+      def release_to_pool(viewmodel, association_data)
+        @released_viewmodels[viewmodel.to_reference] =
+          ReleaseEntry.new(viewmodel, association_data)
+      end
+
+      def claim_from_pool(key)
+        if (entry = @released_viewmodels.delete(key))
+          entry.claimed!
+          entry.viewmodel
+        end
+      end
+
+      def release_all!
+        @released_viewmodels.each_value(&:release!)
+      end
+    end
+
+    def self.build!(root_update_data, referenced_update_data, root_type: nil)
+      if root_type.present? && (bad_types = root_update_data.map(&:viewmodel_class).to_set.delete(root_type)).present?
+        raise ViewModel::DeserializationError::InvalidViewType.new(root_type.view_name, bad_types.map { |t| ViewModel::Reference.new(t, nil) })
+      end
+
+      self.new
+        .build_root_update_operations(root_update_data, referenced_update_data)
+        .assemble_update_tree
+    end
+
+    # TODO an unfortunate abstraction violation. The `append` case constructs an
+    # update tree and later injects the context of parent and position.
+    def root_updates
+      @root_update_operations
+    end
+
+    def initialize
+      @root_update_operations       = [] # The subject(s) of this update
+      @referenced_update_operations = {} # Shared data updates, referred to by a ref hash
+
+      # Set of ViewModel::Reference used to assert only a single update is
+      # present for each viewmodel
+      @updated_viewmodel_references = Set.new
+
+      # hash of { ViewModel::Reference => deferred UpdateOperation }
+      # for linked partially-constructed node updates
+      @worklist = {}
+
+      @release_pool = ReleasePool.new
+    end
+
+    # Processes parsed (UpdateData) root updates and referenced updates into
+    # @root_update_operations and @referenced_update_operations.
+    def build_root_update_operations(root_updates, referenced_updates)
+      # Look up viewmodel classes for each tree with eager_includes. Note this
+      # won't yet include through a polymorphic boundary: for now we become
+      # lazy-loading and slow every time that happens.
+
+      # Combine our root and referenced updates, and separate by viewmodel type
+      updates_by_viewmodel_class =
+        root_updates.lazily
+          .map { |root_update| [nil, root_update] }
+          .concat(referenced_updates)
+          .group_by { |_, update_data| update_data.viewmodel_class }
+
+      # For each viewmodel type, look up referenced models and construct viewmodels to update
+      updates_by_viewmodel_class.each do |viewmodel_class, updates|
+        dependencies = updates.map { |_, upd| upd.preload_dependencies }
+                       .inject { |acc, deps| acc.merge!(deps) }
+
+        model_ids = updates.map { |_, update_data| update_data.id unless update_data.new? }.compact
+
+        existing_models =
+          if model_ids.present?
+            model_class = viewmodel_class.model_class
+            models = model_class.where(model_class.primary_key => model_ids).to_a
+
+            if models.size < model_ids.size
+              missing_model_ids = model_ids - models.map(&:id)
+              missing_viewmodel_refs = missing_model_ids.map  { |id| ViewModel::Reference.new(viewmodel_class, id) }
+              raise ViewModel::DeserializationError::NotFound.new(missing_viewmodel_refs)
+            end
+
+            DeepPreloader.preload(models, dependencies)
+            models.index_by(&:id)
+          else
+            {}
+          end
+
+        updates.each do |ref, update_data|
+          viewmodel =
+            if update_data.new?
+              viewmodel_class.for_new_model(id: update_data.id)
+            else
+              viewmodel_class.new(existing_models[update_data.id])
+            end
+
+          update_op = new_update(viewmodel, update_data)
+
+          if ref.nil?
+            @root_update_operations << update_op
+          else
+            # TODO make sure that referenced subtree hashes are unique and provide a decent error message
+            # not strictly necessary, but will save confusion
+            @referenced_update_operations[ref] = update_op
+          end
+        end
+      end
+
+      self
+    end
+
+    # Applies updates and subsequently releases. Returns the updated viewmodels.
+    def run!(deserialize_context:)
+      updated_viewmodels = @root_update_operations.map do |root_update|
+        root_update.run!(deserialize_context: deserialize_context)
+      end
+
+      @release_pool.release_all!
+
+      if updated_viewmodels.present?
+        # Deferred database constraints may have been violated by changes during
+        # deserialization. VM::AR promises that any errors during deserialization
+        # will be raised as a ViewModel::DeserializationError, so check constraints
+        # and raise before exit.
+        check_deferred_constraints!(updated_viewmodels.first.model.class)
+      end
+
+      updated_viewmodels
+    end
+
+    def assemble_update_tree
+      @root_update_operations.each do |root_update|
+        root_update.build!(self)
+      end
+
+      while @worklist.present?
+        key = @worklist.keys.detect { |k| @release_pool.include?(k) }
+        if key.nil?
+          raise ViewModel::DeserializationError::ParentNotFound.new(@worklist.keys)
+        end
+
+        deferred_update = @worklist.delete(key)
+        deferred_update.viewmodel = @release_pool.claim_from_pool(key)
+        deferred_update.build!(self)
+      end
+
+      dangling_references = @referenced_update_operations.reject { |ref, upd| upd.built? }.map { |ref, upd| upd.viewmodel.to_reference }
+      if dangling_references.present?
+        raise ViewModel::DeserializationError::InvalidStructure.new("References not referred to from roots", dangling_references)
+      end
+
+      self
+    end
+
+    ## Methods for objects being built in this context
+
+    # We require the updates to be recorded in the context so we can enforce the
+    # property that each viewmodel is in the tree at most once. To avoid mistakes,
+    # we require construction to go via methods that do this tracking.
+
+    def new_deferred_update(viewmodel_reference, update_data, reparent_to: nil, reposition_to: nil)
+      update_operation = ViewModel::ActiveRecord::UpdateOperation.new(
+        nil, update_data, reparent_to: reparent_to, reposition_to: reposition_to)
+      check_unique_update!(viewmodel_reference)
+      @worklist[viewmodel_reference] = update_operation
+    end
+
+    def new_update(viewmodel, update_data, reparent_to: nil, reposition_to: nil)
+      update = ViewModel::ActiveRecord::UpdateOperation.new(
+        viewmodel, update_data, reparent_to: reparent_to, reposition_to: reposition_to)
+
+      if (vm_ref = update.viewmodel_reference).present?
+        check_unique_update!(vm_ref)
+      end
+
+      update
+    end
+
+    def check_unique_update!(vm_ref)
+      unless @updated_viewmodel_references.add?(vm_ref)
+        raise ViewModel::DeserializationError::DuplicateNodes.new(vm_ref.viewmodel_class.view_name, vm_ref)
+      end
+    end
+
+    def resolve_reference(ref, blame_reference)
+      @referenced_update_operations.fetch(ref) do
+        raise ViewModel::DeserializationError::InvalidSharedReference.new(ref, blame_reference)
+      end
+    end
+
+    def try_take_released_viewmodel(vm_ref)
+      @release_pool.claim_from_pool(vm_ref)
+    end
+
+    def release_viewmodel(viewmodel, association_data)
+      @release_pool.release_to_pool(viewmodel, association_data)
+    end
+
+    # Immediately enforce any deferred database constraints (when using
+    # Postgres) and convert them to DeserializationErrors.
+    #
+    # Note that there's no effective way to tie such a failure back to the
+    # individual node that caused it, without attempting to parse Postgres'
+    # human-readable error details.
+    def check_deferred_constraints!(model_class)
+      if model_class.connection.adapter_name == "PostgreSQL"
+        model_class.connection.execute("SET CONSTRAINTS ALL IMMEDIATE")
+      end
+    rescue ::ActiveRecord::StatementInvalid => ex
+      raise ViewModel::DeserializationError::DatabaseConstraint.from_exception(ex)
+    end
+  end
+end

data/lib/view_model/active_record/update_data.rb

@@ -0,0 +1,749 @@
+require 'renum'
+require 'view_model/schemas'
+
+class ViewModel::ActiveRecord
+  using ViewModel::Utils::Collections
+
+  class FunctionalUpdate
+    def self.for_type(type)
+      case type
+      when Append::NAME
+        return Append
+      when Remove::NAME
+        return Remove
+      when Update::NAME
+        return Update
+      else
+        raise ArgumentError.new("invalid functional update type #{type}")
+      end
+    end
+
+    class Append
+      NAME = 'append'
+      attr_accessor :before, :after
+      attr_reader :contents
+      def initialize(contents)
+        @contents = contents
+      end
+    end
+
+    class Update
+      NAME = 'update'
+      attr_reader :contents
+      def initialize(contents)
+        @contents = contents
+      end
+    end
+
+    class Remove
+      NAME = 'remove'
+      attr_reader :removed_vm_refs
+
+      def initialize(removed_vm_refs)
+        @removed_vm_refs = removed_vm_refs
+      end
+    end
+  end
+
+  # Parser for collection updates. Collection updates have a regular
+  # structure, but vary based on the contents. Parsing a {direct,
+  # owned} collection recurses deeply and creates a tree of
+  # UpdateDatas, while parsing a {through, shared} collection collects
+  # reference strings.
+  class AbstractCollectionUpdate
+    # Wraps a complete collection of new data: either UpdateDatas for owned
+    # collections or reference strings for shared.
+    class Replace
+      attr_reader :contents
+      def initialize(contents)
+        @contents = contents
+      end
+    end
+
+    # Wraps an ordered list of FunctionalUpdates, each of whose `contents` are
+    # either UpdateData for owned collections or references for shared.
+    class Functional
+      attr_reader :actions
+      def initialize(actions)
+        @actions = actions
+      end
+
+      def contents
+        actions.lazy
+          .reject { |action| action.is_a?(FunctionalUpdate::Remove) }
+          .flat_map(&:contents)
+          .to_a
+      end
+
+      def vm_references(update_context)
+        used_vm_refs(update_context) + removed_vm_refs
+      end
+
+      # Resolve ViewModel::References used in the update's contents, whether by
+      # reference or value.
+      def used_vm_refs(update_context)
+        raise "abstract"
+      end
+
+      def removed_vm_refs
+        actions.lazy
+          .select { |action| action.is_a?(FunctionalUpdate::Remove) }
+          .flat_map(&:removed_vm_refs)
+          .to_a
+      end
+
+      def check_for_duplicates!(update_context, blame)
+        duplicate_vm_refs = vm_references(update_context).duplicates
+        if duplicate_vm_refs.present?
+          formatted_invalid_ids = duplicate_vm_refs.keys.map(&:to_s).join(', ')
+          raise ViewModel::DeserializationError::InvalidStructure.new("Duplicate functional update targets: [#{formatted_invalid_ids}]", blame)
+        end
+      end
+    end
+
+    class Parser
+      def initialize(association_data, blame_reference, valid_reference_keys)
+        @association_data     = association_data
+        @blame_reference      = blame_reference
+        @valid_reference_keys = valid_reference_keys
+      end
+
+      def parse(value)
+        case value
+        when Array
+          replace_update_type.new(parse_contents(value))
+
+        when Hash
+          ViewModel::Schemas.verify_schema!(functional_update_schema, value)
+          functional_updates = value[ACTIONS_ATTRIBUTE].map { |action| parse_action(action) }
+          functional_update_type.new(functional_updates)
+
+        else
+          raise ViewModel::DeserializationError::InvalidSyntax.new(
+                  "Could not parse non-array value for collection association '#{association_data}'",
+                  blame_reference)
+        end
+      end
+
+      protected
+
+      attr_reader :association_data, :blame_reference, :valid_reference_keys
+
+      private
+
+      def parse_action(action)
+        type = action[ViewModel::TYPE_ATTRIBUTE]
+
+        case type
+        when FunctionalUpdate::Remove::NAME
+          parse_remove_action(action)
+        when FunctionalUpdate::Append::NAME
+          parse_append_action(action)
+        when FunctionalUpdate::Update::NAME
+          parse_update_action(action)
+        else
+          raise ViewModel::DeserializationError::InvalidSyntax.new(
+                  "Unknown action type '#{type}'",
+                  blame_reference)
+        end
+      end
+
+      ## Action parsers
+      #
+      # The shape of the actions are always the same
+
+      # Parse an anchor for a functional_update, before/after
+      # May only contain type and id fields, is never a reference even for shared collections.
+      def parse_anchor(child_hash) # final
+        child_metadata = ViewModel.extract_reference_only_metadata(child_hash)
+
+        child_viewmodel_class =
+          association_data.viewmodel_class_for_name(child_metadata.view_name)
+
+        if child_viewmodel_class.nil?
+          raise ViewModel::DeserializationError::InvalidAssociationType.new(
+                  association_data.association_name.to_s,
+                  child_metadata.view_name,
+                  blame_reference)
+        end
+
+        ViewModel::Reference.new(child_viewmodel_class, child_metadata.id)
+      end
+
+      def parse_append_action(action) # final
+        ViewModel::Schemas.verify_schema!(append_action_schema, action)
+
+        values = action[VALUES_ATTRIBUTE]
+        update = FunctionalUpdate::Append.new(parse_contents(values))
+
+        if (before = action[BEFORE_ATTRIBUTE])
+          update.before = parse_anchor(before)
+        end
+
+        if (after = action[AFTER_ATTRIBUTE])
+          update.after = parse_anchor(after)
+        end
+
+        if before && after
+          raise ViewModel::DeserializationError::InvalidSyntax.new(
+                  "Append may not specify both 'after' and 'before'",
+                  blame_reference)
+        end
+
+        update
+      end
+
+      def parse_update_action(action) # final
+        ViewModel::Schemas.verify_schema!(update_action_schema, action)
+
+        values = action[VALUES_ATTRIBUTE]
+        FunctionalUpdate::Update.new(parse_contents(values))
+      end
+
+      def parse_remove_action(action) # final
+        ViewModel::Schemas.verify_schema!(remove_action_schema, action)
+
+        values = action[VALUES_ATTRIBUTE]
+        FunctionalUpdate::Remove.new(parse_remove_values(values))
+      end
+
+      ## Action contents
+      #
+      # The contents of the actions are determined by the subclasses
+
+      def functional_update_schema # abstract
+        raise "abstract"
+      end
+
+      def append_action_schema # abstract
+        raise "abstract"
+      end
+
+      def remove_action_schema # abstract
+        raise "abstract"
+      end
+
+      def update_action_schema # abstract
+        raise "abstract"
+      end
+
+      def parse_contents(values) # abstract
+        raise "abstract"
+      end
+
+      # Remove values are always anchors
+      def parse_remove_values(values)
+        # There's no reasonable interpretation of a remove update that includes data.
+        # Report it as soon as we detect it.
+        invalid_entries = values.reject { |h| UpdateData.reference_only_hash?(h) }
+        if invalid_entries.present?
+          raise ViewModel::DeserializationError::InvalidSyntax.new(
+                  "Removed entities must have only #{ViewModel::TYPE_ATTRIBUTE} and #{ViewModel::ID_ATTRIBUTE} fields. " \
+                  "Invalid entries: #{invalid_entries}",
+                  blame_reference)
+        end
+
+        values.map { |value| parse_anchor(value) }
+      end
+
+      ## Value constructors
+      #
+      # ReferencedCollectionUpdates and OwnedCollectionUpdates have different
+      # behaviour, so we parameterise the result type as well.
+
+      def replace_update_type # abstract
+        raise "abstract"
+      end
+
+      def functional_update_type # abstract
+        raise "abstract"
+      end
+    end
+  end
+
+  class OwnedCollectionUpdate < AbstractCollectionUpdate
+    class Replace < AbstractCollectionUpdate::Replace
+      alias update_datas contents # as UpdateDatas
+    end
+
+    class Functional < AbstractCollectionUpdate::Functional
+      alias update_datas contents # as UpdateDatas
+
+      def used_vm_refs(update_context)
+        update_datas
+          .map { |upd| upd.viewmodel_reference if upd.id }
+          .compact
+      end
+    end
+
+    class Parser < AbstractCollectionUpdate::Parser
+      def functional_update_schema
+        UpdateData::Schemas::COLLECTION_UPDATE
+      end
+
+      def append_action_schema
+        UpdateData::Schemas::APPEND_ACTION
+      end
+
+      def remove_action_schema
+        UpdateData::Schemas::REMOVE_ACTION
+      end
+
+      def update_action_schema
+        UpdateData::Schemas::UPDATE_ACTION
+      end
+
+      def parse_contents(values)
+        values.map do |value|
+          UpdateData.parse_associated(association_data, blame_reference, valid_reference_keys, value)
+        end
+      end
+
+      def replace_update_type
+        Replace
+      end
+
+      def functional_update_type
+        Functional
+      end
+    end
+  end
+
+  class ReferencedCollectionUpdate < AbstractCollectionUpdate
+    class Replace < AbstractCollectionUpdate::Replace
+      alias references contents # as reference strings
+    end
+
+    class Functional < AbstractCollectionUpdate::Functional
+      alias references contents
+
+      def used_vm_refs(update_context)
+        references.map do |ref|
+          update_context.resolve_reference(ref, nil).viewmodel_reference
+        end
+      end
+    end
+
+    class Parser < AbstractCollectionUpdate::Parser
+      def functional_update_schema
+        UpdateData::Schemas::REFERENCED_COLLECTION_UPDATE
+      end
+
+      def append_action_schema
+        UpdateData::Schemas::REFERENCED_APPEND_ACTION
+      end
+
+      def remove_action_schema
+        UpdateData::Schemas::REFERENCED_REMOVE_ACTION
+      end
+
+      def update_action_schema
+        UpdateData::Schemas::REFERENCED_UPDATE_ACTION
+      end
+
+      def parse_contents(values)
+        invalid_entries = values.reject { |h| ref_hash?(h) }
+
+        if invalid_entries.present?
+          raise ViewModel::DeserializationError::InvalidSyntax.new(
+            "Appended/Updated entities must be specified as '#{ViewModel::REFERENCE_ATTRIBUTE}' style hashes." \
+            "Invalid entries: #{invalid_entries}",
+            blame_reference)
+        end
+
+        values.map do |x|
+          ref = ViewModel.extract_reference_metadata(x)
+          unless valid_reference_keys.include?(ref)
+            raise ViewModel::DeserializationError::InvalidSharedReference.new(ref, blame_reference)
+          end
+          ref
+        end
+      end
+
+      private
+
+      def replace_update_type
+        Replace
+      end
+
+      def functional_update_type
+        Functional
+      end
+
+      def ref_hash?(value)
+        value.size == 1 && value.has_key?(ViewModel::REFERENCE_ATTRIBUTE)
+      end
+    end
+  end
+
+  class UpdateData
+    attr_accessor :viewmodel_class, :metadata, :attributes, :associations, :referenced_associations
+    delegate :id, :view_name, :schema_version, to: :metadata
+
+    module Schemas
+      viewmodel_reference_only =
+        {
+          'type'                 => 'object',
+          'description'          => 'viewmodel reference',
+          'properties'           => { ViewModel::TYPE_ATTRIBUTE => { 'type' => 'string' },
+                                      ViewModel::ID_ATTRIBUTE   => ViewModel::Schemas::ID_SCHEMA },
+          'additionalProperties' => false,
+          'required'             => [ViewModel::TYPE_ATTRIBUTE, ViewModel::ID_ATTRIBUTE]
+        }
+
+      VIEWMODEL_REFERENCE_ONLY = JsonSchema.parse!(viewmodel_reference_only)
+
+      fupdate_base = ->(value_schema) do
+        {
+          'description' => 'functional update',
+          'type'        => 'object',
+          'properties'  => {
+            ViewModel::TYPE_ATTRIBUTE => { 'enum' => [FunctionalUpdate::Append::NAME,
+                                                      FunctionalUpdate::Update::NAME,
+                                                      FunctionalUpdate::Remove::NAME] },
+            VALUES_ATTRIBUTE => { 'type'  => 'array',
+                                  'items' => value_schema }
+          },
+          'required' => [ViewModel::TYPE_ATTRIBUTE, VALUES_ATTRIBUTE]
+        }
+      end
+
+      append_mixin = {
+        'description'          => 'collection append',
+        'additionalProperties' => false,
+        'properties'           => {
+          ViewModel::TYPE_ATTRIBUTE => { 'enum' => [FunctionalUpdate::Append::NAME] },
+          BEFORE_ATTRIBUTE          => viewmodel_reference_only,
+          AFTER_ATTRIBUTE           => viewmodel_reference_only
+        },
+      }
+
+      fupdate_owned =
+        fupdate_base.(ViewModel::Schemas::VIEWMODEL_UPDATE_SCHEMA)
+
+      fupdate_shared           =
+        fupdate_base.({ 'oneOf' => [ViewModel::Schemas::VIEWMODEL_REFERENCE_SCHEMA,
+                                    viewmodel_reference_only] })
+
+      # Referenced updates are special:
+      #  - Append requires `_ref` hashes
+      #  - Update requires `_ref` hashes
+      #  - Remove requires vm refs (type/id)
+      # Checked in code (ReferencedCollectionUpdate::Builder.parse_*_values)
+
+      APPEND_ACTION            = JsonSchema.parse!(fupdate_owned.deep_merge(append_mixin))
+      REFERENCED_APPEND_ACTION = JsonSchema.parse!(fupdate_shared.deep_merge(append_mixin))
+
+      update_mixin = {
+        'description'          => 'collection update',
+        'additionalProperties' => false,
+        'properties'           => {
+          ViewModel::TYPE_ATTRIBUTE => { 'enum' => [FunctionalUpdate::Update::NAME] }
+        },
+      }
+
+      UPDATE_ACTION            = JsonSchema.parse!(fupdate_owned.deep_merge(update_mixin))
+      REFERENCED_UPDATE_ACTION = JsonSchema.parse!(fupdate_shared.deep_merge(update_mixin))
+
+      remove_mixin = {
+        'description'          => 'collection remove',
+        'additionalProperties' => false,
+        'properties'           => {
+          ViewModel::TYPE_ATTRIBUTE => { 'enum' => [FunctionalUpdate::Remove::NAME] },
+          # The VALUES_ATTRIBUTE should be a viewmodel_reference, but in the
+          # name of error messages, we allow more keys and check the
+          # constraint in code.
+        },
+      }
+
+      REMOVE_ACTION            = JsonSchema.parse!(fupdate_owned.deep_merge(remove_mixin))
+      REFERENCED_REMOVE_ACTION = JsonSchema.parse!(fupdate_shared.deep_merge(remove_mixin))
+
+
+      collection_update = ->(base_schema) do
+        {
+          'type'                 => 'object',
+          'description'          => 'collection functional update',
+          'additionalProperties' => false,
+          'required'             => [ViewModel::TYPE_ATTRIBUTE, ACTIONS_ATTRIBUTE],
+          'properties'           => {
+            ViewModel::TYPE_ATTRIBUTE => { 'enum' => [FUNCTIONAL_UPDATE_TYPE] },
+            ACTIONS_ATTRIBUTE => { 'type' => 'array', 'items' => base_schema }
+            # The ACTIONS_ATTRIBUTE could be accurately expressed as
+            #
+            #   { 'oneOf' => [append, update, remove] }
+            #
+            # but this produces completely unusable error messages.  Instead we
+            # specify it must be an array, and defer checking to the code that
+            # can determine the schema by inspecting the type field.
+          }
+        }
+      end
+
+      COLLECTION_UPDATE            = JsonSchema.parse!(collection_update.(fupdate_owned))
+      REFERENCED_COLLECTION_UPDATE = JsonSchema.parse!(collection_update.(fupdate_shared))
+    end
+
+    def [](name)
+      case name
+      when :id
+        id
+      when :_type
+        viewmodel_class.view_name
+      else
+        attributes.fetch(name) { associations.fetch(name) { referenced_associations.fetch(name) }}
+      end
+    end
+
+    def has_key?(name)
+      case name
+      when :id, :_type
+        true
+      else
+        attributes.has_key?(name) || associations.has_key?(name) || referenced_associations.has_key?(name)
+      end
+    end
+
+    def new?
+      id.nil? || metadata.new?
+    end
+
+    def self.parse_hashes(root_subtree_hashes, referenced_subtree_hashes = {})
+      valid_reference_keys = referenced_subtree_hashes.keys.to_set
+
+      valid_reference_keys.each do |ref|
+        unless ref.is_a?(String)
+          raise ViewModel::DeserializationError::InvalidSyntax.new("Invalid reference string: #{ref}")
+        end
+      end
+
+      # Construct root UpdateData
+      root_updates = root_subtree_hashes.map do |subtree_hash|
+        metadata = ViewModel.extract_viewmodel_metadata(subtree_hash)
+        viewmodel_class = ViewModel::Registry.for_view_name(metadata.view_name)
+        verify_schema_version!(viewmodel_class, metadata.schema_version, metadata.id) if metadata.schema_version
+        UpdateData.new(viewmodel_class, metadata, subtree_hash, valid_reference_keys)
+      end
+
+      # Ensure that no root is referred to more than once
+      check_duplicate_updates(root_updates, type: "root")
+
+      # Construct reference UpdateData
+      referenced_updates = referenced_subtree_hashes.transform_values do |subtree_hash|
+        metadata = ViewModel.extract_viewmodel_metadata(subtree_hash)
+        viewmodel_class = ViewModel::Registry.for_view_name(metadata.view_name)
+        verify_schema_version!(viewmodel_class, metadata.schema_version, metadata.id) if metadata.schema_version
+
+        UpdateData.new(viewmodel_class, metadata, subtree_hash, valid_reference_keys)
+      end
+
+      check_duplicate_updates(referenced_updates.values, type: "reference")
+
+      return root_updates, referenced_updates
+    end
+
+    def self.check_duplicate_updates(updates, type:)
+      # Ensure that no root is referred to more than once
+      duplicates = updates.duplicates_by { |upd| upd.viewmodel_reference if upd.id }
+      if duplicates.present?
+        raise ViewModel::DeserializationError::DuplicateNodes.new(type, duplicates.keys)
+      end
+    end
+
+    def initialize(viewmodel_class, metadata, hash_data, valid_reference_keys)
+      self.viewmodel_class = viewmodel_class
+      self.metadata        = metadata
+      self.attributes      = {}
+      self.associations    = {}
+      self.referenced_associations = {}
+
+      parse(hash_data, valid_reference_keys)
+    end
+
+    def self.empty_update_for(viewmodel)
+      metadata = ViewModel::Metadata.new(viewmodel.id, viewmodel.view_name, viewmodel.class.schema_version, false)
+      self.new(viewmodel.class, metadata, {}, [])
+    end
+
+    # Produce a sequence of update datas for a given association update value, in the spirit of Array.wrap.
+    def to_sequence(name, value)
+      association_data = self.viewmodel_class._association_data(name)
+      case
+      when value.nil?
+        []
+      when association_data.shared?
+        []
+      when association_data.collection? # not shared, because of shared? check above
+        value.update_datas
+      else
+        [value]
+      end
+    end
+
+    # Updates in terms of viewmodel associations
+    def updated_associations
+      deps = {}
+
+      (associations.merge(referenced_associations)).each do |assoc_name, assoc_update|
+        deps[assoc_name] =
+          to_sequence(assoc_name, assoc_update)
+            .each_with_object({}) do |update_data, updated_associations|
+              updated_associations.deep_merge!(update_data.updated_associations)
+            end
+      end
+
+      deps
+    end
+
+    def build_preload_specs(association_data, updates)
+      if association_data.polymorphic?
+        updates.map do |update_data|
+          target_model = update_data.viewmodel_class.model_class
+          DeepPreloader::PolymorphicSpec.new(
+            target_model.name => update_data.preload_dependencies)
+        end
+      else
+        updates.map { |update_data| update_data.preload_dependencies }
+      end
+    end
+
+    def merge_preload_specs(association_data, specs)
+      empty = association_data.polymorphic? ? DeepPreloader::PolymorphicSpec.new : DeepPreloader::Spec.new
+      specs.inject(empty) { |acc, spec| acc.merge!(spec) }
+    end
+
+    # Updates in terms of activerecord associations: used for preloading subtree
+    # associations necessary to perform update.
+    def preload_dependencies
+      deps = {}
+
+      (associations.merge(referenced_associations)).each do |assoc_name, reference|
+        association_data = self.viewmodel_class._association_data(assoc_name)
+
+        preload_specs = build_preload_specs(association_data,
+                                            to_sequence(assoc_name, reference))
+
+        referenced_deps = merge_preload_specs(association_data, preload_specs)
+
+        if association_data.through?
+          referenced_deps = DeepPreloader::Spec.new(association_data.indirect_reflection.name.to_s => referenced_deps)
+        end
+
+        deps[association_data.direct_reflection.name.to_s] = referenced_deps
+      end
+
+      DeepPreloader::Spec.new(deps)
+    end
+
+    def viewmodel_reference
+      ViewModel::Reference.new(viewmodel_class, id)
+    end
+
+    def self.parse_associated(association_data, blame_reference, valid_reference_keys, child_hash)
+      child_metadata = ViewModel.extract_viewmodel_metadata(child_hash)
+
+      child_viewmodel_class =
+        association_data.viewmodel_class_for_name(child_metadata.view_name)
+
+      if child_viewmodel_class.nil?
+        raise ViewModel::DeserializationError::InvalidAssociationType.new(
+                association_data.association_name.to_s,
+                child_metadata.view_name,
+                blame_reference)
+      end
+
+      verify_schema_version!(child_viewmodel_class, child_metadata.schema_version, child_metadata.id) if child_metadata.schema_version
+
+      UpdateData.new(child_viewmodel_class, child_metadata, child_hash, valid_reference_keys)
+    end
+
+    private
+
+    def self.reference_only_hash?(hash)
+      hash.size == 2 && hash.has_key?(ViewModel::ID_ATTRIBUTE) && hash.has_key?(ViewModel::TYPE_ATTRIBUTE)
+    end
+
+    def parse(hash_data, valid_reference_keys)
+      hash_data = hash_data.dup
+
+      # handle view pre-parsing if defined
+      self.viewmodel_class.pre_parse(viewmodel_reference, metadata, hash_data) if self.viewmodel_class.respond_to?(:pre_parse)
+      hash_data.keys.each do |key|
+        if self.viewmodel_class.respond_to?(:"pre_parse_#{key}")
+          self.viewmodel_class.public_send("pre_parse_#{key}", viewmodel_reference, metadata, hash_data, hash_data.delete(key))
+        end
+      end
+
+      hash_data.each do |name, value|
+        member_data = self.viewmodel_class._members[name]
+        case member_data
+        when ViewModel::Record::AttributeData
+          attributes[name] = value
+
+        when AssociationData
+          association_data = member_data
+          case
+          when value.nil?
+            if association_data.collection?
+              raise ViewModel::DeserializationError::InvalidSyntax.new(
+                      "Invalid collection update value 'nil' for association '#{name}'",
+                      blame_reference)
+            end
+            if association_data.shared?
+              referenced_associations[name] = nil
+            else
+              associations[name] = nil
+            end
+
+          when association_data.through?
+            referenced_associations[name] =
+              ReferencedCollectionUpdate::Parser
+                .new(association_data, blame_reference, valid_reference_keys)
+                .parse(value)
+
+          when association_data.shared?
+            # Extract and check reference
+            ref = ViewModel.extract_reference_metadata(value)
+
+            unless valid_reference_keys.include?(ref)
+              raise ViewModel::DeserializationError::InvalidSharedReference.new(ref, blame_reference)
+            end
+
+            referenced_associations[name] = ref
+
+          else
+            if association_data.collection?
+              associations[name] =
+                OwnedCollectionUpdate::Parser
+                  .new(association_data, blame_reference, valid_reference_keys)
+                  .parse(value)
+            else # not a collection
+              associations[name] =
+                if value.nil?
+                  nil
+                else
+                  self.class.parse_associated(association_data, blame_reference, valid_reference_keys, value)
+                end
+            end
+          end
+        else
+          raise ViewModel::DeserializationError::UnknownAttribute.new(name, blame_reference)
+        end
+      end
+    end
+
+
+    def blame_reference
+      ViewModel::Reference.new(self.viewmodel_class, self.id)
+    end
+
+    def self.verify_schema_version!(viewmodel_class, schema_version, id)
+      unless viewmodel_class.accepts_schema_version?(schema_version)
+        raise ViewModel::DeserializationError::SchemaVersionMismatch.new(
+                viewmodel_class,
+                schema_version,
+                ViewModel::Reference.new(viewmodel_class, id))
+      end
+    end
+  end
+end