barley 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be82895a01fc1f0be3170a9a105b7fdf20b7e98d31a77c74c5d9f67068814dec
-  data.tar.gz: 276dcc80814079aed898b1e4d1d9e5b6bf3bc4b8b6b86f2b5cff701961d2b877
+  metadata.gz: faa7d627d11906ae112f0a8fd640f0a2d90acacc114c63297a26e227d5120c3d
+  data.tar.gz: c36d22bee59469e7e98f481086a5a32a75ac96d9bab984330a4d945c97efa5f6
 SHA512:
-  metadata.gz: 9f3482dc0562669991a64403c9c5cee510d61cc5ec79affa3715eb203ac1a48f1f15c676778d380eccbfe6efc57281eae6c179ab4378a62d35c31b0fd65529ea
-  data.tar.gz: b9d2a98edf8704acf8b8466042b924b771384e1756fd06f9d23939f9bd0fb4368a4934303057edd0a53d0c8f487dc93c10649e39fe17b3031189f383a668ec54
+  metadata.gz: 3adb8da65be384daf38feaf056541f6b3e2c2f7f400917ed2da43a9f382e3bbc28afdad2437fe7489bdcd1ccd3980a587697525f0b493e1ec7b5374acfb61bb8
+  data.tar.gz: a359ed1a3c15f8efdd62ec86112163edc8d423f9d0d8c8790e781c651ac208dfa722a42bb4c93f822b5bbfc2a072626bbf1c9ad088c24354828745476247fc58

data/README.md

@@ -1,4 +1,4 @@
-![Barley loqo](./img/barley.png)
+![Barley loqo](https://i.imgur.com/am0emi4.png)
 
 Barley is a dead simple, fast, and efficient ActiveModel JSON serializer.
 
@@ -6,6 +6,9 @@ Cerealize your ActiveModel objects into flat hashes with a dead simple, yet vers
 
 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,8 +24,9 @@ Then define your attributes and associations in a serializer class.
 ```ruby
 # /app/serializers/user_serializer.rb
 class UserSerializer < Barley::Serializer
-  attributes :id, :name,
+  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
@@ -243,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.
 
@@ -364,4 +389,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## Credits
 Barley is brought to you by the developer team from [StockPro](https://www.stock-pro.fr/).
 
-[![Barley is brought to you by StockPro](img/stockpro.png)](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,6 +39,16 @@ module Barley
     included do
       serializer "#{self}Serializer".constantize
 
+      # 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, root: root).serializable_hash

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
@@ -45,6 +134,39 @@ module Barley
         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
@@ -62,6 +184,12 @@ module Barley
         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,8 +197,13 @@ 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})
+    #
+    # @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
@@ -81,6 +214,9 @@ module Barley
       end
     end
 
+    # Serializes the object
+    #
+    # @return [Hash] the serializable hash
     def serializable_hash
       if @cache
         Barley::Cache.fetch(cache_base_key, expires_in: @expires_in) do
@@ -91,12 +227,20 @@ module Barley
       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
       if object.updated_at.present?
         "#{object.class.name&.underscore}/#{object.id}/#{object.updated_at&.to_i}/barley_cache/"
@@ -105,10 +249,18 @@ module Barley
       end
     end
 
+    # @api private
+    #
+    # @return [Array<Symbol>] the defined attributes
     def defined_attributes
       self.class.instance_variable_get(:@defined_attributes)
     end
 
+    # Serializes the object
+    #
+    # @api private
+    #
+    # @return [Hash] the serializable hash
     def _serializable_hash
       hash = {}
 
@@ -119,6 +271,9 @@ module Barley
       @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

data/lib/barley/version.rb

@@ -1,3 +1,3 @@
 module Barley
-  VERSION = "0.3.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.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Cedric Delalande
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-18 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: