sequel-packer 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 811c7b7319fa09e9885726f132a84e52d8944746288be9331c7d9ac83408537f
-  data.tar.gz: 4a11f786524e3576470b744068fcd7735271743a79bc6874755f0e7e2eadf09a
+  metadata.gz: fa3f2c4a293512f8a86e4acaf01c77e0554a42eb5f8847a6c33bfe8bff03330b
+  data.tar.gz: 8abeec112ff65793ced679bbf1f7aa370c9f3f6f08bdb63b1d5adb7cfc259833
 SHA512:
-  metadata.gz: 608fc72d310784fe7b8edbe0fcc196b3207f4ed652e33fa4d3625864eb6ffaebc9a4b5291046bad92f620b85b7bd6ec1831e445f1934f8dd1b32d31d82e38643
-  data.tar.gz: 296826320aac8126a6c6f53ac3f4cac8828f87ae092428a9f346d8fea1faedcbc9c039f2e7e2ecb40f009d7e9568e75cc8ea2b93ab089ab9873e3eaa411d5ecb
+  metadata.gz: ea64c4d227fd832b232d2833ccae7948208c012cd2b890f44bed919af86c6f828dbfd28de0d925fed3e218f96837b409251bc6f9ea7e8d0ff7802da63d21313f
+  data.tar.gz: 93bd50aee1d410b117ee2c2993d85dc6c53bae5e5204b6be37d413ab160f92a120725cb6cfc6f6c00744a9c12ff1b8db30aea7f8c0593fc9a7fb3831cca258c0

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+### 0.5.0 (2020-05-17)
+
+* Add `**context` argument to `#pack` method, exposed as `@context` in blocks
+  passed to `field` and `trait`.
+* Add `::with_context(&block)`, for accessing `@context` to use in additional
+  DSL calls, or modify data fetching.
+* Update README some re-organization and table of contents.
+
 ### 0.4.0 (2020-05-17)
 
 * **_BREAKING CHANGE:_** `#pack_models` and `#pack_model` have been changed to

data/README.md

@@ -3,22 +3,128 @@
 `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,
+* **Declarative:** Define the shape of your serialized data with a simple,
   straightforward DSL.
-* *Flexible:* Certain contexts require different data. Packers provide an easy
+* **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
+* **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
+* **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
+- [Example](#example)
+  - [Getting Started](#getting-started)
+    - [Installation](#installation)
+    - [Example Schema](#example-schema)
+    - [Basic Fields](#basic-fields)
+    - [Packing Associations by Nesting Packers](#packing-associations-by-nesting-packers)
+    - [Traits](#traits)
+  - [API Reference](#api-reference)
+    - [Using a Packer](#using-a-packer)
+    - [Defining a Packer](#defining-a-packer)
+      - [`self.model(sequel_model_class)`](#selfmodelsequel_model_class)
+      - [`self.field(column_name)` (or `self.field(method_name)`)](#selffieldcolumn_name-or-selffieldmethod_name)
+      - [`self.field(key, &block)`](#selffieldkey-block)
+      - [`self.field(association, subpacker, *traits)`](#selffieldassociation-subpacker-traits)
+      - [`self.field(&block)`](#selffieldblock)
+      - [`self.trait(trait_name, &block)`](#selftraittrait_name-block)
+      - [`self.eager(*associations)`](#selfeagerassociations)
+      - [`self.set_association_packer(association, subpacker, *traits)`](#selfset_association_packerassociation-subpacker-traits)
+      - [`self.pack_association(association, models)`](#selfpack_associationassociation-models)
+      - [`self.precompute(&block)`](#selfprecomputeblock)
+    - [Context](#context)
+      - [`self.with_context(&block)`](#selfwith_contextblock)
+  - [Contributing](#contributing)
+    - [Development](#development)
+    - [Releases](#releases)
+  - [License](#license)
+
+## Example
+
+`Sequel::Packer` uses your existing `Sequel::Model` declarations and leverages
+the use of associations to efficiently serialize data.
+
+```ruby
+class User < Sequel::Model(:users)
+  one_to_many :posts
+end
+class Post < Sequel::Model(:posts); end
+```
+
+Packer definitions use a simple domain-specific language (DSL) to declare which
+fields to serialize:
+
+```ruby
+class PostPacker < Sequel::Packer
+  model Post
+
+  field :id
+  field :title
+
+  trait :truncated_content do
+    field :truncated_content do |post|
+      post.content[0..Post::PREVIEW_LENGTH]
+    end
+  end
+end
+
+class UserPacker < Sequel::Packer
+  model User
+
+  field :id
+  field :name
+
+  trait :posts do
+    field :posts, PostPacker, :truncated_content
+  end
+end
+```
+
+Once defined, Packers are easy to use; just call `.pack` and pass in a Sequel
+dataset, an array of models, or a single model, and get back Ruby hashes.
+Simply call `to_json` on the result!
+
+```ruby
+UserPacker.pack(User.dataset)
+=> [
+  {id: 1, name: 'Paul'},
+  {id: 2, name: 'Julius'},
+  ...
+]
+
+UserPacker.pack(User[1], :posts)
+=> {
+  id: 1,
+  name: 'Paul',
+  posts: [
+    {
+      id: 15,
+      title: 'Announcing Sequel::Packer!',
+      truncated_content: 'Sequel::Packer is a new gem...',
+    },
+    {
+      id: 21,
+      title: 'Postgres Internals',
+      truncated_content: 'I never quite understood autovacuum...',
+    },
+    ...
+  ],
+}
+```
+
+## Getting Started
+
+This section will explain the basic use of `Sequel::Packer`. Check out the [API
+Reference](#api-reference) for an exhaustive coverage of the API and more
+detailed documentation.
+
+### Installation
 
 Add this line to your application's Gemfile:
 
@@ -34,9 +140,9 @@ Or install it yourself as:
 
     $ gem install sequel-packer
 
-## Usage
+### Example Schema
 
-Suppose we have the following basic database schema:
+Most of the following examples will use the following database schema:
 
 ```ruby
 DB.create_table(:users) do
@@ -72,7 +178,7 @@ 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
+After validating the user id, we end up with the Sequel dataset representing the
 data we want to return:
 
 ```ruby
@@ -97,7 +203,7 @@ end
 This can then be used as follows:
 
 ```ruby
-CommentPacker.new.pack(recent_comments)
+CommentPacker.pack(recent_comments)
 => [
   {id: 536, content: "Great post, man!"},
   {id: 436, content: "lol"},
@@ -105,10 +211,10 @@ CommentPacker.new.pack(recent_comments)
 ]
 ```
 
-### Packing associations by nesting Packers
+### Packing Associations by Nesting Packers
 
 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:
+this by defining another packer for `Post` that uses the `CommentPacker`:
 
 ```ruby
 class PostPacker < Sequel::Packer
@@ -121,14 +227,15 @@ class PostPacker < Sequel::Packer
 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.
+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. The second
+argument in `field :comments, CommentPacker` tells the `PostPacker` to use the
+pack those comments using the `CommentPacker`.
 
 We can then use this as follows:
 
 ```ruby
-PostPacker.new.pack(Post.order(:id.desc).limit(1))
+PostPacker.pack(Post[validated_id])
 => [
   {
     id: 682,
@@ -158,8 +265,8 @@ 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:
+`PostPacker` instead, but then we'd have to redeclare all the other fields we
+want on a packed `Comment`:
 
 ```ruby
 class CommentWithAuthorPacker < Sequel::Packer
@@ -184,7 +291,7 @@ end
 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:
+of defining a totally new packer, we can extend the `CommentPacker` as follows:
 
 ```ruby
 class CommentPacker < Sequel::Packer
@@ -199,18 +306,18 @@ class CommentPacker < Sequel::Packer
 end
 ```
 
-To use a trait, simply pass it in when creating the packer instance:
+To use a trait, simply pass it in when calling `pack`:
 
 ```ruby
 # Without the trait
-CommentPacker.new.pack(Comment.dataset)
+CommentPacker.pack(Comment.dataset)
 => [
   {id: 536, content: "Great post, man!"},
   ...
 ]
 
 # With the trait
-CommentPacker.new(:author).pack(Comment.dataset)
+CommentPacker.pack(Comment.dataset, :author)
 => [
   {
     id: 536,
@@ -249,13 +356,64 @@ 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)`
+### Using a Packer
+
+Using a Packer is dead simple. There's a single class method:
+
+```ruby
+self.pack(data, *traits, **context)
+```
+
+`data` can be in the form of a Sequel dataset, an array of Sequel models, or
+a single Sequel model. No matter which form the data is passed in, the Packer
+class will ensure nested data is efficiently loaded.
+
+To pack additional fields defined in a trait, pass the name of the trait as an
+additional argument, e.g., `UserPacker.pack(users, :recent_posts)` to include
+recent posts with each user.
+
+Finally, additional context can be provided to the Packer by passing additional
+keyword arguments to `pack`. This context is handled opaquely by the Packer, but
+it can be accessed in the blocks passed to `field` declarations. Common uses of
+`context` include passing in the current user making a request, or passing in
+additional precomputed data.
+
+The implementation of `pack` is very simple. It creates an instance of a Packer,
+by passing in the traits and the context, then calls `pack` on that instance,
+and passes in the data:
+
+```ruby
+def self.pack(data, *traits, **context)
+  return nil if !data # small easy optimization to avoid unnecessary work
+  new(*traits, **context).pack(data)
+end
+```
+
+It simply combines a constructor and single exposed instance method:
+
+#### `initialize(*traits, **context)`
+
+#### `pack(data)`
+
+One instantiated, the same Packer could be used to pack data multiple times.
+This is unlikely to be needed, but the functionality is there.
+
+### Defining a Packer
+
+#### `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.
+to catch certain errors at load time, rather than at run time:
 
-### `self.field(column_name)` (or `self.field(method_name)`)
+```ruby
+class UserPacker < Sequel::Packer
+  model User
+  ...
+end
+```
+
+#### `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
@@ -283,7 +441,7 @@ 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)`
+#### `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
@@ -309,7 +467,7 @@ class MyPacker < Sequel::Packer
 end
 ```
 
-### `self.field(association, packer_class, *traits)`
+#### `self.field(association, subpacker, *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
@@ -317,15 +475,16 @@ multiple traits specified. A similar output could be generated by doing:
 
 ```ruby
 field :association do |model|
-  packer_class.new(*traits).pack(model.association_dataset)
+  subpacker.pack(model.association_dataset, *traits)
 end
 ```
 
-Though this version of course would result in many more queries to the database,
-which are not required when using the shorthand form, and also requires creating
-a new instance of `packer_class` for every packed model.
+This form is very inefficient though, because it would result in a new subpacker
+getting instantiated for every packed model. Additionally, unless the subpacker
+is declared up-front, the Packer won't know to eager load that association,
+potentially resulting in many unnecessary database queries.
 
-### `self.field(&block)`
+#### `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.
@@ -338,7 +497,7 @@ field do |model, hash|
 end
 ```
 
-### `self.trait(trait_name, &block)`
+#### `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
@@ -347,15 +506,19 @@ the name of the trait as an argument:
 ```ruby
 class MyPacker < Sequel::Packer
   model MyObj
+  field :id
+
   trait :my_trait do
-    field :my_optional_field
+    field :trait_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)
+# packed objects don't have trait_field
+MyPacker.pack(dataset)
+=> [{id: 1}, {id: 2}, ...]
+# packed objects do have trait_field
+MyPacker.pack(dataset, :my_trait)
+=> [{id: 1, trait_field: 'foo'}, {id: 2, trait_field: 'bar'}, ...]
 ```
 
 Traits can also be used when packing associations by passing the name of the
@@ -368,7 +531,7 @@ class MyOtherPacker < Sequel::Packer
 end
 ```
 
-### `self.eager(*associations)`
+#### `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
@@ -392,7 +555,7 @@ class UserPacker < Sequel::Packer
   end
 end
 
-UserPacker.new.pack(User.dataset)
+UserPacker.pack(User.dataset)
 => [
   {id: 123, num_posts: 7},
   {id: 456, num_posts: 3},
@@ -400,7 +563,7 @@ UserPacker.new.pack(User.dataset)
 ]
 ```
 
-This helps prevent N+1 query problems when not using Sequel's
+Using `eager` can help prevent N+1 query problems when not using Sequel's
 [`TacticalEagerLoading`](https://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/TacticalEagerLoading.html)
 plugin.
 
@@ -421,22 +584,28 @@ class UserPacker < Sequel::Packer
 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`.
+**IMPORTANT NOTE:** Eager procs are not guaranteed to be executed when passing
+in models, rather than a dataset, to `pack`. Specifically, if the models already
+have fetched the association, the Packer won't refetch it. Because of this, it's
+good practice to use `set_association_packer` and `pack_association` (see next
+section) in a `field` block and duplicate the filtering action.
+
+Also 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.
+Additionally, 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)`
+#### `self.set_association_packer(association, subpacker, *traits)`
 
 See `self.pack_association(association, models)` below.
 
-### `self.pack_association(association, models)`
+#### `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
+`self.field(association, subpacker, *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
@@ -475,7 +644,7 @@ 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
+##### 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|
@@ -483,7 +652,7 @@ field :nice_external_names do |model|
 end
 ```
 
-#### Pack a single instance of a `one_to_many` association
+##### Pack a single instance of a `one_to_many` association
 ```ruby
 class PostPacker < Sequel::Packer
   set_association_packer :comments, CommentPacker
@@ -493,7 +662,7 @@ class PostPacker < Sequel::Packer
 end
 ```
 
-### `self.precompute(&block)`
+#### `self.precompute(&block)`
 
 Occasionally packing a model may require a computation that doesn't fit in with
 the rest of the Packer paradigm. This may be a Sequel query that is particularly
@@ -532,40 +701,105 @@ class VideoUploadPacker < Sequel::Packer
 end
 ```
 
+#### Instance method versions
 
-### `initialize(*traits)`
+In addition to the class method versions of `field`, `eager`,
+`set_association_packer`, and `precompute`, there are also regular instance method
+versions which take the exact same arguments. When writing a `trait` block, the
+block is evaulated in the context of a new Packer instance and actually calls the
+instance method versions instead.
 
-When creating an instance of a Packer class, pass in any traits desired to
-specify what additional data should be packed, if any.
+### Context
 
-### `pack(dataset_or_models_or_model)`
+In addition to the data to be packed, and a set of traits, the `pack` method
+also accepts arbitrary keyword arguments. This is referred to as `context` is
+handled opaquely by the Packer. The data passed in here is saved as the
+`@context` instance variable, which is then accessible from within the blocks
+passed to `field`, `trait`, and `precompute`, for whatever purpose. It is also
+automatically passed to any nested subpackers.
 
-After creating a new instance of a Packer class, call `packer.pack` to tranform
-your data into packed Ruby hashes.
+The most common usage for context would be to pass in the current user making
+a request. It could then be used to pack permission levels about records, for
+example.
 
-`pack` can accept a dataset, an array of models, or a single model. Even when
-passing models that have already been materialized, the Packer will make sure
-to eagerly load any nested associations needed for packing. When passed a
-dataset or an array of models, `pack` will return an array of hashes, and when
-passed just a single model, it will return a single hash.
+```ruby
+class PostPacker < Sequel::Packer
+  model Post
 
-## Development
+  eager :permissions
+  field :access_level do |post|
+    user_permission = post.permissions.find do |perm|
+      perm.user_id == @context[:user].id
+    end
 
-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.
+    user_permission.access_level
+  end
+end
+```
 
-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).
+You might notice something inefficient about the above code. Even though we only
+want to look at the user's permission record, we fetch ALL of the permission
+records for each Post. Ideally we would filter the `permissions` association
+dataset when we call `eager`, but we don't have access to `@context` at that
+point. This leads to the final DSL method available when writing a Packer:
+
+#### `self.with_context(&block)`
+
+You can pass a block to `with_context` that will be executed as soon as a Packer
+instance is constructed. The block can access `@context` and can also call the
+standard Packer DSL methods, `field`, `eager`, etc.
+
+The above example could then be made more efficient as follows:
+
+```ruby
+class PostPacker < Sequel::Packer
+  model Post
+
+- eager :permissions
++ with_context do
++   eager permissions: (proc {|ds| ds.where(user_id: @context[:user].id)})
++ end
+end
+```
+
+A very tricky usage of `with_context` (and not recommended...) would be to
+control the traits used on subpackers:
+
+```ruby
+class UserPacker < Sequel::Packer
+  model User
+
+  with_context do
+    field :comments, CommentPacker, *@context[:comment_traits]
+  end
+end
+
+UserPacker.pack(User.dataset, comment_traits: [])
+=> [{comments: [{id: 7}, ...]}]
+UserPacker.pack(User.dataset, comment_traits: [:author])
+=> [{comments: [{id: 7, author: {id: 1, ...}}, ...]}]
+UserPacker.pack(User.dataset, comment_traits: [:num_likes])
+=> [{comments: [{id: 7, likes: 53}, ...]}]
+```
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
 https://github.com/PaulJuliusMartinez/sequel-packer.
 
+### 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.
+
+### Releases
+
+To release a new version, update the version number in
+`lib/sequel/packer/version.rb`, update the `CHANGELOG.md` with new changes, then
+run `rake release`, which 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).
 
 ## License
 

data/lib/sequel/packer.rb

@@ -9,15 +9,33 @@ module Sequel
     class AssociationDoesNotExistError < StandardError; end
     class InvalidAssociationPackerError < StandardError; end
     class UnknownTraitError < StandardError; end
+    class UnnecessaryWithContextError < StandardError; end
+    class NoAssociationSubpackerDefinedError < StandardError; end
 
+    # Think of this method as the "initialize" method for a Packer class.
+    # Every Packer class keeps track of the fields, traits, and other various
+    # operations defined using the DSL internally.
     def self.inherited(subclass)
-      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)
-      subclass.instance_variable_set(:@class_precomputations, [])
+      subclass.instance_variable_set(:@model, @model)
+      subclass.instance_variable_set(:@class_fields, @class_fields&.dup || [])
+      subclass.instance_variable_set(:@class_traits, @class_traits&.dup || {})
+      subclass.instance_variable_set(:@class_packers, @class_packers&.dup || {})
+      subclass.instance_variable_set(
+        :@class_eager_hash,
+        EagerHash.deep_dup(@class_eager_hash),
+      )
+      subclass.instance_variable_set(
+        :@class_precomputations,
+        @class_precomputations&.dup || [],
+      )
+      subclass.instance_variable_set(
+        :@class_with_contexts,
+        @class_with_contexts&.dup || [],
+      )
     end
 
+    # Declare the type of Sequel::Model this Packer will be used for. Used to
+    # validate associations at declaration time.
     def self.model(klass)
       if !(klass < Sequel::Model)
         fail(
@@ -35,18 +53,36 @@ module Sequel
     METHOD_FIELD = :method_field
     # field(:foo, &block)
     BLOCK_FIELD = :block_field
-    # field(:association, packer_class)
+    # field(:association, subpacker)
     ASSOCIATION_FIELD = :association_field
     # field(&block)
     ARBITRARY_MODIFICATION_FIELD = :arbitrary_modification_field
 
-    def self.field(field_name=nil, packer_class=nil, *traits, &block)
+    # Declare a field to be packed in the output hash. This method can be called
+    # in multiple ways:
+    #
+    # field(:field_name)
+    # - Calls the method :field_name on a model and stores the result under the
+    #   key :field_name in the packed hash.
+    #
+    # field(:field_name, &block)
+    # - Yields the model to the block and stores the result under the key
+    #   :field_name in the packed hash.
+    #
+    # field(:association, subpacker, *traits)
+    # - Packs model.association using the designated subpacker with the
+    #   specified traits.
+    #
+    # field(&block)
+    # - Yields the model and the partially packed hash to the block, allowing
+    #   for arbitrary modification of the output hash.
+    def self.field(field_name=nil, subpacker=nil, *traits, &block)
       Validation.check_field_arguments(
-        @model, field_name, packer_class, traits, &block)
-      field_type = determine_field_type(field_name, packer_class, block)
+        @model, field_name, subpacker, traits, &block)
+      field_type = determine_field_type(field_name, subpacker, block)
 
       if field_type == ASSOCIATION_FIELD
-        set_association_packer(field_name, packer_class, *traits)
+        set_association_packer(field_name, subpacker, *traits)
       end
 
       @class_fields << {
@@ -56,15 +92,10 @@ module Sequel
       }
     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
-
+    # Helper for determing a field type from the arguments to field.
     private_class_method def self.determine_field_type(
       field_name,
-      packer_class,
+      subpacker,
       block
     )
       if block
@@ -74,7 +105,7 @@ module Sequel
           ARBITRARY_MODIFICATION_FIELD
         end
       else
-        if packer_class
+        if subpacker
           ASSOCIATION_FIELD
         else
           METHOD_FIELD
@@ -82,6 +113,17 @@ module Sequel
       end
     end
 
+    # Register that nested models related to the packed model by association
+    # should be packed using the given subpacker with the specified traits.
+    def self.set_association_packer(association, subpacker, *traits)
+      Validation.check_association_packer(
+        @model, association, subpacker, traits)
+      @class_packers[association] = [subpacker, traits]
+    end
+
+    # Define a trait, a set of optional fields that can be packed in certain
+    # situations. The block can call main Packer DSL methods: field,
+    # set_association_packer, eager, or precompute.
     def self.trait(name, &block)
       if @class_traits.key?(name)
         raise ArgumentError, "Trait :#{name} already defined"
@@ -92,6 +134,14 @@ module Sequel
       @class_traits[name] = block
     end
 
+    # Specify additional eager loading that should take place when fetching data
+    # to be packed. Commonly used to add filters to association datasets via
+    # eager procs.
+    #
+    # Users should not assume when using eager procs that the proc actually gets
+    # executed. If models with their associations already loaded are passed to
+    # pack then the proc will never get processed. Any filtering logic should be
+    # duplicated within a field block.
     def self.eager(*associations)
       @class_eager_hash = EagerHash.merge!(
         @class_eager_hash,
@@ -99,6 +149,12 @@ module Sequel
       )
     end
 
+    # Declare an arbitrary operation to be performed one all the data has been
+    # fetched. The block will be executed once and be passed all of the models
+    # that will be packed by this Packer, even if this Packer is nested as a
+    # subpacker of other packers. The block can save the result of the
+    # computation in an instance variable which can then be accessed in the
+    # blocks passed to field.
     def self.precompute(&block)
       if !block
         raise ArgumentError, 'Sequel::Packer.precompute must be passed a block'
@@ -106,25 +162,55 @@ module Sequel
       @class_precomputations << block
     end
 
-    def initialize(*traits)
-      @subpackers = nil
+    # Declare a block to be called after a Packer has been initialized with
+    # context. The block can call the common Packer DSL methods. It is most
+    # commonly used to pass eager procs that depend on the Packer context to
+    # eager.
+    def self.with_context(&block)
+      if !block
+        raise ArgumentError, 'Sequel::Packer.with_context must be passed a block'
+      end
+      @class_with_contexts << block
+    end
 
-      # 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
-        @instance_precomputations = class_precomputations
-      else
-        @instance_fields = class_fields.dup
-        @instance_packers = class_packers.dup
-        @instance_eager_hash = EagerHash.deep_dup(class_eager_hash)
-        @instance_precomputations = class_precomputations.dup
+    # Pack the given data with the specified traits and additional context.
+    # Context is automatically passed down to any subpackers.
+    #
+    # Data can be provided as a Sequel::Dataset, an array of Sequel::Models, a
+    # single Sequel::Model, or nil. Even when passing models that have already
+    # been materialized, eager loading will be used to efficiently fetch
+    # associations.
+    #
+    # Returns an array of packed hashes, or a single packed hash if a single
+    # model was passed in. Returns nil if nil was passed in.
+    def self.pack(data, *traits, **context)
+      return nil if !data
+      new(*traits, **context).pack(data)
+    end
+
+    # Initialize a Packer instance with the given traits and additional context.
+    # This Packer can then pack multiple datasets or models via the pack method.
+    def initialize(*traits, **context)
+      @context = context
+
+      @subpackers = {}
+
+      # Technically we only need to duplicate these fields if we modify any of
+      # them, but manually implementing some sort of copy-on-write functionality
+      # is messy and error prone.
+      @instance_fields = class_fields.dup
+      @instance_packers = class_packers.dup
+      @instance_eager_hash = EagerHash.deep_dup(class_eager_hash)
+      @instance_precomputations = class_precomputations.dup
+
+      class_with_contexts.each do |with_context_block|
+        self.instance_exec(&with_context_block)
       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.
+      # new packers to @instance_packers, new associations to
+      # @instance_eager_hash, and/or new precomputations to
+      # @instance_precomputations.
       traits.each do |trait|
         trait_block = class_traits[trait]
         if !trait_block
@@ -135,10 +221,9 @@ module Sequel
       end
 
       # Create all the subpackers, and merge in their eager hashes.
-      @instance_packers.each do |association, (packer_class, traits)|
-        association_packer = packer_class.new(*traits)
+      @instance_packers.each do |association, (subpacker, traits)|
+        association_packer = subpacker.new(*traits, @context)
 
-        @subpackers ||= {}
         @subpackers[association] = association_packer
 
         @instance_eager_hash = EagerHash.merge!(
@@ -148,38 +233,38 @@ module Sequel
       end
     end
 
-    def pack(to_be_packed)
-      case to_be_packed
+    # Pack the given data with the traits and additional context specified when
+    # the Packer instance was created.
+    #
+    # Data can be provided as a Sequel::Dataset, an array of Sequel::Models, a
+    # single Sequel::Model, or nil. Even when passing models that have already
+    # been materialized, eager loading will be used to efficiently fetch
+    # associations.
+    #
+    # Returns an array of packed hashes, or a single packed hash if a single
+    # model was passed in. Returns nil if nil was passed in.
+    def pack(data)
+      case data
       when Sequel::Dataset
-        if @instance_eager_hash
-          to_be_packed = to_be_packed.eager(@instance_eager_hash)
-        end
-        models = to_be_packed.all
+        data = data.eager(@instance_eager_hash) if @instance_eager_hash
+        models = data.all
 
         run_precomputations(models)
         pack_models(models)
       when Sequel::Model
         if @instance_eager_hash
-          EagerLoading.eager_load(
-            class_model,
-            [to_be_packed],
-            @instance_eager_hash
-          )
+          EagerLoading.eager_load(class_model, [data], @instance_eager_hash)
         end
 
-        run_precomputations([to_be_packed])
-        pack_model(to_be_packed)
+        run_precomputations([data])
+        pack_model(data)
       when Array
         if @instance_eager_hash
-          EagerLoading.eager_load(
-            class_model,
-            to_be_packed,
-            @instance_eager_hash
-          )
+          EagerLoading.eager_load(class_model, data, @instance_eager_hash)
         end
 
-        run_precomputations(to_be_packed)
-        pack_models(to_be_packed)
+        run_precomputations(data)
+        pack_models(data)
       when NilClass
         nil
       end
@@ -187,6 +272,8 @@ module Sequel
 
     private
 
+    # Run any blocks declared using precompute on the given models, as well as
+    # any precompute blocks declared by subpackers.
     def run_precomputations(models)
       @instance_packers.each do |association, _|
         subpacker = @subpackers[association]
@@ -208,12 +295,15 @@ module Sequel
       end
     end
 
+    # Check if a Packer has any precompute blocks declared, to avoid the
+    # overhead of flattening the child associations.
     def has_precomputations?
       return true if @instance_precomputations.any?
       return false if !@subpackers
       @subpackers.values.any? {|sp| sp.send(:has_precomputations?)}
     end
 
+    # Pack a single model by processing all of the Packer's declared fields.
     def pack_model(model)
       h = {}
 
@@ -236,15 +326,25 @@ module Sequel
       h
     end
 
+    # Pack an array of models by processing all of the Packer's declared fields.
     def pack_models(models)
       models.map {|m| pack_model(m)}
     end
 
+    # Pack models from an association using the designated subpacker.
     def pack_association(association, associated_models)
       return nil if !associated_models
 
       packer = @subpackers[association]
 
+      if !packer
+        raise(
+          NoAssociationSubpackerDefinedError,
+          "pack_association called for the #{class_model}.#{association} " +
+            'association, but no Packer has been set for that association.',
+        )
+      end
+
       if associated_models.is_a?(Array)
         packer.send(:pack_models, associated_models)
       else
@@ -252,16 +352,19 @@ module Sequel
       end
     end
 
-    def field(field_name=nil, packer_class=nil, *traits, &block)
+    # See the definition of self.field. This method accepts the exact same
+    # arguments. When fields are declared within trait blocks, this method is
+    # called rather than the class method.
+    def field(field_name=nil, subpacker=nil, *traits, &block)
       klass = self.class
 
       Validation.check_field_arguments(
-        class_model, field_name, packer_class, traits, &block)
+        class_model, field_name, subpacker, traits, &block)
       field_type =
-        klass.send(:determine_field_type, field_name, packer_class, block)
+        klass.send(:determine_field_type, field_name, subpacker, block)
 
       if field_type == ASSOCIATION_FIELD
-        set_association_packer(field_name, packer_class, *traits)
+        set_association_packer(field_name, subpacker, *traits)
       end
 
       @instance_fields << {
@@ -271,13 +374,19 @@ module Sequel
       }
     end
 
-    def set_association_packer(association, packer_class, *traits)
+    # See the definition of self.set_association_packer. This method accepts the
+    # exact same arguments. When used within a trait block, this method is
+    # called rather than the class method.
+    def set_association_packer(association, subpacker, *traits)
       Validation.check_association_packer(
-        class_model, association, packer_class, traits)
+        class_model, association, subpacker, traits)
 
-      @instance_packers[association] = [packer_class, traits]
+      @instance_packers[association] = [subpacker, traits]
     end
 
+    # See the definition of self.eager. This method accepts the exact same
+    # arguments. When used within a trait block, this method is called rather
+    # than the class method.
     def eager(*associations)
       @instance_eager_hash = EagerHash.merge!(
         @instance_eager_hash,
@@ -285,6 +394,9 @@ module Sequel
       )
     end
 
+    # See the definition of self.precompute. This method accepts the exact same
+    # arguments. When used within a trait block, this method is called rather
+    # than the class method.
     def precompute(&block)
       if !block
         raise ArgumentError, 'Sequel::Packer.precompute must be passed a block'
@@ -292,10 +404,25 @@ module Sequel
       @instance_precomputations << block
     end
 
+    # See the definition of self.with_context. This method accepts the exact
+    # same arguments. When used within a trait block, this method is called
+    # rather than the class method.
+    def with_context(&block)
+      raise(
+        UnnecessaryWithContextError,
+        'There is no need to call with_context from within a trait block; ' +
+          '@context can be accessed directly.',
+      )
+    end
+
+    # Access the internal eager hash.
     def eager_hash
       @instance_eager_hash
     end
 
+    # The following methods expose the class instance variables containing the
+    # core definition of the Packer.
+
     def class_model
       self.class.instance_variable_get(:@model)
     end
@@ -319,6 +446,10 @@ module Sequel
     def class_precomputations
       self.class.instance_variable_get(:@class_precomputations)
     end
+
+    def class_with_contexts
+      self.class.instance_variable_get(:@class_with_contexts)
+    end
   end
 end
 

data/lib/sequel/packer/version.rb

@@ -1,5 +1,5 @@
 module Sequel
   class Packer
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

metadata

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