sequel-packer 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00bbe557f19cf23a18afe4e5d23173a3fb699977680fae2efa99670240f81847
-  data.tar.gz: 324688d708be91fa8e89eb99a65701f35dc8f3f5a799719588fa84adff877c95
+  metadata.gz: 7f7666c0db1cac9f34075e40a398a5963b33e6756d38507953dc14c59d5712d2
+  data.tar.gz: 10bf3ff431ba9fab4ff6bdfec84e51f1243cf3da1b5eff3ea66d6b7b45f94fbc
 SHA512:
-  metadata.gz: a626e68bd1053d818bd830a198bfe92b13bcbc0286a2ce985a996049ba7858a229aeabb00181e144fadfa8dbcc63ca90adef89619ddc32d86076ee53b718b424
-  data.tar.gz: 0344f7b561e830c58dd01c68da86728f57594a8073b920e4de70401e038e7a0cf92907f37726d84d9243268c12d3b256195df523d224224b69f53ee16f26136a
+  metadata.gz: 67d08fbd8aef15f7005ae59b411f87a237d83b53aeb26e7e92efff2a628e6ae29bf14724cfedea03f34b5f7cf61e4c8d28be6cc4e01027535d04519fa681f7e1
+  data.tar.gz: c96e1f683319af1a20d6cb775f6b0ac8a479297947b6a26008082e4a8aa8e35a677de7d3a8f66a7a74fc57079fb8ecab1b678201a214f5768fc57eef61b4b150

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+### 0.3.0 (2020-05-14)
+
+* Add `self.set_association_packer(association, packer_class, *traits)` and
+  `self.pack_association(association, models)` for more flexible packing of
+  associations.
+* Improve internal code quality.
+
 ### 0.2.0 (2020-05-13)
 
 * Add support for `Sequel::Packer.eager(*associations)`

data/README.md

@@ -12,8 +12,8 @@ ORM offering the following features:
 * *Reusable:* The Packer library naturally composes well with itself. Nested
   data can be serialized in the same way no matter what endpoint it's fetched
   from.
-* *Efficient:* When not using Sequel's [`TacticalEagerLoading`]
-  (https://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/TacticalEagerLoading.html)
+* *Efficient:* When not using Sequel's
+  [`TacticalEagerLoading`](https://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/TacticalEagerLoading.html)
   plugin, the Packer library will intelligently determine which associations
   and nested associations it needs to eager load in order to avoid any N+1 query
   issues.
@@ -58,8 +58,12 @@ DB.create_table(:comments) do
   String :content
 end
 
-class User < Sequel::Model(:users); end
-class Post < Sequel::Model(:posts); end
+class User < Sequel::Model(:users)
+  one_to_many :posts, key: :author_id, class: :Post
+end
+class Post < Sequel::Model(:posts)
+  one_to_many :comments, key: :post_id, class: :Comment
+end
 class Comment < Sequel::Model(:comments)
   many_to_one :author, key: :author_id, class: :User
 end
@@ -318,7 +322,8 @@ end
 ```
 
 Though this version of course would result in many more queries to the database,
-which are not required when using the shorthand form.
+which are not required when using the shorthand form, and also requires creating
+a new instance of `packer_class` for every packed model.
 
 ### `self.field(&block)`
 
@@ -383,7 +388,7 @@ class UserPacker < Sequel::Packer
 
   eager(:posts)
   field(:num_posts) do |user|
-    user.posts.counts
+    user.posts.count
   end
 end
 
@@ -396,8 +401,7 @@ UserPacker.new.pack(User.dataset)
 ```
 
 This helps prevent N+1 query problems when not using Sequel's
-[`TacticalEagerLoading`]
-(https://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/TacticalEagerLoading.html)
+[`TacticalEagerLoading`](https://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/TacticalEagerLoading.html)
 plugin.
 
 Another use of `eager`, even when using `TacticalEagerLoading`, is to modify or
@@ -425,6 +429,70 @@ Also, it's important to note that if `eager` is called multiple times, with
 multiple procs, each proc will get applied to the dataset, likely resulting in
 overly restrictive filtering.
 
+### `self.set_association_packer(association, packer_class, *traits)`
+
+See `self.pack_association(association, models)` below.
+
+### `self.pack_association(association, models)`
+
+The simplest way to pack an association is to use
+`self.field(association, packer_class, *traits)`, but sometimes this doesn't do
+exactly what we want. We may want to pack the association under a different key
+than the name of the association. Or we may only want to pack some of the
+associated models (and it may be difficult or impossible to express which subset
+we want to pack using `eager`). Or perhaps we have a `one_to_many` association
+and instead of packing an array, we want to pack a single associated object
+under a key. The two methods, `set_association_packer` and `pack_association`
+are designed to handle these cases.
+
+First, we'll note that following are exactly equivalent:
+
+```ruby
+field :my_assoc, MyAssocPacker, :trait1, :trait2
+```
+
+and
+
+```ruby
+set_association_packer :my_assoc, MyAssocPacker, :trait1, :trait2
+field :my_assoc do |model|
+  pack_association(:my_assoc, model.my_assoc)
+end
+```
+
+`set_association_packer` tells the Packer class that we will want to pack models
+from a particular association using the designated Packer with the specified
+traits. Declaring this ahead of time allows the Packer to ensure that the
+association is eager loaded, as well as any nested associations used when using
+the designated Packer with the specified traits.
+
+`pack_association` can then be used in a `field` block to use that Packer after
+the data has been fetched and we are actually packing the data. The key things
+here are that we don't need to use the name of the association as the name of
+the field, and that we can choose which models get serialized. If
+`pack_association` is passed an array, it will return an array of packed models,
+but if it is passed a single model, it will return just that packed model.
+
+Examples:
+
+#### Use a different field name than the name of the association
+```ruby
+set_association_packer :ugly_internal_names, InternalPacker
+field :nice_external_names do |model|
+  pack_association(:ugly_internal_names, model.ugly_internal_names)
+end
+```
+
+#### Pack a single instance of a `one_to_many` association
+```ruby
+class PostPacker < Sequel::Packer
+  set_association_packer :comments, CommentPacker
+  field :top_comment do |model|
+    pack_association(:comments, model.comments.max_by(&:num_likes))
+  end
+end
+```
+
 
 ### `initialize(*traits)`
 

data/lib/sequel/packer/validation.rb

@@ -0,0 +1,137 @@
+require 'sequel'
+
+module Sequel
+  class Packer
+    module Validation
+      # Cheks for common errors when using the field method. Additional
+      # checks around the packer class and traits occur in
+      # check_association_packer.
+      def self.check_field_arguments(
+        model,
+        field_name,
+        packer_class,
+        traits,
+        &block
+      )
+        fail ModelNotYetDeclaredError if !model
+
+        # This check applies to all invocations:
+        if field_name && !field_name.is_a?(Symbol) && !field_name.is_a?(String)
+          raise(
+            FieldArgumentError,
+            'Field name passed to Sequel::Packer::field must be a Symbol or ' +
+              'a String.',
+          )
+        end
+
+        if block
+          # If the user passed a block, we'll assume they either want:
+          #     field :foo {|model| ...}
+          # or  field {|model, hash| ...}
+          #
+          if packer_class || traits.any?
+            raise(
+              FieldArgumentError,
+              'When passing a block to Sequel::Packer::field, either pass the ' +
+                'name of field as a single argument (e.g., field(:foo) ' +
+                '{|model| ...}), or nothing at all to perform arbitrary ' +
+                'modifications of the final hash (e.g., field {|model, hash| ' +
+                '...}).',
+            )
+          end
+
+          arity = block.arity
+
+          # When using Symbol.to_proc (field(:foo, &:calculate_foo)), the block has arity -1.
+          if field_name && arity != 1 && arity != -1
+            raise(
+              FieldArgumentError,
+              "The block used to define :#{field_name} must accept exactly " +
+                'one argument.',
+            )
+          end
+
+          if !field_name && arity != 2
+            raise(
+              FieldArgumentError,
+              'When passing an arbitrary block to Sequel::Packer::field, the ' +
+                'block must accept exactly two arguments: the model and the ' +
+                'partially packed hash.',
+            )
+          end
+        else
+          # In this part of the if, block is not defined
+
+          if !field_name
+            # Note that this error isn't technically true, but usage of the
+            # field {|model, hash| ...} variant is likely pretty rare.
+            raise(
+              FieldArgumentError,
+              'Must pass a field name to Sequel::Packer::field.',
+            )
+          end
+
+          if model.associations.include?(field_name) && !packer_class
+            raise(
+              InvalidAssociationPackerError,
+              "#{field_name} is an association of #{model}. You must also " +
+                'pass a Sequel::Packer class to be used when serializing ' +
+                'this association.',
+            )
+          end
+        end
+      end
+
+      # Performs various checks when using
+      #   field(association, packer_class, *traits)
+      #   or
+      #   set_association_packer(association, packer_class, *traits)
+      def self.check_association_packer(
+        model,
+        association,
+        packer_class,
+        traits
+      )
+        if !model.associations.include?(association)
+          raise(
+            AssociationDoesNotExistError,
+            "The association :#{association} does not exist on #{model}.",
+          )
+        end
+
+        if !packer_class || !(packer_class < Sequel::Packer)
+          raise(
+            InvalidAssociationPackerError,
+            'You must pass a Sequel::Packer class to use when packing the ' +
+              ":#{association} association. #{packer_class} is not a " +
+              "subclass of Sequel::Packer."
+          )
+        end
+
+        association_model =
+          model.association_reflections[association].associated_class
+        packer_class_model = packer_class.instance_variable_get(:@model)
+
+        if !(association_model <= packer_class_model)
+          raise(
+            InvalidAssociationPackerError,
+            "Model for association packer (#{packer_class_model}) " +
+              "doesn't match model for the #{association} association " +
+              "(#{association_model})",
+          )
+        end
+
+        packer_class_traits = packer_class.instance_variable_get(:@class_traits)
+        traits.each do |trait|
+          if !packer_class_traits.key?(trait)
+            raise(
+              UnknownTraitError,
+              "Trait :#{trait} isn't defined for #{packer_class} used to " +
+                "pack #{association} association.",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/packer/version.rb

@@ -1,5 +1,5 @@
 module Sequel
   class Packer
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/sequel/packer.rb

@@ -4,11 +4,15 @@ module Sequel
     class FieldArgumentError < ArgumentError; end
     # Must declare a model with `model MyModel` before calling field.
     class ModelNotYetDeclaredError < StandardError; end
+    class AssociationDoesNotExistError < StandardError; end
+    class InvalidAssociationPackerError < StandardError; end
+    class UnknownTraitError < StandardError; end
 
     def self.inherited(subclass)
-      subclass.instance_variable_set(:@fields, [])
-      subclass.instance_variable_set(:@traits, {})
-      subclass.instance_variable_set(:@eager_hash, nil)
+      subclass.instance_variable_set(:@class_fields, [])
+      subclass.instance_variable_set(:@class_traits, {})
+      subclass.instance_variable_set(:@class_packers, {})
+      subclass.instance_variable_set(:@class_eager_hash, nil)
     end
 
     def self.model(klass)
@@ -34,22 +38,31 @@ module Sequel
     ARBITRARY_MODIFICATION_FIELD = :arbitrary_modification_field
 
     def self.field(field_name=nil, packer_class=nil, *traits, &block)
-      validate_field_args(field_name, packer_class, *traits, &block)
-      field_type = determine_field_type(field_name, packer_class, &block)
+      Validation.check_field_arguments(
+        @model, field_name, packer_class, traits, &block)
+      field_type = determine_field_type(field_name, packer_class, block)
 
-      @fields << {
+      if field_type == ASSOCIATION_FIELD
+        set_association_packer(field_name, packer_class, *traits)
+      end
+
+      @class_fields << {
         type: field_type,
         name: field_name,
-        packer: packer_class,
-        packer_traits: traits,
         block: block,
       }
     end
 
+    def self.set_association_packer(association, packer_class, *traits)
+      Validation.check_association_packer(
+        @model, association, packer_class, traits)
+      @class_packers[association] = [packer_class, traits]
+    end
+
     private_class_method def self.determine_field_type(
-      field_name=nil,
-      packer_class=nil,
-      &block
+      field_name,
+      packer_class,
+      block
     )
       if block
         if field_name
@@ -66,175 +79,65 @@ module Sequel
       end
     end
 
-    private_class_method def self.validate_field_args(
-      field_name=nil,
-      packer_class=nil,
-      *traits,
-      &block
-    )
-      fail ModelNotYetDeclaredError if !@model
-
-      # This check applies to all invocations:
-      if field_name && !field_name.is_a?(Symbol) && !field_name.is_a?(String)
-        raise(
-          FieldArgumentError,
-          'Field name passed to Sequel::Packer::field must be a Symbol or ' +
-            'a String.',
-        )
-      end
-
-      if block
-        # If the user passed a block, we'll assume they either want:
-        #     field :foo {|model| ...}
-        # or  field {|model, hash| ...}
-        #
-        if packer_class || traits.any?
-          raise(
-            FieldArgumentError,
-            'When passing a block to Sequel::Packer::field, either pass the ' +
-              'name of field as a single argument (e.g., field(:foo) ' +
-              '{|model| ...}), or nothing at all to perform arbitrary ' +
-              'modifications of the final hash (e.g., field {|model, hash| ' +
-              '...}).',
-          )
-        end
-
-        arity = block.arity
-
-        # When using Symbol.to_proc (field(:foo, &:calculate_foo)), the block has arity -1.
-        if field_name && arity != 1 && arity != -1
-          raise(
-            FieldArgumentError,
-            "The block used to define :#{field_name} must accept exactly " +
-              'one argument.',
-          )
-        end
-
-        if !field_name && arity != 2
-          raise(
-            FieldArgumentError,
-            'When passing an arbitrary block to Sequel::Packer::field, the ' +
-              'block must accept exactly two arguments: the model and the ' +
-              'partially packed hash.',
-          )
-        end
-      else
-        # In this part of the if, block is not defined
-
-        if !field_name
-          # Note that this error isn't technically true, but usage of the
-          # field {|model, hash| ...} variant is likely pretty rare.
-          raise(
-            FieldArgumentError,
-            'Must pass a field name to Sequel::Packer::field.',
-          )
-        end
-
-        if packer_class || traits.any?
-          if !@model.associations.include?(field_name)
-            raise(
-              FieldArgumentError,
-              'Passing multiple arguments to Sequel::Packer::field ' +
-                'is used to serialize associations with designated ' +
-                "packers, but the association #{field_name} does not " +
-                "exist on #{@model}.",
-            )
-          end
-
-          if !(packer_class < Sequel::Packer)
-            raise(
-              FieldArgumentError,
-              'When declaring the serialization behavior for an ' +
-                'association, the second argument must be a Sequel::Packer ' +
-                "subclass. #{packer_class} is not a subclass of " +
-                'Sequel::Packer.',
-            )
-          end
-
-          association_model =
-            @model.association_reflections[field_name].associated_class
-          packer_class_model = packer_class.instance_variable_get(:@model)
-
-          if !(association_model <= packer_class_model)
-            raise(
-              FieldArgumentError,
-              "Model for association packer (#{packer_class_model}) " +
-                "doesn't match model for the #{field_name} association " +
-                "(#{association_model})",
-            )
-          end
-
-          packer_class_traits = packer_class.instance_variable_get(:@traits)
-          traits.each do |trait|
-            if !packer_class_traits.key?(trait)
-              raise(
-                FieldArgumentError,
-                "Trait :#{trait} isn't defined for #{packer_class} used to " +
-                  "pack #{field_name} association.",
-              )
-            end
-          end
-        else
-          if @model.associations.include?(field_name)
-            raise(
-              FieldArgumentError,
-              'When declaring a field for a model association, you must ' +
-                'also pass a Sequel::Packer class to use as the second ' +
-                'argument to field.',
-            )
-          end
-        end
-      end
-    end
-
     def self.trait(name, &block)
-      raise ArgumentError, "Trait :#{name} already defined" if @traits.key?(name)
+      if @class_traits.key?(name)
+        raise ArgumentError, "Trait :#{name} already defined"
+      end
       if !block_given?
         raise ArgumentError, 'Must give a block when defining a trait'
       end
-      @traits[name] = block
+      @class_traits[name] = block
     end
 
     def self.eager(*associations)
-      @eager_hash = EagerHash.merge!(
-        @eager_hash,
+      @class_eager_hash = EagerHash.merge!(
+        @class_eager_hash,
         EagerHash.normalize_eager_args(*associations),
       )
     end
 
     def initialize(*traits)
-      @packers = nil
-      @fields = traits.any? ? packer_fields.dup : packer_fields
-      @eager_hash = traits.any? ? EagerHash.deep_dup(packer_eager_hash) : packer_eager_hash
+      @subpackers = nil
+
+      # If there aren't any traits, we can just re-use the class variables.
+      if traits.empty?
+        @instance_fields = class_fields
+        @instance_packers = class_packers
+        @instance_eager_hash = class_eager_hash
+      else
+        @instance_fields = class_fields.dup
+        @instance_packers = class_packers.dup
+        @instance_eager_hash = EagerHash.deep_dup(class_eager_hash)
+      end
 
+      # Evaluate trait blocks, which might add new fields to @instance_fields,
+      # new packers to @instance_packers, and/or new associations to
+      # @instance_eager_hash.
       traits.each do |trait|
-        trait_block = trait_blocks[trait]
+        trait_block = class_traits[trait]
         if !trait_block
-          raise ArgumentError, "Unknown trait for #{self.class}: :#{trait}"
+          raise UnknownTraitError, "Unknown trait for #{self.class}: :#{trait}"
         end
 
         self.instance_exec(&trait_block)
       end
 
-      @fields.each do |field_options|
-        if field_options[:type] == ASSOCIATION_FIELD
-          association = field_options[:name]
-          association_packer =
-            field_options[:packer].new(*field_options[:packer_traits])
+      # Create all the subpackers, and merge in their eager hashes.
+      @instance_packers.each do |association, (packer_class, traits)|
+        association_packer = packer_class.new(*traits)
 
-          @packers ||= {}
-          @packers[association] = association_packer
+        @subpackers ||= {}
+        @subpackers[association] = association_packer
 
-          @eager_hash = EagerHash.merge!(
-            @eager_hash,
-            {association => association_packer.send(:eager_hash)},
-          )
-        end
+        @instance_eager_hash = EagerHash.merge!(
+          @instance_eager_hash,
+          {association => association_packer.send(:eager_hash)},
+        )
       end
     end
 
     def pack(dataset)
-      dataset = dataset.eager(@eager_hash) if @eager_hash
+      dataset = dataset.eager(@instance_eager_hash) if @instance_eager_hash
       models = dataset.all
       pack_models(models)
     end
@@ -242,26 +145,19 @@ module Sequel
     def pack_model(model)
       h = {}
 
-      @fields.each do |field_options|
+      @instance_fields.each do |field_options|
         field_name = field_options[:name]
 
         case field_options[:type]
         when METHOD_FIELD
           h[field_name] = model.send(field_name)
         when BLOCK_FIELD
-          h[field_name] = field_options[:block].call(model)
+          h[field_name] = instance_exec(model, &field_options[:block])
         when ASSOCIATION_FIELD
           associated_objects = model.send(field_name)
-
-          if !associated_objects
-            h[field_name] = nil
-          elsif associated_objects.is_a?(Array)
-            h[field_name] = @packers[field_name].pack_models(associated_objects)
-          else
-            h[field_name] = @packers[field_name].pack_model(associated_objects)
-          end
+          h[field_name] = pack_association(field_name, associated_objects)
         when ARBITRARY_MODIFICATION_FIELD
-          field_options[:block].call(model, h)
+          instance_exec(model, h, &field_options[:block])
         end
       end
 
@@ -272,48 +168,77 @@ module Sequel
       models.map {|m| pack_model(m)}
     end
 
+    def pack_association(association, associated_models)
+      return nil if !associated_models
+
+      packer = @subpackers[association]
+
+      if associated_models.is_a?(Array)
+        packer.pack_models(associated_models)
+      else
+        packer.pack_model(associated_models)
+      end
+    end
+
     private
 
     def field(field_name=nil, packer_class=nil, *traits, &block)
       klass = self.class
-      klass.send(
-        :validate_field_args, field_name, packer_class, *traits, &block)
+      model = klass.instance_variable_get(:@model)
+
+      Validation.check_field_arguments(
+        model, field_name, packer_class, traits, &block)
       field_type =
-        klass.send(:determine_field_type, field_name, packer_class, &block)
+        klass.send(:determine_field_type, field_name, packer_class, block)
+
+      if field_type == ASSOCIATION_FIELD
+        set_association_packer(field_name, packer_class, *traits)
+      end
 
-      @fields << {
+      @instance_fields << {
         type: field_type,
         name: field_name,
-        packer: packer_class,
-        packer_traits: traits,
         block: block,
       }
     end
 
+    def set_association_packer(association, packer_class, *traits)
+      model = self.class.instance_variable_get(:@model)
+      Validation.check_association_packer(
+        model, association, packer_class, traits)
+
+      @instance_packers[association] = [packer_class, traits]
+    end
+
     def eager_hash
-      @eager_hash
+      @instance_eager_hash
     end
 
     def eager(*associations)
-      @eager_hash = EagerHash.merge!(
-        @eager_hash,
+      @instance_eager_hash = EagerHash.merge!(
+        @instance_eager_hash,
         EagerHash.normalize_eager_args(*associations),
       )
     end
 
-    def packer_fields
-      self.class.instance_variable_get(:@fields)
+    def class_fields
+      self.class.instance_variable_get(:@class_fields)
+    end
+
+    def class_eager_hash
+      self.class.instance_variable_get(:@class_eager_hash)
     end
 
-    def packer_eager_hash
-      self.class.instance_variable_get(:@eager_hash)
+    def class_packers
+      self.class.instance_variable_get(:@class_packers)
     end
 
-    def trait_blocks
-      self.class.instance_variable_get(:@traits)
+    def class_traits
+      self.class.instance_variable_get(:@class_traits)
     end
   end
 end
 
 require 'sequel/packer/eager_hash'
+require 'sequel/packer/validation'
 require "sequel/packer/version"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel-packer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Paul Julius Martinez
@@ -128,6 +128,7 @@ files:
 - bin/setup
 - lib/sequel/packer.rb
 - lib/sequel/packer/eager_hash.rb
+- lib/sequel/packer/validation.rb
 - lib/sequel/packer/version.rb
 - sequel-packer.gemspec
 homepage: https://github.com/PaulJuliusMartinez/sequel-packer