panko_serializer 0.8.2 → 0.8.4

data/docs/docs/associations.md

@@ -3,18 +3,19 @@ id: associations
 title: Associations
 sidebar_label: Associations
 ---
-
-A serializer can define it's own associations - both `has_many` and `has_one` to serializer under the context of the object.
+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
@@ -23,44 +24,52 @@ 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 realtionship name, so instead specifying
-the serializer at the above example, we can -
+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 aboe and "Serializer" suffix (by using `Object.const_get`)
+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`).
 
-> 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`
+&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 let you take that step further, and filters the attributes of you associations so you can re-use your serializers in your application.
+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 serializer list of posts and serializer their - `title`, `body`, author's id and comments id.
+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: {
@@ -68,17 +77,20 @@ Panko::ArraySerializer.new(posts, each_serializer: PostSerializer, only: {
   author: [:id],
   comments: [:id],
 })
+
 ```
 
-Let's dissect `only` option we passed -
-* `instance` - list of attributes (and associations) we want to serializer for 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.
+Let's dissect the `only` option we passed:
 
-It's important to note that Nested Filters, are recursive, in other words, we can filter the association's associations.
+-   `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.
 
-For example, `CommentSerializer` have has_one association `Author`, and for each `comments.author` we only it's name.
+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: {
@@ -89,6 +101,7 @@ Panko::ArraySerializer.new(posts, only: {
     author: [:name]
   }
 })
+
 ```
 
 As you see now in `comments` the `instance` have different meaning, the `CommentSerializer`.

data/docs/docs/attributes.md

@@ -3,15 +3,15 @@ id: attributes
 title: Attributes
 sidebar_label: Attributes
 ---
+Attributes allow you to specify which record attributes you want to serialize.
 
-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.
-
+-   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
 
@@ -19,22 +19,23 @@ class UserSerializer < Panko::Serializer
     "#{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 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)).
-
+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` -
+The serializer's attribute methods can access the object being serialized as `object`:
 
 ```ruby
+
 class PostSerializer < Panko::Serializer
   attributes :author_name
 
@@ -42,12 +43,15 @@ class PostSerializer < Panko::Serializer
     "#{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.
+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
 
@@ -61,6 +65,7 @@ serializer = UserSerializer.new(context: {
 })
 
 serializer.serialize(User.first)
+
 ```
 
 ## Filters
@@ -68,11 +73,14 @@ serializer.serialize(User.first)
 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
+
+-   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
@@ -82,20 +90,20 @@ UserSerializer.new(only: [:name]).serialize(User.first)
 
 # this line will return { 'id': '..', 'email': ... }
 UserSerializer.new(except: [:name]).serialize(User.first)
+
 ```
 
-> **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] }`)
+&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 have the same filtering logic in actions in order to
+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
 
@@ -108,15 +116,17 @@ end
 
 # this line will return { 'name': '..' }
 UserSerializer.serialize(User.first)
+
 ```
 
-> See discussion in: https://github.com/yosiat/panko_serializer/issues/16
+&gt; See discussion in: [https:](https://github.com/yosiat/panko_serializer/issues/16)
 
 ## Aliases
 
-Let's say we have attribute name that we want to expose to client as different name, the current way of doing so is using method attribute, for example:
+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
 
@@ -124,14 +134,17 @@ class PostSerializer < Panko::Serializer
     object.created_at
   end
 end
+
 ```
 
-The downside of this approach is that `created_at` skips Panko's type casting, therefore we get direct hit on performance.
+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 -
+To fix this, we can use aliases:
 
 ```ruby
+
 class PostSerializer < Panko::Serializer
   aliases created_at: :published_at
 end
+
 ```

data/docs/docs/design-choices.md

@@ -3,24 +3,23 @@ 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).
+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`.
-
+-   `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 overview. Let's say we want to serialize `User` object, which has
+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
   
@@ -28,11 +27,13 @@ class UserSerializer < Panko::Serializer
     "#{object.first_name} #{object.last_name}"
   end
 end
+
 ```
 
 And the usage of this serializer will be:
 
 ```ruby
+
 # fetch user from database
 user = User.first
 
@@ -41,29 +42,30 @@ 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`)_
+_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)
+-   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`).
+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.
+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.
+-   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 nice JSON string.
+Once this is finished, we have a nice JSON string.
 Now let's dig deeper.
 
 ## Interesting parts
@@ -72,37 +74,36 @@ Now let's dig deeper.
 
 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 new array of hashes where each hash is `User` with the attributes we selected
-3. The JSON serializer, takes this array of hashes and loop them, and converts it to JSON string
+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.
+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: 
+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?
+-   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`)
-
+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 a value of attribute, it does type casting of the DB value to its real ruby type.
+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 converts from their values to Number.
+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".
 
@@ -114,13 +115,13 @@ If we have an integer string value, we will convert it to an integer, and the sa
 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 configureable (before Panko official release).
-* If it's none of the above, I will let ActiveRecord type casting do it's magic.
-
+-   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.

data/docs/docs/getting-started.md

@@ -3,25 +3,27 @@ id: getting-started
 title: Getting Started
 sidebar_label: Getting Started
 ---
-
 ## Installation
 
 To install Panko, all you need is to add it to your Gemfile:
 
 ```ruby
+
 gem "panko_serializer"
+
 ```
 
 Then, install it on the command line:
 
 ```
-> bundle install
-```
 
+ bundle install
+
+```
 
 ## Creating your first serializer
 
-Let's create serializer and use it inside Rails controller.
+Let's create a serializer and use it inside of a Rails controller:
 
 ```ruby
 class PostSerializer < Panko::Serializer
@@ -37,28 +39,32 @@ end
 
 ### Serializing an object
 
-And now serialize a single object
+And now serialize a single object:
 
 ```ruby
+
 # Using Oj serializer
 PostSerializer.new.serialize_to_json(Post.first)
 
 # or, similar to #serializable_hash
 PostSerializer.new.serialize(Post.first).to_json
+
 ```
 
 ### Using the serializers in a controller
 
-As you can see, defining serializers is simple and resembles ActiveModelSerializers 0.9,
+As you can see, defining serializers is simple and resembles ActiveModelSerializers 0.9.
 To utilize the `UserSerializer` inside a Rails controller and serialize some users, all we need to do is:
 
 ```ruby
+
 class UsersController < ApplicationController
  def index
    users = User.includes(:posts).all
    render json: Panko::ArraySerializer.new(users, each_serializer: UserSerializer).to_json
  end
 end
+
 ```
 
-And voila, we have endpoint which serialize users using Panko!
+And voila, we have an endpoint which serializes users using Panko!

data/docs/docs/introduction.md

@@ -2,12 +2,12 @@
 id: index
 title: Introduction
 sidebar_label: Introduction
+slug: /
 ---
+Panko is a library which is inspired by ActiveModelSerializers 0.9 for serializing ActiveRecord/Ruby objects to JSON strings, fast.
 
-Panko is library which is inspired by ActiveModelSerializers 0.9 for serializing ActiveRecord/Ruby objects to JSON strings, fast.
+To achieve it's [performance](https://panko.dev/performance/):
 
-To achieve it's [performance](https://panko.dev/docs/performance.html):
-
-* Oj - Panko relies Oj since it's fast and allow to serialize incrementally using `Oj::StringWriter`
-* Serialization Descriptor - Panko computes most of the metadata ahead of time, to save time later in serialization.
-* Type casting — Panko does type casting by it's self, instead of relying ActiveRecord.
+-   Oj - Panko relies on Oj since it's fast and allow to serialize incrementally using `Oj::StringWriter`.
+-   Serialization Descriptor - Panko computes most of the metadata ahead of time, to save time later in serialization.
+-   Type casting — Panko does type casting by itself, instead of relying on ActiveRecord.

data/docs/docs/performance.md

@@ -3,13 +3,12 @@ id: performance
 title: Performance
 sidebar_label: Performance
 ---
-
 The performance of Panko is measured using microbenchmarks and load testing.
 
 ## Microbenchmarks
 
 The following microbenchmarks are run on MacBook Pro (16-inch, 2021, M1 Max), Ruby 3.2.0 with Rails 7.0.5
-demonstrating the performance of ActiveModelSerializers 0.10.13 and Panko 0.8.0
+demonstrating the performance of ActiveModelSerializers 0.10.13 and Panko 0.8.0.
 
 | Benchmark         | AMS ip/s | Panko ip/s |
 | ----------------- | -------- | ---------- |
@@ -20,8 +19,8 @@ demonstrating the performance of ActiveModelSerializers 0.10.13 and Panko 0.8.0
 
 ## Real-world benchmark
 
-The real-world benchmark here is endpoint which serializes 7,884 entries with 48 attributes and no associations.
-The benchmark took place in environment that simulates production environment and run using `wrk` from machine on the same cluster.
+The real-world benchmark here is an endpoint which serializes 7,884 entries with 48 attributes and no associations.
+The benchmark took place in an environment that simulates production environment and run using `wrk` from machine on the same cluster.
 
 | Metric             | AMS   | Panko |
 | ------------------ | ----- | ----- |
@@ -30,4 +29,4 @@ The benchmark took place in environment that simulates production environment an
 | 99th Response Time | 5.42s | 1.74s |
 | Total Requests     | 61    | 202   |
 
-_Thanks to [Bringg](https://www.bringg.com) for providing the infrastructure for the benchmarks_
+_Thanks to [Bringg](https://www.bringg.com) for providing the infrastructure for the benchmarks._

data/docs/docs/response-bag.md

@@ -3,11 +3,11 @@ id: response-bag
 title: Response
 sidebar_label: Response
 ---
-
-Let's say you have some JSON payload which can is constructed using Panko serialization result,
+Let's say you have some JSON payload which is constructed using Panko serialization result,
 like this:
 
 ```ruby
+
 class PostsController < ApplicationController
   def index
    posts = Post.all
@@ -18,11 +18,13 @@ class PostsController < ApplicationController
    }
   end
 end
+
 ```
 
-The output of the above will be json string (for `posts`) inside json string and this were `Panko::Response` shines.
+The output of the above will be a JSON string (for `posts`) inside a JSON string and this were `Panko::Response` shines.
 
 ```ruby
+
 class PostsController < ApplicationController
   def index
    posts = Post.all
@@ -33,13 +35,15 @@ class PostsController < ApplicationController
    )
   end
 end
+
 ```
 
 And everything will work as expected!
 
-For a single object serialization, we need to use a different API (since `Panko::Serializer` don't accept an object in it's constructor):
+For a single object serialization, we need to use a different API (since `Panko::Serializer` doesn't accept an object in it's constructor):
 
 ```ruby
+
 class PostsController < ApplicationController
   def show
     post = Post.find(params[:id])
@@ -54,14 +58,16 @@ class PostsController < ApplicationController
     )
   end
 end
+
 ```
 
 ## JsonValue
 
-Let's take the above example further, we serialized the posts and cached it as JSON string in our Cache.
-Now, you can wrap the cached value with `Panko::JsonValue`, like here -
+Let's take the above example further, we will serialize the posts and cache it as JSON string in our Cache.
+Now, you can wrap the cached value with `Panko::JsonValue`, like here:
 
 ```ruby
+
 class PostsController < ApplicationController
   def index
    posts = Cache.get("/posts")
@@ -73,4 +79,5 @@ class PostsController < ApplicationController
    )
   end
 end
+
 ```