jsonapi-deserializable 0.1.1.beta2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 93ceb39a5f3d032a99748170ac818e096e691d05
+  data.tar.gz: adfdd698f25de948e225c87087f850376d900f09
+SHA512:
+  metadata.gz: 52f05a26b475cf2afa912ab7e3e207f4d925c32e58c5ba99edfc8a52685c5c536ecdc8d8e0e7e2d06d44916be0b1af383ba035339c87754824a0988cf93ce48c
+  data.tar.gz: aa7bfa1f75f1ec8bd00dc69025dffbc7127874b86f946dd1489798837727630df4a15a9410cb8047a26c195b6b6082e185bb3d9770cc586668d9b52f274c5769

data/README.md

@@ -0,0 +1,116 @@
+# jsonapi-deserializable
+Ruby gem for validating and deserializing [JSON API](http://jsonapi.org)
+payloads into custom hashes.
+Built upon the [jsonapi-validations](https://github.com/beauby/jsonapi/tree/master/validations)
+gem.
+
+## Installation
+```ruby
+# In Gemfile
+gem 'jsonapi-deserializable'
+```
+then
+```
+$ bundle
+```
+or manually via
+```
+$ gem install jsonapi-deserializable
+```
+
+## Usage
+
+First, require the gem:
+```ruby
+require 'jsonapi/deserializable'
+```
+
+Then, define some resource/relationship classes:
+```ruby
+class DeserializableUser < JSONAPI::Deserializable::Resource
+  # List of required attributes / has_many/has_one relationships.
+  #   This directive is not mandatory. If not declared, no field
+  #   will be required.
+  required do
+    id # Optional, require an id for the primary resource.
+
+    type :users # Optional, force a type for the primary resource.
+    # or, still optional, force a set of allowed types for the primary resource:
+    types [:users, :superusers] # Optional,
+
+    attribute :name
+    has_one :sponsor
+    # or, optionally, spcecify a type for the relationship target:
+    has_one :sponsor, :users
+  end
+
+  # List of optional attributes / has_many/has_one relationships.
+  #   This directive is not mandatory. If not declared, all fields
+  #   will be allowed. If declared, all fields that are not within
+  #   eitheroptional or required will be rejected.
+  optional do
+    attribute :address
+    has_many :posts
+    # or, optionally, specify a set of allowed types for the primary resource:
+    has_many :posts, [:posts, :blogs]
+  end
+
+  ## The actual fields of the generated hash.
+  # `attribute` is a shorthand for `field(key) { @attributes.send(key) }`.
+  attribute :address
+
+  field :id do
+    @data.id
+  end
+
+  # `field` is the standard method for defining a key on the result hash.
+  field :username do
+    @document.data.attributes.name
+  end
+
+  field :post_ids do
+    @relationships.posts.data.map(&:id)
+  end
+
+  field :sponsor_id do
+    @relationships.sponsor.data && @relationships.sponsor.data.id
+  end
+end
+```
+Finally, build your hash from the deserializable resource:
+```ruby
+payload = {
+  'data' => {
+    'id' => '1',
+    'type' => 'users',
+    'attributes' => {
+      'name' => 'Name',
+      'address' => 'Address'
+    },
+    'relationships' => {
+      'sponsor' => {
+        'data' => { 'type' => 'users', 'id' => '1337' }
+      },
+      'posts' => {
+        'data' => [
+          { 'type' => 'posts', 'id' => '123' },
+          { 'type' => 'posts', 'id' => '234' },
+          { 'type' => 'posts', 'id' => '345' }
+        ]
+      }
+    }
+  }
+}
+
+DeserializableUser.new(payload).to_h
+# => {
+#      username: 'Name',
+#      address: 'Address',
+#      sponsor_id: '1337',
+#      post_ids: ['123', '234', '345']
+#    }
+```
+
+## License
+
+jsonapi-deserializable is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/jsonapi/deserializable.rb

@@ -0,0 +1,3 @@
+require 'jsonapi/deserializable/exceptions'
+require 'jsonapi/deserializable/relationship'
+require 'jsonapi/deserializable/resource'

data/lib/jsonapi/deserializable/document_validator.rb

@@ -0,0 +1,200 @@
+require 'jsonapi/deserializable/field_list'
+
+module JSONAPI
+  module Deserializable
+    class DocumentValidator
+      def self.validate!(payload, required_list, optional_list)
+        new(payload, required_list, optional_list).validate!
+      end
+
+      def initialize(document, required, optional)
+        whitelist = {
+          id: :optional,
+          types: [],
+          attributes: {
+            foo: :required,
+            bar: :optional
+          },
+          relationships: {
+            foobar: :required,
+            barfoo: {
+              required: true,
+              types: [:baz],
+              arity: :to_many
+            }
+          }
+        }
+
+
+        arities = {
+          foobar: :to_many,
+          barfoo: :to_one
+        }
+        types = {
+          primary: [],
+          relationships: {
+            foobar: [:baz],
+            barfoo: [:bazbaz]
+          }
+        }
+              required: true,
+              types: [:baz],
+              arity: :to_many
+            }
+          }
+        }
+        @document = document
+        @required = required || {}
+        @optional = optional
+        @fields = {}
+        @fields[:primary_id] = true if @required[:primary_id]
+        primary_types = @required[:primary_types]
+        @fields[:primary_types] = primary_types if primary_types
+        @fields[:attributes] = @required[:attributes].dup
+        @fields[:relationships] = @required[:relationships].dup
+        if @optional
+          @fields[:primary_id] = true if @optional[:primary_id]
+          primary_types = @optional[:primary_types]
+          @fields[:primary_types] = primary_types if primary_types
+          @fields[:attributes].merge
+        end
+      end
+
+      def validate!
+        raise INVALID_DOCUMENT unless @document.data
+        @data = @document.data
+        if @data.respond_to?(:each)
+          raise INVALID_DOCUMENT, 'The request MUST include a single resource' \
+                                  ' object as primary data'
+        end
+        @attributes = @data.attributes
+        @relationships = @data.relationships
+        validate_primary!
+        validate_fields!
+      end
+
+      def validate_primary!
+        validate_id!
+        validate_type!
+      end
+
+      def id_required?
+        @required[:primary_id]
+      end
+
+      def id_permitted?
+        @fields[:primary_id]
+      end
+
+      def validate_id!
+        if @data.id.nil?
+          raise INVALID_DOCUMENT,
+                'Expected id for primary resource' if id_required?
+        else
+          raise INVALID_DOCUMENT,
+                'Unexpected id for primary resource' unless id_permitted?
+        end
+      end
+
+      def type_valid?
+        return false if @required &&
+                        @required[:primary_types] &&
+                        !@required[:primary_types].include?(@data.type.to_sym)
+        return false if @optional &&
+                        @optional[:primary_types] &&
+                        !@optional[:primary_types].include?(@data.type.to_sym)
+        true
+      end
+
+      def validate_type!
+        return if type_valid?
+        raise INVALID_DOCUMENT,
+              "Unexpected type #{@data.type} for primary resource"
+      end
+
+      def validate_fields!
+        validate_attributes!
+        validate_relationships!
+      end
+
+      def attr_permitted?(attr_key)
+        return true unless @optional
+        return true if @optional[:attributes].include?(attr_key.to_sym)
+        @required && @required[:attributes].include?(attr_key.to_sym)
+      end
+
+      def validate_attributes!
+        @attributes.keys.each do |attr_key|
+          next if attr_permitted?(attr_key)
+          raise INVALID_DOCUMENT, "Unexpected attribute #{attr_key}"
+        end
+        return unless @required
+        @required[:attributes].each do |attr_key|
+          next if @attributes.defined?(attr_key)
+          raise INVALID_DOCUMENT, "Expected attribute #{attr_key}"
+        end
+      end
+
+      def rel_permitted?(rel_key)
+        return true unless @optional
+        return true if @optional[:relationships].key?(rel_key.to_sym)
+        @required && @required[:relationships].key?(rel_key.to_sym)
+      end
+
+      def validate_relationships!
+        @relationships.keys.each do |rel_key|
+          next if rel_permitted?(rel_key)
+          raise INVALID_DOCUMENT, "Unexpected relationship #{rel_key}"
+        end
+        return unless @required
+        @required[:relationships].keys.each do |rel_key|
+          next if @relationships.defined?(rel_key)
+          raise INVALID_DOCUMENT, "Expected relationship #{rel_key}"
+        end
+        validate_relationship_types!
+      end
+
+      def validate_relationship_types!
+        rels = {}
+        rels.merge!(@required.relationships) if @required
+        rels.merge(@optional.relationships) if @optional
+        rels.each do |key, hash|
+          rel = @relationships[key.to_s]
+          unless rel.data
+            raise INVALID_DOCUMENT, "Expected data for relationship #{key}"
+          end
+
+          if hash[:arity] == :to_one
+            validate_to_one_relationship_type!(rel, hash[:types])
+          else
+            validate_to_many_relationship_type!(rel, hash[:types])
+          end
+        end
+      end
+
+      def validate_to_one_relationship_type!(rel, types)
+        if rel.collection?
+          raise INVALID_DOCUMENT,
+                "Expected relationship #{key} to be has_one"
+        end
+        return unless types && !types.include?(rel.data.type.to_sym)
+        raise INVALID_DOCUMENT, "Unexpected type: #{rel.data.type} for " \
+                                "relationship #{key}"
+      end
+
+      def validate_to_many_relationship_type!(rel, types)
+        unless rel.collection?
+          raise INVALID_DOCUMENT,
+                "Expected relationship #{key} to be has_many"
+        end
+        return unless types
+        rel.data.each do |ri|
+          unless types.include?(ri.type.to_sym)
+            raise INVALID_DOCUMENT, "Unexpected type: #{ri.type} for " \
+                                    "relationship #{key}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/deserializable/exceptions.rb

@@ -0,0 +1,7 @@
+require 'jsonapi/parser/exceptions'
+
+module JSONAPI
+  module Deserializable
+    INVALID_DOCUMENT = JSONAPI::Parser::InvalidDocument
+  end
+end

data/lib/jsonapi/deserializable/relationship.rb

@@ -0,0 +1,38 @@
+require 'jsonapi/deserializable/exceptions'
+require 'jsonapi/deserializable/relationship_dsl'
+
+module JSONAPI
+  module Deserializable
+    class Relationship
+      include RelationshipDSL
+
+      class << self
+        attr_accessor :field_blocks, :validations
+      end
+
+      self.field_blocks = {}
+      self.validations = {}
+
+      def self.inherited(klass)
+        klass.field_blocks = field_blocks.dup
+        klass.validations = Marshal.load(Marshal.dump(validations))
+      end
+
+      def initialize(payload)
+        JSONAPI.validate_relationship!(payload, validations)
+        @document = payload
+        @data = payload['data']
+      end
+
+      def to_h
+        return nil if @data.nil?
+        return @_hash if @_hash
+        @_hash = {}
+        self.class.field_blocks.each do |key, block|
+          @_hash[key] = instance_eval(&block)
+        end
+        @_hash
+      end
+    end
+  end
+end

data/lib/jsonapi/deserializable/relationship_dsl.rb

@@ -0,0 +1,31 @@
+module JSONAPI
+  module Deserializable
+    module RelationshipDSL
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def has_one
+          validations[:kind] = :has_one
+        end
+
+        def has_many
+          validations[:kind] = :has_many
+        end
+
+        def type(value)
+          (validations[:types] ||= []) << value
+        end
+
+        def types(values)
+          (validations[:types] ||= []).concat(values)
+        end
+
+        def field(key, &block)
+          field_blocks[key] = block
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/deserializable/resource.rb

@@ -0,0 +1,44 @@
+require 'jsonapi/validations'
+require 'jsonapi/deserializable/exceptions'
+require 'jsonapi/deserializable/resource_dsl'
+
+module JSONAPI
+  module Deserializable
+    class Resource
+      include ResourceDSL
+
+      class << self
+        attr_accessor :field_blocks, :validations
+      end
+
+      self.field_blocks = {}
+      self.validations = {}
+
+      def self.inherited(klass)
+        super
+        klass.field_blocks = field_blocks.dup
+        klass.validations = Marshal.load(Marshal.dump(validations))
+      end
+
+      def initialize(payload)
+        JSONAPI.validate_resource!(payload, self.class.validations)
+        @document = payload
+        @data = @document['data']
+        @attributes = @data['attributes']
+        @relationships = @data['relationships']
+      end
+
+      def to_h
+        return @_hash if @_hash
+
+        @_hash = {}
+        @_hash[:_payload] = @document
+        self.class.field_blocks.map do |k, v|
+          @_hash[k] = instance_eval(&v)
+        end
+
+        @_hash
+      end
+    end
+  end
+end

data/lib/jsonapi/deserializable/resource/dsl.rb

@@ -0,0 +1,77 @@
+module JSONAPI
+  module Deserializable
+    module ResourceDSL
+      attr_accessor :field_blocks, :validations
+
+      def required(&block)
+        add_validations!(FieldList.new(:required, &block).to_h)
+      end
+
+      def optional(&block)
+        add_validations!(FieldList.new(:optional, &block).to_h)
+      end
+
+      def id
+        field_blocks[:id] = proc { @data['id'] }
+      end
+
+      def field(key, &block)
+        field_blocks[key] = block
+      end
+
+      def attribute(key, opts = {})
+        hash_key = (opts[:key] || key).to_s
+        field_blocks[key] = proc { @attributes[hash_key] }
+      end
+
+      def has_many_ids(key, opts = {})
+        hash_key = (opts[:key] || key).to_s
+        field_blocks[key] = proc do
+          @relationships[hash_key]['data'].map { |ri| ri['id'] }
+        end
+      end
+
+      def has_many_types(key, opts = {})
+        hash_key = (opts[:key] || key).to_s
+        field_blocks[key] = proc do
+          @relationships[hash_key]['data'].map { |ri| ri['type'] }
+        end
+      end
+
+      def has_many_ids(key, opts = {})
+        hash_key = (opts[:key] || key).to_s
+        @relationships[hash_key]['data']['id']
+      end
+
+      def has_many_ids(key, opts = {})
+        hash_key = (opts[:key] || key).to_s
+        @relationships[hash_key]['data']['type']
+      end
+
+      self.field_blocks = {}
+      self.validations = {}
+
+      def self.inherited(klass)
+        super
+        klass.field_blocks = field_blocks.dup
+        klass.validations = Marshal.load(Marshal.dump(validations))
+      end
+
+      private
+
+      def add_validations!(hash)
+        validations[:permitted] = hash[:permitted] if hash[:permitted]
+        validations[:required] = hash[:required] if hash[:required]
+        return unless hash[:types]
+        validations[:types] ||= {}
+        if hash[:types][:primary]
+          validations[:types][:primary] = hash[:types][:primary]
+        end
+        return unless hash[:types][:relationships]
+        validations[:types][:relationships] ||= {}
+        validations[:types][:relationships]
+          .merge!(hash[:types][:relationships])
+      end
+    end
+  end
+end

data/lib/jsonapi/deserializable/resource_dsl.rb

@@ -0,0 +1,74 @@
+require 'jsonapi/deserializable/validations'
+
+module JSONAPI
+  module Deserializable
+    module ResourceDSL
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def required(&block)
+          add_validations!(Validations.new(:required, &block).to_h)
+        end
+
+        def optional(&block)
+          add_validations!(Validations.new(:optional, &block).to_h)
+        end
+
+        def field(key, &block)
+          field_blocks[key] = block
+        end
+
+        def id
+          field(:id) { @data['id'] }
+        end
+
+        def attribute(key, opts = {})
+          hash_key = (opts[:key] || key).to_s
+          field(key) { @attributes[hash_key] }
+        end
+
+        def has_many_ids(key, opts = {})
+          hash_key = (opts[:key] || key).to_s
+          field(key) do
+            @relationships[hash_key]['data'].map { |ri| ri['id'] }
+          end
+        end
+
+        def has_many_types(key, opts = {})
+          hash_key = (opts[:key] || key).to_s
+          field(key) do
+            @relationships[hash_key]['data'].map { |ri| ri['type'] }
+          end
+        end
+
+        def has_one_id(key, opts = {})
+          hash_key = (opts[:key] || key).to_s
+          field(key) { @relationships[hash_key]['data']['id'] }
+        end
+
+        def has_one_type(key, opts = {})
+          hash_key = (opts[:key] || key).to_s
+          field(key) { @relationships[hash_key]['data']['type'] }
+        end
+
+        private
+
+        def add_validations!(hash)
+          validations[:permitted] = hash[:permitted] if hash[:permitted]
+          validations[:required] = hash[:required] if hash[:required]
+          return unless hash[:types]
+          validations[:types] ||= {}
+          if hash[:types][:primary]
+            validations[:types][:primary] = hash[:types][:primary]
+          end
+          return unless hash[:types][:relationships]
+          validations[:types][:relationships] ||= {}
+          validations[:types][:relationships]
+            .merge!(hash[:types][:relationships])
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/deserializable/validations.rb

@@ -0,0 +1,101 @@
+module JSONAPI
+  module Deserializable
+    class Validations
+      def initialize(validation_type, &block)
+        @validation_type = validation_type
+        @hash = {
+          @validation_type => {
+            attributes: [],
+            relationships: []
+          },
+          types: {
+            relationships: {}
+          }
+        }
+        instance_eval(&block)
+      end
+
+      def to_h
+        @hash
+      end
+
+      private
+
+      # Define whether the +id+ of the primary resource should be part of
+      #   this list.
+      def id
+        validations_hash[:id] = true
+      end
+
+      # Define the allowed type for the primary resource.
+      # @param [Symbol] value The value of the type.
+      def type(value)
+        types_hash[:primary] = Array(value)
+      end
+
+      # Define the allowed type for the primary resource.
+      # @param [Array<Symbol>] values List of allowed values of the type.
+      def types(values)
+        types_hash[:primary] = values
+      end
+
+      # Define an attribute with given key.
+      # @param [Symbol] key The key of the attribute in the payload.
+      def attribute(key)
+        validations_hash[:attributes] << key
+      end
+
+      # TODO(beauby): Decide whether type: 'users' / types: [...] is better.
+      #
+      # @overload has_one(key)
+      #   Define a has_one relationship with given key.
+      #   @param [Symbol] key The key of the relationship in the payload.
+      #
+      # @overload has_one(key, type)
+      #   Define a has_one relationship with given key.
+      #   @param [Symbol] key The key of the relationship in the payload.
+      #   @param [Symbol] type The expected type of the relationship value.
+      #
+      # @overload has_one(key, types)
+      #   Define a has_one relationship with given key.
+      #   @param [Symbol] key The key of the relationship in the payload.
+      #   @param [Array<Symbol>] type List of acceptable types for the
+      #     relationship value.
+      def has_many(key, types = nil)
+        validations_hash[:relationships] << key
+        types_hash[:relationships][key] = { kind: :has_many }
+        return unless types
+        types_hash[:relationships][key][:types] = Array(types)
+      end
+
+      # @overload has_one(key)
+      #   Define a has_one relationship with given key.
+      #   @param [Symbol] key The key of the relationship in the payload.
+      #
+      # @overload has_one(key, type)
+      #   Define a has_one relationship with given key.
+      #   @param [Symbol] key The key of the relationship in the payload.
+      #   @param [Symbol] type The expected type of the relationship value.
+      #
+      # @overload has_one(key, types)
+      #   Define a has_one relationship with given key.
+      #   @param [Symbol] key The key of the relationship in the payload.
+      #   @param [Array<Symbol>] type List of acceptable types for the
+      #     relationship value.
+      def has_one(key, types = nil)
+        validations_hash[:relationships] << key
+        types_hash[:relationships][key] = { kind: :has_one }
+        return unless types
+        types_hash[:relationships][key][:types] = Array(types)
+      end
+
+      def validations_hash
+        @hash[@validation_type]
+      end
+
+      def types_hash
+        @hash[:types]
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: jsonapi-deserializable
+version: !ruby/object:Gem::Version
+  version: 0.1.1.beta2
+platform: ruby
+authors:
+- Lucas Hosseini
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-10-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jsonapi-validations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+description: DSL for validating incoming JSON API payloads and building custom objects
+  out of them.
+email: lucas.hosseini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/jsonapi/deserializable.rb
+- lib/jsonapi/deserializable/document_validator.rb
+- lib/jsonapi/deserializable/exceptions.rb
+- lib/jsonapi/deserializable/relationship.rb
+- lib/jsonapi/deserializable/relationship_dsl.rb
+- lib/jsonapi/deserializable/resource.rb
+- lib/jsonapi/deserializable/resource/dsl.rb
+- lib/jsonapi/deserializable/resource_dsl.rb
+- lib/jsonapi/deserializable/validations.rb
+homepage: https://github.com/beauby/jsonapi-deserializable
+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: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Deserialization of JSONAPI payloads.
+test_files: []