panko_serializer 0.8.2 → 0.8.3

data/docs/docs/attributes.md

@@ -3,15 +3,14 @@ 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.
-
+-   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,6 +18,7 @@ class UserSerializer < Panko::Serializer
     "#{object.first_name} #{object.last_name}"
    end
 end
+
 ```
 
 ## Field Attributes
@@ -27,7 +27,6 @@ Using field attributes you can control which columns of the given ActiveRecord o
 
 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)).
 
-
 ## Method Attributes
 
 Method attributes are used when your serialized values can be derived from the object you are serializing.
@@ -35,6 +34,7 @@ Method attributes are used when your serialized values can be derived from the o
 The serializer's attribute methods can access the object being serialized as `object` -
 
 ```ruby
+
 class PostSerializer < Panko::Serializer
   attributes :author_name
 
@@ -42,12 +42,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.
 
 For example, here we will pass feature flags:
+
 ```ruby
+
 class UserSerializer < Panko::Serializer
   attributes :id, :email
 
@@ -61,6 +64,7 @@ serializer = UserSerializer.new(context: {
 })
 
 serializer.serialize(User.first)
+
 ```
 
 ## Filters
@@ -68,11 +72,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,13 +89,14 @@ 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`
+&gt; property is not taken into account.
+&gt; If you have a `has_many :state_transitions, name: :history` association
+&gt; defined, the key to use in filters is `:state_transitions`
+&gt; (e.g. `{ except: [:state_transitions] }`)
 
 ## Filters For
 
@@ -96,6 +104,7 @@ Sometimes you find yourself have 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,30 +117,27 @@ 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:
 
 ## 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:
 
 ```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 direct hit on performance.
+The downside of this approach is that `` skips Panko's type casting, therefore we get 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

@@ -3,15 +3,13 @@ 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`.
-
+-   `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
 
@@ -21,6 +19,7 @@ First, let's start with overview. Let's say we want to serialize `User` object,
 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,6 +42,7 @@ 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.
@@ -49,19 +51,19 @@ _I will skip the serializer definition part, because it's fairly simple and stra
 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.
 Now let's dig deeper.
@@ -72,31 +74,30 @@ 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 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.
+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?
+-   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.
@@ -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 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

@@ -3,21 +3,23 @@ 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
 
@@ -40,11 +42,13 @@ end
 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
@@ -53,12 +57,14 @@ As you can see, defining serializers is simple and resembles ActiveModelSerializ
 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

@@ -2,12 +2,12 @@
 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.html):
+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.
+-   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

@@ -3,7 +3,6 @@ id: performance
 title: Performance
 sidebar_label: Performance
 ---
-
 The performance of Panko is measured using microbenchmarks and load testing.
 
 ## Microbenchmarks

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,
 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.
 
 ```ruby
+
 class PostsController < ApplicationController
   def index
    posts = Post.all
@@ -33,6 +35,7 @@ class PostsController < ApplicationController
    )
   end
 end
+
 ```
 
 And everything will work as expected!
@@ -40,6 +43,7 @@ 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])
@@ -54,6 +58,7 @@ class PostsController < ApplicationController
     )
   end
 end
+
 ```
 
 ## JsonValue
@@ -62,6 +67,7 @@ Let's take the above example further, we serialized the posts and cached it as J
 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
+
 ```

data/docs/docusaurus.config.js

@@ -0,0 +1,86 @@
+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
+    },
+  }
+}