barley 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bee5cfe197a0a824c4edd25ab6ad77628c14732bafc2ff09ceb64e08e24d6aaf
-  data.tar.gz: 5d060056d2de5fb5b8c64ca78b84a5faeb39fb4e7714e8de07647a26bfeeb76b
+  metadata.gz: faa7d627d11906ae112f0a8fd640f0a2d90acacc114c63297a26e227d5120c3d
+  data.tar.gz: c36d22bee59469e7e98f481086a5a32a75ac96d9bab984330a4d945c97efa5f6
 SHA512:
-  metadata.gz: 67d5c179e808312c73d5058e634c4ee2a7237d702b931580fd6a2c5e73085c51839a0e1debb8591f172cc696a8cbb9b694ccd7c740880d5fd384995a28011115
-  data.tar.gz: 5db28559be764eff3ef9990925896c6e1ce11005011335ab993f4fd346313cf0874bd22e7abdfc815616b95b0820c51648ecc22ca4243993b1d5dc9a4f200988
+  metadata.gz: 3adb8da65be384daf38feaf056541f6b3e2c2f7f400917ed2da43a9f382e3bbc28afdad2437fe7489bdcd1ccd3980a587697525f0b493e1ec7b5374acfb61bb8
+  data.tar.gz: a359ed1a3c15f8efdd62ec86112163edc8d423f9d0d8c8790e781c651ac208dfa722a42bb4c93f822b5bbfc2a072626bbf1c9ad088c24354828745476247fc58

data/README.md

@@ -1,11 +1,14 @@
-![Barley loqo](./img/barley.png)
+![Barley loqo](https://i.imgur.com/am0emi4.png)
 
 Barley is a dead simple, fast, and efficient ActiveModel JSON serializer.
 
-Cerealize your ActiveModel objects into flat JSON objects with a dead simple DSL. Our daily bread is to make your API faster. 
+Cerealize your ActiveModel objects into flat hashes with a dead simple, yet versatile DSL, and caching baked in. Our daily bread is to make your API faster. 
 
 You don't believe us? Check out the [benchmarks](#benchmarks). 😎
 
+## API documentation
+[Check out the API documentation here](https://rubydoc.info/github/MoskitoHero/barley/main).
+
 ## Usage
 Add the `Barley::Serializable` module to your ActiveModel object.
 
@@ -21,10 +24,20 @@ Then define your attributes and associations in a serializer class.
 ```ruby
 # /app/serializers/user_serializer.rb
 class UserSerializer < Barley::Serializer
-  attributes :id, :name, :email, :created_at, :updated_at
-
-  many :posts
-  one :group
+  attributes id: Types::Strict::Integer, :name # multiple attributes, optional type checking with dry-types
+  attribute :email # single attribute
+  attribute :value, type: Types::Coercible::Integer # optional type checking with dry-types
+
+  many :posts # relations
+  one :group, serializer: CustomGroupSerializer # custom serializer
+  many :related_users, key: :friends, cache: true # custom key, and caching
+  one :profile, cache: { expires_in: 1.day } do # cache definition, and block (on associations) for nested, on-the-fly serializer
+    attributes :avatar, :social_url
+    attribute :badges do
+      object.badges.map(&:display_name) # use object in a block to return custom code
+    end
+  end
+    
 end
 ```
 
@@ -234,6 +247,27 @@ Barley.configure do |config|
 end
 ```
 
+## Type checking
+Barley can check the type of the object you are serializing with the [dry-types](https://dry-rb.org/gems/dry-types/main/) gem. 
+
+It will raise an error if the object is not of the expected type, or coerce it to the correct type and perform constraints checks.
+
+```ruby
+module Types
+  include Dry.Types()
+end
+
+class UserSerializer < Barley::Serializer
+  attributes id: Types::Strict::Integer, name: Types::Strict::String, email: Types::Strict::String.constrained(format: URI::MailTo::EMAIL_REGEXP)
+
+  attribute :role, type: Types::Coercible::String do
+    object.role.integer_or_string_coercible_value
+  end
+end
+```
+
+Check out [dry-types](https://dry-rb.org/gems/dry-types/main/) for all options and available types.
+
 ## Breakfast mode 🤡 (coming soon)
 You will soon be able to replace all occurrences of `Serializer` with `Cerealizer` in your codebase. Just for fun. And for free.
 
@@ -264,14 +298,14 @@ Ah ah ah. This is so funny.
 *Note: we are thinking about adding a `Surrealizer` class for the most advanced users. Stay tuned.*
 
 ## JSON:API
-No. Not yet. Maybe never. We don't know. We don't care. We don't use it. We don't like it. We don't want to. We don't have time. We don't have money. We don't have a life. We don't have a girlfriend. We don't have a boyfriend. We don't have a dog. We don't have a cat. We are generating this readme with Copilot.
+Barley does not serialize to the JSON:API standard. We prefer to keep it simple and fast.
 
 ## Benchmarks
 This gem is blazing fast and efficient. It is 2 to 3 times faster than [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers) and twice as fast as [FastJsonapi](https://github.com/Netflix/fast_jsonapi). Memory object allocation is also much lower.
 
 With caching enabled, it is just mind-blowing. We think. *Disclaimer: we do not serialize to the JSON:API standard, so that might be the reason why we are so fast.*
 
-This is the result we get with the benchmark script used in the AMS repo on an Apple Silicon M1Pro processor. We will push this benchmark as soon as possible so you can see for yourself.
+This is the result we get with the benchmark script used in the AMS repo on an Apple Silicon M1Pro processor. [Check it out for yourself here](https://github.com/MoskitoHero/active_model_serializers/tree/benchmarks).
 
 ```shell
 bundle exec ruby benchmark.rb
@@ -351,3 +385,8 @@ ams               :    1299674 allocated - 28.20x more
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+Barley is brought to you by the developer team from [StockPro](https://www.stock-pro.fr/).
+
+[![Barley is brought to you by StockPro](https://i.imgur.com/5a0veEG.png)](https://www.stock-pro.fr/)

data/lib/barley/serializable.rb

@@ -4,6 +4,7 @@ module Barley
   # Makes a Model serializable
   #
   # * Allows setting a default model Serializer
+  #
   # @example
   #   class Item < ApplicationRecord
   #     include Barley::Serializable
@@ -19,10 +20,15 @@ module Barley
     class_methods do
       # @example without cache
       #   serializer ItemSerializer
+      #
       # @example with cache
       #   serializer ItemSerializer, cache: true
+      #
       # @example with cache and expires_in
       #   serializer ItemSerializer, cache: {expires_in: 1.hour}
+      #
+      # @param klass [Class] the serializer class
+      # @param cache [Boolean, Hash<Symbol, ActiveSupport::Duration>] whether to cache the result, or a hash with options for the cache
       def serializer(klass, cache: false)
         define_method(:serializer) do
           klass.new(self, cache: cache)
@@ -33,9 +39,19 @@ module Barley
     included do
       serializer "#{self}Serializer".constantize
 
-      def as_json(serializer: nil, cache: false)
+      # Serializes the model
+      #
+      # @note this method does not provide default rails options like `only` or `except`.
+      #   This is because the Barley serializer should be the only place where the attributes are defined.
+      #
+      # @param serializer [Class] the serializer to use
+      # @param cache [Boolean, Hash<Symbol, ActiveSupport::Duration>] whether to cache the result, or a hash with options for the cache
+      # @param root [Boolean] whether to include the root key in the hash
+      #
+      # @return [Hash] the serialized attributes
+      def as_json(serializer: nil, cache: false, root: false)
         serializer ||= self.serializer.class
-        serializer.new(self, cache: cache).as_json
+        serializer.new(self, cache: cache, root: root).serializable_hash
       end
     end
   end

data/lib/barley/serializer.rb

@@ -5,29 +5,118 @@ module Barley
     attr_accessor :object
 
     class << self
+      # Defines attributes for the serializer
+      #
+      # Accepts either a list of symbols or a hash of symbols and Dry::Types, or a mix of both
+      #
+      # @example only symbols
+      #   attributes :id, :name, :email
+      #   # => {id: 1234, name: "John Doe", email: "john.doe@example"}
+      #
+      # @example with types
+      #   attributes id: Types::Strict::Integer, name: Types::Strict::String, email: Types::Strict::String
+      #   # => {id: 1234, name: "John Doe", email: "john.doe@example"}
+      #
+      # @example with types and symbols
+      #   attributes :id, name: Types::Strict::String, email: Types::Strict::String
+      #   # => {id: 1234, name: "John Doe", email: "john.doe@example"}
+      #
+      # @see Serializer#attribute
+      #
+      # @param keys [Hash<Symbol, Dry::Types>, Array<Symbol>] mix of symbols and hashes of symbols and Dry::Types
       def attributes(*keys)
+        if keys.last.is_a?(Hash)
+          keys.pop.each do |key, type|
+            attribute(key, type: type)
+          end
+        end
         keys.each do |key|
-          define_method(key) do
-            object.send(key)
+          if key.is_a?(Hash)
+            attribute(key.keys.first, type: key.values.first)
+          else
+            attribute(key)
           end
-          set_class_iv(:@defined_attributes, key)
         end
       end
 
-      def attribute(key, key_name: nil, &block)
+      # Defines a single attribute for the serializer
+      #
+      # Type checking is done with Dry::Types. If a type is not provided, the value is returned as is.
+      # Dry::Types can be used to coerce the value to the desired type and to check constraints.
+      #
+      # @see https://dry-rb.org/gems/dry-types/main/
+      #
+      # @raise [Dry::Types::ConstraintError] if the type does not match
+      #
+      # @example simple attribute
+      #   attribute :id
+      #   # => {id: 1234}
+      #
+      # @example attribute with a different key name
+      #   attribute :name, key_name: :full_name
+      #   # => {full_name: "John Doe"}
+      #
+      # @example attribute with a type
+      #   attribute :email, type: Types::Strict::String
+      #   # => {email: "john.doe@example"}
+      #
+      # @example attribute with a type and a block
+      #   attribute :email, type: Types::Strict::String do
+      #     object.email.upcase
+      #   end
+      #   # => {email: "JOHN.DOE@EXAMPLE"}
+      #
+      # @param key [Symbol] the attribute name
+      # @param key_name [Symbol] the key name in the hash
+      # @param type [Dry::Types] the type to use, or coerce the value to
+      # @param block [Proc] a block to use to compute the value
+      def attribute(key, key_name: nil, type: nil, &block)
         key_name ||= key
         if block
           define_method(key_name) do
-            instance_eval(&block)
+            type.nil? ? instance_eval(&block) : type[instance_eval(&block)]
           end
         else
           define_method(key_name) do
-            object.send(key)
+            type.nil? ? object.send(key) : type[object.send(key)]
           end
         end
         set_class_iv(:@defined_attributes, key_name)
       end
 
+      # Defines a single association for the serializer
+      #
+      # @example using the default serializer of the associated model
+      #   one :group
+      #   # => {group: {id: 1234, name: "Group 1"}}
+      #
+      # @example using a custom serializer
+      #   one :group, serializer: MyCustomGroupSerializer
+      #   # => {group: {id: 1234, name: "Group 1"}}
+      #
+      # @example using a block with an inline serializer definition
+      #   one :group do
+      #     attributes :id, :name
+      #   end
+      #   # => {group: {id: 1234, name: "Group 1"}}
+      #
+      # @example using a different key name
+      #   one :group, key_name: :my_group
+      #   # => {my_group: {id: 1234, name: "Group 1"}}
+      #
+      # @example using cache
+      #   one :group, cache: true
+      #   # => {group: {id: 1234, name: "Group 1"}}
+      #
+      # @example using cache and expires_in
+      #   one :group, cache: {expires_in: 1.hour}
+      #   # => {group: {id: 1234, name: "Group 1"}}
+      #
+      # @param key [Symbol] the association name
+      # @param key_name [Symbol] the key name in the hash
+      # @param serializer [Class] the serializer to use
+      # @param cache [Boolean, Hash<Symbol, ActiveSupport::Duration>] whether to cache the result, or a hash with options for the cache
+      # @param block [Proc] a block to use to define the serializer inline
       def one(key, key_name: nil, serializer: nil, cache: false, &block)
         key_name ||= key
         if block
@@ -40,11 +129,44 @@ module Barley
           return {} if element.nil?
 
           el_serializer = serializer || element.serializer.class
-          el_serializer.new(element, cache: cache).as_json
+          el_serializer.new(element, cache: cache).serializable_hash
         end
         set_class_iv(:@defined_attributes, key_name)
       end
 
+      # Defines a collection association for the serializer
+      #
+      # @example using the default serializer of the associated model
+      #   many :groups
+      #   # => {groups: [{id: 1234, name: "Group 1"}, {id: 5678, name: "Group 2"}]}
+      #
+      # @example using a custom serializer
+      #   many :groups, serializer: MyCustomGroupSerializer
+      #   # => {groups: [{id: 1234, name: "Group 1"}, {id: 5678, name: "Group 2"}]}
+      #
+      # @example using a block with an inline serializer definition
+      #   many :groups do
+      #     attributes :id, :name
+      #   end
+      #   # => {groups: [{id: 1234, name: "Group 1"}, {id: 5678, name: "Group 2"}]}
+      #
+      # @example using a different key name
+      #   many :groups, key_name: :my_groups
+      #   # => {my_groups: [{id: 1234, name: "Group 1"}, {id: 5678, name: "Group 2"}]}
+      #
+      # @example using cache
+      #   many :groups, cache: true
+      #   # => {groups: [{id: 1234, name: "Group 1"}, {id: 5678, name: "Group 2"}]}
+      #
+      # @example using cache and expires_in
+      #   many :groups, cache: {expires_in: 1.hour}
+      #   # => {groups: [{id: 1234, name: "Group 1"}, {id: 5678, name: "Group 2"}]}
+      #
+      # @param key [Symbol] the association name
+      # @param key_name [Symbol] the key name in the hash
+      # @param serializer [Class] the serializer to use
+      # @param cache [Boolean, Hash<Symbol, ActiveSupport::Duration>] whether to cache the result, or a hash with options for the cache
+      # @param block [Proc] a block to use to define the serializer inline
       def many(key, key_name: nil, serializer: nil, cache: false, &block)
         key_name ||= key
         if block
@@ -57,11 +179,17 @@ module Barley
           return [] if elements.empty?
 
           el_serializer = serializer || elements.first.serializer.class
-          elements.map { |element| el_serializer.new(element, cache: cache).as_json }.reject(&:blank?)
+          elements.map { |element| el_serializer.new(element, cache: cache).serializable_hash }.reject(&:blank?)
         end
         set_class_iv(:@defined_attributes, key_name)
       end
 
+      # Either sets or appends a key to an instance variable
+      #
+      # @api private
+      #
+      # @param iv [Symbol] the instance variable to set
+      # @param key [Symbol] the key to add to the instance variable
       def set_class_iv(iv, key)
         instance_variable_defined?(iv) ? instance_variable_get(iv) << key : instance_variable_set(iv, [key])
       end
@@ -69,10 +197,16 @@ module Barley
 
     # @example with cache
     #   Barley::Serializer.new(object, cache: true)
+    #
     # @example with cache and expires_in
     #   Barley::Serializer.new(object, cache: {expires_in: 1.hour})
-    def initialize(object, cache: false)
+    #
+    # @param object [Object] the object to serialize
+    # @param cache [Boolean, Hash<Symbol, ActiveSupport::Duration>] a boolean to cache the result, or a hash with options for the cache
+    # @param root [Boolean] whether to include the root key in the hash
+    def initialize(object, cache: false, root: false)
       @object = object
+      @root = root
       @cache, @expires_in = if cache.is_a?(Hash)
         [true, cache[:expires_in]]
       else
@@ -80,39 +214,68 @@ module Barley
       end
     end
 
-    def as_json
+    # Serializes the object
+    #
+    # @return [Hash] the serializable hash
+    def serializable_hash
       if @cache
-        cache_key = cache_base_key
-        Barley::Cache.fetch(cache_key, expires_in: @expires_in) do
-          _as_json
+        Barley::Cache.fetch(cache_base_key, expires_in: @expires_in) do
+          _serializable_hash
         end
       else
-        _as_json
+        _serializable_hash
       end
     end
 
+    # Clears the cache for the object
+    #
+    # @param key [String] the cache key
+    #
+    # @return [Boolean] whether the cache was cleared
     def clear_cache(key: cache_base_key)
       Barley::Cache.delete(key)
     end
 
     private
 
+    # @api private
+    #
+    # @return [String] the cache key
     def cache_base_key
-      "#{object.class.name&.underscore}/#{object.id}/#{object.updated_at.to_i}/as_json/"
+      if object.updated_at.present?
+        "#{object.class.name&.underscore}/#{object.id}/#{object.updated_at&.to_i}/barley_cache/"
+      else
+        "#{object.class.name&.underscore}/#{object.id}/barley_cache/"
+      end
     end
 
+    # @api private
+    #
+    # @return [Array<Symbol>] the defined attributes
     def defined_attributes
       self.class.instance_variable_get(:@defined_attributes)
     end
 
-    def _as_json
+    # Serializes the object
+    #
+    # @api private
+    #
+    # @return [Hash] the serializable hash
+    def _serializable_hash
       hash = {}
 
       defined_attributes.each do |key|
         hash[key] = send(key)
       end
 
-      hash
+      @root ? {root_key => hash} : hash
+    end
+
+    # @api private
+    #
+    # @return [Symbol] the root key, based on the class name
+    def root_key
+      object.class.name.underscore.to_sym
     end
   end
 end

data/lib/barley/version.rb

@@ -1,3 +1,3 @@
 module Barley
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/barley.rb

@@ -1,6 +1,7 @@
 require "barley/version"
 require "barley/railtie"
 require "barley/configuration"
+require "dry-types"
 
 module Barley
   mattr_accessor :config

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: barley
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Cedric Delalande
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-11 00:00:00.000000000 Z
+date: 2023-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 6.1.0
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.1
 description: Cerealize your ActiveModel objects into flat JSON objects with a dead
   simple DSL. Our daily bread is to make your API faster.
 email: