metaractor 2.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43fa8164083ceda9dca36dc6584da4bf3ac511e67d0f7a2232468ae841f8bd56
-  data.tar.gz: 1ed5b56c2524f9f73048a8f9f79c2ab4515bafe0749a60122b92841224b5194c
+  metadata.gz: 285b4aecd4d684716db6d574e443464ba4fecaca03f49417153d4eb2d49994e4
+  data.tar.gz: bea5769c3cb76692d1f1a1218fae8937500ae2cdec53dfda5d17066170a723b8
 SHA512:
-  metadata.gz: 535d587dde182fd7c298f050eefb6a560a35f27ffba8e90afd117a0395f760374b88794c09e2cd84821ba760b26ee0322bd1fd95d8d9b0b2c22dceac8b7cac14
-  data.tar.gz: 8571061ff4a4fcd37d3592a82273db4bf308f394b92bb7f36b2241fbbb07cbca4c2e1b05882af339c4a99891efc0688e23d4f7643e12842e200e18379ac78ec4
+  metadata.gz: 78226f45df08e38363d19cf03e3ec7867d0788700abf11daa08d5eca31ff62f3e9c43460d39be9d9422a686ee1a0da35de323df54d49ea06962876a809f3ad06
+  data.tar.gz: 76dee36d5fd30560f4bb7ebee50cf1e59d984e70bc219107e2d439024523ed2992056baacb17227e294466f4cff75b58cd96c7bb8fc0b680438ee8bf367e057c

data/.buildkite/pipeline.yml

@@ -0,0 +1,92 @@
+env:
+  BUILDKITE_PLUGIN_DOCKER_CACHE_S3_BUCKET: "outstand-buildkite-cache"
+  # BUILDKITE_PLUGIN_DOCKER_CACHE_VOLUME_DEBUG: "true"
+  BUILDKITE_PLUGIN_DOCKER_COMPOSE_SHELL: "false"
+  # BUILDKITE_PLUGIN_DOCKER_COMPOSE_UPLOAD_CONTAINER_LOGS: "always"
+  BUILDKITE_PLUGIN_DOCKER_COMPOSE_PULL_RETRIES: 5
+  BUILDKITE_PLUGIN_DOCKER_COMPOSE_PUSH_RETRIES: 5
+  PLUGIN_DOCKER_COMPOSE_VERSION: "17bac3aaee1360e39381b89bb45513b11838238e"
+  PLUGIN_DOCKER_CACHE_VERSION: "f3d8feb52a25c69c75565e9f0b80375eae51850a"
+
+steps:
+  - label: ":docker: Build"
+    command: ./docker/ci-prep.sh
+    key: build
+    plugins:
+      - seek-oss/aws-sm#v2.2.1:
+          env:
+            DOCKER_LOGIN_PASSWORD: "/buildkite/docker_password"
+
+      - docker-login#v2.0.1:
+          username: outstandci
+
+      - ecr#v2.1.1:
+          login: true
+          region: "us-east-1"
+
+      - https://github.com/outstand/docker-compose-buildkite-plugin.git#${PLUGIN_DOCKER_COMPOSE_VERSION}:
+          build: metaractor
+          image-repository: 786715713882.dkr.ecr.us-east-1.amazonaws.com/ci-images
+          config:
+            - docker-compose.yml
+
+  - label: ":bundler: :rubygems:"
+    key: bundle_install
+    command: bundle install
+    depends_on: build
+    plugins:
+      - seek-oss/aws-sm#v2.2.1:
+          env:
+            DOCKER_LOGIN_PASSWORD: "/buildkite/docker_password"
+
+      - docker-login#v2.0.1:
+          username: outstandci
+
+      - ecr#v2.1.1:
+          login: true
+          region: "us-east-1"
+
+      - https://github.com/outstand/docker-compose-buildkite-plugin.git#${PLUGIN_DOCKER_COMPOSE_VERSION}:
+          run: metaractor
+          dependencies: false
+          config:
+            - docker-compose.yml
+
+      - https://github.com/outstand/docker-cache-buildkite-plugin.git#${PLUGIN_DOCKER_CACHE_VERSION}:
+          name: bundler-cache
+          keys:
+            - v1-bundler-cache-{{ arch }}-{{ checksum "metaractor.gemspec" }}-{{ checksum "Gemfile" }}
+            - v1-bundler-cache-{{ arch }}-
+          save: true
+          volumes:
+            - bundler-data
+
+  - label: ":ruby: Specs"
+    command: rspec spec
+    depends_on: bundle_install
+    plugins:
+      - seek-oss/aws-sm#v2.2.1:
+          env:
+            DOCKER_LOGIN_PASSWORD: "/buildkite/docker_password"
+          json-to-env:
+            - secret-id: "/buildkite/rails/env_vars"
+
+      - docker-login#v2.0.1:
+          username: outstandci
+
+      - ecr#v2.1.1:
+          login: true
+          region: "us-east-1"
+
+      - https://github.com/outstand/docker-compose-buildkite-plugin.git#${PLUGIN_DOCKER_COMPOSE_VERSION}:
+          run: metaractor
+          config:
+            - docker-compose.yml
+
+      - https://github.com/outstand/docker-cache-buildkite-plugin.git#${PLUGIN_DOCKER_CACHE_VERSION}:
+          name: bundler-cache
+          keys:
+            - v1-bundler-cache-{{ arch }}-{{ checksum "metaractor.gemspec" }}-{{ checksum "Gemfile" }}
+            - v1-bundler-cache-{{ arch }}-
+          volumes:
+            - bundler-data

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/Deskfile

data/.rspec

@@ -1,2 +1,4 @@
 --color
 --require spec_helper
+--format progress
+--format RSpec::Buildkite::AnnotationFormatter

data/Dockerfile

@@ -1,4 +1,6 @@
-FROM ruby:2.6.5-alpine
+FROM outstand/fixuid as fixuid
+
+FROM ruby:2.7.3-alpine
 LABEL maintainer="Ryan Schlesinger <ryan@outstand.com>"
 
 RUN addgroup -g 1000 -S metaractor && \
@@ -11,7 +13,14 @@ RUN addgroup -g 1000 -S metaractor && \
       git \
       openssh
 
-ENV BUNDLER_VERSION 2.1.4
+COPY --from=fixuid /usr/local/bin/fixuid /usr/local/bin/fixuid
+RUN chmod 4755 /usr/local/bin/fixuid && \
+      USER=metaractor && \
+      GROUP=metaractor && \
+      mkdir -p /etc/fixuid && \
+      printf "user: $USER\ngroup: $GROUP\n" > /etc/fixuid/config.yml
+
+ENV BUNDLER_VERSION 2.2.16
 RUN gem install bundler -v ${BUNDLER_VERSION} -i /usr/local/lib/ruby/gems/$(ls /usr/local/lib/ruby/gems) --force
 
 WORKDIR /metaractor

data/Gemfile

@@ -1,4 +1,4 @@
 source 'https://rubygems.org'
 
 gemspec
-gem 'pry-byebug'
+gem 'rspec-buildkite', github: 'outstand/rspec-buildkite', branch: 'error-output'

data/README.md

@@ -1,4 +1,4 @@
-# Metaractor
+# Metaractor [![Build status](https://badge.buildkite.com/70063a5154eb7366b8b7fd65a875c5f64301bc60f6d29a2ad7.svg)](https://buildkite.com/outstand/metaractor)
 Adds parameter validation and error control to [interactor](https://github.com/collectiveidea/interactor).
 
 ## Installation
@@ -44,7 +44,7 @@ result.failure?
 # => true
 result.valid?
 # => false
-result.errors
+result.error_messages
 # => ["Required parameters: (user_id or user)"]
 ```
 
@@ -68,20 +68,59 @@ Metaractor supports complex required parameter statements and you can chain thes
 required and: [:token, or: [:recipient_id, :recipient] ]
 ```
 
+You can also mark a parameter as required with the `required` option:
+```ruby
+parameter :user, required: true
+```
+
 ### Optional Parameters
 As optional parameters have no enforcement, they are merely advisory.
 ```ruby
 optional :enable_logging
 ```
 
-### Skipping Blank Parameter Removal
+### Parameter Options
+Metaractor supports arbitrary parameter options. The following are currently built in.
+Note that you can specify a block of `required` or `optional` parameters and then use
+`parameter` or `parameters` to add options to one or more of them.
+
+#### Skipping Blank Parameter Removal
 By default Metaractor removes blank values that are passed in. You may skip this behavior on a per-parameter basis:
 ```ruby
-allow_blank :name
+parameter :name, allow_blank: true
 ```
 
 You may check to see if a parameter exists via `context.has_key?`.
 
+#### Default Values
+You can specify a default value for a parameter:
+```ruby
+optional :role, default: :user
+```
+
+This works with `allow_blank` and can also be anything that responds to `#call`.
+```ruby
+parameter :role, allow_blank: true, default: -> { context.default_role }
+```
+
+#### Typecasting/Coersion
+You can supply Metaractor with a callable that will typecast incoming parameters:
+```ruby
+optional :needs_to_be_a_string, type: ->(value) { value.to_s }
+```
+
+You can also configure Metaractor with named types and use them:
+```ruby
+Metaractor.configure do |config|
+  config.register_type(:boolean, ->(value) { ActiveModel::Type::Boolean.new.cast(value) })
+end
+```
+```ruby
+required :is_awesome, type: :boolean
+```
+
+**Note**: Typecasters will _not_ be called on `nil` values.
+
 ### Custom Validation
 Metaractor supports doing custom validation before any user supplied before_hooks run.
 ```ruby
@@ -104,6 +143,203 @@ before do
 end
 ```
 
+### Structured Errors
+As of v2.0.0, metaractor supports structured errors.
+```ruby
+class UpdateUser
+  include Metaractor
+
+  optional :is_admin
+  optional :user
+
+  def call
+    fail_with_error!(
+      errors: {
+        base: 'Invalid configuration',
+        is_admin: 'must be true or false',
+        user: [ title: 'cannot be blank', username: ['must be unique', 'must not be blank'] ]
+      }
+    )
+  end
+end
+
+result = UpdateUser.call
+result.error_messages
+# => [
+#      'Invalid configuration',
+#      'is_admin must be true or false',
+#      'user.title cannot be blank',
+#      'user.username must be unique',
+#      'user.username must not be blank'
+#    ]
+
+result.errors.full_messages_for(:user)
+# => [
+#      'title cannot be blank',
+#      'username must be unique',
+#      'username must not be blank'
+#    ]
+
+# The arguments to `slice` are a list of paths.
+# In this case we're asking for the errors under `base` and also
+# the errors found under user _and_ title.
+result.errors.slice(:base, [:user, :title])
+# => {
+#      base: 'Invalid configuration',
+#      user: { title: 'cannot be blank' }
+#    }
+
+result.errors.to_h
+# => {
+#      base: 'Invalid configuration',
+#      is_admin: 'must be true or false',
+#      user: {
+#        title: 'cannot be blank',
+#        username: ['must be unique', 'must not be blank']
+#      }
+#    }
+```
+
+### I18n
+As of v3.0.0, metaractor supports i18n along with structured errors.
+```ruby
+module Users
+  class UpdateUser
+    include Metaractor
+
+    optional :is_admin
+    optional :user
+
+    def call
+      fail_with_error!(
+        errors: {
+          base: :invalid_configuration,
+          is_admin: :true_or_false,
+          user: [ title: :blank, username: [:unique, :blank] ]
+        }
+      )
+    end
+  end
+end
+```
+
+Locale:
+```yaml
+en:
+  errors:
+    parameters:
+      invalid_configuration: 'Invalid configuration'
+      blank: '%{parameter} cannot be blank'
+      unique: '%{parameter} must be unique'
+
+      users:
+        is_admin:
+          true_or_false: 'must be true or false'
+      user:
+        username:
+          unique: 'Username has already been taken'
+```
+
+Metaractor will attempt to use the namespace of the code that reported the error.
+You can see that above with the `users` key in the locale.
+
+The i18n integration will walk its way from the most specific message to the least specific one, stopping at the first one it can find.
+We currently expose the following variables for use in the message:
+- `error_key`: the error we added (ex: `blank` or `invalid_configuration`)
+- `parameter`: the name of the parameter
+
+You can also use this feature to work with machine readable keys:
+```ruby
+result = Users::UpdateUser.call
+if result.failure? &&
+  result.errors[:is_admin].include?(:true_or_false)
+
+  # handle this specific case
+end
+```
+
+### Spec Helpers
+Enable the helpers and/or matchers:
+```ruby
+RSpec.configure do |config|
+  config.include Metaractor::Spec::Helpers
+  config.include Metaractor::Spec::Matchers
+end
+```
+
+#### Helpers
+- `context_creator`
+```ruby
+# context_creator(error_message: nil, error_messages: [], errors: [], valid: nil, invalid: nil, success: nil, failure: nil, **attributes)
+
+# Create a blank context:
+context_creator
+
+# Create a context with some data:
+context_creator(message: message, user: user)
+
+# Create an invalid context:
+context_creator(error_message: "invalid context", invalid: true)
+
+# Create a context with string errors:
+context_creator(error_messages: ["That didn't work", "Neither did this"])
+
+# Create a context with structured errors:
+context_creator(
+  user: user,
+  errors: {
+    user: {
+      email: 'must be unique'
+    },
+    profile: {
+      first_name: 'cannot be blank'
+    }
+  }
+)
+```
+
+#### Matchers
+- `include_errors`
+```ruby
+result = context_creator(
+  errors: {
+    user: [
+      title: 'cannot be blank',
+      username: ['must be unique', 'must not be blank']
+    ]
+  }
+)
+
+expect(result).to include_errors(
+  'username must be unique',
+  'username must not be blank'
+).at_path(:user, :username)
+
+expect(result).to include_errors('user.title cannot be blank')
+```
+
+### Hash Formatting
+Metaractor customizes the output for `Metaractor::Errors#inspect` and `Interactor::Failure`:
+```
+Interactor::Failure:
+       Errors:
+       {:base=>"NOPE"}
+
+       Previously Called:
+       Chained
+
+       Context:
+       {:parent=>true, :chained=>true}
+```
+
+You can further customize the hash formatting:
+```ruby
+Metaractor.configure do |config|
+  # Configure Metaractor to use awesome_print
+  config.hash_formatter = ->(hash) { hash.ai }
+end
+```
+
 ### Further Reading
 For more examples of all of the above approaches, please see the specs.
 

data/docker-compose.yml

@@ -5,6 +5,9 @@ services:
     image: outstand/metaractor:dev
     stdin_open: true
     tty: true
+    environment:
+      FIXUID:
+      FIXGID:
     volumes:
       - bundler-data:/usr/local/bundle
       - .:/metaractor
@@ -13,6 +16,9 @@ services:
     stdin_open: true
     tty: true
     command: rake release
+    environment:
+      FIXUID:
+      FIXGID:
     volumes:
       - bundler-data:/usr/local/bundle
       - ~/.gitconfig:/home/metaractor/.gitconfig

data/docker-entrypoint.sh

@@ -1,6 +1,19 @@
 #!/bin/sh
+
 set -e
 
+su-exec ${FIXUID:?Missing FIXUID var}:${FIXGID:?Missing FIXGID var} fixuid
+
+chown_dir() {
+  dir=$1
+  if [[ -d ${dir} ]] && [[ "$(stat -c %u:%g ${dir})" != "${FIXUID}:${FIXGID}" ]]; then
+    echo chown $dir
+    chown metaractor:metaractor $dir
+  fi
+}
+
+chown_dir /usr/local/bundle
+
 if [ "$(which "$1")" = '' ]; then
   if [ "$(ls -A /usr/local/bundle/bin)" = '' ]; then
     echo 'command not in path and bundler not initialized'

data/lib/metaractor.rb

@@ -9,6 +9,9 @@ require 'metaractor/context_validity'
 require 'metaractor/chain_failures'
 require 'metaractor/fail_from_context'
 require 'metaractor/context_has_key'
+require 'metaractor/failure_output'
+require 'i18n'
+require 'metaractor/namespace'
 
 module Metaractor
   def self.included(base)
@@ -42,7 +45,8 @@ module Metaractor
       { module: Metaractor::HandleErrors, method: :include },
       { module: Metaractor::Parameters, method: :include },
       { module: Metaractor::RunWithContext, method: :include },
-      { module: Metaractor::ChainFailures, method: :include }
+      { module: Metaractor::ChainFailures, method: :include },
+      { module: Metaractor::Namespace, method: :include }
     ]
   end
 
@@ -53,4 +57,36 @@ module Metaractor
   def self.prepend_module(mod)
     modules << { module: mod, method: :prepend }
   end
+
+  def self.format_hash(hash)
+    if @hash_formatter.nil?
+      @hash_formatter = default_hash_formatter
+    end
+
+    @hash_formatter.call(hash)
+  end
+
+  def self.default_hash_formatter
+    ->(hash){ hash.inspect }
+  end
+
+  def self.hash_formatter
+    @hash_formatter
+  end
+
+  def self.hash_formatter=(callable)
+    @hash_formatter = callable
+  end
+
+  def self.types
+    @types ||= {}
+  end
+
+  def self.register_type(type, callable)
+    types[type] = callable
+  end
+
+  def self.clear_types!
+    @types = {}
+  end
 end

data/lib/metaractor/context_errors.rb

@@ -8,29 +8,29 @@ module Metaractor
       super
     end
 
-    def fail_with_error!(message: nil, errors: nil)
-      add_error(message: message, errors: errors)
+    def fail_with_error!(message: nil, errors: nil, **args)
+      add_error(message: message, errors: errors, **args)
       fail!
     end
 
-    def fail_with_errors!(messages: [], errors: {})
-      add_errors(messages: messages, errors: errors)
+    def fail_with_errors!(messages: [], errors: {}, **args)
+      add_errors(messages: messages, errors: errors, **args)
       fail!
     end
 
-    def add_error(message: nil, errors: nil)
+    def add_error(message: nil, errors: nil, **args)
       if message.nil?
-        add_errors(errors: errors)
+        add_errors(errors: errors, **args)
       else
-        add_errors(messages: Array(message))
+        add_errors(messages: Array(message), **args)
       end
     end
 
-    def add_errors(messages: [], errors: {})
+    def add_errors(messages: [], errors: {}, **args)
       if !messages.empty?
-        self.errors.add(errors: { base: messages })
+        self.errors.add(errors: { base: messages }, **args)
       else
-        self.errors.add(errors: errors)
+        self.errors.add(errors: errors, **args)
       end
     end
 

data/lib/metaractor/errors.rb

@@ -4,13 +4,72 @@ module Metaractor
   class Errors
     extend Forwardable
 
+    class Error
+      attr_reader :value, :object
+
+      def initialize(value:, object: nil)
+        @value = value
+        @object = object
+      end
+
+      def generate_message(path_elements:)
+        if @value.is_a? Symbol
+          defaults = []
+
+          if object.class.respond_to?(:i18n_parent_names) &&
+              !object.class.i18n_parent_names.empty?
+
+            names = object.class.i18n_parent_names
+            until names.empty?
+              defaults << ['errors', names.join('.'), 'parameters', path_elements.join('.'), @value.to_s].reject do |item|
+                item.nil? || item == ''
+              end.join('.').to_sym
+              names.pop
+            end
+          end
+
+          unless path_elements.empty?
+            defaults << :"errors.parameters.#{path_elements.join('.')}.#{@value}"
+          end
+          defaults << :"errors.parameters.#{@value}"
+
+          key = defaults.shift
+          I18n.translate(
+            key,
+            default: defaults,
+            error_key: @value,
+            parameter: path_elements.last
+          )
+        else
+          "#{path_elements.join('.')} #{@value}".lstrip
+        end
+      end
+
+      def ==(other)
+        if other.is_a?(self.class)
+          @value == other.value
+        else
+          @value == other
+        end
+      end
+      alias eql? ==
+
+      def hash
+        @value.hash
+      end
+
+      def inspect
+        "(Error) #{@value.inspect}"
+      end
+    end
+
     def initialize
       @tree = Sycamore::Tree.new
     end
 
-    def_delegators :@tree, :to_h, :empty?
+    def_delegators :@tree, :empty?
 
-    def add(error: {}, errors: {})
+    def add(error: {}, errors: {}, object: nil)
       trees = []
       [error, errors].each do |h| 
         tree = nil
@@ -29,7 +88,17 @@ module Metaractor
       end
 
       trees.each do |tree|
-        @tree.add(tree)
+        tree.each_path do |path|
+          node = path.node
+          unless node.is_a?(Error)
+            node = Error.new(
+              value: path.node,
+              object: object
+            )
+          end
+
+          @tree[path.parent] << node
+        end
       end
       @tree.compact
     end
@@ -58,9 +127,9 @@ module Metaractor
       result = @tree.dig(*path)
 
       if result.strict_leaves?
-        result.nodes
+        unwrapped_enum(result.nodes)
       else
-        result.to_h
+        unwrapped_tree(result).to_h
       end
     end
     alias [] dig
@@ -68,9 +137,15 @@ module Metaractor
     def include?(*elements)
       if elements.size == 1 &&
           elements.first.is_a?(Hash)
-        @tree.include?(*elements)
+        unwrapped_tree.include?(*elements)
       else
-        full_messages.include?(*elements)
+        if elements.all? {|e| e.is_a? String }
+          full_messages.include?(*elements)
+        else
+          elements.all? do |element|
+            @tree.include_path?(element)
+          end
+        end
       end
     end
 
@@ -83,7 +158,29 @@ module Metaractor
         end
       end
 
-      new_tree.to_h
+      unwrapped_tree(new_tree).to_h
+    end
+
+    def to_h(unwrap: true)
+      if unwrap
+        unwrapped_tree.to_h
+      else
+        @tree.to_h
+      end
+    end
+    alias to_hash to_h
+
+    def inspect
+      str = "<##{self.class.name}: "
+
+      if !self.empty?
+        str << "Errors:\n"
+        str << Metaractor.format_hash(to_h(unwrap: false))
+        str << "\n"
+      end
+
+      str << ">"
+      str
     end
 
     private
@@ -96,7 +193,32 @@ module Metaractor
         end
       end
 
-      "#{path_elements.join('.')} #{path.node.to_s}".lstrip
+      path.node.generate_message(path_elements: path_elements)
     end
+
+    def unwrapped_tree(orig_tree = @tree)
+      tree = Sycamore::Tree.new
+      orig_tree.each_path do |path|
+        node = path.node
+        if node.is_a? Error
+          node = node.value
+        end
+
+        tree[path.parent] << node
+      end
+
+      tree
+    end
+
+    def unwrapped_enum(orig)
+      orig.map do |element|
+        if element.is_a? Error
+          element.value
+        else
+          element
+        end
+      end
+    end
+
   end
 end

data/lib/metaractor/failure_output.rb

@@ -0,0 +1,28 @@
+module Metaractor
+  module FailureOutput
+    def to_s
+      str = ''
+
+      if !context.errors.empty?
+        str << "Errors:\n"
+        str << Metaractor.format_hash(context.errors.to_h)
+        str << "\n\n"
+      end
+
+      if !context._called.empty?
+        str << "Previously Called:\n"
+        context._called.each do |interactor|
+          str << interactor.class.name.to_s
+          str << "\n"
+        end
+        str << "\n"
+      end
+
+      str << "Context:\n"
+      str << Metaractor.format_hash(context.to_h.reject{|k,_| k == :errors})
+      str
+    end
+  end
+end
+
+Interactor::Failure.send(:include, Metaractor::FailureOutput)

data/lib/metaractor/handle_errors.rb

@@ -3,20 +3,20 @@ module Metaractor
   class InvalidError < Error; end
 
   module HandleErrors
-    def fail_with_error!(*args)
-      context.fail_with_error!(*args)
+    def fail_with_error!(**args)
+      context.fail_with_error!(object: self, **args)
     end
 
-    def fail_with_errors!(*args)
-      context.fail_with_errors!(*args)
+    def fail_with_errors!(**args)
+      context.fail_with_errors!(object: self, **args)
     end
 
-    def add_error(*args)
-      context.add_error(*args)
+    def add_error(**args)
+      context.add_error(object: self, **args)
     end
 
-    def add_errors(*args)
-      context.add_errors(*args)
+    def add_errors(**args)
+      context.add_errors(object: self, **args)
     end
 
     def error_messages

data/lib/metaractor/namespace.rb

@@ -0,0 +1,46 @@
+module Metaractor
+  module Namespace
+    # The following code is adapted from rails.
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def module_parent_name
+        if defined?(@parent_name)
+          @parent_name
+        else
+          parent_name = name =~ /::[^:]+\z/ ? -$` : nil
+          @parent_name = parent_name unless frozen?
+          parent_name
+        end
+      end
+
+      def module_parent_names
+        parents = []
+        if module_parent_name
+          parents = module_parent_name.split("::")
+        end
+        parents
+      end
+
+      def i18n_parent_names
+        module_parent_names.map {|name| underscore_module_name(name).to_sym }
+      end
+
+      private
+
+      def underscore_module_name(camel_cased_word)
+        return camel_cased_word unless /[A-Z-]|::/.match?(camel_cased_word)
+        word = camel_cased_word.to_s.gsub("::", "/")
+        word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+        word.tr!("-", "_")
+        word.downcase!
+        word
+      end
+
+    end
+  end
+end

data/lib/metaractor/parameters.rb

@@ -1,3 +1,5 @@
+# Special thanks to the `hashie` and `active_attr` gems for code and inspiration.
+
 module Metaractor
   module Parameters
     def self.included(base)
@@ -6,40 +8,93 @@ module Metaractor
         include Metaractor::HandleErrors
 
         class << self
-          attr_writer :_required_parameters
-          attr_writer :_optional_parameters
-          attr_writer :_allow_blank
+          attr_writer :requirement_trees
         end
 
         before :remove_blank_values
+        before :apply_defaults
         before :validate_required_parameters
+        before :apply_types
       end
     end
 
+    class Parameter
+      include Comparable
+
+      attr_reader :name
+
+      def initialize(name, **options)
+        @name = name.to_sym
+        @options = options
+      end
+
+      def <=>(other)
+        return nil unless other.instance_of? self.class
+        return nil if name == other.name && options != other.options
+        self.name.to_s <=> other.name.to_s
+      end
+
+      def [](key)
+        @options[key]
+      end
+
+      def dig(name, *names)
+        @options.dig(name, *names)
+      end
+
+      def merge!(**options)
+        @options.merge!(**options)
+      end
+
+      def to_s
+        name.to_s
+      end
+
+      def to_sym
+        name
+      end
+
+      protected
+      attr_reader :options
+    end
+
     module ClassMethods
-      def _required_parameters
-        @_required_parameters ||= []
+      def parameter(name, **options)
+        if param = self.parameter_hash[name.to_sym]
+          param.merge!(**options)
+        else
+          Parameter.new(name, **options).tap do |parameter|
+            self.parameter_hash[parameter.name] = parameter
+          end
+        end
       end
 
-      def required(*params)
-        self._required_parameters += params
+      def parameters(*names, **options)
+        names.each do |name|
+          parameter(name, **options)
+        end
       end
-      alias_method :required_parameters, :required
 
-      def _optional_parameters
-        @_optional_parameters ||= []
+      def parameter_hash
+        @parameters ||= {}
       end
 
-      def optional(*params)
-        self._optional_parameters += params
+      def requirement_trees
+        @requirement_trees ||= []
       end
 
-      def _allow_blank
-        @_allow_blank ||= []
+      def required(*params, **options)
+        if params.empty?
+          tree = options
+          self.requirement_trees << tree
+          parameters(*parameters_in_tree(tree), required: tree)
+        else
+          parameters(*params, required: true, **options)
+        end
       end
 
-      def allow_blank(*params)
-        self._allow_blank += params
+      def optional(*params, **options)
+        parameters(*params, **options)
       end
 
       def validate_parameters(*hooks, &block)
@@ -50,26 +105,91 @@ module Metaractor
       def validate_hooks
         @validate_hooks ||= []
       end
+
+      def parameters_in_tree(tree)
+        if tree.respond_to?(:to_h)
+          tree.to_h.values.first.to_a.flat_map {|t| parameters_in_tree(t)}
+        else
+          [tree]
+        end
+      end
+    end
+
+    def parameters
+      self.class.parameter_hash
+    end
+
+    def requirement_trees
+      self.class.requirement_trees
+    end
+
+    def requirement_trees=(trees)
+      self.class.requirement_trees=(trees)
     end
 
     def remove_blank_values
       to_delete = []
-      context.each_pair do |k,v|
-        next if self.class._allow_blank.include?(k)
+      context.each_pair do |name, value|
+        next if parameters.dig(name, :allow_blank)
 
         # The following regex is borrowed from Rails' String#blank?
-        to_delete << k if (v.is_a?(String) && /\A[[:space:]]*\z/ === v) || v.nil?
+        to_delete << name if (value.is_a?(String) && /\A[[:space:]]*\z/ === value) || value.nil?
       end
-      to_delete.each do |k|
-        context.delete_field k
+
+      to_delete.each do |name|
+        context.delete_field name
+      end
+    end
+
+    def apply_defaults
+      parameters.each do |name, parameter|
+        next unless parameter[:default]
+
+        unless context.has_key?(name)
+          context[name] = _parameter_default(name)
+        end
+      end
+    end
+
+    def _parameter_default(name)
+      default = self.parameters[name][:default]
+
+      case
+      when default.respond_to?(:call) then instance_exec(&default)
+      when default.respond_to?(:dup) then default.dup
+      else default
+      end
+    end
+
+    def apply_types
+      parameters.each do |name, parameter|
+        next unless parameter[:type]
+
+        if context.has_key?(name) && context[name] != nil
+          callable = parameter[:type]
+
+          if callable.is_a?(Symbol)
+            callable = Metaractor.types[callable]
+            raise ArgumentError, "No such type: #{parameter[:type]}" if callable.nil?
+          end
+
+          context[name] = callable.call(context[name])
+        end
       end
     end
 
     def validate_required_parameters
       context.errors ||= []
 
-      self.class._required_parameters.each do |param|
-        require_parameter param
+      parameters.each do |name, parameter|
+        next if !parameter[:required] ||
+          parameter[:required].is_a?(Hash)
+
+        require_parameter name
+      end
+
+      requirement_trees.each do |tree|
+        require_parameter tree
       end
 
       run_validate_hooks

data/lib/metaractor/version.rb

@@ -1,3 +1,3 @@
 module Metaractor
-  VERSION = "2.0.0"
+  VERSION = "3.1.0"
 end

data/metaractor.gemspec

@@ -11,7 +11,10 @@ Gem::Specification.new do |spec|
   spec.email         = ['ryan@outstand.com']
 
   spec.summary       = %q{Adds parameter validation and error control to interactor}
-  spec.homepage      = 'https://github.com/outstand/metaractor'
+  spec.metadata      = {
+    "homepage_uri" => "https://github.com/outstand/metaractor",
+    "source_code_uri" => "https://github.com/outstand/metaractor"
+  }
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.bindir        = 'exe'
@@ -20,8 +23,12 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'interactor', '~> 3.1'
   spec.add_runtime_dependency 'sycamore', '~> 0.3'
+  spec.add_runtime_dependency 'i18n', '~> 1.8'
 
   spec.add_development_dependency 'bundler', '~> 2'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.9'
+  spec.add_development_dependency 'awesome_print', '~> 1.8'
+  spec.add_development_dependency 'pry-byebug', '~> 3.9'
+  spec.add_development_dependency 'activemodel', '~> 6.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: metaractor
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Ryan Schlesinger
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-03-17 00:00:00.000000000 Z
+date: 2021-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: interactor
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -80,13 +94,56 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.9'
-description: 
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description:
 email:
 - ryan@outstand.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".buildkite/pipeline.yml"
 - ".gitignore"
 - ".rspec"
 - Dockerfile
@@ -103,17 +160,21 @@ files:
 - lib/metaractor/context_validity.rb
 - lib/metaractor/errors.rb
 - lib/metaractor/fail_from_context.rb
+- lib/metaractor/failure_output.rb
 - lib/metaractor/handle_errors.rb
+- lib/metaractor/namespace.rb
 - lib/metaractor/parameters.rb
 - lib/metaractor/run_with_context.rb
 - lib/metaractor/spec.rb
 - lib/metaractor/version.rb
 - metaractor.gemspec
-homepage: https://github.com/outstand/metaractor
+homepage:
 licenses:
 - Apache-2.0
-metadata: {}
-post_install_message: 
+metadata:
+  homepage_uri: https://github.com/outstand/metaractor
+  source_code_uri: https://github.com/outstand/metaractor
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -128,8 +189,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.1.6
+signing_key:
 specification_version: 4
 summary: Adds parameter validation and error control to interactor
 test_files: []