panko_serializer 0.8.3 → 0.8.5

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 overview. Let's say we want to serialize `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 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 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
-
-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 a value of 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.
-
-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 configureable (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

@@ -1,70 +0,0 @@
----
-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
-
-```
-
-## Creating your first serializer
-
-Let's create serializer and use it inside Rails controller.
-
-```ruby
-class PostSerializer < Panko::Serializer
-  attributes :title
-end
-
-class UserSerializer < Panko::Serializer
-  attributes :id, :name, :age
-
-  has_many :posts, serializer: PostSerializer
-end
-```
-
-### Serializing an 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,
-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!

data/docs/docs/introduction.md

@@ -1,13 +0,0 @@
----
-id: index
-title: Introduction
-sidebar_label: Introduction
-slug: /
----
-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/docs/performance/):
-
--   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.

data/docs/docs/performance.md

@@ -1,32 +0,0 @@
----
-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
-
-| Benchmark         | AMS ip/s | Panko ip/s |
-| ----------------- | -------- | ---------- |
-| Simple_Posts_2300 | 11.72    | 523.05     |
-| Simple_Posts_50   | 557.29   | 23,011.9   |
-| HasOne_Posts_2300 | 5.91     | 233.44     |
-| HasOne_Posts_50   | 285.8    | 10,362.79  |
-
-## 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.
-
-| Metric             | AMS   | Panko |
-| ------------------ | ----- | ----- |
-| Avg Response Time  | 4.89s | 1.48s |
-| Max Response Time  | 5.42s | 1.83s |
-| 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_

data/docs/docs/response-bag.md

@@ -1,83 +0,0 @@
----
-id: response-bag
-title: Response
-sidebar_label: Response
----
-Let's say you have some JSON payload which can is constructed using Panko serialization result,
-like this:
-
-```ruby
-
-class PostsController < ApplicationController
-  def index
-   posts = Post.all
-   render json: {
-     success: true,
-     total_count: posts.count,
-     posts: Panko::ArraySerializer.new(posts, each_serializer: PostSerializer).to_json
-   }
-  end
-end
-
-```
-
-The output of the above will be json string (for `posts`) inside json string and this were `Panko::Response` shines.
-
-```ruby
-
-class PostsController < ApplicationController
-  def index
-   posts = Post.all
-   render json: Panko::Response.new(
-     success: true,
-     total_count: posts.count,
-     posts: Panko::ArraySerializer.new(posts, each_serializer: PostSerializer)
-   )
-  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):
-
-```ruby
-
-class PostsController < ApplicationController
-  def show
-    post = Post.find(params[:id])
-
-    render(
-      json: Panko::Response.create do |r|
-        {
-          success: true,
-          post: r.serializer(post, PostSerializer)
-        }
-      end
-    )
-  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 -
-
-```ruby
-
-class PostsController < ApplicationController
-  def index
-   posts = Cache.get("/posts")
-
-   render json: Panko::Response.new(
-     success: true,
-     total_count: posts.count,
-     posts: Panko::JsonValue.from(posts)
-   )
-  end
-end
-
-```

data/docs/docusaurus.config.js

@@ -1,86 +0,0 @@
-module.exports = {
-  "title": "Panko Serializers",
-  "tagline": "High Performance JSON Serialization for ActiveRecord & Ruby Objects",
-  "url": "https://panko.dev",
-  "baseUrl": "/",
-  "organizationName": "yosiat",
-  "projectName": "panko_serializer",
-  "favicon": "favicon.ico",
-  "customFields": {
-    "repoPath": "yosiat/panko_serializer",
-    "repoUrl": "https://github.com/yosiat/panko_serializer",
-  },
-  "onBrokenLinks": "log",
-  "onBrokenMarkdownLinks": "log",
-  "presets": [
-    [
-      "@docusaurus/preset-classic",
-      {
-        "docs": {
-          "path": "./docs",
-          "showLastUpdateAuthor": false,
-          "showLastUpdateTime": false,
-          "sidebarPath": "./sidebars.json",
-          "routeBasePath": process.env.NODE_ENV === 'production' ? '/docs' : '/',
-        },
-        "blog": false,
-        "pages": false,
-        "theme": {
-          "customCss": "./src/css/customTheme.css"
-        }
-      }
-    ]
-  ],
-  "plugins": [],
-  "themeConfig": {
-    colorMode: {
-      defaultMode: 'light',
-      disableSwitch: true,
-    },
-    "navbar": {
-      "title": "Panko Serializers",
-      "items": [
-        {
-          "to": "introduction",
-          "label": "Docs",
-          "position": "left"
-        }
-      ]
-    },
-    "image": "img/undraw_online.svg",
-    "footer": {
-      "links": [
-        {
-          title: "GitHub",
-          items: [
-            {
-              label: "Repository",
-              href: "https://github.com/yosiat/panko_serializer"
-            },
-            {
-              label: "Discussions",
-              href: "https://github.com/yosiat/panko_serializer/discussions"
-            },
-            {
-              label: "Issues",
-              href: "https://github.com/yosiat/panko_serializer/issues"
-            },
-            {
-              "html": `
-                  <iframe
-                    src="https://ghbtns.com/github-btn.html?user=yosiat&amp;repo=panko_serializer&amp;type=star&amp;count=true&amp;size=medium"
-                    title="GitHub Stars"
-                  />`
-            }
-          ]
-        }
-      ],
-      "copyright": `Copyright © ${new Date().getFullYear()} Panko Serializer`,
-    },
-    prism: {
-      theme: require('prism-react-renderer/themes/github'), // Optional: Customize theme
-      darkTheme: require('prism-react-renderer/themes/dracula'), // Optional: Dark theme
-      additionalLanguages: ['ruby'], // Add Ruby as an additional language
-    },
-  }
-}