active_model_serializers 0.10.0 → 0.10.11

Sign up to get free protection for your applications and to get access to all the features.
Files changed (215) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGELOG.md +227 -2
  3. data/README.md +171 -33
  4. data/lib/action_controller/serialization.rb +23 -3
  5. data/lib/active_model/serializable_resource.rb +2 -0
  6. data/lib/active_model/serializer/adapter/attributes.rb +2 -0
  7. data/lib/active_model/serializer/adapter/base.rb +4 -0
  8. data/lib/active_model/serializer/adapter/json.rb +2 -0
  9. data/lib/active_model/serializer/adapter/json_api.rb +2 -0
  10. data/lib/active_model/serializer/adapter/null.rb +2 -0
  11. data/lib/active_model/serializer/adapter.rb +2 -0
  12. data/lib/active_model/serializer/array_serializer.rb +10 -5
  13. data/lib/active_model/serializer/association.rb +64 -10
  14. data/lib/active_model/serializer/attribute.rb +2 -0
  15. data/lib/active_model/serializer/belongs_to_reflection.rb +6 -3
  16. data/lib/active_model/serializer/collection_serializer.rb +39 -13
  17. data/lib/active_model/serializer/{caching.rb → concerns/caching.rb} +89 -117
  18. data/lib/active_model/serializer/error_serializer.rb +13 -7
  19. data/lib/active_model/serializer/errors_serializer.rb +27 -20
  20. data/lib/active_model/serializer/field.rb +2 -0
  21. data/lib/active_model/serializer/fieldset.rb +3 -1
  22. data/lib/active_model/serializer/has_many_reflection.rb +5 -3
  23. data/lib/active_model/serializer/has_one_reflection.rb +3 -4
  24. data/lib/active_model/serializer/lazy_association.rb +99 -0
  25. data/lib/active_model/serializer/link.rb +23 -0
  26. data/lib/active_model/serializer/lint.rb +136 -130
  27. data/lib/active_model/serializer/null.rb +2 -0
  28. data/lib/active_model/serializer/reflection.rb +130 -65
  29. data/lib/active_model/serializer/version.rb +3 -1
  30. data/lib/active_model/serializer.rb +319 -86
  31. data/lib/active_model_serializers/adapter/attributes.rb +17 -57
  32. data/lib/active_model_serializers/adapter/base.rb +41 -39
  33. data/lib/active_model_serializers/adapter/json.rb +2 -0
  34. data/lib/active_model_serializers/adapter/json_api/deserialization.rb +4 -2
  35. data/lib/active_model_serializers/adapter/json_api/error.rb +2 -0
  36. data/lib/active_model_serializers/adapter/json_api/jsonapi.rb +2 -0
  37. data/lib/active_model_serializers/adapter/json_api/link.rb +3 -1
  38. data/lib/active_model_serializers/adapter/json_api/meta.rb +2 -0
  39. data/lib/active_model_serializers/adapter/json_api/pagination_links.rb +49 -21
  40. data/lib/active_model_serializers/adapter/json_api/relationship.rb +77 -23
  41. data/lib/active_model_serializers/adapter/json_api/resource_identifier.rb +41 -10
  42. data/lib/active_model_serializers/adapter/json_api.rb +84 -65
  43. data/lib/active_model_serializers/adapter/null.rb +2 -0
  44. data/lib/active_model_serializers/adapter.rb +9 -1
  45. data/lib/active_model_serializers/callbacks.rb +2 -0
  46. data/lib/active_model_serializers/deprecate.rb +3 -2
  47. data/lib/active_model_serializers/deserialization.rb +4 -0
  48. data/lib/active_model_serializers/json_pointer.rb +2 -0
  49. data/lib/active_model_serializers/logging.rb +2 -0
  50. data/lib/active_model_serializers/lookup_chain.rb +82 -0
  51. data/lib/active_model_serializers/model/caching.rb +25 -0
  52. data/lib/active_model_serializers/model.rb +111 -28
  53. data/lib/active_model_serializers/railtie.rb +7 -1
  54. data/lib/active_model_serializers/register_jsonapi_renderer.rb +46 -31
  55. data/lib/active_model_serializers/serializable_resource.rb +10 -7
  56. data/lib/active_model_serializers/serialization_context.rb +12 -3
  57. data/lib/active_model_serializers/test/schema.rb +4 -2
  58. data/lib/active_model_serializers/test/serializer.rb +2 -0
  59. data/lib/active_model_serializers/test.rb +2 -0
  60. data/lib/active_model_serializers.rb +35 -10
  61. data/lib/generators/rails/resource_override.rb +3 -1
  62. data/lib/generators/rails/serializer_generator.rb +6 -4
  63. data/lib/grape/active_model_serializers.rb +9 -5
  64. data/lib/grape/formatters/active_model_serializers.rb +21 -2
  65. data/lib/grape/helpers/active_model_serializers.rb +3 -0
  66. data/lib/tasks/rubocop.rake +55 -0
  67. metadata +110 -276
  68. data/.github/ISSUE_TEMPLATE.md +0 -29
  69. data/.github/PULL_REQUEST_TEMPLATE.md +0 -15
  70. data/.gitignore +0 -35
  71. data/.rubocop.yml +0 -104
  72. data/.rubocop_todo.yml +0 -167
  73. data/.simplecov +0 -110
  74. data/.travis.yml +0 -43
  75. data/CONTRIBUTING.md +0 -105
  76. data/Gemfile +0 -53
  77. data/Rakefile +0 -103
  78. data/active_model_serializers.gemspec +0 -66
  79. data/appveyor.yml +0 -24
  80. data/bin/bench +0 -171
  81. data/bin/bench_regression +0 -316
  82. data/bin/serve_benchmark +0 -39
  83. data/docs/ARCHITECTURE.md +0 -126
  84. data/docs/README.md +0 -40
  85. data/docs/STYLE.md +0 -58
  86. data/docs/general/adapters.md +0 -245
  87. data/docs/general/caching.md +0 -52
  88. data/docs/general/configuration_options.md +0 -100
  89. data/docs/general/deserialization.md +0 -100
  90. data/docs/general/getting_started.md +0 -133
  91. data/docs/general/instrumentation.md +0 -40
  92. data/docs/general/key_transforms.md +0 -40
  93. data/docs/general/logging.md +0 -14
  94. data/docs/general/rendering.md +0 -255
  95. data/docs/general/serializers.md +0 -372
  96. data/docs/how-open-source-maintained.jpg +0 -0
  97. data/docs/howto/add_pagination_links.md +0 -139
  98. data/docs/howto/add_root_key.md +0 -51
  99. data/docs/howto/outside_controller_use.md +0 -58
  100. data/docs/howto/passing_arbitrary_options.md +0 -27
  101. data/docs/howto/serialize_poro.md +0 -32
  102. data/docs/howto/test.md +0 -152
  103. data/docs/integrations/ember-and-json-api.md +0 -112
  104. data/docs/integrations/grape.md +0 -19
  105. data/docs/jsonapi/errors.md +0 -56
  106. data/docs/jsonapi/schema/schema.json +0 -366
  107. data/docs/jsonapi/schema.md +0 -151
  108. data/docs/rfcs/0000-namespace.md +0 -106
  109. data/docs/rfcs/template.md +0 -15
  110. data/lib/active_model/serializer/associations.rb +0 -100
  111. data/lib/active_model/serializer/attributes.rb +0 -82
  112. data/lib/active_model/serializer/collection_reflection.rb +0 -7
  113. data/lib/active_model/serializer/configuration.rb +0 -35
  114. data/lib/active_model/serializer/include_tree.rb +0 -111
  115. data/lib/active_model/serializer/links.rb +0 -35
  116. data/lib/active_model/serializer/meta.rb +0 -29
  117. data/lib/active_model/serializer/singular_reflection.rb +0 -7
  118. data/lib/active_model/serializer/type.rb +0 -25
  119. data/lib/active_model_serializers/key_transform.rb +0 -70
  120. data/test/action_controller/adapter_selector_test.rb +0 -53
  121. data/test/action_controller/explicit_serializer_test.rb +0 -134
  122. data/test/action_controller/json/include_test.rb +0 -167
  123. data/test/action_controller/json_api/deserialization_test.rb +0 -112
  124. data/test/action_controller/json_api/errors_test.rb +0 -41
  125. data/test/action_controller/json_api/linked_test.rb +0 -197
  126. data/test/action_controller/json_api/pagination_test.rb +0 -116
  127. data/test/action_controller/json_api/transform_test.rb +0 -181
  128. data/test/action_controller/serialization_scope_name_test.rb +0 -229
  129. data/test/action_controller/serialization_test.rb +0 -469
  130. data/test/active_model_serializers/adapter_for_test.rb +0 -208
  131. data/test/active_model_serializers/json_pointer_test.rb +0 -20
  132. data/test/active_model_serializers/key_transform_test.rb +0 -263
  133. data/test/active_model_serializers/logging_test.rb +0 -77
  134. data/test/active_model_serializers/model_test.rb +0 -9
  135. data/test/active_model_serializers/railtie_test_isolated.rb +0 -63
  136. data/test/active_model_serializers/serialization_context_test_isolated.rb +0 -58
  137. data/test/active_model_serializers/test/schema_test.rb +0 -130
  138. data/test/active_model_serializers/test/serializer_test.rb +0 -62
  139. data/test/active_record_test.rb +0 -9
  140. data/test/adapter/deprecation_test.rb +0 -100
  141. data/test/adapter/json/belongs_to_test.rb +0 -45
  142. data/test/adapter/json/collection_test.rb +0 -90
  143. data/test/adapter/json/has_many_test.rb +0 -45
  144. data/test/adapter/json/transform_test.rb +0 -93
  145. data/test/adapter/json_api/belongs_to_test.rb +0 -155
  146. data/test/adapter/json_api/collection_test.rb +0 -95
  147. data/test/adapter/json_api/errors_test.rb +0 -78
  148. data/test/adapter/json_api/fields_test.rb +0 -87
  149. data/test/adapter/json_api/has_many_embed_ids_test.rb +0 -43
  150. data/test/adapter/json_api/has_many_explicit_serializer_test.rb +0 -96
  151. data/test/adapter/json_api/has_many_test.rb +0 -144
  152. data/test/adapter/json_api/has_one_test.rb +0 -80
  153. data/test/adapter/json_api/json_api_test.rb +0 -35
  154. data/test/adapter/json_api/linked_test.rb +0 -392
  155. data/test/adapter/json_api/links_test.rb +0 -93
  156. data/test/adapter/json_api/pagination_links_test.rb +0 -166
  157. data/test/adapter/json_api/parse_test.rb +0 -137
  158. data/test/adapter/json_api/relationship_test.rb +0 -161
  159. data/test/adapter/json_api/relationships_test.rb +0 -199
  160. data/test/adapter/json_api/resource_identifier_test.rb +0 -85
  161. data/test/adapter/json_api/resource_meta_test.rb +0 -100
  162. data/test/adapter/json_api/toplevel_jsonapi_test.rb +0 -82
  163. data/test/adapter/json_api/transform_test.rb +0 -502
  164. data/test/adapter/json_api/type_test.rb +0 -61
  165. data/test/adapter/json_test.rb +0 -45
  166. data/test/adapter/null_test.rb +0 -23
  167. data/test/adapter/polymorphic_test.rb +0 -171
  168. data/test/adapter_test.rb +0 -67
  169. data/test/array_serializer_test.rb +0 -22
  170. data/test/benchmark/app.rb +0 -65
  171. data/test/benchmark/benchmarking_support.rb +0 -67
  172. data/test/benchmark/bm_caching.rb +0 -119
  173. data/test/benchmark/bm_transform.rb +0 -34
  174. data/test/benchmark/config.ru +0 -3
  175. data/test/benchmark/controllers.rb +0 -84
  176. data/test/benchmark/fixtures.rb +0 -219
  177. data/test/cache_test.rb +0 -485
  178. data/test/collection_serializer_test.rb +0 -110
  179. data/test/fixtures/active_record.rb +0 -78
  180. data/test/fixtures/poro.rb +0 -282
  181. data/test/generators/scaffold_controller_generator_test.rb +0 -24
  182. data/test/generators/serializer_generator_test.rb +0 -57
  183. data/test/grape_test.rb +0 -82
  184. data/test/include_tree/from_include_args_test.rb +0 -26
  185. data/test/include_tree/from_string_test.rb +0 -94
  186. data/test/include_tree/include_args_to_hash_test.rb +0 -64
  187. data/test/lint_test.rb +0 -49
  188. data/test/logger_test.rb +0 -18
  189. data/test/poro_test.rb +0 -9
  190. data/test/serializable_resource_test.rb +0 -83
  191. data/test/serializers/association_macros_test.rb +0 -36
  192. data/test/serializers/associations_test.rb +0 -295
  193. data/test/serializers/attribute_test.rb +0 -151
  194. data/test/serializers/attributes_test.rb +0 -52
  195. data/test/serializers/caching_configuration_test_isolated.rb +0 -170
  196. data/test/serializers/configuration_test.rb +0 -32
  197. data/test/serializers/fieldset_test.rb +0 -14
  198. data/test/serializers/meta_test.rb +0 -196
  199. data/test/serializers/options_test.rb +0 -21
  200. data/test/serializers/read_attribute_for_serialization_test.rb +0 -79
  201. data/test/serializers/root_test.rb +0 -21
  202. data/test/serializers/serialization_test.rb +0 -55
  203. data/test/serializers/serializer_for_test.rb +0 -134
  204. data/test/support/custom_schemas/active_model_serializers/test/schema_test/my/index.json +0 -6
  205. data/test/support/isolated_unit.rb +0 -79
  206. data/test/support/rails5_shims.rb +0 -47
  207. data/test/support/rails_app.rb +0 -45
  208. data/test/support/schemas/active_model_serializers/test/schema_test/my/index.json +0 -6
  209. data/test/support/schemas/active_model_serializers/test/schema_test/my/show.json +0 -6
  210. data/test/support/schemas/custom/show.json +0 -7
  211. data/test/support/schemas/hyper_schema.json +0 -93
  212. data/test/support/schemas/render_using_json_api.json +0 -43
  213. data/test/support/schemas/simple_json_pointers.json +0 -10
  214. data/test/support/serialization_testing.rb +0 -53
  215. data/test/test_helper.rb +0 -57
@@ -1,151 +0,0 @@
1
- [Back to Guides](../README.md)
2
-
3
- [![JSON API 1.0](https://img.shields.io/badge/JSON%20API-1.0-lightgrey.svg)](http://jsonapi.org/)
4
-
5
- ## JSON API Requests
6
-
7
- - [Query Parameters Spec](http://jsonapi.org/format/#query-parameters)
8
-
9
- Headers:
10
-
11
- - Request: `Accept: application/vnd.api+json`
12
- - Response: `Content-Type: application/vnd.api+json`
13
-
14
- ### [Fetching Data](http://jsonapi.org/format/#fetching)
15
-
16
- A server MUST support fetching resource data for every URL provided as:
17
-
18
- - a `self` link as part of the top-level links object
19
- - a `self` link as part of a resource-level links object
20
- - a `related` link as part of a relationship-level links object
21
-
22
- Example supported requests
23
-
24
- - Individual resource or collection
25
- - GET /articles
26
- - GET /articles/1
27
- - GET /articles/1/author
28
- - Relationships
29
- - GET /articles/1/relationships/comments
30
- - GET /articles/1/relationships/author
31
- - Optional: [Inclusion of related resources](http://jsonapi.org/format/#fetching-includes) `ActiveModel::Serializer::IncludeTree`
32
- - GET /articles/1?`include`=comments
33
- - GET /articles/1?`include`=comments.author
34
- - GET /articles/1?`include`=author,comments.author
35
- - GET /articles/1/relationships/comments?`include`=comments.author
36
- - Optional: [Sparse Fieldsets](http://jsonapi.org/format/#fetching-sparse-fieldsets) `ActiveModel::Serializer::Fieldset`
37
- - GET /articles?`include`=author&`fields`[articles]=title,body&`fields`[people]=name
38
- - Optional: [Sorting](http://jsonapi.org/format/#fetching-sorting)
39
- - GET /people?`sort`=age
40
- - GET /people?`sort`=age,author.name
41
- - GET /articles?`sort`=-created,title
42
- - Optional: [Pagination](http://jsonapi.org/format/#fetching-pagination)
43
- - GET /articles?`page`[number]=3&`page`[size]=1
44
- - Optional: [Filtering](http://jsonapi.org/format/#fetching-filtering)
45
- - GET /comments?`filter`[post]=1
46
- - GET /comments?`filter`[post]=1,2
47
- - GET /comments?`filter`[post]=1,2
48
-
49
- ### [CRUD Actions](http://jsonapi.org/format/#crud)
50
-
51
- ### [Asynchronous Processing](http://jsonapi.org/recommendations/#asynchronous-processing)
52
-
53
- ### [Bulk Operations Extension](http://jsonapi.org/extensions/bulk/)
54
-
55
- ## JSON API Document Schema
56
-
57
- | JSON API object | JSON API properties | Required | ActiveModelSerializers representation |
58
- |-----------------------|----------------------------------------------------------------------------------------------------|----------|---------------------------------------|
59
- | schema | oneOf (success, failure, info) | |
60
- | success | data, included, meta, links, jsonapi | | AM::SerializableResource
61
- | success.meta | meta | | AMS::Adapter::Base#meta
62
- | success.included | UniqueArray(resource) | | AMS::Adapter::JsonApi#serializable_hash_for_collection
63
- | success.data | data | |
64
- | success.links | allOf (links, pagination) | | AMS::Adapter::JsonApi#links_for
65
- | success.jsonapi | jsonapi | |
66
- | failure | errors, meta, jsonapi | errors | AMS::Adapter::JsonApi#failure_document, #1004
67
- | failure.errors | UniqueArray(error) | | AM::S::ErrorSerializer, #1004
68
- | meta | Object | |
69
- | data | oneOf (resource, UniqueArray(resource)) | | AMS::Adapter::JsonApi#serializable_hash_for_collection,#serializable_hash_for_single_resource
70
- | resource | String(type), String(id),<br>attributes, relationships,<br>links, meta | type, id | AM::S::Adapter::JsonApi#primary_data_for
71
- | links | Uri(self), Link(related) | | #1028, #1246, #1282
72
- | link | oneOf (linkString, linkObject) | |
73
- | link.linkString | Uri | |
74
- | link.linkObject | Uri(href), meta | href |
75
- | attributes | patternProperties(<br>`"^(?!relationships$|links$)\\w[-\\w_]*$"`),<br>any valid JSON | | AM::Serializer#attributes, AMS::Adapter::JsonApi#resource_object_for
76
- | relationships | patternProperties(<br>`"^\\w[-\\w_]*$"`);<br>links, relationships.data, meta | | AMS::Adapter::JsonApi#relationships_for
77
- | relationships.data | oneOf (relationshipToOne, relationshipToMany) | | AMS::Adapter::JsonApi#resource_identifier_for
78
- | relationshipToOne | anyOf(empty, linkage) | |
79
- | relationshipToMany | UniqueArray(linkage) | |
80
- | empty | null | |
81
- | linkage | String(type), String(id), meta | type, id | AMS::Adapter::JsonApi#primary_data_for
82
- | pagination | pageObject(first), pageObject(last),<br>pageObject(prev), pageObject(next) | | AMS::Adapter::JsonApi::PaginationLinks#serializable_hash
83
- | pagination.pageObject | oneOf(Uri, null) | |
84
- | jsonapi | String(version), meta | | AMS::Adapter::JsonApi::Jsonapi#as_json
85
- | error | String(id), links, String(status),<br>String(code), String(title),<br>String(detail), error.source, meta | | AM::S::ErrorSerializer, AMS::Adapter::JsonApi::Error.resource_errors
86
- | error.source | String(pointer), String(parameter) | | AMS::Adapter::JsonApi::Error.error_source
87
- | pointer | [JSON Pointer RFC6901](https://tools.ietf.org/html/rfc6901) | | AMS::JsonPointer
88
-
89
-
90
- The [http://jsonapi.org/schema](schema/schema.json) makes a nice roadmap.
91
-
92
- ### Success Document
93
- - [ ] success
94
- - [ ] data: `"$ref": "#/definitions/data"`
95
- - [ ] included: array of unique items of type `"$ref": "#/definitions/resource"`
96
- - [ ] meta: `"$ref": "#/definitions/meta"`
97
- - [ ] links:
98
- - [ ] link: `"$ref": "#/definitions/links"`
99
- - [ ] pagination: ` "$ref": "#/definitions/pagination"`
100
- - [ ] jsonapi: ` "$ref": "#/definitions/jsonapi"`
101
-
102
- ### Failure Document
103
-
104
- - [ ] failure
105
- - [x] errors: array of unique items of type ` "$ref": "#/definitions/error"`
106
- - [ ] meta: `"$ref": "#/definitions/meta"`
107
- - [ ] jsonapi: `"$ref": "#/definitions/jsonapi"`
108
-
109
- ### Info Document
110
-
111
- - [ ] info
112
- - [ ] meta: `"$ref": "#/definitions/meta"`
113
- - [ ] links: `"$ref": "#/definitions/links"`
114
- - [ ] jsonapi: ` "$ref": "#/definitions/jsonapi"`
115
-
116
- ### Definitions
117
-
118
- - [ ] definitions:
119
- - [ ] meta
120
- - [ ] data: oneOf (resource, array of unique resources)
121
- - [ ] resource
122
- - [ ] attributes
123
- - [ ] relationships
124
- - [ ] relationshipToOne
125
- - [ ] empty
126
- - [ ] linkage
127
- - [ ] meta
128
- - [ ] relationshipToMany
129
- - [ ] linkage
130
- - [ ] meta
131
- - [ ] links
132
- - [ ] meta
133
- - [ ] links
134
- - [ ] link
135
- - [ ] uri
136
- - [ ] href, meta
137
- - [ ] pagination
138
- - [ ] jsonapi
139
- - [ ] meta
140
- - [ ] error
141
- - [ ] id: a unique identifier for this particular occurrence of the problem.
142
- - [ ] links: a links object containing the following members:
143
- - [ ] about: a link that leads to further details about this particular occurrence of the problem.
144
- - [ ] status: the HTTP status code applicable to this problem, expressed as a string value.
145
- - [ ] code: an application-specific error code, expressed as a string value.
146
- - [ ] title: a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
147
- - [x] detail: a human-readable explanation specific to this occurrence of the problem.
148
- - [x] source: an object containing references to the source of the error, optionally including any of the following members:
149
- - [x] pointer: a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901) to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
150
- - [x] parameter: a string indicating which query parameter caused the error.
151
- - [ ] meta: a meta object containing non-standard meta-information about the error.
@@ -1,106 +0,0 @@
1
- - Start Date: (2015-10-29)
2
- - RFC PR: https://github.com/rails-api/active_model_serializers/pull/1310
3
- - ActiveModelSerializers Issue: https://github.com/rails-api/active_model_serializers/issues/1298
4
-
5
- # Summary
6
-
7
- Provide a consistent API for the user of the AMS.
8
-
9
- # Motivation
10
-
11
- The actual public API is defined under `ActiveModelSerializers`,
12
- `ActiveModel::Serializer` and `ActiveModel`.
13
-
14
- At the `ActiveModel::Serializer` we have:
15
-
16
- - `ActiveModel::Serializer.config`
17
- - `ActiveModel::Serializer`
18
-
19
- At the `ActiveModelSerializers` we have:
20
-
21
- - `ActiveModelSerializers::Model`
22
- - `ActiveModelSerializers.logger`
23
-
24
- At `ActiveModel` we have:
25
-
26
- - `ActiveModel::SerializableResource`
27
-
28
- The idea here is to provide a single namespace `ActiveModelSerializers` to the user.
29
- Following the same idea we have on other gems like
30
- [Devise](https://github.com/plataformatec/devise/blob/e9c82472ffe7c43a448945f77e034a0e47dde0bb/lib/devise.rb),
31
- [Refile](https://github.com/refile/refile/blob/6b24c293d044862dafbf1bfa4606672a64903aa2/lib/refile.rb) and
32
- [Active Job](https://github.com/rails/rails/blob/30bacc26f8f258b39e12f63fe52389a968d9c1ea/activejob/lib/active_job.rb)
33
- for example.
34
-
35
- This way we are clarifing the boundaries of
36
- [ActiveModelSerializers and Rails](https://github.com/rails-api/active_model_serializers/blob/master/CHANGELOG.md#prehistory)
37
- and make clear that the `ActiveModel::Serializer` class is no longer the primary
38
- behavior of the ActiveModelSerializers.
39
-
40
- # Detailed design
41
-
42
- ## New classes and modules organization
43
-
44
- Since this will be a big change we can do this on baby steps, read small pull requests. A
45
- possible approach is:
46
-
47
- - All new code will be in `lib/active_model_serializers/` using
48
- the module namespace `ActiveModelSerializers`.
49
- - Move all content under `ActiveModel::Serializer` to be under
50
- `ActiveModelSerializers`, the adapter is on this steps;
51
- - Move all content under `ActiveModel` to be under `ActiveModelSerializers`,
52
- the `SerializableResource` is on this step;
53
- - Change all public API that doesn't make sense, keeping in mind only to keep
54
- this in the same namespace
55
- - Update the README;
56
- - Update the docs;
57
-
58
- The following table represents the current and the desired classes and modules
59
- at the first moment.
60
-
61
- | Current | Desired | Notes |
62
- |--------------------------------------------------------|--------------------------------------------------|--------------------|
63
- | `ActiveModelSerializers` and `ActiveModel::Serializer` | `ActiveModelSerializers` | The main namespace |
64
- | `ActiveModelSerializers.logger` | `ActiveModelSerializers.logger` ||
65
- | `ActiveModelSerializers::Model` | `ActiveModelSerializers::Model` ||
66
- | `ActiveModel::SerializableResource` | `ActiveModelSerializers::SerializableResource` ||
67
- | `ActiveModel::Serializer` | `ActiveModelSerializers::Serializer` | The name can be discussed in a future pull request. For example, we can rename this to `Resource` [following this idea](https://github.com/rails-api/active_model_serializers/pull/1301/files#r42963185) more info about naming in the next section|
68
- | `ActiveModel::Serializer.config` | `ActiveModelSerializers.config` ||
69
-
70
- ## Renaming of class and modules
71
-
72
- When moving some content to the new namespace we can find some names that does
73
- not make much sense like `ActiveModel::Serializer::Adapter::JsonApi`.
74
- Discussion of renaming existing classes / modules and JsonApi objects will
75
- happen in separate pull requests, and issues, and in the google doc
76
- https://docs.google.com/document/d/1rcrJr0sVcazY2Opd_6Kmv1iIwuHbI84s1P_NzFn-05c/edit?usp=sharing
77
-
78
- Some of names already have a definition.
79
-
80
- - Adapters get their own namespace under ActiveModelSerializers. E.g
81
- `ActiveModelSerializers::Adapter`
82
- - Serializers get their own namespace under ActiveModelSerializers. E.g
83
- `ActiveModelSerializers::Serializer`
84
-
85
- ## Keeping compatibility
86
-
87
- All moved classes or modules be aliased to their old name and location with
88
- deprecation warnings, such as
89
- [was done for CollectionSerializer](https://github.com/rails-api/active_model_serializers/pull/1251).
90
-
91
- # Drawbacks
92
-
93
- This will be a breaking change, so all users serializers will be broken after a
94
- major bump.
95
- All pull requests will need to rebase since the architeture will change a lot.
96
-
97
- # Alternatives
98
-
99
- We can keep the way it is, and keep in mind to not add another namespace as a
100
- public API.
101
-
102
- # Unresolved questions
103
-
104
- What is the better class name to be used to the class that will be inherited at
105
- the creation of a serializer. This can be discussed in other RFC or directly via
106
- pull request.
@@ -1,15 +0,0 @@
1
- - Start Date: (YYYY-MM-DD)
2
- - RFC PR: https://github.com/rails-api/active_model_serializers/pull/dddd
3
- - ActiveModelSerializers Issue: https://github.com/rails-api/active_model_serializers/issues/dddd
4
-
5
- # Summary
6
-
7
- # Motivation
8
-
9
- # Detailed design
10
-
11
- # Drawbacks
12
-
13
- # Alternatives
14
-
15
- # Unresolved questions
@@ -1,100 +0,0 @@
1
- module ActiveModel
2
- class Serializer
3
- # Defines an association in the object should be rendered.
4
- #
5
- # The serializer object should implement the association name
6
- # as a method which should return an array when invoked. If a method
7
- # with the association name does not exist, the association name is
8
- # dispatched to the serialized object.
9
- #
10
- module Associations
11
- extend ActiveSupport::Concern
12
-
13
- DEFAULT_INCLUDE_TREE = ActiveModel::Serializer::IncludeTree.from_string('*')
14
-
15
- included do
16
- with_options instance_writer: false, instance_reader: true do |serializer|
17
- serializer.class_attribute :_reflections
18
- self._reflections ||= []
19
- end
20
-
21
- extend ActiveSupport::Autoload
22
- autoload :Association
23
- autoload :Reflection
24
- autoload :SingularReflection
25
- autoload :CollectionReflection
26
- autoload :BelongsToReflection
27
- autoload :HasOneReflection
28
- autoload :HasManyReflection
29
- end
30
-
31
- module ClassMethods
32
- def inherited(base)
33
- super
34
- base._reflections = _reflections.dup
35
- end
36
-
37
- # @param [Symbol] name of the association
38
- # @param [Hash<Symbol => any>] options for the reflection
39
- # @return [void]
40
- #
41
- # @example
42
- # has_many :comments, serializer: CommentSummarySerializer
43
- #
44
- def has_many(name, options = {}, &block)
45
- associate(HasManyReflection.new(name, options, block))
46
- end
47
-
48
- # @param [Symbol] name of the association
49
- # @param [Hash<Symbol => any>] options for the reflection
50
- # @return [void]
51
- #
52
- # @example
53
- # belongs_to :author, serializer: AuthorSerializer
54
- #
55
- def belongs_to(name, options = {}, &block)
56
- associate(BelongsToReflection.new(name, options, block))
57
- end
58
-
59
- # @param [Symbol] name of the association
60
- # @param [Hash<Symbol => any>] options for the reflection
61
- # @return [void]
62
- #
63
- # @example
64
- # has_one :author, serializer: AuthorSerializer
65
- #
66
- def has_one(name, options = {}, &block)
67
- associate(HasOneReflection.new(name, options, block))
68
- end
69
-
70
- private
71
-
72
- # Add reflection and define {name} accessor.
73
- # @param [ActiveModel::Serializer::Reflection] reflection
74
- # @return [void]
75
- #
76
- # @api private
77
- #
78
- def associate(reflection)
79
- self._reflections << reflection
80
- end
81
- end
82
-
83
- # @param [IncludeTree] include_tree (defaults to all associations when not provided)
84
- # @return [Enumerator<Association>]
85
- #
86
- def associations(include_tree = DEFAULT_INCLUDE_TREE)
87
- return unless object
88
-
89
- Enumerator.new do |y|
90
- self.class._reflections.each do |reflection|
91
- next if reflection.excluded?(self)
92
- key = reflection.options.fetch(:key, reflection.name)
93
- next unless include_tree.key?(key)
94
- y.yield reflection.build_association(self, instance_options)
95
- end
96
- end
97
- end
98
- end
99
- end
100
- end
@@ -1,82 +0,0 @@
1
- module ActiveModel
2
- class Serializer
3
- module Attributes
4
- extend ActiveSupport::Concern
5
-
6
- included do
7
- with_options instance_writer: false, instance_reader: false do |serializer|
8
- serializer.class_attribute :_attributes_data # @api private
9
- self._attributes_data ||= {}
10
- end
11
-
12
- extend ActiveSupport::Autoload
13
- autoload :Attribute
14
-
15
- # Return the +attributes+ of +object+ as presented
16
- # by the serializer.
17
- def attributes(requested_attrs = nil, reload = false)
18
- @attributes = nil if reload
19
- @attributes ||= self.class._attributes_data.each_with_object({}) do |(key, attr), hash|
20
- next if attr.excluded?(self)
21
- next unless requested_attrs.nil? || requested_attrs.include?(key)
22
- hash[key] = attr.value(self)
23
- end
24
- end
25
- end
26
-
27
- module ClassMethods
28
- def inherited(base)
29
- super
30
- base._attributes_data = _attributes_data.dup
31
- end
32
-
33
- # @example
34
- # class AdminAuthorSerializer < ActiveModel::Serializer
35
- # attributes :id, :name, :recent_edits
36
- def attributes(*attrs)
37
- attrs = attrs.first if attrs.first.class == Array
38
-
39
- attrs.each do |attr|
40
- attribute(attr)
41
- end
42
- end
43
-
44
- # @example
45
- # class AdminAuthorSerializer < ActiveModel::Serializer
46
- # attributes :id, :recent_edits
47
- # attribute :name, key: :title
48
- #
49
- # attribute :full_name do
50
- # "#{object.first_name} #{object.last_name}"
51
- # end
52
- #
53
- # def recent_edits
54
- # object.edits.last(5)
55
- # end
56
- def attribute(attr, options = {}, &block)
57
- key = options.fetch(:key, attr)
58
- _attributes_data[key] = Attribute.new(attr, options, block)
59
- end
60
-
61
- # @api private
62
- # keys of attributes
63
- # @see Serializer::attribute
64
- def _attributes
65
- _attributes_data.keys
66
- end
67
-
68
- # @api private
69
- # maps attribute value to explict key name
70
- # @see Serializer::attribute
71
- # @see FragmentCache#fragment_serializer
72
- def _attributes_keys
73
- _attributes_data
74
- .each_with_object({}) do |(key, attr), hash|
75
- next if key == attr.name
76
- hash[attr.name] = { key: key }
77
- end
78
- end
79
- end
80
- end
81
- end
82
- end
@@ -1,7 +0,0 @@
1
- module ActiveModel
2
- class Serializer
3
- # @api private
4
- class CollectionReflection < Reflection
5
- end
6
- end
7
- end
@@ -1,35 +0,0 @@
1
- module ActiveModel
2
- class Serializer
3
- module Configuration
4
- include ActiveSupport::Configurable
5
- extend ActiveSupport::Concern
6
-
7
- # Configuration options may also be set in
8
- # Serializers and Adapters
9
- included do |base|
10
- config = base.config
11
- config.collection_serializer = ActiveModel::Serializer::CollectionSerializer
12
- config.serializer_lookup_enabled = true
13
-
14
- def config.array_serializer=(collection_serializer)
15
- self.collection_serializer = collection_serializer
16
- end
17
-
18
- def config.array_serializer
19
- collection_serializer
20
- end
21
-
22
- config.adapter = :attributes
23
- config.jsonapi_resource_type = :plural
24
- config.jsonapi_version = '1.0'
25
- config.jsonapi_toplevel_meta = {}
26
- # Make JSON API top-level jsonapi member opt-in
27
- # ref: http://jsonapi.org/format/#document-top-level
28
- config.jsonapi_include_toplevel_object = false
29
- config.key_transform = nil
30
-
31
- config.schema_path = 'test/support/schemas'
32
- end
33
- end
34
- end
35
- end
@@ -1,111 +0,0 @@
1
- module ActiveModel
2
- class Serializer
3
- # TODO: description of this class, and overview of how it's used
4
- class IncludeTree
5
- module Parsing
6
- module_function
7
-
8
- # Translates a comma separated list of dot separated paths (JSON API format) into a Hash.
9
- #
10
- # @example
11
- # `'posts.author, posts.comments.upvotes, posts.comments.author'`
12
- #
13
- # would become
14
- #
15
- # `{ posts: { author: {}, comments: { author: {}, upvotes: {} } } }`.
16
- #
17
- # @param [String] included
18
- # @return [Hash] a Hash representing the same tree structure
19
- def include_string_to_hash(included)
20
- # TODO: Needs comment walking through the process of what all this is doing.
21
- included.delete(' ').split(',').reduce({}) do |hash, path|
22
- include_tree = path.split('.').reverse_each.reduce({}) { |a, e| { e.to_sym => a } }
23
- hash.deep_merge!(include_tree)
24
- end
25
- end
26
-
27
- # Translates the arguments passed to the include option into a Hash. The format can be either
28
- # a String (see #include_string_to_hash), an Array of Symbols and Hashes, or a mix of both.
29
- #
30
- # @example
31
- # `posts: [:author, comments: [:author, :upvotes]]`
32
- #
33
- # would become
34
- #
35
- # `{ posts: { author: {}, comments: { author: {}, upvotes: {} } } }`.
36
- #
37
- # @example
38
- # `[:author, :comments => [:author]]`
39
- #
40
- # would become
41
- #
42
- # `{:author => {}, :comments => { author: {} } }`
43
- #
44
- # @param [Symbol, Hash, Array, String] included
45
- # @return [Hash] a Hash representing the same tree structure
46
- def include_args_to_hash(included)
47
- case included
48
- when Symbol
49
- { included => {} }
50
- when Hash
51
- included.each_with_object({}) do |(key, value), hash|
52
- hash[key] = include_args_to_hash(value)
53
- end
54
- when Array
55
- included.reduce({}) { |a, e| a.deep_merge!(include_args_to_hash(e)) }
56
- when String
57
- include_string_to_hash(included)
58
- else
59
- {}
60
- end
61
- end
62
- end
63
-
64
- # Builds an IncludeTree from a comma separated list of dot separated paths (JSON API format).
65
- # @example `'posts.author, posts.comments.upvotes, posts.comments.author'`
66
- #
67
- # @param [String] included
68
- # @return [IncludeTree]
69
- #
70
- def self.from_string(included)
71
- new(Parsing.include_string_to_hash(included))
72
- end
73
-
74
- # Translates the arguments passed to the include option into an IncludeTree.
75
- # The format can be either a String (see #from_string), an Array of Symbols and Hashes, or a mix of both.
76
- # @example `posts: [:author, comments: [:author, :upvotes]]`
77
- #
78
- # @param [Symbol, Hash, Array, String] included
79
- # @return [IncludeTree]
80
- #
81
- def self.from_include_args(included)
82
- return included if included.is_a?(IncludeTree)
83
-
84
- new(Parsing.include_args_to_hash(included))
85
- end
86
-
87
- # @param [Hash] hash
88
- def initialize(hash = {})
89
- @hash = hash
90
- end
91
-
92
- def key?(key)
93
- @hash.key?(key) || @hash.key?(:*) || @hash.key?(:**)
94
- end
95
-
96
- def [](key)
97
- # TODO(beauby): Adopt a lazy caching strategy for generating subtrees.
98
- case
99
- when @hash.key?(key)
100
- self.class.new(@hash[key])
101
- when @hash.key?(:*)
102
- self.class.new(@hash[:*])
103
- when @hash.key?(:**)
104
- self.class.new(:** => {})
105
- else
106
- nil
107
- end
108
- end
109
- end
110
- end
111
- end
@@ -1,35 +0,0 @@
1
- module ActiveModel
2
- class Serializer
3
- module Links
4
- extend ActiveSupport::Concern
5
-
6
- included do
7
- with_options instance_writer: false, instance_reader: true do |serializer|
8
- serializer.class_attribute :_links # @api private
9
- self._links ||= {}
10
- end
11
-
12
- extend ActiveSupport::Autoload
13
- end
14
-
15
- module ClassMethods
16
- def inherited(base)
17
- super
18
- base._links = _links.dup
19
- end
20
-
21
- # Define a link on a serializer.
22
- # @example
23
- # link(:self) { resource_url(object) }
24
- # @example
25
- # link(:self) { "http://example.com/resource/#{object.id}" }
26
- # @example
27
- # link :resource, "http://example.com/resource"
28
- #
29
- def link(name, value = nil, &block)
30
- _links[name] = block || value
31
- end
32
- end
33
- end
34
- end
35
- end
@@ -1,29 +0,0 @@
1
- module ActiveModel
2
- class Serializer
3
- module Meta
4
- extend ActiveSupport::Concern
5
-
6
- included do
7
- with_options instance_writer: false, instance_reader: true do |serializer|
8
- serializer.class_attribute :_meta # @api private
9
- end
10
-
11
- extend ActiveSupport::Autoload
12
- end
13
-
14
- module ClassMethods
15
- # Set the JSON API meta attribute of a serializer.
16
- # @example
17
- # class AdminAuthorSerializer < ActiveModel::Serializer
18
- # meta { stuff: 'value' }
19
- # @example
20
- # meta do
21
- # { comment_count: object.comments.count }
22
- # end
23
- def meta(value = nil, &block)
24
- self._meta = block || value
25
- end
26
- end
27
- end
28
- end
29
- end