correlate 0.1.0

data/lib/correlate/links.rb

@@ -0,0 +1,89 @@
+module Correlate
+  # Thin proxy around the array of links.
+  class Links
+
+    instance_methods.each { |m| undef_method m unless m =~ /(^__|^send$|^object_id$)/ }
+
+    def initialize( klass, array = [] )
+      @klass = klass
+      @target_array = array
+    end
+
+    # Extract all the matching links for rel.
+    #
+    # @param [String] rel
+    # @return [ Correlate::Links ] for matching links
+    def rel( rel )
+      clone( @target_array.select { |link| link['rel'] == rel } )
+    end
+
+    # Add an object to the list
+    def <<( obj )
+      write_target.push({ 'rel' => rel_for_object( obj ), 'href' => id_for_object( obj ) })
+    end
+
+    alias :push :<<
+    alias :concat :<<
+
+    # Replace a matching +rel+ with this object
+    def replace( obj )
+      delete( obj )
+
+      self.<< obj
+    end
+
+    # Delete this object from the list
+    def delete( obj )
+      rel = rel_for_object( obj )
+
+      write_target.reject! { |l| l['rel'] == rel }
+    end
+
+    def __debug__
+      {
+        :object_id => object_id,
+        :klass => @klass,
+        :target_array => @target_array,
+        :original_copy => @original_copy,
+        :original_copy_object_id => @original_copy.object_id
+      }
+    end
+
+    protected
+
+    def clone( array )
+      Links.new( @klass, array ).subset_of( @original_copy || self )
+    end
+
+    def subset_of( links_instance )
+      @original_copy = links_instance
+    end
+
+    def rel_for_object( obj )
+      c = @klass.correlation_for( obj )
+
+      if c.nil? && obj.instance_of?( Hash )
+        obj['rel']
+      else
+        c.rel
+      end
+    end
+
+    def id_for_object( obj )
+      c = @klass.correlation_for( obj )
+      if c.nil? && obj.instance_of?( Hash )
+        obj['href']
+      else
+        obj.send( c.id_method )
+      end
+    end
+
+    def write_target
+      @original_copy || @target_array
+    end
+
+    def method_missing( name, *args, &block )
+      @target_array.send( name, *args, &block )
+    end
+  end
+end

data/lib/correlate/relationships.rb

@@ -0,0 +1,36 @@
+module Correlate
+  module Relationships
+
+    autoload :CouchRest, 'correlate/relationships/couchrest'
+    autoload :ActiveRecord, 'correlate/relationships/active_record'
+
+    class << self
+
+      def configure!( klass, &block )
+        if klass.ancestors.include?( ::CouchRest::ExtendedDocument )
+          Correlate::Relationships::CouchRest.configure! klass, &block
+        else
+          if defined?( ::ActiveRecord ) && klass.ancestors.include?( ::ActiveRecord::Base )
+            Correlate::Relationships::ActiveRecord.configure! klass, &block
+          end
+        end
+      end
+
+      def build_correlation( name, type, opts )
+        correlation = Correlation.new
+        correlation.name = name
+        correlation.type = type
+        correlation.target = opts[:class]
+        correlation.source = opts[:source]
+        correlation.rel = opts[:rel]
+        correlation.id_method = opts[:id_method]
+        correlation.requires = opts[:requires]
+        correlation.required = opts[:required]
+
+        correlation
+      end
+
+    end
+
+  end
+end

data/lib/correlate/relationships/active_record.rb

@@ -0,0 +1,146 @@
+module Correlate
+  module Relationships
+
+    # Used to define relationships between ActiveRecord::Base models and
+    # CouchRest::ExtendedDocument classes.
+    #
+    # == Important note
+    #
+    # Unlike normal correlations, when correlating an ActiveRecord model with
+    # a CouchRest document, the 'reverse correlation' needs to be specified in
+    # in the CouchRest model.
+    #
+    # @see #a
+    # @see #some
+    class ActiveRecord
+
+      autoload :CollectionProxy, 'correlate/relationships/active_record/collection_proxy'
+
+      class << self
+
+        def configure!( klass, &block )
+
+          # Setup our conveniences
+          relationships = new( klass )
+          relationships.instance_eval( &block )
+        end
+
+      end
+
+      def initialize( klass )
+        @klass = klass
+      end
+
+      # Specify that this model will have multiple documents of said relationship.
+      # This is akin to ActiveRecord's +has_many associations+
+      #
+      # @example Defining correlations and using them
+      #   class MyModel < ActiveRecord::Base
+      #     include Correlate
+      #
+      #     related_to do
+      #       some :other_documents, :class => 'OtherDocument', :rel => 'my_model'
+      #     end
+      #   end
+      #
+      #   class OtherDocument < CouchRest::ExtendedDocument
+      #     include Correlate
+      #
+      #     related_to do
+      #       a :my_model, :class => 'MyModel'
+      #     end
+      #   end
+      #
+      #   doc = OtherDocument.new
+      #   doc.my_model # => nil
+      #
+      #   me = MyModel.find( 1 )
+      #   doc.my_model = me
+      #
+      #   doc.me_model # => <MyModel#12121212>
+      #
+      #   me.other_documents # => [ <OtherDocument#121212121> ]
+      #
+      # @param [Symbol] name of the relationship
+      # @param [Hash] options for the relationship
+      # @option options [String] :class the class of the related document/model
+      # @option options [String] :rel the value of the +rel+ key in the related hash
+      # @option options [Symbol] :id_method (:id) name of a method use to retrieve the 'foreign key' value from documents added to the relationship
+      # @option options [Symbol] :load_via (:get) name of the class method used to retreive related documents
+      def some( *args )
+        name = args.shift
+        opts = args.empty? ? {} : args.last
+        opts[:source] = @klass
+
+        correlation = Correlate::Relationships.build_correlation( name, :some, opts )
+        @klass.correlations << correlation
+
+        @klass.class_eval <<-EOF, __FILE__, __LINE__
+          def #{name}( raw = false )
+            local_correlation = self.class.correlations.detect { |c| c.name == :#{name} }
+
+            Correlate::Relationships::ActiveRecord::CollectionProxy.new self, local_correlation
+          end
+        EOF
+      end
+
+      # Specify that this model will have a single document of said relationship.
+      # This is akin to ActiveRecord's +belongs_to or has_one associations+.
+      #
+      # @example Defining correlations and using them
+      #   class MyModel < ActiveRecord::Base
+      #     include Correlate
+      #
+      #     related_to do
+      #       a :journal, :class => 'Journal', :rel => 'my_model'
+      #     end
+      #   end
+      #
+      #   class Journal < CouchRest::ExtendedDocument
+      #     include Correlate
+      #
+      #     related_to do
+      #       some :my_models, :class => 'MyModel', :rel => 'my_model'
+      #     end
+      #   end
+      #
+      #   doc = Journal.new
+      #   doc.my_models # => []
+      #
+      #   me = MyModel.find( 1 )
+      #   doc.my_models << me
+      #
+      #   doc.my_models # => [ <MyModel#12121212> ]
+      #
+      #   me.journal # => <Journal#121212121>
+      #
+      # @param [Symbol] name of the relationship
+      # @param [Hash] options for the relationship
+      # @option options [String] :class the class of the related document/model
+      # @option options [String] :rel (name) the value of the +rel+ key in the related hash
+      # @option options [Symbol] :id_method (:id) name of a method use to retrieve the 'foreign key' value from documents added to the relationship
+      # @option options [Symbol] :load_via (:get) name of the class method used to retreive related documents
+      def a( name, options = {} )
+        options[:source] = @klass
+
+        @klass.correlations << Correlate::Relationships.build_correlation( name, :a, options )
+
+        @klass.class_eval <<-EOF, __FILE__, __LINE__
+          def #{name}=( object )
+            self.links.replace( object )
+          end
+
+          def #{name}( raw = false )
+            correlation = self.links.rel( '#{name}' ).first
+            return if correlation.nil?
+
+            correlation = self.class.correlation_for( correlation ).correlate( correlation ) unless raw
+
+            correlation
+          end
+        EOF
+      end
+
+    end
+  end
+end

data/lib/correlate/relationships/active_record/collection_proxy.rb

@@ -0,0 +1,32 @@
+module Correlate
+  module Relationships
+    class ActiveRecord
+      class CollectionProxy
+
+        instance_methods.each { |m| undef_method m unless m =~ /(^__|^send$|^object_id$)/ }
+
+        def initialize( source, correlation )
+          @source = source
+          @correlation = correlation
+          @collection = correlation.correlate( source )
+        end
+
+        def <<( object )
+          correlation = @correlation.opposite
+
+          object.send( "#{correlation.name}=", @source )
+          object.save
+        end
+
+        alias :push :<<
+        alias :concat :<<
+
+        protected
+
+        def method_missing( name, *args, &block )
+          @collection.send( name, *args, &block )
+        end
+      end
+    end
+  end
+end

data/lib/correlate/relationships/couchrest.rb

@@ -0,0 +1,171 @@
+module Correlate
+  module Relationships
+
+    # Configure relationships between CouchRest::ExtendedDocument classes, as
+    # well as between CouchRest::ExtendedDocument & ActiveRecord::Base classes.
+    #
+    # Using this correlation in a CouchRest::ExtendedDocument creates a +links+
+    # property that is used for storing the correlations between this document
+    # and others.
+    #
+    # It also creates a +rel+ view for the class that emits two keys: +rel+ &
+    # +href+, which is used for bulk lookups and loading of documents.
+    #
+    # == Notes
+    #
+    # To use the validations provided by Correlate you need to include
+    # +CouchRest::Validation+ into your classes.
+    #
+    # @see #a
+    # @see #some
+    class CouchRest
+
+      class << self
+
+        def configure!( klass, &block )
+
+          # Add our property
+          klass.property :links, :type => 'Correlate::Links', :default => Correlate::Links.new( klass )
+
+          # Setup our conveniences
+          relationships = new( klass )
+          relationships.instance_eval( &block )
+          relationships.build_validators
+          relationships.build_views
+
+          # Make sure our links array is properly casted
+          klass.class_eval <<-EOF, __FILE__, __LINE__
+            def links=( array )
+              self[:links] = Correlate::Links.new( self.class, array )
+            end
+          EOF
+        end
+
+      end
+
+      def initialize( klass )
+        @klass = klass
+      end
+
+      # Specify that this document will have multiple documents of said relationship.
+      #
+      # @example Defining correlations and using them
+      #   class SomeDocument < CouchRest::ExtendedDocument
+      #     include Correlate
+      #
+      #     related_to do
+      #       some :other_documents, :class => 'OtherDocument, :rel => 'other_document'
+      #     end
+      #   end
+      #
+      #   doc = SomeDocument.new
+      #   doc.other_documents # => []
+      #
+      #   other_doc = OtherDocument.get( '885387e892e63f4b6d31dbc877533099' )
+      #   doc.other_documents << other_doc
+      #
+      #   doc.other_documents # => [ <OtherDocument#12121212> ]
+      #
+      # @param [Symbol] name of the relationship
+      # @param [Hash] options for the relationship
+      # @option options [String] :class the class of the related document/model
+      # @option options [String] :rel the value of the +rel+ key in the related hash
+      # @option options [Fixnum] :requires (nil) a number of documents required
+      # @option options [Symbol] :id_method (:id) name of a method use to retrieve the 'foreign key' value from documents added to the relationship
+      # @option options [Symbol] :load_via (:get/:find) name of the class method used to retreive related documents (defaults to :get for CouchRest::ExtendedDocument, :find for ActiveRecord::Base)
+      def some( name, options = {} )
+        options[:source] = @klass
+
+        @klass.correlations << Correlate::Relationships.build_correlation( name, :some, options )
+
+        @klass.class_eval <<-EOF, __FILE__, __LINE__
+          def #{name}( raw = false )
+            correlations = self.links.rel( '#{name}' )
+
+            #correlations.map! do |c|
+            #  self.links.correlation_for_object( c ).correlate( c )
+            #end unless raw
+            unless raw
+              c = self.class.correlation_for( correlations.first )
+              correlations = c.bulk_correlate( correlations ) unless c.nil?
+            end
+
+            correlations
+          end
+        EOF
+      end
+
+      # Specify that this document will have a single document of said relationship.
+      #
+      # @example Defining correlations and using them
+      #   class OtherDocument < CouchRest::ExtendedDocument
+      #     include Correlate
+      #
+      #     related_to do
+      #       a :some_document, :class => 'SomeDocument'
+      #     end
+      #   end
+      #
+      #   doc = OtherDocument.new
+      #   doc.some_document # => nil
+      #
+      #   some_doc = SomeDocument.get( '885387e892e63f4b6d31dbc877533099' )
+      #   doc.some_document = some_doc
+      #
+      #   doc.some_document # => [ <SomeDocument#12121212> ]
+      #
+      # @param [Symbol] name of the relationship
+      # @param [Hash] options for the relationship
+      # @option options [String] :class the class of the related document/model
+      # @option options [String] :rel (name) the value of the +rel+ key in the related hash
+      # @option options [Fixnum] :required (false) whether required or not
+      # @option options [Symbol] :id_method (:id) name of a method use to retrieve the 'foreign key' value from documents added to the relationship
+      # @option options [Symbol] :load_via (:get/:find) name of the class method used to retreive related documents (defaults to :get for CouchRest::ExtendedDocument, :find for ActiveRecord::Base)
+      def a( name, options = {} )
+        options[:source] = @klass
+
+        @klass.correlations << Correlate::Relationships.build_correlation( name, :a, options )
+
+        @klass.class_eval <<-EOF, __FILE__, __LINE__
+          def #{name}=( object )
+            self.links.replace( object )
+          end
+
+          def #{name}( raw = false )
+            correlation = self.links.rel( '#{name}' ).first
+            return if correlation.nil?
+
+            correlation = self.class.correlation_for( correlation ).correlate( correlation ) unless raw
+
+            correlation
+          end
+        EOF
+      end
+
+      # @private
+      def build_validators
+        if @klass.included_modules.include?( ::CouchRest::Validation )
+
+          fields = [ :links ]
+          opts = @klass.opts_from_validator_args( fields )
+          @klass.add_validator_to_context( opts, fields, Correlate::Validator )
+        end
+      end
+
+      # @private
+      def build_views
+        @klass.view_by :rel,
+          :map => <<-MAP
+            function( doc ) {
+              if( doc['couchrest-type'] == '#{@klass}' ) {
+                doc.links.forEach(function(link) {
+                  emit([ link.rel, link.href ], 1);
+                });
+              }
+            }
+          MAP
+      end
+
+    end
+  end
+end