paramore 0.2.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78c8a8c6985a0f9044fa608f0473cbd6ce872c5ff7f9626a2fb6e49f39c67f69
-  data.tar.gz: c6c18de5f2dd039d06044ba58f7c4bfc38dda160fd6730213748c883529f8823
+  metadata.gz: d42894f0d3cefbd8979dc3048515ad8285a7f322f1ec1907b19d9941d6f95620
+  data.tar.gz: '0283777104760cb5d2d8774d95a61aa5841adaa38f35a488218cf89865a2571b'
 SHA512:
-  metadata.gz: e406c95c757d7c583fb5d962f4b453c8dbda6dc141ad581169aab7ba767e2903723eb31c830ef8f55b98e5a12606feb578644141800e64a154217c0cd2f886e0
-  data.tar.gz: 9061803ea9cdcccd492bb58f280d0037e01870c61d7dd30d8fad1d1ceabcb580f0e715531cf71ceff6fb8f875f60810ec95d7cfbedb14594f6fc65e85d491a1e
+  metadata.gz: 19def8fd4558111735cb93a28157e3fd7a7905be0b11b4d4515c85ccee3f26f64d6ab1c1d6c464d96230030960a89bac4ff31c96e391603a8786a08c98bdb8a1
+  data.tar.gz: da286395c83d3e13fc5ec1a0344a0232800fbf841bbc8bec14e32072059c32f678caef0d609cb17a6a4780e8ef3b4cd699fd52e2432ecca3dede925156ff0162

data/README.md

@@ -1,11 +1,10 @@
 # Paramore
 
 Paramore is a small gem intended to make strong parameter definitions declarative
-and provide a unified way to format and sanitize their values outside of controllers.
+and provide a unified way to typecast and sanitize their values outside of controllers.
 
 # Installation
 
-
 In your Gemfile:
 ```ruby
 gem 'paramore'
@@ -18,14 +17,14 @@ $ bundle
 
 # Usage
 
-<h3>Without formatting/sanitizing</h3>
+<h3>Without typing</h3>
 
 ```ruby
-declare_params :item_params
+paramorize :item_params,
   item: [:name, :description, :for_sale, :price, metadata: [tags: []]]
 ```
 
-This is completely equivalent (including return type) to
+This is completely equivalent (including the return type) to
 
 ```ruby
 def item_params
@@ -35,10 +34,10 @@ def item_params
 end
 ```
 
-<h3>With formatting/sanitizing</h3>
+<h3>With typing</h3>
 
 A common problem in app development is untrustworthy input given by clients.
-That input needs to be sanitized and potentially formatted and type-cast for further processing.
+That input needs to be sanitized and typecast for further processing.
 A naive approach could be:
 
 ```ruby
@@ -48,7 +47,7 @@ def item_params
   @item_params ||= begin
     _params = params
       .require(:item)
-      .permit(:name, :description, :price, metadata: [tags: []])
+      .permit(:name, :description, :for_sale, :price, metadata: [tags: []])
 
     _params[:name] = _params[:name].strip.squeeze(' ') if _params[:name]
     _params[:description] = _params[:description].strip.squeeze(' ') if _params[:description]
@@ -70,69 +69,42 @@ The next logical step is extracting those procedures - this is where Paramore st
 ```ruby
 # app/controllers/items_controller.rb
 
-declare_params :item_params
-  item: [:name, :description, :price, metadata: [tags: []]],
-  format: {
-    name: :Text,
-    description: :Text,
-    for_sale: :Boolean,
-    price: :Decimal,
-    metadata: {
-      tags: :ItemTags
-    }
-  }
-```
-
-```ruby
-# app/formatter/text.rb
-
-module Formatter::Text
-  module_function
-  def run(input)
-    input.strip.squeeze(' ')
+class ItemsController < ApplicationController
+  def create
+    Item.create(item_params)
   end
-end
-```
-```ruby
-# app/formatter/boolean.rb
 
-module Formatter::Boolean
-  TRUTHY_TEXT_VALUES = %w[t true 1]
-
-  module_function
-  def run(input)
-    input.in?(TRUTHY_TEXT_VALUES)
-  end
+  paramorize :item_params,
+    item: {
+      name: Paratype[Paramore::SanitizedString],
+      description: Paratype[Paramore::StrippedString, null: true],
+      for_sale: Paratype[Paramore::Boolean],
+      price: Paratype[Paramore::Decimal],
+      metadata: Paratype[{
+        tags: Paratype[[Types::ItemTag], compact: true]
+      }]
+    }
 end
 ```
-```ruby
-# app/formatter/decimal.rb
 
-module Formatter::Decimal
-  module_function
-  def run(input)
-    input.to_d
-  end
-end
-```
+`Types::ItemTag` could be your own type:
 ```ruby
-# app/formatter/item_tags.rb
+# app/types/item_tag.rb
 
-module Formatter::ItemTags
+module Types::ItemTag
   module_function
-  def run(input)
-    input.map { |tag_id| Item.tags[tag_id.to_i] }
+  def [](input)
+    Item.tags[input.to_i]
   end
 end
 ```
 
-
 Now, given `params` are:
 ```ruby
 <ActionController::Parameters {
   "unpermitted"=>"parameter",
   "name"=>"Shoe  \n",
-  "description"=>"Black,  with laces",
+  "description"=>"  Black,  with laces",
   "for_sale"=>"true",
   "price"=>"39.99",
   "metadata"=><ActionController::Parameters { "tags"=>["38", "112"] } permitted: false>
@@ -142,7 +114,7 @@ Calling `item_params` will return:
 ```ruby
 <ActionController::Parameters {
   "name"=>"Shoe",
-  "description"=>"Black, with laces",
+  "description"=>"Black,  with laces",
   "for_sale"=>true,
   "price"=>39.99,
   "metadata"=><ActionController::Parameters { "tags"=>[:shoe, :new] } permitted: true>
@@ -150,22 +122,30 @@ Calling `item_params` will return:
 ```
 
 This is useful when the values are not used with Rails models, but are passed to simple functions for processing.
-The formatters can also be easily reused anywhere in the app,
-since they are completely decoupled from Rails.
+The types can also be easily reused anywhere in the app, since they are completely decoupled from Rails.
+
+Notice that the `Paramore::StrippedString` does not perform `.squeeze(' ')`, only `Paramore::SanitizedString` does.
+
+<h3>nil</h3>
+
+Types are non-nullable by default and raise exceptions if the param hash misses any.
+This can be disabled for any type by declaring `Paratype[Paramore::Int, null: true]`.
+
+nils will usually not reach any of the type classes - if some parameter is nullable, the class will not be called.
+If a parameter is non-nullable, then a `Paramore::NilParameter` error will be raised before calling the class.
+If a, say, `item_ids` array is non-nullable, but the received parameter is `['1', '', '3']`, only the `'1'` and `'2'` will get passed to type classes, and the resulting array will contain a nil, eg.: `['1', nil, '3']`.
+nils inside arrays can still be passed to type classes by declaring `Paratype[[Paramore::Int], empty: true]`.
+If you wish to get rid of empty array elements, declare `Paratype[Paramore::Int, compact: true]`.
 
 <h3>Configuration</h3>
 
 Running `$ paramore` will generate a configuration file located in `config/initializers/paramore.rb`.
-- `config.formatter_namespace` - default is `Formatter`. Set to `nil` to have top level named formatters
-  (this also allows specifying the formatter object itself, eg.: `name: Formatter::Text`).
-- `config.formatter_method_name` - default is `run`. Don't set to `nil` :D
+- `config.type_method_name` - default is `[]`, to allow using, for example, `SuperString["foo"]` syntax. Note that changing this value will preclude you from using built in types.
 
 <h3>Safety</h3>
 
-  - Formatters will not be called if their parameter is missing (no key in the param hash)
-  - Formatters are validated - all given formatter names must match actual modules/classes defined in the app
-    and must respond to the configured `formatter_method_name`.
-    This means that all used formatters are loaded when the controller is loaded.
+  - Types will not be called if their parameter is missing (no key in the param hash)
+  - All given types must respond to the configured `type_method_name` and an error will be raised when controllers are loaded if they don't.
 
 # License
 

data/lib/paramore.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 require_relative 'paramore/configuration'
 require_relative 'paramore/railtie'
+require_relative 'paramore/types'
+require_relative 'paratype'
 
 module Paramore
   class << self

data/lib/paramore/cast_parameters.rb

@@ -0,0 +1,65 @@
+require_relative 'errors'
+
+module Paramore
+  module CastParameters
+    module_function
+    def run(types_definition, permitted_params)
+      recursive_merge(
+        recursive_typecast(
+          types_definition, permitted_params
+        )
+      )
+    end
+
+    def recursive_merge(nested_hash_array)
+      nested_hash_array.reduce(:merge).map do |param_name, value|
+        if value.is_a?(Array) && value.all? { |_value| _value.is_a?(Hash) }
+          { param_name => recursive_merge(value) }
+        else
+          { param_name => value }
+        end
+      end.reduce(:merge)
+    end
+
+    def recursive_typecast(types_definition, permitted_params)
+      types_definition.map do |param_name, definition|
+        value = permitted_params[param_name]
+
+        if value.nil?
+          if definition.nullable?
+            next { param_name => nil }
+          else
+            raise Paramore::NilParameter, param_name
+          end
+        end
+
+        { param_name => cast(definition, value) }
+      end
+    end
+
+    def cast(definition, value)
+      case definition.type
+      when Hash
+        recursive_typecast(definition.type, value || {})
+      when Array
+        typecast_array(definition, value)
+      else
+        typecast_value(definition.type, value)
+      end
+    end
+
+    def typecast_array(definition, array)
+      array
+        .reject { |unit| unit.to_s == '' && definition.compact? }
+        .map do |unit|
+          if unit.to_s != '' || definition.use_empty_strings?
+            typecast_value(definition.type.first, unit)
+          end
+        end
+    end
+
+    def typecast_value(type, value)
+      type.send(Paramore.configuration.type_method_name, value)
+    end
+  end
+end

data/lib/paramore/cli.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Paramore
   module Cli
     module_function
@@ -12,15 +10,9 @@ module Paramore
       end
 
       File.write(config_file_path, <<~CONF)
-        # frozen_string_literal: true
-
         Paramore.configure do |config|
-          # change this to any level you need, eg.: `'A::B'` for doubly nested formatters
-          # or `nil` for top level formatters
-          # config.formatter_namespace = 'Formatter'
-
-          # what method name to call formatters with
-          # config.formatter_method_name = 'run'
+          # what method name to call types with
+          # config.type_method_name = :[]
         end
       CONF
 

data/lib/paramore/configuration.rb

@@ -1,15 +1,11 @@
-# frozen_string_literal: true
-
 module Paramore
   class Configuration
-    DEFAULT_FORMATTER_NAMESPACE = 'Formatter'
-    DEFAULT_FORMATTER_METHOD_NAME = 'run'
+    DEFAULT_TYPE_METHOD_NAME = :[]
 
-    attr_accessor :formatter_namespace, :formatter_method_name
+    attr_accessor :type_method_name
 
     def initialize
-      @formatter_namespace = DEFAULT_FORMATTER_NAMESPACE
-      @formatter_method_name = DEFAULT_FORMATTER_METHOD_NAME
+      @type_method_name = DEFAULT_TYPE_METHOD_NAME
     end
   end
 end

data/lib/paramore/errors.rb

@@ -0,0 +1,11 @@
+class Paramore::NilParameter < StandardError
+  def initialize(param_name)
+    super("Received a nil `#{param_name}`, but it's type is non nullable!")
+  end
+end
+
+class Paramore::NonParatype < StandardError
+  def initialize(param_name, type)
+    super("`#{param_name}` defined as a `#{type.class}`, expected `Paratype`! Perhaps you declared a plain hash instead of Paratype[{}]?")
+  end
+end

data/lib/paramore/extension.rb

@@ -1,27 +1,44 @@
-# frozen_string_literal: true
-
 require_relative 'validate'
-require_relative 'format'
+require_relative 'cast_parameters'
+require_relative 'permitted_parameter_argument'
 
 module Paramore
   module Extension
-    def declare_params(accessor_name, param_definition)
-      format_definition = param_definition.delete(:format)
+    def paramorize(accessor_name, parameter_configuration)
+      unless parameter_configuration.keys.size == 1
+        raise ArgumentError,
+          "Paramore: exactly one required attribute allowed! Given: #{param_definition.keys}"
+      end
 
-      Validate.run(param_definition, format_definition)
+      required_parameter_name = parameter_configuration.keys.first
+      types_definition = parameter_configuration.values.first
 
-      required = param_definition.keys.first
-      permitted = param_definition.values.first
+      Paramore::Validate.run(types_definition) if types_definition.is_a?(Hash)
 
       define_method(accessor_name) do |rails_parameters = params|
         return instance_variable_get("@#{accessor_name}") if instance_variable_defined?("@#{accessor_name}")
 
-        permitted_params = rails_parameters.require(required).permit(permitted)
+        permitted_parameter_argument =
+          if types_definition.is_a?(Hash)
+            Paramore::PermittedParameterArgument.parse(types_definition)
+          else
+            types_definition
+          end
+
+        permitted_params = rails_parameters
+          .require(required_parameter_name)
+          .permit(permitted_parameter_argument)
+
+        parameter_values =
+          if types_definition.is_a?(Hash)
+            permitted_params.merge(
+              Paramore::CastParameters.run(types_definition, permitted_params)
+            ).permit!
+          else
+            permitted_params.permit!
+          end
 
-        instance_variable_set(
-          "@#{accessor_name}",
-          permitted_params.merge(Format.run(format_definition, permitted_params)).permit!
-        )
+        instance_variable_set("@#{accessor_name}", parameter_values)
       end
     end
   end

data/lib/paramore/permitted_parameter_argument.rb

@@ -0,0 +1,37 @@
+module Paramore
+  module PermittedParameterArgument
+    module_function
+
+    def parse(types_definition)
+      merge_hashes(
+        types_definition.map do |key, definition|
+          case definition
+          when Hash
+            { key => merge_hashes(parse(definition)) }
+          when Paratype
+            case definition.type
+            when Array
+              { key => [] }
+            when Hash
+              { key => merge_hashes(parse(definition.type)) }
+            else
+              key
+            end
+          end
+        end
+      )
+    end
+
+    def merge_hashes(parsed)
+      (flat_parameters(parsed) + nested_parameters(parsed)).compact
+    end
+
+    def flat_parameters(parsed)
+      parsed.select { |arg| arg.is_a?(Symbol) }
+    end
+
+    def nested_parameters(parsed)
+      [parsed.reject { |arg| arg.is_a?(Symbol) }.reduce(:merge)]
+    end
+  end
+end

data/lib/paramore/railtie.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require_relative 'extension'
 
 return unless defined?(Rails)

data/lib/paramore/types.rb

@@ -0,0 +1,52 @@
+module Paramore
+  module BigDecimal
+    module_function
+    def [](input)
+      BigDecimal(input)
+    end
+  end
+
+  module Boolean
+    TRUTHY_TEXT_VALUES = %w[t true 1]
+
+    module_function
+    def [](input)
+      input.in?(TRUTHY_TEXT_VALUES)
+    end
+  end
+
+  module Float
+    module_function
+    def [](input)
+      input.to_f
+    end
+  end
+
+  module Int
+    module_function
+    def [](input)
+      input.to_i
+    end
+  end
+
+  module String
+    module_function
+    def [](input)
+      input.to_s
+    end
+  end
+
+  module StrippedString
+    module_function
+    def [](input)
+      input.to_s.strip
+    end
+  end
+
+  module SanitizedString
+    module_function
+    def [](input)
+      Paramore::StrippedString[input].squeeze(' ')
+    end
+  end
+end

data/lib/paramore/validate.rb

@@ -1,39 +1,24 @@
-# frozen_string_literal: true
-
 module Paramore
   module Validate
     module_function
-    def run(param_definition, format_definition)
-      unless param_definition.keys.size == 1
-        raise ArgumentError,
-          "Paramore: exactly one required attribute allowed! Given: #{param_definition.keys}"
-      end
-
-      return unless format_definition
 
-      formatter_names(format_definition).each do |formatter_name|
-        formatter =
-          begin
-            Paramore::Format.formatter_for(formatter_name)
-          rescue NameError => e
-            raise NameError, "Paramore: formatter `#{formatter_name}` is undefined! #{e}"
-          end
-
-          unless formatter.respond_to?(Paramore.configuration.formatter_method_name)
-            raise NoMethodError,
-              "Paramore: formatter `#{formatter_name}` does not respond to " +
-              "`#{Paramore.configuration.formatter_method_name}`!"
-          end
+    def run(types_definition)
+      types(types_definition).each do |type|
+        unless type.respond_to?(Paramore.configuration.type_method_name)
+          raise NoMethodError,
+            "Paramore: type `#{type}` does not respond to " +
+            "`#{Paramore.configuration.type_method_name}`!"
+        end
       end
     end
 
-    def formatter_names(format_definition)
-      format_definition.flat_map do |_, value|
-        if value.kind_of?(Hash)
-          formatter_names(value)
-        else
-          value
+    def types(types_definition)
+      types_definition.flat_map do |param_name, paratype|
+        unless paratype.is_a?(Paratype)
+          raise Paramore::NonParatype.new(param_name, paratype)
         end
+
+        paratype.type.is_a?(Hash) ? types(paratype.type) : paratype.type
       end.uniq
     end
   end

data/lib/paratype.rb

@@ -0,0 +1,32 @@
+class Paratype
+  def self.[](given_type, null: false, empty: false, compact: false)
+    self.new(given_type, null: null, empty: empty, compact: compact)
+  end
+
+  def initialize(given_type, null:, empty:, compact:)
+    @given_type = given_type
+    @nullable = null
+    @empty = empty
+    @compact = compact
+  end
+
+  def compact?
+    compact
+  end
+
+  def nullable?
+    nullable
+  end
+
+  def use_empty_strings?
+    empty
+  end
+
+  def type
+    given_type
+  end
+
+  private
+
+  attr_reader :given_type, :nullable, :empty, :compact
+end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: paramore
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Lukas Kairevičius
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-09 00:00:00.000000000 Z
+date: 2021-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: combustion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -54,7 +68,7 @@ dependencies:
         version: '5.0'
 description: |
   Paramore lets you declare which parameters are permitted and what object is responsible
-  for formatting/sanitizing/type-casting them before they passed along to your models/processors.
+  for typing/sanitizing/type-casting them before they are passed along to your models/domain.
   It is intended to reduce the amount of imperative code in controllers.
 email: lukas.kairevicius9@gmail.com
 executables:
@@ -66,18 +80,22 @@ files:
 - README.md
 - bin/paramore
 - lib/paramore.rb
+- lib/paramore/cast_parameters.rb
 - lib/paramore/cli.rb
 - lib/paramore/configuration.rb
+- lib/paramore/errors.rb
 - lib/paramore/extension.rb
-- lib/paramore/format.rb
+- lib/paramore/permitted_parameter_argument.rb
 - lib/paramore/railtie.rb
+- lib/paramore/types.rb
 - lib/paramore/validate.rb
+- lib/paratype.rb
 homepage: https://github.com/lumzdas/paramore
 licenses:
 - MIT
 metadata: {}
 post_install_message: |
-  Thank you for installing Paramore 0.2.0 !
+  Thank you for installing Paramore 1.0.1 !
   From the command line you can run `paramore` to generate a configuration file
 
   More details here         : https://github.com/lumzdas/paramore/blob/master/README.md
@@ -96,8 +114,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.0.8
 signing_key: 
 specification_version: 4
-summary: A declarative approach to Rails' strong parameter formatting and sanitizing
+summary: A declarative approach to Rails' strong parameter typing and sanitizing
 test_files: []

data/lib/paramore/format.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-module Paramore
-  module Format
-    module_function
-    def run(format_definition, permitted_params)
-      return {} unless format_definition
-
-      recursive_merge(
-        recursive_format(
-          format_definition, permitted_params
-        )
-      )
-    end
-
-    def recursive_merge(nested_hash_array)
-      nested_hash_array.reduce(:merge).map do |param_name, value|
-        if value.kind_of?(Array) && value.all? { |_value| _value.kind_of?(Hash) }
-          { param_name => recursive_merge(value) }
-        else
-          { param_name => value }
-        end
-      end.reduce(:merge)
-    end
-
-    def recursive_format(format_definition, permitted_params)
-      format_definition.map do |param_name, value|
-        next {} unless permitted_params[param_name]
-
-        if value.kind_of?(Hash)
-          { param_name => recursive_format(value, permitted_params[param_name]) }
-        else
-          { param_name => formatted_value(permitted_params[param_name], formatter_for(value)) }
-        end
-      end
-    end
-
-    def formatted_value(value, formatter)
-      formatter.send(Paramore.configuration.formatter_method_name, value)
-    end
-
-    def formatter_for(formatter_name)
-      Object.const_get(
-        [Paramore.configuration.formatter_namespace, formatter_name].compact.join('::'),
-        false # inherit=false - only get exact match
-      )
-    end
-  end
-end