rom 2.0.2 → 3.0.0

data/lib/rom/relation.rb

@@ -1,3 +1,4 @@
+require 'rom/initializer'
 require 'rom/relation/class_interface'
 
 require 'rom/pipeline'
@@ -17,82 +18,97 @@ module ROM
   # Base relation class
   #
   # Relation is a proxy for the dataset object provided by the gateway. It
-  # forwards every method to the dataset, which is why the "native" interface of
+  # can forward methods to the dataset, which is why the "native" interface of
   # the underlying gateway is available in the relation. This interface,
   # however, is considered private and should not be used outside of the
   # relation instance.
   #
-  # ROM builds sub-classes of this class for every relation defined in the
-  # environment for easy inspection and extensibility - every gateway can
-  # provide extensions for those sub-classes but there is always a vanilla
-  # relation instance stored in the schema registry.
+  # Individual adapters sets up their relation classes and provide different APIs
+  # depending on their persistence backend.
+  #
+  # Vanilla Relation class doesn't have APIs that are specific to ROM container setup.
+  # When adapter Relation class inherits from this class, these APIs are added automatically,
+  # so that they can be registered within a container.
+  #
+  # @see ROM::Relation::ClassInterface
   #
   # @api public
   class Relation
+    # Default no-op output schema which is called in `Relation#each`
+    NOOP_OUTPUT_SCHEMA = -> tuple { tuple }.freeze
+
+    extend Initializer
     extend ClassInterface
 
-    include Options
     include Dry::Equalizer(:dataset)
     include Materializable
     include Pipeline
 
+    # @!attribute [r] dataset
+    #   @return [Object] dataset used by the relation provided by relation's gateway
+    #   @api public
+    param :dataset
+
     # @!attribute [r] mappers
     #   @return [MapperRegistry] an optional mapper registry (empty by default)
     option :mappers, reader: true, default: proc { MapperRegistry.new }
 
-    # @!attribute [r] schema_hash
+    # @!attribute [r] schema
+    #   @return [Schema] relation schema, defaults to class-level canonical
+    #                    schema (if it was defined) and sets an empty one as
+    #                    the fallback
+    #   @api public
+    option :schema, reader: true, optional: true, default: method(:default_schema).to_proc
+
+    # @!attribute [r] input_schema
     #   @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
+    option :input_schema, reader: true, default: -> relation {
+      relation.schema? ? schema.to_input_hash : 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] output_schema
+    #   @return [Object#[]] tuple processing function, uses schema or defaults to NOOP_OUTPUT_SCHEMA
+    #   @api private
+    option :output_schema, reader: true, optional: true, default: -> relation {
+      relation.schema.any?(&:read?) ? schema.to_output_hash : NOOP_OUTPUT_SCHEMA
     }
 
-    # @!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
+    # Return schema attribute
+    #
+    # @example accessing canonical attribute
+    #   users[:id]
+    #   # => #<ROM::SQL::Attribute[Integer] primary_key=true name=:id source=ROM::Relation::Name(users)>
     #
-    # @param dataset [Object]
+    # @example accessing joined attribute
+    #   tasks_with_users = tasks.join(users).select_append(tasks[:title])
+    #   tasks_with_users[:title, :tasks]
+    #   # => #<ROM::SQL::Attribute[String] primary_key=false name=:title source=ROM::Relation::Name(tasks)>
     #
-    # @param options [Hash]
-    #   @option :mappers [MapperRegistry]
-    #   @option :schema_hash [#[]]
-    #   @option :associations [AssociationSet]
+    # @return [Schema::Attribute]
     #
     # @api public
-    def initialize(dataset, options = EMPTY_HASH)
-      @dataset = dataset
-      @schema = self.class.schema
-      super
+    def [](name)
+      schema[name]
     end
 
     # Yields relation tuples
     #
+    # Every tuple is processed through Relation#output_schema, it's a no-op by default
+    #
     # @yield [Hash]
+    #
     # @return [Enumerator] if block is not provided
     #
     # @api public
     def each(&block)
       return to_enum unless block
-      dataset.each { |tuple| yield(tuple) }
+      dataset.each { |tuple| yield(output_schema[tuple]) }
     end
 
     # Composes with other relations
     #
-    # @param *others [Array<Relation>] The other relation(s) to compose with
+    # @param [Array<Relation>] others The other relation(s) to compose with
     #
     # @return [Relation::Graph]
     #
@@ -143,27 +159,71 @@ module ROM
     #
     # @api private
     def schema?
-      ! schema.nil?
+      ! schema.empty?
+    end
+
+    # Return a new relation with provided dataset and additional options
+    #
+    # Use this method whenever you need to use dataset API to get a new dataset
+    # and you want to return a relation back. Typically relation API should be
+    # enough though. If you find yourself using this method, it might be worth
+    # to consider reporting an issue that some dataset functionality is not available
+    # through relation API.
+    #
+    # @example with a new dataset
+    #   users.new(users.dataset.some_method)
+    #
+    # @example with a new dataset and options
+    #   users.new(users.dataset.some_method, other: 'options')
+    #
+    # @param [Object] dataset
+    # @param [Hash] new_opts Additional options
+    #
+    # @api public
+    def new(dataset, new_opts = EMPTY_HASH)
+      self.class.new(dataset, new_opts.empty? ? options : options.merge(new_opts))
     end
 
     # Returns a new instance with the same dataset but new options
     #
+    # @example
+    #   users.with(output_schema: -> tuple { .. })
+    #
     # @param new_options [Hash]
     #
     # @return [Relation]
     #
     # @api private
     def with(new_options)
-      __new__(dataset, options.merge(new_options))
+      new(dataset, options.merge(new_options))
     end
 
-    private
+    # Return all registered relation schemas
+    #
+    # This holds all schemas defined via `view` DSL
+    #
+    # @return [Hash<Symbol=>Schema>]
+    #
+    # @api public
+    def schemas
+      @schemas ||= self.class.schemas
+    end
 
-    # @api private
-    def __new__(dataset, new_opts = EMPTY_HASH)
-      self.class.new(dataset, options.merge(new_opts))
+    # Return schema's association set (empty by default)
+    #
+    # @return [AssociationSet] Schema's association set (empty by default)
+    #
+    # @api public
+    def associations
+      @associations ||= schema.associations
     end
 
+    private
+
+    # Hook used by `Pipeline` to get the class that should be used for composition
+    #
+    # @return [Class]
+    #
     # @api private
     def composite_class
       Relation::Composite

data/lib/rom/schema/attribute.rb

@@ -0,0 +1,367 @@
+require 'delegate'
+require 'dry/equalizer'
+require 'dry/types/decorator'
+
+module ROM
+  class Schema
+    # Schema attributes provide meta information about types and an API
+    # for additional operations. This class can be extended by adapters to provide
+    # database-specific features. In example rom-sql provides SQL::Attribute
+    # with more features like creating SQL expressions for queries.
+    #
+    # Schema attributes are accessible through canonical relation schemas and
+    # instance-level schemas.
+    #
+    # @api public
+    class Attribute
+      include Dry::Equalizer(:type)
+
+      # !@attribute [r] type
+      #   @return [Dry::Types::Definition, Dry::Types::Sum, Dry::Types::Constrained]
+      attr_reader :type
+
+      # @api private
+      def initialize(type)
+        @type = type
+      end
+
+      # @api private
+      def [](input)
+        type[input]
+      end
+
+      # Return true if this attribute type is a primary key
+      #
+      # @example
+      #   class Users < ROM::Relation[:memory]
+      #     schema do
+      #       attribute :id, Types::Int
+      #       attribute :name, Types::String
+      #
+      #       primary_key :id
+      #     end
+      #   end
+      #
+      #   Users.schema[:id].primary_key?
+      #   # => true
+      #
+      #   Users.schema[:name].primary_key?
+      #   # => false
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @api public
+      def primary_key?
+        meta[:primary_key].equal?(true)
+      end
+
+      # Return true if this attribute type is a foreign key
+      #
+      # @example
+      #   class Tasks < ROM::Relation[:memory]
+      #     schema do
+      #       attribute :id, Types::Int
+      #       attribute :user_id, Types.ForeignKey(:users)
+      #     end
+      #   end
+      #
+      #   Users.schema[:user_id].foreign_key?
+      #   # => true
+      #
+      #   Users.schema[:id].foreign_key?
+      #   # => false
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @api public
+      def foreign_key?
+        meta[:foreign_key].equal?(true)
+      end
+
+      # Return true if this attribute type is a foreign key
+      #
+      # @example
+      #   class Tasks < ROM::Relation[:memory]
+      #     schema do
+      #       attribute :user_id, Types::Int.meta(alias: :id)
+      #       attribute :name, Types::String
+      #     end
+      #   end
+      #
+      #   Users.schema[:user_id].aliased?
+      #   # => true
+      #
+      #   Users.schema[:name].aliased?
+      #   # => false
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @api public
+      def aliased?
+        !meta[:alias].nil?
+      end
+
+      # Return source relation of this attribute type
+      #
+      # @example
+      #   class Tasks < ROM::Relation[:memory]
+      #     schema do
+      #       attribute :id, Types::Int
+      #       attribute :user_id, Types.ForeignKey(:users)
+      #     end
+      #   end
+      #
+      #   Users.schema[:id].source
+      #   # => :tasks
+      #
+      #   Users.schema[:user_id].source
+      #   # => :tasks
+      #
+      # @return [Symbol, Relation::Name]
+      #
+      # @api public
+      def source
+        meta[:source]
+      end
+
+      # Return target relation of this attribute type
+      #
+      # @example
+      #   class Tasks < ROM::Relation[:memory]
+      #     schema do
+      #       attribute :id, Types::Int
+      #       attribute :user_id, Types.ForeignKey(:users)
+      #     end
+      #   end
+      #
+      #   Users.schema[:id].target
+      #   # => nil
+      #
+      #   Users.schema[:user_id].target
+      #   # => :users
+      #
+      # @return [NilClass, Symbol, Relation::Name]
+      #
+      # @api public
+      def target
+        meta[:target]
+      end
+
+      # Return the canonical name of this attribute name
+      #
+      # This *always* returns the name that is used in the datastore, even when
+      # an attribute is aliased
+      #
+      # @example
+      #   class Tasks < ROM::Relation[:memory]
+      #     schema do
+      #       attribute :user_id, Types::Int.meta(alias: :id)
+      #       attribute :name, Types::String
+      #     end
+      #   end
+      #
+      #   Users.schema[:id].name
+      #   # => :id
+      #
+      #   Users.schema[:user_id].name
+      #   # => :user_id
+      #
+      # @return [Symbol]
+      #
+      # @api public
+      def name
+        meta[:name]
+      end
+
+      # Return attribute's alias
+      #
+      # @example
+      #   class Tasks < ROM::Relation[:memory]
+      #     schema do
+      #       attribute :user_id, Types::Int.meta(alias: :id)
+      #       attribute :name, Types::String
+      #     end
+      #   end
+      #
+      #   Users.schema[:user_id].alias
+      #   # => :user_id
+      #
+      #   Users.schema[:name].alias
+      #   # => nil
+      #
+      # @return [NilClass,Symbol]
+      #
+      # @api public
+      def alias
+        meta[:alias]
+      end
+
+      # Return new attribute type with provided alias
+      #
+      # @example
+      #   class Tasks < ROM::Relation[:memory]
+      #     schema do
+      #       attribute :user_id, Types::Int
+      #       attribute :name, Types::String
+      #     end
+      #   end
+      #
+      #   aliased_user_id = Users.schema[:user_id].aliased(:id)
+      #
+      #   aliased_user_id.aliased?
+      #   # => true
+      #
+      #   aliased_user_id.name
+      #   # => :user_id
+      #
+      #   aliased_user_id.alias
+      #   # => :id
+      #
+      # @param [Symbol] name The alias
+      #
+      # @return [Schema::Attribute]
+      #
+      # @api public
+      def aliased(name)
+        meta(alias: name)
+      end
+      alias_method :as, :aliased
+
+      # Return new attribute type with an alias using provided prefix
+      #
+      # @example
+      #   class Users < ROM::Relation[:memory]
+      #     schema do
+      #       attribute :id, Types::Int
+      #       attribute :name, Types::String
+      #     end
+      #   end
+      #
+      #   prefixed_id = Users.schema[:id].prefixed
+      #
+      #   prefixed_id.aliased?
+      #   # => true
+      #
+      #   prefixed_id.name
+      #   # => :id
+      #
+      #   prefixed_id.alias
+      #   # => :users_id
+      #
+      #   prefixed_id = Users.schema[:id].prefixed(:user)
+      #
+      #   prefixed_id.alias
+      #   # => :user_id
+      #
+      # @param [Symbol] prefix The prefix (defaults to source.dataset)
+      #
+      # @return [Schema::Attribute]
+      #
+      # @api public
+      def prefixed(prefix = source.dataset)
+        aliased(:"#{prefix}_#{name}")
+      end
+
+      # Return if the attribute type is from a wrapped relation
+      #
+      # Wrapped attributes are used when two schemas from different relations
+      # are merged together. This way we can identify them easily and handle
+      # correctly in places like auto-mapping.
+      #
+      # @api public
+      def wrapped?
+        meta[:wrapped].equal?(true)
+      end
+
+      # Return attribute type wrapped for the specified relation name
+      #
+      # @param [Symbol] name The name of the source relation (defaults to source.dataset)
+      #
+      # @return [Schema::Attribute]
+      #
+      # @api public
+      def wrapped(name = source.dataset)
+        self.class.new(prefixed(name).meta(wrapped: true))
+      end
+
+      # Return attribute type with additional meta information
+      #
+      # Return meta information hash if no opts are provided
+      #
+      # @param [Hash] opts The meta options
+      #
+      # @return [Schema::Attribute]
+      #
+      # @api public
+      def meta(opts = nil)
+        if opts
+          self.class.new(type.meta(opts))
+        else
+          type.meta
+        end
+      end
+
+      # Return string representation of the attribute type
+      #
+      # @return [String]
+      #
+      # @api public
+      def inspect
+        %(#<#{self.class}[#{type.name}] #{meta.map { |k, v| "#{k}=#{v.inspect}" }.join(' ')}>)
+      end
+      alias_method :pretty_inspect, :inspect
+
+      # Check if the attribute type is equal to another
+      #
+      # @param [Dry::Type, Schema::Attribute]
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @api public
+      def eql?(other)
+        other.is_a?(self.class) ? super : type.eql?(other)
+      end
+
+      # Return if this attribute type has additional attribute type for reading
+      # tuple values
+      #
+      # @return [TrueClass, FalseClass]
+      #
+      # @api private
+      def read?
+        ! meta[:read].nil?
+      end
+
+      # Return read type or self
+      #
+      # @return [Schema::Attribute]
+      #
+      # @api private
+      def to_read_type
+        read? ? meta[:read] : type
+      end
+
+      # @api private
+      def respond_to_missing?(name, include_private = false)
+        type.respond_to?(name) || super
+      end
+
+      private
+
+      # @api private
+      def method_missing(meth, *args, &block)
+        if type.respond_to?(meth)
+          response = type.__send__(meth, *args, &block)
+
+          if response.is_a?(type.class)
+            self.class.new(type)
+          else
+            response
+          end
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/rom/schema/dsl.rb

@@ -13,19 +13,17 @@ module ROM
 
     # @api public
     class DSL < BasicObject
-      attr_reader :name, :attributes, :inferrer
+      attr_reader :relation, :attributes, :inferrer, :schema_class
 
       # @api private
-      def initialize(name, inferrer, &block)
-        @name = name
+      def initialize(relation, schema_class: Schema, inferrer: Schema::DEFAULT_INFERRER, &block)
+        @relation = relation
         @inferrer = inferrer
-        @attributes = nil
+        @schema_class = schema_class
+        @attributes = {}
 
         if block
           instance_exec(&block)
-        elsif inferrer.nil?
-          raise ArgumentError,
-            'You must pass a block to define a schema or set an inferrer for automatic inferring'
         end
       end
 
@@ -34,9 +32,15 @@ module ROM
       # @see Relation.schema
       #
       # @api public
-      def attribute(name, type)
+      def attribute(name, type, options = EMPTY_HASH)
         @attributes ||= {}
-        @attributes[name] = type.meta(name: name)
+
+        @attributes[name] =
+          if options[:read]
+            type.meta(name: name, source: relation, read: options[:read])
+          else
+            type.meta(name: name, source: relation)
+          end
       end
 
       # Specify which key(s) should be the primary key
@@ -51,7 +55,7 @@ module ROM
 
       # @api private
       def call
-        Schema.new(name, attributes, inferrer: inferrer)
+        schema_class.define(relation, attributes: attributes.values, inferrer: inferrer)
       end
     end
   end