computed_model 0.1.0 → 0.3.0

data/lib/computed_model.rb

@@ -1,166 +1,66 @@
 # frozen_string_literal: true
 
 require "computed_model/version"
-require 'set'
-
+require "computed_model/plan"
+require "computed_model/dep_graph"
+require "computed_model/model"
+
+# ComputedModel is a universal batch loader which comes with a dependency-resolution algorithm.
+#
+# - Thanks to the dependency resolution, it allows you to the following trifecta at once, without breaking abstraction.
+#   - Process information gathered from datasources (such as ActiveRecord) and return the derived one.
+#   - Prevent N+1 problem via batch loading.
+#   - Load only necessary data.
+# - Can load data from multiple datasources.
+# - Designed to be universal and datasource-independent.
+#   For example, you can gather data from both HTTP and ActiveRecord and return the derived one.
+#
+# See {ComputedModel::Model} for basic usage.
 module ComputedModel
+  # An error raised when you tried to read from a loaded/computed attribute,
+  # but that attribute isn't loaded by the batch loader.
   class NotLoaded < StandardError; end
 
-  Plan = Struct.new(:load_order, :subdeps_hash)
-
-  module ClassMethods
-    # @param deps [Array]
-    def dependency(*deps)
-      @__computed_model_next_dependency ||= []
-      @__computed_model_next_dependency.push(*deps)
-    end
-
-    # @param meth_name [Symbol]
-    def computed(meth_name)
-      var_name = :"@#{meth_name}"
-      meth_name_orig = :"#{meth_name}_orig"
-      compute_meth_name = :"compute_#{meth_name}"
-
-      @__computed_model_dependencies[meth_name] = ComputedModel.normalize_dependencies(@__computed_model_next_dependency)
-      remove_instance_variable(:@__computed_model_next_dependency)
-
-      alias_method meth_name_orig, meth_name
-      define_method(meth_name) do
-        raise NotLoaded, "the field #{meth_name} is not loaded" unless instance_variable_defined?(var_name)
-        instance_variable_get(var_name)
-      end
-      define_method(compute_meth_name) do
-        instance_variable_set(var_name, send(meth_name_orig))
-      end
-      if public_method_defined?(meth_name_orig)
-        public meth_name
-      elsif protected_method_defined?(meth_name_orig)
-        protected meth_name
-      elsif private_method_defined?(meth_name_orig)
-        private meth_name
-      end
-
-      meth_name
-    end
-
-    # @param methods [Array<Symbol>]
-    # @param to [Symbol]
-    # @param allow_nil [nil, Boolean]
-    # @param prefix [nil, Symbol]
-    # @param include_subdeps [nil, Boolean]
-    # @return [void]
-    def delegate_dependency(*methods, to:, allow_nil: nil, prefix: nil, include_subdeps: nil)
-      method_prefix = prefix ? "#{prefix_}" : ""
-      methods.each do |meth_name|
-        pmeth_name = :"#{method_prefix}#{meth_name}"
-        if include_subdeps
-          dependency to=>meth_name
-        else
-          dependency to
-        end
-        if allow_nil
-          define_method(pmeth_name) do
-            send(to)&.public_send(meth_name)
-          end
-        else
-          define_method(pmeth_name) do
-            send(to).public_send(meth_name)
-          end
-        end
-        computed pmeth_name
-      end
-    end
-
-    # @param meth_name [Symbol]
-    # @yieldparam objects [Array]
-    # @yieldparam options [Hash]
-    # @yieldreturn [void]
-    def define_loader(meth_name, &block)
-      raise ArgumentError, "No block given" unless block
-
-      var_name = :"@#{meth_name}"
-
-      @__computed_model_loaders[meth_name] = block
-
-      define_method(meth_name) do
-        raise NotLoaded, "the field #{meth_name} is not loaded" unless instance_variable_defined?(var_name)
-        instance_variable_get(var_name)
-      end
-      attr_writer meth_name
-    end
-
-    # @param objs [Array]
-    # @param deps [Array]
-    def bulk_load_and_compute(objs, deps, **options)
-      plan = computing_plan(deps)
-      plan.load_order.each do |dep_name|
-        if @__computed_model_dependencies.key?(dep_name)
-          objs.each do |obj|
-            obj.send(:"compute_#{dep_name}")
-          end
-        elsif @__computed_model_loaders.key?(dep_name)
-          @__computed_model_loaders[dep_name].call(objs, plan.subdeps_hash[dep_name], **options)
-        else
-          raise "No dependency info for #{self}##{dep_name}"
-        end
-      end
-    end
-
-    # @param deps [Array]
-    # @return [Plan]
-    def computing_plan(deps)
-      normalized = ComputedModel.normalize_dependencies(deps)
-      load_order = []
-      subdeps_hash = {}
-      visiting = Set[]
-      visited = Set[]
-      normalized.each do |dep_name, dep_subdeps|
-        computing_plan_dfs(dep_name, dep_subdeps, load_order, subdeps_hash, visiting, visited)
-      end
-
-      Plan.new(load_order, subdeps_hash)
-    end
-
-    # @param meth_name [Symbol]
-    # @param meth_subdeps [Array]
-    # @param load_order [Array<Symbol>]
-    # @param subdeps_hash [Hash{Symbol=>Array}]
-    # @param visiting [Set<Symbol>]
-    # @param visited [Set<Symbol>]
-    private def computing_plan_dfs(meth_name, meth_subdeps, load_order, subdeps_hash, visiting, visited)
-      (subdeps_hash[meth_name] ||= []).push(*meth_subdeps)
-      return if visited.include?(meth_name)
-      raise "Cyclic dependency for #{self}##{meth_name}" if visiting.include?(meth_name)
-      visiting.add(meth_name)
-
-      if @__computed_model_dependencies.key?(meth_name)
-        @__computed_model_dependencies[meth_name].each do |dep_name, dep_subdeps|
-          computing_plan_dfs(dep_name, dep_subdeps, load_order, subdeps_hash, visiting, visited)
-        end
-      elsif @__computed_model_loaders.key?(meth_name)
-      else
-        raise "No dependency info for #{self}##{meth_name}"
-      end
-
-      load_order << meth_name
-      visiting.delete(meth_name)
-      visited.add(meth_name)
-    end
-  end
-
-  # @param deps [Array<Symbol, Hash>]
-  # @return [Hash{Symbol=>Array}]
+  # An error raised when you tried to read from a loaded/computed attribute,
+  # but that attribute isn't listed in the dependencies list.
+  class ForbiddenDependency < StandardError; end
+
+  # An error raised when the dependency graph contains a cycle.
+  class CyclicDependency < StandardError; end
+
+  # Normalizes dependency list as a hash.
+  #
+  # Normally you don't need to call it directly.
+  # {ComputedModel::Model::ClassMethods#dependency}, {ComputedModel::Model::ClassMethods#bulk_load_and_compute}, and
+  # {ComputedModel::NormalizableArray#normalized} will internally use this function.
+  #
+  # @param deps [Array<(Symbol, Hash)>, Hash, Symbol] dependency list
+  # @return [Hash{Symbol=>Array}] normalized dependency hash
+  # @raise [RuntimeError] if the dependency list contains values other than Symbol or Hash
+  # @example
+  #   ComputedModel.normalize_dependencies([:foo, :bar])
+  #   # => { foo: [true], bar: [true] }
+  #
+  # @example
+  #   ComputedModel.normalize_dependencies([:foo, bar: :baz])
+  #   # => { foo: [true], bar: [true, :baz] }
+  #
+  # @example
+  #   ComputedModel.normalize_dependencies(foo: -> (subfields) { true })
+  #   # => { foo: [#<Proc:...>] }
   def self.normalize_dependencies(deps)
     normalized = {}
-    deps.each do |elem|
+    deps = [deps] if deps.is_a?(Hash)
+    Array(deps).each do |elem|
       case elem
       when Symbol
-        normalized[elem] ||= []
+        normalized[elem] ||= [true]
       when Hash
         elem.each do |k, v|
           v = [v] if v.is_a?(Hash)
           normalized[k] ||= []
           normalized[k].push(*Array(v))
+          normalized[k].push(true) if v == []
         end
       else; raise "Invalid dependency: #{elem.inspect}"
       end
@@ -168,10 +68,35 @@ module ComputedModel
     normalized
   end
 
-  def self.included(klass)
-    super
-    klass.extend ClassMethods
-    klass.instance_variable_set(:@__computed_model_dependencies, {})
-    klass.instance_variable_set(:@__computed_model_loaders, {})
+  # Removes `nil`, `true` and `false` from the given array.
+  #
+  # Normally you don't need to call it directly.
+  # {ComputedModel::Model::ClassMethods#define_loader},
+  # {ComputedModel::Model::ClassMethods#define_primary_loader}, and
+  # {ComputedModel::NormalizableArray#normalized} will internally use this function.
+  #
+  # @param subfields [Array] subfield selector list
+  # @return [Array] the filtered one
+  # @example
+  #   ComputedModel.filter_subfields([false, {}, true, nil, { foo: :bar }])
+  #   # => [{}, { foo: :bar }]
+  def self.filter_subfields(subfields)
+    subfields.select { |x| x && x != true }
+  end
+
+  # Convenience class to easily access normalized version of dependencies.
+  #
+  # You don't need to directly use it.
+  #
+  # - {ComputedModel::Model#current_subfields} returns NormalizableArray.
+  # - Procs passed to {ComputedModel::Model::ClassMethods#dependency} will receive NormalizeArray.
+  class NormalizableArray < Array
+    # Returns the normalized hash of the dependencies.
+    # @return [Hash{Symbol=>Array}] the normalized hash of the dependencies
+    # @raise [RuntimeError] if the list isn't valid as a dependency list.
+    #   See {ComputedModel.normalize_dependencies} for details.
+    def normalized
+      @normalized ||= ComputedModel.normalize_dependencies(ComputedModel.filter_subfields(self))
+    end
   end
 end

data/lib/computed_model/dep_graph.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module ComputedModel
+  # A dependency graph representation used within ComputedModel::Model.
+  # Usually you don't need to use this class directly.
+  #
+  # @api private
+  #
+  # @example
+  #   graph = ComputedModel::DepGraph.new
+  #   graph << ComputedModel::DepGraph::Node.new(:computed, :foo, { bar: [] })
+  #   graph << ComputedModel::DepGraph::Node.new(:loaded, :bar, {})
+  #   plan = graph.tsort.plan([:foo])
+  class DepGraph
+    def initialize
+      @nodes = {}
+    end
+
+    # Returns the node with the specified name.
+    #
+    # @param name [Symbol] the name of the node
+    # @return [Node, nil]
+    #
+    # @example
+    #   graph = ComputedModel::DepGraph.new
+    #   graph[:foo]
+    def [](name)
+      @nodes[name]
+    end
+
+    # Adds the new node.
+    #
+    # @param node [Node]
+    # @return [void]
+    # @raise [ArgumentError] when the node already exists
+    #
+    # @example
+    #   graph = ComputedModel::DepGraph.new
+    #   graph << ComputedModel::DepGraph::Node.new(:computed, :foo, {})
+    def <<(node)
+      raise ArgumentError, "Field already declared: #{node.name}" if @nodes.key?(node.name)
+
+      @nodes[node.name] = node
+    end
+
+    # @return [Array<ComputedModel::DepGraph::Node>]
+    def nodes
+      @nodes.values
+    end
+
+    # Preprocess the graph by topological sorting. This is a necessary step for loader planning.
+    #
+    # @return [ComputedModel::DepGraph::Sorted]
+    #
+    # @example
+    #   graph = ComputedModel::DepGraph.new
+    #   graph << ComputedModel::DepGraph::Node.new(:computed, :foo, { bar: [] })
+    #   graph << ComputedModel::DepGraph::Node.new(:loaded, :bar, {})
+    #   sorted = graph.tsort
+    def tsort
+      load_order = []
+      visiting = Set[]
+      visited = Set[]
+
+      @nodes.each_value do |node|
+        next unless node.type == :primary
+
+        load_order << node.name
+        visiting.add node.name
+        visited.add node.name
+      end
+
+      raise ArgumentError, 'No primary loader defined' if load_order.empty?
+      raise "Multiple primary fields: #{load_order.inspect}" if load_order.size > 1
+
+      @nodes.each_value do |node|
+        tsort_dfs(node.name, load_order, visiting, visited)
+      end
+
+      nodes_in_order = load_order.reverse.map { |name| @nodes[name] }
+      ComputedModel::DepGraph::Sorted.new(self, nodes_in_order)
+    end
+
+    private def tsort_dfs(name, load_order, visiting, visited)
+      return if visited.include?(name)
+      raise ComputedModel::CyclicDependency, "Cyclic dependency for ##{name}" if visiting.include?(name)
+      raise "No dependency info for ##{name}" unless @nodes.key?(name)
+
+      visiting.add(name)
+
+      @nodes[name].edges.each_value do |edge|
+        tsort_dfs(edge.name, load_order, visiting, visited)
+      end
+
+      load_order << name
+      visiting.delete(name)
+      visited.add(name)
+    end
+
+    # @param graphs [Array<ComputedModel::DepGraph>]
+    # @return [ComputedModel::DepGraph]
+    def self.merge(graphs)
+      new_graph = ComputedModel::DepGraph.new
+      nodes_by_name = graphs.flat_map(&:nodes).group_by(&:name)
+      nodes_by_name.each do |name, nodes|
+        type = nodes.first.type
+        raise ArgumentError, "Field #{name} has multiple different types" unless nodes.all? { |node| node.type == type }
+
+        new_graph << ComputedModel::DepGraph::Node.new(type, name, nodes.map { |n| n.edges.transform_values { |e| e.spec } })
+      end
+      new_graph
+    end
+
+    # A node in the dependency graph. That is, a field in a computed model.
+    #
+    # @example computed node with plain dependencies
+    #   Node.new(:computed, :field1, { field2: [], field3: [] })
+    # @example computed node with subfield selectors
+    #   Node.new(:computed, :field1, { field2: [:foo, bar: []], field3: [] })
+    # @example loaded and primary dependencies
+    #   Node.new(:loaded, :field1, {})
+    #   Node.new(:primary, :field1, {})
+    class Node
+      # @return [Symbol] the type of the node. One of :computed, :loaded and :primary.
+      attr_reader :type
+      # @return [Symbol] the name of the node.
+      attr_reader :name
+      # @return [Hash{Symbol => Edge}] edges indexed by its name.
+      attr_reader :edges
+
+      ALLOWED_TYPES = %i[computed loaded primary].freeze
+      private_constant :ALLOWED_TYPES
+
+      # @param type [Symbol] the type of the node. One of :computed, :loaded and :primary.
+      # @param name [Symbol] the name of the node.
+      # @param edges [Array<(Symbol, Hash)>, Hash, Symbol] list of edges.
+      def initialize(type, name, edges)
+        raise ArgumentError, "invalid type: #{type.inspect}" unless ALLOWED_TYPES.include?(type)
+
+        edges = ComputedModel.normalize_dependencies(edges)
+        raise ArgumentError, "primary field cannot have dependency: #{name}" if type == :primary && edges.size > 0
+
+        @type = type
+        @name = name
+        @edges = edges.map { |k, v| [k, Edge.new(k, v)] }.to_h.freeze
+      end
+    end
+
+    # An edge in the dependency graph. That is, a dependency declaration in a computed model.
+    class Edge
+      # @return [Symbol] the name of the dependency (not the dependent)
+      attr_reader :name
+      # @return [Array] an auxiliary data called subfield selectors
+      attr_reader :spec
+
+      # @param name [Symbol] the name of the dependency (not the dependent)
+      # @param spec [Array] an auxiliary data called subfield selectors
+      def initialize(name, spec)
+        @name = name
+        @spec = Array(spec)
+      end
+
+      # @param subfields [Array] incoming list of subfield selectors
+      # @return [Array, nil]
+      def evaluate(subfields)
+        return @spec if @spec.all? { |specelem| !specelem.respond_to?(:call) }
+
+        evaluated = []
+        @spec.each do |specelem|
+          if specelem.respond_to?(:call)
+            ret = specelem.call(subfields)
+            if ret.is_a?(Array)
+              evaluated.push(*ret)
+            else
+              evaluated << ret
+            end
+          else
+            evaluated << specelem
+          end
+        end
+        evaluated
+      end
+    end
+
+    # A preprocessed graph with topologically sorted order.
+    #
+    # Generated by {ComputedModel::DepGraph#tsort}.
+    class Sorted
+      # @return [ComputedModel::DepGraph]
+      attr_reader :original
+      # @return [Array<ComputedModel::DepGraph::Node>]
+      attr_reader :nodes_in_order
+
+      # @param original [ComputedModel::DepGraph]
+      # @param nodes_in_order [Array<ComputedModel::DepGraph::Node>]
+      def initialize(original, nodes_in_order)
+        @original = original
+        @nodes_in_order = nodes_in_order
+      end
+
+      # Computes the plan for the given requirements.
+      #
+      # @param deps [Array] the list of required nodes. Each dependency can optionally include subfields hashes.
+      # @return [ComputedModel::Plan]
+      #
+      # @example Plain dependencies
+      #   sorted.plan([:field1, :field2])
+      #
+      # @example Dependencies with subfields
+      #   sorted.plan([:field1, field2: { optional_field: {} }])
+      def plan(deps)
+        normalized = ComputedModel.normalize_dependencies(deps)
+        subfields_hash = {}
+        uses = Set[]
+        plan_nodes = []
+
+        normalized.each do |name, subfields|
+          raise "No dependency info for ##{name}" unless @original[name]
+
+          uses.add(name)
+          (subfields_hash[name] ||= []).unshift(*subfields)
+        end
+        @nodes_in_order.each do |node|
+          uses.add(node.name) if node.type == :primary
+          next unless uses.include?(node.name)
+
+          node_subfields = ComputedModel::NormalizableArray.new(subfields_hash[node.name] || [])
+          deps = Set[]
+          node.edges.each_value do |edge|
+            specval = edge.evaluate(node_subfields)
+            if specval.any?
+              deps.add(edge.name)
+              uses.add(edge.name)
+              (subfields_hash[edge.name] ||= []).unshift(*specval)
+            end
+          end
+          plan_nodes.push(ComputedModel::Plan::Node.new(node.name, deps, node_subfields))
+        end
+        ComputedModel::Plan.new(plan_nodes.reverse, normalized.keys.to_set)
+      end
+    end
+  end
+end