paramore 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 78c8a8c6985a0f9044fa608f0473cbd6ce872c5ff7f9626a2fb6e49f39c67f69
+  data.tar.gz: c6c18de5f2dd039d06044ba58f7c4bfc38dda160fd6730213748c883529f8823
+SHA512:
+  metadata.gz: e406c95c757d7c583fb5d962f4b453c8dbda6dc141ad581169aab7ba767e2903723eb31c830ef8f55b98e5a12606feb578644141800e64a154217c0cd2f886e0
+  data.tar.gz: 9061803ea9cdcccd492bb58f280d0037e01870c61d7dd30d8fad1d1ceabcb580f0e715531cf71ceff6fb8f875f60810ec95d7cfbedb14594f6fc65e85d491a1e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Lumzdas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# 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.
+
+# Installation
+
+
+In your Gemfile:
+```ruby
+gem 'paramore'
+```
+
+In your terminal:
+```sh
+$ bundle
+```
+
+# Usage
+
+<h3>Without formatting/sanitizing</h3>
+
+```ruby
+declare_params :item_params
+  item: [:name, :description, :for_sale, :price, metadata: [tags: []]]
+```
+
+This is completely equivalent (including return type) to
+
+```ruby
+def item_params
+  @item_params ||= params
+    .require(:item)
+    .permit(:name, :description, :for_sale, :price, metadata: [tags: []])
+end
+```
+
+<h3>With formatting/sanitizing</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.
+A naive approach could be:
+
+```ruby
+# items_controller.rb
+
+def item_params
+  @item_params ||= begin
+    _params = params
+      .require(:item)
+      .permit(:name, :description, :price, metadata: [tags: []])
+
+    _params[:name] = _params[:name].strip.squeeze(' ') if _params[:name]
+    _params[:description] = _params[:description].strip.squeeze(' ') if _params[:description]
+    _params[:for_sale] = _params[:for_sale].in?('t', 'true', '1') if _params[:for_sale]
+    _params[:price] = _params[:price].to_d if _params[:price]
+    if _params.dig(:metadata, :tags)
+      _params[:metadata][:tags] =
+        _params[:metadata][:tags].map { |tag_id| Item.tags[tag_id.to_i] }
+    end
+
+    _params
+  end
+end
+```
+
+This approach clutters controllers with procedures to clean data, which leads to repetition and difficulties refactoring.
+The next logical step is extracting those procedures - this is where Paramore steps in:
+
+```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(' ')
+  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
+end
+```
+```ruby
+# app/formatter/decimal.rb
+
+module Formatter::Decimal
+  module_function
+  def run(input)
+    input.to_d
+  end
+end
+```
+```ruby
+# app/formatter/item_tags.rb
+
+module Formatter::ItemTags
+  module_function
+  def run(input)
+    input.map { |tag_id| Item.tags[tag_id.to_i] }
+  end
+end
+```
+
+
+Now, given `params` are:
+```ruby
+<ActionController::Parameters {
+  "unpermitted"=>"parameter",
+  "name"=>"Shoe  \n",
+  "description"=>"Black,  with laces",
+  "for_sale"=>"true",
+  "price"=>"39.99",
+  "metadata"=><ActionController::Parameters { "tags"=>["38", "112"] } permitted: false>
+} permitted: false>
+```
+Calling `item_params` will return:
+```ruby
+<ActionController::Parameters {
+  "name"=>"Shoe",
+  "description"=>"Black, with laces",
+  "for_sale"=>true,
+  "price"=>39.99,
+  "metadata"=><ActionController::Parameters { "tags"=>[:shoe, :new] } permitted: true>
+} permitted: true>
+```
+
+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.
+
+<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
+
+<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.
+
+# License
+
+Paramore is released under the MIT license:
+
+* https://opensource.org/licenses/MIT

data/bin/paramore

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative '../lib/paramore/cli'
+
+Paramore::Cli.config!

data/lib/paramore.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'paramore/configuration'
+require_relative 'paramore/railtie'
+
+module Paramore
+  class << self
+    attr_reader :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Paramore::Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/paramore/cli.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Paramore
+  module Cli
+    module_function
+    def config!
+      config_file_path = 'config/initializers/paramore.rb'
+
+      if File.exists?(config_file_path)
+        puts "#{config_file_path} already exists, skipping"
+        exit 0
+      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'
+        end
+      CONF
+
+      puts "#{config_file_path} created"
+    end
+  end
+end

data/lib/paramore/configuration.rb

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

data/lib/paramore/extension.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'validate'
+require_relative 'format'
+
+module Paramore
+  module Extension
+    def declare_params(accessor_name, param_definition)
+      format_definition = param_definition.delete(:format)
+
+      Validate.run(param_definition, format_definition)
+
+      required = param_definition.keys.first
+      permitted = param_definition.values.first
+
+      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)
+
+        instance_variable_set(
+          "@#{accessor_name}",
+          permitted_params.merge(Format.run(format_definition, permitted_params)).permit!
+        )
+      end
+    end
+  end
+end

data/lib/paramore/format.rb

@@ -0,0 +1,49 @@
+# 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

data/lib/paramore/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'extension'
+
+return unless defined?(Rails)
+
+module Paramore
+  class Railtie < Rails::Railtie
+    initializer 'paramore.action_controller' do
+      ActiveSupport.on_load(:action_controller) do
+        ActionController::Base.extend(Paramore::Extension)
+        ActionController::API.extend(Paramore::Extension)
+      end
+    end
+  end
+end

data/lib/paramore/validate.rb

@@ -0,0 +1,40 @@
+# 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
+      end
+    end
+
+    def formatter_names(format_definition)
+      format_definition.flat_map do |_, value|
+        if value.kind_of?(Hash)
+          formatter_names(value)
+        else
+          value
+        end
+      end.uniq
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: paramore
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Lukas Kairevičius
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-09-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        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.
+  It is intended to reduce the amount of imperative code in controllers.
+email: lukas.kairevicius9@gmail.com
+executables:
+- paramore
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/paramore
+- lib/paramore.rb
+- lib/paramore/cli.rb
+- lib/paramore/configuration.rb
+- lib/paramore/extension.rb
+- lib/paramore/format.rb
+- lib/paramore/railtie.rb
+- lib/paramore/validate.rb
+homepage: https://github.com/lumzdas/paramore
+licenses:
+- MIT
+metadata: {}
+post_install_message: |
+  Thank you for installing Paramore 0.2.0 !
+  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
+  Feel free to report issues: https://github.com/lumzdas/paramore/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: A declarative approach to Rails' strong parameter formatting and sanitizing
+test_files: []