jat 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c17f2cb00d5dc319df32abc1b0fd41d00adb30f0f8357faf6d74b7d440ef1d9
-  data.tar.gz: 0d638bef47aa94698fa25a5c2dc0f6559e528ef8b5bf525bec07310307dbcda3
+  metadata.gz: 3fdf9f1733a9d7ddcdeced1bcf6b6cbb1f53b9ffa11b8cb1592874dcc55c3bf2
+  data.tar.gz: d8982abf27a244a845ec0147a51e23946a8f6cac66c36d350aef6567253326f8
 SHA512:
-  metadata.gz: 369741fcd71f789f49fe0e555db75982fd7758959c59833b1b3d4dd8c55d424cd159f825a9ee6a7d17d5da3c821d44c7052b3ec49910bcf5ab569114916ed6b4
-  data.tar.gz: 25a6235d5ec37e44917f64e0d40a98032bb391120832c0357741b56f98571d5941323b548c501bb4a1c761caf62f6cc0a65a09cb8b05f1376d20ba093799688c
+  metadata.gz: f8a9be4d5e0d59922b37763de59a8833b5d3c71ac634f2c3555b6b9ab36e8a4149be04f8b33a68406616cfaeda85f49ed349fe8cc4d47bc44e0a873f0128829a
+  data.tar.gz: 9dcf9433b3d5f40e538db79e082095b54977f8ba8fd885ada3442441c98f374635956d0cd5201c654282954dd24d59e589a181338d2774855b97bd9677fa40d4

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+### Development
+
+* Replace `.id` DSL method with `.attribute(:id)`
+* Allow to add attributes with name `:type`
+* Remove possibility to add presenters methods in serializer
+* Remove `delegate` option
+

data/README.md

@@ -0,0 +1,21 @@
+# JAT (JSON API TOOLKIT)
+
+JAT helps to serialize complex nested objects to JSON format.
+
+Key features:
+
+* **Auto preload** – No need to preload data manually to omit N+1 (Active Record only)
+* **Configurable exposed attributes** – No more tons of serializers with different attributes sets
+* **Modular design** – plugin system (aka [shrine]) allows you to load only the functionality you need
+
+## Output Format
+
+Supported two serialization formats:
+  - [JSON:API]
+  - Simple nested JSON objects (same as good old [AMS] or [Jbuilder])
+
+
+[shrine]: https://shrinerb.com/docs/getting-started#plugin-system
+[JSON:API]: https://jsonapi.org/format/
+[AMS]: https://github.com/rails-api/active_model_serializers/tree/0-9-stable
+[Jbuilder]: https://github.com/rails/jbuilder

data/jat.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |gem|
+  gem.name = "jat"
+  gem.version = "0.0.3"
+  gem.summary = "JSON API TOOLKIT"
+  gem.description = <<~DESC
+    The JAT serializer allows you to generate a JSON response based on the fields requested by the client.
+    Besides, it avoids manually adding includes and solves N+1 problems on its own.
+  DESC
+
+  gem.authors = ["Andrey Glushkov"]
+  gem.email = "aglushkov@shakuro.com"
+  gem.files = Dir["README.md", "LICENSE.txt", "CHANGELOG.md", "lib/**/*.rb", "jat.gemspec", "doc/**/*.md"]
+  gem.test_files = `git ls-files -- test/*`.split("\n")
+  gem.homepage = "https://github.com/aglushkov/jat"
+  gem.license = "MIT"
+  gem.required_ruby_version = 2.5
+  gem.metadata = {
+    "bug_tracker_uri" => "https://github.com/aglushkov/jat/issues",
+    "changelog_uri" => "https://github.com/aglushkov/jat/blob/master/CHANGELOG.md",
+    "source_code_uri" => "https://github.com/aglushkov/jat"
+  }
+
+  # General testing helpers
+  gem.add_development_dependency "minitest", "~> 5.14"
+  gem.add_development_dependency "mocha", "~> 1.12"
+  gem.add_development_dependency "rake", "~> 13.0"
+
+  # Code standard
+  gem.add_development_dependency "standard", "~> 1.0"
+  gem.add_development_dependency "simplecov", "~> 0.21"
+
+  # ORM plugins
+  gem.add_development_dependency "activerecord", RUBY_VERSION >= "2.5" ? "~> 6.0" : "~> 5.2"
+  gem.add_development_dependency "sqlite3", "~> 1.4" unless RUBY_ENGINE == "jruby"
+end

data/lib/jat/attribute.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "utils/enum_deep_dup"
+require_relative "utils/enum_deep_freeze"
+
+class Jat
+  class Attribute
+    module InstanceMethods
+      attr_reader :params, :opts
+
+      def initialize(name:, opts: {}, block: nil)
+        @opts = EnumDeepDup.call(opts)
+        @params = EnumDeepFreeze.call(name: name, opts: @opts, block: block)
+      end
+
+      # Attribute name that was provided when initializing attribute
+      def original_name
+        @original_name ||= params.fetch(:name).to_sym
+      end
+
+      # Object method name to get attribute value
+      def key
+        @key ||= opts.key?(:key) ? opts[:key].to_sym : original_name
+      end
+
+      # Attribute name that will be used in serialized response
+      def name
+        @name ||= original_name
+      end
+
+      # Checks if attribute is exposed
+      def exposed?
+        return @exposed if instance_variable_defined?(:@exposed)
+
+        @exposed =
+          case self.class.jat_class.config[:exposed]
+          when :all then opts.fetch(:exposed, true)
+          when :none then opts.fetch(:exposed, false)
+          else opts.fetch(:exposed, !relation?)
+          end
+      end
+
+      def many?
+        return @many if instance_variable_defined?(:@many)
+
+        @many = opts[:many]
+      end
+
+      def relation?
+        return @relation if instance_variable_defined?(:@relation)
+
+        @relation = opts.key?(:serializer)
+      end
+
+      def serializer
+        return @serializer if instance_variable_defined?(:@serializer)
+
+        @serializer = opts[:serializer]
+      end
+
+      def block
+        @block ||=
+          params.fetch(:block) || begin
+            key_method_name = key
+            -> { object.public_send(key_method_name) }
+          end
+      end
+    end
+
+    module ClassMethods
+      # Returns the Jat class that this Attribute class is namespaced under.
+      attr_accessor :jat_class
+
+      # Since Attribute is anonymously subclassed when Jat is subclassed,
+      # and then assigned to a constant of the Jat subclass, make inspect
+      # reflect the likely name for the class.
+      def inspect
+        "#{jat_class.inspect}::Attribute"
+      end
+    end
+
+    extend ClassMethods
+    include InstanceMethods
+  end
+end

data/lib/jat/config.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "utils/enum_deep_dup"
+
+class Jat
+  class Config
+    module InstanceMethods
+      attr_reader :opts
+
+      def initialize(opts = {})
+        @opts = EnumDeepDup.call(opts)
+      end
+
+      def []=(key, value)
+        opts[key] = value
+      end
+
+      def [](key)
+        opts[key]
+      end
+    end
+
+    module ClassMethods
+      # Returns the Jat class that this config class is namespaced under.
+      attr_accessor :jat_class
+
+      # Since Config is anonymously subclassed when Jat is subclassed,
+      # and then assigned to a constant of the Jat subclass, make inspect
+      # reflect the likely name for the class.
+      def inspect
+        "#{jat_class.inspect}::Config"
+      end
+    end
+
+    include InstanceMethods
+    extend ClassMethods
+  end
+end

data/lib/jat/plugins/_activerecord_preloads/_activerecord_preloads.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "./lib/preloader"
+
+class Jat
+  module Plugins
+    module ActiverecordPreloads
+      module InstanceMethods
+        def initialize(*)
+          super
+          @object = add_preloads(@object)
+        end
+
+        private
+
+        def add_preloads(obj)
+          return obj if obj.nil? || (obj.is_a?(Array) && obj.empty?)
+
+          preloads = self.class.jat_preloads(self)
+          return obj if preloads.empty?
+
+          Preloader.preload(obj, preloads)
+        end
+      end
+    end
+
+    register_plugin(:_activerecord_preloads, ActiverecordPreloads)
+  end
+end

data/lib/jat/plugins/_activerecord_preloads/lib/preloader.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+class Jat
+  module Plugins
+    module ActiverecordPreloads
+      class Preloader
+        module ClassMethods
+          def preload(object, preloads)
+            preload_handler = handlers.find { |handler| handler.fit?(object) }
+            raise Error, "Can't preload #{preloads.inspect} to #{object.inspect}" unless preload_handler
+
+            preload_handler.preload(object, preloads)
+          end
+
+          def handlers
+            @handlers ||= [ActiverecordRelation, ActiverecordObject, ActiverecordArray].freeze
+          end
+        end
+
+        extend ClassMethods
+      end
+
+      class ActiverecordObject
+        module ClassMethods
+          def fit?(object)
+            object.is_a?(ActiveRecord::Base)
+          end
+
+          def preload(object, preloads)
+            # Reset associations that will be preloaded to fix possible bugs with
+            # ActiveRecord::Associations::Preloader
+            preloads.each_key { |key| object.association(key).reset }
+            ActiveRecord::Associations::Preloader.new.preload(object, preloads)
+
+            object
+          end
+        end
+
+        extend ClassMethods
+      end
+
+      class ActiverecordRelation
+        module ClassMethods
+          def fit?(objects)
+            objects.is_a?(ActiveRecord::Relation)
+          end
+
+          def preload(objects, preloads)
+            objects.preload(preloads)
+          end
+        end
+
+        extend ClassMethods
+      end
+
+      class ActiverecordArray
+        module ClassMethods
+          def fit?(objects)
+            objects.is_a?(Array) &&
+              ActiverecordObject.fit?(objects.first) &&
+              same_kind?(objects)
+          end
+
+          def preload(objects, preloads)
+            # Reset associations that will be preloaded to fix possible bugs with
+            # ActiveRecord::Associations::Preloader
+            preloads.each_key { |key| reset_association(objects, key) }
+            ActiveRecord::Associations::Preloader.new.preload(objects, preloads)
+
+            objects
+          end
+
+          private
+
+          def reset_association(objects, key)
+            objects.each { |object| object.association(key).reset }
+          end
+
+          def same_kind?(objects)
+            first_object_class = objects.first.class
+            objects.all? { |object| object.instance_of?(first_object_class) }
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end

data/lib/jat/plugins/_json_api_activerecord/_json_api_activerecord.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "./lib/preloads"
+
+class Jat
+  module Plugins
+    module JsonApiActiverecord
+      def self.after_load(jat_class, **opts)
+        jat_class.plugin :_preloads, **opts
+        jat_class.plugin :_activerecord_preloads, **opts
+      end
+
+      module ClassMethods
+        def jat_preloads(jat)
+          Preloads.call(jat)
+        end
+      end
+    end
+
+    register_plugin(:_json_api_activerecord, JsonApiActiverecord)
+  end
+end

data/lib/jat/plugins/_json_api_activerecord/lib/preloads.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+class Jat
+  module Plugins
+    module JsonApiActiverecord
+      class Preloads
+        class << self
+          def call(jat)
+            new(jat.traversal_map.current).for(jat.class)
+          end
+        end
+
+        attr_reader :initial_result
+
+        def initialize(current_map)
+          @current_map = current_map
+          @initial_result = {}
+        end
+
+        def for(jat_class)
+          @initial_result = {}
+          append(initial_result, jat_class)
+          initial_result
+        rescue SystemStackError
+          raise Error, "Stack level too deep, recursive preloads detected: #{initial_result}"
+        end
+
+        private
+
+        attr_reader :current_map
+
+        def append(result, jat_class)
+          attrs = current_map[jat_class.type]
+          attributes_names = attrs[:attributes] + attrs[:relationships]
+
+          add_attributes(result, jat_class, attributes_names)
+        end
+
+        def add_attributes(result, jat_class, attributes_names)
+          attributes_names.each do |name|
+            attribute = jat_class.attributes[name]
+            preloads = attribute.preloads
+            next unless preloads # we should not addd preloads and nested preloads when nil provided
+
+            add_preloads(result, preloads, attribute)
+          end
+        end
+
+        def add_preloads(result, preloads, attribute)
+          unless preloads.empty?
+            preloads = deep_dup(preloads)
+            merge(result, preloads)
+          end
+
+          add_nested_preloads(result, attribute) if attribute.relation?
+        end
+
+        def add_nested_preloads(result, attribute)
+          path = attribute.preloads_path
+          nested_result = nested(result, path)
+          nested_serializer = attribute.serializer.call
+
+          append(nested_result, nested_serializer)
+        end
+
+        def merge(result, preloads)
+          result.merge!(preloads) do |_key, value_one, value_two|
+            merge(value_one, value_two)
+          end
+        end
+
+        def deep_dup(preloads)
+          preloads.dup.transform_values! do |nested_preloads|
+            deep_dup(nested_preloads)
+          end
+        end
+
+        def nested(result, path)
+          !path || path.empty? ? result : result.dig(*path)
+        end
+      end
+    end
+  end
+end

data/lib/jat/plugins/_preloads/_preloads.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "./lib/format_user_preloads"
+require_relative "./lib/preloads_with_path"
+
+# This plugin adds attribute methods #preloads, #preloads_path
+class Jat
+  module Plugins
+    module Preloads
+      module AttributeMethods
+        NULL_PRELOADS = [nil, [].freeze].freeze
+
+        def preloads
+          return @preloads if defined?(@preloads)
+
+          @preloads, @preloads_path = get_preloads_with_path
+          @preloads
+        end
+
+        def preloads_path
+          return @preloads_path if defined?(@preloads_path)
+
+          @preloads, @preloads_path = get_preloads_with_path
+          @preloads_path
+        end
+
+        # When provided multiple values in preloads, such as { user: [:profile] },
+        # we don't know which entity is main (:user or :profile in this example) but
+        # we need to know main value to add nested preloads to it.
+        # User can specify main preloaded entity by adding "!" suffix
+        # ({ user!: [:profile] } for example), othervice the latest key will be considered main.
+        def get_preloads_with_path
+          preloads_provided = opts.key?(:preload)
+          preloads =
+            if preloads_provided
+              opts[:preload]
+            elsif relation?
+              key
+            end
+
+          # Nulls and empty hash differs as we can preload nested results to
+          # empty hash, but we will skip nested preloading if null or false provided
+          return NULL_PRELOADS if preloads_provided && !preloads
+
+          preloads = FormatUserPreloads.to_hash(preloads)
+          PreloadsWithPath.call(preloads)
+        end
+      end
+    end
+
+    register_plugin(:_preloads, Preloads)
+  end
+end

data/lib/jat/plugins/_preloads/lib/format_user_preloads.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+class Jat
+  module Plugins
+    module Preloads
+      class FormatUserPreloads
+        METHODS = {
+          Array => :array_to_hash,
+          FalseClass => :nil_to_hash,
+          Hash => :hash_to_hash,
+          NilClass => :nil_to_hash,
+          String => :string_to_hash,
+          Symbol => :symbol_to_hash
+        }.freeze
+
+        module ClassMethods
+          def to_hash(value)
+            send(METHODS.fetch(value.class), value)
+          end
+
+          private
+
+          def array_to_hash(values)
+            values.each_with_object({}) do |value, obj|
+              obj.merge!(to_hash(value))
+            end
+          end
+
+          def hash_to_hash(values)
+            values.each_with_object({}) do |(key, value), obj|
+              obj[key.to_sym] = to_hash(value)
+            end
+          end
+
+          def nil_to_hash(_value)
+            {}
+          end
+
+          def string_to_hash(value)
+            symbol_to_hash(value.to_sym)
+          end
+
+          def symbol_to_hash(value)
+            {value => {}}
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end

data/lib/jat/plugins/_preloads/lib/preloads_with_path.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class Jat
+  module Plugins
+    module Preloads
+      class PreloadsWithPath
+        module ClassMethods
+          BANG = "!"
+          NO_PRELOADS = [{}.freeze, [].freeze].freeze
+
+          # @param preload<Hash> Formatted user provided preloads hash
+          def call(preloads)
+            return NO_PRELOADS if preloads.empty?
+
+            path = main_path(preloads)
+            return [preloads, path] unless has_bang?(path)
+
+            # We should remove bangs from last key in path and from associated preloads key.
+            # We use mutable methods here.
+            remove_bangs(preloads, path)
+            [preloads, path]
+          end
+
+          private
+
+          # Generates path (Array) to main included resource.
+          # We need to know main included resource to include nested associations.
+          #
+          # User should mark main included resource with "!"
+          # When nothing marked, last included resource is considered main.
+          #
+          #  main_path(a: { b!: { c: {} }, d: {} }) # => [:a, :b]
+          #  main_path(a: { b: { c: {} }, d: {} }) # => [:a, :d]
+          #
+          def main_path(hash, path = [])
+            current_level = path.size
+
+            hash.each do |key, data|
+              path.pop(path.size - current_level)
+              path << key
+              return path if key[-1] == BANG
+
+              main_path(data, path)
+              return path if path.last[-1] == BANG
+            end
+
+            path
+          end
+
+          def remove_bangs(preloads, path)
+            # Remove last path with bang
+            bang_key = path.pop
+
+            # Delete bang from key
+            key = bang_key.to_s.delete_suffix!(BANG).to_sym
+
+            # Navigate to main resource and replace key with BANG
+            nested_preloads = empty_dig(preloads, path)
+            nested_preloads[key] = nested_preloads.delete(bang_key)
+
+            # Add cleared key to path
+            path << key
+          end
+
+          def empty_dig(hash, path)
+            path.empty? ? hash : hash.dig(*path)
+          end
+
+          def has_bang?(path)
+            path.last[-1] == BANG
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end

data/lib/jat/plugins/cache/cache.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+class Jat
+  module Plugins
+    module Cache
+      def self.before_load(jat_class, **opts)
+        jat_class.plugin :to_str, **opts
+      end
+
+      module InstanceMethods
+        FORMAT_TO_STR = :to_str
+        FORMAT_TO_H = :to_h
+
+        def to_h
+          return super if context[:_format] == FORMAT_TO_STR
+
+          context[:_format] = FORMAT_TO_H
+          cached { super }
+        end
+
+        def to_str
+          context[:_format] = FORMAT_TO_STR
+          cached { super }
+        end
+
+        private
+
+        def cached(&block)
+          cache = context[:cache]
+          return yield unless cache
+
+          cache.call(object, context, &block)
+        end
+      end
+    end
+
+    register_plugin(:cache, Cache)
+  end
+end

data/lib/jat/plugins/camel_lower/camel_lower.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class Jat
+  module Plugins
+    module CamelLower
+      module AttributeMethods
+        def name
+          first_word, *other = original_name.to_s.split("_")
+          last_words = other.map!(&:capitalize).join
+
+          :"#{first_word}#{last_words}"
+        end
+      end
+    end
+
+    register_plugin(:camel_lower, CamelLower)
+  end
+end