simple_ams 0.2.1 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e9a6bbc4ee5adfd199a3a3aa79ae6609e578e600e4ca1f93888efb2263f9b39
-  data.tar.gz: 3d25a70ad671b9ca9b57e229070dcb029d5368bc7f503335628fe761ee325a30
+  metadata.gz: d2221682d109248b00a4d4d8a99b8bac469cd76ec60ad4e5710c9b56e43bbf5f
+  data.tar.gz: 0aa48e2d0e09dd36cc8b31ef3daff832059e5d01ea5b090648def84c677de036
 SHA512:
-  metadata.gz: 49f94ebf51efda1776abda3e7db9aa8a6a75b1ad25fe566a43a862e4bf4af6efc77c3d777138ba62c410d4be30ad5293eab0edf7eaf8729b775faff3ef0a1b84
-  data.tar.gz: 2a287e0f5d6b368f509a95f10777ff8e41bf57bcde11588ede23a0132d4fc1d8b4493c8aebb7e1292ac6ccd179bb737fd9c10c59ba78240ce68112a6887fdf20
+  metadata.gz: e8355af588f6efa58699e0394d3d913c56e16d1573e334930512f971c80a20f285e8200c9d74bd634e07a81de5e79915d7bd694afe6e76161f8b9a592c4a0896
+  data.tar.gz: 38f6bbb2a0493870544866eb04a9501db97232f97b02dd647aeeea83f336e2cf8ae8d7979553aa74ad8cab7d409e06cabec6949b375080d3c96d850f290654fd

data/.github/workflows/ruby.yml

@@ -0,0 +1,28 @@
+name: Ruby
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest ]
+        ruby: [ 2.5, 2.6, 2.7, '3.0', truffleruby ]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - name: Install dependencies
+      run: bundle install
+    - name: Rubocop
+      run: bundle exec rubocop
+    - name: Run tests
+      run: bundle exec rspec spec

data/.rubocop.yml

@@ -0,0 +1,56 @@
+AllCops:
+  NewCops: enable
+Style/FrozenStringLiteralComment:
+  Enabled: false
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+Metrics/ModuleLength:
+  Max: 250
+Metrics/ClassLength:
+  Max: 250
+Metrics/MethodLength:
+  Max: 50
+Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - 'spec/**/*.rb'
+Metrics/AbcSize:
+  Max: 50
+Lint/UnreachableLoop:
+  Exclude:
+    - 'spec/**/*.rb'
+Style/Documentation:
+  Enabled: false
+Lint/UnderscorePrefixedVariableName:
+  Exclude:
+    - 'spec/**/*.rb'
+    - 'lib/simple_ams/options.rb'
+    - 'lib/simple_ams/dsl.rb'
+Naming/MemoizedInstanceVariableName:
+  Exclude:
+    - 'lib/simple_ams/options.rb'
+    - 'lib/simple_ams/dsl.rb'
+Lint/SuppressedException:
+  Exclude:
+    - 'spec/**/*.rb'
+Metrics/PerceivedComplexity:
+  Max: 14
+  Exclude:
+    - 'spec/**/*.rb'
+Metrics/CyclomaticComplexity:
+  Max: 14
+  Exclude:
+    - 'spec/**/*.rb'
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - 'spec/**/*.rb'
+Style/OptionalArguments:
+  Exclude:
+    - 'lib/simple_ams/options/relations.rb'
+Naming/PredicateName:
+  Exclude:
+    - 'lib/simple_ams/dsl.rb'
+Lint/MissingSuper:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+**0.2.6**
+* [#45](https://github.com/vasilakisfil/SimpleAMS/pull/45) add changelog
+* [#44](https://github.com/vasilakisfil/SimpleAMS/pull/44) add Ruby 3.0 support
+* [#42](https://github.com/vasilakisfil/SimpleAMS/pull/42) fix bug when more than 1 nested relations where specified on Renderer
+* [#37](https://github.com/vasilakisfil/SimpleAMS/pull/37) Use Rubocop to lint
+* [#34](https://github.com/vasilakisfil/SimpleAMS/pull/34) update README with detailed documentation and examples
+* [#31](https://github.com/vasilakisfil/SimpleAMS/pull/31) improve serializer inference when collection is not an array
+
+**v0.2.5**
+* [#28](https://github.com/vasilakisfil/SimpleAMS/pull/28) fix repo reference in gemspec
+* [#27](https://github.com/vasilakisfil/SimpleAMS/pull/27) fixes bug when rendering polymorphic collections (properly cleans serializer variable)
+
+**v0.2.3**
+* [#24](https://github.com/vasilakisfil/SimpleAMS/pull/24) add travis for CI
+* fixes on JSON:API adapter (`skip_data` option)
+* small performance improvements
+
+**0.2.1**
+* various bug fixes and performance improvements
+
+**0.1.5**
+* first stable release

data/Gemfile

@@ -1,6 +1,6 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in SimpleAMS.gemspec
 gemspec

data/README.md

@@ -1,9 +1,48 @@
+[![Build Status](https://travis-ci.org/vasilakisfil/SimpleAMS.svg?branch=master)](https://travis-ci.org/vasilakisfil/SimpleAMS)
+
 # SimpleAMS
 > "Simple things should be simple and complex things should be possible." Alan Kay.
 
 If we want to interact with modern APIs we should start building modern, flexible libraries
 that help developers to build such APIs. Modern Ruby serializers, as I always wanted them to be.
 
+You can find the core ideas, the reasoning behind the architecture, use cases
+and examples [here](https://vasilakisfil.social/blog/2020/01/20/modern-ruby-serializers/).
+
+## Table of contents
+
+1. [Installation](#installation)
+2. [Usage](#usage)
+    * [Simple case](#simple-case)
+        - [Rendering a resource](#rendering-a-resource)
+        - [Rendering a collection](#rendering-a-collection)
+    * [Serializer DSL](#serializer-dsl)
+        - [fields directive](#fields-directive)
+        - [Relations (has_many/has_one/belongs_to)](#relations-has_manyhas_onebelongs_to)
+            * [relations are recursive](#relations-are-recursive)
+            * [embedded content (again recursive)](#embedded-content-again-recursive)
+            * [relation name/type](#relation-nametype)
+        - [value-hashmap type of directives](#value-hashmap-type-of-directives)
+            * [adapter](#adapter)
+            * [primary_id](#primary_id)
+            * [type](#type)
+        - [name-value-hashmap type of directives](#name-value-hashmap-type-of-directives)
+            * [link](#link)
+            * [meta](#meta)
+            * [form](#form)
+            * [generic](#generic)
+            * [group of link/meta/form/generic](#group-of-linksmetasformsgenerics)
+        - [collection directive](#collection-directive)
+    * [Rendering DSL](#rendering-dsl)
+        - [includes vs relations](#includes-vs-relations)
+        - [Rendering collections](#rendering-collections)
+        - [Rendering options with values](#rendering-options-with-values)
+        - [Exposing methods inside the serializer, like helpers](#exposing-methods-inside-the-serializer-like-helpers)
+    * [Extended DSL show off](#extended-dsl-show-off)
+3. [Development](#development)
+4. [Contributing](#contributing)
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -21,103 +60,651 @@ Or install it yourself as:
     $ gem install simple_ams
 
 ## Usage
-The gem's interface has been inspired by ActiveModel Serializers 0.9.2, 0.10.stable, jsonapi-rb and Ember Data.
-However, **it has been built for POROs, does not rely in any dependency and does not relate to Rails in any case** other than
-some nostalgia for the (advanced at that time) pre-0.10 ActiveModel Serialiers.
+The gem's interface has been inspired by ActiveModel Serializers 0.9.2,
+0.10.stable, jsonapi-rb and Ember Data.
+However, it has been built for POROs, **has zero dependencies** and does not
+relate to Rails in any case other than some nostalgia for the (advanced at that
+time) pre-0.10 ActiveModel Serialiers.
 
+You can find the core ideas, the reasoning behind the architecture, use cases and examples [here](https://vasilakisfil.social/blog/2020/01/20/modern-ruby-serializers/).
 
 ### Simple case
-
 You will rarely need all the advanced options. Usually you will have something like that:
 
 ```ruby
 class UserSerializer
   include SimpleAMS::DSL
 
-  #specify the adapter, pass some options all the way down to the adapter
-  adapter SimpleAMS::Adapters::JSONAPI, root: true
-
-  #specify available attributes/fields
-  attributes :id, :name, :email, :birth_date
-
-  #specify available relations
-  has_one :profile, serializer: ProfileSerializer
-  #belongs_to is just an alias to has_one
-  belongs_to :organization, serializer: OrganizationSerializer
-  has_many :videos, serializer: VideosSerializer do
-    #rarely used: if you need more options, you can pas a block
-    #which adheres to the same DSL as described here
-    #it goes to an option called `embedded`
-    #essentially these options here should be used for linking current resource
-    #with the relation (useful for JSONAPI for instance)
-    generic :include_data, false
-  end
+  #specify the adapter we want to use
+  adapter SimpleAMS::Adapters::JSONAPI
 
-  #specify some links
-  link :feed, '/api/v1/me/feed'
-  #links can also take other options, as specified by RFC 8288
-  link :root, '/api/v1/', rel: :user
-  #link values can be dynamic as well through lambdas
-  #lambdas take arguments the object to be serialized and the instantiated serializer
-  link :posts, ->(obj, s) { s.api_v1_user_followers_path(user_id: obj.id) }, rel: :user
-  #if you also need dynamic options, you can return an array from the lambda
-  link :followers, ->(obj, s) { ["/api/v1/users/#{obj.id}/followers/", rel: obj.type] }
-
-  #same with metas: can be static, dynamic and accept arbitrary options
-  meta :environment, ->(obj, s) { Rails.env.to_s }
-
-  #same with form: can be static, dynamic and accept arbitrary options
-  form :create, ->(obj, s) { User::CreateForm.for(obj) }
-
-  #or if you need something quite generic (and probably adapter-related)
-  #again it follows the same patterns as link
-  generic :include_embedded_data, true, {only: :collection}
-
-  #these are properties to the collection resource itself
-  #AND NOT to each resource separately, when applied inside a collection..
-  #It's a rarely used feature but definitely nice to have..
-  collection do
-    #collection accepts exactly the same aforementioned interface
-    #here we use only links and meta
-    link :root, '/api/v1/', rel: :user
-    type :users
-    meta :count, ->(collection, s) { collection.count }
-  end
+  #specify the attributes we want to serialize from the given object
+  attributes :id, :name, :email, :created_at, :role
 
-  #note that most probably the only thing that you will need here is the `type`,
-  #so there is a shortcut if you just need to specify the collection name/type:
-  #collection :users
-
-  #override an attribute
-  def name
-    "#{object.first_name} #{object.last_name}"
-  end
+  #specify the type of the resource
+  type :user
+  #specify the name of the collection
+  collection :users
 
-  #override a relation
-  def videos
-    Videos.where(user_id: object.id).published
-  end
+  #specify a relation. Here microposts serves as both a name of the collection
+  #and the name of the method used to retrieve the values of the collection
+  #from the given object
+  has_many :microposts
 end
 ```
 
-Then you can just feed your serializer with data, along with some options:
+
+#### Rendering a resource
+Then you can just feed your serializer with data:
 
 ```ruby
-SimpleAMS::Renderer.new(user, fields: [:id, :name, :email], includes: [:videos]).to_json
+SimpleAMS::Renderer.new(user).to_json
 ```
 `to_json` first calls `as_json`, which creates a ruby Hash and then `to_json` is called
 on top of that hash.
 
+If you want to filter the available options (defined by the serializer) when you
+instantiate the serializer, `Renderer` accepts an options hash. In there you can
+throw pretty much the same DSL:
+
+```ruby
+SimpleAMS::Renderer.new(user, {
+  serializer: UserSerializer, fields: [:id, :name, :email], includes: []
+}).to_json
+```
+
+Here we say that we only want 3 specific fields, and no relations at all.
+
+
+#### Rendering a collection
+Rendering a collection is pretty similar, meaning that it reuses the same serializer
+class, and accepts the same runtime options. The only difference is that you need
+to call a different class.
+
+```ruby
+SimpleAMS::Renderer::Collection.new(users, {
+  serializer: UserSerializer, fields: [:id, :email, :name], includes: []
+}).to_json
+```
+
+### Serializer DSL
+The serializer is a very robust, yet simple, with a hash-based internal
+representation.
+
+#### fields directive
+Fields specify the attributes that the serializer will hold.
+The values of each attribute is taken by the to-be serialized object,
+unless the serializer has a method of the same name.
+
+```ruby
+fields :id, :name, :email, :created_at, :role
+```
+
+
+Using `attributes` is also valid, it’s just an [alias](https://github.com/vasilakisfil/SimpleAMS/blob/master/lib/simple_ams/dsl.rb#L130-L137) after all:
+
+```ruby
+attributes :id, :name, :email, :created_at, :role
+```
+
+
+Of course, any field can be overridden by defining a method of the same name
+inside the serializer.
+In there, you can have access to a method called object which holds the actual
+resource to be serialized:
+
+```ruby
+def name
+  "#{object.first_name} #{object.last_name}"
+end
+```
+
+
+#### Relations (has_many/has_one/belongs_to)
+These directives allows you to append relations in a resource.
+`has_one` is just an alias of `belongs_to` since there is no real difference in
+APIs (although internally and in adapters, SimpleAMS knows if you specified the
+relation using`belongs_to` or `has_one`, making it future proof in case API specs
+decide to support each one in a different way).
+
+```ruby
+has_many :microposts
+```
+
+Again, it can be overridden by defining a method of the same name:
+
+```ruby
+def microposts
+  Post.where(user_id: object.id).order(:created_at, :desc).limit(10)
+end
+```
+
+##### relations are recursive
+The relations directives can take the same options as the rendering.
+
+```ruby
+#overriding the serializer
+has_many :microposts, serializer: CustomPostsSerializer
+#overriding the serializer and fields that should be included
+has_many :microposts, serializer: CustomPostsSerializer, fields: [:content]
+#overriding the serializer, fields and relations that should be included
+has_many :microposts, serializer: CustomPostsSerializer, fields: [:content],
+  includes: []
+#overriding the serializer, fields, relations and links
+has_many :microposts, serializer: CustomPostsSerializer, fields: [:content],
+  includes: [], links: [:self]
+```
+
+
+When overriding from the relations directives (or when rendering in general) you
+are able to override any directive defined in the serializer to acquire a subset
+**but never a superset**.
+
+##### embedded content (again recursive)
+Sometimes, an annoying spec might define parts of a relation in the main body,
+while parts of the relation somewhere else. For instance, JSON:API does that by
+having some links in the main body and the rest in the included section.
+That’s also possible if you pass a block in the relation directive:
+
+```ruby
+has_many :microposts, serializer: MicropostsSerializer, fields: [:content] do
+  #these goes to a class named `Embedded`, attached to the relation
+  link :self, ->(obj){ "/api/v1/users/#{obj.id}/relationships/microposts" }
+  link :related, ->(obj){ ["/api/v1/users/1", rel: :user] }
+end
+```
+
+Inside that block, you can pass any parameter the original DSL supports and will
+be stored in an Embedded class under MicropostsSerializer.
+Btw SimpleAMS is smart enough (one of the very few cases that acts like that) to
+figure out that if a lambda returns something that’s not an array, then this must
+be the value, while options are just empty.
+
+##### relation name/type
+Sometimes, we want to detach the relation’s name from the type. In the previous
+example `microposts` is the relation name (whatever that means), while the type
+is defined by the `MicropostsSerializer`, unless we override it, which can be
+done either in the relation serializer itself, or when we use the relation from
+the parent serializer:
+
+```ruby
+has_many :microposts, serializer: MicropostsSerializer, fields: [:content], type: :feed do
+  link :self, ->(obj){ "/api/v1/users/#{obj.id}/relationships/microposts" }
+  link :related, ->(obj){ ["/api/v1/users/1", rel: :user] }
+end
+```
+
+Internally SimpleAMS, differentiates type from name, and usually type is
+something that’s semantically stronger (like a relation type) than name.
+You can even inject the name of the relation using the name option:
+
+```ruby
+has_many :microposts, serializer: MicropostsSerializer, fields: [:content], type: :feed, name: :posts do
+  link :self, ->(obj){ "/api/v1/users/#{obj.id}/relationships/microposts" }
+  link :related, ->(obj){ ["/api/v1/users/1", rel: :user] }
+end
+```
+
+As I said, the name, which is usually the name of the attribute that includes
+the relation in the JSON format, doesn’t really have any semantic meaning in
+most specs. At least I haven’t seen any spec to depend on the root attribute
+name of the relation. Instead it’s the type that’s important, because type is
+what the [web linking RFC defines](https://tools.ietf.org/html/rfc8288#section-2).
+
+#### value-hashmap type of directives
+These are directives like adapter. They take a value, and optionally a hashmap,
+which are options to be passed down straight to the adapter, hence they are adapter specific.
+Such options are `primary_id`, `type` and `adapter`
+
+For instance, for adapter it could be:
+```ruby
+adapter SimpleAMS::Adapters::JSONAPI, root: true
+```
+
+Of course, since we are talking about Ruby here, it would be a huge restriction
+to not allow dynamic value/hashmap combination. Basically any such directive
+can accept a lambda (generally anything that responds to `call`) and should
+return an array where the first part is the value and (optionally) the second part is the
+options. There is an argument that is passed down to the function/lambda, and
+that’s the actual object. For instance, to support polymorphic resources you
+can have the type dynamic:
+
+```ruby
+type ->(obj, s){ obj.employee? ? [:employee, {}] : [:user, {}]}
+```
+
+One of the very few times that SimpleAMS acts smart is inside the lambda, that
+if you have only a value (not an Array), it will take that as the value, while
+the options will be taken by the second argument, after the lambda. So the
+above is equivalent with:
+
+```ruby
+type ->(obj, s){ obj.employee? ? :employee : :user}, {}
+```
+
+Note: you shouldn't use that in case of adapter, as that's the definition of UB :P
+
+
+<details>
+<summary id="adapter">adapter</summary>
+
+Specifies the adapter to be used. The `adapter` method is the only one that does
+not support lambda as it's value, as that would be the definition of undefined
+behavior. If you want to support polymorphic collections, you should use the `type`
+instead in combination with the `serializer`.
+
+```ruby
+#without options
+adapter SimpleAMS::Adapters::JSONAPI
+#with adapter-specific options
+adapter SimpleAMS::Adapters::JSONAPI, {root: false}
+```
+
+Note that you can even specify your own adapter. Usually you will want to inherit
+from an existing adapter (like `SimpleAMS::Adapters::AMS`), but that's not a
+requirement. All you need is to duck type to 2 methods:
+* `initialize(document, options = {})` be able to accept 2 arguments when your adapter
+  is instantiated. The first one is a document, while the second one is the adapter-specific
+  options (like the `{root: false}`.
+* `as_json` method returns that returns the hash representation of the serialized result
+
+The conversion of a Hash into raw JSON string is out of the scope of this library.
+But you will probably want to use the fastest implementation possible like [oj](https://github.com/ohler55/oj).
+</details>
+
+<details>
+<summary id="primary_id">primary_id</summary>
+
+Specifies the `primary_id` to be used. There are many API specs that handle the
+identifier of a resource in a different way than the rest of the attributes.
+JSON:API is one of those.
+
+```ruby
+#without options
+primary_id :id
+#with adapter-specific options
+adapter :id, {external: true}
+#dynamic
+adapter ->(obj, s) { [obj.class.primary_key, {}]}
+```
+
+
+</details>
+
+<details>
+<summary id="type">type</summary>
+
+Specifies the `type` to be used. There are many API specs that handle the
+type of a resource in a different way than the rest of the attributes.
+JSON:API is one of those.
+
+```ruby
+#without options
+type :user
+#with adapter-specific options
+type :user, {polymorphic: false}
+#dynamic
+type ->(obj, s){ obj.employee? ? [:employee, {}] : [:user, {}]}
+```
+
+</details>
+
+
+
+#### name-value-hashmap type of directives
+These are similar to the above, only that they also have an actual value, which
+is converted to a representation through the adapter.
+Such options are `link`, `meta`, `form` and the most generic directive `generic`.
+
+For instance, think about a links. According to RFC [8288](https://tools.ietf.org/html/rfc8288#section-2), a link has
+
+* a link context,
+* a link relation type,
+* a link target, and
+* optionally, target attributes
+
+Now, if we wanted to translate that to our serializers, a link could look like:
+```ruby
+link :feed, '/api/v1/me/feed', {style: :compact}
+```
+
+Here obviously the link context is the serializer itself, the link relation is
+the feed, and the value is `/api/v1/me/feed`. Now you might say, feed should be
+the name of the link which is different from the relation type.
+The relation type could be `microposts`.
+And actually, that’s the case for [JSONAPI v1.1](https://jsonapi.org/format/1.1/).
+In that case, the feed should be treated barely as a name (whatever that means)
+and relation type will be put inside the link options like:
+
+```ruby
+link :feed, '/api/v1/me/feed', {rel: :microposts, style: :compact}
+```
+
+Note however that this needs to be supported by the adapter you are using.
+
+Similar to the case of value-hash directives, it is possible to have dynamic
+value and options:
+
+```ruby
+#values can be dynamic through lambdas
+#lambdas take arguments the object to be serialized and the instantiated serializer
+link :feed, ->(obj, s) { [s.api_v1_user_feed_path(user_id: obj.id), {rel: :feed} }
+#if the value inside the lambda is single (no array), the options will be taken from
+#the second argument, after the lambda. So the above is equivelent to:
+link :feed, ->(obj, s) { s.api_v1_user_feed_path(user_id: obj.id) }, rel: :feed
+```
+
+<details>
+<summary id="link">link</summary>
+
+Specifies a link to be used. There are many API specs that handle the links of a
+resource in a special way (JSON:API is one of those).
+You can specify multiple links, as long as each link name is unique.
+
+```ruby
+#specifying a link with without options
+link :feed, "/api/v1/feed"
+#specifying a link with options
+link :feed, "/api/v1/feed", {rel: :feed, compact: true}
+#values can be dynamic through lambdas
+#lambdas take arguments the object to be serialized and the instantiated serializer
+link :feed, ->(obj, s) { [s.api_v1_user_feed_path(user_id: obj.id), {rel: :feed, compact: true}] }
+#if the value inside the lambda is single (no array), the options will be taken from
+#the second argument, after the lambda. So the above is equivelent to:
+link :feed, ->(obj, s) { s.api_v1_user_feed_path(user_id: obj.id) }, rel: :feed, compact: true
+```
+
+</details>
+
+<details>
+<summary id="meta">meta</summary>
+
+Specifies a meta to be used. There are many API specs that handle the metas of a
+resource in a special way (JSON:API is one of those).
+You can specify multiple metas, as long as each link name is unique.
+
+```ruby
+#specifying a meta with without options
+meta :total_count, 1
+#specifying a meta with options
+meta :total_count, 1, {compact: true}
+#values can be dynamic through lambdas
+#lambdas take arguments the object to be serialized and the instantiated serializer
+#in this case an object is apparently a collection/array
+meta :total_count, ->(obj, s) { [obj.count, {compact: true}] }
+#if the value inside the lambda is single (no array), the options will be taken from
+#the second argument, after the lambda. So the above is equivelent to:
+meta :total_count, ->(obj, s) { obj.count }, {compact: true}
+```
+
+</details>
+
+<details>
+<summary id="form">form</summary>
+
+Specifies a form to be used. Unfortunately, there are very few API specs that
+handle forms (the [Ion hypermedia type](https://ionspec.org) is one of those).
+You can specify multiple forms, as long as each link name is unique.
+
+```ruby
+#specifying a form with without options
+form :upload, {method: :get, url: "/api/v1/submit"}
+#specifying a form with options
+form :upload, {method: :get, url: "/api/v1/submit"}, compact: true
+#values can be dynamic through lambdas
+#lambdas take arguments the object to be serialized and the instantiated serializer
+form :upload, ->(obj, s) { [obj.class.upload_form_options, {compact: true}] }
+#if the value inside the lambda is single (no array), the options will be taken from
+#the second argument, after the lambda. So the above is equivelent to:
+form :upload, ->(obj, s) { obj.class.upload_form_options }, {compact: true}
+```
+
+</details>
+
+<details>
+<summary id="generic">generic</summary>
+
+Specifies a generic to be used. A generic is just a placeholder for extensions
+that are unknown to SimpleAMS (but maybe they make a lot of sense to you ^_^)
+
+```ruby
+#specifying a generic with without options
+generic :pagination, :extended
+#specifying a form with options
+generic :pagination, :extended, compact: false
+#values can be dynamic through lambdas
+#lambdas take arguments the object to be serialized and the instantiated serializer
+generic :pagination, ->(obj, s) { [obj.class.pagination_type, {compact: false}] }
+#if the value inside the lambda is single (no array), the options will be taken from
+#the second argument, after the lambda. So the above is equivelent to:
+generic :pagination, ->(obj, s) { obj.class.pagination_type }, {compact: false}
+```
+
+</details>
+
+##### group of links/metas/forms/generics
+
+Each of the aforementioned options comes with a plural form as well.
+For instance, if we want to specify multiple `links` at the same time:
+
+```ruby
+links {
+  self: ['/api/v1/me', {rel: :user}]
+  feed: ['/api/v1/me/feed', {rel: :feed}]
+}
+```
+
+or if we want to specify multiple `metas`:
+```ruby
+metas {
+  total_count: ->(obj){ obj.count }
+  pages: ->(obj){ obj.pages_count }
+}
+```
+
+Same goes for `forms` and `generics`.
+
+#### collection directive
+SimpleAMS has a unique ability to allow you specify different options when you are
+rendering a collection. In its most simple use case it specified the plural name
+of the resource, used when rendering a collection:
+
+```ruby
+collection :users
+```
+
+It’s needed, if your adapter serializes the collection using a root element.
+But it can do much more than that: it allows you to define directives on the
+collection level. For instance, if you want to have a link that should be
+applied **only** to the collection level and not to each resource of the collection,
+then you need to define it inside the collection’s block:
+
+```ruby
+collection :users do
+  link :self, "/api/v1/users"
+end
+```
 
-# Advanced usage
-The DSL in the previous example is just syntactic sugar. In the basis, there is a very powerful
-hash-based DSL that can be used in 3 different places:
+Or if we also want to have the total count of the collection, that should go in
+there actually:
 
-* When initializing the `SimpleAMS::Renderer` class to render the data using specific serializer, adapter and options.
-* Inside a class that has the `SimpleAMS::DSL` included, using the `with_options({})` class method
-* Through the DSL, powered with some syntactic sugar
+```ruby
+collection :users do
+  link :self, "/api/v1/users"
+  meta :count, ->(collection, s) { collection.count }
+end
+```
+
+Again, inside that block you can define using the regular DSL, whatever you
+would define in the resource level. It’s just yet another level of recursion
+since, the same things that I show you here can be applied in the collection
+level inside the block. For instance, in theory (and if the adapter supports
+it), you can specify relations that apply only to the collection level:
+
+```ruby
+class UserSerializer
+  include SimpleAMS::DSL
+
+  adapter SimpleAMS::Adapters::JSONAPI
+
+  attributes :id, :name, :email, :created_at, :role
+
+  type :user
+  collection :users do
+    link :self, "/api/v1/users"
+    meta :count, ->(collection, s) { collection.count }
+
+    has_one :s3_uploader #whatever that means :P
+  end
+
+  has_many :microposts
+end
+```
+
+### Rendering DSL
+When rendering a resource, it should be straightforward:
+
+```ruby
+SimpleAMS::Renderer.new(user, { serializer: UserSerializer }).to_json
+```
+
+All you need is to specify a serializer. In the example above, the resulted
+resource is a reflection of what is defined inside the serializer.
+However, the serializer acts as a filtering mechanism, meaning that you can
+override anything the serializer defines, given that the result creates a
+**subset and not a superset** (any superset options will be ignored).
+
+For instance, you can override the type during rendering:
+
+```ruby
+SimpleAMS::Renderer.new(user, {
+  serializer: UserSerializer, type: :person
+}).to_json
+```
+or you can override the relations, and specify that you don’t want to include
+any relation defined in the serializer:
+
+```ruby
+SimpleAMS::Renderer.new(user, {
+  serializer: UserSerializer, includes: []
+}).to_json
+```
 
-In any case, we have the following options:
+or specify exactly what fields you want:
+
+```ruby
+SimpleAMS::Renderer.new(user, {
+  serializer: UserSerializer, fields: [:id, :email, :name, :created_at]
+}).to_json
+```
+
+or even specify the links subset that you want:
+
+```ruby
+SimpleAMS::Renderer.new(user, {
+  serializer: UserSerializer, fields: [:id, :email, :name, :created_at],
+  links: [:self, :comments, :posts]
+}).to_json
+```
+
+and the list goes on.. basically the rendering DSL is identical
+
+#### includes vs relations
+There might be some confusion between `includes` and `relations`, so to clear things up:
+* `includes`: specifies which relations you want to include, out of the available relations.
+* `relations`: specifies the available relations, so it's not just an array of
+  symbols, but rather full relation objects which are generated through the dsl.
+  The raw representation of relations is an array of objects where each object
+  is `[relation_type, name, options, embedded_options]`. Here
+   `relation_type` is the type of the relation (`has_many`, `belongs_to` etc),
+   `name` is the name of the relation (like users), `options`, any relation options,
+   and `embedded_options` relevant to embedded options.
+
+So when rendering, if you don't want any relations at all, the correct way is to
+specify `includes: []`. In practice you can use `relations: []` as well, but that
+will mean that the serializer has no relations at all (takes precedence over
+`includes`). But that's not the correct way to do it. For instance, thing about
+another scenario: you want to specify only one relation, the `feed` relation.
+With `includes` you would have `includes: [:feed]`. With relations, you would
+have to specify the relation at runtime (
+`relations: [[:has_one, :feed, {serializer: FeedSerializer, fields: [:id, :content]}, {}]]`
+) and then also specify that you only want that: `includes: [:feed]`.
+
+In general, there is no reason why you should use `relations` at rendering time,
+instead you should leave that to the serializer, and only specify the `includes`.
+
+Btw you might have noticed `includes` only as a rendering option, but SimpleAMS
+DSL is used all over the place, and actually it's a serializer option as well
+(just that it's not very useful ^_^).
+
+
+#### Rendering collections
+Rendering a collection is similar, only that you need to call
+`SimpleAMS::Renderer::Collection` instead of just `SimpleAMS::Renderer`:
+
+```ruby
+SimpleAMS::Renderer::Collection.new(users, {
+  serializer: UserSerializer, fields: [:id, :email, :name, :created_at],
+  links: [:self, :comments, :posts]
+}).to_json
+```
+
+Note that even with collection, by default everything goes to the resource.
+If you need to specify options for the collection itself, you need to use the
+collection key. For instance, having some metas inside the collection:
+
+```ruby
+SimpleAMS::Renderer::Collection.new(users, {
+  serializer: UserSerializer, fields: [:id, :email, :name, :created_at],
+  links: [:self, :comments, :posts],
+  collection: {
+    metas: [:total_count]
+  }
+}).to_json
+```
+
+#### Rendering options with values
+If you want to specify the actual values when rendering the resource, rather
+than taking into account the serializer, you can inject a hashmap:
+
+```ruby
+SimpleAMS::Renderer::Collection.new(users, {
+  serializer: UserSerializer, fields: [:id, :email, :name, :created_at],
+  links: [:self, :comments, :posts],
+  collection: {
+    metas: {
+      total_count: users.count,
+  }
+}).to_json
+```
+
+Of course, you can also pass a lambda there, but not sure what’s the point since
+the lambda parameter is the resource that you already try to render so it’s not
+going to give you anything more (and will be slower actually).
+
+#### Exposing methods inside the serializer, like helpers
+When rendering you can expose a couple of objects in the serializer:
+
+```ruby
+SimpleAMS::Renderer::Collection.new(users, {
+  serializer: UserSerializer, fields: [:id, :email, :name, :created_at],
+  #exposing helpers that will be available inside the serializer
+  expose: {
+    #a class
+    current_user: User.first
+    #or a module
+    helpers: CommonHelpers
+  },
+}).to_json
+```
+
+The expose attribute is also available through DSL, although usually that’s not
+very useful. Just wanted to mentions that there is actually parity on everything,
+since everything has been built on the same building blocks :)
+
+### Extended DSL show off
+Here is an extended example of the DSL. It's not a real use case of course, but
+shows what's possible with SimpleAMS and its powerful DSL.
 
 ```ruby
 {
@@ -131,13 +718,14 @@ In any case, we have the following options:
   fields: [:id, :name, posts: [:id, :text], videos: [:id, :title, comments: [:id, :text]]] #overrides includes when association is specified
   relations: [
     [:belongs_to, :company, {
-      serializer: CompanySerializer,
-      fields: Company.column_names.map(&:to_sym)
+        serializer: CompanySerializer,
+        fields: Company.column_names.map(&:to_sym)
       }
     ],
     [:has_many, :followers, {
-      serializer: UserSerializer,
-      fields: User.column_names.map(&:to_sym)
+        serializer: UserSerializer,
+        fields: User.column_names.map(&:to_sym)
+      }
     ],
   ]
   #the serializer that should be used
@@ -197,45 +785,6 @@ In any case, we have the following options:
 }
 ```
 
-Now let those options be `OPTIONS`. These can be fed to either the `SimpleAMS::Renderer`
-or to the serializer class itself using the `with_options` class method. Let's see how:
-
-```ruby
-class UserSerializer
-  include SimpleAMS::DSL
-
-  with_options({ #you can pass the same options as above ;)
-    primary_id: :id,
-    #   ...
-    #   ...
-    #   ...
-  })
-
-  def name
-    "#{object.first_name} #{object.last_name}"
-  end
-
-  def videos
-    Videos.where(user_id: object.id).published
-  end
-end
-```
-
-The same options can be passed when calling the `Renderer`. `Renderer` can override
-some properties, however in all properties that act as sets/arrays (like
-attributes/fields, includes, links etc.), **specified serializer options take precedence** over
-`Renderer` options.
-
-```ruby
-SimpleAMS::Renderer.new(user, {
-  primary_id: :id,
-  serializer: UserSerializer,
-  #   ...
-  #   ...
-  #   ...
-}).to_json
-```
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.