panko_serializer 0.8.4 → 1.0.0

data/benchmarks/sanity.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "benchmarking_support"
-require_relative "app"
-require_relative "setup"
-
-class PostWithAliasModel < ActiveRecord::Base
-  self.table_name = "posts"
-
-  alias_attribute :new_id, :id
-  alias_attribute :new_body, :body
-  alias_attribute :new_title, :title
-  alias_attribute :new_author_id, :author_id
-  alias_attribute :new_created_at, :created_at
-end
-
-class PostWithAliasFastSerializer < Panko::Serializer
-  attributes :new_id, :new_body, :new_title, :new_author_id, :new_created_at
-end
-
-def benchmark_aliased(prefix, serializer, options = {})
-  posts = PostWithAliasModel.all.to_a
-  posts_50 = posts.first(50).to_a
-
-  merged_options = options.merge(each_serializer: serializer)
-
-  Benchmark.run("Panko_#{prefix}_PostWithAliasModels_#{posts.count}") do
-    Panko::ArraySerializer.new(posts, merged_options).to_json
-  end
-
-  Benchmark.run("Panko_#{prefix}_Posts_50") do
-    Panko::ArraySerializer.new(posts_50, merged_options).to_json
-  end
-end
-
-class AuthorFastSerializer < Panko::Serializer
-  attributes :id, :name
-end
-
-class PostFastSerializer < Panko::Serializer
-  attributes :id, :body, :title, :author_id, :created_at
-end
-
-class PostFastWithMethodCallSerializer < Panko::Serializer
-  attributes :id, :body, :title, :author_id, :created_at, :method_call
-
-  def method_call
-    object.id
-  end
-end
-
-class PostWithHasOneFastSerializer < Panko::Serializer
-  attributes :id, :body, :title, :author_id, :created_at
-
-  has_one :author, serializer: AuthorFastSerializer
-end
-
-class AuthorWithHasManyFastSerializer < Panko::Serializer
-  attributes :id, :name
-
-  has_many :posts, serializer: PostFastSerializer
-end
-
-def benchmark(prefix, serializer, options = {})
-  posts = Benchmark.data[:all]
-
-  merged_options = options.merge(each_serializer: serializer)
-
-  Benchmark.run("Panko_#{prefix}_Posts_#{posts.count}") do
-    Panko::ArraySerializer.new(posts, merged_options).to_json
-  end
-
-  posts_50 = Benchmark.data[:small]
-
-  Benchmark.run("Panko_#{prefix}_Posts_50") do
-    Panko::ArraySerializer.new(posts_50, merged_options).to_json
-  end
-end
-
-benchmark "Simple", PostFastSerializer
-benchmark "HasOne", PostWithHasOneFastSerializer
-benchmark "SimpleWithMethodCall", PostFastWithMethodCallSerializer
-benchmark_aliased "Simple (aliased)", PostWithAliasFastSerializer

data/benchmarks/setup.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-###########################################
-# Setup active record models
-##########################################
-require "active_record"
-require "sqlite3"
-require "securerandom"
-
-# Change the following to reflect your database settings
-ActiveRecord::Base.establish_connection(
-  adapter: "sqlite3",
-  database: ":memory:"
-)
-
-# Don't show migration output when constructing fake db
-ActiveRecord::Migration.verbose = false
-
-ActiveRecord::Schema.define do
-  create_table :authors, force: true do |t|
-    t.string :name
-    t.timestamps(null: false)
-  end
-
-  create_table :posts, force: true do |t|
-    t.text :body
-    t.string :title
-    t.references :author
-    t.json :data
-    t.timestamps(null: false)
-  end
-end
-
-class Author < ActiveRecord::Base
-  has_one :profile
-  has_many :posts
-end
-
-class Post < ActiveRecord::Base
-  belongs_to :author
-end
-
-Post.destroy_all
-Author.destroy_all
-
-# Build out the data to serialize
-Post.transaction do
-  ENV.fetch("ITEMS_COUNT", "2300").to_i.times do
-    Post.create(
-      body: SecureRandom.hex(30),
-      title: SecureRandom.hex(20),
-      author: Author.create(name: SecureRandom.alphanumeric),
-      data: {a: 1, b: 2, c: 3}
-    )
-  end
-end

data/benchmarks/type_casts/bm_active_record.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "support"
-
-def ar_type_convert(type_klass, from, to)
-  converter = type_klass.new
-
-  assert type_klass.name, converter.deserialize(from), to
-
-  Benchmark.run("#{type_klass.name}_TypeCast") do
-    converter.deserialize(from)
-  end
-
-  Benchmark.run("#{type_klass.name}_NoTypeCast") do
-    converter.deserialize(to)
-  end
-end
-
-def utc_ar_time
-  date = DateTime.new(2017, 3, 4, 12, 45, 23)
-  tz = ActiveSupport::TimeZone.new("UTC")
-  from = date.in_time_zone(tz).iso8601
-
-  type = ActiveRecord::ConnectionAdapters::PostgreSQL::OID::DateTime.new
-  converter = ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter.new(type)
-
-  Benchmark.run("#{tz}_#{type.class.name}_TypeCast") do
-    converter.deserialize(from).iso8601
-  end
-end
-
-def db_ar_time
-  type = ActiveRecord::ConnectionAdapters::PostgreSQL::OID::DateTime.new
-  converter = ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter.new(type)
-
-  from = "2017-07-10 09:26:40.937392"
-
-  Benchmark.run("ActiveRecord_Time_TypeCast_WithISO8601") do
-    converter.deserialize(from).iso8601
-  end
-end
-
-ar_type_convert ActiveRecord::Type::String, 1, "1"
-ar_type_convert ActiveRecord::Type::Text, 1, "1"
-ar_type_convert ActiveRecord::Type::Integer, "1", 1
-ar_type_convert ActiveRecord::Type::Float, "1.23", 1.23
-ar_type_convert ActiveRecord::Type::Boolean, "true", true
-ar_type_convert ActiveRecord::Type::Boolean, "t", true
-
-if check_if_exists "ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Json"
-  ar_type_convert ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Json, '{"a":1}', {a: 1}
-end
-if check_if_exists "ActiveRecord::Type::Json"
-  ar_type_convert ActiveRecord::Type::Json, '{"a":1}', {a: 1}
-end
-
-db_ar_time
-utc_ar_time

data/benchmarks/type_casts/bm_panko.rb

@@ -1,65 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "support"
-
-def panko_type_convert(type_klass, from, to)
-  converter = type_klass.new
-  assert type_klass.name.to_s, Panko._type_cast(converter, from), to
-
-  Benchmark.run("#{type_klass.name}_TypeCast") do
-    Panko._type_cast(converter, from)
-  end
-
-  Benchmark.run("#{type_klass.name}_NoTypeCast") do
-    Panko._type_cast(converter, to)
-  end
-end
-
-def utc_panko_time
-  date = DateTime.new(2017, 3, 4, 12, 45, 23)
-  tz = ActiveSupport::TimeZone.new("UTC")
-  from = date.in_time_zone(tz).iso8601
-
-  type = ActiveRecord::ConnectionAdapters::PostgreSQL::OID::DateTime.new
-  converter = ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter.new(type)
-
-  to = Panko._type_cast(converter, from)
-
-  Benchmark.run("#{tz}_#{type.class.name}_TypeCast") do
-    Panko._type_cast(converter, from)
-  end
-
-  Benchmark.run("#{tz}_#{type.class.name}_NoTypeCast") do
-    Panko._type_cast(converter, to)
-  end
-end
-
-def db_panko_time
-  type = ActiveRecord::ConnectionAdapters::PostgreSQL::OID::DateTime.new
-  converter = ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter.new(type)
-
-  from = "2017-07-10 09:26:40.937392"
-
-  Benchmark.run("Panko_Time_TypeCast") do
-    Panko._type_cast(converter, from)
-  end
-end
-
-panko_type_convert ActiveRecord::Type::String, 1, "1"
-panko_type_convert ActiveRecord::Type::Text, 1, "1"
-panko_type_convert ActiveRecord::Type::Integer, "1", 1
-panko_type_convert ActiveRecord::Type::Float, "1.23", 1.23
-panko_type_convert ActiveRecord::Type::Boolean, "true", true
-panko_type_convert ActiveRecord::Type::Boolean, "t", true
-
-if check_if_exists "ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Json"
-  panko_type_convert ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Json, '{"a":1}', '{"a":1}'
-end
-if check_if_exists "ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Jsonb"
-  panko_type_convert ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Jsonb, '{"a":1}', '{"a":1}'
-end
-if check_if_exists "ActiveRecord::Type::Json"
-  panko_type_convert ActiveRecord::Type::Json, '{"a":1}', '{"a":1}'
-end
-db_panko_time
-utc_panko_time

data/benchmarks/type_casts/support.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-require "active_record"
-require "active_record/connection_adapters/postgresql_adapter"
-require "active_model"
-require "active_support/all"
-require "pg"
-require "oj"
-
-require_relative "../benchmarking_support"
-require_relative "../../lib/panko_serializer"
-
-def assert(type_name, from, to)
-  raise "#{type_name} - #{from.class} is not equals to #{to.class}" unless from.to_json == to.to_json
-end
-
-def check_if_exists(module_name)
-  mod = begin
-    module_name.constantize
-  rescue
-    nil
-  end
-  return true if mod
-  false unless mod
-end
-
-Time.zone = "UTC"

data/docs/docs/associations.md

@@ -1,107 +0,0 @@
----
-id: associations
-title: Associations
-sidebar_label: Associations
----
-A serializer can define it's own associations - both `has_many` and `has_one` to serialize under the context of the object.
-
-For example:
-
-```ruby
-
-class PostSerializer < Panko::Serializer
-  attributes :title, :body
-
-  has_one :author, serializer: AuthorSerializer
-  has_many :comments, each_serializer: CommentSerializer
-end
-
-```
-
-### Associations with aliases
-
-An association key name can be aliased with the `name` option.
-
-For example:
-the `actual_author` property will be converted to `alias_author`.
-
-```ruby
-
-class PostSerializer < Panko::Serializer
-  attributes :title, :body
-
-  has_one :actual_author, serializer: AuthorSerializer, name: :alias_author
-  has_many :comments, each_serializer: CommentSerializer
-end
-
-```
-
-### Inference
-
-Panko can find the type of the serializer by looking at the relationship name, so instead of specifying
-the serializer at the above example, we can:
-
-```ruby
-
-class PostSerializer < Panko::Serializer
-  attributes :title, :body
-
-  has_one :author
-  has_many :comments
-end
-
-```
-
-The logic of inferencing is:
-
--   Take the name of the relationship (for example - `:author` / `:comments`) singularize and camelize it.
--   Look for const defined with the name above and "Serializer" suffix (by using `Object.const_get`).
-
-&gt; If Panko can't find the serializer it will throw an error on startup time, for example: `Can't find serializer for PostSerializer.author has_one relationship`.
-
-## Nested Filters
-
-As talked before, Panko allows you to filter the attributes of a serializer.
-But Panko lets you take that step further, and filters the attributes of you associations so you can re-use your serializers in your application.
-
-For example, let's say one portion of the application needs to serialize a list of posts but only with their - `title`, `body`, author's id and comments id.
-
-We can declare tailored serializer for this, or we can re-use the above defined serializer - `PostSerializer` and use nested filters.
-
-```ruby
-
-posts = Post.all
-
-Panko::ArraySerializer.new(posts, each_serializer: PostSerializer, only: {
-  instance: [:title, :body, :author, :comments],
-  author: [:id],
-  comments: [:id],
-})
-
-```
-
-Let's dissect the `only` option we passed:
-
--   `instance` - list of attributes (and associations) we want to serialize for the current instance of the serializer, in this case - `PostSerializer`.
--   `author`, `comments` - here we specify the list of attributes we want to serialize for each association.
-
-It's important to note that Nested Filters are recursive, in other words, we can filter the association's associations.
-
-For example, `CommentSerializer` has an `has_one` association `Author`, and for each `comments.author` we can only serialize it's name.
-
-```ruby
-
-posts = Post.all
-
-Panko::ArraySerializer.new(posts, only: {
-  instance: [:title, :body, :author, :comments],
-  author: [:id],
-  comments: {
-    instance: [:id, :author],
-    author: [:name]
-  }
-})
-
-```
-
-As you see now in `comments` the `instance` have different meaning, the `CommentSerializer`.

data/docs/docs/attributes.md

@@ -1,150 +0,0 @@
----
-id: attributes
-title: Attributes
-sidebar_label: Attributes
----
-Attributes allow you to specify which record attributes you want to serialize.
-
-There are two types of attributes:
-
--   Field - simple columns defined on the record it self.
--   Virtual/Method - this allows to include properties beyond simple fields.
-
-```ruby
-
-class UserSerializer < Panko::Serializer
-  attributes :full_name
-
-  def full_name
-    "#{object.first_name} #{object.last_name}"
-   end
-end
-
-```
-
-## Field Attributes
-
-Using field attributes you can control which columns of the given ActiveRecord object you want to serialize.
-
-Instead of relying on ActiveRecord to do it's type casting, Panko does on it's own for performance reasons (read more in [Design Choices](design-choices.md#type-casting)).
-
-## Method Attributes
-
-Method attributes are used when your serialized values can be derived from the object you are serializing.
-
-The serializer's attribute methods can access the object being serialized as `object`:
-
-```ruby
-
-class PostSerializer < Panko::Serializer
-  attributes :author_name
-
-  def author_name
-    "#{object.author.first_name} #{object.author.last_name}"
-  end
-end
-
-```
-
-Another useful thing you can pass your serializer is `context`, a `context` is a bag of data whom your serializer may need.
-
-For example, here we will pass feature flags:
-
-```ruby
-
-class UserSerializer < Panko::Serializer
-  attributes :id, :email
-
-  def feature_flags
-    context[:feature_flags]
-  end
-end
-
-serializer = UserSerializer.new(context: {
-  feature_flags: FeatureFlags.all
-})
-
-serializer.serialize(User.first)
-
-```
-
-## Filters
-
-Filters allows us to reduce the amount of attributes we can serialize, therefore reduce the data usage & performance of serializing.
-
-There are two types of filters:
-
--   only - use those attributes **only** and nothing else.
--   except - all attributes **except** those attributes.
-
-Usage example:
-
-```ruby
-
-class UserSerializer < Panko::Serializer
-  attributes :id, :name, :email
-end
-
-# this line will return { 'name': '..' }
-UserSerializer.new(only: [:name]).serialize(User.first)
-
-# this line will return { 'id': '..', 'email': ... }
-UserSerializer.new(except: [:name]).serialize(User.first)
-
-```
-
-&gt; **Note** that if you want to user filter on an associations, the `:name` property is not taken into account.
-If you have a `has_many :state_transitions, name: :history` association defined, the key to use in filters is 
-`:state_transitions` (e.g. `{ except: [:state_transitions] }`).
-
-## Filters For
-
-Sometimes you find yourself having the same filtering logic in actions. In order to
-solve this duplication, Panko allows you to write the filters in the serializer.
-
-```ruby
-
-class UserSerializer < Panko::Serializer
-  attributes :id, :name, :email
-
-  def self.filters_for(context, scope)
-    {
-      only: [:name]
-    }
-  end
-end
-
-# this line will return { 'name': '..' }
-UserSerializer.serialize(User.first)
-
-```
-
-&gt; See discussion in: [https:](https://github.com/yosiat/panko_serializer/issues/16)
-
-## Aliases
-
-Let's say we have an attribute name that we want to expose to client as different name, the current way of doing so is using method attribute, for example:
-
-```ruby
-
-class PostSerializer < Panko::Serializer
-  attributes :published_at
-
-  def published_at
-    object.created_at
-  end
-end
-
-```
-
-The downside of this approach is that `created_at` skips Panko's type casting, therefore we get a direct hit on performance.
-
-To fix this, we can use aliases:
-
-```ruby
-
-class PostSerializer < Panko::Serializer
-  aliases created_at: :published_at
-end
-
-```

data/docs/docs/design-choices.md

@@ -1,127 +0,0 @@
----
-id: design-choices
-title: Design Choices
-sidebar_label: Design Choices
----
-In short, Panko is a serializer for ActiveRecord objects (it can't serialize any other object), which strives for high performance & simple API (which is inspired by ActiveModelSerializers).
-
-Its performance is achieved by:
-
--   `Oj::StringWriter` - I will elaborate later.
--   Type casting — instead of relying on ActiveRecord to do its type cast, Panko is doing it by itself.
--   Figuring out the metadata, ahead of time — therefore, we ask less questions during the `serialization loop`.
-
-## Serialization overview
-
-First, let's start with an overview. Let's say we want to serialize an `User` object, which has
-`first_name`, `last_name`, `age`, and `email` properties.
-
-The serializer definition will be something like this:
-
-```ruby
-
-class UserSerializer < Panko::Serializer
-  attributes :name, :age, :email
-  
-  def name
-    "#{object.first_name} #{object.last_name}"
-  end
-end
-
-```
-
-And the usage of this serializer will be:
-
-```ruby
-
-# fetch user from database
-user = User.first
-
-# create serializer, with empty options
-serializer = UserSerializer.new
-
-# serialize to JSON
-serializer.serialize_to_json(user)
-
-```
-
-Let's go over the steps that Panko will execute behind the scenes for this flow.
-_I will skip the serializer definition part, because it's fairly simple and straightforward (see `lib/panko/serializer.rb`)._
-
-First step, while initializing the UserSerializer, we will create a **Serialization Descriptor** for this class.
-Serialization Descriptor's goal is to answer those questions:
-
--   Which fields do we have? In our case, `:age`, `:email`.
--   Which method fields do we have? In our case `:name`.
--   Which associations do we have (and their serialization descriptors)?
-
-The serialization description is also responsible for filtering the attributes (`only` \\ `except`).
-
-Now, that we have the serialization descriptor, we are finished with the Ruby part of Panko, and all we did here is done in _initialization time_ and now we move to C code.
-
-In C land, we take the `user` object and the serialization descriptor, and start the serialization process which is separated to 4 parts:
-
--   Serializing Fields - looping through serialization descriptor's `fields` and read them from the ActiveRecord object (see `Type Casting`) and write them to the writer.
--   Serializing Method Fields - creating (a cached) serializer instance, setting its `@object` and `@context`, calling all the method fields and writing them to the writer.
--   Serializing associations — this is simple, once we have fields + method fields, we just repeat the process.
-
-Once this is finished, we have a nice JSON string.
-Now let's dig deeper.
-
-## Interesting parts
-
-### Oj::StringWriter
-
-If you read the code of ActiveRecord serialization code in Ruby, you will observe this flow:
-
-1.  Get an array of ActiveRecord objects (`User.all` for example).
-2.  Build a new array of hashes where each hash is an `User` with the attributes we selected.
-3.  The JSON serializer, takes this array of hashes and loop them, and converts it to a JSON string.
-
-This entire process is expensive in terms of Memory & CPU, and this where the combination of Panko and Oj::StringWriter really shines. 
-
-In Panko, the serialization process of the above is:
-
-1.  Get an array of ActiveRecord objects (`User.all` for example).
-2.  Create `Oj::StringWriter` and feed the values to it, via `push_value` / `push_object` / `push_object` and behind the scene, `Oj::StringWriter` will serialize the objects incrementally into a string.
-3.  Get from `Oj::StringWriter` the completed JSON string — which is a no-op, since `Oj::StringWriter` already built the string.
-
-### Figuring out the metadata, ahead of time.
-
-Another observation I noticed in the Ruby serializers is that they ask and do a lot in a serialization loop: 
-
--   Is this field a method? is it a property?
--   Which fields and associations do I need for the serializer to consider the `only` and `except` options?
--   What is the serializer of this has_one association?
-
-Panko tries to ask the bare minimum in serialization by building `Serialization Descriptor` for each serialization and caching it.
-
-The Serialization Descriptor will do the filtering of `only` and `except` and will check if a field is a method or not (therefore Panko doesn't have list of `attributes`).
-
-### Type Casting
-
-This is the final part, which helped yield most of the performance improvements.
-In ActiveRecord, when we read the value of an attribute, it does type casting of the DB value to its real Ruby type.
-
-For example, time strings are converted to Time objects, Strings are duplicated, and Integers are converted from their values to Number.
-
-This type casting is really expensive, as it's responsible for most of the allocations in the serialization flow and most of them can be "relaxed".
-
-If we think about it, we don't need to duplicate strings or convert time strings to time objects or even parse JSON strings for the JSON serialization process.
-
-What Panko does is that if we have ActiveRecord type string, we won't duplicate it.
-If we have an integer string value, we will convert it to an integer, and the same goes for other types.
-
-All of these conversions are done in C, which of course yields a big performance improvement.
-
-#### Time type casting
-
-While you read Panko source code, you will encounter the time type casting and immediately you will have a "WTF?" moment.
-
-The idea behind the time type casting code relies on the end result of JSON type casting — what we need in order to serialize Time to JSON? UTC ISO8601 time format representation.
-
-The time type casting works as follows:
-
--   If it's a string that ends with `Z`, and the strings matches the UTC ISO8601 regex, then we just return the string.
--   If it's a string and it doesn't follow the rules above, we check if it's a timestamp in database format and convert it via regex + string concat to UTC ISO8601 - Yes, there is huge assumption here, that the database returns UTC timestamps — this will be configurable (before Panko official release).
--   If it's none of the above, I will let ActiveRecord type casting do it's magic.