roar-jsonapi 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ece64905f608afe23b1ff500b22cc2735773ff4d
+  data.tar.gz: 8b9b74e066c310d7dfcc1fb615ec050df9e825ea
+SHA512:
+  metadata.gz: f9617c6cbe337a9d0533f67426fd6b8ce83420e7873f783acea631e7227a39e59097dd11b4a80916d694b2d5771dd9a47da2e7212c12096960eaf72e7058ce3b
+  data.tar.gz: 320c347be830d71313d237cb66460dfa1ef63ae0492c73d6064f3e5cba0bf50497a1c51769c249ae9a7047681063d659d81e1b0f97aa2fe9e0f2ed797fd86d20

data/.gitignore

@@ -0,0 +1,5 @@
+pkg/*
+*.gem
+.bundle
+Gemfile*.lock
+.idea

data/.rubocop.yml

@@ -0,0 +1,37 @@
+AllCops:
+  TargetRubyVersion: 1.9
+
+Style/AlignHash:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Style/AndOr:
+  EnforcedStyle: conditionals
+
+Style/BlockDelimiters:
+  Enabled: true
+  EnforcedStyle: semantic
+  IgnoredMethods:
+    - lambda
+    - proc
+    - it
+    - link
+
+Style/Lambda:
+  Enabled: false
+  EnforcedStyle: literal
+
+Style/LambdaCall:
+  EnforcedStyle: braces
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 15
+
+Style/PredicateName:
+  NameWhitelist:
+    - is_a?
+    - has_one
+    - has_many

data/.travis.yml

@@ -0,0 +1,14 @@
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 1.9.3
+  - 2.1
+  - 2.2.6
+  - 2.3.1
+  - 2.4.0
+  - jruby-9.1.6.0
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/.yardopts

@@ -0,0 +1,5 @@
+--markup markdown
+--no-private
+-
+README.markdown
+LICENSE

data/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+## How to contribute to Roar
+
+#### **Did you find a bug?**
+
+* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/trailblazer/roar-jsonapi/issues).
+
+* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/trailblazer/roar-jsonapi/issues/new). Be sure to follow the issue template.
+
+#### **Did you write a patch that fixes a bug?**
+
+* Open a new GitHub pull request with the patch.
+
+* Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.
+
+* All code in pull requests is assumed to be MIT licensed.  Do not submit a pull request if that isn't the case.
+
+#### **Do you intend to add a new feature or change an existing one?**
+
+* Suggest your change in the [Trailblazer Gitter Room](https://gitter.im/trailblazer/chat) and start writing code.
+
+* Do not open an issue on GitHub until you have collected positive feedback about the change. GitHub issues are primarily intended for bug reports and fixes.
+
+#### **Do you have questions using Roar?**
+
+* Ask any questions about how to use Roar in the [Trailblazer Gitter Room](https://gitter.im/trailblazer/chat). Github issues are restricted to bug reports and fixes.
+
+* GitHub Issues should not be used as a help forum and any such issues will be closed.
+
+#### **Do you want to contribute to the Roar documentation?**
+
+* Roar documentation is provided via the [Trailblazer site](http://trailblazer.to/gems/roar/) and not the repository readme. Please add your contributions to the [Trailblazer site repository](https://github.com/trailblazer/trailblazer.github.io)

data/Gemfile

@@ -0,0 +1,11 @@
+source 'http://rubygems.org'
+
+gemspec
+
+gem 'roar', github: 'trailblazer/roar', branch: 'master'
+
+gem 'minitest-line'
+gem 'minitest-reporters'
+gem 'pry'
+
+gem 'json_spec', require: nil

data/ISSUE_TEMPLATE.md

@@ -0,0 +1,20 @@
+Note: If you have a question about Roar, would like help using
+Roar, want to request a feature, or do anything else other than
+submit a bug report, please use the Trailblazer gitter channel.
+
+### Complete Description of Issue
+
+
+### Steps to reproduce
+
+
+### Expected behavior
+Tell us what should happen
+
+### Actual behavior
+Tell us what happens instead
+
+### System configuration
+**Roar version**:
+
+### Full Backtrace of Exception (if any)

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 - 2017 Nick Sutterer and the roar contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,127 @@
+# Roar JSON API
+
+_Resource-Oriented Architectures in Ruby._
+
+[![Gitter Chat](https://badges.gitter.im/trailblazer/chat.svg)](https://gitter.im/trailblazer/chat)
+[![TRB Newsletter](https://img.shields.io/badge/TRB-newsletter-lightgrey.svg)](http://trailblazer.to/newsletter/)
+[![Build Status](https://travis-ci.org/trailblazer/roar-jsonapi.svg?branch=master)](https://travis-ci.org/trailblazer/roar-jsonapi)
+[![Gem Version](https://badge.fury.io/rb/roar-jsonapi.svg)](http://badge.fury.io/rb/roar-jsonapi)
+
+Roar JSON API provides support for [JSON API](http://jsonapi.org/), a specification for building APIs in JSON. It can render _and_ parse singular and collection documents.
+
+### Resource
+
+A minimal representation of a Resource can be defined as follows:
+
+```ruby
+require 'roar/json/json_api'
+
+class SongsRepresenter < Roar::Decorator
+  include Roar::JSON::JSONAPI.resource :songs
+
+  attributes do
+    property :title
+  end
+end
+```
+
+Properties (or attributes) of the represented model are defined within an
+`attributes` block.
+
+An `id` property will automatically defined when using Roar JSON API.
+
+### Relationships
+
+To define relationships, use `::has_one` or `::has_many` with either an inline
+or a standalone representer (specified with the `extend:` or `decorates:` option).
+
+```ruby
+class SongsRepresenter < Roar::Decorator
+  include Roar::JSON::JSONAPI.resource :songs
+
+  has_one :album do
+    property :title
+  end
+
+  has_many :musicians, extend: MusicianRepresenter
+end
+```
+
+### Meta information
+
+Meta information can be included into rendered singular and collection documents in two ways.
+
+You can define meta information on your collection object and then let Roar compile it.
+
+```ruby
+class SongsRepresenter < Roar::Decorator
+  include Roar::JSON::JSONAPI.resource :songs
+
+  meta toplevel: true do
+    property :page
+    property :total
+  end
+end
+```
+
+Your collection object must expose the respective methods.
+
+```ruby
+collection.page  #=> 1
+collection.total #=> 12
+```
+
+This will render the `{"meta": {"page": 1, "total": 12}}` hash into the JSON API document.
+
+Alternatively, you can provide meta information as a hash when rendering.  Any values also defined on your object will be overriden.
+
+```ruby
+collection.to_json(meta: {page: params["page"], total: collection.size})
+```
+
+Both methods work for singular documents too.
+
+```ruby
+class SongsRepresenter < Roar::Decorator
+  include Roar::JSON::JSONAPI.resource :songs
+
+  meta do
+    property :label
+    property :format
+  end
+end
+```
+
+```ruby
+song.to_json(meta: { label: 'EMI' })
+```
+
+If you need more functionality (and parsing), please let us know.
+
+### Usage
+
+As JSON API per definition can represent singular models and collections you have two entry points.
+
+```ruby
+SongsRepresenter.prepare(Song.find(1)).to_json
+SongsRepresenter.prepare(Song.new).from_json("..")
+```
+
+Singular models can use the representer module directly.
+
+```ruby
+SongsRepresenter.for_collection.prepare([Song.find(1), Song.find(2)]).to_json
+SongsRepresenter.for_collection.prepare([Song.new, Song.new]).from_json("..")
+```
+
+
+Parsing currently works great with singular documents - for collections, we are still working out how to encode the application semantics. Feel free to help.
+
+## Support
+
+Questions? Need help? Free 1st Level Support on irc.freenode.org#roar !
+We also have a [mailing list](https://groups.google.com/forum/?fromgroups#!forum/roar-talk), yiha!
+
+## License
+
+Roar is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+task default: [:test]
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/**/*_test.rb']
+  test.verbose = true
+end

data/lib/roar/json/json_api.rb

@@ -0,0 +1,156 @@
+require 'roar/json'
+require 'roar/decorator'
+require 'set'
+
+require 'roar/json/json_api/member_name'
+
+require 'roar/json/json_api/defaults'
+require 'roar/json/json_api/meta'
+require 'roar/json/json_api/declarative'
+require 'roar/json/json_api/for_collection'
+require 'roar/json/json_api/options'
+require 'roar/json/json_api/document'
+
+module Roar
+  module JSON
+    module JSONAPI
+      # Include to define a JSON API Resource and make API methods available to
+      # your `Roar::Decorator`.
+      #
+      # @api public
+      class Resource < Module
+        # @param [Symbol, String] type type name of this resource.
+        # @option options [Symbol] :id_key custom ID key for this resource.
+        def initialize(type, options = {})
+          @type   = type
+          @id_key = options.fetch(:id_key, :id)
+        end
+
+        private
+
+        # 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 included(base)
+          base.send(:include, JSONAPI::Mixin)
+          base.type(@type)
+          base.property(@id_key, as: :id, render_filter: ->(input, _opts) {
+                                                           input.to_s
+                                                         })
+        end
+      end
+
+      # Include to define a JSON API Resource and make API methods available to
+      # your `Roar::Decorator`.
+      #
+      # @example Basic Usage
+      #   class SongsRepresenter < Roar::Decorator
+      #     include Roar::JSON::JSONAPI.resource :songs
+      #   end
+      #
+      # @example Custom ID key
+      #   class SongsRepresenter < Roar::Decorator
+      #     include Roar::JSON::JSONAPI.resource :songs, id_key: :song_id
+      #   end
+      #
+      # @param (see Resource.initialize)
+      # @option options (see Resource.initialize)
+      #
+      # @see Mixin
+      # @api public
+      def self.resource(type, options = {})
+        Resource.new(type, options)
+      end
+
+      # Include to make API methods available to your `Roar::Decorator`.
+      #
+      # Unlike {Resource}, you must define a `type` (by calling
+      # {Declarative#type}) and `id` property separately.
+      #
+      # @example Basic Usage
+      #   class SongsRepresenter < Roar::Decorator
+      #     include Roar::JSON::JSONAPI::Mixin
+      #
+      #     type :songs
+      #     property :id
+      #   end
+      #
+      # @see Resource
+      # @api semi-public
+      module Mixin
+        # 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.class_eval do
+            feature Roar::JSON
+            feature Roar::Hypermedia
+            feature JSONAPI::Defaults, JSONAPI::Meta
+            extend JSONAPI::Declarative
+            extend JSONAPI::ForCollection
+            include JSONAPI::Document
+            self.representation_wrap = :data
+
+            nested :relationships do
+            end
+
+            nested :included do
+              def to_hash(*)
+                super.flat_map { |_, resource| resource }
+              end
+            end
+          end
+        end
+      end
+
+      # @api private
+      module Renderer
+        class Links
+          def call(res, _options)
+            tuples = (res.delete('links') || []).collect { |link|
+              [JSONAPI::MemberName.(link['rel']), link['href']]
+            }
+
+            ::Hash[tuples] # NOTE: change to tuples.to_h when dropping < 2.1.
+          end
+        end
+      end
+
+      # @api private
+      module Fragment
+        Included = ->(included, options) do
+          return unless included && included.any?
+          return if options[:included] == false
+
+          type_and_id_seen = Set.new
+
+          included = included.select { |object|
+            type_and_id_seen.add? [object['type'], object['id']]
+          }
+
+          included
+        end
+      end
+    end
+
+    # @api private
+    module HashUtils
+      def store_if_any(hash, key, value)
+        hash[key] = value if value && value.any?
+      end
+      module_function :store_if_any
+    end
+  end
+end