shreddies 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6770e333d8c5c90f6a7f1d56fd4d3e27fa32103c13473ed500d151ee20cd8826
-  data.tar.gz: 387cc3e15bbaa1eb8ca3c1775fbc80d22df8c7edf79547dd1518149f07d70e68
+  metadata.gz: 1f3a9878d5d25ca7eb02bc3d9f3e4e4dc6f71ab6f970312331ed01fe864923b4
+  data.tar.gz: bfba9356df3012c94527f1214d1862c5a507f91aab243f43fc85c8a30b0d50e3
 SHA512:
-  metadata.gz: 8a7ef85a2a7e0cf2bac9353ce5998f3b7b897c36da844e7169e13dfea62c377cf7a994b4e0bf27a763721a3853aa503303ff2248b65a6ade68b9db4748b027ec
-  data.tar.gz: c2b54d864565890b793b63bdbdf6160d85ff7dd3a8de974034499139aedb7c2fb0974cb34ae05acda31d7d444caa480522f4c9408c6284709a6a1168f552f221
+  metadata.gz: '069be646751138acce14f15960e417c18dcb2f57981a49b77d7d1a3a71ef4c2c079c49be4535c8ae193e752cb90298ddca0a72d5f51d12a9f2f2860c940a1e84'
+  data.tar.gz: 8cf4dd148fe6ab7a6989e52462bc3fd3b14cddf592d17b45bd6470ec60f7482fe21e64a12af1909181bf789981b64a964b30f241e746ff3150de7bb4edfa3245

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/test/internal/db/*.sqlite

data/README.md

@@ -20,7 +20,7 @@ Or install it yourself as:
 
 ## Usage
 
-Serializers should be named after your models and located in "`app/serializers`". Any public methods you define will be serialized, and you can quickly expose methods from the serialized subject using the `delegate` class method.
+Serializers should be named after your models and located in "`app/serializers`". Any public methods you define will be serialized, and you can quickly expose methods from the serialized subject using the `delegate` class method, which simply delegates to the subject.
 
 ```ruby
 # app/serializers/user_serializer.rb
@@ -65,12 +65,64 @@ Model collections and array's are also supported:
 User.all.as_json
 ```
 
+You may find that you don't want or need to return as much data in collections of objects, or may want to include differtent data. So if a serializer defines a `Collection` module, and a collection or array is being rendered, then that Collection module will automatically be included:
+
+```ruby
+ArticleSerializer < Shreddies::Json
+  module Collection
+    def url
+      "https://blah.com/#{subject.slug}"
+    end
+  end
+end
+```
+
+Conversely, you can define a `Single` module, and that will be included when rendering a single object.
+
+```ruby
+ArticleSerializer < Shreddies::Json
+  module Single
+    def body
+      'this body is really, really long, and I do not want it returned in lists.'
+    end
+  end
+end
+```
+
 ### Options
 
 Both `#as_json` and `.render` accepts an `options` hash, which will be forwarded to the serializer class, and available as `options`. This allows you to pass arbitrary options and use them in your serializer.
 
 The following standard options are supported, and provide additional built-in functionality:
 
+#### `serializer`
+
+By default `#as_json` will look for a serializer named after your model. So a `User` model will automatically use the `UserSerializer`. Sometimes you want to use a different serializer class, in which case you can use the `serializer` option:
+
+```ruby
+User.all.as_json serializer: User::AdminSerializer
+```
+
+#### `module`
+
+You can pass one or module names in the `module` option, and these modules will be included into the serializer. This is great for selectively including attributes and methods.
+
+```ruby
+Article.all.as_json module: :WithBody
+```
+
+```ruby
+ArticleSerializer < Shreddies::Json
+  module WithBody
+    def body
+      'This article body is really, really long'
+    end
+  end
+end
+```
+
+The `Collection` and `Single` modules can be defined and they will be automatically included. The Collection module will be included when rendering an array or ActiveRecord collection (`ActiveRecord::Relation`), and the Single module will be included when rendering a single obejct.
+
 #### `index_by`
 
 Give this option a property of your serialized subject as a Symbol, and the returned collection will be a Hash keyed by that property.
@@ -99,6 +151,33 @@ User.all.as_json index_by: :id
 }
 ```
 
+### Serializer Inheritance
+
+A serializer can inherit from any other serializer, which is a great way to create custom views:
+
+```ruby
+# app/serializers/user_serializer.rb
+class UserSerializer < Shreddies::Json
+  delegate :id, :first_name, :last_name, :email
+
+  def name
+    "#{first_name} #{last_name}"
+  end
+end
+
+class User::AdministratorSerializer < UserSerializer
+  def type
+    'administrator'
+  end
+end
+```
+
+Then call it like any other serializer:
+
+```ruby
+User::AdministratorSerializer.render(user)
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/shreddies/as_json.rb

@@ -7,12 +7,10 @@ module Shreddies
         serializer = options.delete(:serializer) || "#{model_name}Serializer"
 
         if serializer.is_a?(String) || serializer.is_a?(Symbol)
-          serializer.to_s.constantize.render_as_json self, options
-        else
-          serializer.render self, options
+          serializer = serializer.to_s.safe_constantize
         end
-      rescue NameError
-        super
+
+        serializer ? serializer.render_as_json(self, options) : super
       end
     end
 
@@ -21,12 +19,10 @@ module Shreddies
         serializer = options.delete(:serializer) || "#{model_name}Serializer"
 
         if serializer.is_a?(String) || serializer.is_a?(Symbol)
-          serializer.to_s.constantize.render_as_json self, options
-        else
-          serializer.render self, options
+          serializer = serializer.to_s.safe_constantize
         end
-      rescue NameError
-        super
+
+        serializer ? serializer.render_as_json(self, options) : super
       end
     end
   end

data/lib/shreddies/json.rb

@@ -6,20 +6,28 @@ module Shreddies
       # Render a subject as json, where `subject` is a single object (usually a Rails model), or an
       # array/collection of objects.
       #
+      # If subject is an array/collection then it will look for a `Collection` module prepend it to
+      # the `module` option.
+      #
       # A Hash of options can be given as the second argument:
       #   - index_by - Key the returned array by the value, transforming it from an array to a hash.
+      #   - module   - A Symbol or String of a local module to include. Or an array of several
+      #                modules, where each will be mixed in in order. Use this to mix in groups of
+      #                attributes. Eg. `ArticleSerializer.render(data, module: :WithBody)`.
       #
       def render(subject, options = {})
         index_by = options.delete(:index_by)
 
         if subject.is_a?(Array) || subject.is_a?(ActiveRecord::Relation)
+          collection_options = options.merge(from_collection: true)
+
           if index_by
             mapped = {}
             subject.each do |x|
-              mapped[x[index_by]] = new(x, options)
+              mapped[x[index_by]] = new(x, collection_options)
             end
           else
-            mapped = subject.map { |x| new(x, options) }
+            mapped = subject.map { |x| new(x, collection_options) }
           end
 
           mapped.as_json
@@ -31,31 +39,62 @@ module Shreddies
       alias render_as_json render
     end
 
-    # Monkey patches Rails Module#delegate so that the `:to` argument defaults tio `:subject`.
+    # Monkey patches Rails Module#delegate so that the `:to` argument defaults to `:subject`.
     def self.delegate(*methods, to: :subject, prefix: nil, allow_nil: nil, private: nil)
       super(*methods, to: to, prefix: prefix, allow_nil: allow_nil, private: private)
     end
 
-    attr_reader :subject, :options
+    attr_reader :subject, :options, :from_collection
 
     def initialize(subject, options)
       @subject = subject
       @options = options
+
+      extend_with_modules
     end
 
+    # Travel through the ancestors that are serializers (class name ends with "Serializer"), and
+    # call all public instance methods, returning a hash.
     def as_json
       json = {}
+      methods = Set.new(public_methods(false))
 
-      methods = public_methods(false)
-      if self.class.superclass.to_s.end_with?('Serializer')
-        methods.concat self.class.superclass.public_instance_methods(false)
+      self.class.ancestors.each do |ancestor|
+        if ancestor.to_s.end_with?('Serializer')
+          methods.merge ancestor.public_instance_methods(false)
+        end
       end
 
-      methods.uniq.excluding(:subject, :options, :as_json).map do |attr|
-        json[attr] = public_send(attr)
+      methods.map do |attr|
+        json[attr.to_s.camelize :lower] = public_send(attr)
       end
 
       json.deep_transform_keys { |key| key.to_s.camelize :lower }
     end
+
+    private
+
+    def extend_with_modules
+      self.class.ancestors.reverse.each do |ancestor|
+        next unless ancestor.to_s.end_with?('Serializer')
+
+        # Extend with Collection module if it exists, and a collection is being rendered. Otherwise,
+        # extend with the Single module if that exists.
+        if options[:from_collection]
+          (collection_mod = "#{ancestor}::Collection".safe_constantize) && extend(collection_mod)
+        else
+          (single_mod = "#{ancestor}::Single".safe_constantize) && extend(single_mod)
+        end
+      end
+
+      # Extend with the :module option if given.
+      if options[:module]
+        Array(options[:module]).each do |m|
+          mod = m.is_a?(Module) ? m : "#{self.class}::#{m}".constantize
+
+          extend mod
+        end
+      end
+    end
   end
 end

data/lib/shreddies/version.rb

@@ -1,3 +1,3 @@
 module Shreddies
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shreddies
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Joel Moss
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-30 00:00:00.000000000 Z
+date: 2020-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord