sequel-packer 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa3f2c4a293512f8a86e4acaf01c77e0554a42eb5f8847a6c33bfe8bff03330b
-  data.tar.gz: 8abeec112ff65793ced679bbf1f7aa370c9f3f6f08bdb63b1d5adb7cfc259833
+  metadata.gz: b3668368d8bc70c9c48aed2d48180c46caf75749eec556e4625e134534f65760
+  data.tar.gz: bcd3643f407dd675b80b5b76719ee6906b0892d8b437b0415712c81e271bdba1
 SHA512:
-  metadata.gz: ea64c4d227fd832b232d2833ccae7948208c012cd2b890f44bed919af86c6f828dbfd28de0d925fed3e218f96837b409251bc6f9ea7e8d0ff7802da63d21313f
-  data.tar.gz: 93bd50aee1d410b117ee2c2993d85dc6c53bae5e5204b6be37d413ab160f92a120725cb6cfc6f6c00744a9c12ff1b8db30aea7f8c0593fc9a7fb3831cca258c0
+  metadata.gz: 979da0d59439adbb1065cdd0a07977b7a9192842d2df8cf753ccfac306b26b92361a340536d4125c31901f7ad2d064eb4dc563ba246c8f667c7b7af2ee9937e1
+  data.tar.gz: 8e8ed34ddc5e6059253454772fe7f089e9bb662eebd4ec1d44c7d2d0699cd6cc9800d347fa1d9a82aa3dfd16606df3e7a062e6a62ec4f08e7aed72f4c6c4aab0

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+### 1.0.0 (2020-05-18)
+
+* Version 1.0.0 release! No changes since 0.5.0 except some small changes to the
+  README.
+
 ### 0.5.0 (2020-05-17)
 
 * Add `**context` argument to `#pack` method, exposed as `@context` in blocks

data/README.md

@@ -1,7 +1,7 @@
 # Sequel::Packer
 
-`Sequel::Packer` is a Ruby JSON serialization library to be used with the Sequel
-ORM offering the following features:
+`Sequel::Packer` is a Ruby serialization library to be used with the [Sequel
+ORM](https://github.com/jeremyevans/sequel) with the following qualities:
 
 * **Declarative:** Define the shape of your serialized data with a simple,
   straightforward DSL.
@@ -18,33 +18,6 @@ ORM offering the following features:
   and nested associations it needs to eager load in order to avoid any N+1 query
   issues.
 
-- [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
@@ -88,7 +61,7 @@ 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!
+From there you can simply call `to_json` on the result!
 
 ```ruby
 UserPacker.pack(User.dataset)
@@ -118,6 +91,41 @@ UserPacker.pack(User[1], :posts)
 }
 ```
 
+## Contents
+
+- [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)
+- [Potential Future Functionality](#potential-future-functionality)
+  - [Automatically Generated Type Declarations](#automatically-generated-type-declarations)
+  - [Lifecycle Hooks](#lifecycle-hooks)
+  - [Less Data Fetching](#less-data-fetching)
+  - [Other Enhancements](#other-enhancements)
+- [Contributing](#contributing)
+  - [Development](#development)
+  - [Releases](#releases)
+- [Attribution](#attribution)
+- [License](#license)
+
 ## Getting Started
 
 This section will explain the basic use of `Sequel::Packer`. Check out the [API
@@ -782,6 +790,68 @@ UserPacker.pack(User.dataset, comment_traits: [:num_likes])
 => [{comments: [{id: 7, likes: 53}, ...]}]
 ```
 
+## Potential Future Functionality
+
+The 1.0.0 version of the Packer library is flexible to support many use cases.
+That said, of course there are ways to improve it! There are three main
+improvements I can imagine adding:
+
+### Automatically Generated Type Declarations
+
+It would be fairly easy to add generate type definitions by adding arguments to
+`field`. Packers could produce [TypeScript
+interface](https://www.typescriptlang.org/docs/handbook/interfaces.html)
+declarations, and adding a simple build step to a CI pipeline could enforce type
+safety across the frontend and backend. Or they could produce
+[OpenAPI](http://spec.openapis.org/oas/v3.0.3) specifications, which could then
+be used to automatically generate clients using something like
+[Swagger](https://swagger.io/).
+
+### Lifecycle Hooks
+
+It should be fairly easy to extend the Packer library using standard Ruby
+features like subclassing, mixins, via `include`, or even monkey-patching. It
+may be beneficial to have explicit hooks for common operations however, like
+`before_fetch`, or `around_pack`. It's more likely that these hooks are needed
+for logging and tracing capabilities, than for actual functionality, so I'd
+like to see some real-world usage before committing to a specific style of
+integration.
+
+### Less Data Fetching
+
+Sequel by default fetches every column in a table, but a Packer knows (roughly)
+what data is going to be used so it could only select the columns neede for
+actual serialization, and limit how much data is actually fetched from the
+database. I haven't done any benchmarking on this, so I'm not sure how much of
+a benefit could be gained by this, but it would be interesting!
+
+This could work roughly as follows:
+
+* Start by fetching all columns that appear in simple `field(:column_name)`
+  declarations
+* Add any columns need to fetch nested associations, or to re-asscociate fetched
+  records with their "parent" models, using the `left_key` and `right_key`
+  fields of the `AssociationReflections`
+* Add a `column(*columns)` DSL method to explicitly fetch additional columns
+
+### Other Enhancements
+
+Here are some other potential enhancements, though these are less fleshed out.
+
+* Support not including a key in a hash if the associated value is nil, to
+  reduce size of outputted data.
+* Support different casing of the outputted hashes, i.e., `snake_case` vs.
+  `camelCase`.
+* Explicitly support different output formats, rather than just plain Ruby
+  hashes, such as [Protocol
+  Buffers](https://developers.google.com/protocol-buffers) or [Cap'n
+  Proto](https://capnproto.org/).
+* When using nested `precompute` blocks, the Packer has to flatten the
+  associations of a model, which may be expensive, but has not been benchmarked.
+  These flattened arrays already exist internally in Sequel when the eager
+  loading occurs, but those aren't exposed. The code in Sequel could be
+  re-implemented as part of the library to avoid re-constructing those arrays.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at
@@ -801,6 +871,13 @@ 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).
 
+## Attribution
+
+[Karthik Viswanathan](https://github.com/karthikv) designed the original API
+of the Packer library while at [Affinity](https://www.affinity.co/). This
+library is a ground up rewrite which defines a very similar API, but shares no
+code with the original implementation.
+
 ## License
 
 The gem is available as open source under the terms of the

data/lib/sequel/packer/version.rb

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

metadata

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