lp-serializable 0.1.0 → 1.0.0

data/.ruby-version

@@ -0,0 +1 @@
+2.5.0

data/.travis.yml

@@ -2,4 +2,6 @@ sudo: false
 language: ruby
 rvm:
   - 2.5.0
-before_install: gem install bundler -v 1.16.1
+before_install: gem install bundler -v 1.16.3
+ignore:
+  - spec/lib/object_serializer_performance.rb

data/Gemfile.lock

@@ -1,12 +1,37 @@
 PATH
   remote: .
   specs:
-    lp-serializable (0.1.0)
-      fast_jsonapi
+    lp-serializable (1.0.0)
+      activesupport (>= 4.2)
+      fast_jsonapi (>= 1.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    actionpack (5.2.0)
+      actionview (= 5.2.0)
+      activesupport (= 5.2.0)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.2.0)
+      activesupport (= 5.2.0)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    active_model_serializers (0.10.7)
+      actionpack (>= 4.1, < 6)
+      activemodel (>= 4.1, < 6)
+      case_transform (>= 0.2)
+      jsonapi-renderer (>= 0.1.1.beta1, < 0.3)
+    activemodel (5.2.0)
+      activesupport (= 5.2.0)
+    activerecord (5.2.0)
+      activemodel (= 5.2.0)
+      activesupport (= 5.2.0)
+      arel (>= 9.0)
     activesupport (5.2.0)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
@@ -16,23 +41,58 @@ GEM
       bundler
       rake
       thor (>= 0.14.0)
+    arel (9.0.0)
+    benchmark-perf (0.2.1)
+    builder (3.2.3)
+    byebug (10.0.2)
+    case_transform (0.2)
+      activesupport
     coderay (1.1.2)
-    concurrent-ruby (1.0.5)
+    concurrent-ruby (1.1.5)
+    crass (1.0.4)
     diff-lcs (1.3)
-    fast_jsonapi (1.2)
+    erubi (1.8.0)
+    fast_jsonapi (1.5)
       activesupport (>= 4.2)
-    i18n (1.0.1)
+    i18n (1.6.0)
       concurrent-ruby (~> 1.0)
+    jsonapi-deserializable (0.2.0)
+    jsonapi-rb (0.5.0)
+      jsonapi-deserializable (~> 0.2.0)
+      jsonapi-serializable (~> 0.3.0)
+    jsonapi-renderer (0.2.0)
+    jsonapi-serializable (0.3.0)
+      jsonapi-renderer (~> 0.2.0)
+    jsonapi-serializers (1.0.1)
+      activesupport
+    loofah (2.2.3)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
     method_source (0.9.0)
+    mini_portile2 (2.4.0)
     minitest (5.11.3)
+    nokogiri (1.10.2)
+      mini_portile2 (~> 2.4.0)
+    oj (3.6.3)
     pry (0.11.3)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
+    rack (2.0.6)
+    rack-test (1.0.0)
+      rack (>= 1.0, < 3)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.0.4)
+      loofah (~> 2.2, >= 2.2.2)
     rake (10.5.0)
     rspec (3.7.0)
       rspec-core (~> 3.7.0)
       rspec-expectations (~> 3.7.0)
       rspec-mocks (~> 3.7.0)
+    rspec-benchmark (0.3.0)
+      benchmark-perf (~> 0.2.0)
+      rspec (>= 3.0.0, < 4.0.0)
     rspec-core (3.7.1)
       rspec-support (~> 3.7.0)
     rspec-expectations (3.7.0)
@@ -42,6 +102,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.7.0)
     rspec-support (3.7.1)
+    sqlite3 (1.3.13)
     thor (0.20.0)
     thread_safe (0.3.6)
     tzinfo (1.2.5)
@@ -51,12 +112,20 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  active_model_serializers (~> 0.10.7)
+  activerecord (>= 4.2)
   appraisal
   bundler (~> 1.16)
+  byebug
+  jsonapi-rb (~> 0.5.0)
+  jsonapi-serializers (~> 1.0.0)
   lp-serializable!
+  oj (~> 3.3)
   pry
   rake (~> 10.0)
   rspec (~> 3.0)
+  rspec-benchmark (~> 0.3.0)
+  sqlite3 (~> 1.3)
 
 BUNDLED WITH
-   1.16.1
+   1.16.3

data/README.md

@@ -1,8 +1,10 @@
 # Lp::Serializable
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/lp/serializable`. To experiment with that code, run `bin/console` for an interactive prompt.
+When serializing with [fast_jsonapi](https://github.com/Netflix/fast_jsonapi), data is structured per the json-api [specs](http://jsonapi.org/format/).
 
-TODO: Delete this and the text above, and describe your gem
+lp-serializable is a thin wrapper around fast_jsonapi serialization, producting AMS style output.
+
+lp-serializable is intended to be used in Rails controllers.
 
 ## Installation
 
@@ -22,7 +24,170 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+**Controller Definition**
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Lp::Serializable
+end
+
+class MoviesController < ApplicationController
+  def index
+    movies = Movie.all
+    movies_hash = serializable_collection(movies, 'Movie')
+    render json: movies_hash
+  end
+
+  def show
+    movie = Movie.find(params[:id])
+    movie_hash = serializable(movie)
+    render json: movie_hash
+  end
+end
+```
+
+**Serializer Definition**
+
+```ruby
+class MovieSerializer
+  include FastJsonapi::ObjectSerializer
+
+  attributes :name
+  
+  attribute :year, if: Proc.new { |object| object.year.present? }
+  
+  attribute :last_updated do |object|
+    object.updated_at
+  end
+
+  has_many :actors
+  belongs_to :owner
+end
+
+class ActorSerializer
+  include FastJsonapi::ObjectSerializer
+    
+  attributes :id
+end
+
+class OwnerSerializer
+  include FastJsonapi::ObjectSerializer
+
+  attributes :id
+end
+```
+
+## Object Serialization
+**Sample Object**
+
+```ruby
+movie = Movie.new
+movie.id = 232
+movie.name = 'test movie'
+movie.actor_ids = [1, 2, 3]
+movie.owner_id = 3
+movie.movie_type_id = 1
+movie
+```
+
+**Return a hash**
+```ruby
+hash = serializable(movie)
+```
+
+**Output**
+
+```json
+{
+  "data": {
+    "id": "3",
+    "type": "movie",
+    "name": "test movie",
+    "last_updated": "2019-04-26 18:55:46 UTC",
+    "actors": [
+        {
+            "id": "1",
+            "type": "actor"
+        },
+        {
+            "id": "2",
+            "type": "actor"
+        }
+    ],
+    "owner": {
+        "id": "3",
+        "type": "user"
+    }
+  }
+}
+
+```
+
+For more information on configuration, refer to [fast_jsonapi](https://github.com/Netflix/fast_jsonapi#customizable-options) documentation.
+
+## Deeply Nested Serialization Pattern
+
+Fastjson API does not support serialization of deeply nested resources.
+
+To get around this, extend `Lp::Serializable` in your serializers:
+
+```ruby
+class MovieSerializer
+  include FastJsonapi::ObjectSerializer
+  extend Lp::Serializable
+
+ ...
+end
+```
+
+Define custom attributes for relationships, instead of defining them via fastjson_api:
+
+```ruby
+class MovieSerializer
+  include FastJsonapi::ObjectSerializer
+  extend Lp::Serializable
+
+ attribute :actors do |object|
+  collection = object.actors
+  serializer = 'Actor'
+  serializable_collection(collection, serializer, nested: true)
+ end
+end
+```
+
+Attribute `:actors` will trigger `ActorSerializer` to serialize the actors collection. Consequently, any relationships defined in `ActorSerializer` via custom attributes and serialized with `serializable_` methods (using the `nested: true` option) will be appropriately nested.
+
+## Custom Serializer Class
+
+Use `#serializable_class` to serialize with a custom class:
+
+```ruby
+  def show
+    movie = Movie.find(params[:id])
+    # Will serialize with FilmSerializer instead of MovieSerializer
+    movie_hash = serializable_class(movie, 'Film')
+    render json: movie_hash
+  end
+```
+
+## Options Support
+
+Supported options include:
+
+- `:fields` ([Sparse Fieldsets](https://github.com/Netflix/fast_jsonapi#sparse-fieldsets))
+- `:params` ([Params](https://github.com/Netflix/fast_jsonapi#params))
+- [Conditional Attributes](https://github.com/Netflix/fast_jsonapi#conditional-attributes)
+
+Other options are "supported" but may yeild unexpected results, as Serializable's hash flattening prioritizes deeply nested data structures.
+
+`:is_collection` is baked into Seriazable methods for accurate detection of collections or singular resources.
+
+## Aliases
+
+- `serialize_and_flatten()` = `serializable()`
+- `serialize_and_flatten_with_class_name()` = `serializable_class()`
+- `serialize_and_flatten_collection()` = `serializable_collection()`
+
 
 ## Development
 
@@ -32,7 +197,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lp-serializable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/LaunchPadLab/lp-serializable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
@@ -40,4 +205,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Lp::Serializable project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/lp-serializable/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Lp::Serializable project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/LaunchPadLab/lp-serializable/blob/master/CODE_OF_CONDUCT.md).

data/lib/fast_jsonapi/multi_to_json.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+# Usage:
+#   class Movie
+#     def to_json(payload)
+#       FastJsonapi::MultiToJson.to_json(payload)
+#     end
+#   end
+module FastJsonapi
+  module MultiToJson
+    # Result object pattern is from https://johnnunemaker.com/resilience-in-ruby/
+    # e.g. https://github.com/github/github-ds/blob/fbda5389711edfb4c10b6c6bad19311dfcb1bac1/lib/github/result.rb
+    class Result
+      def initialize(*rescued_exceptions)
+        @rescued_exceptions = if rescued_exceptions.empty?
+          [StandardError]
+        else
+          rescued_exceptions
+        end
+
+        @value = yield
+        @error = nil
+      rescue *rescued_exceptions => e
+        @error = e
+      end
+
+      def ok?
+        @error.nil?
+      end
+
+      def value!
+        if ok?
+          @value
+        else
+          raise @error
+        end
+      end
+
+      def rescue
+        return self if ok?
+
+        Result.new(*@rescued_exceptions) { yield(@error) }
+      end
+    end
+
+    def self.logger(device=nil)
+      return @logger = Logger.new(device) if device
+      @logger ||= Logger.new(IO::NULL)
+    end
+
+    # Encoder-compatible with default MultiJSON adapters and defaults
+    def self.to_json_method
+      encode_method = String.new(%(def _fast_to_json(object)\n ))
+      encode_method << Result.new(LoadError) {
+        require 'oj'
+        %(::Oj.dump(object, mode: :compat, time_format: :ruby, use_to_json: true))
+      }.rescue {
+        require 'yajl'
+        %(::Yajl::Encoder.encode(object))
+      }.rescue {
+        require 'jrjackson' unless defined?(::JrJackson)
+        %(::JrJackson::Json.dump(object))
+      }.rescue {
+        require 'json'
+        %(JSON.fast_generate(object, create_additions: false, quirks_mode: true))
+      }.rescue {
+        require 'gson'
+        %(::Gson::Encoder.new({}).encode(object))
+      }.rescue {
+        require 'active_support/json/encoding'
+        %(::ActiveSupport::JSON.encode(object))
+      }.rescue {
+        warn "No JSON encoder found. Falling back to `object.to_json`"
+        %(object.to_json)
+      }.value!
+      encode_method << "\nend"
+    end
+
+    def self.to_json(object)
+      _fast_to_json(object)
+    rescue NameError
+      define_to_json(FastJsonapi::MultiToJson)
+      _fast_to_json(object)
+    end
+
+    def self.define_to_json(receiver)
+      cl = caller_locations[0]
+      method_body = to_json_method
+      logger.debug { "Defining #{receiver}._fast_to_json as #{method_body.inspect}" }
+      receiver.instance_eval method_body, cl.absolute_path, cl.lineno
+    end
+
+    def self.reset_to_json!
+      undef :_fast_to_json if method_defined?(:_fast_to_json)
+      logger.debug { "Undefining #{receiver}._fast_to_json" }
+    end
+  end
+end

data/lib/fast_jsonapi/object_serializer.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/object'
+require 'active_support/concern'
+require 'active_support/inflector'
+require 'fast_jsonapi/serialization_core'
+require 'fast_jsonapi/attribute'
+
+module FastJsonapi
+  module ObjectSerializer
+    extend ActiveSupport::Concern
+    include SerializationCore
+
+    SERIALIZABLE_HASH_NOTIFICATION = 'render.fast_jsonapi.serializable_hash'
+    SERIALIZED_JSON_NOTIFICATION = 'render.fast_jsonapi.serialized_json'
+
+    included do
+      # Set record_type based on the name of the serializer class
+      set_type(reflected_record_type) if reflected_record_type
+    end
+
+    def initialize(resource, options = {})
+      process_options(options)
+
+      @resource = resource
+    end
+
+    def serializable_hash
+      return hash_for_collection if is_collection?(@resource)
+
+      hash_for_one_record
+    end
+    alias_method :to_hash, :serializable_hash
+
+    def hash_for_one_record
+      serializable_hash = { data: nil }
+      serializable_hash[:meta] = @meta if @meta.present?
+      serializable_hash[:links] = @links if @links.present?
+
+      return serializable_hash unless @resource
+
+      serializable_hash[:data] = self.class.record_hash(@resource, @params)
+      serializable_hash[:included] = self.class.get_included_records(@resource, @includes, @known_included_objects, @params) if @includes.present?
+      serializable_hash
+    end
+
+    def hash_for_collection
+      serializable_hash = {}
+
+      data = []
+      included = []
+      @resource.each do |record|
+        data << self.class.record_hash(record, @params)
+        included.concat self.class.get_included_records(record, @includes, @known_included_objects, @params) if @includes.present?
+      end
+
+      serializable_hash[:data] = data
+      serializable_hash[:included] = included if @includes.present?
+      serializable_hash[:meta] = @meta if @meta.present?
+      serializable_hash[:links] = @links if @links.present?
+      serializable_hash
+    end
+
+    def serialized_json
+      self.class.to_json(serializable_hash)
+    end
+
+    private
+
+    def process_options(options)
+      return if options.blank?
+
+      @known_included_objects = {}
+      @meta = options[:meta]
+      @links = options[:links]
+      @params = options[:params] || {}
+      raise ArgumentError.new("`params` option passed to serializer must be a hash") unless @params.is_a?(Hash)
+
+      if options[:include].present?
+        @includes = options[:include].delete_if(&:blank?).map(&:to_sym)
+        self.class.validate_includes!(@includes)
+      end
+    end
+
+    def is_collection?(resource)
+      resource.respond_to?(:each) && !resource.respond_to?(:each_pair)
+    end
+
+    class_methods do
+
+      def inherited(subclass)
+        super(subclass)
+        subclass.attributes_to_serialize = attributes_to_serialize.dup if attributes_to_serialize.present?
+        subclass.relationships_to_serialize = relationships_to_serialize.dup if relationships_to_serialize.present?
+        subclass.cachable_relationships_to_serialize = cachable_relationships_to_serialize.dup if cachable_relationships_to_serialize.present?
+        subclass.uncachable_relationships_to_serialize = uncachable_relationships_to_serialize.dup if uncachable_relationships_to_serialize.present?
+        subclass.transform_method = transform_method
+        subclass.cache_length = cache_length
+        subclass.race_condition_ttl = race_condition_ttl
+        subclass.data_links = data_links
+        subclass.cached = cached
+      end
+
+      def reflected_record_type
+        return @reflected_record_type if defined?(@reflected_record_type)
+
+        @reflected_record_type ||= begin
+          if self.name.end_with?('Serializer')
+            self.name.split('::').last.chomp('Serializer').underscore.to_sym
+          end
+        end
+      end
+
+      def set_key_transform(transform_name)
+        mapping = {
+          camel: :camelize,
+          camel_lower: [:camelize, :lower],
+          dash: :dasherize,
+          underscore: :underscore
+        }
+        self.transform_method = mapping[transform_name.to_sym]
+      end
+
+      def run_key_transform(input)
+        if self.transform_method.present?
+          input.to_s.send(*@transform_method).to_sym
+        else
+          input.to_sym
+        end
+      end
+
+      def use_hyphen
+        warn('DEPRECATION WARNING: use_hyphen is deprecated and will be removed from fast_jsonapi 2.0 use (set_key_transform :dash) instead')
+        set_key_transform :dash
+      end
+
+      def set_type(type_name)
+        self.record_type = run_key_transform(type_name)
+      end
+
+      def set_id(id_name)
+        self.record_id = id_name
+      end
+
+      def cache_options(cache_options)
+        self.cached = cache_options[:enabled] || false
+        self.cache_length = cache_options[:cache_length] || 5.minutes
+        self.race_condition_ttl = cache_options[:race_condition_ttl] || 5.seconds
+      end
+
+      def attributes(*attributes_list, &block)
+        attributes_list = attributes_list.first if attributes_list.first.class.is_a?(Array)
+        options = attributes_list.last.is_a?(Hash) ? attributes_list.pop : {}
+        self.attributes_to_serialize = {} if self.attributes_to_serialize.nil?
+        
+        attributes_list.each do |attr_name|
+          method_name = attr_name
+          key = run_key_transform(method_name)
+          attributes_to_serialize[key] = Attribute.new(
+            key: key,
+            method: block || method_name,
+            options: options
+          )
+        end
+      end
+
+      alias_method :attribute, :attributes
+
+      def add_relationship(name, relationship)
+        self.relationships_to_serialize = {} if relationships_to_serialize.nil?
+        self.cachable_relationships_to_serialize = {} if cachable_relationships_to_serialize.nil?
+        self.uncachable_relationships_to_serialize = {} if uncachable_relationships_to_serialize.nil?
+
+        if !relationship[:cached]
+          self.uncachable_relationships_to_serialize[name] = relationship
+        else
+          self.cachable_relationships_to_serialize[name] = relationship
+        end
+        self.relationships_to_serialize[name] = relationship
+     end
+
+      def has_many(relationship_name, options = {}, &block)
+        name = relationship_name.to_sym
+        hash = create_relationship_hash(relationship_name, :has_many, options, block)
+        add_relationship(name, hash)
+      end
+
+      def has_one(relationship_name, options = {}, &block)
+        name = relationship_name.to_sym
+        hash = create_relationship_hash(relationship_name, :has_one, options, block)
+        add_relationship(name, hash)
+      end
+
+      def belongs_to(relationship_name, options = {}, &block)
+        name = relationship_name.to_sym
+        hash = create_relationship_hash(relationship_name, :belongs_to, options, block)
+        add_relationship(name, hash)
+      end
+
+      def create_relationship_hash(base_key, relationship_type, options, block)
+        name = base_key.to_sym
+        if relationship_type == :has_many
+          base_serialization_key = base_key.to_s.singularize
+          base_key_sym = base_serialization_key.to_sym
+          id_postfix = '_ids'
+        else
+          base_serialization_key = base_key
+          base_key_sym = name
+          id_postfix = '_id'
+        end
+        {
+          key: options[:key] || run_key_transform(base_key),
+          name: name,
+          id_method_name: options[:id_method_name] || "#{base_serialization_key}#{id_postfix}".to_sym,
+          record_type: options[:record_type] || run_key_transform(base_key_sym),
+          object_method_name: options[:object_method_name] || name,
+          object_block: block,
+          serializer: compute_serializer_name(options[:serializer] || base_key_sym),
+          relationship_type: relationship_type,
+          cached: options[:cached] || false,
+          polymorphic: fetch_polymorphic_option(options)
+        }
+      end
+
+      def compute_serializer_name(serializer_key)
+        return serializer_key unless serializer_key.is_a? Symbol
+        namespace = self.name.gsub(/()?\w+Serializer$/, '')
+        serializer_name = serializer_key.to_s.classify + 'Serializer'
+        (namespace + serializer_name).to_sym
+      end
+
+      def fetch_polymorphic_option(options)
+        option = options[:polymorphic]
+        return false unless option.present?
+        return option if option.respond_to? :keys
+        {}
+      end
+
+      def link(link_name, link_method_name = nil, &block)
+        self.data_links = {} if self.data_links.nil?
+        link_method_name = link_name if link_method_name.nil?
+        key = run_key_transform(link_name)
+        self.data_links[key] = block || link_method_name
+      end
+
+      def validate_includes!(includes)
+        return if includes.blank?
+
+        includes.detect do |include_item|
+          klass = self
+          parse_include_item(include_item).each do |parsed_include|
+            relationship_to_include = klass.relationships_to_serialize[parsed_include]
+            raise ArgumentError, "#{parsed_include} is not specified as a relationship on #{klass.name}" unless relationship_to_include
+            raise NotImplementedError if relationship_to_include[:polymorphic].is_a?(Hash)
+            klass = relationship_to_include[:serializer].to_s.constantize
+          end
+        end
+      end
+    end
+  end
+end