decanter 2.1.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '06357965a0176a615be643b95e2d874a4220551e1005297e4d00289c030281bf'
-  data.tar.gz: 5b91739498814cf560122667e35be29d000185940a65731411fae870d49dff11
+  metadata.gz: ba861d2437b9eb12f96d0ec704fd942bdc9d1883759b3e30b17b223e936c1c3e
+  data.tar.gz: f475da814ab3af68c80452de399a4f633403b9ff1fb5756087f9f0eac04b7679
 SHA512:
-  metadata.gz: 74e7ae10f60661f911620590d9785eb6fadd3a7f80229b48911b3b82dfd3143b38781d59915db8e4beb506d5d409b1f8190f014b521c119a7deae0ccb5a17a91
-  data.tar.gz: ac9b8c3d70b006f98fe13be3711943567f17adfe8776f71b3ae2ca28690769129cf9391886c51d4053d476e8d1c85786a3a6d281ea7d5b79261009d0875dfd46
+  metadata.gz: cce2d74bc1e8437510b4a10c586f1cfd67d914d63cd9571c88d3290f1fc08d0050e5950c16ced0b9696548c39b93bc0c20329c2633bd60196b48b8acca9f1c2f
+  data.tar.gz: 90a256b4b3a30e18017b7b4cf471b72425446319dd2ca0a516d9ecb475e014f7717dc7071ba5898d24c9720d562991e228edbbc0e15eb5757d4443d3687d3b37

data/.codeclimate.yml

@@ -0,0 +1,38 @@
+engines:
+  rubocop:
+    enabled: true
+    checks:
+      Rubocop/Style/Documentation:
+        enabled: false
+      Rubocop/Metrics/LineLength:
+        enabled: false
+      Rubocop/Rails/Validation:
+        enabled: false
+      Rubocop/Style/IndentationConsistency:
+        enabled: false
+      Rubocop/Style/EmptyLines:
+        enabled: false
+      Rubocop/Style/ClassAndModuleChildren:
+        enabled: false
+      Rubocop/Style/AccessorMethodName:
+        enabled: false
+  golint:
+    enabled: true
+  gofmt:
+    enabled: true
+  eslint:
+    enabled: true
+  csslint:
+    enabled: true
+  brakeman:
+    enabled: false
+  bundler-audit:
+    enabled: true
+ratings:
+   paths:
+   - lib/**
+   - "**.rb"
+exclude_paths:
+- bin/**/*
+- spec/**/*
+- coverage/**/*

data/.gitignore

@@ -0,0 +1,5 @@
+/coverage
+.env
+.DS_Store
+# Builds for push
+decanter-*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.ruby-version

@@ -0,0 +1 @@
+2.6.5

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+
+cache:
+  bundler: true
+
+script:
+  - bundle exec rspec
+
+notifications:
+  email: false

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in goaltender.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,102 @@
+PATH
+  remote: .
+  specs:
+    decanter (3.0.0)
+      actionpack (>= 4.2.10)
+      activesupport
+      rails-html-sanitizer (>= 1.0.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (5.1.4)
+      actionview (= 5.1.4)
+      activesupport (= 5.1.4)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.1.4)
+      activesupport (= 5.1.4)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activesupport (5.1.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    builder (3.2.3)
+    concurrent-ruby (1.0.5)
+    crass (1.0.4)
+    diff-lcs (1.3)
+    docile (1.1.5)
+    dotenv (2.2.1)
+    erubi (1.7.0)
+    i18n (0.9.3)
+      concurrent-ruby (~> 1.0)
+    json (2.1.0)
+    loofah (2.2.2)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    method_source (0.9.0)
+    mini_portile2 (2.3.0)
+    minitest (5.11.3)
+    nokogiri (1.8.5)
+      mini_portile2 (~> 2.3.0)
+    rack (2.0.4)
+    rack-test (0.8.2)
+      rack (>= 1.0, < 3)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.0.4)
+      loofah (~> 2.2, >= 2.2.2)
+    railties (5.1.4)
+      actionpack (= 5.1.4)
+      activesupport (= 5.1.4)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.18.1, < 2.0)
+    rake (10.5.0)
+    rspec-core (3.7.1)
+      rspec-support (~> 3.7.0)
+    rspec-expectations (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-mocks (3.7.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.7.0)
+    rspec-rails (3.7.2)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 3.7.0)
+      rspec-expectations (~> 3.7.0)
+      rspec-mocks (~> 3.7.0)
+      rspec-support (~> 3.7.0)
+    rspec-support (3.7.1)
+    simplecov (0.15.1)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    thor (0.20.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.9)
+  decanter!
+  dotenv
+  rake (~> 10.0)
+  rspec-rails
+  simplecov (~> 0.15.1)
+
+BUNDLED WITH
+   1.17.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 TODO: Write your name
+
+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,232 @@
+# Decanter
+
+Decanter is a Ruby gem that makes it easy to transform incoming data before it hits the model.
+
+```ruby
+gem 'decanter', '~> 3.0'
+```
+
+## Contents
+
+- [Migration guides](#migration-guides)
+- [Basic Usage](#basic-usage)
+  - [Decanters](#decanters)
+  - [Generators](#generators)
+  - [Nested resources](#nested-resources)
+  - [Default parsers](#default-parsers)
+  - [Parser options](#parser-options)
+  - [Exceptions](#exceptions)
+- [Advanced usage](#advanced-usage)
+  - [Custom parsers](#custom-parsers)
+  - [Squashing inputs](#squashing-inputs)
+  - [Chaining parsers](#chaining-parsers)
+  - [Requiring params](#requiring-params)
+  - [Global configuration](#global-configuration)
+
+## Migration Guides
+
+- [v3.0.0](migration-guides/v3.0.0.md)
+
+## Basic Usage
+
+### Decanters
+
+Declare a `Decanter` for a model:
+
+```ruby
+# app/decanters/trip_decanter.rb
+
+class TripDecanter < Decanter::Base
+  input :name, :string
+  input :start_date, :date
+  input :end_date, :date
+end
+```
+
+Transform incoming params in your controller using `Decanter#decant`:
+
+```rb
+# app/controllers/trips_controller.rb
+
+  def create
+    trip_params = TripDecanter.decant(params[:trip])
+    @trip = Trip.new(trip_params)
+
+    # ...any response logic
+  end
+
+```
+
+### Generators
+
+Decanter comes with generators for creating `Decanter` and `Parser` files:
+
+```
+rails g decanter Trip name:string start_date:date end_date:date
+```
+
+```
+rails g parser TruncatedString
+```
+
+### Nested resources
+
+Decanters can declare relationships using `ActiveRecord`-style declarators:
+
+```ruby
+class TripDecanter < Decanter::Base
+  has_many :destinations
+end
+```
+
+### Default parsers
+
+Decanter comes with the following parsers out of the box:
+
+- `:boolean`
+- `:date`
+- `:date_time`
+- `:float`
+- `:integer`
+- `:pass`
+- `:phone`
+- `:string`
+- `:array`
+
+Note: these parsers are designed to operate on a single value, except for `:array`. This parser expects an array, and will use the `parse_each` option to call a given parser on each of its elements:
+
+```ruby
+input :ids, :array, parse_each: :integer
+```
+
+### Parser options
+
+Parsers can receive options that modify their behavior. These options are passed in as named arguments to `input`:
+
+```ruby
+input :start_date, :date, parse_format: '%Y-%m-%d'
+```
+
+This decanter will look up and apply the corresponding `DestinationDecanter` whenever necessary to transform nested resources.
+
+### Exceptions
+
+By default, `Decanter#decant` will raise an exception when unexpected parameters are passed. To override this behavior, you can disable strict mode:
+
+```ruby
+class TripDecanter <  Decanter::Base
+  strict false
+  # ...
+end
+```
+
+Or explicitly ignore a key:
+
+```rb
+class TripDecanter <  Decanter::Base
+  ignore :created_at, :updated_at
+  # ...
+end
+```
+
+You can also disable strict mode globally using a [global configuration](#global-configuration) setting.
+
+## Advanced Usage
+
+### Custom Parsers
+
+To add a custom parser, first create a parser class:
+
+```rb
+# app/parsers/truncate_string_parser.rb
+class TruncateStringParser < Decanter::Parser::ValueParser
+
+  parser do |value, options|
+    length = options.fetch(:length, 100)
+    value.truncate(length)
+  end
+end
+```
+
+Then, use the appropriate key to look up the parser:
+
+```ruby
+  input :name, :truncate_string #=> TruncateStringParser
+```
+
+#### Custom parser methods
+
+- `#parse <block>`: (required) recieves a block for parsing a value. Block parameters are `|value, options|` for `ValueParser` and `|name, value, options|` for `HashParser`.
+- `#allow [<class>]`: skips parse step if the incoming value `is_a?` instance of class(es).
+- `#pre [<parser>]`: applies the given parser(s) before parsing the value.
+
+#### Custom parser base classes
+
+- `Decanter::Parser::ValueParser`: subclasses are expected to return a single value.
+- `Decanter::Parser::HashParser`: subclasses are expected to return a hash of keys and values.
+
+### Squashing inputs
+
+Sometimes, you may want to take several inputs and combine them into one finished input prior to sending to your model. You can achieve this with a custom parser:
+
+```ruby
+class TripDecanter < Decanter::Base
+  input [:day, :month, :year], :squash_date, key: :start_date
+end
+```
+
+```ruby
+class SquashDateParser < Decanter::Parser::ValueParser
+  parser do |values, options|
+    day, month, year = values.map(&:to_i)
+    Date.new(year, month, day)
+  end
+end
+```
+
+### Chaining parsers
+
+You can compose multiple parsers by using the `#pre` method:
+
+```ruby
+class FloatPercentParser < Decanter::Parser::ValueParser
+
+  pre :float
+
+  parser do |val, options|
+    val / 100
+  end
+end
+```
+
+Or by declaring multiple parsers for a single input:
+
+```ruby
+class SomeDecanter < Decanter::Base
+  input :some_percent, [:float, :percent]
+end
+```
+
+### Requiring params
+
+If you provide the option `:required` for an input in your decanter, an exception will be thrown if the parameter is `nil` or an empty string.
+
+```ruby
+class TripDecanter <  Decanter::Base
+  input :name, :string, required: true
+end
+```
+
+_Note: we recommend using [Active Record validations](https://guides.rubyonrails.org/active_record_validations.html) to check for presence of an attribute, rather than using the `required` option. This method is intended for use in non-RESTful routes or cases where Active Record validations are not available._
+
+### Global configuration
+
+You can generate a local copy of the default configuration with `rails generate decanter:install`. This will create an initializer where you can do global configuration:
+
+```ruby
+# ./config/initializers/decanter.rb
+
+Decanter.config do |config|
+  config.strict = false
+end
+```

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/console

@@ -1,8 +1,7 @@
 #!/usr/bin/env ruby
-# frozen_string_literal: true
 
-require 'bundler/setup'
-require 'decanter'
+require "bundler/setup"
+require "decanter"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -11,5 +10,5 @@ require 'decanter'
 # require "pry"
 # Pry.start
 
-require 'irb'
+require "irb"
 IRB.start