inflorm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d695f0a82e3f0f6c2efdc498261063ba56f1d924
+  data.tar.gz: 581f6187ef37d2e14dec68dfd827b54d13441b6e
+SHA512:
+  metadata.gz: 3e56cdff307f20cf309b456bd2b0a9e36896a36bca05b33242363126ca540d8c18d99520e134564a91950a57d8a5c0c108bd73635ccf1babfed35ed572805de0
+  data.tar.gz: ae4eeef4bfff80668cda0154787f82b4147a1149d33b15f83d6b7f97bca9c8f0db431dbd812cb9cdfbfea0bd799b8ec344fdc748d1ab09e256e1dc916f874934

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/tmp/

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.2.2

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Brad Robertson
+
+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,182 @@
+# Inflorm
+
+*Simple Form Objects with validations and associations making no assumptions about persistence*
+
+This is so little code you almost can't call it a library. It's simply a wrapper around Virtus
+and ActiveModel validations, with an extra validation to allow for validating associations. I hesistated
+to even make it a gem, but it's a pattern we use across multiple apps so it kind of made sense.
+
+## Philosophy
+
+After working on many massive rails apps, it's become clear that model validations can cause a lot
+of headaches, particularly when you get into custom validations and conditional validations. At
+Influitive, we now consider these types of validations on the model an anti-pattern and stick purely
+to validations that support underlying database constraints. Validations such as `NOT NULL` and `UNIQUE`
+make sense on the model. Validations such as `validate property x if it's a full moon` do NOT
+make sense in the model as these are contextual to a particular use case. This use case should be
+wrapped up in its own object and used to validate input *before* it hits your persistence layer.
+
+## Why another form object library?
+
+Again, I hardly consider this a library on its own, it's just a thin wrapper. We worked with
+both [Reform](https://github.com/apotonick/reform) and [ActiveType](https://github.com/makandra/active_type)
+and both always felt awkward to use and required a new dsl to understand.
+
+- Reform feels weird to me because I generally just want params in and params out with validations
+and param whitelisting. It requires however an underlying model to be passed in, then validated with
+params separately passed in. It has a whole DSL for persistence which I never fully grasped, though
+as the author states, it's optional to use.
+- ActiveType is very much ActiveRecord dependent. It also unfortunately sticks to the Rails
+`accepts_nested_attributes` paradigm which requires nesting to be done with a `{association_name}_attributes` key which I find annoying. (your public interface should NOT be determined by the framework you use under the hood).
+Futhermore, for associations, it instantiates raw models as the children, as opposed to other form objects, which to me defeats the purpose of a form object library.
+
+This is not to speak badly about either library. They both obviously suit the use-cases of the authors,
+they just didn't suit our use-case.
+
+## Usage
+
+Since inflorm is nothing more than a thin wrapper over [Virtus](https://github.com/solnic/virtus)
+and [ActiveModel::Validations](http://guides.rubyonrails.org/active_model_basics.html#validations).
+As such, you can find advanced documentation on this sites, but a simple example would look like this:
+
+```ruby
+class ParentForm
+  include Inflorm
+
+  attribute :name,  String
+  attribute :title, String
+
+  attribute :child, ChildForm      # has_one association
+  attribute :pets,  Array[PetForm] # has_many association
+
+  validates :name,  presence: true
+  validates :child, associated: true
+  validates :pets,  associated: true
+end
+
+class ChildForm
+  include Inflorm
+
+  attribute :age, Integer
+
+  validates :age, presence: true
+end
+
+class PetForm
+  include Inflorm
+
+  attribute :name,    String
+  attribute :species, String
+
+  validates :name,    presence: true
+  validates :species, presence: true
+end
+```
+
+Using those classes like so:
+
+```ruby
+  # Simple object
+  p = Parent.new name: ''
+  p.valid? # => false
+
+  # Object with has_one association
+  p = Parent.new name: 'x', child: {age: 123}
+  p.child.class # => ChildForm
+  p.valid? # => true
+
+  # Object with has_many association
+  p = Parent.new pets: [{species: 'dog', name: 'George'}, {species: 'cat', name: 'Fluffy'}]
+  p.pets.class # => Array
+  p.pets[0].class # => PetForm
+  p.valid? # => true
+```
+
+## Persistence
+
+Inflorm doesn't care about persistence. That's what your ORM is for (or appropriate
+[Command](http://rom-rb.org/guides/basics/commands/),
+[Repository](http://lotusrb.org/guides/models/repositories/) etc). Since it's just params in and
+params out, you can just call `to_h` on your form object to get the validated, whitelisted params.
+This means you don't need to use things like `strong_parameters`.
+
+### Rails-like pattern
+A common pattern in the rails world is to do something like:
+
+```ruby
+# some_controller.rb
+if @my_object.save
+  # do_something
+else
+  # something else
+end
+```
+
+Inflorm includes a very simple implementation of `save` by allowing you to define a `persist!` method
+on your form that will only be called if your form is valid. It looks like this:
+
+```ruby
+def save
+  valid? && persist!
+end
+```
+
+So if you define a `persist!` method on your form like so:
+
+```ruby
+def persist!
+  MyCommand.persist(to_h)
+end
+```
+
+Then your controller can stick to the above pattern. You might need the underlying model from that
+persistence, so assuming the command above returns that, you can do something like this in your controller
+
+```ruby
+# some_controller.rb
+if model = @my_object.save
+  render json: model.to_json
+else
+  render json: {errors: model.errors.messages}
+end
+```
+
+## FAQ
+
+> *What's with the name?*
+
+> **At Influitive we're known for our very creative [portmanteaus](https://en.wikipedia.org/wiki/Portmanteau). This is the ultimate portmanteau of a portmanteau combining Influitive and Form. Clearly we're not very creative people.**
+
+#
+> *Will this ever hook into my persistence layer X?*
+
+> **No**
+
+#
+> *My association is nil, but my main object still passes validation. How do I prevent this?*
+
+> **Inflorm won't validate nil or empty arrays of associations (since there's nothing to validate). If you need to ensure that the association is there, simply validate its presence like so `validates :child, presence: true`. This will ensure that `child` is not nil (or empty in the `has_many` case)**
+
+## TODO
+
+1. `to_h` right now relies on Rails ActiveSupport `Object#as_json` as it will traverse all properties and convert them recursively to an appropriate primitive or hash/array. This isn't possible right now with just Virtus as calling `to_h` on the Virtus object will still nested associations as their defined instance type. I'm really not happy about having to use Rails monkeypatching for this. Apparently Virtus 2.0 [will have better to_h handling](https://github.com/solnic/virtus/issues/290)
+2. The current association validator pollutes the ruby global constant namespace by defining a `AssociatedValidator` class. There's *got* to be a way to register this validation without doing so. This would be a nice change.
+3. *Maybe* add `has_one`, `has_many` methods to mimic ActiveRecord associations but for form objects?. I kind of question the extra overhead, although it's not too much cognitive load since most people inherently understand `has_one` / `has_many`
+
+## Credits
+
+I really haven't done any significant work to make this gem. It's all thanks to [virtus contributors](https://github.com/solnic/virtus/graphs/contributors) and [activemodel contributors](https://github.com/rails/rails/tree/master/activemodel). So go thank them!
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, 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` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/inflorm/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

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

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "inflorm"
+
+# 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.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/inflorm.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'inflorm/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "inflorm"
+  spec.version       = Inflorm::VERSION
+  spec.authors       = ["Brad Robertson"]
+  spec.email         = ["brad@influitive.com"]
+
+  spec.summary       = %q{Simple Form Objects}
+  spec.description   = %q{Form Objects with no assumptions about persistence and a clean api for associations/validations}
+  spec.homepage      = "https://github.com/influitive/inflorm"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.9"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+
+  spec.add_dependency "activemodel", "~> 4.0"
+  spec.add_dependency "virtus", "~> 1.0"
+end

data/lib/inflorm.rb

@@ -0,0 +1,49 @@
+require "inflorm/version"
+require "active_model"
+require "active_support/core_ext/hash/keys"
+require "virtus"
+
+require "inflorm/associated_validator"
+
+module Inflorm
+  def self.included(base)
+    base.class_eval do
+      include Virtus.model
+      include ActiveModel::Validations
+
+      attribute :id, String
+
+      # Need to override Virtus.model to_h, but self.included is run *after* our module
+      # is included, so we can't define this method below with the others (unless we prepended)
+      # Note we're unfortunately relying on rails monkey patching
+      # active_support/core_ext/object/json
+      # which will recursively call as_json on all nested objs. Apparently Virtus 2.0 will give us
+      # these facilities without relying on it.
+      def to_h
+        as_json.deep_symbolize_keys
+      end
+    end
+  end
+
+  def persisted?
+    id.present?
+  end
+
+  def marked_for_destruction?
+    respond_to?(marked_for_destruction_param) && send(marked_for_destruction_param).present?
+  end
+
+  def save
+    valid? && persist!
+  end
+
+  protected
+
+    def marked_for_destruction_param
+      "_destroy".freeze
+    end
+
+    def persist!
+      raise "Not Implemented"
+    end
+end

data/lib/inflorm/associated_validator.rb

@@ -0,0 +1,26 @@
+# TODO see if ActiveModel lets you register a validation
+# without polluting global namespace
+class AssociatedValidator < ActiveModel::EachValidator
+
+  def validate_each(record, attribute, value)
+    value.respond_to?(:to_ary) ?
+      validate_many(record, attribute, value) :
+      validate_one(record, attribute, value)
+  end
+
+  private
+
+    def validate_one(record, attribute, value)
+      return true if value.nil? || value.marked_for_destruction?
+
+      unless value.valid?
+        record.errors.add(attribute, "association error")
+      end
+    end
+
+    def validate_many(record, attribute, value)
+      unless value.reject(&:marked_for_destruction?).all?(&:valid?)
+        record.errors.add(attribute, "association error")
+      end
+    end
+end

data/lib/inflorm/version.rb

@@ -0,0 +1,3 @@
+module Inflorm
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: inflorm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brad Robertson
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2015-07-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !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: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: virtus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Form Objects with no assumptions about persistence and a clean api for
+  associations/validations
+email:
+- brad@influitive.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- inflorm.gemspec
+- lib/inflorm.rb
+- lib/inflorm/associated_validator.rb
+- lib/inflorm/version.rb
+homepage: https://github.com/influitive/inflorm
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Simple Form Objects
+test_files: []