atacama 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5cf86d5c337258aa67e7c9f25dfe42a0bc82a913
-  data.tar.gz: a1f304895a629d1c13c9455536e853acd1e5371e
+  metadata.gz: 2d78853c9e718c4ea9ff6ea4fbc8e729cd2f48cf
+  data.tar.gz: addda9f05177a741fc8d2dd36d465646e37249c0
 SHA512:
-  metadata.gz: 78d72f1ee206d6b4f253531eef2ec3e1a4ad93c572fdbde98887ba74267542e269ef9c534a9d1fc2853a5ffe9148242002583aa0bca863d61d0a3a12b7ec6e1b
-  data.tar.gz: 5f2b0f9530c7b675930af229cd5577ffdf24c6addc3443c7db277fb1b0a3a3731ec7d95c7f1f509fce8aa7eac92d3cab5479ea46a517fdc66080264b43226fbb
+  metadata.gz: 88ca8a4083003137ca041c1b985cbe4f8046d5777c1b45fa75994fe7f435c5fddc9b8eb83344789bc6e0a10f925ca348e01dff8ae9c9361c560863f2d7a1d317
+  data.tar.gz: 1166397fca1f7348584534140b3edc31418384cb4cc9c4e3d7e735608f6000eab5028524e585b7c5a0db1dea90656b1d4041bf258e94f071d64820a855e8a914

data/.rubocop.yml

@@ -0,0 +1,84 @@
+AllCops:
+  TargetRubyVersion: 2.2
+  # RuboCop has a bunch of cops enabled by default. This setting tells RuboCop
+  # to ignore them, so only the ones explicitly set in this file are enabled.
+  Exclude:
+    - '**/bin/*'
+    - '**/db/**/*'
+    - '**/vendor/**/*'
+    - '**/node_modules/**/*'
+    - '**/*.gemspec'
+
+Bundler/OrderedGems:
+  Enabled: true
+
+Layout/IndentArray:
+  EnforcedStyle: consistent
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/LineLength:
+  Max: 100
+
+Metrics/ClassLength:
+  Max: 100
+  Exclude:
+    - '*/test/**/*'
+    - '*_test.rb'
+
+Metrics/MethodLength:
+  Max: 20
+
+Style/Documentation:
+  Enabled: false
+
+Style/Lambda:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false
+
+Style/DocumentationMethod:
+  Enabled: false
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: true
+  Exclude:
+    - '**/test/**/*'
+    - 'cli/*'
+
+Style/BracesAroundHashParameters:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: true
+  Exclude:
+    - '**/*_test.rb'
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Style/RescueModifier:
+  Enabled: false
+
+Style/GlobalVars:
+  Enabled: false
+
+Layout/IndentHash:
+  Enabled: false
+
+Naming/MethodName:
+  Enabled: false
+
+Lint/AssignmentInCondition:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atacama (0.1.6)
+    atacama (0.1.7)
       dry-types (~> 0.13.2)
 
 GEM

data/lib/atacama/contract/parameter.rb

@@ -12,14 +12,10 @@ module Atacama
 
     # Determine the validity of a value for an optionally given type. Raises a
     # type error on failure.
-    # @raise [Atacama::TypeError]
-    # @returns Boolean
-    def valid?(value)
-      return true if type.nil?
-      type[value]
-      true
-    rescue Dry::Types::ConstraintError => error
-      raise TypeError, error.message
+    #
+    # @raise [Dry::Types::ConstraintError]
+    def validate!(value)
+      type[value] && nil unless type.nil?
     end
   end
 end

data/lib/atacama/contract/validator.rb

@@ -9,9 +9,10 @@ module Atacama
 
     # @param options [Hash] options schema
     # @param context [Atacama::Context] keyword arguments to validate
-    def initialize(options:, context:)
+    def initialize(options:, context:, klass:)
       @options = options
       @context = context
+      @klass = klass
     end
 
     def call
@@ -20,12 +21,15 @@ module Atacama
 
     private
 
-    attr_reader :options, :context
+    attr_reader :options, :context, :klass
 
     def detect_invalid_types!
-      options.each do |(key, parameter)|
-        raise ArgumentError, "option not found: #{key}" unless context.key?(key)
-        parameter.valid? context[key]
+      options.each do |key, parameter|
+        begin
+          parameter.validate! context[key]
+        rescue Dry::Types::ConstraintError => e
+          raise OptionTypeMismatchError, %(#{klass} option :#{key} invalid: #{e.message})
+        end
       end
     end
   end

data/lib/atacama/contract.rb

@@ -8,63 +8,127 @@ require 'atacama/contract/context'
 module Atacama
   # This class enables a DSL for creating a contract for the initializer
   class Contract
+    # @private
     RESERVED_KEYS = %i[call initialize context].freeze
 
+    # Namespace alias for easier reading when defining types.
     Types = Atacama::Types
 
+    # @private
     NameInterface = Types::Strict::Symbol.constrained(excluded_from: RESERVED_KEYS)
+
+    # @private
     ContextInterface = Types::Strict::Hash | Types.Instance(Context)
 
     class << self
-      def injected=(hash)
-        @injected = Types::Strict::Hash[hash]
+      # Define an initializer value.
+      #
+      # @example Set an option
+      #   option :model. type: Types.Instance(User)
+      #
+      # @param name [Symbol] name of the argument
+      # @param type [Dry::Type?] the type object to optionally check
+      def option(name, type: nil)
+        options[NameInterface[name]] = Parameter.new(name: name, type: type)
+
+        define_method(name) { @context[name] }
+        define_method("#{name}?") { !!@context[name] }
       end
 
-      def injected
-        # Silences the VM warning about accessing uninitalized ivar
-        defined?(@injected) ? @injected : {}
+      # Set the return type for the contract. This is only validated automatically
+      # through the #call class method.
+      #
+      # @param type [Dry::Type?] the type object to optionally check
+      def returns(type) # rubocop:disable Style/TrivialAccessors
+        @returns = type
       end
 
-      def options
-        @options ||= {}
+      # The main interface to executing contracts. Given a set of options it
+      # will check the parameter types as well as return types, if defined.
+      #
+      # @param arguments [Hash] keyword arguments that match the defined options
+      #
+      # @yield the block is evaluated in the context of the instance call method
+      #
+      # @return The value of the #call instance method.
+      def call(context = {}, &block)
+        new(context: context).call(&block).tap { |result| validate_return(result) }
       end
 
-      def returns(type)
-        @returns = type
+      # Inject dependencies statically in to the Contract object. Allows for easier
+      # composition of contracts when used in a Transaction.
+      #
+      # @example
+      #   SampleClass.inject(user: User.new).call(attributes: { name: "Cindy" })
+      #
+      # @param injected [Hash] the options to inject in to the initializer
+      #
+      # @return [Class] a new class object that contains the injection
+      def inject(injected)
+        Validator.call({
+          options: Hash[injected.keys.zip(options.values_at(*injected.keys))],
+          context: Context.new(injected),
+          klass: self
+        })
+
+        Class.new(self) do
+          self.injected = injected
+        end
       end
 
+      # The defined return type on the Contract.
+      #
+      # @return [Dry::Type?] the type object to optionally check
       def return_type
         defined?(@returns) && @returns
       end
 
+      # Execute type checking on a value for the defined return value. Useful
+      # when executing `new` on these objects.
+      #
+      # @raise [Dry::Types::ConstraintError] a type check failure
+      #
+      # @param value [Any] the object to type check
       def validate_return(value)
-        return_type && return_type[value]
+        Atacama.check(return_type, value) do |e|
+          raise ReturnTypeMismatchError, "#{self} return value invalid: #{e.message}"
+        end
       end
 
-      # Define an initializer value.
-      # @param [Symbol] name of the argument
-      def option(name, **kwargs)
-        options[NameInterface[name]] = Parameter.new(name: name, **kwargs)
-
-        define_method(name) { @context[name] }
-        define_method("#{name}?") { !!@context[name] }
+      # The defined options on the contract.
+      #
+      # @return [Hash<String, Atacama::Parameter>]
+      def options
+        @options ||= {}
       end
 
-      def call(context = {}, &block)
-        new(context: context).call(&block).tap do |result|
-          validate_return(result)
+      # Executed by the Ruby VM at subclass time. Ensure that all internal state
+      # is copied to the new subclass.
+      def inherited(subclass)
+        subclass.returns(return_type)
+
+        options.each do |name, parameter|
+          subclass.option(name, type: parameter.type)
         end
       end
 
-      def inject(injected)
-        clone.tap do |clone|
-          clone.injected = injected
-        end
+      # @private
+      def injected=(hash)
+        @injected = Types::Strict::Hash[hash]
+      end
+
+      # @private
+      def injected
+        # Silences the VM warning about accessing uninitalized ivar
+        defined?(@injected) ? @injected : {}
       end
     end
 
     attr_reader :context
 
+    # @raise [Dry::Types::ConstraintError] a type check failure
+    #
+    # @param context [Hash] the values to satisfy the option definition
     def initialize(context: {}, **)
       ContextInterface[context] # Validate the type
 
@@ -72,19 +136,22 @@ module Atacama
         ctx.merge!(context.is_a?(Context) ? context.to_h : context)
       end
 
-      Validator.call(options: self.class.options, context: @context)
+      Validator.call(options: self.class.options, context: @context, klass: self.class)
     end
 
-    # Pretty pretty printing.
+    # @private
     def inspect
       "#<#{self.class}:0x%x %s>" % [
         object_id,
         self.class.options.keys.map do |option|
-          "#{option}: #{context.send(option).inspect}"
+          "#{option}: #{context.send(option).inspect[0..20]}"
         end.join(' ')
       ]
     end
 
+    # @abstract
+    # The default entrypoint for all Contracts. This is executed and
+    # type checked when called from the Class#call.
     def call
       self
     end

data/lib/atacama/transaction.rb

@@ -9,6 +9,7 @@ module Atacama
   class Transaction < Contract
     include Values::Methods
 
+    # The return value of all Transactions.
     class Result < Contract
       option :value, type: Types::Any
       option :transaction, type: Types.Instance(Context)
@@ -17,28 +18,62 @@ module Atacama
     class << self
       attr_reader :return_option
 
-      def returns_option(key, type)
+      def inherited(subclass)
+        super(subclass)
+        subclass.returns_option return_option, return_type
+        steps.each do |step|
+          subclass.step(step.name, with: step.with, yielding: step.yielding)
+        end
+      end
+
+      # Return the value of a given Option in the pipeline.
+      #
+      # @param key [Symbol] the option to read
+      # @param type [Dry::Type?] the type object to optionally check
+      def returns_option(key, type = nil)
         @return_option = key
 
         returns(
           Types.Instance(Result).constructor do |options|
-            type[options.value]
+            Atacama.check(type, options.value) do |e|
+              raise ResultTypeMismatchError, "Invalid Result value for #{self}: #{e.message}"
+            end
+
             options
           end
         )
       end
 
-      # @returns [Array<Atacama::Transaction::Definition>]
-      def steps
-        @steps ||= []
-      end
-
       # Add a step to the processing queue.
+      #
+      # @example
+      #   step :extract, with: UserParamsExtractor
+      #
+      # @example a yielding step
+      #   step :wrap, with: Wrapper do
+      #     step :extract, with: UserParamsExtractor
+      #   end
+      #
       # @param name [Symbol] a unique name for a step
-      def step(name, **kwargs, &block)
-        kwargs[:yielding] = block_given? ? Class.new(self, &block) : nil
-        kwargs[:with] ||= nil
-        steps.push Definition.call(name: name, **kwargs)
+      # @param with [Contract, Proc, nil] the callable to execute
+      #
+      # @yield The captured block allows defining of child steps. The wrapper must implement yield.
+      def step(name, with: nil, yielding: nil, &block)
+        add_step({
+          name: name,
+          with: with,
+          yielding: yielding || block_given? ? Class.new(self, &block) : nil
+        })
+      end
+
+      # @private
+      def add_step(params)
+        steps.push(Definition.call(params))
+      end
+
+      # @private
+      def steps
+        @steps ||= []
       end
     end
 
@@ -48,6 +83,9 @@ module Atacama
       @return_value = nil
     end
 
+    # Trigger execution of the Transaction pipeline.
+    #
+    # @return [Atacama::Transaction::Result] final result with value
     def call
       execute(self.class.steps)
       Result.call(value: return_value, transaction: context)

data/lib/atacama/types.rb

@@ -6,20 +6,41 @@ module Atacama
     include Dry::Types.module
     Boolean = Types::True | Types::False
 
+    # Defines a type which checks that the Option value contains a valid
+    # data structure.
+    #
+    # @param map [Hash] schema definition of the option value
+    #
+    # @return [Dry::Type]
     def self.Option(**map)
-      Instance(Values::Option).constructor do |options|
-        if options.is_a? Values::Option
-          map.each { |key, type| type[options.value[key]] }
+      Instance(Values::Option).constructor do |value_object|
+        if value_object.is_a? Values::Option
+          map.each do |key, type|
+            Atacama.check(type, value_object.value[key]) do |e|
+              raise OptionTypeMismatchError, "Invalid Option value type: #{e.message}"
+            end
+          end
         end
 
-        options
+        value_object
       end
     end
 
+    # Defines a type which checks that the Return value contains a valid
+    # object
+    #
+    # @param type [Dry::Type]
+    #
+    # @return [Dry::Type]
     def self.Return(type)
-      Instance(Values::Return).constructor do |options|
-        type[options.value] if options.is_a? Values::Return
-        options
+      Instance(Values::Return).constructor do |value_object|
+        if value_object.is_a?(Values::Return)
+          Atacama.check(type, value_object.value) do |e|
+            raise ReturnTypeMismatchError, "Invalid Return Value type: #{e.message}"
+          end
+        end
+
+        value_object
       end
     end
   end

data/lib/atacama/version.rb

@@ -1,3 +1,3 @@
 module Atacama
-  VERSION = '0.1.6'.freeze
+  VERSION = '0.1.7'.freeze
 end

data/lib/atacama.rb

@@ -5,7 +5,14 @@ require 'atacama/transaction'
 require 'atacama/step'
 
 module Atacama
-  ArgumentError = Class.new(StandardError)
-  TypeError = Class.new(StandardError)
-  MissingReturn = Class.new(StandardError)
+  OptionTypeMismatchError = Class.new(StandardError)
+  ReturnTypeMismatchError = Class.new(StandardError)
+  ResultTypeMismatchError = Class.new(StandardError)
+
+  def self.check(type, value)
+    type && type[value]
+    nil
+  rescue Dry::Types::ConstraintError => e
+    yield e
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atacama
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Tyler Johnston
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-12 00:00:00.000000000 Z
+date: 2018-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-types
@@ -74,6 +74,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rubocop.yml"
 - ".travis.yml"
 - Gemfile
 - Gemfile.lock