panko_serializer 0.8.1 → 0.8.3

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.
 
 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,33 +24,40 @@ 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 -
 
 ```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`)
 
-> 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`
+-   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`)
+
+&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
 
@@ -61,24 +69,28 @@ For example, let's say one portion of the application needs to serializer list o
 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, only: {
+Panko::ArraySerializer.new(posts, each_serializer: PostSerializer, only: {
   instance: [:title, :body, :author, :comments],
   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.
+
+-   `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.
 
 It's important to note that Nested Filters, are recursive, in other words, we can filter the association's associations.
 
 For example, `CommentSerializer` have has_one association `Author`, and for each `comments.author` we only 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,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
+    },
+  }
+}