sequel-packer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1420dc6158b5ec7447d40e2818513a0b73c948fe1f2c9dced0732f1ad10e97db
-  data.tar.gz: e18293bafbe14d0af6c81ddde1e64e026498c61492bc26338bbc9fdbbd08507b
+  metadata.gz: 00bbe557f19cf23a18afe4e5d23173a3fb699977680fae2efa99670240f81847
+  data.tar.gz: 324688d708be91fa8e89eb99a65701f35dc8f3f5a799719588fa84adff877c95
 SHA512:
-  metadata.gz: 43da46c32b0f2b068dc7c0c29022ea6ffebd6bf7becaae55185db95626779ed968c82f06d8edb424b6c33430edd58c53e44785ef0b1b9bdb240429b24b70aaa8
-  data.tar.gz: 40d48122b9ce084f0c6b585b805481f2ef057ce2158a505782e2d2b0d2f58db4d1c4fd32a22de4f7178cbe82fdf6013694020558e305a1bd4845086648675731
+  metadata.gz: a626e68bd1053d818bd830a198bfe92b13bcbc0286a2ce985a996049ba7858a229aeabb00181e144fadfa8dbcc63ca90adef89619ddc32d86076ee53b718b424
+  data.tar.gz: 0344f7b561e830c58dd01c68da86728f57594a8073b920e4de70401e038e7a0cf92907f37726d84d9243268c12d3b256195df523d224224b69f53ee16f26136a

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+### 0.2.0 (2020-05-13)
+
+* Add support for `Sequel::Packer.eager(*associations)`
+* Use `Sequel::Dataset.eager` in the background when fetching a dataset to avoid
+  N+1 query issues.
+
 ### 0.1.0 (2020-05-11)
 
 * Add traits.

data/README.md

@@ -1,6 +1,22 @@
 # Sequel::Packer
 
-A Ruby serialization library to be used with the Sequel ORM.
+`Sequel::Packer` is a Ruby JSON serialization library to be used with the Sequel
+ORM offering the following features:
+
+* *Declarative:* Define the shape of your serialized data with a simple,
+  straightforward DSL.
+* *Flexible:* Certain contexts require different data. Packers provide an easy
+  way to opt-in to serializing certain data only when you need it. The library
+  also provides convenient escape hatches when you need to do something not
+  explicitly supported by the API.
+* *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)
+  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.
 
 ## Installation
 
@@ -156,8 +172,8 @@ class PostPacker < Sequel::Packer
   ...
 
   # Eww!
--  field :comments, CommentPacker
-+  field :comments, CommentWithAuthorPacker
+- field :comments, CommentPacker
++ field :comments, CommentWithAuthorPacker
 end
 ```
 
@@ -173,10 +189,9 @@ class CommentPacker < Sequel::Packer
   field :id
   field :content
 
-  # Added!
-  trait :author do
-    field :author, UserPacker
-  end
++ trait :author do
++   field :author, UserPacker
++ end
 end
 ```
 
@@ -214,8 +229,8 @@ class PostPacker < Sequel::Packer
   field :title
   field :content
 
--  field :comments, CommentPacker
-+  field :comments, CommentPacker, :author
+- field :comments, CommentPacker
++ field :comments, CommentPacker, :author
 end
 ```
 
@@ -290,7 +305,7 @@ class MyPacker < Sequel::Packer
 end
 ```
 
-### `self.field(association, packer_class, *traits)
+### `self.field(association, packer_class, *traits)`
 
 A Sequel association (defined in the model file using `one_to_many`, or
 `many_to_one`, etc.), can be packed using another Packer class, possibly with
@@ -318,6 +333,99 @@ field do |model, hash|
 end
 ```
 
+### `self.trait(trait_name, &block)`
+
+Define optional serialization behavior by defining additional fields within a
+`trait` block. Traits can be opted into when initializing a packer by passing
+the name of the trait as an argument:
+
+```ruby
+class MyPacker < Sequel::Packer
+  model MyObj
+  trait :my_trait do
+    field :my_optional_field
+  end
+end
+
+# packed objects don't have my_optional_field
+MyPacker.new.pack(dataset)
+# packed objects do have my_optional_field
+MyPacker.new(:my_trait).pack(dataset)
+```
+
+Traits can also be used when packing associations by passing the name of the
+traits after the packer class:
+
+```ruby
+class MyOtherPacker < Sequel::Packer
+  model MyObj
+  field :my_packers, MyPacker, :my_trait
+end
+```
+
+### `self.eager(*associations)`
+
+When packing an association, a Packer will automatically ensure that association
+is eager loaded, but there may be cases when an association will be accessed
+that the Packer doesn't know about. In these cases you can tell the Packer to
+eager load that data by calling `eager(*associations)`, passing in arguments
+the exact same way you would to [`Sequel::Dataset.eager`](
+https://sequel.jeremyevans.net/rdoc/classes/Sequel/Model/Associations/DatasetMethods.html#method-i-eager).
+
+One case where this may be useful is for a "count" field, that just lists the
+number of associated objects, but doesn't actually return them:
+
+```ruby
+class UserPacker < Sequel::Packer
+  model User
+
+  field :id
+
+  eager(:posts)
+  field(:num_posts) do |user|
+    user.posts.counts
+  end
+end
+
+UserPacker.new.pack(User.dataset)
+=> [
+  {id: 123, num_posts: 7},
+  {id: 456, num_posts: 3},
+  ...
+]
+```
+
+This helps prevent N+1 query problems when not using Sequel's
+[`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
+limit which records gets fetched from the database by using an eager proc. For
+example, to only pack recent posts, published in the past month, we might do:
+
+```
+class UserPacker < Sequel::Packer
+  model User
+
+  field :id
+
+  trait :recent_posts do
+    eager posts: (proc {|ds| ds.where {created_at > Time.now - 1.month}})
+    field :posts, PostIdPacker
+  end
+end
+```
+
+Keep in mind that this limits the association that gets used by ALL fields, so
+if another field actually needs access to all the users posts, it might not make
+sense to use `eager`.
+
+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.
+
+
 ### `initialize(*traits)`
 
 When creating an instance of a Packer class, pass in any traits desired to

data/lib/sequel/packer/eager_hash.rb

@@ -0,0 +1,173 @@
+require 'sequel'
+
+module Sequel
+  class Packer
+    module EagerHash
+      # An eager hash cannot have the form: {
+      #   :assoc1 => :nested_assoc,
+      #   <proc> => :assoc2,
+      # }
+      class MixedProcHashError < StandardError; end
+      # An eager hash cannot have multiple keys that are Procs.
+      class MultipleProcKeysError < StandardError; end
+      # If an eager hash contains a Proc as the key of a hash, that value at
+      # that key cannot be another hash with a Proc as a key.
+      class NestedEagerProcsError < StandardError; end
+
+      # Sequel's eager function can accept arguments in a number of different
+      # formats:
+      #   .eager(:assoc)
+      #   .eager([:assoc1, :assoc2])
+      #   .eager(assoc: :nested_assoc)
+      #   .eager(
+      #     :assoc1,
+      #     assoc2: {(proc {|ds| ...}) => [:nested_assoc1, :nested_assoc2]},
+      #   )
+      #
+      # This method normalizes these arguments such that:
+      # - A Hash is returned
+      # - The keys of that hash are the names of associations
+      # - The values of that hash are either:
+      #   - nil, representing no nested associations
+      #   - a nested normalized hash, meeting these definitions
+      #   - a "Proc hash", which is a hash with a single key, which is a proc,
+      #     and whose value is either nil or a nested normalized hash.
+      #
+      # Notice that a normalized has the property that every value in the hash
+      # is either nil, or itself a normalized hash.
+      #
+      # Note that this method cannot return a "Proc hash" as the top level
+      # normalized hash; Proc hashes can only be nested under other
+      # associations.
+      def self.normalize_eager_args(*associations)
+        # Implementation largely borrowed from Sequel's
+        # eager_options_for_associations:
+        #
+        # https://github.com/jeremyevans/sequel/blob/5.32.0/lib/sequel/model/associations.rb#L3228-L3245
+        normalized_hash = {}
+
+        associations.flatten.each do |association|
+          case association
+          when Symbol
+            normalized_hash[association] = nil
+          when Hash
+            num_proc_keys = 0
+            num_symbol_keys = 0
+
+            association.each do |key, val|
+              case key
+              when Symbol
+                num_symbol_keys += 1
+              when Proc
+                num_proc_keys += 1
+
+                if val.is_a?(Proc) || is_proc_hash?(val)
+                  raise(
+                    NestedEagerProcsError,
+                    "eager hash has nested Procs: #{associations.inspect}",
+                  )
+                end
+              end
+
+              if val.nil?
+                # Already normalized
+                normalized_hash[key] = nil
+              elsif val.is_a?(Proc)
+                # Convert Proc value to a Proc hash.
+                normalized_hash[key] = {val => nil}
+              else
+                # Otherwise recurse.
+                normalized_hash[key] = normalize_eager_args(val)
+              end
+            end
+
+            if num_proc_keys > 1
+              raise(
+                MultipleProcKeysError,
+                "eager hash has multiple Proc keys: #{associations.inspect}",
+              )
+            end
+
+            if num_proc_keys > 0 && num_symbol_keys > 0
+              raise(
+                MixedProcHashError,
+                'eager hash has both symbol keys and Proc keys: ' +
+                  associations.inspect,
+              )
+            end
+          else
+            raise(
+              Sequel::Error,
+              'Associations must be in the form of a symbol or hash',
+            )
+          end
+        end
+
+        normalized_hash
+      end
+
+      def self.is_proc_hash?(hash)
+        return false if !hash.is_a?(Hash)
+        return false if hash.size != 1
+        hash.keys[0].is_a?(Proc)
+      end
+
+      # Merges two eager hashes together, without modifying either one.
+      def self.merge(hash1, hash2)
+        return deep_dup(hash2) if !hash1
+        merge!(deep_dup(hash1), hash2)
+      end
+
+      # Merges two eager hashes together, modifying the first hash, while
+      # leaving the second unmodified. Since the first argument may be nil,
+      # callers should still use the return value, rather than the first
+      # argument.
+      def self.merge!(hash1, hash2)
+        return hash1 if !hash2
+        return deep_dup(hash2) if !hash1
+
+        hash2.each do |key, val2|
+          if !hash1.key?(key)
+            hash1[key] = deep_dup(val2)
+            next
+          end
+
+          val1 = hash1[key]
+          h1_is_proc_hash = is_proc_hash?(val1)
+          h2_is_proc_hash = is_proc_hash?(val2)
+
+          case [h1_is_proc_hash, h2_is_proc_hash]
+          when [false, false]
+            hash1[key] = merge!(val1, val2)
+          when [true, false]
+            # We want to actually merge the hash the proc points to.
+            eager_proc, nested_hash = val1.entries[0]
+            hash1[key] = {eager_proc => merge!(nested_hash, val2)}
+          when [false, true]
+            # Same as above, but flipped. Notice the order of the arguments to
+            # merge! to ensure hash2 is not modified!
+            eager_proc, nested_hash = val2.entries[0]
+            hash1[key] = {eager_proc => merge!(val1, nested_hash)}
+          when [true, true]
+            # Create a new proc that applies both procs, then merge their
+            # respective hashes.
+            proc1, nested_hash1 = val1.entries[0]
+            proc2, nested_hash2 = val2.entries[0]
+
+            new_proc = (proc {|ds| proc2.call(proc1.call(ds))})
+
+            hash1[key] = {new_proc => merge!(nested_hash1, nested_hash2)}
+          end
+        end
+
+        hash1
+      end
+
+      # Creates a deep copy of an eager hash.
+      def self.deep_dup(hash)
+        return nil if !hash
+        hash.transform_values {|val| deep_dup(val)}
+      end
+    end
+  end
+end

data/lib/sequel/packer/version.rb

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

data/lib/sequel/packer.rb

@@ -8,6 +8,7 @@ module Sequel
     def self.inherited(subclass)
       subclass.instance_variable_set(:@fields, [])
       subclass.instance_variable_set(:@traits, {})
+      subclass.instance_variable_set(:@eager_hash, nil)
     end
 
     def self.model(klass)
@@ -194,9 +195,17 @@ module Sequel
       @traits[name] = block
     end
 
+    def self.eager(*associations)
+      @eager_hash = EagerHash.merge!(
+        @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
 
       traits.each do |trait|
         trait_block = trait_blocks[trait]
@@ -209,14 +218,23 @@ module Sequel
 
       @fields.each do |field_options|
         if field_options[:type] == ASSOCIATION_FIELD
-          @packers ||= {}
-          @packers[field_options[:name]] =
+          association = field_options[:name]
+          association_packer =
             field_options[:packer].new(*field_options[:packer_traits])
+
+          @packers ||= {}
+          @packers[association] = association_packer
+
+          @eager_hash = EagerHash.merge!(
+            @eager_hash,
+            {association => association_packer.send(:eager_hash)},
+          )
         end
       end
     end
 
     def pack(dataset)
+      dataset = dataset.eager(@eager_hash) if @eager_hash
       models = dataset.all
       pack_models(models)
     end
@@ -272,15 +290,30 @@ module Sequel
       }
     end
 
+    def eager_hash
+      @eager_hash
+    end
+
+    def eager(*associations)
+      @eager_hash = EagerHash.merge!(
+        @eager_hash,
+        EagerHash.normalize_eager_args(*associations),
+      )
+    end
+
     def packer_fields
       self.class.instance_variable_get(:@fields)
     end
 
+    def packer_eager_hash
+      self.class.instance_variable_get(:@eager_hash)
+    end
+
     def trait_blocks
       self.class.instance_variable_get(:@traits)
     end
   end
 end
 
+require 'sequel/packer/eager_hash'
 require "sequel/packer/version"
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequel-packer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Paul Julius Martinez
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-05-12 00:00:00.000000000 Z
+date: 2020-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel
@@ -127,6 +127,7 @@ files:
 - bin/console
 - bin/setup
 - lib/sequel/packer.rb
+- lib/sequel/packer/eager_hash.rb
 - lib/sequel/packer/version.rb
 - sequel-packer.gemspec
 homepage: https://github.com/PaulJuliusMartinez/sequel-packer