rom-sql 1.0.0.beta3 → 1.0.0.rc1

data/lib/rom/sql/migration/migrator.rb

@@ -1,10 +1,12 @@
 require 'pathname'
+
 require 'rom/types'
 require 'rom/initializer'
 
 module ROM
   module SQL
     module Migration
+      # @api private
       class Migrator
         extend Initializer
 
@@ -15,18 +17,22 @@ module ROM
 
         option :path, type: ROM::Types.Definition(Pathname), reader: true, default: proc { DEFAULT_PATH }
 
+        # @api private
         def run(options = {})
           Sequel::Migrator.run(connection, path.to_s, options)
         end
 
+        # @api private
         def pending?
           !Sequel::Migrator.is_current?(connection, path.to_s)
         end
 
+        # @api private
         def migration(&block)
           Sequel.migration(&block)
         end
 
+        # @api private
         def create_file(name, version = generate_version)
           filename = "#{version}_#{name}.rb"
           dirname = Pathname(path)
@@ -38,10 +44,12 @@ module ROM
           fullpath
         end
 
+        # @api private
         def generate_version
           Time.now.utc.strftime(VERSION_FORMAT)
         end
 
+        # @api private
         def migration_file_content
           File.read(Pathname(__FILE__).dirname.join('template.rb').realpath)
         end

data/lib/rom/sql/order_dsl.rb

@@ -2,6 +2,7 @@ require 'rom/sql/dsl'
 
 module ROM
   module SQL
+    # @api private
     class OrderDSL < DSL
       private
 

data/lib/rom/sql/plugin/associates.rb

@@ -5,6 +5,21 @@ module ROM
       #
       # @api private
       module Associates
+        class MissingJoinKeysError < StandardError
+          ERROR_TEMPLATE = ':%{command} command for :%{relation} relation ' \
+                           'is missing join keys configuration for :%{name} association'
+
+          def initialize(command, assoc_name)
+            super(ERROR_TEMPLATE % tokens(command, assoc_name))
+          end
+
+          def tokens(command, assoc_name)
+            { command: command.register_as,
+              relation: command.relation,
+              name: assoc_name }
+          end
+        end
+
         # @api private
         def self.included(klass)
           klass.class_eval do
@@ -55,6 +70,8 @@ module ROM
                   assoc.associate(relation.__registry__, tuple, parent)
                 }
               end
+
+            one? ? input_tuples[0] : input_tuples
           end
 
           # @api public
@@ -115,6 +132,10 @@ module ROM
               end
             end
 
+            [*before_hooks, *after_hooks].
+              map { |hook| hook[:associate] }.
+              each { |conf| raise MissingJoinKeysError.new(self, conf[:assoc]) unless conf[:keys] }
+
             command.
               with_opts(configured_associations: assoc_names).
               before(*before_hooks).

data/lib/rom/sql/plugin/timestamps.rb

@@ -0,0 +1,131 @@
+require 'set'
+
+module ROM
+  module SQL
+    module Plugin
+      # Make a command that automatically fills in timestamp attributes on
+      # input tuples
+      #
+      # @api private
+      module Timestamps
+        # @api private
+        def self.included(klass)
+          klass.extend(ClassInterface)
+          super
+        end
+
+        module ClassInterface
+          # @api private
+          def self.extended(klass)
+            klass.defines :timestamp_columns, :datestamp_columns
+            klass.timestamp_columns Set.new
+            klass.datestamp_columns Set.new
+
+            super
+          end
+
+          # Set up attributes to timestamp when the command is called
+          #
+          # @example
+          #   class CreateTask < ROM::Commands::Create[:sql]
+          #     result :one
+          #     use :timestamps
+          #     timestamps :created_at, :updated_at
+          #   end
+          #
+          #   create_user = rom.command(:user).create.with(name: 'Jane')
+          #
+          #   result = create_user.call
+          #   result[:created_at]  #=> Time.now.utc
+          #
+          # @param [Symbol] name of the attribute to set
+          #
+          # @api public
+          def timestamps(*args)
+            timestamp_columns timestamp_columns.merge(args)
+
+            include InstanceMethods
+          end
+          alias timestamp timestamps
+
+          # Set up attributes to datestamp when the command is called
+          #
+          # @example
+          #   class CreateTask < ROM::Commands::Create[:sql]
+          #     result :one
+          #     use :timestamps
+          #     datestamps :created_on, :updated_on
+          #   end
+          #
+          #   create_user = rom.command(:user).create.with(name: 'Jane')
+          #
+          #   result = create_user.call
+          #   result[:created_at]  #=> Date.today
+          #
+          # @param [Symbol] name of the attribute to set
+          #
+          # @api public
+          def datestamps(*args)
+            datestamp_columns datestamp_columns.merge(args)
+
+            include InstanceMethods
+          end
+          alias datestamp datestamps
+        end
+
+        module InstanceMethods
+          # @api private
+          def self.included(base)
+            base.before :set_timestamps
+          end
+
+          # @api private
+          def timestamp_columns
+            self.class.timestamp_columns
+          end
+
+          # @api private
+          def datestamp_columns
+            self.class.datestamp_columns
+          end
+
+          # Set the timestamp attributes on the given tuples
+          #
+          # @param [Array<Hash>, Hash] tuples the input tuple(s)
+          #
+          # @return [Array<Hash>, Hash]
+          #
+          # @api private
+          def set_timestamps(tuples)
+            timestamps = build_timestamps
+
+            case tuples
+            when Hash
+              timestamps.merge(tuples)
+            when Array
+              tuples.map { |t| timestamps.merge(t) }
+            end
+          end
+
+          private
+
+          # @api private
+          def build_timestamps
+            time        = Time.now.utc
+            date        = Date.today
+            timestamps  = {}
+            timestamp_columns.each do |column|
+              timestamps[column.to_sym] = time
+            end
+
+            datestamp_columns.each do |column|
+              timestamps[column.to_sym] = date
+            end
+
+            timestamps
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rom/sql/plugins.rb

@@ -1,9 +1,12 @@
 require 'rom/sql/plugin/associates'
 require 'rom/sql/plugin/pagination'
+require 'rom/sql/plugin/timestamps'
 
 ROM.plugins do
   adapter :sql do
     register :pagination, ROM::SQL::Plugin::Pagination, type: :relation
     register :associates, ROM::SQL::Plugin::Associates, type: :command
+
+    register :timestamps, ROM::SQL::Plugin::Timestamps, type: :command
   end
 end

data/lib/rom/sql/projection_dsl.rb

@@ -3,6 +3,7 @@ require 'rom/sql/function'
 
 module ROM
   module SQL
+    # @api private
     class ProjectionDSL < DSL
       # @api private
       def respond_to_missing?(name, include_private = false)

data/lib/rom/sql/relation/reading.rb

@@ -83,7 +83,8 @@ module ROM
         # This method is intended to be used internally within a relation object
         #
         # @example
-        #   users.qualified
+        #   users.qualified.dataset.sql
+        #   # SELECT "users"."id", "users"."name" ...
         #
         # @return [Relation]
         #
@@ -141,22 +142,6 @@ module ROM
           map(name)
         end
 
-        # Project a relation
-        #
-        # This method is intended to be used internally within a relation object
-        #
-        # @example
-        #   users.project(:id, :name) }
-        #
-        # @param [Symbol] *names A list of symbol column names
-        #
-        # @return [Relation]
-        #
-        # @api public
-        def project(*names)
-          schema.project(*names).(self)
-        end
-
         # Rename columns in a relation
         #
         # This method is intended to be used internally within a relation object
@@ -176,9 +161,53 @@ module ROM
 
         # Select specific columns for select clause
         #
-        # @example
-        #   users.select(:id, :name).first
-        #   # {:id => 1, :name => "Jane" }
+        # @overload select(*columns)
+        #   Project relation using column names
+        #
+        #   @example using column names
+        #     users.select(:id, :name).first
+        #     # {:id => 1, :name => "Jane"}
+        #
+        #   @param [Array<Symbol>] columns A list of column names
+        #
+        # @overload select(*attributes)
+        #   Project relation using schema attributes
+        #
+        #   @example using attributes
+        #     users.select(:id, :name).first
+        #     # {:id => 1, :name => "Jane"}
+        #
+        #   @example using schema
+        #     users.select(*schema.project(:id)).first
+        #     # {:id => 1}
+        #
+        #   @param [Array<SQL::Attribute>] columns A list of schema attributes
+        #
+        # @overload select(&block)
+        #   Project relation using projection DSL
+        #
+        #   @example using attributes
+        #     users.select { id.as(:user_id) }
+        #     # {:user_id => 1}
+        #
+        #     users.select { [id, name] }
+        #     # {:id => 1, :name => "Jane"}
+        #
+        #   @example using SQL functions
+        #     users.select { string::concat(id, '-', name).as(:uid) }.first
+        #     # {:uid => "1-Jane"}
+        #
+        # @overload select(*columns, &block)
+        #   Project relation using column names and projection DSL
+        #
+        #   @example using attributes
+        #     users.select(:id) { int::count(id).as(:count) }.group(:id).first
+        #     # {:id => 1, :count => 1}
+        #
+        #     users.select { [id, name] }
+        #     # {:id => 1, :name => "Jane"}
+        #
+        #   @param [Array<SQL::Attribute>] columns A list of schema attributes
         #
         # @return [Relation]
         #
@@ -186,14 +215,11 @@ module ROM
         def select(*args, &block)
           schema.project(*args, &block).(self)
         end
+        alias_method :project, :select
 
         # Append specific columns to select clause
         #
-        # @example
-        #   users.select(:id, :name).select_append(:email)
-        #   # {:id => 1, :name => "Jane", :email => "jane@doe.org"}
-        #
-        # @param [Array<Symbol>] *args A list with column names
+        # @see Relation#select
         #
         # @return [Relation]
         #
@@ -204,10 +230,20 @@ module ROM
 
         # Returns a copy of the relation with a SQL DISTINCT clause.
         #
-        # @example
-        #   users.distinct(:country)
+        # @overload distinct(*columns)
+        #   Create a distinct statement from column names
         #
-        # @param [Array<Symbol>] *args A list with column names
+        #   @example
+        #     users.distinct(:country)
+        #
+        #   @param [Array<Symbol>] columns A list with column names
+        #
+        # @overload distinct(&block)
+        #   Create a distinct statement from a block
+        #
+        #   @example
+        #     users.distinct { func(id) }
+        #     # SELECT DISTINCT ON (count("id")) "id" ...
         #
         # @return [Relation]
         #
@@ -274,19 +310,30 @@ module ROM
 
         # Restrict a relation to match criteria
         #
-        # If block is passed it'll be executed in the context of a condition
-        # builder object.
+        # @overload where(conditions)
+        #   Restrict a relation using a hash with conditions
         #
-        # @example
-        #   users.where(name: 'Jane')
+        #   @example
+        #     users.where(name: 'Jane', age: 30)
         #
-        #   users.where { age >= 18 }
+        #   @param [Hash] conditions A hash with conditions
         #
-        # @param [Hash] *args An optional hash with conditions for WHERE clause
+        # @overload where(conditions, &block)
+        #   Restrict a relation using a hash with conditions and restriction DSL
         #
-        # @return [Relation]
+        #   @example
+        #     users.where(name: 'Jane') { age > 18 }
+        #
+        #   @param [Hash] conditions A hash with conditions
+        #
+        # @overload where(&block)
+        #   Restrict a relation using restriction DSL
         #
-        # @see http://sequel.jeremyevans.net/rdoc/files/doc/dataset_filtering_rdoc.html
+        #   @example
+        #     users.where { age > 18 }
+        #     users.where { (id < 10) | (id > 20) }
+        #
+        # @return [Relation]
         #
         # @api public
         def where(*args, &block)
@@ -313,17 +360,36 @@ module ROM
 
         # Restrict a relation to match grouping criteria
         #
-        # @example
-        #   users.with_task_count.having( task_count: 2 )
-        #
-        #   users.with_task_count.having { task_count > 3 }
-        #
-        # @param [Hash] *args An optional hash with conditions for HAVING clause
+        # @overload having(conditions)
+        #   Return a new relation with having clause from conditions hash
+        #
+        #   @example
+        #     users.
+        #       qualified.
+        #       left_join(tasks).
+        #       select { [id, name, int::count(:tasks__id).as(:task_count)] }.
+        #       group(users[:id].qualified).
+        #       having(task_count: 2)
+        #       first
+        #     # {:id => 1, :name => "Jane", :task_count => 2}
+        #
+        #   @param [Hash] conditions A hash with conditions
+        #
+        # @overload having(&block)
+        #   Return a new relation with having clause created from restriction DSL
+        #
+        #   @example
+        #     users.
+        #       qualified.
+        #       left_join(tasks).
+        #       select { [id, name, int::count(:tasks__id).as(:task_count)] }.
+        #       group(users[:id].qualified).
+        #       having { count(id.qualified) >= 1 }.
+        #       first
+        #     # {:id => 1, :name => "Jane", :task_count => 2}
         #
         # @return [Relation]
         #
-        # @see http://sequel.jeremyevans.net/rdoc/files/doc/dataset_filtering_rdoc.html
-        #
         # @api public
         def having(*args, &block)
           if block
@@ -351,11 +417,31 @@ module ROM
 
         # Set order for the relation
         #
-        # @example
-        #   users.order(:name)
-        #   users.order { [name.desc, id.qualified.desc]}
+        # @overload order(*columns)
+        #   Return a new relation ordered by provided columns (ASC by default)
         #
-        # @param [Array<Symbol>] *args A list with column names
+        #   @example
+        #     users.order(:name, :id)
+        #
+        #   @param [Array<Symbol>] columns A list with column names
+        #
+        # @overload order(*attributes)
+        #   Return a new relation ordered by provided schema attributes
+        #
+        #   @example
+        #     users.order(self[:name].qualified.desc, self[:id].qualified.desc)
+        #
+        #   @param [Array<SQL::Attribute>] attributes A list with schema attributes
+        #
+        # @overload order(&block)
+        #   Return a new relation ordered using order DSL
+        #
+        #   @example using attribute
+        #     users.order { id.desc }
+        #     users.order { price.desc(nulls: :first) }
+        #
+        #   @example using a function
+        #     users.order { nullif(name.qualified, `''`).desc(nulls: :first) }
         #
         # @return [Relation]
         #
@@ -382,19 +468,28 @@ module ROM
 
         # Limit a relation to a specific number of tuples
         #
-        # @example
-        #   users.limit(1)
+        # @overload limit(num)
+        #   Return a new relation with the limit set to the provided num
+        #
+        #   @example
+        #     users.limit(1)
+        #
+        #   @param [Integer] num The limit value
         #
-        #   users.limit(10, 2)
+        # @overload limit(num, offset)
+        #   Return a new relation with the limit set to the provided num
         #
-        # @param [Integer] limit The limit value
-        # @param [Integer] offset An optional offset
+        #   @example
+        #     users.limit(10, 2)
+        #
+        #   @param [Integer] num The limit value
+        #   @param [Integer] offset The offset value
         #
         # @return [Relation]
         #
         # @api public
-        def limit(*args, &block)
-          new(dataset.__send__(__method__, *args, &block))
+        def limit(*args)
+          new(dataset.__send__(__method__, *args))
         end
 
         # Set offset for the relation
@@ -407,17 +502,41 @@ module ROM
         # @return [Relation]
         #
         # @api public
-        def offset(*args, &block)
-          new(dataset.__send__(__method__, *args, &block))
+        def offset(num)
+          new(dataset.__send__(__method__, num))
         end
 
         # Join with another relation using INNER JOIN
         #
-        # @example
-        #   users.inner_join(:tasks, id: :user_id)
+        # @overload join(dataset, join_conditions)
+        #   Join with another relation using dataset name and join conditions
+        #
+        #   @example
+        #     users.join(:tasks, id: :user_id)
+        #
+        #   @param [Symbol] dataset Join table name
+        #   @param [Hash] join_conditions A hash with join conditions
+        #
+        # @overload join(dataset, join_conditions, options)
+        #   Join with another relation using dataset name and join conditions
+        #   with additional join options
+        #
+        #   @example
+        #     users.join(:tasks, { id: :user_id }, { table_alias: :tasks_1 })
+        #
+        #   @param [Symbol] dataset Join table name
+        #   @param [Hash] join_conditions A hash with join conditions
+        #   @param [Hash] options Additional join options
         #
-        # @param [Symbol] relation name
-        # @param [Hash] join keys
+        # @overload join(relation)
+        #   Join with another relation
+        #
+        #   Join conditions are automatically set based on schema association
+        #
+        #   @example
+        #     users.join(tasks)
+        #
+        #   @param [Relation] relation A relation for join
         #
         # @return [Relation]
         #
@@ -427,13 +546,37 @@ module ROM
         end
         alias_method :inner_join, :join
 
-        # Join other relation using LEFT OUTER JOIN
+        # Join with another relation using LEFT OUTER JOIN
         #
-        # @example
-        #   users.left_join(:tasks, id: :user_id)
+        # @overload left_join(dataset, left_join_conditions)
+        #   Left_Join with another relation using dataset name and left_join conditions
+        #
+        #   @example
+        #     users.left_join(:tasks, id: :user_id)
+        #
+        #   @param [Symbol] dataset Left_Join table name
+        #   @param [Hash] left_join_conditions A hash with left_join conditions
         #
-        # @param [Symbol] relation name
-        # @param [Hash] join keys
+        # @overload left_join(dataset, left_join_conditions, options)
+        #   Left_Join with another relation using dataset name and left_join conditions
+        #   with additional left_join options
+        #
+        #   @example
+        #     users.left_join(:tasks, { id: :user_id }, { table_alias: :tasks_1 })
+        #
+        #   @param [Symbol] dataset Left_Join table name
+        #   @param [Hash] left_join_conditions A hash with left_join conditions
+        #   @param [Hash] options Additional left_join options
+        #
+        # @overload left_join(relation)
+        #   Left_Join with another relation
+        #
+        #   Left_Join conditions are automatically set based on schema association
+        #
+        #   @example
+        #     users.left_join(tasks)
+        #
+        #   @param [Relation] relation A relation for left_join
         #
         # @return [Relation]
         #
@@ -442,14 +585,37 @@ module ROM
           __join__(__method__, *args, &block)
         end
 
-        # Join other relation using RIGHT JOIN
+        # Join with another relation using RIGHT JOIN
         #
-        # @example
-        #   users.right_join(:tasks, id: :user_id)
-        #   users.right_join(tasks)
+        # @overload right_join(dataset, right_join_conditions)
+        #   Right_Join with another relation using dataset name and right_join conditions
+        #
+        #   @example
+        #     users.right_join(:tasks, id: :user_id)
+        #
+        #   @param [Symbol] dataset Right_Join table name
+        #   @param [Hash] right_join_conditions A hash with right_join conditions
+        #
+        # @overload right_join(dataset, right_join_conditions, options)
+        #   Right_Join with another relation using dataset name and right_join conditions
+        #   with additional right_join options
+        #
+        #   @example
+        #     users.right_join(:tasks, { id: :user_id }, { table_alias: :tasks_1 })
+        #
+        #   @param [Symbol] dataset Right_Join table name
+        #   @param [Hash] right_join_conditions A hash with right_join conditions
+        #   @param [Hash] options Additional right_join options
         #
-        # @param [Symbol] relation name
-        # @param [Hash] join keys
+        # @overload right_join(relation)
+        #   Right_Join with another relation
+        #
+        #   Right_Join conditions are automatically set based on schema association
+        #
+        #   @example
+        #     users.right_join(tasks)
+        #
+        #   @param [Relation] relation A relation for right_join
         #
         # @return [Relation]
         #
@@ -460,10 +626,21 @@ module ROM
 
         # Group by specific columns
         #
-        # @example
-        #   tasks.group(:user_id)
+        # @overload group(*columns)
+        #   Return a new relation grouped by provided columns
         #
-        # @param [Array<Symbol>] *args A list of column names
+        #   @example
+        #     tasks.group(:user_id)
+        #
+        #   @param [Array<Symbol>] columns A list with column names
+        #
+        # @overload group(*attributes)
+        #   Return a new relation grouped by provided schema attributes
+        #
+        #   @example
+        #     tasks.group(tasks[:id], tasks[:title])
+        #
+        #   @param [Array<SQL::Attribute>] columns A list with column names
         #
         # @return [Relation]
         #
@@ -557,6 +734,8 @@ module ROM
 
         private
 
+        # Common join method used by other join methods
+        #
         # @api private
         def __join__(type, other, join_cond = EMPTY_HASH, opts = EMPTY_HASH, &block)
           case other
@@ -569,6 +748,8 @@ module ROM
           end
         end
 
+        # Return join key conditions for the provided relation
+        #
         # @api private
         def join_keys(other)
           other.associations[name].join_keys(__registry__)