barley 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be82895a01fc1f0be3170a9a105b7fdf20b7e98d31a77c74c5d9f67068814dec
-  data.tar.gz: 276dcc80814079aed898b1e4d1d9e5b6bf3bc4b8b6b86f2b5cff701961d2b877
+  metadata.gz: d882b89bf1bf77259eda96813c4732ef1b286142ecb29fcb945837b743e089c9
+  data.tar.gz: 87dc3b213a614957a668c08865b87eb44f805cf76b79a60c710025a7d18257d8
 SHA512:
-  metadata.gz: 9f3482dc0562669991a64403c9c5cee510d61cc5ec79affa3715eb203ac1a48f1f15c676778d380eccbfe6efc57281eae6c179ab4378a62d35c31b0fd65529ea
-  data.tar.gz: b9d2a98edf8704acf8b8466042b924b771384e1756fd06f9d23939f9bd0fb4368a4934303057edd0a53d0c8f487dc93c10649e39fe17b3031189f383a668ec54
+  metadata.gz: a7eb159a6e40374364504f5c828d7e1f82e7a581bd89fe374182916b0dbc6863caaea779acf409e58c8fe60ff3614acdfa944bb3f74dbd808957925db146dded
+  data.tar.gz: d84b0157c80e83cfa28dbafda0fd300f2774c4362b5e1e47f9fc0381fb0cd8713dce2f1b27f4cfb9896af2c11d354d92b8df0dcfaee6a94bb69e6aca738e45b2

data/README.md

@@ -1,11 +1,18 @@
-![Barley loqo](./img/barley.png)
+![Barley loqo](https://i.imgur.com/am0emi4.png)
 
-Barley is a dead simple, fast, and efficient ActiveModel JSON serializer.
+![Test suite badge](https://github.com/MoskitoHero/barley/actions/workflows/ruby.yml/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/barley.svg)](https://badge.fury.io/rb/barley)
+![Static Badge](https://img.shields.io/badge/Cereal%20-%20100%25%20-%20darklime)
 
-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. 
+Barley is a dead simple, fast, and efficient ActiveModel serializer.
+
+Cerealize your ActiveModel objects into flat hashes with a dead simple, yet versatile DSL, and caching and type-checking 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,23 +28,30 @@ Then define your attributes and associations in a serializer class.
 ```ruby
 # /app/serializers/user_serializer.rb
 class UserSerializer < Barley::Serializer
-  attributes :id, :name,
-  attribute :email # single attribute
+  
+  attributes id: Types::Strict::Integer, :name
+  
+  attribute :email
+  attribute :value, type: Types::Coercible::Integer
 
-  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
+  many :posts
+  
+  one :group, serializer: CustomGroupSerializer
+  
+  many :related_users, key: :friends, cache: true
+  
+  one :profile, cache: { expires_in: 1.day } do
     attributes :avatar, :social_url
+    
     attribute :badges do
-      object.badges.map(&:display_name) # use object in a block to return custom code
+      object.badges.map(&:display_name)
     end
   end
     
 end
 ```
 
-The just use the `as_json` method on your model.
+Then just use the `as_json` method on your model.
 
 ```ruby
 user = User.find(1)
@@ -243,6 +257,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.
 
@@ -361,7 +396,16 @@ 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).
 
+## Contributing
+You can contribute in several ways: reporting bugs, suggesting features, or contributing code. See [our contributing guidelines](CONTRIBUTING.md)
+
+Make sure you adhere to [our code of conduct](CODE_OF_CONDUCT.md). We aim to keep this project open and inclusive.
+
+## Security
+
+Please refer to our [security guidelines](SECURITY.md)
+
 ## 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/Rakefile

@@ -1,3 +1,12 @@
 require "bundler/setup"
 
 require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << "test"
+end
+desc "Run tests"
+
+task default: :test

data/lib/barley/error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Barley
+  class Error < StandardError
+  end
+end

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,23 +20,55 @@ 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)
+        # We need to silence the warnings because we are defining a method with the same name as the parameter
+        # This avoids :
+        # - warning: method redefined; discarding old serializer
+        # - warning: previous definition of serializer was here
+        Kernel.silence_warnings do
+          define_method(:serializer) do
+            klass.new(self, cache: cache)
+          end
         end
       end
     end
 
     included do
-      serializer "#{self}Serializer".constantize
+      begin
+        serializer "#{self}Serializer".constantize
+      rescue NameError
+        raise Barley::Error, "Could not find serializer for #{self}. Please define a #{self}Serializer class."
+      end
 
-      def as_json(serializer: nil, cache: false, root: false)
-        serializer ||= self.serializer.class
-        serializer.new(self, cache: cache, root: root).serializable_hash
+      # 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.
+      #
+      # @option options [Class] :serializer the serializer to use
+      # @option options [Boolean, Hash<Symbol, ActiveSupport::Duration>] :cache whether to cache the result, or a hash with options for the cache
+      # @option options [Boolean] :root whether to include the root key
+      #
+      # @return [Hash] the serialized attributes
+      def as_json(options = nil)
+        options ||= {}
+        serializer = options[:serializer] || self.serializer.class
+        cache = options[:cache] || false
+        root = options[:root] || false
+        begin
+          serializer.new(self, cache: cache, root: root).serializable_hash
+        rescue NameError
+          raise Barley::Error, "Could not find serializer for #{self}. Please define a #{serializer} class."
+        end
       end
     end
   end

data/lib/barley/serializer.rb

@@ -5,29 +5,116 @@ module Barley
     attr_accessor :object
 
     class << self
+      attr_accessor :defined_attributes
+
+      # 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)
-          end
-        else
-          define_method(key_name) do
-            object.send(key)
-          end
+        define_method(key_name) do
+          value = block ? instance_eval(&block) : object.send(key)
+          type.nil? ? value : type[value]
         end
-        set_class_iv(:@defined_attributes, key_name)
+
+        self.defined_attributes = (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
@@ -42,9 +129,42 @@ module Barley
           el_serializer = serializer || element.serializer.class
           el_serializer.new(element, cache: cache).serializable_hash
         end
-        set_class_iv(:@defined_attributes, key_name)
+        self.defined_attributes = (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
@@ -59,18 +179,19 @@ module Barley
           el_serializer = serializer || elements.first.serializer.class
           elements.map { |element| el_serializer.new(element, cache: cache).serializable_hash }.reject(&:blank?)
         end
-        set_class_iv(:@defined_attributes, key_name)
-      end
-
-      def set_class_iv(iv, key)
-        instance_variable_defined?(iv) ? instance_variable_get(iv) << key : instance_variable_set(iv, [key])
+        self.defined_attributes = (defined_attributes || []) << key_name
       end
     end
 
     # @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 +202,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 +215,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 +237,18 @@ module Barley
       end
     end
 
+    # @api private
+    #
+    # @return [Array<Symbol>] the defined attributes
     def defined_attributes
-      self.class.instance_variable_get(:@defined_attributes)
+      self.class.defined_attributes
     end
 
+    # Serializes the object
+    #
+    # @api private
+    #
+    # @return [Hash] the serializable hash
     def _serializable_hash
       hash = {}
 
@@ -119,6 +259,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.1"
 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.1
 platform: ruby
 authors:
 - Cedric Delalande
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-18 00:00:00.000000000 Z
+date: 2023-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -24,8 +24,23 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 6.1.0
-description: Cerealize your ActiveModel objects into flat JSON objects with a dead
-  simple DSL. Our daily bread is to make your API faster.
+- !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 hashes with a dead simple,
+  yet versatile DSL, and caching and type-checking baked in. Our daily bread is to
+  make your API faster.
 email:
 - weengs@moskitohero.com
 executables: []
@@ -38,6 +53,7 @@ files:
 - lib/barley.rb
 - lib/barley/cache.rb
 - lib/barley/configuration.rb
+- lib/barley/error.rb
 - lib/barley/railtie.rb
 - lib/barley/serializable.rb
 - lib/barley/serializer.rb
@@ -60,7 +76,8 @@ metadata:
   homepage_uri: https://github.com/moskitohero/barley
   source_code_uri: https://github.com/moskitohero/barley
   changelog_uri: https://github.com/moskitohero/barley/CHANGELOG.md
-post_install_message:
+  documentation_uri: https://rubydoc.info/github/MoskitoHero/barley/main
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -75,8 +92,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
-signing_key:
+rubygems_version: 3.3.26
+signing_key: 
 specification_version: 4
-summary: Barley is a dead simple, fast, and efficient ActiveModel JSON serializer.
+summary: Barley is a dead simple, fast, and efficient ActiveModel serializer.
 test_files: []