rom-rails 0.3.0.beta1 → 0.3.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dca5938e41a98dc3af6fe2aa5d301c13a6984d04
-  data.tar.gz: 372f0581874750544b013ff63048ff60ee69085b
+  metadata.gz: 2f534a7630fb69accef529f372f2b211f35c7985
+  data.tar.gz: c530fd02f02046a61e6f86173f8ba28ef6820474
 SHA512:
-  metadata.gz: d0b26883fb509ab4ff4a39294b84d90436bd73c736e653f16ad90b4fb89c8fe6949590ac3f5f1513f0da752291ed96e6d69fb26fd164e47ba22b6a6cff400e94
-  data.tar.gz: d5fe5b5a9c13523bd2d53c5c193402de75e963edce3a79c6a815eff1c8a2f03010af8520cce4f037850a100dcccd96ba7cc1a692d6fd71bbd80fcc531f3c5ba0
+  metadata.gz: 5e70baa4ab07025be46b4f6ff1e19fad7830150298fa90de2e8fcd5f87cba06967057d48e3b3c6b6ecdd35ef6305cf9770db853aa0c24f8f49150f2a6725b902
+  data.tar.gz: 6b31f9a2aff08f7a4747bb045061f5f3658bfeff2d204abc0981ebea5d4a27094798b7bacc2ebf126690669b7ea40517f140b6341e28f1bdbec6647f2c5b5d5a

data/CHANGELOG.md

@@ -5,9 +5,9 @@
 * `ROM::Model::Form` for modeling and setting up web-forms (solnic + cflipse)
 * Support for timestamps attributes in Form objects (kchien)
 
-
 ### Changed
 
+* [BREAKING] Model::Params renamed to Model::Attributes (solnic)
 * Improved initialization process which works with AR-style configurations (aflatter)
 * Allow setup using a configuration block from railtie (aflatter)
 

data/lib/generators/rom/form/templates/edit_form.rb.erb

@@ -18,7 +18,7 @@ class Edit<%= model_name %>Form < ROM::Model::Form
   end
 
   def commit!
-    <%= relation %>.try { <%= relation %>.update.by_id(id).set(params) }
+    <%= relation %>.try { <%= relation %>.update.by_id(id).set(attributes) }
   end
 
 end

data/lib/generators/rom/form/templates/new_form.rb.erb

@@ -18,7 +18,7 @@ class New<%= model_name %>Form < ROM::Model::Form
   end
 
   def commit!
-    <%= relation %>.try { <%= relation %>.create.call(params) }
+    <%= relation %>.try { <%= relation %>.create.call(attributes) }
   end
 
 end

data/lib/generators/rom/mapper/templates/mapper.rb.erb

@@ -1,6 +1,6 @@
 class <%= model_name %>Mapper < ROM::Mapper
-  # relation :<%= relation %>
-  #
+  relation :<%= relation %>
+
   # specify model and attributes ie
   #
   # model <%= model_name %>

data/lib/rom/model.rb

@@ -9,6 +9,6 @@ module ROM
   end
 end
 
-require 'rom/rails/model/params'
+require 'rom/rails/model/attributes'
 require 'rom/rails/model/validator'
 require 'rom/rails/model/form'

data/lib/rom/rails/controller_extension.rb

@@ -3,44 +3,9 @@ module ROM
     RelationParamsMissingError = Class.new(StandardError)
 
     module ControllerExtension
-      def self.included(klass)
-        klass.extend(ClassExtensions)
-      end
-
       def rom
         ROM.env
       end
-
-      module ClassExtensions
-        def relation(path, options)
-          root, method = path.split('.').map(&:to_sym)
-
-          name = options.fetch(:as) { root }
-          requires = Array(options.fetch(:requires) { [] })
-
-          before_filter(options.except(:as, :requires)) do
-            args = params.values_at(*requires)
-
-            if requires.any? && args.none?
-              raise RelationParamsMissingError
-            else
-              relation =
-                if args.any?
-                  rom.read(root).send(method, *args)
-                else
-                  rom.read(root).send(method)
-                end
-
-              instance_variable_set("@#{name}", relation.to_a)
-            end
-          end
-
-          unless respond_to?(name)
-            attr_reader name
-            helper_method name
-          end
-        end
-      end
     end
   end
 end

data/lib/rom/rails/model/attributes.rb

@@ -0,0 +1,133 @@
+require 'virtus'
+require 'active_model/conversion'
+
+module ROM
+  module Model
+    # Mixin for validatable and coercible parameters
+    #
+    # @example
+    #
+    #   class UserAttributes
+    #     include ROM::Model::Attributes
+    #
+    #     attribute :email, String
+    #     attribute :age, Integer
+    #
+    #     validates :email, :age, presence: true
+    #   end
+    #
+    #   user_attrs = UserAttributes.new(email: '', age: '18')
+    #
+    #   user_attrs.email # => ''
+    #   user_attrs.age # => 18
+    #
+    #   user_attrs.valid? # => false
+    #   user_attrs.errors # => #<ActiveModel::Errors:0x007fd2423fadb0 ...>
+    #
+    # @api public
+    module Attributes
+      VirtusModel = Virtus.model(nullify_blank: true)
+
+      # Inclusion hook used to extend a class with required interfaces
+      #
+      # @api private
+      def self.included(base)
+        base.class_eval do
+          include VirtusModel
+          include ActiveModel::Conversion
+        end
+        base.extend(ClassMethods)
+      end
+
+      # Return model name for the attributes class
+      #
+      # The model name object is configurable using `set_model_name` macro
+      #
+      # @see ClassMethods#set_model_name
+      #
+      # @return [ActiveModel::Name]
+      #
+      # @api public
+      def model_name
+        self.class.model_name
+      end
+
+      # Class extensions for an attributes class
+      #
+      # @api public
+      module ClassMethods
+        # Default timestamp attribute names used by `timestamps` method
+        DEFAULT_TIMESTAMPS = [:created_at, :updated_at].freeze
+
+        # Process input and return attributes instance
+        #
+        # @example
+        #   class UserAttributes
+        #     include ROM::Model::Attributes
+        #
+        #     attribute :name, String
+        #   end
+        #
+        #   UserAttributes[name: 'Jane']
+        #
+        # @param [Hash,#to_hash] input The input params
+        #
+        # @return [Attributes]
+        #
+        # @api public
+        def [](input)
+          input.is_a?(self) ? input : new(input)
+        end
+
+        # Macro for defining ActiveModel::Name object on the attributes class
+        #
+        # This is essential for rails helpers to work properly when generating
+        # form input names etc.
+        #
+        # @example
+        #   class UserAttributes
+        #     include ROM::Model::Attributes
+        #
+        #     set_model_name 'User'
+        #   end
+        #
+        # @return [undefined]
+        #
+        # @api public
+        def set_model_name(name)
+          class_eval <<-RUBY
+            def self.model_name
+              @model_name ||= ActiveModel::Name.new(self, nil, #{name.inspect})
+            end
+          RUBY
+        end
+
+        # Shortcut for defining timestamp attributes like created_at etc.
+        #
+        # @example
+        #   class NewPostAttributes
+        #     include ROM::Model::Attributes
+        #
+        #     # provide name(s) explicitly
+        #     timestamps :published_at
+        #
+        #     # defaults to :created_at, :updated_at without args
+        #     timestamps
+        #   end
+        #
+        # @api public
+        def timestamps(*attrs)
+          if attrs.empty?
+            DEFAULT_TIMESTAMPS.each do |t|
+              attribute t, DateTime, default: proc { DateTime.now }
+            end
+          else
+            attrs.each do |attr|
+              attribute attr, DateTime, default: proc { DateTime.now }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rom/rails/model/form.rb

@@ -1,24 +1,85 @@
-require 'rom/rails/model/form/dsl'
+require 'rom/rails/model/form/class_interface'
 
 module ROM
   module Model
+    # Abstract form class
+    #
+    # Form objects in ROM are your top-level interface to persist data in the
+    # database. They combine many features that you know from ActiveRecord:
+    #
+    #   * params processing with sanitization and coercion
+    #   * attribute validations
+    #   * persisting data in the database
+    #
+    # The major difference is that a ROM form object separates those
+    # responsibilities - a ROM form class has its own Attributes, Validator and
+    # ROM commands that are accessible within its instance.
+    #
+    # @example
+    #   class UserForm < ROM::Model::Form
+    #     commands users: :create
+    #
+    #     input do
+    #       set_model_name 'User'
+    #
+    #       attribute :name, String
+    #     end
+    #
+    #     validations do
+    #       validates :name, presence: true
+    #     end
+    #   end
+    #
+    #   class CreateUserForm < UserForm
+    #     attributes.timestamps :created_at
+    #
+    #     def commit!
+    #       users.try { users.create.call(attributes) }
+    #     end
+    #   end
+    #
+    #   # then in your controller
+    #   CreateUserForm.build(params[:user]).save
+    #
+    # @api public
     class Form
       include Equalizer.new(:params, :model, :result)
 
       extend ROM::ClassMacros
-      extend Form::DSL
+      extend Form::ClassInterface
 
       defines :relation
 
-      attr_reader :params, :model, :result
+      # Return raw params received from the request
+      #
+      # @return [Object]
+      #
+      # @api public
+      attr_reader :params
+
+      # Return model instance representing an ActiveModel object that will be
+      # persisted or updated
+      #
+      # @return [Object]
+      #
+      # @api public
+      attr_reader :model
+
+      # Return the result of commit!
+      #
+      # @return [Object]
+      #
+      # @api public
+      attr_reader :result
 
       delegate :model_name, :persisted?, :to_key, to: :model
       alias_method :to_model, :model
 
       class << self
-        delegate :model_name, to: :params
+        delegate :model_name, to: :attributes
       end
 
+      # @api private
       def initialize(params = {}, options = {})
         @params = params
         @model  = self.class.model.new(params.merge(options.slice(*self.class.key)))
@@ -27,19 +88,37 @@ module ROM
         options.each { |key, value| instance_variable_set("@#{key}", value) }
       end
 
+      # A specialized form object must implement this method
+      #
+      # @abstract
+      #
+      # @api public
       def commit!
         raise NotImplementedError, "#{self.class}#commit! must be implemented"
       end
 
+      # Save a form by calling commit! and memoizing result
+      #
+      # @return [self]
+      #
+      # @api public
       def save(*args)
         @result = commit!(*args)
         self
       end
 
+      # Return whether commit was successful
+      #
+      # @return [TrueClass,FalseClass]
+      #
+      # @api public
       def success?
         errors.nil? || !errors.any?
       end
 
+      # Trigger validation and store errors (if any)
+      #
+      # @api public
       def validate!
         validator = self.class::Validator.new(attributes)
         validator.validate
@@ -47,10 +126,22 @@ module ROM
         @errors = validator.errors
       end
 
+      # Sanitize and coerce input params
+      #
+      # This can also set default values
+      #
+      # @return [Model::Attributes]
+      #
+      # @api public
       def attributes
-        self.class.params[params]
+        self.class.attributes[params]
       end
 
+      # Return errors
+      #
+      # @return [ActiveModel::Errors]
+      #
+      # @api public
       def errors
         (result && result.error) || @errors
       end

data/lib/rom/rails/model/form/class_interface.rb

@@ -0,0 +1,401 @@
+module ROM
+  module Model
+    class Form
+      module ClassInterface
+        # Return param handler class
+        #
+        # This class is used to process input params coming from a request and
+        # it's being created using `input` API
+        #
+        # @example
+        #
+        #   class MyForm < ROM::Model::Form
+        #     input do
+        #       attribute :name, String
+        #     end
+        #   end
+        #
+        #   MyForm.attributes # => MyForm::Attributes
+        #
+        #   # process input params
+        #   attributes = MyForm.attributes[name: 'Jane']
+        #
+        # @return [Class]
+        #
+        # @api public
+        attr_reader :attributes
+
+        # Return attributes validator
+        #
+        # @example
+        #   class MyForm < ROM::Model::Form
+        #     input do
+        #       attribute :name, String
+        #     end
+        #
+        #     validations do
+        #       validates :name, presence: true
+        #     end
+        #   end
+        #
+        #   attributes = MyForm.attributes[name: nil]
+        #   MyForm::Validator.call(attributes) # raises validation error
+        #
+        # @return [Class]
+        #
+        # @api public
+        attr_reader :validator
+
+        # Return model class
+        #
+        # @return [Class]
+        #
+        # @api public
+        attr_reader :model
+
+        # relation => command name mapping used to generate commands automatically
+        #
+        # @return [Hash]
+        #
+        # @api private
+        attr_reader :self_commands
+
+        # A list of relation names for which commands should be injected from
+        # the rom env automatically.
+        #
+        # This is used only when a given form re-uses existing commands
+        #
+        # @return [Hash]
+        #
+        # @api private
+        attr_reader :injectible_commands
+
+        # input block stored to be used in inherited hook
+        #
+        # @return [Proc]
+        #
+        # @api private
+        attr_reader :input_block
+
+        # validation block stored to be used in inherited hook
+        #
+        # @return [Proc]
+        #
+        # @api private
+        attr_reader :validations_block
+
+        # Copy input attributes, validator and model to the descendant
+        #
+        # @api private
+        def inherited(klass)
+          klass.inject_commands_for(*injectible_commands) if injectible_commands
+          klass.commands(*self_commands) if self_commands
+          klass.input(readers: false, &input_block) if input_block
+          klass.validations(&validations_block) if validations_block
+          super
+        end
+
+        # Set key for the model that is handled by a form object
+        #
+        # This defaults to [:id]
+        #
+        # @example
+        #   class MyForm < ROM::Model::Form
+        #     key [:user_id]
+        #   end
+        #
+        # @return [Array<Symbol>]
+        #
+        # @api public
+        def key(*keys)
+          if keys.any? && !@key
+            @key = keys
+            attr_reader(*keys)
+          elsif !@key
+            @key = [:id]
+            attr_reader :id
+          elsif keys.any?
+            @key = keys
+          end
+          @key
+        end
+
+        # Specify what commands should be generated for a form object
+        #
+        # @example
+        #   class MyForm < ROM::Model::Form
+        #     commands users: :create
+        #   end
+        #
+        # @param [Hash] relation => command name map
+        #
+        # @return [self]
+        #
+        # @api public
+        def commands(names)
+          names.each { |relation, _action| attr_reader(relation) }
+          @self_commands = names
+          self
+        end
+
+        # Specify input params handler class
+        #
+        # This uses Virtus DSL
+        #
+        # @example
+        #   class MyForm < ROM::Model::Form
+        #     input do
+        #       set_model_name 'User'
+        #
+        #       attribute :name, String
+        #       attribute :age, Integer
+        #     end
+        #   end
+        #
+        #   MyForm.build(name: 'Jane', age: 21).attributes
+        #   # => #<MyForm::Attributes:0x007f821f863d48 @name="Jane", @age=21>
+        #
+        # @return [self]
+        #
+        # @api public
+        def input(options = {}, &block)
+          readers = options.fetch(:readers) { true }
+          define_attributes!(block)
+          define_attribute_readers! if readers
+          define_model!
+          self
+        end
+
+        # Specify attribute validator class
+        #
+        # This uses ActiveModel::Validations DSL
+        #
+        # @example
+        #   class MyForm < ROM::Model::Form
+        #     input do
+        #       set_model_name 'User'
+        #
+        #       attribute :name, String
+        #       attribute :age, Integer
+        #     end
+        #
+        #     validations do
+        #       validates :name, :age, presence: true
+        #     end
+        #   end
+        #
+        #   form = MyForm.build(name: 'Jane', age: nil)
+        #   # => #<MyForm::Attributes:0x007f821f863d48 @name="Jane", @age=21>
+        #   form.validate! # raises
+        #
+        # @return [self]
+        #
+        # @api public
+        def validations(&block)
+          define_validator!(block)
+          self
+        end
+
+        # Inject specific commands from the rom env
+        #
+        # This can be used when the env has re-usable commands
+        #
+        # @example
+        #   class MyForm < ROM::Model::Form
+        #     inject_commands_for :users
+        #   end
+        #
+        # @api public
+        def inject_commands_for(*names)
+          @injectible_commands = names
+          names.each { |name| attr_reader(name) }
+          self
+        end
+
+        # Build a form object using input params and options
+        #
+        # @example
+        #   class MyForm < ROM::Model::Form
+        #     input do
+        #       set_model_name 'User'
+        #
+        #       attribute :name, String
+        #       attribute :age, Integer
+        #     end
+        #   end
+        #
+        #   # form for a new object
+        #   form = MyForm.build(name: 'Jane')
+        #
+        #   # form for a persisted object
+        #   form = MyForm.build({ name: 'Jane' }, id: 1)
+        #
+        # @return [Model::Form]
+        #
+        # @api public
+        def build(input = {}, options = {})
+          new(input, options.merge(command_registry))
+        end
+
+        private
+
+        # @return [Hash<Symbol=>ROM::CommandRegistry>]
+        #
+        # @api private
+        def command_registry
+          @command_registry ||= setup_command_registry
+        end
+
+        # Create attribute handler class
+        #
+        # @return [Class]
+        #
+        # @api private
+        def define_attributes!(block)
+          @input_block = block
+          @attributes = ClassBuilder.new(name: "#{name}::Attributes", parent: Object).call { |klass|
+            klass.send(:include, ROM::Model::Attributes)
+          }
+          @attributes.class_eval(&block)
+          const_set(:Attributes, @attributes)
+        end
+
+        # Define attribute readers for the form
+        #
+        # This is very unfortunate but rails `form_for` and friends require
+        # the object to provide attribute values, hence we need to expose those
+        # using the form object itself.
+        #
+        # @return [Class]
+        #
+        # @api private
+        def define_attribute_readers!
+          @attributes.attribute_set.each do |attribute|
+            if public_instance_methods.include?(attribute.name)
+              raise(
+                ArgumentError,
+                "#{attribute.name} attribute is in conflict with #{self}##{attribute.name}"
+              )
+            end
+
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{attribute.name}
+                attributes[:#{attribute.name}]
+              end
+            RUBY
+          end
+        end
+
+        # Create model class
+        #
+        # Model instance represents an entity that will be persisted or was
+        # already persisted and will be updated.
+        #
+        # This object is returned via `Form#to_model` which rails uses internally
+        # in many places to figure out what to do.
+        #
+        # Model object provides two crucial pieces of information: whether or not
+        # something was persisted and its primary key value
+        #
+        # @return [Class]
+        #
+        # @api private
+        def define_model!
+          @model = ClassBuilder.new(name: "#{name}::Model", parent: @attributes).call { |klass|
+            klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def persisted?
+                to_key.any?
+              end
+
+              def to_key
+                to_h.values_at(#{key.map(&:inspect).join(', ')}).compact
+              end
+            RUBY
+          }
+          key.each { |name| @model.attribute(name) }
+          const_set(:Model, @model)
+        end
+
+        # Define attribute validator class
+        #
+        # @return [Class]
+        #
+        # @api private
+        def define_validator!(block)
+          @validations_block = block
+          @validator = ClassBuilder.new(name: "#{name}::Validator", parent: Object).call { |klass|
+            klass.send(:include, ROM::Model::Validator)
+          }
+          @validator.class_eval(&block)
+          const_set(:Validator, @validator)
+        end
+
+        # Shortcut to global ROM env
+        #
+        # @return [ROM::Env]
+        #
+        # @api private
+        def rom
+          ROM.env
+        end
+
+        # Return identifier of the default adapter
+        #
+        # TODO: we need an interface for that in ROM
+        #
+        # @return [Symbol]
+        #
+        # @api private
+        def adapter
+          ROM.adapters.keys.first
+        end
+
+        # Generate a command registry hash which will be auto-injected to a form
+        # object.
+        #
+        # @return [Hash<Symbol=>ROM::CommandRegistry>]
+        #
+        # @api private
+        def setup_command_registry
+          commands = {}
+
+          if self_commands
+            self_commands.each do |rel_name, name|
+              command = build_command(name, rel_name)
+              commands[rel_name] = CommandRegistry.new(name => command)
+            end
+          end
+
+          if injectible_commands
+            injectible_commands.each do |relation|
+              commands[relation] = rom.command(relation)
+            end
+          end
+
+          commands
+        end
+
+        # Build a command object with a specific name
+        #
+        # @param [Symbol] name The name of the command
+        # @param [Symbol] rel_name The name of the command's relation
+        #
+        # @return [ROM::Command]
+        #
+        # @api private
+        def build_command(name, rel_name)
+          klass = Command.build_class(name, rel_name, adapter: adapter)
+
+          klass.result :one
+          klass.validator @validator
+
+          relation = rom.relations[rel_name]
+          repository = rom.repositories[relation.repository]
+          repository.extend_command_class(klass, relation.dataset)
+
+          klass.build(relation)
+        end
+      end
+    end
+  end
+end