jsonapi-serializable 0.1.1.beta4 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b7a55ca51fb13e04ac2c96153ea3558aef19d35
-  data.tar.gz: 7a378903d6206bdc7cb203bd47a5ec415034ec87
+  metadata.gz: bb3b603af78361747fc5ff33c1a81c19c66a78af
+  data.tar.gz: 8113fbfcbc52ff590bf7b820dbee01fa43b37b8b
 SHA512:
-  metadata.gz: a29424f72a6a0170319503da5f7aa3a8bb62633cdcd496d0e0ae89f5a7431fe6b9dd763e8ff6fe44aa2823fa897c191434f6fe211836cc3133dcc57654ebb065
-  data.tar.gz: 18ead5e2f56d6cad50e432c4d09f5f7590df9d27e1b52348d0d3ca1f72e8efd22065d0c763cd3e1b8340ab692fb7c1fb8633674f572dc5dfa9eeb5475a19d66f
+  metadata.gz: 54f95566a246044b529b017fd7bf38da736ece3332ee79d221752221baf9840f3ae26d1482061dfce323775fed052fee98bcc879e65e583a6a3943f70dcfa4a7
+  data.tar.gz: f9557913f0fa0ee5fa6c35212fdb193ffc2bae554205e988039de7f80ecdf1a3e3c8e9c85d740f9922e85d06e69c1cb51559834e3166e2005142caca0e2d42b7

data/README.md

@@ -1,22 +1,12 @@
 # jsonapi-serializable
-Ruby gem for building [JSON API](http://jsonapi.org) resources to be rendered by
-the [jsonapi-renderer](https://github.com/jsonapi-rb/renderer) gem.
+Ruby gem for building and rendering [JSON API](http://jsonapi.org) documents.
 
 ## Status
 
 [![Gem Version](https://badge.fury.io/rb/jsonapi-serializable.svg)](https://badge.fury.io/rb/jsonapi-serializable)
-[![Build Status](https://secure.travis-ci.org/jsonapi-rb/serializable.svg?branch=master)](http://travis-ci.org/jsonapi-rb/serializable?branch=master)
-
-## Table of Contents
-
-  - [Installation](#installation)
-  - [Usage](#usage)
-  - [Documentation](#documentation)
-    - [`JSONAPI::Serializable::Resource` DSL](#jsonapiserializableresource-dsl)
-    - [`JSONAPI::Serializable::Relationship` DSL](#jsonapiserializablerelationship-dsl)
-    - [`JSONAPI::Serializable::Link` DSL](#jsonapiserializablelink-dsl)
-    - [`JSONAPI::Serializable::Error` DSL](#jsonapiserializableerror-dsl)
-  - [License](#license)
+[![Build Status](https://secure.travis-ci.org/jsonapi-rb/jsonapi-serializable.svg?branch=master)](http://travis-ci.org/jsonapi-rb/jsonapi-serializable?branch=master)
+[![codecov](https://codecov.io/gh/jsonapi-rb/jsonapi-serializable/branch/master/graph/badge.svg)](https://codecov.io/gh/jsonapi-rb/jsonapi-serializable)
+[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/jsonapi-rb/Lobby)
 
 ## Installation
 ```ruby
@@ -32,288 +22,9 @@ or manually via
 $ gem install jsonapi-serializable
 ```
 
-## Usage
-
-First, require the gem:
-```ruby
-require 'jsonapi/serializable'
-```
-
-Then, define some resource classes:
-
-```ruby
-class PostResource < JSONAPI::Serializable::Resource
-  type 'posts'
-
-  attribute :title
-
-  attribute :date do
-    @object.created_at
-  end
-
-  has_one :author, 'V2::SerializableUser' do
-    link(:self) do
-      href @url_helpers.link_for_rel('posts', @object.id, 'author')
-      meta link_meta: 'some meta'
-    end
-    link(:related) { @url_helpers.link_for_res('users', @object.author.id) }
-    meta do
-      { relationship_meta: 'some meta' }
-    end
-  end
-
-  has_many :comments
-
-  meta do
-    { resource_meta: 'some meta' }
-  end
-
-  link(:self) do
-    @url_helpers.link_for_res('posts', @object.id)
-  end
-end
-```
-
-Then, render your resources:
-```ruby
-# `post` is some `Post` object
-# `UrlHelpers` is some helper class
-document = JSONAPI::Serializable::Renderer.render(
-  post,
-  expose: { url_helpers: UrlHelpers.new }
-)
-```
-
-## Documentation
-
-### `JSONAPI::Serializable::AbstractResource` DSL
-
-+ `#initialize(hash)`
-
-All the values of the hash are made available during serialization as instance
-variables within all DSLs.
-
-Example:
-```ruby
-SerializablePost.new(post: post, url_helpers: url_helpers)
-# => You can then use @post and @url_helpers from within the DSL.
-```
-
-+ `::type(value = nil, &block)`
-
-Define the type of the resource, either statically, or dynamically as the
-return value of the block.
-
-+ `::id(&block)`
-
-Define the id of the resource.
-
-Example:
-```ruby
-id { @post.id }
-```
-
-+ `::attribute(key, &block)`
-
-Define an attribute of the resource.
-
-Example:
-```ruby
-attribute(:title) { @post.title }
-```
-
-+ `::relationship(key, &block)`
-
-Define a relationship of the resource. The block can contain any instruction of
-the [`JSONAPI::Serializable::Relationship` DSL](#jsonapiserializablerelationship-dsl).
-
-Example:
-```ruby
-relationship :comments do
-  resources do
-    @post.comments.map do |c|
-      SerializableComment.new(comment: c, url_helpers: @url_helpers)
-    end
-  end
-  link :self do
-    @url_helpers.link_for_post_comments(post_id: @post.id)
-  end
-  meta do
-    { count: @post.comments.count }
-  end
-end
-```
-
-+ `::link(key, &block)`
-
-Define a resource-level link. The block can either return a string or contain
-any instruction of the [`JSONAPI::Serializable::Link` DSL](#jsonapiserializablelink-dsl).
-
-Example:
-```ruby
-link :self do
-  "http://api.example.com/posts/#{@post.id}"
-end
-```
-
-+ `::meta(value = nil, &block)`
-
-Define a resource-level meta member. The value can either be provided
-statically, or dynamically as the return value of a block.
-
-Examples:
-```ruby
-meta(experimental: true)
-```
-```ruby
-meta do
-  { remaining_time: @post.remaining_time }
-end
-```
-
-### `JSONAPI::Serializable::Resource` DSL
-
-This class is a subclass of `JSONAPI::Serializable::AbstractResource` with a more
-convenient DSL tailored for resources that are direct representation of some
-business models.
-
-+ `#initialize(hash)`
-
-See `JSONAPI::Serializable::AbstractResource` DSL.
-
-The model is expected to be provided in the hash with the key `:model`.
-
-+ `::type(value = nil, &block)`
-
-See `JSONAPI::Serializable::AbstractResource` DSL.
-
-+ `::id(&block)`
-
-See `JSONAPI::Serializable::AbstractResource` DSL.
-
-Defaults to:
-```ruby
-id { @model.id }
-```
-
-+ `::attribute(key, &block)`
-
-See `JSONAPI::Serializable::AbstractResource` DSL.
-
-Defaults to the following when no block is provided:
-```ruby
-attribute key do
-  @model.public_send(key)
-end
-```
-
-+ `::attributes(*keys)`
-
-Define multiple attributes.
-
-+ `::has_one(key, resource_klass = nil, &block)`
-
-Define a `has_one` relationship on the resource.
-
-The serializable class for the related resource can be explicitly stated as the
-second parameter, but when omitted it will be infered from the related
-resource's class name.
-
-When no block is provided, the value of the relationship defaults to
-`resource_klass.new(model: @model.public_send(key))`.
-
-+ `::has_many(key, resource_klass = nil, &block)`
-
-Define a `has_many` relationship on the resource.
-
-The serializable class for the related resources can be explicitly stated as the
-second parameter, but when omitted it will be infered from the related
-resources' class names.
-
-When no block is provided, the value of the relationship defaults to:
-```ruby
-@model.public_send(key).map do |r|
-  resource_klass.new(model: r)
-end
-```
-
-+ `::relationship(key, &block)`
-
-See `JSONAPI::Serializable::AbstractResource` DSL.
-
-+ `::link(key, &block)`
-
-See `JSONAPI::Serializable::AbstractResource` DSL.
-
-+ `::meta(value = nil, &block)`
-
-See `JSONAPI::Serializable::AbstractResource` DSL.
-
-### `JSONAPI::Serializable::Relationship` DSL
-
-+ `::resources(resource_class = nil, &block)`
-
-NOTE: This section is outdated. It is still valid, but the resources method is
-now much more flexible.
-
-Defines the related serializable resources for the relationship.
-
-Example:
-```ruby
-resources do
-  if @post.author.nil?
-    nil
-  else
-    SerializableUser.new(user: @post.author)
-  end
-end
-```
-
-+ `::data(&block)`
-
-Explicitly define linkage data (optional).
-
-+ `::link(key, &block)`
-
-Define a relationship-level link.
-
-See `JSONAPI::Serializable::AbstractResource` DSL.
-
-+ `::meta(value = nil, &block)`
-
-Define some relationship-level meta member.
-
-See `JSONAPI::Serializable::AbstractResource` DSL.
-
-### `JSONAPI::Serializable::Link` DSL
-
-+ `::href(value = nil, &block)`
-
-Define the href member for the link, either directly, or dynamically as the
-return value of a block.
-
-+ `::meta(value = nil, &block)`
-
-Define the meta member for the link, either directly, or dynamically as the
-return value of a block.
-
-### `JSONAPI::Serializable::Error` DSL
-
-+ `::id(value = nil, &block)`
-
-+ `::status(value = nil, &block)`
-
-+ `::code(value = nil, &block)`
-
-+ `::title(value = nil, &block)`
-
-+ `::detail(value = nil, &block)`
-
-+ `::meta(value = nil, &block)`
-
-+ `::link(key, &block)`
+## Usage and documentation
 
-+ `::source(&block)`
+See [jsonapi-rb.org/guides](http://jsonapi-rb.org/guides).
 
 ## License
 

data/lib/jsonapi/serializable/error.rb

@@ -4,13 +4,14 @@ require 'jsonapi/serializable/error_dsl'
 module JSONAPI
   module Serializable
     class ErrorSource
-      def self.as_jsonapi(params = {})
-        self.class.new(params).as_jsonapi
+      def self.as_jsonapi(params = {}, &block)
+        new(params, &block).as_jsonapi
       end
 
-      def initialize(params = {})
+      def initialize(params = {}, &block)
         params.each { |k, v| instance_variable_set("@#{k}", v) }
         @_data = {}
+        instance_eval(&block)
       end
 
       def as_jsonapi
@@ -19,6 +20,7 @@ module JSONAPI
 
       private
 
+      # @api private
       def method_missing(name, arg)
         @_data[name] = arg
       end
@@ -28,16 +30,17 @@ module JSONAPI
       include ErrorDSL
 
       class << self
-        attr_accessor :id, :id_block, :status, :status_block, :code,
-                      :code_block, :title, :title_block, :detail, :detail_block,
-                      :meta, :meta_block, :source_block, :link_blocks
+        attr_accessor :id_val, :id_block, :status_val, :status_block, :code_val,
+                      :code_block, :title_val, :title_block, :detail_val,
+                      :detail_block, :meta_val, :meta_block, :source_block,
+                      :link_blocks
       end
 
       self.link_blocks = {}
 
       def self.inherited(klass)
         super
-        klass.link_blocks = self.class.link_blocks.dup
+        klass.link_blocks = link_blocks.dup
       end
 
       def initialize(exposures = {})
@@ -58,23 +61,30 @@ module JSONAPI
 
       def links
         @_links ||= self.class.link_blocks.each_with_object({}) do |(k, v), h|
-          h[k] = Link.as_jsonapi(@_exposures, v)
+          h[k] = Link.as_jsonapi(@_exposures, &v)
         end
       end
 
       def source
-        @_source ||= ErrorSource.as_jsonapi(@_exposures,
-                                            self.class.source_block)
+        return @_source if @_source
+        return if self.class.source_block.nil?
+        @_source = ErrorSource.as_jsonapi(@_exposures,
+                                          &self.class.source_block)
       end
 
       [:id, :status, :code, :title, :detail, :meta].each do |key|
         define_method(key) do
-          unless instance_variable_defined?("@#{key}")
-            value = self.class.send(key) ||
-                    instance_eval(self.class.send("#{key}_block"))
-            instance_variable_set("@#{key}", value)
+          unless instance_variable_defined?("@_#{key}")
+            block = self.class.send("#{key}_block")
+            value =
+              if block
+                instance_eval(&block)
+              else
+                self.class.send("#{key}_val")
+              end
+            instance_variable_set("@_#{key}", value)
           end
-          instance_variable_get("@#{key}")
+          instance_variable_get("@_#{key}")
         end
       end
     end

data/lib/jsonapi/serializable/error_dsl.rb

@@ -6,11 +6,34 @@ module JSONAPI
       end
 
       module ClassMethods
-        [:id, :status, :code, :title, :detail, :meta].each do |key|
-          define_method(key) do |*args, &block|
-            send("@#{key}=", args[0])
-            send("@#{key}_block=", block)
-          end
+        def id(value = nil, &block)
+          @id_val = value
+          @id_block = block
+        end
+
+        def status(value = nil, &block)
+          @status_val = value
+          @status_block = block
+        end
+
+        def code(value = nil, &block)
+          @code_val = value
+          @code_block = block
+        end
+
+        def title(value = nil, &block)
+          @title_val = value
+          @title_block = block
+        end
+
+        def detail(value = nil, &block)
+          @detail_val = value
+          @detail_block = block
+        end
+
+        def meta(value = nil, &block)
+          @meta_val = value
+          @meta_block = block
         end
 
         def link(name, &block)

data/lib/jsonapi/serializable/fieldset.rb

@@ -0,0 +1,7 @@
+module JSONAPI
+  module Serializable
+    class FieldSet
+
+    end
+  end
+end

data/lib/jsonapi/serializable/link.rb

@@ -8,11 +8,7 @@ module JSONAPI
       def initialize(exposures = {}, &block)
         exposures.each { |k, v| instance_variable_set("@#{k}", v) }
         static_value = instance_eval(&block)
-        if static_value.is_a?(Hash)
-          @_hash = static_value
-        elsif static_value.is_a?(String)
-          @_href = static_value
-        end
+        @_href = static_value if static_value.is_a?(String)
       end
 
       # @overload href(value)

data/lib/jsonapi/serializable/relationship/dsl.rb

@@ -0,0 +1,121 @@
+require 'jsonapi/serializable/resource_builder'
+
+module JSONAPI
+  module Serializable
+    class Relationship
+      module DSL
+        # Declare the related resources for this relationship.
+        # @param [String,Constant,Hash{Symbol=>String,Constant}] resource_class
+        # @yieldreturn The related resources for this relationship.
+        #   If it is nil, an object implementing the Serializable::Resource
+        #   interface, an empty array, or an array of objects implementing the
+        #   Serializable::Resource interface, then it is used as is.
+        #   Otherwise an appropriate Serializable::Resource subclass is inferred
+        #   from the object(s)' namespace/class, the resource_class parameter if
+        #   provided, and the @_resource_inferrer.
+        #
+        # @example
+        #   data do
+        #     @user.posts.map { |p| PostResource.new(post: p) }
+        #   end
+        #
+        # @example
+        #   data do
+        #     @post.author && UserResource.new(user: @user.author)
+        #   end
+        #
+        # @example
+        #   data do
+        #     @user.posts
+        #   end
+        # end
+        #
+        # @example
+        #   data SerializablePost do
+        #     @user.posts
+        #   end
+        #
+        # @example
+        #   data "SerializableUser" do
+        #     @post.author
+        #   end
+        def data(resource_class = nil)
+          # NOTE(beauby): Lazify computation since it is only needed when
+          #   the corresponding relationship is included.
+          @_resources_block = proc do
+            _resources_for(yield, resource_class)
+          end
+        end
+
+        # @overload linkage(options = {}, &block)
+        #   Explicitly declare linkage data.
+        #   @yieldreturn The resource linkage.
+        #
+        #   @example
+        #     linkage do
+        #       @object.posts.map { |p| { id: p.id.to_s, type: 'posts' } }
+        #     end
+        #
+        # @overload linkage(options = {})
+        #   Forces standard linkage even if relationship not included.
+        #
+        #   @example
+        #     linkage always: true
+        def linkage(always: false, &block)
+          @_include_linkage = always
+          @_linkage_block = block
+        end
+
+        # @overload meta(value)
+        #   Declare the meta information for this relationship.
+        #   @param [Hash] value The meta information hash.
+        #
+        #   @example
+        #     meta paginated: true
+        #
+        # @overload meta(&block)
+        #   Declare the meta information for this relationship.
+        #   @yieldreturn [Hash] The meta information hash.
+        #
+        #   @example
+        #     meta do
+        #       { paginated: true }
+        #     end
+        def meta(value = nil)
+          @_meta = value || yield
+        end
+
+        # Declare a link for this relationship. The properties of the link are set
+        #   by providing a block in which the DSL methods of
+        #   +JSONAPI::Serializable::Link+ are called.
+        # @see JSONAPI::Serialiable::Link
+        #
+        # @param [Symbol] name The key of the link.
+        # @yieldreturn [Hash, String, nil] The block to compute the value, if any.
+        #
+        # @example
+        #   link(:self) do
+        #     "http://api.example.com/users/#{@user.id}/relationships/posts"
+        #   end
+        #
+        # @example
+        #    link(:related) do
+        #      href "http://api.example.com/users/#{@user.id}/posts"
+        #      meta authorization_needed: true
+        #    end
+        def link(name, &block)
+          @_links[name] = Link.as_jsonapi(@_exposures, &block)
+        end
+
+        private
+
+        # @api private
+        def _resources_for(objects, resource_class)
+          resource_class ||= @_resource_inferrer
+
+          ResourceBuilder.build(objects, @_exposures, resource_class)
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/serializable/relationship.rb

@@ -1,10 +1,10 @@
 require 'jsonapi/serializable/link'
-require 'jsonapi/serializable/relationship_dsl'
+require 'jsonapi/serializable/relationship/dsl'
 
 module JSONAPI
   module Serializable
     class Relationship
-      include RelationshipDSL
+      include DSL
 
       def initialize(exposures = {}, &block)
         exposures.each { |k, v| instance_variable_set("@#{k}", v) }
@@ -15,25 +15,26 @@ module JSONAPI
 
       def as_jsonapi(included)
         {}.tap do |hash|
-          hash[:links] = @_links if @_links.any?
-          hash[:meta]  = @_meta  unless @_meta.nil?
-          include_linkage = included || (!@_links.any? && @_meta.nil?)
-          hash[:data] = linkage_data if include_linkage
+          hash[:links] = @_links           if @_links.any?
+          hash[:data]  = linkage_data      if included || @_include_linkage
+          hash[:meta]  = @_meta            unless @_meta.nil?
+          hash[:meta]  = { included: false } if hash.empty?
         end
       end
 
+      # @api private
       def related_resources
-        return @_related_resources if @_related_resources
-
-        resources = @_resources_block.call
-        @_arity = resources.respond_to?(:each) ? :many : :one
-        @_related_resources = Array(resources)
-
-        @_related_resources
+        @_related_resources ||= Array(resources)
       end
 
       private
 
+      # @api private
+      def resources
+        @_resources ||= @_resources_block.call
+      end
+
+      # @api private
       def linkage_data
         return @_linkage_block.call if @_linkage_block
 
@@ -41,7 +42,7 @@ module JSONAPI
           { type: res.jsonapi_type, id: res.jsonapi_id }
         end
 
-        @_arity == :many ? linkage_data : linkage_data.first
+        resources.respond_to?(:each) ? linkage_data : linkage_data.first
       end
     end
   end