contracted_value 0.1.0.alpha.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1475b67e1a9de52ca20803fc2b32de21ce69a061b772c0d089bfc3e11dceea1f
+  data.tar.gz: 8b80844c114b4224ac252cbcb5694d418a31b586ee69a12c22ef194cba05dc6e
+SHA512:
+  metadata.gz: 5956bdb3fc30b074a6443bd014ab8be70e431676d5c4c3b552568539e364c8b2f2f53679991bd840035c8011364204de205cb22283ff5a8eac84988da81bbc3d
+  data.tar.gz: a1ee38d4e9a23d95397133e6e6b1fe28884c122cf453a508ead4b1ffb49f2ee949e52d53a545a2410d14c3a1485a2d591df6352d13e0f40fe8ab4da1f35e9fdb

data/.codeclimate.yml

@@ -0,0 +1,17 @@
+---
+engines:
+  duplication:
+    enabled: true
+    config:
+      languages:
+      - ruby
+  fixme:
+    enabled: true
+  rubocop:
+    enabled: true
+    channel: rubocop-0-70
+ratings:
+  paths:
+  - "**.rb"
+exclude_paths:
+- spec/

data/.editorconfig

@@ -0,0 +1,24 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# default configuration
+[*]
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# Unix-style newlines with a newline ending every file
+end_of_line = lf
+
+# Set default charset
+charset = utf-8
+
+# Tab indentation (no size specified)
+[Makefile]
+indent_style = tab
+
+[*.{md,markdown}]
+trim_trailing_whitespace = false

data/.gitignore

@@ -0,0 +1,35 @@
+# Because this is a gem, ignore Gemfile.lock:
+
+Gemfile.lock
+
+# And because this is Ruby, ignore the following
+#  (source: https://github.com/github/gitignore/blob/master/Ruby.gitignore):
+
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+
+# IDEA
+/.idea/
+
+# RSpec
+/.rspec
+
+# Appraisal
+/gemfiles/.bundle/
+/gemfiles/*.gemfile.lock

data/.rubocop.yml

@@ -0,0 +1,41 @@
+---
+AllCops:
+  Exclude:
+    - "Gemfile*"
+    - "gemfiles/**/*"
+    - "spec/**/*"
+    - "node_modules/**/*"
+  TargetRubyVersion: 2.4
+
+Layout/DotPosition:
+  Enabled: true
+  Severity: warning
+  EnforcedStyle: trailing
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+Style/RaiseArgs:
+  Enabled: false
+Style/StringLiterals:
+  Enabled: true
+  Severity: warning
+  EnforcedStyle: double_quotes
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  Severity: warning
+  EnforcedStyle: double_quotes
+Style/TrailingCommaInArguments:
+  Enabled: true
+  Severity: warning
+  EnforcedStyleForMultiline: consistent_comma
+Style/TrailingCommaInArrayLiteral:
+  Enabled: true
+  Severity: warning
+  EnforcedStyleForMultiline: consistent_comma
+Style/TrailingCommaInHashLiteral:
+  Enabled: true
+  Severity: warning
+  EnforcedStyleForMultiline: consistent_comma

data/.travis.yml

@@ -0,0 +1,25 @@
+# Send builds to container-based infrastructure
+# http://docs.travis-ci.com/user/workers/container-based-infrastructure/
+sudo: false
+language: ruby
+before_install:
+  # This is required since 2.6.8 has issue when installing `rainbow`
+  # https://github.com/sickill/rainbow/issues/48
+  - gem update --system
+  - gem --version
+cache:
+  - bundler
+rvm:
+  - 2.4
+  - 2.5
+  - 2.6
+  - 2.7
+  - ruby-head
+gemfile:
+  - gemfiles/contracts_15_0.gemfile
+  - gemfiles/contracts_16_0.gemfile
+matrix:
+  fast_finish: true
+  allow_failures:
+    - rvm: 2.7
+    - rvm: ruby-head

data/Appraisals

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+appraise "contracts_15_0" do
+  gem "contracts", "~> 0.15.0"
+end
+
+appraise "contracts_16_0" do
+  gem "contracts", "~> 0.16.0"
+end

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT LICENSE
+
+Copyright (c)  PikachuEXE <pikachuexe@gmail.com>
+
+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,346 @@
+# ContractedValue
+
+Library for creating contracted immutable(by default) value objects
+
+[![Build Status](http://img.shields.io/travis/PikachuEXE/contracted_value.svg?style=flat-square)](https://travis-ci.org/PikachuEXE/contracted_value)
+
+[![Code Climate](https://img.shields.io/codeclimate/maintainability/PikachuEXE/contracted_value.svg?style=flat-square)](https://codeclimate.com/github/PikachuEXE/contracted_value)
+[![Coverage Status](https://img.shields.io/codecov/c/github/PikachuEXE/contracted_value.svg?style=flat-square)](https://codecov.io/gh/PikachuEXE/contracted_value)
+[![Inch CI](https://inch-ci.org/github/PikachuEXE/contracted_value.svg?branch=master)](https://inch-ci.org/github/PikachuEXE/contracted_value)
+
+
+This gem allows creation of value objects which are
+- contracted (enforced by [`contracts.ruby`](https://github.com/egonSchiele/contracts.ruby))
+- immutable (enforced by [`ice_nine`](https://github.com/dkubb/ice_nine))
+
+See details explanation in below sections
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+# `require` can be set to `true` safely without too much side effect
+# (except having additional modules & classes defined which could be wasting memory).
+# But there is no point requiring it unless in test
+# Also maybe add it inside a "group"
+gem "contracted_value", require: false
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install contracted_value
+```
+
+
+## Usage
+
+The examples below might contain some of my habbits,  
+like including [`contracts.ruby`](https://github.com/egonSchiele/contracts.ruby) modules in class  
+You **don't** have to do it  
+
+
+### Attribute Declaration
+
+You can declare with or without contract/default value
+But an attribute **cannot** be declared twice
+
+```ruby
+module ::Geometry
+end
+
+module ::Geometry::LocationRange
+  class Entry < ::ContractedValue::Value
+    include ::Contracts::Core
+    include ::Contracts::Builtin
+
+    attribute(
+      :latitude,
+      contract: Numeric,
+    )
+    attribute(
+      :longitude,
+      contract: Numeric,
+    )
+
+    attribute(
+      :radius_in_meter,
+      contract: And[Numeric, Send[:positive?]],
+    )
+
+    attribute(
+      :latitude,
+    ) # => error, declared already
+  end
+end
+
+location_range = ::Geometry::LocationRange::Entry.new(
+  latitude:         22.2,
+  longitude:        114.4,
+  radius_in_meter:  1234,
+)
+```
+
+
+### Attribute Assignment
+
+Only `Hash` and `ContractedValue::Value` can be passed to `.new`
+
+```ruby
+module ::Geometry
+end
+
+module ::Geometry::Location
+  class Entry < ::ContractedValue::Value
+    include ::Contracts::Core
+    include ::Contracts::Builtin
+
+    attribute(
+      :latitude,
+      contract: Numeric,
+    )
+    attribute(
+      :longitude,
+      contract: Numeric,
+    )
+  end
+end
+
+module ::Geometry::LocationRange
+  class Entry < ::ContractedValue::Value
+    include ::Contracts::Core
+    include ::Contracts::Builtin
+
+    attribute(
+      :latitude,
+      contract: Numeric,
+    )
+    attribute(
+      :longitude,
+      contract: Numeric,
+    )
+
+    attribute(
+      :radius_in_meter,
+      contract: Maybe[And[Numeric, Send[:positive?]]],
+      default_value: nil,
+    )
+  end
+end
+
+location = ::Geometry::Location::Entry.new(
+  latitude:   22.2,
+  longitude:  114.4,
+)
+location_range = ::Geometry::LocationRange::Entry.new(location)
+
+```
+
+
+### Input Validation
+
+Input values are validated on object creation (instead of on attribute value access) with 2 validations:
+- Value contract
+- Value presence
+
+#### Value contract
+An attribute can be declared without any contract, and any input value would be pass the validation
+But you can pass a contract via `contract` option (must be a [`contracts.ruby`](https://github.com/egonSchiele/contracts.ruby) contract)
+Passing input value violating an attribute's contract would cause an error
+
+```ruby
+class YetAnotherRationalNumber < ::ContractedValue::Value
+  include ::Contracts::Core
+  include ::Contracts::Builtin
+
+  attribute(
+    :numerator,
+    contract: ::Integer,
+  )
+  attribute(
+    :denominator,
+    contract: And[::Integer, Not[Send[:zero?]]],
+  )
+end
+
+YetAnotherRationalNumber.new(
+  numerator: 1, 
+  denominator: 0, 
+) # => Error
+
+```
+
+#### Value presence
+An attribute declared should be provided a value on object creation, even the input value is `nil`
+Otherwise an error is raised
+You can pass default value via option `default_value`
+The default value will need to confront to the contract passed in `contract` option too
+
+
+```ruby
+module ::WhatIsThis
+  class Entry < ::ContractedValue::Value
+    include ::Contracts::Core
+    include ::Contracts::Builtin
+
+    attribute(
+      :something_required,
+    )
+    attribute(
+      :something_optional,
+      default_value: nil,
+    )
+    attribute(
+      :something_with_error,
+      contract: NatPos,
+      default_value: 0,
+    ) # => error
+  end
+end
+
+WhatIsThis::Entry.new(
+  something_required: 123,
+).something_optional # => nil
+```
+
+
+### Object Freezing
+All input values are frozen using [`ice_nine`](https://github.com/dkubb/ice_nine) by default  
+But some objects won't work properly when deeply frozen (rails obviously)  
+So you can specify how input value should be frozen (or not frozen) with option `refrigeration_mode`  
+Possible values are:
+- `:deep` (default)
+- `:shallow`
+- `:none`
+
+However the value object itself is always frozen  
+Any lazy method caching with use of instance var would cause `FrozenError`  
+(Many Rails classes use lazy caching heavily so most rails object can't be frozen to work properly)  
+
+```ruby
+class SomeDataEntry < ::ContractedValue::Value
+  include ::Contracts::Core
+  include ::Contracts::Builtin
+
+  attribute(
+    :cold_hash,
+    contract: ::Hash,
+  )
+  attribute(
+    :cool_hash,
+    contract: ::Hash,
+    refrigeration_mode: :shallow,
+  )
+  attribute(
+    :warm_hash,
+    contract: ::Hash,
+    refrigeration_mode: :none,
+  )
+  
+  def cached_hash
+    @cached_hash ||= {}
+  end
+end
+
+entry = SomeDataEntry.new(
+  cold_hash: {a: {b: 0}},
+  cool_hash: {a: {b: 0}},
+  warm_hash: {a: {b: 0}},
+)
+
+entry.cold_hash[:a].delete(:b) # => `FrozenError`
+
+entry.cool_hash[:a].delete(:b) # => fine
+entry.cool_hash.delete(:a) # => `FrozenError`
+
+entry.warm_hash.delete(:a) # => fine
+
+entry.cached_hash # => `FrozenError`
+
+```
+
+Beware that the value passed to `default_value` option when declaring an attribute is always deeply frozen  
+This is to avoid any in-place change which changes the default value of any value object class attribute  
+
+
+### Value Object Class Inheritance
+You can create a value object class inheriting an existing value class instead of `::ContractedValue::Value`  
+
+#### All existing attributes can be used  
+No need to explain right?
+```ruby
+class Pokemon < ::ContractedValue::Value
+  attribute(:name)
+end
+
+class Pikachu < ::Pokemon
+  attribute(:type, default_value: "Thunder")
+end
+
+# Ya I love using pokemon as examples, problem?
+pikachu = Pikachu.new(name: "PikaPika")
+```
+
+#### All existing attributes can be redeclared  
+Within the same class you cannot redefine an attribute
+But in subclasses you can
+```ruby
+class Pokemon < ::ContractedValue::Value
+  attribute(:name)
+end
+
+class Pikachu < ::Pokemon
+  include ::Contracts::Core
+  include ::Contracts::Builtin
+
+  attribute(
+    :name,
+    contract: And[::String, Not[Send[:empty?]]],
+    default_value: String.new("Pikachu"),
+    refrigeration_mode: :none,
+  )
+end
+
+# Ya I love using pokemon as examples, problem?
+Pikachu.new.name # => "Pikachu"
+Pikachu.new.name.frozen? # => true, as mentioned above default value are always deeply frozen
+Pikachu.new(name: "Pikaaaachuuu").name.frozen? # => false
+```
+
+
+## Related gems
+Here is a list of gems which I found and I have tried some of them.  
+But eventually I am unsatisfied so I build this gem.  
+
+- [values](https://github.com/tcrayford/values)
+- [active_attr](https://github.com/cgriego/active_attr)
+- [dry-struct](https://github.com/dry-rb/dry-struct)
+
+### [values](https://github.com/tcrayford/values)
+I used to use this a bit  
+But I keep having to write the attribute names in `Values.new`,  
+then the same attribute names again with `attr_reader` + contract (since I want to use contract)  
+Also the input validation happens on attribute value access instead of on object creation  
+
+### [active_attr](https://github.com/cgriego/active_attr)
+Got similar issue as `values`  
+
+### [dry-struct](https://github.com/dry-rb/dry-struct)
+Seems more suitable for form objects instead of just value objects (for me)  
+
+
+## Contributing
+
+1. Fork it ( https://github.com/PikachuEXE/contracted_value/fork )
+2. Create your branch (Preferred to be prefixed with `feature`/`fix`/other sensible prefixes)
+3. Commit your changes (No version related changes will be accepted)
+4. Push to the branch on your forked repo
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "appraisal"
+require "rubygems"
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+if !ENV["APPRAISAL_INITIALIZED"] && !ENV["TRAVIS"]
+  task :default do
+    sh "appraisal install && rake appraisal spec"
+  end
+else
+  task default: :spec
+end

data/contracted_value.gemspec

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# rubocop:disable all
+$LOAD_PATH.push File.expand_path("../lib", __FILE__)
+
+author_name = "PikachuEXE"
+gem_name = "contracted_value"
+
+require "#{gem_name}/version"
+
+Gem::Specification.new do |s|
+  s.platform      = Gem::Platform::RUBY
+  s.name          = gem_name
+  s.version       = ContractedValue::VERSION
+  s.summary       = "Some Tweaks for ActiveRecord"
+  s.description   = <<-DOC
+    ActiveRecord is great, but could be better. Here are some tweaks for it.
+  DOC
+
+  s.license       = "MIT"
+
+  s.authors       = [author_name]
+  s.email         = ["pikachuexe@gmail.com"]
+  s.homepage      = "http://github.com/#{author_name}/#{gem_name}"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "contracts", "~> 0.15"
+  s.add_dependency "ice_nine"
+
+  s.add_development_dependency "bundler", ">= 1.0.0"
+  s.add_development_dependency "rake", ">= 10.0", "<= 13.0"
+  s.add_development_dependency "pry"
+
+  s.add_development_dependency "appraisal", "~> 2.0"
+
+  s.add_development_dependency "rspec", "~> 3.0"
+  s.add_development_dependency "rspec-its", "~> 1.0"
+
+  s.add_development_dependency "simplecov"
+  s.add_development_dependency "codecov"
+
+  s.add_development_dependency "gem-release", ">= 0.7"
+
+  s.add_development_dependency "inch", "~> 0.6"
+
+  s.add_development_dependency "rubocop", ">= 0.70"
+
+  s.required_ruby_version = ">= 2.3.0"
+
+  s.required_rubygems_version = ">= 1.4.0"
+end

data/gemfiles/contracts_15_0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "contracts", "~> 0.15.0"
+
+gemspec path: "../"

data/gemfiles/contracts_16_0.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "contracts", "~> 0.16.0"
+
+gemspec path: "../"