cuprum-rails 0.1.0 → 0.2.0

data/lib/cuprum/rails/responses/html/redirect_response.rb

@@ -5,13 +5,18 @@ require 'cuprum/rails/responses/html'
 module Cuprum::Rails::Responses::Html
   # Encapsulates an HTML response that redirects to a given path.
   class RedirectResponse
-    # @param path [String] The path or url to redirect to.
-    # @param status [Integer] The HTTP status of the response.
-    def initialize(path, status: 302)
+    # @param flash [Hash] the flash messages to set.
+    # @param path [String] the path or url to redirect to.
+    # @param status [Integer] the HTTP status of the response.
+    def initialize(path, flash: {}, status: 302)
+      @flash  = flash
       @path   = path
       @status = status
     end
 
+    # @return [Hash] the flash messages to set.
+    attr_reader :flash
+
     # @return [String] the path or url to redirect to.
     attr_reader :path
 
@@ -20,10 +25,20 @@ module Cuprum::Rails::Responses::Html
 
     # Calls the renderer's #redirect_to method with the path and status.
     #
-    # @param renderer [#redirect_to] The context for executing the response,
+    # @param renderer [#redirect_to] The tontext for executing the response,
     #   such as a Rails controller.
     def call(renderer)
+      assign_flash(renderer)
+
       renderer.redirect_to(path, status: status)
     end
+
+    private
+
+    def assign_flash(renderer)
+      flash.each do |key, value|
+        renderer.flash[key] = value
+      end
+    end
   end
 end

data/lib/cuprum/rails/responses/html/render_response.rb

@@ -5,12 +5,14 @@ require 'cuprum/rails/responses/html'
 module Cuprum::Rails::Responses::Html
   # Encapsulates an HTML response that renders a given template.
   class RenderResponse
-    # @param assigns [Hash] Variables to assign when rendering the template.
-    # @param layout [String] The layout to render.
-    # @param status [Integer] The HTTP status of the response.
-    # @param template [String, Symbol] The template to render.
-    def initialize(template, assigns: {}, layout: nil, status: 200)
+    # @param assigns [Hash] variables to assign when rendering the template.
+    # @param flash [Hash] the flash messages to set.
+    # @param layout [String] the layout to render.
+    # @param status [Integer] the HTTP status of the response.
+    # @param template [String, Symbol] the template to render.
+    def initialize(template, assigns: {}, flash: {}, layout: nil, status: 200)
       @assigns  = assigns
+      @flash    = flash
       @layout   = layout
       @status   = status
       @template = template
@@ -19,6 +21,9 @@ module Cuprum::Rails::Responses::Html
     # @return [Hash] variables to assign when rendering the template.
     attr_reader :assigns
 
+    # @return [Hash] the flash messages to set.
+    attr_reader :flash
+
     # @return [String] the layout to render.
     attr_reader :layout
 
@@ -33,6 +38,7 @@ module Cuprum::Rails::Responses::Html
     # @param renderer [#render] The context for executing the response, such as
     #   a Rails controller.
     def call(renderer)
+      assign_flash(renderer)
       assign_variables(renderer)
 
       options = { status: status }
@@ -43,6 +49,12 @@ module Cuprum::Rails::Responses::Html
 
     private
 
+    def assign_flash(renderer)
+      flash.each do |key, value|
+        renderer.flash.now[key] = value
+      end
+    end
+
     def assign_variables(renderer)
       assigns.each do |key, value|
         renderer.instance_variable_set("@#{key}", value)

data/lib/cuprum/rails/responses/html.rb

@@ -5,7 +5,11 @@ require 'cuprum/rails/responses'
 module Cuprum::Rails::Responses
   # Namespace for response objects, which encapsulate Html responses.
   module Html
-    autoload :RedirectResponse, 'cuprum/rails/responses/html/redirect_response'
-    autoload :RenderResponse,   'cuprum/rails/responses/html/render_response'
+    autoload :RedirectBackResponse,
+      'cuprum/rails/responses/html/redirect_back_response'
+    autoload :RedirectResponse,
+      'cuprum/rails/responses/html/redirect_response'
+    autoload :RenderResponse,
+      'cuprum/rails/responses/html/render_response'
   end
 end

data/lib/cuprum/rails/responses.rb

@@ -5,6 +5,7 @@ require 'cuprum/rails'
 module Cuprum::Rails
   # Namespace for response objects, which encapsulate server responses.
   module Responses
+    autoload :HeadResponse, 'cuprum/rails/responses/head_response'
     autoload :Html,         'cuprum/rails/responses/html'
     autoload :JsonResponse, 'cuprum/rails/responses/json_response'
   end

data/lib/cuprum/rails/result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'cuprum/rails'
+
+module Cuprum::Rails
+  # Result class representing the result of calling an action.
+  #
+  # In addition to the standard properties inherited from Cuprum::Result, each
+  # Cuprum::Rails::Result also includes a #metadata property. This represents
+  # secondary information about the result that may be relevant for rendering or
+  # displaying the data, but is not part of the requested value. For example.
+  # information about the current controller would be metadata, as would the
+  # current authentication session.
+  class Result < Cuprum::Result
+    # @param value [Object] the value returned by calling the action.
+    # @param error [Cuprum::Error] the error (if any) generated when the action
+    #   was called.
+    # @param metadata [Hash{Symbol => Object}] the request or action metadata.
+    # @param status [String, Symbol, nil] the status of the result. Must be
+    #   :success, :failure, or nil.
+    def initialize(error: nil, metadata: {}, status: nil, value: nil)
+      super(error: error, status: status, value: value)
+
+      @metadata = metadata
+    end
+
+    # @return [Hash{Symbol => Object}] the request or action metadata.
+    attr_reader :metadata
+
+    # @return [Hash{Symbol => Object}] a Hash representation of the result.
+    def properties
+      super().merge(metadata: metadata)
+    end
+    alias to_h properties
+  end
+end

data/lib/cuprum/rails/routes.rb

@@ -4,7 +4,7 @@ require 'cuprum/rails'
 
 module Cuprum::Rails
   # Represent the routes available for a given resource.
-  class Routes
+  class Routes # rubocop:disable Metrics/ClassLength
     # Error class when a wildcard value is missing for a route.
     class MissingWildcardError < StandardError; end
 
@@ -37,18 +37,18 @@ module Cuprum::Rails
       private
 
       def define_collection_route(action_name, original_path)
-        define_method :"#{action_name}_path" do
+        define_method :"#{action_name}_path" do |**wildcards|
           path = resolve_base_path(original_path)
 
-          insert_wildcards(path)
+          insert_wildcards(path, **wildcards)
         end
       end
 
       def define_member_route(action_name, original_path)
-        define_method :"#{action_name}_path" do |entity|
+        define_method :"#{action_name}_path" do |entity = nil, **wildcards|
           path = resolve_base_path(original_path)
 
-          insert_wildcards(path, entity)
+          insert_wildcards(path, entity, **wildcards)
         end
       end
 
@@ -75,10 +75,12 @@ module Cuprum::Rails
       end
     end
 
-    # @param base_path [String] The relative path of the resource.
-    def initialize(base_path:, &block)
-      @base_path = base_path
-      @wildcards = {}
+    # @param base_path [String] the relative path of the resource.
+    # @param parent_path [String] the path to the parent resource, if any.
+    def initialize(base_path:, parent_path: nil, &block)
+      @base_path   = base_path
+      @parent_path = parent_path
+      @wildcards   = {}
 
       singleton_class.instance_exec(&block) if block_given?
     end
@@ -91,7 +93,9 @@ module Cuprum::Rails
 
     # @return [String] the path to the parent resource index.
     def parent_path
-      root_path
+      return '/' if @parent_path.nil?
+
+      insert_wildcards(@parent_path)
     end
 
     # @return [String] the root path for the application.
@@ -120,15 +124,15 @@ module Cuprum::Rails
 
     private
 
-    def insert_wildcards(path, entity = nil)
+    def insert_wildcards(path, value_or_entity = nil, **wildcards)
+      wildcards = wildcards.merge('id' => value_or_entity) if value_or_entity
+
       path
         .split('/')
         .map do |segment|
           next segment unless segment.start_with?(':')
 
-          next resolve_primary_key(entity) if segment == ':id'
-
-          resolve_wildcard(segment)
+          resolve_wildcard(segment, **wildcards)
         end
         .join('/')
     end
@@ -141,24 +145,33 @@ module Cuprum::Rails
       "#{base_path}/#{path}"
     end
 
-    def resolve_primary_key(entity)
-      raise MissingWildcardError, 'missing wildcard :id' if entity.nil?
+    def resolve_primary_key(value_or_entity)
+      raise MissingWildcardError, 'missing wildcard :id' if value_or_entity.nil?
+
+      unless value_or_entity.class.respond_to?(:primary_key)
+        return value_or_entity
+      end
 
-      primary_key = entity.class.primary_key
+      primary_key = value_or_entity.class.primary_key
 
-      entity[primary_key]
+      value_or_entity[primary_key]
     end
 
-    def resolve_wildcard(segment)
+    def resolve_wildcard(segment, **wildcards)
+      wildcards = self.wildcards.merge(wildcards)
+      value     = wildcard_value(segment, **wildcards)
+
+      resolve_primary_key(value)
+    end
+
+    def wildcard_value(segment, **wildcards)
       wildcard = segment[1..] # :something_id to something_id
 
-      return wildcards[wildcard] if wildcards.include?(wildcard)
+      return wildcards[wildcard] if wildcards.key?(wildcard)
 
       wildcard = segment[1...-3] # :something_id to something
 
-      if wildcards.include?(wildcard)
-        return resolve_primary_key(wildcards[wildcard])
-      end
+      return wildcards[wildcard] if wildcards.key?(wildcard)
 
       raise MissingWildcardError, "missing wildcard #{segment}"
     end

data/lib/cuprum/rails/rspec/contract_helpers.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Cuprum::Rails::RSpec
+  # Helper methods for defining RSpec contracts.
+  module ContractHelpers
+    class << self
+      # Resolves a configuration option.
+      #
+      # If the configured value is a Proc, the Proc is executed in the context
+      # of the example group and the resulting value returned. Otherwise,
+      # returns the configured value, or the given default if the configured
+      # value is nil.
+      #
+      # @param value [Object] The configured value for the option.
+      # @param context [RSpec::SleepingKingStudios::ExampleGroup] The example
+      #   group used as a context if the configured value is a Proc.
+      # @param default [Object] An optional default value if the configured
+      #   value is nil.
+      def option_with_default(value, context:, default: nil)
+        # :nocov:
+        case value
+        when Proc
+          return context.instance_exec(&value) if value.arity.zero?
+
+          context.instance_exec(default, &value)
+        when nil
+          default
+        else
+          value
+        end
+        # :nocov:
+      end
+    end
+
+    # Resolves a configuration option.
+    #
+    # If the configured value is a Proc, the Proc is executed in the context of
+    # the example group and the resulting value returned. Otherwise, returns the
+    # configured value, or the given default if the configured value is nil.
+    #
+    # @param value [Object] The configured value for the option.
+    # @param context [RSpec::SleepingKingStudios::ExampleGroup] The example
+    #   group used as a context if the configured value is a Proc.
+    # @param default [Object] An optional default value if the configured value
+    #   is nil.
+    def option_with_default(value, context: nil, default: nil)
+      # :nocov:
+      Cuprum::Rails::RSpec::ContractHelpers
+        .option_with_default(
+          value,
+          context: context || self,
+          default: default
+        )
+      # :nocov:
+    end
+  end
+end