alba 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34c441cbc87f959f73c3e7a0175309f780b23ce840add4d53cf5083488390f1f
-  data.tar.gz: f78fb2eea40f502c6f7b3c905317616054bd397d30aa9ce979285003205c81af
+  metadata.gz: c7ab62feaab9747cd1441aea57b8d8f7f1d149261d86e4e64e9f859ae8f1091c
+  data.tar.gz: 4442a77416ee235ad6537580ec0600c4b1c9b0bea7b154b3a96010514316531d
 SHA512:
-  metadata.gz: 326ac8e731f2b4e0fe4afbb8f690059ecd578ffcb9270b9779bdcb6bb50d57d063ec0a98fc488398915c39ca2978b41e79d53bb1f5a809f9272ad885c383a549
-  data.tar.gz: 2b36eb5d07749505b4ab377b56cc7e564bcd6e86d872e7cb2c45f62ae2cf91a41b2c6e0b70cdcbb8d2a5d802528e4d9bfb113b723a2be7b1bdbc207c0277df45
+  metadata.gz: 373f00c4b2bf57f18d65d86a9c8209f9d0c94038f44a98df8e7c7768158d23e03f427729006eb113f0e88fde17a829364cf561026858c83bbb861a7d7eefba13
+  data.tar.gz: ad75036a0f554d13637d32413906f17166347459f2e3bcd3e1fe55f4ddc5d805da59ece5c1e46babadea434d667927aab4e3b7f6b0d37887ee6f58cae10396c9

data/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,70 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ main ]
+  schedule:
+    - cron: '21 4 * * 5'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'ruby' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://git.io/codeql-language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v1
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1

data/.github/workflows/main.yml

@@ -8,9 +8,11 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        ruby: [2.5, 2.6, 2.7, 3.0, head, jruby, truffleruby]
+        ruby: [2.5, 2.6, 2.7, 3.0, 3.1, head, jruby, truffleruby]
         gemfile: [all, without_active_support, without_oj]
         exclude:
+          - os: windows-latest
+            ruby: 3.1
           - os: windows-latest
             ruby: jruby
           - os: windows-latest

data/.rubocop.yml

@@ -46,9 +46,11 @@ Metrics:
     - 'test/**/*.rb'
 
 # `Resource` module is a core module and its length tends to be long...
+# `Alba` main module is also long because it has all parts of configuration
 Metrics/ModuleLength:
   Exclude:
     - 'lib/alba/resource.rb'
+    - 'lib/alba.rb'
 
 # Resource class includes DSLs, which tend to accept long list of parameters
 Metrics/ParameterLists:

data/CHANGELOG.md

@@ -6,6 +6,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] 2022-03-16
+
+- [Feat] Support instance method as an attribute
+- [Fix] Explicitly raise error when inference is disabled
+- [Improve] `enable_inference!` now takes inflector as argument
+- [Improve] `transform_keys` now accepts `:snake` and `:none`
+- [Deprecate] `to_hash` is special method and should not be used
+- [Deprecate] `ignoring` in favor of `attributes` overriding
+- [Deprecate] `Alba.on_nil`, `Alba.on_error` and `Alba.enable_root_key_transformation!`
+
 ## [1.5.0] 2021-11-28
 
 - [Feat] Add nil handler

data/Gemfile

@@ -9,8 +9,8 @@ gem 'inch', require: false # For inline documents
 gem 'minitest', '~> 5.14' # For test
 gem 'rake', '~> 13.0' # For test and automation
 gem 'rubocop', '>= 0.79.0', require: false # For lint
-gem 'rubocop-minitest', '~> 0.17.0', require: false # For lint
-gem 'rubocop-performance', '~> 1.12.0', require: false # For lint
+gem 'rubocop-minitest', '~> 0.18.0', require: false # For lint
+gem 'rubocop-performance', '~> 1.13.0', require: false # For lint
 gem 'rubocop-rake', '>= 0.5.1', require: false # For lint
 gem 'rubocop-sensible', '~> 0.3.0', require: false # For lint
 gem 'simplecov', '~> 0.21.0', require: false # For test coverage

data/README.md

@@ -2,7 +2,6 @@
 [![CI](https://github.com/okuramasafumi/alba/actions/workflows/main.yml/badge.svg)](https://github.com/okuramasafumi/alba/actions/workflows/main.yml)
 [![codecov](https://codecov.io/gh/okuramasafumi/alba/branch/master/graph/badge.svg?token=3D3HEZ5OXT)](https://codecov.io/gh/okuramasafumi/alba)
 [![Maintainability](https://api.codeclimate.com/v1/badges/fdab4cc0de0b9addcfe8/maintainability)](https://codeclimate.com/github/okuramasafumi/alba/maintainability)
-[![Inline docs](http://inch-ci.org/github/okuramasafumi/alba.svg?branch=main)](http://inch-ci.org/github/okuramasafumi/alba)
 ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/okuramasafumi/alba)
 ![GitHub](https://img.shields.io/github/license/okuramasafumi/alba)
 
@@ -20,19 +19,19 @@ If you have feature requests or interesting ideas, join us with [Ideas](https://
 
 ## Why Alba?
 
-Because it's fast, flexible and well-maintained!
+Because it's fast, easy-to-use and extensible!
 
 ### Fast
 
 Alba is faster than most of the alternatives. We have a [benchmark](https://github.com/okuramasafumi/alba/tree/master/benchmark).
 
-### Flexible
+### Easy to use
 
-Alba provides a small set of DSL to define your serialization logic. It also provides methods you can override to alter and filter serialized hash so that you have full control over the result.
+Alba provides four DSLs, `attributes` to fetch attribute with its name, `attribute` to execute block for the attribute, `one` to seriaize single attribute with another resource, and `many` to serialize collection attribute with another resource. When you want to do something complex, there are many examples in this README so you can mimic them to get started.
 
-### Maintained
+### Extensible
 
-Alba is well-maintained and adds features quickly. [Coverage Status](https://coveralls.io/github/okuramasafumi/alba?branch=master) and [CodeClimate Maintainability](https://codeclimate.com/github/okuramasafumi/alba/maintainability) show the code base is quite healthy.
+Alba embraces extensibility through common techniques such as class inheritance and module inclusion. Alba provides its capacity with one module so you can still have your own class hierarchy.
 
 ## Installation
 
@@ -72,15 +71,6 @@ You can find the documentation on [RubyDoc](https://rubydoc.info/github/okuramas
 * Layout
 * No runtime dependencies
 
-## Anti features
-
-* Sorting keys
-* Class level support of parameters
-* Supporting all existing JSON encoder/decoder
-* Cache
-* [JSON:API](https://jsonapi.org) support
-* And many others
-
 ## Usage
 
 ### Configuration
@@ -116,23 +106,21 @@ You can consider setting a backend with Symbol as a shortcut to set encoder.
 You can enable inference feature using `enable_inference!` method.
 
 ```ruby
-Alba.enable_inference!
+Alba.enable_inference!(with: :active_support)
 ```
 
-You must install `ActiveSupport` to enable inference.
-
-#### Error handling configuration
+You can choose which inflector Alba uses for inference. Possible value for `with` option are:
 
-You can configure error handling with `on_error` method.
-
-```ruby
-Alba.on_error :ignore
-```
+- `:active_support` for `ActiveSupport::Inflector`
+- `:dry` for `Dry::Inflector`
+- any object which responds to some methods (see [below](#custom-inflector))
 
 For the details, see [Error handling section](#error-handling)
 
 ### Simple serialization with root key
 
+You can define attributes with (yes) `attributes` macro with attribute names. If your attribute need some calculations, you can use `attribute` with block.
+
 ```ruby
 class User
   attr_accessor :id, :name, :email, :created_at, :updated_at
@@ -159,7 +147,34 @@ end
 
 user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
 UserResource.new(user).serialize
-# => "{\"id\":1,\"name\":\"Masafumi OKURA\",\"name_with_email\":\"Masafumi OKURA: masafumi@example.com\"}"
+# => "{\"user\":{\"id\":1,\"name\":\"Masafumi OKURA\",\"name_with_email\":\"Masafumi OKURA: masafumi@example.com\"}}"
+```
+
+You can define instance methods on resources so that you can use it as attribute name in `attributes`.
+
+```ruby
+# The serialization result is the same as above
+class UserResource
+  include Alba::Resource
+
+  root_key :user, :users # Later is for plural
+
+  attributes :id, :name, :name_with_email
+
+  # Attribute methods must accept one argument for each serialized object
+  def name_with_email(user)
+    "#{user.name}: #{user.email}"
+  end
+end
+```
+
+This even works with users collection.
+
+```ruby
+user1 = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
+user2 = User.new(2, 'Test User', 'test@example.com')
+UserResource.new([user1, user2]).serialize
+# => "{\"users\":[{\"id\":1,\"name\":\"Masafumi OKURA\",\"name_with_email\":\"Masafumi OKURA: masafumi@example.com\"},{\"id\":2,\"name\":\"Test User\",\"name_with_email\":\"Test User: test@example.com\"}]}"
 ```
 
 ### Serialization with associations
@@ -240,6 +255,63 @@ class AnotherUserResource
 end
 ```
 
+You can "filter" association using second proc argument. This proc takes association object and `params`.
+
+This feature is useful when you want to modify association, such as adding `includes` or `order` to ActiveRecord relations.
+
+```ruby
+class User
+  attr_reader :id
+  attr_accessor :articles
+
+  def initialize(id)
+    @id = id
+    @articles = []
+  end
+end
+
+class Article
+  attr_accessor :id, :title, :body
+
+  def initialize(id, title, body)
+    @id = id
+    @title = title
+    @body = body
+  end
+end
+
+class ArticleResource
+  include Alba::Resource
+
+  attributes :title
+end
+
+class UserResource
+  include Alba::Resource
+
+  attributes :id
+
+  # Second proc works as a filter
+  many :articles,
+    proc { |articles, params|
+      filter = params[:filter] || :odd?
+      articles.select {|a| a.id.send(filter) }
+    },
+    resource: ArticleResource
+end
+
+user = User.new(1)
+article1 = Article.new(1, 'Hello World!', 'Hello World!!!')
+user.articles << article1
+article2 = Article.new(2, 'Super nice', 'Really nice!')
+user.articles << article2
+
+UserResource.new(user).serialize
+# => '{"id":1,"articles":[{"title":"Hello World!"}]}'
+UserResource.new(user, params: {filter: :even?}).serialize
+# => '{"id":1,"articles":[{"title":"Super nice"}]}'
+```
+
 ### Inline definition with `Alba.serialize`
 
 `Alba.serialize` method is a shortcut to define everything inline.
@@ -263,9 +335,11 @@ Alba.serialize(something)
 
 Although this might be useful sometimes, it's generally recommended to define a class for Resource.
 
-### Inheritance and Ignorance
+### Inheritance and attributes filter
 
-You can `exclude` or `ignore` certain attributes using `ignoring`.
+You can filter out certain attributes by overriding `attributes` instance method. This is useful when you want to customize existing resource with inheritance.
+
+You can access raw attributes via `super` call. It returns a Hash whose keys are the name of the attribute and whose values are the body. Usually you need only keys to filter out, like below.
 
 ```ruby
 class Foo
@@ -285,7 +359,9 @@ class GenericFooResource
 end
 
 class RestrictedFooResource < GenericFooResource
-  ignoring :id, :body
+  def attributes
+    super.select { |key, _| key.to_sym == :name }
+  end
 end
 
 RestrictedFooResource.new(foo).serialize
@@ -324,14 +400,22 @@ UserResourceCamel.new(user).serialize
 # => '{"id":1,"firstName":"Masafumi","lastName":"Okura"}'
 ```
 
+Possible values for `transform_keys` argument are:
+
+* `:camel` for CamelCase
+* `:lower_camel` for lowerCamelCase
+* `:dash` for dash-case
+* `:snake` for snake_case
+* `:none` for not transforming keys
+
 You can also transform root key when:
 
 * `Alba.enable_inference!` is called
 * `root_key!` is called in Resource class
-* `root` option of `transform_keys` is set to true or `Alba.enable_root_key_transformation!` is called.
+* `root` option of `transform_keys` is set to true
 
 ```ruby
-Alba.enable_inference!
+Alba.enable_inference!(with: :active_support) # with :dry also works
 
 class BankAccount
   attr_reader :account_number
@@ -361,30 +445,29 @@ Supported transformation types are :camel, :lower_camel and :dash.
 
 #### Custom inflector
 
-A custom inflector can be plugged in as follows...
-```ruby
-Alba.inflector = MyCustomInflector
-```
-...and has to implement following interface (the parameter `key` is of type `String`):
+A custom inflector can be plugged in as follows.
+
 ```ruby
-module InflectorInterface
-  def camelize(key)
-    raise "Not implemented"
+module CustomInflector
+  module_function
+
+  def camelize(string)
+  end
+
+  def camelize_lower(string)
   end
 
-  def camelize_lower(key)
-    raise "Not implemented"
+  def dasherize(string)
   end
 
-  def dasherize(key)
-    raise "Not implemented"
+  def underscore(string)
+  end
+
+  def classify(string)
   end
 end
 
-```
-For example you could use `Dry::Inflector`, which implements exactly the above interface. If you are developing a `Hanami`-Application `Dry::Inflector` is around. In this case the following would be sufficient:
-```ruby
-Alba.inflector = Dry::Inflector.new
+Alba.enable_inference!(with: CustomInflector)
 ```
 
 ### Filtering attributes
@@ -469,7 +552,7 @@ We believe this is clearer than using some (not implemented yet) DSL such as `de
 After `Alba.enable_inference!` called, Alba tries to infer root key and association resource name.
 
 ```ruby
-Alba.enable_inference!
+Alba.enable_inference!(with: :active_support) # with :dry also works
 
 class User
   attr_reader :id
@@ -517,8 +600,6 @@ This resource automatically sets its root key to either "users" or "user", depen
 
 Also, you don't have to specify which resource class to use with `many`. Alba infers it from association name.
 
-Note that to enable this feature you must install `ActiveSupport` gem.
-
 ### Error handling
 
 You can set error handler globally or per resource using `on_error`.
@@ -562,12 +643,14 @@ There are four possible arguments `on_error` method accepts.
 The block receives five arguments, `error`, `object`, `key`, `attribute` and `resource class` and must return a two-element array. Below is an example.
 
 ```ruby
-# Global error handling
-Alba.on_error do |error, object, key, attribute, resource_class|
-  if resource_class == MyResource
-    ['error_fallback', object.error_fallback]
-  else
-    [key, error.message]
+class ExampleResource
+  include Alba::Resource
+  on_error do |error, object, key, attribute, resource_class|
+    if resource_class == MyResource
+      ['error_fallback', object.error_fallback]
+    else
+      [key, error.message]
+    end
   end
 end
 ```
@@ -624,43 +707,6 @@ UserResource.new(User.new(1)).serialize
 # => '{"user":{"id":1,"name":"User1","age":20}}'
 ```
 
-You can also set global nil handler.
-
-```ruby
-Alba.on_nil { 'default name' }
-
-class Foo
-  attr_reader :name
-  def initialize(name)
-    @name = name
-  end
-end
-
-class FooResource
-  include Alba::Resource
-
-  key :foo
-
-  attributes :name
-end
-
-FooResource.new(Foo.new).serialize
-# => '{"foo":{"name":"default name"}}'
-
-class FooResource2
-  include Alba::Resource
-
-  key :foo
-
-  on_nil { '' } # This is applied instead of global handler
-
-  attributes :name
-end
-
-FooResource2.new(Foo.new).serialize
-# => '{"foo":{"name":""}}'
-```
-
 ### Metadata
 
 You can set a metadata with `meta` DSL or `meta` option.
@@ -824,6 +870,108 @@ Also note that we use percentage notation here to use double quotes. Using singl
 
 Currently, Alba doesn't support caching, primarily due to the behavior of `ActiveRecord::Relation`'s cache. See [the issue](https://github.com/rails/rails/issues/41784).
 
+### Extend Alba
+
+Sometimes we have shared behaviors across resources. In such cases we can have a module for common logic.
+
+In `attribute` block we can call instance method so we can improve the code below:
+
+```ruby
+class FooResource
+  include Alba::Resource
+  # other attributes
+  attribute :created_at do |foo|
+    foo.created_at.strftime('%m/%d/%Y')
+  end
+
+  attribute :updated_at do |foo|
+    foo.updated_at.strftime('%m/%d/%Y')
+  end
+end
+
+class BarResource
+  include Alba::Resource
+  # other attributes
+  attribute :created_at do |bar|
+    bar.created_at.strftime('%m/%d/%Y')
+  end
+
+  attribute :updated_at do |bar|
+    bar.updated_at.strftime('%m/%d/%Y')
+  end
+end
+```
+
+to:
+
+```ruby
+module SharedLogic
+  def format_time(time)
+    time.strftime('%m/%d/%Y')
+  end
+end
+
+class FooResource
+  include Alba::Resource
+  include SharedLogic
+  # other attributes
+  attribute :created_at do |foo|
+    format_time(foo.created_at)
+  end
+
+  attribute :updated_at do |foo|
+    format_time(foo.updated_at)
+  end
+end
+
+class BarResource
+  include Alba::Resource
+  include SharedLogic
+  # other attributes
+  attribute :created_at do |bar|
+    format_time(bar.created_at)
+  end
+
+  attribute :updated_at do |bar|
+    format_time(bar.updated_at)
+  end
+end
+```
+
+We can even add our own DSL to serialize attributes for readability and removing code duplications.
+
+To do so, we need to `extend` our module. Let's see how we can achieve the same goal with this approach.
+
+```ruby
+module AlbaExtension
+  # Here attrs are an Array of Symbol
+  def formatted_time_attributes(*attrs)
+    attrs.each do |attr|
+      attribute attr do |object|
+        time = object.send(attr)
+        time.strftime('%m/%d/%Y')
+      end
+    end
+  end
+end
+
+class FooResource
+  include Alba::Resource
+  extend AlbaExtension
+  # other attributes
+  formatted_time_attributes :created_at, :updated_at
+end
+
+class BarResource
+  include Alba::Resource
+  extend AlbaExtension
+  # other attributes
+  formatted_time_attributes :created_at, :updated_at
+end
+```
+
+In this way we have shorter and cleaner code. Note that we need to use `send` or `public_send` in `attribute` block to get attribute data.
+
 ## Rails
 
 When you use Alba in Rails, you can create an initializer file with the line below for compatibility with Rails JSON encoder.

data/alba.gemspec

@@ -12,9 +12,13 @@ Gem::Specification.new do |spec|
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
 
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/okuramasafumi/alba'
-  spec.metadata['changelog_uri'] = 'https://github.com/okuramasafumi/alba/blob/main/CHANGELOG.md'
+  spec.metadata = {
+    'bug_tracker_uri' => 'https://github.com/okuramasafumi/issues',
+    'changelog_uri' => 'https://github.com/okuramasafumi/alba/blob/main/CHANGELOG.md',
+    'documentation_uri' => 'https://rubydoc.info/github/okuramasafumi/alba',
+    'source_code_uri' => 'https://github.com/okuramasafumi/alba',
+    'rubygems_mfa_required' => 'true'
+  }
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.