alba 1.1.0 → 1.5.0

data/README.md

@@ -2,6 +2,7 @@
 [![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)
 
@@ -59,18 +60,16 @@ You can find the documentation on [RubyDoc](https://rubydoc.info/github/okuramas
 
 ## Features
 
-* Resource-based serialization
-* Arbitrary attribute definition
-* One and many association with the ability to define them inline
-* Adding condition and filter to association
-* Parameters can be injected and used in attributes and associations
 * Conditional attributes and associations
 * Selectable backend
 * 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
@@ -102,6 +101,16 @@ You can set a backend like this:
 Alba.backend = :oj
 ```
 
+#### Encoder configuration
+
+You can also set JSON encoder directly with a Proc.
+
+```ruby
+Alba.encoder = ->(object) { JSON.generate(object) }
+```
+
+You can consider setting a backend with Symbol as a shortcut to set encoder.
+
 #### Inference configuration
 
 You can enable inference feature using `enable_inference!` method.
@@ -122,7 +131,7 @@ Alba.on_error :ignore
 
 For the details, see [Error handling section](#error-handling)
 
-### Simple serialization with key
+### Simple serialization with root key
 
 ```ruby
 class User
@@ -139,7 +148,7 @@ end
 class UserResource
   include Alba::Resource
 
-  key :user
+  root_key :user
 
   attributes :id, :name
 
@@ -202,12 +211,41 @@ 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
+```
+
 ### 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
@@ -216,6 +254,13 @@ 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
@@ -239,20 +284,21 @@ class GenericFooResource
   attributes :id, :name, :body
 end
 
-class RestrictedFooResouce < GenericFooResource
+class RestrictedFooResource < GenericFooResource
   ignoring :id, :body
 end
 
-RestrictedFooResouce.new(foo).serialize
+RestrictedFooResource.new(foo).serialize
 # => '{"name":"my foo"}'
-end
 ```
 
-### Attribute key transformation
+### Key transformation
 
-** Note: You need to install `active_support` gem to use `transform_keys` DSL.
+If you want to use `transform_keys` DSL and you already have `active_support` installed, key transformation will work out of the box, using `ActiveSupport::Inflector`. If `active_support` is not around, you have 2 possibilities:
+* install it
+* use a [custom inflector](#custom-inflector)
 
-With `active_support` installed, you can transform attribute keys.
+With `transform_keys` DSL, you can transform attribute keys.
 
 ```ruby
 class User
@@ -278,8 +324,69 @@ UserResourceCamel.new(user).serialize
 # => '{"id":1,"firstName":"Masafumi","lastName":"Okura"}'
 ```
 
+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.
+
+```ruby
+Alba.enable_inference!
+
+class BankAccount
+  attr_reader :account_number
+
+  def initialize(account_number)
+    @account_number = account_number
+  end
+end
+
+class BankAccountResource
+  include Alba::Resource
+
+  root_key!
+
+  attributes :account_number
+  transform_keys :dash, root: true
+end
+
+bank_account = BankAccount.new(123_456_789)
+BankAccountResource.new(bank_account).serialize
+# => '{"bank-account":{"account-number":123456789}}'
+```
+
+This behavior to transform root key will become default at version 2.
+
 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`):
+```ruby
+module InflectorInterface
+  def camelize(key)
+    raise "Not implemented"
+  end
+
+  def camelize_lower(key)
+    raise "Not implemented"
+  end
+
+  def dasherize(key)
+    raise "Not implemented"
+  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
+```
+
 ### Filtering attributes
 
 You can filter attributes by overriding `Alba::Resource#converter` method, but it's a bit tricky.
@@ -343,6 +450,20 @@ 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.
@@ -451,12 +572,254 @@ Alba.on_error do |error, object, key, attribute, resource_class|
 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}}'
+```
+
+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.
+
+```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.**
+
 You can control circular associations with `within` option. `within` option is a nested Hash such as `{book: {authors: books}}`. In this example, Alba serializes a book's authors' books. This means you can reference `BookResource` from `AuthorResource` and vice versa. This is really powerful when you have a complex data structure and serialize certain parts of it.
 
 For more details, please refer to [test code](https://github.com/okuramasafumi/alba/blob/master/test/usecases/circular_association_test.rb)
 
+### Experimental support of types
+
+You can validate and convert input with types.
+
+```ruby
+class User
+  attr_reader :id, :name, :age, :bio, :admin, :created_at
+
+  def initialize(id, name, age, bio = '', admin = false) # rubocop:disable Style/OptionalBooleanParameter
+    @id = id
+    @name = name
+    @age = age
+    @admin = admin
+    @bio = bio
+    @created_at = Time.new(2020, 10, 10)
+  end
+end
+
+class UserResource
+  include Alba::Resource
+
+  attributes :name, id: [String, true], age: [Integer, true], bio: String, admin: [:Boolean, true], created_at: [String, ->(object) { object.strftime('%F') }]
+end
+
+user = User.new(1, 'Masafumi OKURA', '32', 'Ruby dev')
+UserResource.new(user).serialize
+# => '{"name":"Masafumi OKURA","id":"1","age":32,"bio":"Ruby dev","admin":false,"created_at":"2020-10-10"}'
+```
+
+Notice that `id` and `created_at` are converted to String and `age` is converted to Integer.
+
+If type is not correct and auto conversion is disabled (default), `TypeError` occurs.
+
+```ruby
+user = User.new(1, 'Masafumi OKURA', '32', nil) # bio is nil and auto conversion is disabled for bio
+UserResource.new(user).serialize
+# => TypeError, 'Attribute bio is expected to be String but actually nil.'
+```
+
+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).

data/SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.y   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+If you find a vulnerability of Alba, please contact me (OKURA Masafumi) via [email](masafumi.o1988@gmail.com). I'll report back within a few days.

data/alba.gemspec

@@ -7,14 +7,14 @@ Gem::Specification.new do |spec|
   spec.email         = ['masafumi.o1988@gmail.com']
 
   spec.summary       = 'Alba is the fastest JSON serializer for Ruby.'
-  spec.description   = "Alba is designed to be a simple, easy to use and fast alternative to existing JSON serializers. Its performance is better than almost all gems which do similar things. The internal is so simple that it's easy to hack and maintain."
+  spec.description   = "Alba is the fastest JSON serializer for Ruby. It focuses on performance, flexibility and usability."
   spec.homepage      = 'https://github.com/okuramasafumi/alba'
   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['changelog_uri'] = 'https://github.com/okuramasafumi/alba/blob/main/CHANGELOG.md'
 
   # 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.