rom 1.0.0 → 2.0.0

data/lib/rom/plugins/relation/registry_reader.rb

@@ -1,6 +1,8 @@
 module ROM
   module Plugins
     module Relation
+      EMPTY_REGISTRY = RelationRegistry.new.freeze
+
       # Allows relations to access all other relations through registry
       #
       # For now this plugin is always enabled
@@ -10,7 +12,7 @@ module ROM
         # @api private
         def self.included(klass)
           super
-          klass.option :__registry__, type: Hash, default: EMPTY_HASH, reader: true
+          klass.option :__registry__, type: RelationRegistry, default: EMPTY_REGISTRY, reader: true
         end
 
         # @api private

data/lib/rom/plugins/relation/view.rb

@@ -11,6 +11,7 @@ module ROM
             extend ClassInterface
 
             option :view, reader: true
+            option :attributes
 
             def self.attributes
               @__attributes__ ||= {}
@@ -27,13 +28,17 @@ module ROM
         #
         # @api private
         def attributes(view_name = view)
-          header = self.class.attributes
-            .fetch(view_name, self.class.attributes.fetch(:base))
-
-          if header.is_a?(Proc)
-            instance_exec(&header)
+          if options.key?(:attributes)
+            options[:attributes]
           else
-            header
+            header = self.class.attributes
+              .fetch(view_name, self.class.attributes.fetch(:base))
+
+            if header.is_a?(Proc)
+              instance_exec(&header)
+            else
+              header
+            end
           end
         end
 

data/lib/rom/relation.rb

@@ -8,6 +8,10 @@ require 'rom/relation/curried'
 require 'rom/relation/composite'
 require 'rom/relation/graph'
 require 'rom/relation/materializable'
+require 'rom/association_set'
+
+require 'rom/types'
+require 'rom/schema'
 
 module ROM
   # Base relation class
@@ -32,36 +36,63 @@ module ROM
     include Materializable
     include Pipeline
 
+    # @!attribute [r] mappers
+    #   @return [MapperRegistry] an optional mapper registry (empty by default)
     option :mappers, reader: true, default: proc { MapperRegistry.new }
 
-    # Dataset used by the relation
+    # @!attribute [r] schema_hash
+    #   @return [Object#[]] tuple processing function, uses schema or defaults to Hash[]
+    #   @api private
+    option :schema_hash, reader: true, default: -> relation {
+      relation.schema? ? Types::Coercible::Hash.schema(relation.schema.to_h) : Hash
+    }
+
+    # @!attribute [r] associations
+    #   @return [AssociationSet] Schema's association set (empty by default)
+    option :associations, reader: true, default: -> rel {
+      rel.schema? ? rel.schema.associations : Schema::EMPTY_ASSOCIATION_SET
+    }
+
+    # @!attribute [r] dataset
+    #   @return [Object] dataset used by the relation provided by relation's gateway
+    #   @api public
+    attr_reader :dataset
+
+    # @!attribute [r] schema
+    #   @return [Schema] returns relation schema object (if defined)
+    #   @api public
+    attr_reader :schema
+
+    # Initializes a relation object
     #
-    # This object is provided by the gateway during the setup
+    # @param dataset [Object]
     #
-    # @return [Object]
+    # @param options [Hash]
+    #   @option :mappers [MapperRegistry]
+    #   @option :schema_hash [#[]]
+    #   @option :associations [AssociationSet]
     #
-    # @api private
-    attr_reader :dataset
-
-    # @api private
+    # @api public
     def initialize(dataset, options = EMPTY_HASH)
       @dataset = dataset
+      @schema = self.class.schema
       super
     end
 
-    # Yield dataset tuples
+    # Yields relation tuples
     #
     # @yield [Hash]
+    # @return [Enumerator] if block is not provided
     #
-    # @api private
+    # @api public
     def each(&block)
       return to_enum unless block
       dataset.each { |tuple| yield(tuple) }
     end
 
-    # Eager load other relation(s) for this relation
+    # Composes with other relations
     #
-    # @param [Array<Relation>] others The other relation(s) to eager load
+    # @param *others [Array<Relation>] The other relation(s) to compose with
     #
     # @return [Relation::Graph]
     #
@@ -70,7 +101,7 @@ module ROM
       Graph.build(self, others)
     end
 
-    # Load relation
+    # Loads relation
     #
     # @return [Relation::Loaded]
     #
@@ -79,7 +110,7 @@ module ROM
       Loaded.new(self)
     end
 
-    # Materialize a relation into an array
+    # Materializes a relation into an array
     #
     # @return [Array<Hash>]
     #
@@ -88,7 +119,7 @@ module ROM
       to_enum.to_a
     end
 
-    # Return if this relation is curried
+    # Returns if this relation is curried
     #
     # @return [false]
     #
@@ -97,9 +128,33 @@ module ROM
       false
     end
 
+    # Returns if this relation is a graph
+    #
+    # @return [false]
+    #
     # @api private
-    def with(options)
-      __new__(dataset, options)
+    def graph?
+      false
+    end
+
+    # Returns true if a relation has schema defined
+    #
+    # @return [TrueClass, FalseClass]
+    #
+    # @api private
+    def schema?
+      ! schema.nil?
+    end
+
+    # Returns a new instance with the same dataset but new options
+    #
+    # @param new_options [Hash]
+    #
+    # @return [Relation]
+    #
+    # @api private
+    def with(new_options)
+      __new__(dataset, options.merge(new_options))
     end
 
     private
@@ -108,5 +163,10 @@ module ROM
     def __new__(dataset, new_opts = EMPTY_HASH)
       self.class.new(dataset, options.merge(new_opts))
     end
+
+    # @api private
+    def composite_class
+      Relation::Composite
+    end
   end
 end

data/lib/rom/relation/class_interface.rb

@@ -2,6 +2,8 @@ require 'set'
 
 require 'rom/support/auto_curry'
 require 'rom/relation/curried'
+require 'rom/relation/name'
+require 'rom/schema'
 
 module ROM
   class Relation
@@ -30,9 +32,11 @@ module ROM
         klass.class_eval do
           use :registry_reader
 
-          defines :gateway, :dataset, :dataset_proc, :register_as
+          defines :gateway, :dataset, :dataset_proc, :register_as, :schema_dsl, :schema_inferrer
 
           gateway :default
+          schema_dsl Schema::DSL
+          schema_inferrer nil
 
           dataset default_name
 
@@ -93,7 +97,7 @@ module ROM
 
           # @api private
           def initialize(dataset, options = EMPTY_HASH)
-            @name = self.class.dataset
+            @name = Name.new(self.class.register_as, self.class.dataset)
             super
           end
 
@@ -125,6 +129,43 @@ module ROM
         raise AdapterNotPresentError.new(adapter, :relation)
       end
 
+      # Specify canonical schema for a relation
+      #
+      # With a schema defined commands will set up a type-safe input handler
+      # automatically
+      #
+      # @example
+      #   class Users < ROM::Relation[:sql]
+      #     schema do
+      #       attribute :id, Types::Serial
+      #       attribute :name, Types::String
+      #     end
+      #   end
+      #
+      #   # access schema
+      #   Users.schema
+      #
+      # @return [Schema]
+      #
+      # @param [Symbol] dataset An optional dataset name
+      # @param [Boolean] infer Whether to do an automatic schema inferring
+      #
+      # @api public
+      def schema(dataset = nil, infer: false, &block)
+        if defined?(@schema)
+          @schema
+        elsif block || infer
+          self.dataset(dataset) if dataset
+          self.register_as(self.dataset) unless register_as
+
+          name = Name[register_as, self.dataset]
+          inferrer = infer ? schema_inferrer : nil
+          dsl = schema_dsl.new(name, inferrer, &block)
+
+          @schema = dsl.call
+        end
+      end
+
       # Dynamically define a method that will forward to the dataset and wrap
       # response in the relation itself
       #
@@ -175,7 +216,7 @@ module ROM
         ancestor_methods = ancestors.reject { |klass| klass == self }
           .map(&:instance_methods).flatten
 
-        instance_methods - ancestor_methods
+        instance_methods - ancestor_methods + auto_curried_methods
       end
 
       # Hook to finalize a relation after its instance was created

data/lib/rom/relation/curried.rb

@@ -1,6 +1,7 @@
 require 'rom/support/options'
 
 require 'rom/pipeline'
+require 'rom/relation/name'
 require 'rom/relation/materializable'
 
 module ROM
@@ -10,15 +11,18 @@ module ROM
       include Materializable
       include Pipeline
 
-      option :name, type: Symbol, reader: true
+      option :name, type: Symbol
       option :arity, type: Integer, reader: true, default: -1
       option :curry_args, type: Array, reader: true, default: EMPTY_ARRAY
 
       attr_reader :relation
 
+      attr_reader :name
+
       # @api private
       def initialize(relation, options = EMPTY_HASH)
         @relation = relation
+        @name = relation.name.with(options[:name])
         super
       end
 
@@ -33,7 +37,7 @@ module ROM
           all_args = curry_args + args
 
           if arity == all_args.size
-            Loaded.new(relation.__send__(name, *all_args))
+            Loaded.new(relation.__send__(name.relation, *all_args))
           else
             __new__(relation, curry_args: all_args)
           end
@@ -47,7 +51,7 @@ module ROM
       def to_a
         raise(
           ArgumentError,
-          "#{relation.class}##{name} arity is #{arity} " \
+          "#{relation.class}##{name.relation} arity is #{arity} " \
           "(#{curry_args.size} args given)"
         )
       end
@@ -64,7 +68,7 @@ module ROM
 
       # @api private
       def respond_to_missing?(name, include_private = false)
-        super || relation.respond_to?(name)
+        super || relation.respond_to?(name, include_private)
       end
 
       private
@@ -74,6 +78,11 @@ module ROM
         Curried.new(relation, options.merge(new_opts))
       end
 
+      # @api private
+      def composite_class
+        Relation::Composite
+      end
+
       # @api private
       def method_missing(meth, *args, &block)
         if relation.respond_to?(meth)

data/lib/rom/relation/graph.rb

@@ -5,11 +5,9 @@ require 'rom/pipeline'
 
 module ROM
   class Relation
-    # Load a relation with its associations
+    # Compose relations using join-keys
     #
     # @example
-    #   ROM.setup(:memory)
-    #
     #   class Users < ROM::Relation[:memory]
     #   end
     #
@@ -19,8 +17,6 @@ module ROM
     #     end
     #   end
     #
-    #   rom = ROM.finalize.env
-    #
     #   rom.relations[:users] << { name: 'Jane' }
     #   rom.relations[:tasks] << { user: 'Jane', title: 'Do something' }
     #
@@ -65,6 +61,15 @@ module ROM
         @nodes = nodes
       end
 
+      # Return if this is a graph relation
+      #
+      # @return [true]
+      #
+      # @api private
+      def graph?
+        true
+      end
+
       # Combine this graph with more nodes
       #
       # @param [Array<Relation::Lazy>]
@@ -100,6 +105,11 @@ module ROM
       def decorate?(other)
         super || other.is_a?(Curried)
       end
+
+      # @api private
+      def composite_class
+        Relation::Composite
+      end
     end
   end
 end

data/lib/rom/relation/loaded.rb

@@ -40,12 +40,7 @@ module ROM
       # @api public
       def each(&block)
         return to_enum unless block
-        collection.each { |object| yield(object) }
-      end
-
-      # @api public
-      def new(collection)
-        self.class.new(source, collection)
+        collection.each { |tuple| yield(tuple) }
       end
 
       # Returns a single tuple from the relation if there is one.
@@ -77,6 +72,47 @@ module ROM
           'The relation does not contain any tuples'
         )
       end
+
+      # Return a list of values under provided key
+      #
+      # @example
+      #   all_users = rom.relations[:users].call
+      #   all_users.pluck(:name)
+      #   # ["Jane", "Joe"]
+      #
+      # @param [Symbol] key The key name
+      #
+      # @return [Array]
+      # @raises KeyError when provided key doesn't exist in any of the tuples
+      #
+      # @api public
+      def pluck(key)
+        map { |tuple| tuple.fetch(key) }
+      end
+
+      # Pluck primary key values
+      #
+      # This method *may not work* with adapters that don't provide relations
+      # that have primary key configured
+      #
+      # @example
+      #   users = rom.relations[:users].call
+      #   users.primary_keys
+      #   # [1, 2, 3]
+      #
+      # @return [Array]
+      #
+      # @api public
+      def primary_keys
+        pluck(source.primary_key)
+      end
+
+      # Return a loaded relation with a new collection
+      #
+      # @api public
+      def new(collection)
+        self.class.new(source, collection)
+      end
     end
   end
 end