iknow_view_models 2.8.4

data/lib/view_model/active_record/visitor.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class ViewModel::ActiveRecord::Visitor
+  attr_reader :visit_shared, :for_edit
+
+  def initialize(visit_shared: true, for_edit: false)
+    @visit_shared = visit_shared
+    @for_edit     = for_edit
+  end
+
+  def visit(view, context: nil)
+    return unless pre_visit(view, context: context)
+
+    run_callback(ViewModel::Callbacks::Hook::BeforeVisit, view, context: context)
+    run_callback(ViewModel::Callbacks::Hook::BeforeDeserialize, view, context: context) if for_edit
+
+    class_name = view.class.name.underscore.gsub('/', '__')
+    visit      = :"visit_#{class_name}"
+    end_visit  = :"end_visit_#{class_name}"
+
+    visit_children =
+      if respond_to?(visit, true)
+        self.send(visit, view, context: context)
+      else
+        true
+      end
+
+    if visit_children
+      # visit the underlying viewmodel for each association, ignoring any
+      # customization
+      view.class._members.each do |name, member_data|
+        next unless member_data.is_a?(ViewModel::ActiveRecord::AssociationData)
+        next if member_data.shared? && !visit_shared
+        children = Array.wrap(view._read_association(name))
+        children.each do |child|
+          if context
+            child_context = view.context_for_child(name, context: context)
+          end
+          self.visit(child, context: child_context)
+        end
+      end
+    end
+
+    self.send(end_visit, view, context: context) if respond_to?(end_visit, true)
+
+    if for_edit
+      view_changes = changes(view)
+      run_callback(ViewModel::Callbacks::Hook::OnChange, view, context: context, changes: view_changes) if view_changes.changed?
+      run_callback(ViewModel::Callbacks::Hook::AfterDeserialize, view, context: context, changes: view_changes)
+    end
+
+    run_callback(ViewModel::Callbacks::Hook::AfterVisit, view, context: context)
+
+    post_visit(view, context: context)
+  end
+
+  # Invoked for all view types before visit, may cancel visit by returning
+  # false.
+  def pre_visit(_view, context: nil)
+    true
+  end
+
+  # Invoked for all view types after visit.
+  def post_visit(_view, context: nil); end
+
+  # If a context is provided, run the specified callback hook on it
+  def run_callback(hook, view, context:, **args)
+    context.run_callback(hook, view, **args) if context
+  end
+
+  # This method may be overridden by subclasses to specify the changes to be
+  # provided to callback hooks for each view. By default returns an empty
+  # Changes.
+  def changes(_view)
+    ViewModel::Changes.new
+  end
+end

data/lib/view_model/after_transaction_runner.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Module implementing the behaviour of a AR post-transaction hook. After calling
+# `add_to_transaction`, the abstract method `after_transaction` will be invoked
+# by AR's callbacks.
+module ViewModel::AfterTransactionRunner
+  def committed!; end
+
+  def before_committed!
+    after_transaction
+  end
+
+  def rolledback!(*)
+    after_transaction
+  end
+
+  def add_to_transaction
+    if connection.transaction_open?
+      connection.add_transaction_record(self)
+    else
+      after_transaction
+    end
+  end
+
+  # Override to tie to a specific connection.
+  def connection
+    ActiveRecord::Base.connection
+  end
+end

data/lib/view_model/callbacks.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require 'renum'
+require 'safe_values'
+
+# Callback hooks for viewmodel traversal contexts
+module ViewModel::Callbacks
+  extend ActiveSupport::Concern
+
+  # Callbacks are run in the instance context of an Env class that wraps the
+  # callbacks instance with additional instance method access to the view,
+  # context and extra context-dependent parameters.
+  module CallbackEnvContext
+    def method_missing(method, *args, &block)
+      if _callbacks.respond_to?(method, true)
+        _callbacks.send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_all = false)
+      _callbacks.respond_to?(method, false) || super
+    end
+  end
+
+  # Define the possible callback hooks and their required parameters.
+  enum :Hook do
+    BeforeVisit(:context)
+    AfterVisit(:context)
+
+    # The before deserialize hook is called when the viewmodel is visited during
+    # deserialization. At this point we don't know whether deserialization will
+    # be making any changes.
+    BeforeDeserialize(:deserialize_context)
+
+    # The BeforeValidate hook is called during deserialization immediately
+    # before validating the viewmodel. For AR viewmodels, this is after
+    # deserializing attributes and points-to associations, but before saving and
+    # deserializing points-from associations. Callbacks on this hook may make
+    # changes to the model, but must call the viewmodel's `*_changed!` methods
+    # for any changes to viewmodel attributes/associations.
+    BeforeValidate(:deserialize_context)
+
+    # The on change hook is called when deserialization has visited the model
+    # and made changes. Keyword argument `changes` is a ViewModel::Changes
+    # describing the effects. Callbacks on this hook may not themselves make any
+    # changes to the model. ViewModels backed by a transactional model such as
+    # AR will have been saved once, allowing the hook to inspect changed model
+    # values on `previous_changes`.
+    OnChange(:deserialize_context, :changes)
+
+    # The after-deserialize hook is called when leaving the viewmodel during
+    # deserialization. The recorded ViewModel::Changes instance (which may have
+    # no changes) is passed to the hook.
+    AfterDeserialize(:deserialize_context, :changes)
+
+    attr_reader :context_name, :required_params, :env_class
+
+    def init(context_name, *other_params)
+      @context_name    = context_name
+      @required_params = other_params
+      @env_class = Value.new(:_callbacks, :view, context_name, *other_params) do
+        include CallbackEnvContext
+        delegate :model, to: :view
+
+        unless context_name == :context
+          alias_method :context, context_name
+        end
+
+        # If we have any other params, generate a combined positional/keyword
+        # constructor wrapper
+        if other_params.present?
+          params = other_params.map { |x| "#{x}:" }.join(', ')
+          args   = other_params.join(', ')
+          instance_eval(<<-SRC, __FILE__, __LINE__ + 1)
+            def create(callbacks, view, context, #{params})
+              self.new(callbacks, view, context, #{args})
+            end
+          SRC
+        else
+          def self.create(callbacks, view, context)
+            self.new(callbacks, view, context)
+          end
+        end
+      end
+    end
+
+    def dsl_add_hook_name
+      name.underscore
+    end
+
+    def dsl_viewmodel_callback_method
+      name.underscore.to_sym
+    end
+  end
+
+  # Placeholder for callbacks to invoked for all view types
+  ALWAYS = '__always'
+
+  # Callbacks classes may be inherited, including their callbacks and
+  # env method delegations.
+  included do
+    base_callbacks = {}
+    define_singleton_method(:class_callbacks) { base_callbacks }
+    define_singleton_method(:all_callbacks) do |&block|
+      return to_enum(__method__) unless block
+      block.call(base_callbacks)
+    end
+  end
+
+  class_methods do
+    def inherited(subclass)
+      subclass_callbacks = {}
+      subclass.define_singleton_method(:class_callbacks) { subclass_callbacks }
+      subclass.define_singleton_method(:all_callbacks) do |&block|
+        return to_enum(__method__) unless block
+        super(&block)
+        block.call(subclass_callbacks)
+      end
+    end
+
+    # Add dsl methods to declare hooks in subclasses
+    Hook.each do |hook|
+      define_method(hook.dsl_add_hook_name) do |view_name = ALWAYS, &block|
+        add_callback(hook, view_name, &block)
+      end
+    end
+
+    def each_callback(hook, view_name)
+      valid_hook!(hook)
+      return to_enum(__method__, hook, view_name) unless block_given?
+
+      all_callbacks do |callbacks|
+        if (hook_callbacks = callbacks[hook])
+          hook_callbacks[view_name.to_s]&.each { |c| yield(c) }
+          hook_callbacks[ALWAYS]&.each { |c| yield(c) }
+        end
+      end
+    end
+
+    def updates_view?
+      false
+    end
+
+    private
+
+    def updates_view!
+      define_singleton_method(:updates_view?) { true }
+    end
+
+    def add_callback(hook, view_name, &block)
+      valid_hook!(hook)
+
+      hook_callbacks = (class_callbacks[hook] ||= {})
+      view_callbacks = (hook_callbacks[view_name.to_s] ||= [])
+      view_callbacks << block
+    end
+
+    def valid_hook!(hook)
+      unless hook.is_a?(Hook)
+        raise ArgumentError.new("Invalid hook: '#{hook}'")
+      end
+    end
+  end
+
+  def run_callback(hook, view, context, **args)
+    return if ineligible(view)
+
+    callback_env = hook.env_class.create(self, view, context, **args)
+
+    view_name = view.class.view_name
+    self.class.each_callback(hook, view_name) do |callback|
+      callback_env.instance_exec(&callback)
+    end
+  end
+
+  def ineligible(view)
+    # ARVM synthetic views are considered part of their association and as such
+    # are not visited by callbacks. Eligibility exclusion is intended to be
+    # library-internal: subclasses should not attempt to extend this.
+    view.is_a?(ViewModel::ActiveRecord) && view.class.synthetic
+  end
+
+  def self.wrap_serialize(viewmodel, context:)
+    context.run_callback(ViewModel::Callbacks::Hook::BeforeVisit, viewmodel)
+    val = yield
+    context.run_callback(ViewModel::Callbacks::Hook::AfterVisit, viewmodel)
+    val
+  end
+
+  # Record changes made in the deserialization block so that they can be
+  # provided to the AfterDeserialize hook.
+  DeserializeHookControl = Struct.new(:changes) do
+    alias_method :record_changes, :changes=
+  end
+
+  def self.wrap_deserialize(viewmodel, deserialize_context:)
+    hook_control = DeserializeHookControl.new
+
+    wrap_serialize(viewmodel, context: deserialize_context) do
+      deserialize_context.run_callback(ViewModel::Callbacks::Hook::BeforeDeserialize,
+                                       viewmodel)
+
+      val = yield(hook_control)
+
+      if hook_control.changes.nil?
+        raise ViewModel::DeserializationError::Internal.new(
+                'Internal error: changes not recorded for deserialization of viewmodel',
+                viewmodel.blame_reference)
+      end
+
+      deserialize_context.run_callback(ViewModel::Callbacks::Hook::AfterDeserialize,
+                                       viewmodel,
+                                       changes: hook_control.changes)
+      val
+    end
+  end
+end

data/lib/view_model/changes.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'view_model/utils/collections'
+
+class ViewModel::Changes
+  using ViewModel::Utils::Collections
+
+  attr_reader :new, :changed_attributes, :changed_associations, :changed_children, :deleted
+
+  alias new? new
+  alias deleted? deleted
+  alias changed_children? changed_children
+
+  def initialize(new: false, changed_attributes: [], changed_associations: [], changed_children: false, deleted: false)
+    @new                  = new
+    @changed_attributes   = changed_attributes.map(&:to_s)
+    @changed_associations = changed_associations.map(&:to_s)
+    @changed_children     = changed_children
+    @deleted              = deleted
+  end
+
+  def contained_to?(associations: [], attributes: [])
+    !deleted? &&
+      changed_associations.all? { |assoc| associations.include?(assoc.to_s) } &&
+      changed_attributes.all? { |attr| attributes.include?(attr.to_s) }
+  end
+
+  def changed_any?(associations: [], attributes: [])
+    associations.any? { |assoc| changed_associations.include?(assoc.to_s) } ||
+      attributes.any? { |attr| changed_attributes.include?(attr.to_s) }
+  end
+
+  def changed?
+    new? || deleted? || changed_attributes.present? || changed_associations.present?
+  end
+
+  def changed_tree?
+    changed? || changed_children?
+  end
+
+  def to_h
+    {
+      'changed_attributes'   => changed_attributes.dup,
+      'changed_associations' => changed_associations.dup,
+      'new'                  => new?,
+      'changed_children'     => changed_children?,
+      'deleted'              => deleted?,
+    }
+  end
+
+  def ==(other)
+    return false unless other.is_a?(ViewModel::Changes)
+
+    self.new? == other.new? &&
+      self.changed_children? == other.changed_children? &&
+      self.deleted? == other.deleted? &&
+      self.changed_attributes.contains_exactly?(other.changed_attributes) &&
+      self.changed_associations.contains_exactly?(other.changed_associations)
+  end
+
+  alias eql? ==
+end

data/lib/view_model/config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'safe_values'
+require 'keyword_builder'
+
+ViewModel::Config = Value.new(
+  show_cause_in_error_view: false,
+  debug_deserialization: false,
+)
+
+class ViewModel::Config
+  def self.configure!(&block)
+    if instance_variable_defined?(:@instance)
+      raise ArgumentError.new('ViewModel library already configured')
+    end
+
+    builder = KeywordBuilder.create(self, constructor: :with)
+    @instance = builder.build!(&block)
+  end
+
+  def self._option(opt)
+    configure! unless instance_variable_defined?(:@instance)
+    @instance[opt]
+  end
+
+  self.members.each do |opt|
+    define_singleton_method(opt) { _option(opt) }
+  end
+end

data/lib/view_model/controller.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "view_model"
+
+module ViewModel::Controller
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from ViewModel::AbstractError, with: ->(ex) do
+      render_error(ex.view, ex.status)
+    end
+  end
+
+  def render_viewmodel(viewmodel, status: nil, serialize_context: viewmodel.class.try(:new_serialize_context), &block)
+    prerender = prerender_viewmodel(viewmodel, serialize_context: serialize_context, &block)
+    render_json_string(prerender, status: status)
+  end
+
+  # Render viewmodel(s) to a JSON API response as a String
+  def prerender_viewmodel(viewmodel, status: nil, serialize_context: viewmodel.class.try(:new_serialize_context))
+    Jbuilder.encode do |json|
+      json.data do
+        ViewModel.serialize(viewmodel, json, serialize_context: serialize_context)
+      end
+
+      if serialize_context && serialize_context.has_references?
+        json.references do
+          serialize_context.serialize_references(json)
+        end
+      end
+
+      yield(json) if block_given?
+    end
+  end
+
+  # Render an arbitrarily nested tree of hashes and arrays with pre-rendered
+  # JSON string terminals. Useful for rendering cached views without parsing
+  # then re-serializing the cached JSON.
+  def render_json_view(json_view, json_references: {}, status: nil, &block)
+    prerender = prerender_json_view(json_view, json_references: json_references, &block)
+    render_json_string(prerender, status: status)
+  end
+
+  def prerender_json_view(json_view, json_references: {})
+    json_view = wrap_json_view(json_view)
+    json_references = wrap_json_view(json_references)
+
+    Jbuilder.encode do |json|
+      json.data json_view
+      if json_references.present?
+        json.references do
+          json_references.sort.each do |key, value|
+            json.set!(key, value)
+          end
+        end
+      end
+      yield(json) if block_given?
+    end
+  end
+
+  def render_error(error_view, status = 500)
+    unless error_view.is_a?(ViewModel)
+      raise "Expected ViewModel error view, received #{error_view.inspect}"
+    end
+
+    render_jbuilder(status: status) do |json|
+      json.error do
+        ctx = error_view.class.new_serialize_context(access_control: ViewModel::AccessControl::Open.new)
+        ViewModel.serialize(error_view, json, serialize_context: ctx)
+      end
+    end
+  end
+
+  protected
+
+  def parse_viewmodel_updates
+    update_hash = _extract_update_data(params.fetch(:data))
+    refs        = _extract_param_hash(params.fetch(:references, {}))
+
+    return update_hash, refs
+  end
+
+  private
+
+  def _extract_update_data(data)
+    if data.is_a?(Array)
+      if data.blank?
+        raise ViewModel::Error.new(status: 400, detail: "No data submitted: #{data.inspect}")
+      end
+      data.map { |el| _extract_param_hash(el) }
+    else
+      _extract_param_hash(data)
+    end
+  end
+
+  def _extract_param_hash(data)
+    case data
+    when Hash
+      data
+    when ActionController::Parameters
+      data.to_unsafe_h
+    else
+      raise ViewModel::Error.new(status: 400, detail: "Invalid data submitted, expected hash: #{data.inspect}")
+    end
+  end
+
+  def render_jbuilder(status:)
+    response = Jbuilder.encode do |json|
+      yield json
+    end
+
+    render_json_string(response, status: status)
+  end
+
+  def render_json_string(response, status: nil)
+    render(json: response, status: status)
+  end
+
+  # Wrap raw JSON in such a way that MultiJSON knows to pass it through
+  # untouched. Requires a MultiJson adapter other than ActiveSupport's
+  # (modified) JsonGem.
+  class CompiledJson
+    def initialize(s);  @s = s; end
+    def to_json(*args); @s;     end
+    def to_s;           @s;     end
+    undef_method :as_json
+  end
+
+  # Traverse a tree and wrap all String terminals in CompiledJson
+  def wrap_json_view(view)
+    case view
+    when Array
+      view.map { |v| wrap_json_view(v) }
+    when Hash
+      view.transform_values { |v| wrap_json_view(v) }
+    when String, Symbol
+      CompiledJson.new(view)
+    else
+      view
+    end
+  end
+end