shreddies 0.1.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6770e333d8c5c90f6a7f1d56fd4d3e27fa32103c13473ed500d151ee20cd8826
-  data.tar.gz: 387cc3e15bbaa1eb8ca3c1775fbc80d22df8c7edf79547dd1518149f07d70e68
+  metadata.gz: d6daee669edb85f0a632236f2eacdec946b07d9419a25ae88f6beb6bd09c4a19
+  data.tar.gz: f673da386a57e68668a356c8687a88a5f0ae7ec934ebab439b48d5fd2d53ef64
 SHA512:
-  metadata.gz: 8a7ef85a2a7e0cf2bac9353ce5998f3b7b897c36da844e7169e13dfea62c377cf7a994b4e0bf27a763721a3853aa503303ff2248b65a6ade68b9db4748b027ec
-  data.tar.gz: c2b54d864565890b793b63bdbdf6160d85ff7dd3a8de974034499139aedb7c2fb0974cb34ae05acda31d7d444caa480522f4c9408c6284709a6a1168f552f221
+  metadata.gz: ec6d5dc108f25b5d4f820574ae8051e5cc594b24d101de65f8145f476bf6f782db0361c4ffdacf6505b7fbb96708e5b6cd4ed7ff704ad4e3bd2d5653a86e3e49
+  data.tar.gz: 4c330bf894abf811866bd21ad77460cd7073ad89d5e97719bc2e2af73bf2d1255808b3487e6880d22c52f5e8a130a19d3b52b09c4ecd711abb4dcc71f52a46ca

data/.gitignore

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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shreddies (0.1.0)
+    shreddies (0.5.0)
       activerecord (>= 5)
       railties (>= 5)
 

data/README.md

@@ -2,6 +2,8 @@
 
 Shreddies is a JSON serialization library for Rails that focuses on simplicity and speed. No more "magic" DSL's - just plain old Ruby objects! It's primarily intended to serialize Rails models as JSON, but will also work with pretty much anything at all.
 
+Shreddies primary principle is to be explicit. So a serializer will return nothing until you define some methods. This gives you complete control and everything is a known quantity - no surprises.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -20,7 +22,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 +67,122 @@ Model collections and array's are also supported:
 User.all.as_json
 ```
 
+### Collection and Single Modules
+
+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
+```
+
+### ActiveRecord Associations
+
+ActiveRecord associations are supported with no additional work on your part. Shreddies will simply call `#as_json` on any method that returns an ActiveRecord model or relation.
+
+```ruby
+# app/serializers/user_serializer.rb
+class UserSerializer < Shreddies::Json
+  delegate :articles
+
+  def latest_article
+    articles.latest
+  end
+end
+```
+
+And if you need to be specific about what you render, just call the serializer or `#as_json` directly:
+
+```ruby
+# app/serializers/user_serializer.rb
+class UserSerializer < Shreddies::Json
+  def articles
+    subject.articles.as_json index_by: :slug
+  end
+
+  def latest_article
+    LatestArticleSerializer.render articles.latest
+  end
+end
+```
+
+### `before_render` callback
+
+You can define a `#before_render` private method in your serializers, which will act as a callback. It receives the object to be output, and expects you to return the object, which allows you to modify it before rendering.
+
 ### 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.
+
+#### `transform_keys` (default: true)
+
+If false, the returned keys will not be transformed. The default is to deeply transform all keys to camelCase.
+
+#### `except`
+
+Pass one or more attribute names as a Symbol or Array of Symbols, and these will be excluded from the results:
+
+```ruby
+User.all.as_json(except: [:first_name, :age])
+```
+
+#### `only`
+
+Pass one or more attribute names as a Symbol or Array of Symbols, and _ONLY_ these will be included in the results:
+
+```ruby
+User.all.as_json(only: :first_name)
+```
+
+> Attributes must still be defined within the Serializer.
+
 #### `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 +211,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,81 @@ 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
 
-    def initialize(subject, options)
-      @subject = subject
-      @options = options
+    def initialize(subject, opts = {})
+      @subject = subject.is_a?(Hash) ? OpenStruct.new(subject) : subject
+      @options = { transform_keys: true }.merge(opts)
+
+      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 = {}
+      output = {}.with_indifferent_access
+      methods = Set.new(public_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 = public_methods(false)
-      if self.class.superclass.to_s.end_with?('Serializer')
-        methods.concat self.class.superclass.public_instance_methods(false)
+      # Filter out methods using the `only` or `except` options.
+      if @options[:only]
+        @options[:only] = Array(@options[:only])
+        methods = methods.select { |x| @options[:only].include? x }
+      elsif @options[:except]
+        methods = methods.excluding(@options[:except])
       end
 
-      methods.uniq.excluding(:subject, :options, :as_json).map do |attr|
-        json[attr] = public_send(attr)
+      methods.map do |attr|
+        res = public_send(attr)
+        if res.is_a?(ActiveRecord::Relation) || res.is_a?(ActiveRecord::Base)
+          res = res.as_json(transform_keys: @options[:transform_keys])
+        end
+
+        output[attr] = res
+      end
+
+      output = before_render(output)
+
+      return output unless @options[:transform_keys]
+
+      output.deep_transform_keys { |key| key.to_s.camelize :lower }
+    end
+
+    private
+
+    def before_render(output)
+      output
+    end
+
+    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
 
-      json.deep_transform_keys { |key| key.to_s.camelize :lower }
+      # Extend with the :module option if given.
+      if @options[:module]
+        Array(@options[:module]).each do |m|
+          extend m.is_a?(Module) ? m : "#{self.class}::#{m}".constantize
+        end
+      end
     end
   end
 end

data/lib/shreddies/version.rb

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

metadata

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