sequel-packer 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd29eb07b27fb23e4f4ccf1e9cefc38c608ffea0bc6b6a1757cd240cdb5c58cd
-  data.tar.gz: b2581d4f789fa3db36a80bcf2b11918ec5ce88d4249901e345b72f5a17ff4f28
+  metadata.gz: 248126ba630e1d763f32e911c992b296cd32b5201503a67296bbb18fa4000679
+  data.tar.gz: abecaa06c7e4d64eef3e4b91be2311cd2921e966062fd03fc5a5d590604c6b92
 SHA512:
-  metadata.gz: 06edeac19dd43963ae1711d58f4f77a49e914841a4e108fae027de088263c07609b90cf2fec5cd6284b1fa999d71fb38bd452922fd11654b27097ea4ad8c71a0
-  data.tar.gz: 388fae9fad1bed49c71697be1f862be334ee4d27229f15a24f1d177fe5e8e36887b8fbfffdefbc64a3d526bb71fb5b79bc4b9d503fac3c979247006f82075d84
+  metadata.gz: 0231fbedf7d8d7ccd77093e00617bf15688ed57e52d169876780854023e3c6c758dd34d002d89952795291a8c1f5c7ef398f7f24543cf686be85e496059a5f58
+  data.tar.gz: da6163737a56d4a96205ff0c26ce9ece0b90b2763c1fe271b899d3b55261bc67cf36ea35d4e75cdac540c81fd587618fbb0272691bbd86fcca0375e712d31809

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+### 0.0.2 (2020-05-11)
+
+* Added 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
+  `Sequel::Packer.field(association, packer_class)`
+* Update README with usage instructions and basic API reference.
+
 ### 0.0.1 (2020-05-10)
 
 * Most basic functionality for serializing single fields

data/README.md

@@ -1,8 +1,6 @@
 # Sequel::Packer
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sequel/packer`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+A Ruby serialization library to be used with the Sequel ORM.
 
 ## Installation
 
@@ -22,19 +20,232 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Suppose we have the following basic database schema:
+
+```ruby
+DB.create_table(:users) do
+  primary_key :id
+  String :name
+end
+
+DB.create_table(:posts) do
+  primary_key :id
+  foreign_key :author_id, :users
+  String :title
+  String :content
+end
+
+DB.create_table(:comments) do
+  primary_key :id
+  foreign_key :author_id, :users
+  foreign_key :post_id, :posts
+  String :content
+end
+
+class User < Sequel::Model(:users); end
+class Post < Sequel::Model(:posts); end
+class Comment < Sequel::Model(:comments)
+  many_to_one :author, key: :author_id, class: :User
+end
+```
+
+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:
+
+```ruby
+recent_comments = Comment
+  .where(author_id: user_id)
+  .order(:id.desc)
+  .limit(10)
+```
+
+We can define a Packer class to serialize just fields we want to, using a
+custom DSL:
+
+```ruby
+class CommentPacker < Sequel::Packer
+  model Comment
+
+  field :id
+  field :content
+end
+```
+
+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..."},
+]
+```
+
+In another context, suppose that we want to fetch the comments on a post along
+with the authors of those comments.
+
+In this case we could define two separate Packers, one for Users, and another
+for Comments:
+
+```ruby
+class UserPacker < Sequel::Packer
+  model User
+
+  field :id
+  field :name
+end
+
+class CommentWithAuthorPacker < Sequel::Packer
+  model Comment
+
+  field :id
+  field :content
+  field :author, UserPacker
+end
+```
+
+When we use this, we get:
+
+```ruby
+comments_on_post = Comment.where(post_id: post.id)
+CommentWithAuthorPacker.new.pack(comments_on_post)
+=> [
+  {
+    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"},
+  },
+  ...
+]
+```
+
+See the API Reference below for the exact API.
+
+## API Reference
+
+Custom packers are written by creating subclasses of `Sequel::Packer`. This
+class defines a DSL for declaring how a Sequel Model will be converted into a
+plain Ruby hash.
+
+### `self.model(sequel_model_class)`
+
+The beginning of each Packer class must begin with `model MySequelModel`, which
+specifies which Sequel Model this Packer class will serialize. This is mostly
+to catch certain errors at load time, rather than at run time.
+
+### `self.field(column_name)` (or `self.field(method_name)`)
+
+Defining the shape of the outputted data is done using the `field` method, which
+exists in four different variants. This first variant is the simplest. It simply
+fetches the value of the column from the model and stores it in the outputted
+hash under a key of the same name. Essentially `field :my_column` eventually
+results in `hash[:my_column] = model.my_column`.
+
+Sequel Models define accessor methods for each column in the underlying table,
+so technically underneath the hood Packer is actually calling the sending the
+method `column_name` to the model: `hash[:my_column] = model.send(:my_column)`.
+
+This means that the result of any method can be serialized using
+`field :method_name`. For example, suppose a User model has a `first_name` and
+`last_name` column, and a helper method `full_name`:
+
+```ruby
+class User < Sequel::Model(:users)
+  def full_name
+    "#{first_name} #{last_name}"
+  end
+end
+```
+
+Then when `User.create(first_name: "Paul", last_name: "Martinez")` gets packed
+with `field :full_name` specified, the outputted hash will contain
+`full_name: "Paul Martinez"`.
+
+### `self.field(key, &block)`
+
+A block can be passed to `field` to perform arbitrary computation and store the
+result under the specified `key`. The block will be passed the model as a single
+argument. Use this to call methods on the model that may take additional
+arguments, or to "rename" a column.
+
+Examples:
+
+```ruby
+class MyPacker < Sequel::Packer
+  model MyModel
+
+  field :friendly_public_name do |model|
+    model.unfriendly_internal_name
+  end
+
+  # Shorthand for above
+  field :friendly_public_name, &:unfriendly_internal_name
+
+  field :foo do |model|
+    model.bar(baz, quux)
+  end
+end
+```
+
+### `self.field(association, packer_class)
+
+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:
+
+```ruby
+field :association do |model|
+  packer_class.new.pack(model.association_dataset)
+end
+```
+
+Though this version of course would result in many more queries to the database,
+which are not required when using the shorthand form.
+
+### `self.field(&block)`
+
+Passing a block but no `key` to `field` allows for arbitrary manipulation of the
+packed hash. The block will be passed the model and the partially packed hash.
+One potential usage is for dynamic keys that cannot be determined at load time,
+but otherwise it's meant as a general escape hatch.
+
+```ruby
+field do |model, hash|
+  hash[model.compute_dynamic_key] = model.dynamic_value
+end
+```
+
+### `pack(dataset)`
+
+After creating a new instance of a Packer class, call `packer.pack(dataset)` to
+materialize a dataset and convert it to an array of packed Ruby hashes.
 
 ## 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.
+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.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sequel-packer.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/PaulJuliusMartinez/sequel-packer.
 
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/lib/sequel/packer/version.rb

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

data/lib/sequel/packer.rb

@@ -1,25 +1,216 @@
 module Sequel
   class Packer
+    # For invalid arguments provided to the field class method.
+    class FieldArgumentError < ArgumentError; end
+    # Must declare a model with `model MyModel` before calling field.
+    class ModelNotYetDeclaredError < StandardError; end
+
     def self.inherited(subclass)
       subclass.instance_variable_set(:@fields, [])
     end
 
-    def self.field(field_name)
-      @fields << field_name
+    def self.model(klass)
+      if !(klass < Sequel::Model)
+        fail(
+          ArgumentError,
+          'model declaration must be a subclass of Sequel::Model',
+        )
+      end
+
+      fail ArgumentError, 'model already declared' if @model
+
+      @model = klass
     end
 
-    def fields
-      self.class.instance_variable_get(:@fields)
+    # field(:foo)
+    METHOD_FIELD = :method_field
+    # field(:foo, &block)
+    BLOCK_FIELD = :block_field
+    # field(:association, packer_class)
+    ASSOCIATION_FIELD = :association_field
+    # field(&block)
+    ARBITRARY_MODIFICATION_FIELD = :arbitrary_modification_field
+
+    def self.field(field_name=nil, packer_class=nil, &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
+          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
+          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
+        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
+
+      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,
+      }
+    end
+
+    def initialize
+      @packers = nil
+
+      fields.each do |field_options|
+        if field_options[:type] == ASSOCIATION_FIELD
+          @packers ||= {}
+          @packers[field_options[:name]] = field_options[:packer].new
+        end
+      end
     end
 
     def pack(dataset)
-      dataset.map do |model|
-        h = {}
-        fields.each do |field_name|
+      models = dataset.all
+      pack_models(models)
+    end
+
+    def pack_model(model)
+      h = {}
+
+      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)
+        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
+            @packers[field_name].pack_model(associated_objects)
+          end
+        when ARBITRARY_MODIFICATION_FIELD
+          field_options[:block].call(model, h)
         end
-        h
       end
+
+      h
+    end
+
+    def pack_models(models)
+      models.map {|m| pack_model(m)}
+    end
+
+    private
+
+    def fields
+      self.class.instance_variable_get(:@fields)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel-packer
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Paul Julius Martinez