sequel-packer 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 248126ba630e1d763f32e911c992b296cd32b5201503a67296bbb18fa4000679
-  data.tar.gz: abecaa06c7e4d64eef3e4b91be2311cd2921e966062fd03fc5a5d590604c6b92
+  metadata.gz: 1420dc6158b5ec7447d40e2818513a0b73c948fe1f2c9dced0732f1ad10e97db
+  data.tar.gz: e18293bafbe14d0af6c81ddde1e64e026498c61492bc26338bbc9fdbbd08507b
 SHA512:
-  metadata.gz: 0231fbedf7d8d7ccd77093e00617bf15688ed57e52d169876780854023e3c6c758dd34d002d89952795291a8c1f5c7ef398f7f24543cf686be85e496059a5f58
-  data.tar.gz: da6163737a56d4a96205ff0c26ce9ece0b90b2763c1fe271b899d3b55261bc67cf36ea35d4e75cdac540c81fd587618fbb0272691bbd86fcca0375e712d31809
+  metadata.gz: 43da46c32b0f2b068dc7c0c29022ea6ffebd6bf7becaae55185db95626779ed968c82f06d8edb424b6c33430edd58c53e44785ef0b1b9bdb240429b24b70aaa8
+  data.tar.gz: 40d48122b9ce084f0c6b585b805481f2ef057ce2158a505782e2d2b0d2f58db4d1c4fd32a22de4f7178cbe82fdf6013694020558e305a1bd4845086648675731

data/CHANGELOG.md

@@ -1,9 +1,13 @@
+### 0.1.0 (2020-05-11)
+
+* Add traits.
+
 ### 0.0.2 (2020-05-11)
 
-* Added support for `Sequel::Packer.field(key, &block)` and
+* Add support for `Sequel::Packer.field(key, &block)` and
   `Sequel::Packer.field(&block)`
-* Added validation to `Sequel::Packer::field` to detect incorrect usage.
-* Added support for nested packing of associations using
+* Add validation to `Sequel::Packer::field` to detect incorrect usage.
+* Add support for nested packing of associations using
   `Sequel::Packer.field(association, packer_class)`
 * Update README with usage instructions and basic API reference.
 

data/README.md

@@ -49,6 +49,8 @@ class Comment < Sequel::Model(:comments)
 end
 ```
 
+### Basic Fields
+
 Suppose an endpoint wants to fetch all the ten most recent comments by a user.
 After validating the user id, we end up with the Sequel dataset represting the
 data we want to return:
@@ -77,17 +79,54 @@ This can then be used as follows:
 ```ruby
 CommentPacker.new.pack(recent_comments)
 => [
-  {id: 536, "Great post, man!"},
-  {id: 436, "lol"},
-  {id: 413, "What a story..."},
+  {id: 536, content: "Great post, man!"},
+  {id: 436, content: "lol"},
+  {id: 413, content: "What a story..."},
 ]
 ```
 
-In another context, suppose that we want to fetch the comments on a post along
-with the authors of those comments.
+### Packing associations by nesting Packers
 
-In this case we could define two separate Packers, one for Users, and another
-for Comments:
+Now, suppose that we want to fetch a post and all of its comments. We can do
+this by defining another packer for Post that uses the CommentPacker:
+
+```ruby
+class PostPacker < Sequel::Packer
+  model Post
+
+  field :id
+  field :title
+  field :content
+  field :comments, CommentPacker
+end
+```
+
+Since `post.comments` is an array of Sequel::Models and not a primitive value,
+we must tell the Packer how to serialize them using another packer. This is
+what the second argument in `field :comments, CommentPacker` is doing.
+
+We can then use this as follows:
+
+```ruby
+PostPacker.new.pack(Post.order(:id.desc).limit(1))
+=> [
+  {
+    id: 682,
+    title: "Announcing sequel-packer",
+    content: "I've written a new gem...",
+    comments: [
+      {id: 536, content: "Great post, man!"},
+      {id: 541, content: "Incredible, this solves my EXACT problem!"},
+      ...
+    ],
+  }
+]
+```
+
+### Traits
+
+But suppose we want to be able to show who authored each comment on the post. We
+first have to define a packer for users:
 
 ```ruby
 class UserPacker < Sequel::Packer
@@ -96,37 +135,94 @@ class UserPacker < Sequel::Packer
   field :id
   field :name
 end
+```
 
+We could now define a new packer, `CommentWithAuthorPacker`, and use that in the
+PostPacker instead, but then we'd have to redeclare all the other fields we want
+on a packed Comment:
+
+```ruby
 class CommentWithAuthorPacker < Sequel::Packer
   model Comment
 
+  field :author, UserPacker
+
+  # Also defined in CommentPacker!
   field :id
   field :content
-  field :author, UserPacker
+end
+
+class PostPacker < Sequel::Packer
+  ...
+
+  # Eww!
+-  field :comments, CommentPacker
++  field :comments, CommentWithAuthorPacker
 end
 ```
 
-When we use this, we get:
+Declaring these fields in two places could cause them to get out of sync
+as more fields are added. Instead, we will use a _trait_. A _trait_ is a
+way to define a set of fields that we only want to pack sometimes. Instead
+of defining a totally new packer, we can extend the CommentPacker as follows:
 
 ```ruby
-comments_on_post = Comment.where(post_id: post.id)
-CommentWithAuthorPacker.new.pack(comments_on_post)
+class CommentPacker < Sequel::Packer
+  model Comment
+
+  field :id
+  field :content
+
+  # Added!
+  trait :author do
+    field :author, UserPacker
+  end
+end
+```
+
+To use a trait, simply pass it in when creating the packer instance:
+
+```ruby
+# Without the trait
+CommentPacker.new.pack(Comment.dataset)
+=> [
+  {id: 536, content: "Great post, man!"},
+  ...
+]
+
+# With the trait
+CommentPacker.new(:author).pack(Comment.dataset)
 => [
   {
-    id: 752,
-    content: "Great gem",
-    author: {id: 382, name: "Jeremy Evans"},
-  },
-  {
-    id: 162,
-    content: "Never seen anything like it",
-    author: {id: 382, name: "Donald Knuth"},
+    id: 536,
+    content: "Great post, man!",
+    author: {id: 1, name: "Paul Martinez"},
   },
   ...
 ]
 ```
 
-See the API Reference below for the exact API.
+To use a trait when packing an association in another packer, simply include
+the name of the trait as additional argument to `field`. Thus, to modify our
+PostPacker to pack comments with their authors we make the following change:
+
+```ruby
+class PostPacker < Sequel::Packer
+  model Post
+
+  field :id
+  field :title
+  field :content
+
+-  field :comments, CommentPacker
++  field :comments, CommentPacker, :author
+end
+```
+
+While the basic Packer DSL is convenient, traits are the things that make
+Packers so powerful. Each packer should define a small set of fields that every
+endpoint needs, but then traits can be used to pack additional data only when
+it's needed.
 
 ## API Reference
 
@@ -194,15 +290,15 @@ class MyPacker < Sequel::Packer
 end
 ```
 
-### `self.field(association, packer_class)
+### `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. A similar
-output could be generated by doing:
+`many_to_one`, etc.), can be packed using another Packer class, possibly with
+multiple traits specified. A similar output could be generated by doing:
 
 ```ruby
 field :association do |model|
-  packer_class.new.pack(model.association_dataset)
+  packer_class.new(*traits).pack(model.association_dataset)
 end
 ```
 
@@ -222,6 +318,11 @@ field do |model, hash|
 end
 ```
 
+### `initialize(*traits)`
+
+When creating an instance of a Packer class, pass in any traits desired to
+specify what additional data should be packed, if any.
+
 ### `pack(dataset)`
 
 After creating a new instance of a Packer class, call `packer.pack(dataset)` to

data/lib/sequel/packer/version.rb

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

data/lib/sequel/packer.rb

@@ -7,6 +7,7 @@ module Sequel
 
     def self.inherited(subclass)
       subclass.instance_variable_set(:@fields, [])
+      subclass.instance_variable_set(:@traits, {})
     end
 
     def self.model(klass)
@@ -31,7 +32,45 @@ module Sequel
     # field(&block)
     ARBITRARY_MODIFICATION_FIELD = :arbitrary_modification_field
 
-    def self.field(field_name=nil, packer_class=nil, &block)
+    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)
+
+      @fields << {
+        type: field_type,
+        name: field_name,
+        packer: packer_class,
+        packer_traits: traits,
+        block: block,
+      }
+    end
+
+    private_class_method def self.determine_field_type(
+      field_name=nil,
+      packer_class=nil,
+      &block
+    )
+      if block
+        if field_name
+          BLOCK_FIELD
+        else
+          ARBITRARY_MODIFICATION_FIELD
+        end
+      else
+        if packer_class
+          ASSOCIATION_FIELD
+        else
+          METHOD_FIELD
+        end
+      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:
@@ -48,7 +87,7 @@ module Sequel
         #     field :foo {|model| ...}
         # or  field {|model, hash| ...}
         #
-        if packer_class
+        if packer_class || traits.any?
           raise(
             FieldArgumentError,
             'When passing a block to Sequel::Packer::field, either pass the ' +
@@ -90,7 +129,7 @@ module Sequel
           )
         end
 
-        if packer_class
+        if packer_class || traits.any?
           if !@model.associations.include?(field_name)
             raise(
               FieldArgumentError,
@@ -123,6 +162,17 @@ module Sequel
                 "(#{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(
@@ -134,37 +184,34 @@ module Sequel
           end
         end
       end
+    end
 
-      field_type =
-        if block
-          if field_name
-            BLOCK_FIELD
-          else
-            ARBITRARY_MODIFICATION_FIELD
-          end
-        else
-          if packer_class
-            ASSOCIATION_FIELD
-          else
-            METHOD_FIELD
-          end
-        end
-
-      @fields << {
-        type: field_type,
-        name: field_name,
-        packer: packer_class,
-        block: block,
-      }
+    def self.trait(name, &block)
+      raise ArgumentError, "Trait :#{name} already defined" if @traits.key?(name)
+      if !block_given?
+        raise ArgumentError, 'Must give a block when defining a trait'
+      end
+      @traits[name] = block
     end
 
-    def initialize
+    def initialize(*traits)
       @packers = nil
+      @fields = traits.any? ? packer_fields.dup : packer_fields
+
+      traits.each do |trait|
+        trait_block = trait_blocks[trait]
+        if !trait_block
+          raise ArgumentError, "Unknown trait for #{self.class}: :#{trait}"
+        end
+
+        self.instance_exec(&trait_block)
+      end
 
-      fields.each do |field_options|
+      @fields.each do |field_options|
         if field_options[:type] == ASSOCIATION_FIELD
           @packers ||= {}
-          @packers[field_options[:name]] = field_options[:packer].new
+          @packers[field_options[:name]] =
+            field_options[:packer].new(*field_options[:packer_traits])
         end
       end
     end
@@ -177,7 +224,7 @@ module Sequel
     def pack_model(model)
       h = {}
 
-      fields.each do |field_options|
+      @fields.each do |field_options|
         field_name = field_options[:name]
 
         case field_options[:type]
@@ -193,7 +240,7 @@ module Sequel
           elsif associated_objects.is_a?(Array)
             h[field_name] = @packers[field_name].pack_models(associated_objects)
           else
-            @packers[field_name].pack_model(associated_objects)
+            h[field_name] = @packers[field_name].pack_model(associated_objects)
           end
         when ARBITRARY_MODIFICATION_FIELD
           field_options[:block].call(model, h)
@@ -209,10 +256,31 @@ module Sequel
 
     private
 
-    def fields
+    def field(field_name=nil, packer_class=nil, *traits, &block)
+      klass = self.class
+      klass.send(
+        :validate_field_args, field_name, packer_class, *traits, &block)
+      field_type =
+        klass.send(:determine_field_type, field_name, packer_class, &block)
+
+      @fields << {
+        type: field_type,
+        name: field_name,
+        packer: packer_class,
+        packer_traits: traits,
+        block: block,
+      }
+    end
+
+    def packer_fields
       self.class.instance_variable_get(:@fields)
     end
+
+    def trait_blocks
+      self.class.instance_variable_get(:@traits)
+    end
   end
 end
 
 require "sequel/packer/version"
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequel-packer
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Paul Julius Martinez
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-05-11 00:00:00.000000000 Z
+date: 2020-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel