roar-jsonapi 0.0.1

data/lib/roar/json/json_api/declarative.rb

@@ -0,0 +1,196 @@
+module Roar
+  module JSON
+    module JSONAPI
+      # Declarative API for JSON API Representers.
+      #
+      # @since 0.1.0
+      module Declarative
+        # Defjne a type for this resource.
+        #
+        # @example
+        #   type :articles
+        #
+        # @param [Symbol, String] name type name of this resource
+        # @return [String] type name of this resource
+        #
+        # @see http://jsonapi.org/format/#document-resource-object-identification
+        # @api public
+        def type(name = nil)
+          return @type unless name # original name.
+
+          heritage.record(:type, name)
+          @type = name.to_s
+        end
+
+        # Define attributes for this resource.
+        #
+        # @example
+        #   attributes do
+        #     property :name
+        #   end
+        #
+        # @param [#call] block
+        #
+        # @see http://jsonapi.org/format/#document-resource-object-attributes
+        # @api public
+        def attributes(&block)
+          nested(:attributes, inherit: true, &block)
+        end
+
+        # Define a link.
+        #
+        # @example Link for a resource
+        #   link(:self) { "http://authors/#{represented.id}" }
+        # @example Top-level link
+        #   link(:self, toplevel: true) { "http://authors/#{represented.id}" }
+        # @example Link with options
+        #   link(:self) do |opts|
+        #     "http://articles?locale=#{opts[:user_options][:locale]}"
+        #   end
+        #
+        #   representer.to_json(user_options: { locale: 'de' })
+        #
+        # @param [Symbol, String] name name of the link.
+        # @option options [Boolean] :toplevel place link at top-level of document.
+        #
+        # @yieldparam opts [Hash] Options passed to render method
+        #
+        # @see Roar::Hypermedia::ClassMethods#link
+        # @see http://jsonapi.org/format/#document-links
+        # @api public
+        def link(name, options = {}, &block)
+          return super(name, &block) unless options[:toplevel]
+          for_collection.link(name, &block)
+        end
+
+        # Define meta information.
+        #
+        # @example Meta information for a resource
+        #   meta do
+        #     collection :reviewers
+        #   end
+        # @example Top-level meta information
+        #   meta toplevel: true do
+        #     property :copyright
+        #   end
+        #
+        # @param (see Meta::ClassMethods#meta)
+        # @option options [Boolean] :toplevel place meta information at top-level of document.
+        #
+        # @see Meta::ClassMethods#meta
+        # @see http://jsonapi.org/format/#document-meta
+        # @api public
+        def meta(options = {}, &block)
+          return super(&block) unless options[:toplevel]
+          for_collection.meta(&block)
+        end
+
+        # Define links and meta information for a given relationship.
+        #
+        # @example
+        #   has_one :author, extend: AuthorDecorator do
+        #     relationship do
+        #       link(:self)     { "/articles/#{represented.id}/relationships/author" }
+        #       link(:related)  { "/articles/#{represented.id}/author" }
+        #     end
+        #   end
+        #
+        # @param [#call] block
+        #
+        # @api public
+        def relationship(&block)
+          return (@relationship ||= -> {}) unless block
+
+          heritage.record(:relationship, &block)
+          @relationship = block
+        end
+
+        #  Define a to-one relationship for this resource.
+        #
+        # @param [String] name name of the relationship
+        # @option options [Class,Module,Proc] :extend	Representer to use for parsing or rendering
+        # @option options [Proc] :prepare	Decorate the represented object
+        # @option options [Class,Proc] :class Class to instantiate when parsing nested fragment
+        # @option options [Proc] :instance Instantiate object directly when parsing nested fragment
+        # @param [#call] block Stuff
+        #
+        # @see http://trailblazer.to/gems/representable/3.0/function-api.html#options
+        # @api public
+        def has_one(name, options = {}, &block)
+          has_relationship(name, options.merge(collection: false), &block)
+        end
+
+        # Define a to-many relationship for this resource.
+        #
+        # @param (see #has_one)
+        # @option options (see #has_one)
+        #
+        # @api public
+        def has_many(name, options = {}, &block)
+          has_relationship(name, options.merge(collection: true), &block)
+        end
+
+        private
+
+        def has_relationship(name, options = {}, &block)
+          resource_decorator = options[:decorator] || options[:extends] ||
+                               Class.new(Roar::Decorator).tap { |decorator|
+                                 decorator.send(:include, JSONAPI::Resource.new(
+                                                            name,
+                                                            id_key: options.fetch(:id_key, :id)
+                                 ))
+                               }
+          resource_decorator.instance_exec(&block) if block
+
+          resource_identifier_representer = Class.new(resource_decorator)
+          resource_identifier_representer.class_eval do
+            def to_hash(_options = {})
+              super(fields: { self.class.type.to_sym => [] }, include: [], wrap: false)
+            end
+          end
+
+          nested(:included, inherit: true) do
+            property(name, collection: options[:collection],
+                           decorator:  resource_decorator,
+                           wrap:       false)
+          end
+
+          nested(:relationships, inherit: true) do
+            nested(:"#{name}_relationship", as: MemberName.(name)) do
+              property name, options.merge(as:           :data,
+                                           getter:       ->(opts) {
+                                             object = opts[:binding].send(:exec_context, opts)
+                                             value  = object.public_send(opts[:binding].getter)
+                                             # do not blow up on nil collections
+                                             if options[:collection] && value.nil?
+                                               []
+                                             else
+                                               value
+                                             end
+                                           },
+                                           render_nil:   true,
+                                           render_empty: true,
+                                           decorator:    resource_identifier_representer,
+                                           wrap:         false)
+
+              instance_exec(&resource_identifier_representer.relationship)
+
+              # rubocop:disable Lint/NestedMethodDefinition
+              def to_hash(*)
+                hash  = super
+                links = Renderer::Links.new.(hash, {})
+                meta  = render_meta({})
+
+                HashUtils.store_if_any(hash, 'links', links)
+                HashUtils.store_if_any(hash, 'meta',  meta)
+
+                hash
+              end
+              # rubocop:enable Lint/NestedMethodDefinition
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/roar/json/json_api/defaults.rb

@@ -0,0 +1,25 @@
+module Roar
+  module JSON
+    module JSONAPI
+      # Defines defaults for JSON API Representers.
+      #
+      # @api public
+      module Defaults
+        # Hook called when module is included
+        #
+        # @param [Class,Module] base
+        #   the module or class including Defaults
+        #
+        # @return [undefined]
+        #
+        # @api private
+        # @see http://www.ruby-doc.org/core/Module.html#method-i-included
+        def self.included(base)
+          base.defaults do |name, _|
+            { as: JSONAPI::MemberName.(name) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/roar/json/json_api/document.rb

@@ -0,0 +1,104 @@
+module Roar
+  module JSON
+    module JSONAPI
+      # Instance method API for JSON API Documents.
+      #
+      module Document
+        # Render the document as JSON
+        #
+        # @example Simple rendering
+        #   representer.to_json
+        #
+        # @example Rendering with compount documents and sparse fieldsets
+        #   uri   = Addressable::URI.parse('/articles/1?include=author,comments.author')
+        #   query = Rack::Utils.parse_nested_query(uri.query)
+        #   # => {"include"=>"author", "fields"=>{"articles"=>"title,body", "people"=>"name"}}
+        #
+        #   representer.to_json(
+        #     include: query['include'],
+        #     fields:  query['fields']
+        #   )
+        #
+        # @option options (see #to_hash)
+        #
+        # @return [String] JSON String
+        #
+        # @see http://jsonapi.org/format/#fetching-includes
+        # @see http://jsonapi.org/format/#fetching-sparse-fieldsets
+        # @api public
+        def to_json(options = {})
+          super
+        end
+
+        # Render the document as a Ruby Hash
+        #
+        # @option options [Array<#to_s>,#to_s,false] include
+        #   compound documents to include, specified as a list of relationship
+        #   paths (Array or comma-separated String) or `false`, if no compound
+        #   documents are to be included.
+        #
+        #   N.B. this syntax and behaviour for this option *is signficantly
+        #   different* to that of the `include` option implemented in other,
+        #   non-JSON API Representers.
+        # @option options [Hash{Symbol=>[Array<String>]}] fields
+        #   fields to returned on a per-type basis.
+        # @option options [Hash{#to_s}=>Object] meta
+        #   additional meta information to be rendered in the document.
+        # @option options [Hash{Symbol=>Symbol}] user_options
+        #   additional arbitary options to be passed to the Representer.
+        #
+        # @return [Hash{String=>Object}]
+        #
+        # @api public
+        def to_hash(options = {})
+          document  = super(Options::Include.(options, mappings))
+          unwrapped = options[:wrap] == false
+          resource  = unwrapped ? document : document['data']
+          resource['type'] = JSONAPI::MemberName.(self.class.type)
+
+          links = Renderer::Links.new.(resource, options)
+          meta  = render_meta(options)
+
+          resource.reject! do |_, v| v && v.empty? end
+
+          unless unwrapped
+            included = resource.delete('included')
+
+            HashUtils.store_if_any(document, 'included',
+                                   Fragment::Included.(included, options))
+          end
+
+          HashUtils.store_if_any(resource, 'links', links)
+          HashUtils.store_if_any(document, 'meta',  meta)
+
+          document
+        end
+
+        private
+
+        def mappings
+          @mappings ||= begin
+            mappings = {}
+            mappings[:id]             = find_id_mapping
+            mappings[:relationships]  = find_relationship_mappings
+            mappings[:relationships]['_self'] = self.class.type
+            mappings
+          end
+        end
+
+        def find_id_mapping
+          self.class.definitions.detect { |definition|
+            definition[:as] && definition[:as].evaluate(:value) == 'id'
+          }.name
+        end
+
+        def find_relationship_mappings
+          included_definitions = self.class.definitions['included'].representer_module.definitions
+          included_definitions.each_with_object({}) do |definition, hash|
+            hash[definition.name] = definition.representer_module.type
+          end
+        end
+      end
+    end
+  end
+end

data/lib/roar/json/json_api/for_collection.rb

@@ -0,0 +1,35 @@
+module Roar
+  module JSON
+    module JSONAPI
+      # @api private
+      module ForCollection
+        def collection_representer!(_options)
+          singular = self # e.g. Song::Representer
+
+          nested_builder.(_base: default_nested_class, _features: [Roar::JSON, Roar::Hypermedia, JSONAPI::Defaults, JSONAPI::Meta], _block: proc do
+            collection :to_a, as: :data, decorator: singular, wrap: false
+            # rubocop:disable Lint/NestedMethodDefinition
+            def to_hash(options = {})
+              document = super(to_a: options, user_options: options[:user_options]) # [{data: {..}, data: {..}}]
+
+              links = Renderer::Links.new.(document, options)
+              meta  = render_meta(options)
+              included = []
+              document['data'].each do |single|
+                included += single.delete('included') || []
+              end
+
+              HashUtils.store_if_any(document, 'included',
+                                     Fragment::Included.(included, options))
+              HashUtils.store_if_any(document, 'links',    links)
+              HashUtils.store_if_any(document, 'meta',     meta)
+
+              document
+            end
+            # rubocop:enable Lint/NestedMethodDefinition
+          end)
+        end
+      end
+    end
+  end
+end

data/lib/roar/json/json_api/member_name.rb

@@ -0,0 +1,57 @@
+# encoding=utf-8
+
+module Roar
+  module JSON
+    module JSONAPI
+      # Member Name formatting according to the JSON API specification.
+      #
+      # @see http://jsonapi.org/format/#document-member-names
+      # @since 0.1.0
+      class MemberName
+        # @api private
+        LENIENT_FILTER_REGEXP = /([^[:alnum:][-_ ]]+)/
+        # @api private
+        STRICT_FILTER_REGEXP  = /([^[0-9a-z][-_]]+)/
+
+        # @see #call
+        def self.call(name, options = {})
+          new.(name, options)
+        end
+
+        # Format a member name
+        #
+        # @param [String, Symbol] name
+        #   member name.
+        # @option options [Boolean] :strict
+        #   whether strict mode is enabled.
+        #
+        #   Strict mode applies additional JSON Specification *RECOMMENDATIONS*,
+        #   permitting only non-reserved, URL safe characters specified in RFC 3986.
+        #   The member name will be lower-cased and underscores will be
+        #   transformed to hyphens.
+        #
+        #   Non-strict mode permits:
+        #   * non-ASCII alphanumeric Unicode characters.
+        #   * spaces, underscores and hyphens, except as the first or last character.
+        #
+        # @return [String] formatted member name.
+        #
+        # @api public
+        def call(name, options = {})
+          name    = name.to_s
+          strict  = options.fetch(:strict, true)
+          if strict
+            name.downcase!
+            name.gsub!(STRICT_FILTER_REGEXP, ''.freeze)
+          else
+            name.gsub!(LENIENT_FILTER_REGEXP, ''.freeze)
+          end
+          name.gsub!(/\A([-_ ])/, '')
+          name.gsub!(/([-_ ])\z/, '')
+          name.tr!('_', '-') if strict
+          name
+        end
+      end
+    end
+  end
+end

data/lib/roar/json/json_api/meta.rb

@@ -0,0 +1,56 @@
+module Roar
+  module JSON
+    module JSONAPI
+      # Meta information API for JSON API Representers.
+      #
+      # @api public
+      module Meta
+        # Hook called when module is included
+        #
+        # @param [Class,Module] base
+        #   the module or class including JSONAPI
+        #
+        # @return [undefined]
+        #
+        # @api private
+        # @see http://www.ruby-doc.org/core/Module.html#method-i-included
+        def self.included(base)
+          base.extend ClassMethods
+        end
+
+        # Class level interface
+        module ClassMethods
+          # Define meta information.
+          #
+          # @example
+          #   meta do
+          #     property :copyright
+          #     collection :reviewers
+          #   end
+          #
+          # @param [#call] block
+          #
+          # @see http://jsonapi.org/format/#document-meta
+          # @api public
+          def meta(&block)
+            representable_attrs[:meta_representer] ||= nested_builder.(
+              _base:     default_nested_class,
+              _features: [Roar::JSON, JSONAPI::Defaults],
+              _block:    Proc.new
+            )
+            representable_attrs[:meta_representer].instance_exec(&block)
+          end
+        end
+
+        private
+
+        def render_meta(options)
+          representer = representable_attrs[:meta_representer]
+          meta        = representer ? representer.new(represented).to_hash : {}
+          meta.merge!(options[:meta]) if options[:meta]
+          meta
+        end
+      end
+    end
+  end
+end