safe_type 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b5ef8f748c40fe69ebe9bde7525c18a26227e922
-  data.tar.gz: c5dbba13dd9778bc27048e4f78ad80f1a81d8c80
+  metadata.gz: 129ba2fcf5b08749ade1b5a843a39939875dc9ee
+  data.tar.gz: 356f3af3411031f961ff7c5716dc7a631227db65
 SHA512:
-  metadata.gz: 18b50e3f3ffdd15d9fb98242ddd44e32777c9f7add2a9c3539177c5226e2934092a98832f284107fa9168a06ba84fcc899a05dd4c8147beb5850857c140816f3
-  data.tar.gz: b4a87e49171f26eff48bda4bee778780fd67c5b3e45e199ddf6f4d5fbd1189db5405ae8fccb52a512cf55ec2a7007dbb18a3b0b0bed030462c2ee97e413dbb52
+  metadata.gz: 314e4f6f4ca111a75c0fe924b63952e48efdce36d75947ee0811f488b98829734a1c2ab69562bc66bd68f093858ad6f397733001328236e40948e38c56169e26
+  data.tar.gz: 77727ad30bb03c10fea5db6cf380176d9eb69bb828dc1855239ada81a6d8c840726b77918a41d5973975c4b93f084c1baa0e96e080f3ddac47d4ee07f16c0c3b

data/.gitignore

@@ -0,0 +1,11 @@
+.bundle
+Gemfile.lock
+*.gem
+coverage
+tags
+
+# Swap
+[._]*.s[a-v][a-z]
+[._]*.sw[a-p]
+[._]s[a-v][a-z]
+[._]sw[a-p]

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require ./spec/spec_helper

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+
+rvm:
+  - 2.2.9
+  - 2.3.5
+  - 2.4.3
+  - 2.5.0
+
+bundler_args: --binstubs
+
+before_install:
+  - gem install bundler --no-doc
+
+script:
+  - bundle exec rake
+
+after_success:
+  - bundle exec codeclimate-test-reporter

data/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing 
+
+## Issues
+If there are any issues, feel free to create an issue on the GitHub repository issue page.
+
+## Development 
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to rubygems.org.
+
+If there are issues with running the `bin` files, try to `chmod +x bin/*` the files first.
+
+## Contribution Guidelines
+1.  Make commits that are logically well isolated and have descriptive commit messages.
+ 
+2.  Make sure that there are tests in the [spec](./spec) directory for the code you wrote.
+
+3.  Make sure that changes to public methods or interfaces are documented in this README.
+
+4.  Run tests and address any errors.
+
+5.  Open a pull request with a descriptive message that describes the change, the need, and verification that the change is tested.

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem "codeclimate-test-reporter", require: false
+  gem 'simplecov', require: false
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Chan Zuckerberg Initiative 
+
+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

@@ -1,18 +1,16 @@
 ---
-SafeType
+safe_type
 ---
 [![Gem Version](https://badge.fury.io/rb/safe_type.svg)](https://badge.fury.io/rb/safe_type)
 [![Build Status](https://travis-ci.org/chanzuckerberg/safe_type.svg?branch=master)](https://travis-ci.org/chanzuckerberg/safe_type)
 [![Maintainability](https://api.codeclimate.com/v1/badges/7fbc9a4038b86ef639e1/maintainability)](https://codeclimate.com/github/chanzuckerberg/safe_type/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/7fbc9a4038b86ef639e1/test_coverage)](https://codeclimate.com/github/chanzuckerberg/safe_type/test_coverage)
 
-While working with environment variables, routing parameters, API responses,
-  or other Hash-like objects require parsing,
-  we often need type coercion to assure expected behaviors.
+While working with environment variables, routing parameters, network responses, or other Hash-like objects that require parsing, we often need type coercion to assure expected behaviors.
 
-***SafeType*** provides an intuitive type coercion interface and type enhancement.
+***safe_type*** provides an intuitive type coercion interface and type enhancement.
 
-# Install
+# Installation
 
 We can install `safe_type` using `gem install`: 
 
@@ -69,7 +67,7 @@ SafeType::coerce!(params, rules)
 params["course_id"]       # => 101
 params["start_date"]      # => <Date: 2018-10-01 ((2458393j,0s,0n),+0s,2299161j)>
 ```
-## JSON Response
+## Ruby Hashes
 ```ruby
 json = {
   "names" => ["Alice", "Bob", "Chris"],
@@ -99,7 +97,7 @@ SafeType::coerce!(json, {
   ]
 })
 ```
-## Http Response
+## Network Responses 
 ```ruby
 class ResponseType; end
 
@@ -129,7 +127,7 @@ The parameters are
 - `required` indicates whether empty values are allowed
 
 ## `strict` vs `default`
-The primitive types in *SafeType* provide `default` and `strict` mode, which are
+The primitive types in `SafeType` provide `default` and `strict` mode, which are
 - `SafeType::Boolean`
 - `SafeType::Date`
 - `SafeType::DateTime`
@@ -139,13 +137,13 @@ The primitive types in *SafeType* provide `default` and `strict` mode, which are
 - `SafeType::Symbol`
 - `SafeType::Time`
 
-Under the hood, they are all just SafeType rules.
+Under the hood, they are all just `Rule` classes with parameters:
 - `default`: a rule with default value specified
 - `strict`: a rule with `required: true`, so no empty values are allowed, or it throws `EmptyValueError`
 
-## Apply the rules
-As we've seen in the use cases, we can call `coerce` to apply a set of `SafeType::Rule`s.
-Rules can be bundled together as elements in an array or values in a hash.
+## Apply the Rules
+As we've seen in the use cases, we can call `coerce` to apply a set of `SafeType::Rule` classes.
+`Rule` classes can be bundled together as elements in an array or values in a hash.
 
 ### `coerce` vs `coerce!`
 - `SafeType::coerce` returns a new object, corresponding to the rules. The unspecified fields will not be included in the new object.
@@ -162,7 +160,7 @@ Note those two examples are equivalent:
 SafeType::coerce(ENV["PORT"], SafeType::Integer.default(3000))
 SafeType::Integer.default(3000).coerce(ENV["PORT"])
 ``` 
-For the *SafeType* primitive types, applying the rule on the class itself will use the default rule.
+For the `SafeType` primitive types, applying the rule on the class itself will use the default rule.
 
 ## Customized Types
 We can inherit from a `SafeType::Rule` to create a customized type.
@@ -174,15 +172,13 @@ We can override following methods if needed:
 - Override `handle_exceptions` to change the behavior of exceptions handling (e.g: send to the logger, or no exception) 
 - Override `default` or `strict` to modify the default and strict rule.
 
-# Prior Art
-This gem was inspired by [rails_param](https://github.com/nicolasblanco/rails_param)
-and [dry-types](https://github.com/dry-rb/dry-types). `dry-types` has a complex interface. 
-Also it does not support in place coercion, and it will be complicated to `ENV` since the design of its
-`Hash Schemas`. `rails_param` relies on Rails and it is only for the `params`. 
-Therefore, `safe_type` was created. It integrated some ideas from both gems, 
-and it was designed specifically for type checking to provide an clean and easy-to-use interface.
-It should be useful when working with any string or hash where the values are coming from an external source, 
-such as `ENV` variables, rails `params`, or API calls.
-
-## License
-`safe_type` is released under an MIT license.
+## Prior Art
+`safe_type` pulls heavy inspiration from [dry-types](https://github.com/dry-rb/dry-types) and [rails_param](https://github.com/nicolasblanco/rails_param).
+The interface in `safe_type` looks similar to the interface in `dry-types`, however, `safe_type` supports some additional features such as in-place coercion
+using the Ruby bang method interface and the ability to define schemas using Ruby hashes and arrays. `safe_type` also borrows some concepts from `rails_param`, 
+but with some fundamental differences such as `safe_type` not relying  on Rails and `safe_type` not having a focus on only typing Rails controller parameters.
+The goal of `safe_type` is to provide a good tradeoff between complexity and flexibility by enabling type checking through a clean and easy-to-use interface.
+`safe_type` should be useful when working with any string or hash where the values could be ambiguously typed, such as `ENV` variables, rails `params`, or network responses..
+
+# License
+The `safe_type` project is licensed and available open source under the terms of the [MIT license](http://opensource.org/licenses/MIT). 

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = ['--format progress']
+end
+
+task :default => :spec

data/lib/safe_type.rb

@@ -12,12 +12,12 @@ require 'safe_type/primitive/time'
 
 module SafeType
   class << self
-    def coerce(input, rule)
-      return rule.coerce(input) if rule.is_a?(SafeType::Rule)
+    def coerce(input, rule, coerce_key=nil)
+      return rule.coerce(input, coerce_key) if rule.is_a?(SafeType::Rule)
       if rule.class == ::Hash
         result = {}
         rule.each do |key, val|
-          result[key] = coerce(input[key], val)
+          result[key] = coerce(input[key], val, key)
         end
         return result
       end
@@ -26,7 +26,7 @@ module SafeType
         result = ::Array.new(input.length)
         i = 0
         while i < input.length
-          result[i] = coerce(input[i], rule[i % rule.length])
+          result[i] = coerce(input[i], rule[i % rule.length], i)
           i += 1
         end
         return result
@@ -40,7 +40,7 @@ module SafeType
           if val.class == ::Hash
             coerce!(input[key], val)
           else
-            input[key] = coerce(input[key], val)
+            input[key] = coerce(input[key], val, key)
           end
         end
         return nil
@@ -48,7 +48,7 @@ module SafeType
       if rule.class == ::Array
         i = 0
         while i < input.length
-          input[i] = coerce(input[i], rule[i % rule.length])
+          input[i] = coerce(input[i], rule[i % rule.length], i)
           i += 1
         end
         return nil

data/lib/safe_type/errors.rb

@@ -1,27 +1,52 @@
 module SafeType
-  class Error < StandardError; end
 
-  class CoercionError < Error
-    def initialize(message="unable to transform into the requested type")
-      super
+  class CoercionError < StandardError 
+    attr_reader :key
+    attr_reader :value
+    attr_reader :desired_type
+
+    def initialize(value, desired_type, key=nil)
+      super("Could not coerce " + (key.nil? ? '' : "key (#{key}) with ")  +
+            "value (#{value.inspect}) of type (#{value.class}) to desired type (#{desired_type})")
+
+      @key = key
+      @value = value
+      @desired_type = desired_type
     end
   end
 
-  class ValidationError < Error
-    def initialize(message="failed to validate")
-      super
+  class ValidationError < StandardError
+    attr_reader :key
+    attr_reader :value
+    attr_reader :desired_type
+
+    def initialize(value, desired_type, key=nil)
+      super("Validation for " + (key.nil? ? '' : "key (#{key}) with ")  +
+            "value (#{value.inspect}) of " +
+            "type (#{value.class}) to desired type (#{desired_type}) has failed")
+
+      @key = key
+      @value = value
+      @desired_type = desired_type
     end
   end
 
-  class EmptyValueError < Error
-    def initialize(message="the value should not be empty")
-      super
+  class EmptyValueError < StandardError
+    attr_reader :key
+    attr_reader :desired_type
+
+    def initialize(desired_type, key=nil)
+      super("Expected a " + (key.nil? ? '' : "key (#{key}) with ")  +
+            "value of desired type (#{desired_type}), but received a nil value")
+
+      @key = key
+      @desired_type = desired_type
     end
   end
 
   class InvalidRuleError < ArgumentError
-    def initialize(message="invalid coercion rule")
-      super
+    def initialize()
+      super("Coercion rule does not exist or is not valid")
     end
   end
 end

data/lib/safe_type/rule.rb

@@ -24,10 +24,6 @@ module SafeType
       input
     end
 
-    def handle_exceptions(e)
-      raise SafeType::CoercionError
-    end
-
     def self.coerce(input)
       default.coerce(input)
     end
@@ -40,19 +36,19 @@ module SafeType
       new(required: true)
     end
 
-    def coerce(input)
-      raise SafeType::EmptyValueError if input.nil? && @required
+    def coerce(input, key=nil)
+      raise SafeType::EmptyValueError.new(@type, key) if input.nil? && @required
       input = before(input)
       input = Converter.to_type(input, @type)
-      raise SafeType::ValidationError unless is_valid?(input)
+      raise SafeType::ValidationError.new(input, @type, key) unless is_valid?(input)
       result = after(input)
-      raise SafeType::EmptyValueError if result.nil? && @required
+      raise SafeType::EmptyValueError.new(@type, key) if result.nil? && @required
       return @default if result.nil?
-      raise SafeType::CoercionError unless result.is_a?(@type)
+      raise SafeType::CoercionError.new(result, @type, key) unless result.is_a?(@type)
       result
-    rescue TypeError, ArgumentError, NoMethodError => e
+    rescue TypeError, ArgumentError, NoMethodError
       return @default if input.nil? && !@required
-      handle_exceptions(e)
+      raise SafeType::CoercionError.new(input, @type, key)
     end
   end
 end

data/safe_type.gemspec

@@ -0,0 +1,22 @@
+Gem::Specification.new do |s|
+  s.name        = 'safe_type'
+  s.version     = '1.1.0'
+  s.date        = '2018-07-18'
+  s.summary     = 'Type Coercion & Type Enhancement'
+  s.description = %q{ 
+    Type Coercion & Type Enhancement
+  }
+  s.authors     = ['Donald Dong', 'Edmund Loo', 'Jacob Gable']
+  s.email       = ['mail@ddong.me', 'edmundloo@outlook.com', 'jgable@chanzuckerberg.com']
+  s.homepage    = 'https://github.com/chanzuckerberg/safe_type'
+  s.license     = 'MIT'
+  s.files       = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) } - ['bin/console', 'bin/setup']
+
+  s.rdoc_options = ['--charset=UTF-8']
+  s.require_paths = ['lib']
+
+  s.add_development_dependency 'bundler', '~> 1.16'
+  s.add_development_dependency 'rake', '~> 12.3'
+  s.add_development_dependency 'rspec', '~> 3.8'
+
+end

metadata

@@ -1,50 +1,76 @@
 --- !ruby/object:Gem::Specification
 name: safe_type
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Donald Dong
+- Edmund Loo
+- Jacob Gable
 autorequire: 
 bindir: bin
 cert_chain: []
 date: 2018-07-18 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '12.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '12.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: " \n    Type coercion & Type Enhancement\n  "
-email: mail@ddong.me
+        version: '3.8'
+description: " \n    Type Coercion & Type Enhancement\n  "
+email:
+- mail@ddong.me
+- edmundloo@outlook.com
+- jgable@chanzuckerberg.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE
 - README.md
+- Rakefile
 - lib/safe_type.rb
 - lib/safe_type/converter.rb
 - lib/safe_type/errors.rb
@@ -59,6 +85,7 @@ files:
 - lib/safe_type/primitive/symbol.rb
 - lib/safe_type/primitive/time.rb
 - lib/safe_type/rule.rb
+- safe_type.gemspec
 homepage: https://github.com/chanzuckerberg/safe_type
 licenses:
 - MIT
@@ -80,8 +107,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2.1
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
-summary: Type coercion & Type Enhancement
+summary: Type Coercion & Type Enhancement
 test_files: []