data_graph 1.0.0

data/History

@@ -0,0 +1,3 @@
+== 1.0.0 2010/07/20
+
+Initial public release.

data/License.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2010 Pinnacol Assurance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software. Except as contained in this
+notice, the name(s) of the above copyright holders shall not be used in
+advertising or otherwise to promote the sale, use or other dealings in this
+Software without prior written authorization.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README

@@ -0,0 +1,48 @@
+= DataGraph
+
+Simplified eager loading for ActiveRecord
+
+== Description
+
+The default eager loading mechanism of ActiveRecord has numerous cases where
+these two are not equivalent as you might expect:
+
+  Model.find(:first, :include => :assoc).assoc
+  Model.find(:first).assoc
+
+As a result it gets tricky to make associations that work correctly via
+include. Oftentimes too much data gets returned. DataGraph makes eager loading
+easier by providing a way to declare and load a specific set of associated
+data.
+
+== Usage
+
+DataGraph uses a syntax based on the serialization methods.
+
+  require 'data_graph'
+  graph = Model.data_graph(
+    :only => [:a, :b, :c],
+    :include => {
+      :assoc => {
+        :only => [:x, :y]
+  }})
+  
+  data = graph.find(:first)
+  data.a                       # => 'A'
+  data.assoc.x                 # => 'X'
+  data.assoc.z                 # !> ActiveRecord::MissingAttributeError
+
+Any number of associations may be specified this way, and to any nesting
+depth. DataGraph always uses a 'one query per-association' strategy and never
+reverts to left outer joins the way include sometimes will.
+
+== Installation
+
+DataGraph is available as a gem on {Gemcutter}[http://gemcutter.org/gems/data_graph]
+
+  % gem install data_graph
+
+== Info 
+
+Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com]
+License:: {MIT-Style}[link:files/License_txt.html]

data/lib/data_graph.rb

@@ -0,0 +1,9 @@
+require 'data_graph/graph'
+
+module DataGraph
+  def data_graph(options={})
+    Graph.new(Node.new(self, options), options)
+  end
+end
+
+ActiveRecord::Base.extend(DataGraph)

data/lib/data_graph/cpk_linkage.rb

@@ -0,0 +1,21 @@
+require 'data_graph/linkage'
+
+module DataGraph
+  class CpkLinkage < Linkage
+    def parent_id(record)
+      parent_columns.collect {|attribute| record.send(attribute) }
+    end
+    
+    def child_id(record)
+      child_columns.collect {|attribute| record.send(attribute) }
+    end
+    
+    def conditions(id_map)
+      condition = child_columns.collect {|col| "#{table_name}.#{connection.quote_column_name(col)} = ?" }.join(' AND ')
+      conditions = Array.new(id_map.length, condition)
+      conditions_str = "(#{conditions.join(') OR (')})"
+      
+      id_map.keys.flatten.unshift(conditions_str)
+    end
+  end
+end

data/lib/data_graph/graph.rb

@@ -0,0 +1,92 @@
+require 'data_graph/node'
+
+module DataGraph
+  class Graph
+    include Utils
+    
+    attr_reader :model
+    attr_reader :aliases
+    attr_reader :paths
+    attr_reader :subsets
+    attr_reader :node
+    
+    def initialize(node, options={})
+      aliases = options[:aliases]
+      subsets = options[:subsets]
+      
+      @node = node
+      @nest_paths = node.nest_paths
+      @aliases = @node.aliases
+      @aliases.merge!(aliases) if aliases
+      
+      @paths = {}
+      @subsets = {}
+      
+      subsets = {
+        :default => '*',
+        :get => node.get_paths,
+        :set => node.set_paths
+      }.merge(subsets || {})
+      
+      subsets.each_pair do |name, unresolved_paths|
+        resolved_paths  = resolve(unresolved_paths)
+        @paths[name]    = resolved_paths
+        @subsets[name]  = node.only(resolved_paths)
+      end
+    end
+    
+    def find(*args)
+      node.find(*args)
+    end
+    
+    def paginate(*args)
+      node.paginate(*args)
+    end
+    
+    def only(paths)
+      node.only validate(:get, resolve(paths))
+    end
+    
+    def except(paths)
+      node.only validate(:get, resolve(paths))
+    end
+    
+    def resolve(paths)
+      paths = paths.collect {|path| aliases[path.to_s] || path }
+      paths.flatten!
+      paths.collect! {|path| path.to_s }
+      paths.uniq!
+      paths
+    end
+    
+    def path(type)
+      paths[type] or raise "no such path: #{type.inspect}"
+    end
+    
+    def subset(type, default_type = :default)
+      (subsets[type] || subsets[default_type]) or raise "no such subset: #{type.inspect}"
+    end
+    
+    def validate(type, paths)
+      inaccessible_paths = paths - path(type)
+      unless inaccessible_paths.empty?
+        raise InaccessiblePathError.new(inaccessible_paths)
+      end
+      paths
+    end
+    
+    def validate_attrs(type, attrs)
+      validate(type, patherize_attrs(attrs, @nest_paths))
+      attrs
+    end
+  end
+  
+  class InaccessiblePathError < RuntimeError
+    attr_reader :paths
+    
+    def initialize(paths)
+      @paths = paths
+      super "inaccesible: #{paths.inspect}"
+    end
+  end
+end

data/lib/data_graph/linkage.rb

@@ -0,0 +1,127 @@
+require 'data_graph/utils'
+
+module DataGraph
+  class Linkage
+    include Utils
+    
+    attr_reader :macro
+    attr_reader :name
+    attr_reader :through
+    attr_reader :table_name
+    attr_reader :connection
+    attr_reader :parent_columns
+    attr_reader :child_columns
+    attr_reader :child_node
+    
+    def initialize(assoc, options={})
+      @macro = assoc.macro
+      @name = assoc.name
+      @through = nil
+      
+      case macro
+      when :belongs_to
+        @parent_columns = foreign_key(assoc)
+        @child_columns  = reference_key(assoc)
+      when :has_many, :has_one
+        if through_assoc = assoc.through_reflection
+          @through = assoc.source_reflection.name
+          
+          assoc = through_assoc
+          options = {:only => [], :include => {@through => options}}
+        end
+        
+        @parent_columns = reference_key(assoc)
+        @child_columns  = foreign_key(assoc)
+      else
+        raise "currently unsupported association macro: #{macro}"
+      end
+      
+      klass = assoc.klass
+      @child_node = Node.new(assoc.klass, options)
+      @table_name = klass.table_name
+      @connection = klass.connection
+    end
+    
+    def node
+      through ? child_node[through] : child_node
+    end
+    
+    def parent_id(record)
+      record.send parent_columns.at(0)
+    end
+    
+    def child_id(record)
+      record.send child_columns.at(0)
+    end
+    
+    def conditions(id_map)
+      ["#{table_name}.#{connection.quote_column_name(child_columns.at(0))} IN (?)", id_map.keys.flatten]
+    end
+    
+    def link(parents)
+      id_map = Hash.new {|hash, key| hash[key] = [] }
+      
+      parents = arrayify(parents)
+      parents.each do |parent|
+        id_map[parent_id(parent)] << parent
+      end
+      
+      children = child_node.find(:all, 
+        :select => child_columns, 
+        :conditions => conditions(id_map))
+      visited = []
+      
+      arrayify(children).each do |child|
+        id_map[child_id(child)].each do |parent|
+          visited << parent
+          set_child(parent, child)
+        end
+      end
+      
+      if macro == :has_many && through
+        visited.each do |parent|
+          parent.send(name).uniq!
+        end
+      end
+      
+      (parents - visited).each do |parent|
+        set_child(parent, nil)
+      end
+      
+      children
+    end
+    
+    def inherit(method_name, paths)
+      dup.inherit!(method_name, paths)
+    end
+    
+    def inherit!(method_name, paths)
+      paths = paths.collect {|path| "#{through}.#{path}"} if through
+      @child_node = @child_node.send(method_name, paths)
+      self
+    end
+    
+    private
+    
+    def arrayify(obj) # :nodoc:
+      obj.kind_of?(Array) ? obj : [obj]
+    end
+    
+    def set_child(parent, child) # :nodoc:
+      if child && through
+        child = child.send(through).target
+      end
+      
+      case macro
+      when :belongs_to, :has_one
+        parent.send("set_#{name}_target", child)
+      when :has_many
+        association_proxy = parent.send(name)
+        association_proxy.loaded
+        association_proxy.target.push(child) if child
+      else
+        # should never get here...
+      end
+    end
+  end
+end

data/lib/data_graph/node.rb

@@ -0,0 +1,290 @@
+require 'data_graph/cpk_linkage'
+
+module DataGraph
+  
+  #-- Treated as immutable once created.
+  class Node
+    include Utils
+    
+    attr_reader :model
+    attr_reader :column_names
+    attr_reader :method_names
+    attr_reader :linkages
+    attr_reader :always_columns
+    
+    def initialize(model, options={})
+      @model = model
+      self.options = options
+    end
+    
+    def associations
+      linkages.keys
+    end
+    
+    def [](name)
+      linkage = linkages[name.to_s]
+      linkage ? linkage.node : nil
+    end
+    
+    def paths
+      paths = column_names + method_names
+      linkages.each_pair do |name, linkage|
+        linkage.node.paths.each do |path|
+          paths << "#{name}.#{path}"
+        end
+      end
+      
+      paths
+    end
+    
+    def get_paths
+      paths = primary_keys(model) + column_names + method_names
+      linkages.each_pair do |name, linkage|
+        paths << name
+        paths.concat linkage.parent_columns
+        (linkage.node.get_paths + linkage.child_columns).each do |path|
+          paths << "#{name}.#{path}"
+        end
+      end
+      
+      paths.uniq!
+      paths
+    end
+    
+    def set_paths
+      paths = primary_keys(model) + column_names + method_names
+      nested_attributes = model.nested_attributes_options
+      linkages.each_pair do |name, linkage|
+        next unless nested_attributes.has_key?(name.to_sym)
+        
+        attributes = linkage.node.set_paths
+        attributes += ActiveRecord::NestedAttributes::UNASSIGNABLE_KEYS
+        attributes.each do |path|
+          paths << "#{name}_attributes.#{path}"
+        end
+      end
+      
+      paths.uniq!
+      paths
+    end
+    
+    def aliases
+      aliases = {'*' => column_names.dup}
+      
+      linkages.each_pair do |name, linkage|
+        linkage.node.aliases.each_pair do |als, paths|
+          aliases["#{name}.#{als}"] = paths.collect {|path| "#{name}.#{path}" }
+        end
+      end
+      
+      aliases
+    end
+    
+    def nest_paths
+      paths = []
+      
+      linkages.each_pair do |name, linkage|
+        if linkage.macro == :has_many
+          paths << "#{name}_attributes"
+        end
+        
+        linkage.node.nest_paths.each do |path|
+          paths << "#{name}.#{path}"
+        end
+      end
+      
+      paths
+    end
+    
+    def options
+      associations = {}
+      linkages.each_pair do |name, linkage|
+        associations[name.to_sym] = linkage.node.options
+      end
+      
+      # note a new options hash must be generated because serialization is
+      # destructive to the hash (although not the values)
+      
+      {
+        :only    => column_names,
+        :methods => method_names,
+        :include => associations
+      }
+    end
+    
+    def options=(options)
+      unless options.kind_of?(Hash)
+        raise "not a hash: #{options.inspect}"
+      end
+      @column_names = parse_columns(options)
+      @method_names = parse_methods(options)
+      @linkages     = parse_linkages(options)
+      @always_columns = parse_always(options)
+    end
+    
+    def find(*args)
+      link model.find(*find_args(args))
+    end
+    
+    def paginate(*args)
+      link model.paginate(*find_args(args))
+    end
+    
+    def find_args(args=[])
+      args << {} unless args.last.kind_of?(Hash)
+      scope(args.last)
+      args
+    end
+    
+    def scope(options={})
+      columns = arrayify(options[:select]) + column_names + always_columns
+      linkages.each_value {|linkage| columns.concat linkage.parent_columns }
+      columns.uniq!
+      
+      options[:select] = columns.join(',')
+      options
+    end
+    
+    def link(records)
+      linkages.each_value do |linkage|
+        linkage.link(records)
+      end
+      
+      records
+    end
+    
+    def only!(paths)
+      attr_paths, nest_paths = partition(paths)
+      source, target = linkages, {}
+      
+      attr_paths.each do |name|
+        if linkage = source[name]
+          target[name] = linkage
+        end
+      end
+      
+      nest_paths.each_pair do |name, paths|
+        if linkage = source[name]
+          target[name] = linkage.inherit(:only, paths)
+        end
+      end
+      
+      @column_names &= attr_paths
+      @method_names &= attr_paths
+      @linkages = target
+      
+      self
+    end
+    
+    def only(paths)
+      dup.only!(paths)
+    end
+    
+    def except!(paths)
+      attr_paths, nest_paths = partition(paths)
+      source, target = linkages, {}
+      
+      (attr_paths - nest_paths.keys).each do |path|
+        source.delete(path)
+      end
+      
+      nest_paths.each_pair do |name, paths|
+        if linkage = source[name]
+          target[name] = linkage.inherit(:except, paths)
+        end
+      end
+      
+      @column_names -= attr_paths
+      @method_names -= attr_paths
+      @linkages = target
+      
+      self
+    end
+    
+    def except(paths)
+      dup.except!(paths)
+    end
+    
+    private
+    
+    def arrayify(array)
+      case array
+      when Array then array
+      when nil   then []
+      else [array]
+      end.collect! {|obj| obj.to_s }
+    end
+    
+    def parse_columns(options)
+      attributes = model.column_names
+
+      case
+      when options.has_key?(:except)
+        if options.has_key?(:only)
+          raise "only and except are both specified: #{options.inspect}"
+        end
+
+        except = options[:except]
+        attributes - arrayify(except)
+
+      when options.has_key?(:only)
+        only = options[:only]
+        arrayify(only) & attributes
+
+      else
+        attributes.dup
+      end
+    end
+
+    def parse_methods(options)
+      arrayify(options[:methods])
+    end
+    
+    def hashify(hash)
+      case hash
+      when Hash   # default
+        hash.symbolize_keys
+      when Array  # an array of identifiers {:include => [:a, :b]}
+        hash.inject({}) {|h, k| h[k.to_sym] = {}; h}
+      else        # a bare identifier {:include => :a}
+        {hash.to_sym => {}}
+      end
+    end
+    
+    def parse_linkages(options)
+      linkages = {}
+      
+      hashify(options[:include] || {}).each_pair do |name, options|
+        next unless assoc = model.reflect_on_association(name)
+        linkage = cpk?(assoc) ? CpkLinkage : Linkage
+        linkages[name.to_s] = linkage.new(assoc, options)
+      end
+      
+      linkages
+    end
+    
+    def parse_always(options)
+      always_columns = primary_keys(model).collect {|key| key.to_s }
+      always_columns.concat arrayify(options[:always])
+      always_columns.uniq!
+      always_columns
+    end
+    
+    def partition(paths)
+      attrs = []
+      nested_attrs = {}
+      
+      paths.each do |path|
+        head, tail = path.split('.', 2)
+        
+        if tail
+          (nested_attrs[head] ||= []) << tail
+        else
+          attrs << head
+        end
+      end
+      
+      [attrs, nested_attrs]
+    end
+  end
+end

data/lib/data_graph/utils.rb

@@ -0,0 +1,59 @@
+require 'active_record'
+ActiveRecord.load_all!
+
+require 'composite_primary_keys'
+
+module DataGraph
+  module Utils
+    module_function
+    
+    def primary_keys(model)
+      model.respond_to?(:primary_keys) ? model.primary_keys : [model.primary_key]
+    end
+    
+    def foreign_key(assoc)
+      # actually returns options[:foreign_key], or the default foreign key
+      foreign_key = assoc.primary_key_name
+
+      # cpk returns a csv string
+      foreign_key.to_s.split(',')
+    end
+
+    def reference_key(assoc)
+      primary_key = assoc.options[:primary_key] || primary_keys(assoc.macro == :belongs_to ? assoc.klass : assoc.active_record)
+      primary_key.kind_of?(Array) ? primary_key.collect {|key| key.to_s } : primary_key.to_s.split(',')
+    end
+    
+    def cpk?(assoc)
+      assoc = assoc.through_reflection if assoc.through_reflection
+      assoc.primary_key_name.to_s.include?(',')
+    end
+    
+    def patherize_attrs(attrs, nest_paths=[], paths=[], prefix='')
+      attrs.each_pair do |key, value|
+        case key
+        when String, Symbol
+          path = "#{prefix}#{key}"
+          
+          if nest_paths.include?(path)
+            value = value.values
+          end
+          
+          case value
+          when Hash
+            patherize_attrs(value, nest_paths, paths, "#{path}.")
+          when Array
+            next_prefix = "#{path}."
+            value.each {|hash| patherize_attrs(hash, nest_paths, paths, next_prefix) }
+          else
+            paths << path
+          end
+        else
+          raise "unexpected attribute key: #{key.inspect}"
+        end
+      end
+      
+      paths
+    end
+  end
+end

data/lib/data_graph/version.rb

@@ -0,0 +1,7 @@
+module DataGraph
+  MAJOR = 1
+  MINOR = 0
+  TINY = 0
+
+  VERSION="#{MAJOR}.#{MINOR}.#{TINY}"
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification 
+name: data_graph
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Simon Chiang
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-20 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 3
+        - 5
+        version: 2.3.5
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: composite_primary_keys
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 3
+        - 5
+        - 1
+        version: 2.3.5.1
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: sqlite3-ruby
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 2
+        - 5
+        version: 1.2.5
+  type: :development
+  version_requirements: *id003
+description: 
+email: simon.a.chiang@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History
+- README
+- License.txt
+files: 
+- lib/data_graph.rb
+- lib/data_graph/cpk_linkage.rb
+- lib/data_graph/graph.rb
+- lib/data_graph/linkage.rb
+- lib/data_graph/node.rb
+- lib/data_graph/utils.rb
+- lib/data_graph/version.rb
+- History
+- README
+- License.txt
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+- -S
+- -N
+- --title
+- Data Graph
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: ""
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: ""
+test_files: []
+