smart_params 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ee27024729173b4bbeb45827db79738a4ed84b07da26c315b57ba0fcca313cc
+  data.tar.gz: 0a65e6f80959a389e55d492735f0a6c8fcfa9c06397acaf9468c83a2e8db4670
+SHA512:
+  metadata.gz: 4580e4078efacdf5b01d334b4f943b8a8426cc375a08180970715187de761595dce15c9b62599f259f769f31bd503f25781da895e1a8dbba0778d37d151ac414
+  data.tar.gz: 9e78ae9f84d8541b5ddebde79346e54dcec97b1bc2b055c00f7fa7d34aae03175b05dbf7e32a96ccad047e8be7c6f340c004384a27437e7d17eb5d8e9f710088

data/README.md

@@ -0,0 +1,153 @@
+# smart_params
+
+  - [![Build](http://img.shields.io/travis-ci/krainboltgreene/smart_params.svg?style=flat-square)](https://travis-ci.org/krainboltgreene/smart_params)
+  - [![Downloads](http://img.shields.io/gem/dtv/smart_params.svg?style=flat-square)](https://rubygems.org/gems/smart_params)
+  - [![Version](http://img.shields.io/gem/v/smart_params.svg?style=flat-square)](https://rubygems.org/gems/smart_params)
+
+
+Work smart, not strong. This gem gives developers an easy to understand and easy to maintain schema for request parameters. Meant as a drop-in replacement for strong_params.
+
+
+## Using
+
+So lets say you have a complex set of incoming data, say a JSON:API-specification compliant payload that contains the data to create an account on your server. Of course, your e-commerce platform is pretty flexible; You don't stop users from creating an account just because they don't have an email or password. So let's see how this would play out:
+
+``` ruby
+class CreateAccountSchema
+  include SmartParams
+
+  schema type: Strict::Hash do
+    need :data, type: Strict::Hash do
+      allow :id, type: Coercible::String.optional
+      need :type, type: Strict::String
+      allow :attributes, type: Strict::Hash.optional do
+        allow :email, type: Strict::String.optional
+        allow :username, type: Strict::String.optional
+        allow :name, type: Strict::String.optional
+        allow :password, type: Strict::String.optional.default { SecureRandom.hex(32) }
+      end
+    end
+    allow :meta, type: Strict::Hash.optional
+    allow :included, type: Strict::Array.optional
+  end
+end
+```
+
+And now using that schema in the controller:
+
+``` ruby
+class AccountsController < ApplicationController
+  def create
+    schema = CreateAccountSchema.new(params)
+    # parameters will be a SmartParams::Dataset, which will respond to the various fields you defined
+
+    # Here we're pulling out the id and data properties defined above
+    record = Account.create({id: schema.data.id, **schema.data.attributes})
+
+    redirect_to account_url(record)
+  end
+end
+```
+
+Okay, so lets look at some scenarios.
+
+First, lets try an empty payload:
+
+``` ruby
+CreateAccountSchema.new({})
+# raises SmartParams::Error::InvalidPropertyType, keychain: [:data], wanted: Hash, raw: nil
+
+# You can return the exception directly by providing :safe => false
+
+CreateAccountSchema.new({}, safe: false).payload
+# return #<SmartParams::Error::InvalidPropertyType... keychain: [:data], wanted: Hash, raw: nil>
+```
+
+Great, we've told SmartParams we need `data` and it enforced this! The exception class knows the "key chain" path to the property that was missing and the value that was given. Lets experiment with that:
+
+``` ruby
+CreateAccountSchema.new({data: ""})
+# raise SmartParams::Error::InvalidPropertyType, keychain: [:data], wanted: Hash, raw: ""
+```
+
+Sweet, we can definitely catch this and give the client a meaningful error! Okay, so to show off a good payload I'm going to do two things: Examine the properties and turn it to a JSON compatible structure. Lets see a minimum viable account according to our schema:
+
+
+``` ruby
+schema = CreateAccountSchema.new({
+  data: {
+    type: "accounts"
+  }
+})
+
+schema.payload.data.type
+# "accounts"
+
+schema.data.type
+# "accounts"
+
+schema.as_json
+# {
+#   "data" => {
+#     "type" => "accounts",
+#     "attributes" => {
+#       "password" => "1a6c3ffa4e96ad1660cb819f52a3393d924ac20073e84a9a6943a721d49bab38"
+#     }
+#   }
+# }
+```
+
+Wait, what happened here? Well we told SmartParams that we're going to want a default password, so it delivered!
+
+
+### Types
+
+For more information on what types and options you can use, please read: http://dry-rb.org/gems/dry-types/
+
+
+### Why not strong_params?
+
+Okay so sure strong_params exists and it's definitely better than `attr_accessible` (if you remember that mess), but it often leaves you with code like this:
+
+https://github.com/diaspora/diaspora/blob/develop/app/controllers/users_controller.rb#L140-L158
+
+Which while fine to start with usually evolves into:
+
+https://github.com/discourse/discourse/blob/master/app/controllers/posts_controller.rb#L592-L677
+
+None of this is very maintainable and it's definitely not easy to teach. So my solution is to follow the wake of other libraries: Define a maintainable interface that can be easily tested and easily integrated. It doesn't require wholesale adoption nor is it hard to remove.
+
+
+### Why not have this in the controller?
+
+First and foremost because the controller already has a job: Determining the course of action for a request. Why complicate it with yet another responsibility? Second because it makes testing that much harder. Instead of just testing the correctness of your schema, you now have to mock authentication and authorization.
+
+
+### Why not use before_validation or before_save?
+
+Your model is already complex enough and it doesn't need the added baggage of figuring out how to transform incoming data. We learned that lesson the hard way with `attr_accessible`. Further, it's not vary sharable or understandable over large time periods.
+
+
+## Installing
+
+Add this line to your application's Gemfile:
+
+    gem "smart_params", "1.0.0"
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself with:
+
+    $ gem install smart_params
+
+
+## Contributing
+
+  1. Read the [Code of Conduct](/CONDUCT.md)
+  2. Fork it
+  3. Create your feature branch (`git checkout -b my-new-feature`)
+  4. Commit your changes (`git commit -am 'Add some feature'`)
+  5. Push to the branch (`git push origin my-new-feature`)
+  6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+desc "Run all the tests in spec"
+RSpec::Core::RakeTask.new(:spec) do |let|
+  let.pattern = "lib/**{,/*/**}/*_spec.rb"
+end
+
+desc "Default: run tests"
+task default: :spec

data/lib/smart_params/error/invalid_property_type.rb

@@ -0,0 +1,27 @@
+module SmartParams
+  class Error
+    class InvalidPropertyType < Error
+      attr_reader :keychain
+      attr_reader :wanted
+      attr_reader :raw
+
+      def initialize(keychain:, wanted:, raw:)
+        @keychain = keychain
+        @wanted = type
+        @raw = raw
+      end
+
+      def message
+        "expected #{keychain.inspect} to be wanted of #{wanted.type.name}, but was #{raw.inspect}"
+      end
+
+      def as_json
+        {
+          "keychain" => keychain,
+          "wanted" => wanted.type.name,
+          "raw" => raw
+        }
+      end
+    end
+  end
+end

data/lib/smart_params/error.rb

@@ -0,0 +1,5 @@
+module SmartParams
+  class Error < StandardError
+    require_relative "error/invalid_property_type"
+  end
+end

data/lib/smart_params/field.rb

@@ -0,0 +1,61 @@
+module SmartParams
+  class Field
+    RECURSIVE_TREE = ->(accumulated, key) {accumulated[key] = Hash.new(&RECURSIVE_TREE)}
+
+    attr_reader :keychain
+    attr_reader :value
+    attr_reader :subfields
+    attr_reader :type
+
+    def initialize(keychain:, type:, &nesting)
+      @keychain = Array(keychain)
+      @subfields = Set.new
+      @type = type
+
+      if block_given?
+        instance_eval(&nesting)
+      end
+    end
+
+    def allow(key, type:, &subfield)
+      @subfields << self.class.new(keychain: [*keychain, key], type: type, &subfield)
+    end
+
+    def need(key, type:, &subfield)
+      @subfields << self.class.new(keychain: [*keychain, key], type: type, &subfield)
+    end
+
+    def deep?
+      subfields.present?
+    end
+
+    def claim(raw)
+      if keychain.empty?
+        @value = type[raw]
+      else
+        @value = type[raw.dig(*keychain)]
+      end
+    rescue Dry::Types::ConstraintError => bad_type_exception
+      raise SmartParams::Error::InvalidPropertyType, keychain: keychain, wanted: type, raw: raw.dig(*keychain)
+    end
+
+    def to_hash
+      *chain, key = keychain
+      Hash.new(&RECURSIVE_TREE).tap do |tree|
+        if chain.any?
+          tree.dig(*chain)[key] = value
+        else
+          tree[key] = value
+        end
+      end
+    end
+
+    def empty?
+      value.nil?
+    end
+
+    def weight
+      keychain.length
+    end
+  end
+end

data/lib/smart_params/version.rb

@@ -0,0 +1,3 @@
+module SmartParams
+  VERSION = "1.0.0"
+end

data/lib/smart_params/version_spec.rb

@@ -0,0 +1,7 @@
+require "spec_helper"
+
+RSpec.describe SmartParams::VERSION do
+  it "should be a string" do
+    expect(SmartParams::VERSION).to be_kind_of(String)
+  end
+end

data/lib/smart_params.rb

@@ -0,0 +1,92 @@
+require "ostruct"
+require "dry-types"
+require "recursive-open-struct"
+require "active_support/concern"
+require "active_support/core_ext/object"
+
+module SmartParams
+  extend ActiveSupport::Concern
+  include Dry::Types.module
+
+  RECURSIVE_TREE = ->(accumulated, key) {accumulated[key] = Hash.new(&RECURSIVE_TREE)}
+
+  require_relative "smart_params/field"
+  require_relative "smart_params/error"
+  require_relative "smart_params/version"
+
+  attr_reader :raw
+  attr_reader :schema
+  attr_reader :fields
+
+  def initialize(raw, safe: true)
+    @raw = raw
+    @schema = self.class.instance_variable_get(:@schema)
+    @fields = [@schema, *unfold(@schema.subfields)]
+      .sort_by(&:weight)
+      .each { |field| field.claim(raw) }
+    @safe = safe
+  rescue SmartParams::Error::InvalidPropertyType => invalid_property_type_exception
+    if safe?
+      raise invalid_property_type_exception
+    else
+      @exception = invalid_property_type_exception
+    end
+  end
+
+  def payload
+    if @exception.present?
+      @exception
+    else
+      RecursiveOpenStruct.new(structure)
+    end
+  end
+
+  def as_json
+    if @exception.present?
+      @exception.as_json
+    else
+      structure.deep_stringify_keys
+    end
+  end
+
+  def method_missing(name, *arguments, &block)
+    if payload.respond_to?(name)
+      payload.public_send(name)
+    else
+      super
+    end
+  end
+
+  # This function basically takes a list of fields and reduces them into a tree of values
+  private def structure
+    fields
+      .reject(&:empty?)
+      .map(&:to_hash)
+      .map do |hash|
+        # NOTE: okay, so this looks weird, but it's because the root type has no key
+        if hash.key?(nil) then hash.fetch(nil) else hash end
+      end
+      .reduce(&:deep_merge)
+  end
+
+  # This funcion takes a nested field tree and turns it into a list of fields
+  private def unfold(subfields)
+    subfields.to_a.reduce([]) do |list, field|
+      if field.deep?
+        [*list, field, *unfold(field.subfields)]
+      else
+        [*list, field]
+      end
+    end.flatten
+  end
+
+  private def safe?
+    @safe
+  end
+
+  class_methods do
+    def schema(type:, &subfield)
+      @schema = Field.new(keychain: [], type: type, &subfield)
+    end
+  end
+end

data/lib/smart_params_spec.rb

@@ -0,0 +1,147 @@
+require "spec_helper"
+
+RSpec.describe SmartParams do
+  let(:schema) { CreateAccountSchema.new(params) }
+
+  describe ".new" do
+    context "with an empty params" do
+      let(:params) { {} }
+
+      it "throws an error with a message detailing the invalid property type and given properties" do
+        expect {schema}.to raise_exception(SmartParams::Error::InvalidPropertyType, "expected [:data] to be kind of Hash, but was nil")
+      end
+
+      it "throws an error with the missing property and given properties" do
+        expect {schema}.to raise_exception do |exception|
+          expect(exception).to have_attributes(keychain: [:data], wanted: SmartParams::Strict::Hash, raw: nil)
+        end
+      end
+    end
+
+    context "with a good key but bad type" do
+      let(:params) { {data: ""} }
+
+      it "throws an error with a message detailing the invalid property, expected type, given type, and given value" do
+        expect { schema }.to raise_exception(SmartParams::Error::InvalidPropertyType, "expected [:data] to be kind of Hash, but was \"\"")
+      end
+
+      it "throws an error with the invalid property, expected type, given type, and given value" do
+        expect {schema }.to raise_exception do |exception|
+          expect(exception).to have_attributes(keychain: [:data], wanted: SmartParams::Strict::Hash, raw: "")
+        end
+      end
+    end
+  end
+
+  describe "#payload" do
+    context "with a reasonably good params" do
+      let(:params) do
+        {
+          data: {
+            type: "accounts",
+            attributes: {
+              email: "kurtis@example.com"
+            }
+          },
+          meta: {
+            jsonapi_version: "1.0"
+          },
+          included: [
+            {
+              data: {
+                id: "a",
+                type: "widget",
+                attributes: {
+                  title: "Widget A",
+                }
+              }
+            }
+          ]
+        }
+      end
+
+      it "returns the type" do
+        expect(schema.payload.data.type).to eq("accounts")
+      end
+
+      it "returns the email" do
+        expect(schema.data.attributes.email).to eq("kurtis@example.com")
+      end
+
+      it "returns the password" do
+        expect(schema.data.attributes.password).to be_kind_of(String)
+      end
+
+      it "returns the jsonapi version" do
+        expect(schema.meta.jsonapi_version).to eq("1.0")
+      end
+    end
+  end
+
+  describe "#as_json" do
+    subject {schema.as_json}
+
+    context "with a reasonably good params" do
+      let(:params) do
+        {
+          data: {
+            type: "accounts",
+            attributes: {
+              email: "kurtis@example.com"
+            }
+          },
+          meta: {
+            jsonapi_version: "1.0"
+          },
+          included: [
+            {
+              data: {
+                id: "a",
+                type: "widget",
+                attributes: {
+                  title: "Widget A",
+                }
+              }
+            }
+          ]
+        }
+      end
+
+      it "returns as json" do
+        expect(
+          subject
+        ).to eq(
+          hash_including(
+            {
+              "data" => hash_including(
+                {
+                  "type" => "accounts",
+                  "attributes" => hash_including(
+                    {
+                      "email" => "kurtis@example.com",
+                      "password" => an_instance_of(String)
+                    }
+                  )
+                }
+              ),
+              "meta" => {
+                "jsonapi_version" => "1.0"
+              },
+              "included" => [
+                {
+                  "data" => {
+                    "id" => "a",
+                    "type" => "widget",
+                    "attributes" => {
+                      "title" => "Widget A"
+                    }
+                  }
+                }
+              ]
+            }
+          )
+        )
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,179 @@
+--- !ruby/object:Gem::Specification
+name: smart_params
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Kurtis Rainbolt-Greene
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-04-21 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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: pry-doc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: dry-monads
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: recursive-open-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: Apply an organized and easy to maintain schema to request params
+email:
+- kurtis@rainbolt-greene.online
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/smart_params.rb
+- lib/smart_params/error.rb
+- lib/smart_params/error/invalid_property_type.rb
+- lib/smart_params/field.rb
+- lib/smart_params/version.rb
+- lib/smart_params/version_spec.rb
+- lib/smart_params_spec.rb
+homepage: http://krainboltgreene.github.io/smart_params
+licenses:
+- ISC
+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.7.6
+signing_key: 
+specification_version: 4
+summary: Apply an organized and easy to maintain schema to request params
+test_files: []