alba 1.3.0 → 1.6.0

data/README.md

@@ -19,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
 
@@ -64,20 +64,13 @@ You can find the documentation on [RubyDoc](https://rubydoc.info/github/okuramas
 * Key transformation
 * Root key inference
 * Error handling
+* Nil handling
 * Resource name inflection based on association name
 * Circular associations control
 * [Experimental] Types for validation and conversion
+* 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
@@ -98,27 +91,35 @@ You can set a backend like this:
 Alba.backend = :oj
 ```
 
-#### Inference configuration
+#### Encoder configuration
 
-You can enable inference feature using `enable_inference!` method.
+You can also set JSON encoder directly with a Proc.
 
 ```ruby
-Alba.enable_inference!
+Alba.encoder = ->(object) { JSON.generate(object) }
 ```
 
-You must install `ActiveSupport` to enable inference.
+You can consider setting a backend with Symbol as a shortcut to set encoder.
 
-#### Error handling configuration
+#### Inference configuration
 
-You can configure error handling with `on_error` method.
+You can enable inference feature using `enable_inference!` method.
 
 ```ruby
-Alba.on_error :ignore
+Alba.enable_inference!(with: :active_support)
 ```
 
+You can choose which inflector Alba uses for inference. Possible value for `with` option are:
+
+- `: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 key
+### 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
@@ -135,7 +136,7 @@ end
 class UserResource
   include Alba::Resource
 
-  key :user
+  root_key :user
 
   attributes :id, :name
 
@@ -146,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
@@ -198,12 +226,98 @@ UserResource.new(user).serialize
 # => '{"id":1,"articles":[{"title":"Hello World!"},{"title":"Super nice"}]}'
 ```
 
+You can define associations inline if you don't need a class for association.
+
+```ruby
+class ArticleResource
+  include Alba::Resource
+
+  attributes :title
+end
+
+class UserResource
+  include Alba::Resource
+
+  attributes :id
+
+  many :articles, resource: ArticleResource
+end
+
+# This class works the same as `UserResource`
+class AnotherUserResource
+  include Alba::Resource
+
+  attributes :id
+
+  many :articles do
+    attributes :title
+  end
+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.
 
 ```ruby
-Alba.serialize(user, key: :foo) do
+Alba.serialize(user, root_key: :foo) do
   attributes :id
   many :articles do
     attributes :title, :body
@@ -212,11 +326,20 @@ end
 # => '{"foo":{"id":1,"articles":[{"title":"Hello World!","body":"Hello World!!!"},{"title":"Super nice","body":"Really nice!"}]}}'
 ```
 
+`Alba.serialize` can be used when you don't know what kind of object you serialize. For example:
+
+```ruby
+Alba.serialize(something)
+# => Same as `FooResource.new(something).serialize` when `something` is an instance of `Foo`.
+```
+
 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
@@ -235,13 +358,14 @@ class GenericFooResource
   attributes :id, :name, :body
 end
 
-class RestrictedFooResouce < GenericFooResource
-  ignoring :id, :body
+class RestrictedFooResource < GenericFooResource
+  def attributes
+    super.select { |key, _| key.to_sym == :name }
+  end
 end
 
-RestrictedFooResouce.new(foo).serialize
+RestrictedFooResource.new(foo).serialize
 # => '{"name":"my foo"}'
-end
 ```
 
 ### Key transformation
@@ -276,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
-* `key!` is called in Resource class
-* `root` option of `transform_keys` is set to true or `Alba.enable_root_key_transformation!` is called.
+* `root_key!` is called in Resource class
+* `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
@@ -296,7 +428,7 @@ end
 class BankAccountResource
   include Alba::Resource
 
-  key!
+  root_key!
 
   attributes :account_number
   transform_keys :dash, root: true
@@ -313,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(key)
-    raise "Not implemented"
+  def camelize_lower(string)
   end
 
-  def dasherize(key)
-    raise "Not implemented"
+  def dasherize(string)
+  end
+
+  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
@@ -402,12 +533,26 @@ user = User.new(1, nil, nil)
 UserResource.new(user).serialize # => '{"id":1}'
 ```
 
+### Default
+
+Alba doesn't support default value for attributes, but it's easy to set a default value.
+
+```ruby
+class FooResource
+  attribute :bar do |foo|
+    foo.bar || 'default bar'
+  end
+end
+```
+
+We believe this is clearer than using some (not implemented yet) DSL such as `default` because there are some conditions where default values should be applied (`nil`, `blank?`, `empty?` etc.)
+
 ### Inference
 
 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
@@ -455,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`.
@@ -500,16 +643,118 @@ 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
 ```
 
+### Nil handling
+
+Sometimes we want to convert `nil` to different values such as empty string. Alba provides a flexible way to handle `nil`.
+
+```ruby
+class User
+  attr_reader :id, :name, :age
+
+  def initialize(id, name = nil, age = nil)
+    @id = id
+    @name = name
+    @age = age
+  end
+end
+
+class UserResource
+  include Alba::Resource
+
+  on_nil { '' }
+
+  root_key :user, :users
+
+  attributes :id, :name, :age
+end
+
+UserResource.new(User.new(1)).serialize
+# => '{"user":{"id":1,"name":"","age":""}}'
+```
+
+You can get various information via block parameters.
+
+```ruby
+class UserResource
+  include Alba::Resource
+
+  on_nil do |object, key|
+    if key == age
+      20
+    else
+      "User#{object.id}"
+    end
+  end
+
+  root_key :user, :users
+
+  attributes :id, :name, :age
+end
+
+UserResource.new(User.new(1)).serialize
+# => '{"user":{"id":1,"name":"User1","age":20}}'
+```
+
+### Metadata
+
+You can set a metadata with `meta` DSL or `meta` option.
+
+```ruby
+class UserResource
+  include Alba::Resource
+
+  root_key :user, :users
+
+  attributes :id, :name
+
+  meta do
+    if object.is_a?(Enumerable)
+      {size: object.size}
+    else
+      {foo: :bar}
+    end
+  end
+end
+
+user = User.new(1, 'Masafumi OKURA', 'masafumi@example.com')
+UserResource.new([user]).serialize
+# => '{"users":[{"id":1,"name":"Masafumi OKURA"}],"meta":{"size":1}}'
+
+# You can merge metadata with `meta` option
+
+UserResource.new([user]).serialize(meta: {foo: :bar})
+# => '{"users":[{"id":1,"name":"Masafumi OKURA"}],"meta":{"size":1,"foo":"bar"}}'
+
+# You can set metadata with `meta` option alone
+
+class UserResourceWithoutMeta
+  include Alba::Resource
+
+  root_key :user, :users
+
+  attributes :id, :name
+end
+
+UserResource.new([user]).serialize(meta: {foo: :bar})
+# => '{"users":[{"id":1,"name":"Masafumi OKURA"}],"meta":{"foo":"bar"}}'
+```
+
+You can use `object` method to access the underlying object and `params` to access the params in `meta` block.
+
+Note that setting root key is required when setting a metadata.
+
 ### Circular associations control
 
 **Note that this feature works correctly since version 1.3. In previous versions it doesn't work as expected.**
@@ -559,10 +804,174 @@ UserResource.new(user).serialize
 
 Note that this feature is experimental and interfaces are subject to change.
 
+### Layout
+
+Sometimes we'd like to serialize JSON into a template. In other words, we need some structure OUTSIDE OF serialized JSON. IN HTML world, we call it a "layout".
+
+Alba supports serializing JSON in a layout. You need a file for layout and then to specify file with `layout` method.
+
+```erb
+{
+  "header": "my_header",
+  "body": <%= serialized_json %>
+}
+```
+
+```ruby
+class FooResource
+  include Alba::Resource
+  layout file: 'my_layout.json.erb'
+end
+```
+
+Note that layout files are treated as `json` and `erb` and evaluated in a context of the resource, meaning
+
+* A layout file must be a valid JSON
+* You must write `<%= serialized_json %>` in a layout to put serialized JSON string into a layout
+* You can access `params` in a layout so that you can add virtually any objects to a layout
+  * When you access `params`, it's usually a Hash. You can use `encode` method in a layout to convert `params` Hash into a JSON with the backend you use
+* You can also access `object`, the underlying object for the resource
+
+In case you don't want to have a file for layout, Alba lets you define and apply layouts inline:
+
+```ruby
+class FooResource
+  include Alba::Resource
+  layout inline: proc do
+    {
+      header: 'my header',
+      body: serializable_hash
+    }
+  end
+end
+```
+
+In the example above, we specify a Proc which returns a Hash as an inline layout. In the Proc we can use `serializable_hash` method to access a Hash right before serialization.
+
+You can also use a Proc which returns String, not a Hash, for an inline layout.
+
+```ruby
+class FooResource
+  include Alba::Resource
+  layout inline: proc do
+    %({
+      "header": "my header",
+      "body": #{serialized_json}
+    })
+  end
+end
+```
+
+It looks similar to file layout but you must use string interpolation for method calls since it's not an ERB.
+
+Also note that we use percentage notation here to use double quotes. Using single quotes in inline string layout causes the error which might be resolved in other ways.
+
 ### Caching
 
 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/master/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.