jsonapi-renderer 0.1.1.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3f02425bfc2d75e4ea21cd4ecb42b6378b4c6939
+  data.tar.gz: 14400fddf957704ea29b97b422a0f814bad5f3a2
+SHA512:
+  metadata.gz: 57a9d3c9d252fa70c29ee3734b322c8254b527b13661c226184cd3d4304eaaf9ae12b88a9c105a21f826b61f07fc71f6cd02e31f19c3a634001a4f178e204a26
+  data.tar.gz: c620d458eb042cc288c5b461af20181acc0e75dd9d0c0509c9f3bc6b9cb7edb1711db86bdbc1aa5c5805f882c148a1c4d57e708bcccfcb6fa4962a2b628c0555

data/README.md

@@ -0,0 +1,91 @@
+# jsonapi-renderer
+Ruby gem for rendering [JSON API](http://jsonapi.org) documents.
+
+## Installation
+```ruby
+# In Gemfile
+gem 'jsonapi-renderer'
+```
+then
+```
+$ bundle
+```
+or manually via
+```
+$ gem install jsonapi-renderer
+```
+
+## Usage
+
+First, require the gem:
+```ruby
+require 'jsonapi/renderer'
+```
+
+### Rendering resources
+
+A resource here is any class that implements the following interface:
+```ruby
+class ResourceInterface
+  # Returns the type of the resource.
+  # @return [String]
+  def jsonapi_type; end
+
+  # Returns the id of the resource.
+  # @return [String]
+  def jsonapi_id; end
+
+  # Returns a hash containing, for each included relationship, the resource(s)
+  # to be included from that one.
+  # @param [Array<Symbol>] included_relationships The keys of the relationships
+  #   to be included.
+  # @return [Hash{Symbol => #ResourceInterface, Array<#ResourceInterface>}]
+  def jsonapi_related(included_relationships); end
+
+  # Returns a JSON API-compliant representation of the resource as a hash.
+  # @param [Hash] options
+  #   @option [Array<Symbol>, Nil] fields The requested fields, or nil.
+  #   @option [Array<Symbol>, Nil] included The requested included
+  #     relationships, or nil.
+  # @return [Hash]
+  def as_jsonapi(options = {}); end
+```
+
+#### Rendering a single resource
+```ruby
+JSONAPI.render(resource,
+               include: include_string,
+               fields: fields_hash,
+               meta: meta_hash,
+               links: links_hash)
+```
+
+This returns a JSON API compliant hash representing the described document.
+
+#### Rendering a collection of resources
+```ruby
+JSONAPI.render(resources,
+               include: include_string,
+               fields: fields_hash,
+               meta: meta_hash,
+               links: links_hash)
+```
+
+This returns a JSON API compliant hash representing the described document.
+
+### Rendering errors
+
+```ruby
+JSONAPI.render_errors(errors,
+                      meta: meta_hash,
+                      links: links_hash)
+```
+
+where `errors` is an array of objects implementing the `as_jsonapi` method, that
+returns a JSON API-compliant representation of the error.
+
+This returns a JSON API compliant hash representing the described document.
+
+## License
+
+jsonapi-renderer is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/jsonapi/include_directive/parser.rb

@@ -0,0 +1,65 @@
+module JSONAPI
+  class IncludeDirective
+    # Utilities to create an IncludeDirective hash from various types of
+    # inputs.
+    module Parser
+      module_function
+
+      # @api private
+      def parse_include_args(include_args)
+        case include_args
+        when Symbol
+          { include_args => {} }
+        when Hash
+          parse_hash(include_args)
+        when Array
+          parse_array(include_args)
+        when String
+          parse_string(include_args)
+        else
+          {}
+        end
+      end
+
+      # @api private
+      def parse_string(include_string)
+        include_string.split(',')
+          .each_with_object({}) do |path, hash|
+            deep_merge!(hash, parse_path_string(path))
+        end
+      end
+
+      # @api private
+      def parse_path_string(include_path)
+        include_path.split('.')
+          .reverse
+          .reduce({}) { |a, e| { e.to_sym => a } }
+      end
+
+      # @api private
+      def parse_hash(include_hash)
+        include_hash.each_with_object({}) do |(key, value), hash|
+          hash[key.to_sym] = parse_include_args(value)
+        end
+      end
+
+      # @api private
+      def parse_array(include_array)
+        include_array.each_with_object({}) do |x, hash|
+          deep_merge!(hash, parse_include_args(x))
+        end
+      end
+
+      # @api private
+      def deep_merge!(src, ext)
+        ext.each do |k, v|
+          if src[k].is_a?(Hash) && v.is_a?(Hash)
+            deep_merge!(src[k], v)
+          else
+            src[k] = v
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/include_directive.rb

@@ -0,0 +1,72 @@
+require 'jsonapi/include_directive/parser'
+
+module JSONAPI
+  # Represent a recursive set of include directives
+  # (c.f. http://jsonapi.org/format/#fetching-includes)
+  #
+  # Addition to the spec: two wildcards, namely '*' and '**'.
+  # The former stands for any one level of relationship, and the latter stands
+  # for any number of levels of relationships.
+  # @example 'posts.*' # => Include related posts, and all the included posts'
+  #   related resources.
+  # @example 'posts.**' # => Include related posts, and all the included
+  #   posts' related resources, and their related resources, recursively.
+  class IncludeDirective
+    # @param include_args (see Parser.parse_include_args)
+    def initialize(include_args, options = {})
+      include_hash = Parser.parse_include_args(include_args)
+      @hash = include_hash.each_with_object({}) do |(key, value), hash|
+        hash[key] = self.class.new(value, options)
+      end
+      @options = options
+    end
+
+    # @param key [Symbol, String]
+    def key?(key)
+      @hash.key?(key.to_sym) ||
+        (@options[:allow_wildcard] && (@hash.key?(:*) || @hash.key?(:**)))
+    end
+
+    # @return [Array<Symbol>]
+    def keys
+      @hash.keys
+    end
+
+    # @param key [Symbol, String]
+    # @return [IncludeDirective, nil]
+    def [](key)
+      case
+      when @hash.key?(key.to_sym)
+        @hash[key.to_sym]
+      when @options[:allow_wildcard] && @hash.key?(:**)
+        self.class.new({ :** => {} }, @options)
+      when @options[:allow_wildcard] && @hash.key?(:*)
+        @hash[:*]
+      end
+    end
+
+    # @return [Hash{Symbol => Hash}]
+    def to_hash
+      @hash.each_with_object({}) do |(key, value), hash|
+        hash[key] = value.to_hash
+      end
+    end
+
+    # @return [String]
+    def to_string
+      string_array = @hash.map do |(key, value)|
+        string_value = value.to_string
+        if string_value == ''
+          key.to_s
+        else
+          string_value
+            .split(',')
+            .map { |x| key.to_s + '.' + x }
+            .join(',')
+        end
+      end
+
+      string_array.join(',')
+    end
+  end
+end

data/lib/jsonapi/renderer.rb

@@ -0,0 +1,118 @@
+require 'jsonapi/include_directive'
+
+module JSONAPI
+  class Renderer
+    def initialize(resources, options = {})
+      @resources = resources
+      @errors = options[:errors] || false
+      @meta = options[:meta] || nil
+      @links = options[:links] || {}
+      @fields = options[:fields] || {}
+      # NOTE(beauby): Room for some nifty defaults on those.
+      @jsonapi = options[:jsonapi_object] || nil
+      @include = JSONAPI::IncludeDirective.new(options[:include] || {})
+    end
+
+    def as_json
+      return @json unless @json.nil?
+
+      process_resources
+      @json = {}
+
+      if @errors
+        @json[:errors] = @resources.map(&:as_jsonapi)
+      else
+        @json[:data] = @resources.respond_to?(:each) ? @primary : @primary[0]
+        @json[:included] = @included if @included.any?
+      end
+      @json[:links] = @links if @links.any?
+      @json[:meta] = @meta unless @meta.nil?
+      @json[:jsonapi] = @jsonapi unless @jsonapi.nil?
+
+      @json
+    end
+
+    private
+
+    def process_resources
+      @primary = []
+      @included = []
+      @hashes = {}
+      @processed = Set.new # NOTE(beauby): Set of [type, id, prefix].
+      @queue = []
+
+      Array(@resources).each do |res|
+        process_resource(res, '', @include, true)
+        @processed.add([res.jsonapi_type, res.jsonapi_id, ''])
+      end
+      until @queue.empty?
+        res, prefix, include_dir = @queue.pop
+        process_resource(res, prefix, include_dir, false)
+      end
+    end
+
+    def merge_resources!(a, b)
+      b[:relationships].each do |name, rel|
+        a[:relationships][name][:data] ||= rel[:data] if rel.key?(:data)
+        (a[:relationships][name][:links] ||= {})
+          .merge!(rel[:links]) if rel.key?(:links)
+      end
+    end
+
+    def process_resource(res, prefix, include_dir, is_primary)
+      ri = [res.jsonapi_type, res.jsonapi_id]
+      hash = res.as_jsonapi(fields: @fields[res.jsonapi_type.to_sym],
+                            include: include_dir.keys)
+      if @hashes.key?(ri)
+        merge_resources!(@hashes[ri], hash)
+      else
+        (is_primary ? @primary : @included) << (@hashes[ri] = hash)
+      end
+      process_relationships(res, prefix, include_dir)
+    end
+
+    def process_relationships(res, prefix, include_dir)
+      res.jsonapi_related(include_dir.keys).each do |key, data|
+        Array(data).each do |child_res|
+          child_prefix = "#{prefix}.#{key}"
+          next unless @processed.add?([child_res.jsonapi_type,
+                                       child_res.jsonapi_id,
+                                       child_prefix])
+          @queue << [child_res, child_prefix, include_dir[key]]
+        end
+      end
+    end
+  end
+
+  module_function
+
+  # Render a success JSON API document.
+  #
+  # @param [(#jsonapi_id, #jsonapi_type, #jsonapi_related, #as_jsonapi),
+  #         Array<(#jsonapi_id, #jsonapi_type, #jsonapi_related, #as_jsonapi)>,
+  #         nil] resources The primary resource(s) to be rendered.
+  # @param [Hash] options All optional.
+  #   @option [String, Hash{Symbol => Hash}] include Relationships to be
+  #     included.
+  #   @option [Hash{Symbol, Array<Symbol>}] fields List of requested fields
+  #     for some or all of the resource types.
+  #   @option [Hash] meta Non-standard top-level meta information to be
+  #     included.
+  #   @option [Hash] links Top-level links to be included.
+  #   @option [Hash] jsonapi_object JSON API object.
+  def render(resources, options = {})
+    Renderer.new(resources, options).as_json
+  end
+
+  # Render an error JSON API document.
+  #
+  # @param [Array<#jsonapi_id>] errors Errors to be rendered.
+  # @param [Hash] options All optional.
+  #   @option [Hash] meta Non-standard top-level meta information to be
+  #     included.
+  #   @option [Hash] links Top-level links to be included.
+  #   @option [Hash] jsonapi_object JSON API object.
+  def render_errors(errors)
+    Renderer.new(errors, errors: true).as_json
+  end
+end

metadata

@@ -0,0 +1,47 @@
+--- !ruby/object:Gem::Specification
+name: jsonapi-renderer
+version: !ruby/object:Gem::Version
+  version: 0.1.1.beta1
+platform: ruby
+authors:
+- Lucas Hosseini
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-10-02 00:00:00.000000000 Z
+dependencies: []
+description: Low-level renderer for JSONAPI documents.
+email: lucas.hosseini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/jsonapi/include_directive.rb
+- lib/jsonapi/include_directive/parser.rb
+- lib/jsonapi/renderer.rb
+homepage: https://github.com/beauby/jsonapi
+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: Render JSONAPI documents.
+test_files: []