rom-core 4.0.0.beta3 → 4.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8a152a49542a83c5195f02e61f08823c7207f23
-  data.tar.gz: d4513f31be747f8f01e7c581084782afc3662a6a
+  metadata.gz: dd842da91b8eff4e935f9bc0064b7225fbc41d6a
+  data.tar.gz: b949c0798bbddfb9bb49b52b0e4137759accc1f7
 SHA512:
-  metadata.gz: 652ebe10f678636a8dfe0dd78e1f31fbba58499a9e65eaf1589e46c3abc87e730ee773fdf60435146725e73ca7596e519bc3888dd5498a3d81a90783740a7b40
-  data.tar.gz: 95f2e25a3eac0195a6d9d35697b619b52364255b7fefcbfd1c68a647f9aefecc21a489f9a945346f6834d2936d81235b447451c9131d2b86be40a5c834144e00
+  metadata.gz: c95c856d8c205db0013f905ad72e4e8bcecc243f227410d05607c8e2f1280e5d7cf8943c607cd6b45f5926e55e8febadab4e809cb847efe3e96c48e8c4873200
+  data.tar.gz: bf2277dae18e48950740d93a6478cf4d0d56eda97065b797edb5d88d8ab9327f871ab99d2207a909ae80663ae0a654b2495485be7ddf071ab5da6105737b9db8

data/CHANGELOG.md

@@ -12,8 +12,10 @@ Previous `rom` gem was renamed to `rom-core`
 * `Relation#command` which automatically creates a command for a given relation, supports graphs too (solnic)
 * `Relation::to_ast` which returns an AST representation of a relation. This can be used to infer other objects based on relation information (solnic)
 * `Relation::Name#as` which returns an aliased relation name (solnic)
-* Association DSL supports `:override` option which will use configured `:view` as the relation used by association (solnic)
 * Associations are now part of core API and available to all adapters, cross-adapter associations are supported too via `:override` option (solnic)
+* New settings in association DSL:
+  * `:override` option which will use configured `:view` as the relation used by association (solnic)
+  * `:combine_keys` option which overriddes default combine keys that are based on join keys (solnic)
 * `Schema#primary_key_name` and `Schema#primary_key_names` are now part of core schema API (solnic)
 * `Schema#to_ast` which returns an AST representation of a relation schema (flash-gordon)
 * Plugin system supports schema plugins (flash-gordon)

data/lib/rom/association_set.rb

@@ -1,6 +1,9 @@
 require 'rom/registry'
 
 module ROM
+  # Association set contains a registry with associations defined
+  # in schema DSL
+  #
   # @api public
   class AssociationSet < ROM::Registry
     # @api private

data/lib/rom/associations/abstract.rb

@@ -32,6 +32,11 @@ module ROM
       #   @return [ROM::SQL::Relation::Name] the target relation
       option :target, reader: true
 
+      # Create an association object
+      #
+      # @param [Definition] definition The association definition object
+      # @param [RelationRegistry] relations The relation registry
+      #
       # @api public
       def self.new(definition, relations)
         super(
@@ -42,62 +47,116 @@ module ROM
         )
       end
 
+      # Return if an association has an alias
+      #
+      # @return [Boolean]
+      #
       # @api public
       def aliased?
         definition.aliased?
       end
 
+      # Return association alias
+      #
+      # @return [Symbol]
+      #
       # @api public
       def as
         definition.as
       end
 
+      # Return association canonical name
+      #
+      # @return [Symbol]
+      #
       # @api public
       def name
         definition.name
       end
 
+      # Return the name of a custom relation view that should be use to
+      # extend or override default association view
+      #
+      # @return [Symbol]
+      #
       # @api public
       def view
         definition.view
       end
 
+      # Return association foreign key name
+      #
+      # @return [Symbol]
+      #
       # @api public
       def foreign_key
         definition.foreign_key
       end
 
+      # Return result type
+      #
+      # This can be either :one or :many
+      #
+      # @return [Symbol]
+      #
       # @api public
       def result
         definition.result
       end
 
+      # Return if a custom view should override default association view
+      #
+      # @return [Boolean]
+      #
       # @api public
       def override?
         definition.override
       end
 
+      # Return the name of a key in tuples under which loaded association data are returned
+      #
+      # @return [Symbol]
+      #
       # @api public
       def key
         as || name
       end
 
+      # Applies custom view to the default association view
+      #
+      # @return [Relation]
+      #
       # @api protected
       def apply_view(schema, relation)
         view_rel = relation.public_send(view)
         schema.merge(view_rel.schema).uniq(&:key).(view_rel)
       end
 
+      # Return combine keys hash
+      #
+      # Combine keys are used for merging associated data together, typically these
+      # are the same as fk<=>pk mapping
+      #
+      # @return [Hash<Symbol=>Symbol>]
+      #
       # @api public
       def combine_keys
-        { source_key => target_key }
+        definition.combine_keys || { source_key => target_key }
       end
 
+      # Return names of source PKs and target FKs
+      #
+      # @return [Array<Symbol>]
+      #
       # @api private
       def join_key_map
         join_keys.to_a.flatten(1).map(&:key)
       end
 
+      # Return target relation configured as a combine node
+      #
+      # @return [Relation]
+      #
       # @api private
       def node
         target.with(
@@ -106,6 +165,10 @@ module ROM
         )
       end
 
+      # Return target relation as a wrap node
+      #
+      # @return [Relation]
+      #
       # @api private
       def wrap
         target.with(
@@ -115,6 +178,10 @@ module ROM
         )
       end
 
+      # Prepare association's target relation for composition
+      #
+      # @return [Relation]
+      #
       # @api private
       def prepare(target)
         if override?
@@ -124,6 +191,10 @@ module ROM
         end
       end
 
+      # Return if this association's source relation is the same as the target
+      #
+      # @return [Boolean]
+      #
       # @api private
       def self_ref?
         source.name.dataset == target.name.dataset

data/lib/rom/associations/definitions/abstract.rb

@@ -55,16 +55,20 @@ module ROM
         #   @return [TrueClass,FalseClass] Whether custom view should override default one or not
         option :override, optional: true, default: -> { false }
 
+        # @!attribute [r] combine_keys
+        #   @return [Hash<Symbol=>Symbol>] Override inferred combine keys
+        option :combine_keys, optional: true
+
         # Instantiate a new association definition
         #
         # @param [Symbol] source The name of the source dataset
         # @param [Symbol] target The name of the target dataset
-        # @param [Hash] options The option hash
-        # @option options [Symbol] :as The name of the association (defaults to target)
-        # @option options [Symbol] :relation The name of the target relation (defaults to target)
-        # @option options [Symbol] :foreign_key The name of a custom foreign key
-        # @option options [Symbol] :view The name of a custom relation view on the target's relation side
-        # @option options [TrueClass,FalseClass] :override Whether provided :view should override association's default view
+        # @param [Hash] opts The option hash
+        # @option opts [Symbol] :as The name of the association (defaults to target)
+        # @option opts [Symbol] :relation The name of the target relation (defaults to target)
+        # @option opts [Symbol] :foreign_key The name of a custom foreign key
+        # @option opts [Symbol] :view The name of a custom relation view on the target's relation side
+        # @option opts [TrueClass,FalseClass] :override Whether provided :view should override association's default view
         #
         # @api public
         def self.new(source, target, opts = EMPTY_HASH)
@@ -96,16 +100,28 @@ module ROM
           options
         end
 
+        # Return true if association's default relation view should be overridden by a custom one
+        #
+        # @return [Boolean]
+        #
         # @api public
         def override?
           options[:override].equal?(true)
         end
 
+        # Return true if association is aliased
+        #
+        # @return [Boolean]
+        #
         # @api public
         def aliased?
           options.key?(:as)
         end
 
+        # Return association class for a given definition object
+        #
+        # @return [Class]
+        #
         # @api public
         def type
           Dry::Core::Inflector.demodulize(self.class.name).to_sym

data/lib/rom/associations/definitions/many_to_many.rb

@@ -4,9 +4,12 @@ require 'rom/associations/definitions/abstract'
 module ROM
   module Associations
     module Definitions
+      # @api private
       class ManyToMany < Abstract
         result :many
 
+        # @!attribute [r] through
+        #   @return [ThroughIdentifier] The name of the "through" relation
         option :through, reader: true
 
         # @api private

data/lib/rom/associations/definitions/many_to_one.rb

@@ -3,6 +3,7 @@ require 'rom/associations/definitions/abstract'
 module ROM
   module Associations
     module Definitions
+      # @api private
       class ManyToOne < Abstract
         result :one
       end

data/lib/rom/associations/definitions/one_to_many.rb

@@ -3,6 +3,7 @@ require 'rom/associations/definitions/abstract'
 module ROM
   module Associations
     module Definitions
+      # @api private
       class OneToMany < Abstract
         result :many
       end

data/lib/rom/associations/definitions/one_to_one.rb

@@ -3,6 +3,7 @@ require 'rom/associations/definitions/abstract'
 module ROM
   module Associations
     module Definitions
+      # @api private
       class OneToOne < Abstract
         result :one
       end

data/lib/rom/associations/definitions/one_to_one_through.rb

@@ -3,6 +3,7 @@ require 'rom/associations/definitions/abstract'
 module ROM
   module Associations
     module Definitions
+      # @api private
       class OneToOneThrough < ManyToMany
         result :one
       end

data/lib/rom/associations/many_to_many.rb

@@ -3,7 +3,12 @@ require 'rom/associations/abstract'
 
 module ROM
   module Associations
+    # Abstract many-to-many association type
+    #
+    # @api public
     class ManyToMany < Abstract
+      # @!attribute [r] join_relation
+      #   @return [Relation] Intermediate join relation
       attr_reader :join_relation
 
       # @api private
@@ -12,26 +17,49 @@ module ROM
         @join_relation = relations[through]
       end
 
+      # Adapters should implement this method
+      #
+      # @abstract
+      #
       # @api public
       def call(*)
         raise NotImplementedError
       end
 
+      # Return configured or inferred FK name
+      #
+      # @return [Symbol]
+      #
       # @api public
       def foreign_key
         definition.foreign_key || join_relation.foreign_key(source.name)
       end
 
+      # Return join-relation name
+      #
+      # @return [Symbol]
+      #
       # @api public
       def through
         definition.through
       end
 
+      # Return parent's relation combine keys
+      #
+      # @return [Hash<Symbol=>Symbol>]
+      #
       # @api private
       def parent_combine_keys
         target.associations[source.name].combine_keys.to_a.flatten(1)
       end
 
+      # Associate child tuples with the provided parent
+      #
+      # @param [Array<Hash>] children An array with child tuples
+      # @param [Array,Hash] parent An array with parent tuples or a single tuple
+      #
+      # @return [Array<Hash>]
+      #
       # @api private
       def associate(children, parent)
         ((spk, sfk), (tfk, tpk)) = join_key_map
@@ -48,16 +76,28 @@ module ROM
 
       protected
 
+      # Primary key name on the source side
+      #
+      # @return [Symbol]
+      #
       # @api protected
       def source_key
         source.primary_key
       end
 
+      # Foreign key name on the target side
+      #
+      # @return [Symbol]
+      #
       # @api protected
       def target_key
         foreign_key
       end
 
+      # Return association for many-to-many-through
+      #
+      # @return [Association]
+      #
       # @api protected
       def join_assoc
         if join_relation.associations.key?(through.assoc_name)
@@ -67,6 +107,10 @@ module ROM
         end
       end
 
+      # Return a [pk, fk] mapping for source/target relations
+      #
+      # @return [Array<Symbol>]
+      #
       # @api protected
       def join_key_map
         left = super

data/lib/rom/associations/many_to_one.rb

@@ -2,17 +2,35 @@ require 'rom/associations/abstract'
 
 module ROM
   module Associations
+    # Abstract many-to-one association type
+    #
+    # @api public
     class ManyToOne < Abstract
+      # Adapters must implement this method
+      #
+      # @abstract
+      #
       # @api public
       def call(*)
         raise NotImplementedError
       end
 
+      # Return configured or inferred FK name
+      #
+      # @return [Symbol]
+      #
       # @api public
       def foreign_key
         definition.foreign_key || source.foreign_key(target.name)
       end
 
+      # Associate child with a parent
+      #
+      # @param [Hash] child The child tuple
+      # @param [Hash] parent The parent tuple
+      #
+      # @return [Hash]
+      #
       # @api private
       def associate(child, parent)
         fk, pk = join_key_map
@@ -21,11 +39,19 @@ module ROM
 
       protected
 
+      # Return foreign key on the source side
+      #
+      # @return [Symbol]
+      #
       # @api protected
       def source_key
         foreign_key
       end
 
+      # Return primary key on the target side
+      #
+      # @return [Symbol]
+      #
       # @api protected
       def target_key
         target.schema.primary_key_name