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).