README.md in alba-1.2.0 vs README.md in alba-1.3.0
- old
+ new
@@ -64,11 +64,11 @@
* Key transformation
* Root key inference
* Error handling
* Resource name inflection based on association name
* Circular associations control
-* Types for validation and conversion
+* [Experimental] Types for validation and conversion
* No runtime dependencies
## Anti features
* Sorting keys
@@ -244,13 +244,15 @@
end
```
### 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
attr_reader :id, :first_name, :last_name
@@ -307,10 +309,38 @@
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.
```ruby
@@ -480,15 +510,17 @@
end
```
### 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)
-### Types
+### Experimental support of types
You can validate and convert input with types.
```ruby
class User
@@ -522,9 +554,11 @@
```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.
### 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).