guacamole 0.3.0 → 0.4.0

data/lib/guacamole/configuration.rb

@@ -71,7 +71,7 @@ module Guacamole
   class Configuration
     # A wrapper object to handle both configuration from a connection URI and a hash.
     class ConfigStruct
-      attr_reader :url, :username, :password, :database
+      attr_reader :url, :username, :password, :database, :graph
 
       def initialize(config_hash_or_url)
         case config_hash_or_url
@@ -98,6 +98,7 @@ module Guacamole
         @username = hash['username']
         @password = hash['password']
         @database = hash['database']
+        @graph    = hash['graph']
         @url      = "#{hash['protocol']}://#{hash['host']}:#{hash['port']}"
       end
     end
@@ -105,18 +106,13 @@ module Guacamole
     # @!visibility protected
     attr_accessor :database, :default_mapper, :logger
 
-    AVAILABLE_EXPERIMENTAL_FEATURES = [
-      :aql_support
-    ]
-
     class << self
       extend Forwardable
 
       def_delegators :configuration,
                      :database, :database=,
                      :default_mapper=,
-                     :logger=,
-                     :experimental_features=, :experimental_features
+                     :logger=
 
       def default_mapper
         configuration.default_mapper || (self.default_mapper = Guacamole::DocumentModelMapper)
@@ -126,14 +122,61 @@ module Guacamole
         configuration.logger ||= (rails_logger || default_logger)
       end
 
+      def shared_path
+        Pathname.new(File.join(__dir__, '..', '..', 'shared'))
+      end
+
+      # Returns the graph associated with this Guacamole application.
+      #
+      # You can create more graphs by interacting with the database instance directly. This is just the main graph
+      # that will be used to realize relations between models. The default name will be generated based on some
+      # environment information. To set a custom name use the `graph_name` option when configure your connection.
+      #
+      # @return [Graph] The graph to be used internally to handle relations
+      def graph
+        database.graph(graph_name)
+      end
+
+      # Sets a custom name for the internally used graph
+      #
+      # @param [String] graph_name The name of the graph to be used
+      def graph_name=(graph_name)
+        @graph_name = graph_name
+      end
+
+      # The name of the graph to be used internally.
+      #
+      # Determining the name of the graph will go through the following steps:
+      #
+      # 1. Use the manually set `graph_name`
+      # 2. Use the ENV variable `GUACAMOLE_GRAPH` if present.
+      #    This is useful if you configure the application with ENV variables.
+      # 3. If a Rails context was found it will use the name of the application with a `_graph` suffix
+      # 4. If none of the above matched it will use the database name with a `_graph` suffix
+      #
+      # @return [String] The name of the graph to be used
+      def graph_name
+        return @graph_name if @graph_name
+        return ENV['GUACAMOLE_GRAPH'] if ENV['GUACAMOLE_GRAPH']
+
+        base_name = if Module.const_defined?('Rails')
+                      Rails.application.class.name.deconstantize.underscore
+                    else
+                      database.name
+                    end
+
+        [base_name, 'graph'].join('_')
+      end
+
       # Load a YAML configuration file to configure Guacamole
       #
       # @param [String] file_name The file name of the configuration
       def load(file_name)
-        yaml_content  = process_file_with_erb(file_name)
-        config        = YAML.load(yaml_content)[current_environment.to_s]
+        yaml_content    = process_file_with_erb(file_name)
+        config          = build_config(YAML.load(yaml_content)[current_environment.to_s])
+        self.graph_name = config.graph
 
-        create_database_connection(build_config(config))
+        create_database_connection(config)
         warn_if_database_was_not_yet_created
       end
 
@@ -212,20 +255,5 @@ module Guacamole
         ERB.new(File.read(file_name)).result
       end
     end
-
-    # A list of active experimental features. Refer to `AVAILABLE_EXPERIMENTAL_FEATURES` to see
-    # what can be activated.
-    #
-    # @return [Array<Symbol>] The activated experimental features. Defaults to `[]`
-    def experimental_features
-      @experimental_features || []
-    end
-
-    # Experimental features to activate
-    #
-    # @param [Array<Symbol>] features A list of experimental features to activate
-    def experimental_features=(features)
-      @experimental_features = features
-    end
   end
 end

data/lib/guacamole/document_model_mapper.rb

@@ -1,7 +1,6 @@
 # -*- encoding : utf-8 -*-
 
-require 'guacamole/proxies/referenced_by'
-require 'guacamole/proxies/references'
+require 'guacamole/proxies/relation'
 
 module Guacamole
   # This is the default mapper class to map between Ashikawa::Core::Document and
@@ -12,6 +11,80 @@ module Guacamole
   #
   # @note If you plan to bring your own `DocumentModelMapper` please consider using an {Guacamole::IdentityMap}.
   class DocumentModelMapper
+    # An attribute to encapsulate special mapping
+    class Attribute
+      # The name of the attribute with in the model
+      #
+      # @return [Symbol] The name of the attribute
+      attr_reader :name
+
+      # Additional options to be used for the mapping
+      #
+      # @return [Hash] The mapping options for the attribute
+      attr_reader :options
+
+      # Create a new attribute instance
+      #
+      # You must at least provide the name of the attribute to be mapped and
+      # optionally pass configuration for the mapper when it processes this attribute.
+      #
+      # @param [Symbol] name The name of the attribute
+      # @param [Hash] options Additional options to be passed
+      # @option options [Edge] :via The Edge class this attribute relates to
+      def initialize(name, options = {})
+        @name    = name.to_sym
+        @options = options
+      end
+
+      # The name of the getter for this attribute
+      #
+      # @returns [Symbol] The method name to read this attribute
+      def getter
+        name
+      end
+
+      def get_value(model)
+        value = model.send(getter)
+
+        value.is_a?(Guacamole::Query) ? value.entries : value
+      end
+
+      # The name of the setter for this attribute
+      #
+      # @return [String] The method name to set this attribute
+      def setter
+        "#{name}="
+      end
+
+      # Should this attribute be mapped via an Edge in a Graph?
+      #
+      # @return [Boolean] True if there was an edge class configured
+      def map_via_edge?
+        !!edge_class
+      end
+
+      # The edge class to be used during the mapping process
+      #
+      # @return [Edge] The actual edge class
+      def edge_class
+        options[:via]
+      end
+
+      def inverse?
+        !!options[:inverse]
+      end
+
+      # To Attribute instances are equal if their name is equal
+      #
+      # @param [Attribute] other The Attribute to compare this one to
+      # @return [Boolean] True if both have the same name
+      def ==(other)
+        other.instance_of?(self.class) &&
+          other.name == name
+      end
+      alias_method :eql?, :==
+    end
+
     # The class to map to
     #
     # @return [class] The class to map to
@@ -21,8 +94,11 @@ module Guacamole
     #
     # @return [Array] An array of embedded models
     attr_reader :models_to_embed
-    attr_reader :referenced_by_models
-    attr_reader :referenced_models
+
+    # The list of Attributes to treat specially during the mapping process
+    #
+    # @return [Array<Attribute>] The list of special attributes
+    attr_reader :attributes
 
     # Create a new instance of the mapper
     #
@@ -34,8 +110,7 @@ module Guacamole
       @model_class          = model_class
       @identity_map         = identity_map
       @models_to_embed      = []
-      @referenced_by_models = []
-      @referenced_models    = []
+      @attributes           = []
     end
 
     class << self
@@ -64,7 +139,7 @@ module Guacamole
     #       seems to be a good place for this functionality.
     # @param [symbol, string] model_name the name of the model
     # @return [class] the {collection} class for the given model name
-    def collection_for(model_name)
+    def collection_for(model_name = model_class.name)
       self.class.collection_for model_name
     end
 
@@ -74,26 +149,18 @@ module Guacamole
     #
     # @param [Ashikawa::Core::Document] document
     # @return [Model] the resulting model with the given Model class
-    # rubocop:disable MethodLength
     def document_to_model(document)
       identity_map.retrieve_or_store model_class, document.key do
         model = model_class.new(document.to_h)
 
-        referenced_by_models.each do |ref_model_name|
-          model.send("#{ref_model_name}=", Proxies::ReferencedBy.new(ref_model_name, model))
-        end
-
-        referenced_models.each do |ref_model_name|
-          model.send("#{ref_model_name}=", Proxies::References.new(ref_model_name, document))
-        end
-
         model.key = document.key
         model.rev = document.revision
 
+        handle_related_documents(model)
+
         model
       end
     end
-    # rubocop:enable MethodLength
 
     # Map a model to a document
     #
@@ -101,29 +168,14 @@ module Guacamole
     #
     # @param [Model] model
     # @return [Ashikawa::Core::Document] the resulting document
-    # rubocop:disable MethodLength
     def model_to_document(model)
       document = model.attributes.dup.except(:key, :rev)
-      models_to_embed.each do |attribute_name|
-        document[attribute_name] = model.send(attribute_name).map do |embedded_model|
-          embedded_model.attributes.except(:key, :rev)
-        end
-      end
 
-      referenced_models.each do |ref_model_name|
-        ref_key = [ref_model_name.to_s, 'id'].join('_').to_sym
-        ref_model = model.send ref_model_name
-        document[ref_key] = ref_model.key if ref_model
-        document.delete(ref_model_name)
-      end
-
-      referenced_by_models.each do |ref_model_name|
-        document.delete(ref_model_name)
-      end
+      handle_embedded_models(model, document)
+      handle_related_models(document)
 
       document
     end
-    # rubocop:enable MethodLength
 
     # Declare a model to be embedded
     #
@@ -158,12 +210,43 @@ module Guacamole
       @models_to_embed << model_name
     end
 
-    def referenced_by(model_name)
-      @referenced_by_models << model_name
+    # Mark an attribute of the model to be specially treated during mapping
+    #
+    # @param [Symbol] attribute_name The name of the model attribute
+    # @param [Hash] options Additional options to configure the mapping process
+    # @option options [Edge] :via The Edge class this attribute relates to
+    # @example Define a relation via an Edge in a Graph
+    #   class Authorship
+    #     include Guacamole::Edge
+    #
+    #     from :users
+    #     to :posts
+    #   end
+    #
+    #   class BlogpostsCollection
+    #     include Guacamole::Collection
+    #
+    #     map do
+    #       attribute :author, via: Authorship
+    #     end
+    #   end
+    def attribute(attribute_name, options = {})
+      @attributes << Attribute.new(attribute_name, options)
+    end
+
+    # Returns a list of attributes that have an Edge class configured
+    #
+    # @return [Array<Attribute>] A list of attributes which all have an Edge class
+    def edge_attributes
+      attributes.select(&:map_via_edge?)
     end
 
-    def references(model_name)
-      @referenced_models << model_name
+    # Is this Mapper instance responsible for mapping the given model
+    #
+    # @param [Model] model The model to check against
+    # @return [Boolean] True if the given model is an instance of #model_class. False if not.
+    def responsible_for?(model)
+      model.instance_of?(model_class)
     end
 
     private
@@ -171,5 +254,33 @@ module Guacamole
     def identity_map
       @identity_map
     end
+
+    def handle_embedded_models(model, document)
+      models_to_embed.each do |attribute_name|
+        document[attribute_name] = model.send(attribute_name).map do |embedded_model|
+          embedded_model.attributes.except(:key, :rev)
+        end
+      end
+    end
+
+    def handle_related_models(document)
+      edge_attributes.each do |edge_attribute|
+        document.delete(edge_attribute.name)
+      end
+    end
+
+    def handle_related_documents(model)
+      edge_attributes.each do |edge_attribute|
+        just_one = case model.class.attribute_set[edge_attribute.name].type
+                   when Virtus::Attribute::Collection::Type then false
+                   else
+                     true
+                   end
+
+        opts = { just_one: just_one, inverse: edge_attribute.inverse? }
+
+        model.send(edge_attribute.setter, Proxies::Relation.new(model, edge_attribute.edge_class, opts))
+      end
+    end
   end
 end

data/lib/guacamole/edge.rb

@@ -0,0 +1,74 @@
+# -*- encoding : utf-8 -*-
+
+require 'guacamole/model'
+
+require 'active_support'
+require 'active_support/concern'
+
+module Guacamole
+  # An Edge representing a relation between two models within a Graph
+  #
+  # A Guacamole::Edge is specialized model with two predefined attributes (`from` and `to`)
+  # and a class level DSL to define the relation between models inside a Graph. Like normal
+  # models, edge models don't know the database. But unlike the collection classes you define
+  # yourself for your models Guacamole will create a default collection class to be used with
+  # your edge models.
+  #
+  # @!attribute [r] from
+  #   The model on the from side of the edge
+  #
+  #   @return [Guacamole::Model] The document from which the relation originates
+  #
+  # @!attribute [r] to
+  #   The model on the to side of the edge
+  #
+  #   @return [Guacamole::Model] The document to which the relation directs
+  #
+  # @!method self.from(collection_name)
+  #   Define the collection from which all these edges will originate
+  #
+  #   @api public
+  #   @param [Symbol] collection_name The name of the originating collection
+  #
+  # @!method self.to(collection_name)
+  #   Define the collection to which all these edges will direct
+  #
+  #   @api public
+  #   @param [Symbol] collection_name The name of the target collection
+  module Edge
+    extend ActiveSupport::Concern
+
+    included do
+      include Guacamole::Model
+
+      attribute :from, Object
+      attribute :to, Object
+    end
+
+    module ClassMethods
+      def from(collection_name = nil)
+        if collection_name.nil?
+          @from
+        else
+          @from = collection_name
+        end
+      end
+
+      def to(collection_name = nil)
+        if collection_name.nil?
+          @to
+        else
+          @to = collection_name
+        end
+      end
+
+      def to_collection
+        [to.to_s.camelcase, 'Collection'].join('').constantize
+      end
+
+      def from_collection
+        [from.to_s.camelcase, 'Collection'].join('').constantize
+      end
+    end
+  end
+end