Repository: fast-jsonapi/fast_jsonapi Branch: master Commit: f40de017a213 Files: 47 Total size: 96.4 KB Directory structure: gitextract_curekkew/ ├── .github/ │ ├── dependabot.yml │ └── workflows/ │ └── ci.yml ├── .gitignore ├── .rspec ├── .rubocop.yml ├── CHANGELOG.md ├── Gemfile ├── LICENSE.txt ├── README.md ├── Rakefile ├── docs/ │ ├── ISSUE_TEMPLATE.md │ ├── PULL_REQUEST_TEMPLATE.md │ ├── json_serialization.md │ └── performance_methodology.md ├── jsonapi-serializer.gemspec ├── lib/ │ ├── extensions/ │ │ └── has_one.rb │ ├── fast_jsonapi/ │ │ ├── attribute.rb │ │ ├── helpers.rb │ │ ├── instrumentation/ │ │ │ └── skylight.rb │ │ ├── instrumentation.rb │ │ ├── link.rb │ │ ├── object_serializer.rb │ │ ├── railtie.rb │ │ ├── relationship.rb │ │ ├── scalar.rb │ │ ├── serialization_core.rb │ │ └── version.rb │ ├── fast_jsonapi.rb │ ├── generators/ │ │ └── serializer/ │ │ ├── USAGE │ │ ├── serializer_generator.rb │ │ └── templates/ │ │ └── serializer.rb.tt │ └── jsonapi/ │ ├── serializer/ │ │ ├── errors.rb │ │ ├── instrumentation.rb │ │ └── version.rb │ └── serializer.rb └── spec/ ├── fixtures/ │ ├── _user.rb │ ├── actor.rb │ └── movie.rb ├── integration/ │ ├── attributes_fields_spec.rb │ ├── caching_spec.rb │ ├── errors_spec.rb │ ├── instrumentation_spec.rb │ ├── key_transform_spec.rb │ ├── links_spec.rb │ ├── meta_spec.rb │ └── relationships_spec.rb └── spec_helper.rb ================================================ FILE CONTENTS ================================================ ================================================ FILE: .github/dependabot.yml ================================================ version: 2 updates: - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly" ================================================ FILE: .github/workflows/ci.yml ================================================ name: CI on: [push, pull_request] jobs: tests: runs-on: ubuntu-latest strategy: fail-fast: false matrix: ruby: [2.7, '3.0', 3.1, 3.2, 3.3, 3.4, head, truffleruby-head] steps: - uses: actions/checkout@v3 - name: Sets up the Ruby version uses: ruby/setup-ruby@v1 with: ruby-version: ${{ matrix.ruby }} - name: Sets up the environment run: | sudo apt-get install libsqlite3-dev - name: Install legacy bundler for Ruby 2.7 if: ${{ matrix.ruby == 2.7 }} run: | gem install -q bundler -v 2.4.22 - name: Install bundler 2.7+ for modern Rubies if: ${{ matrix.ruby != 2.7 }} run: | gem install -q bundler - name: Run bundle install run: | bundle install - name: Runs code QA and tests run: bundle exec rake - name: Publish to Rubygems continue-on-error: true if: ${{ github.ref == 'refs/heads/master' }} run: | mkdir -p $HOME/.gem touch $HOME/.gem/credentials chmod 0600 $HOME/.gem/credentials printf -- "---\n:rubygems_api_key: Bearer ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials gem build *.gemspec gem push *.gem env: GEM_HOST_API_KEY: ${{secrets.RUBYGEMS_AUTH_TOKEN}} ================================================ FILE: .gitignore ================================================ # rcov generated coverage coverage.data # rdoc generated rdoc # yard generated doc .yardoc # bundler .bundle .byebug_history # For MacOS: .DS_Store # For MacOS: .DS_Store # For TextMate #*.tmproj #tmtags *.swp # For redcar: #.redcar # For rubinius: #*.rbc # For the gem test.db # For those using rbenv .ruby-version # For those who install gems locally to a vendor dir /vendor # Don't checkin Gemfile.lock # See: https://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/ Gemfile.lock # Gem builds /*.gem ================================================ FILE: .rspec ================================================ --color ================================================ FILE: .rubocop.yml ================================================ plugins: - rubocop-performance - rubocop-rspec AllCops: NewCops: enable SuggestExtensions: false Style/FrozenStringLiteralComment: Enabled: false Style/SymbolArray: Enabled: false Style/WordArray: Enabled: false Style/SymbolProc: Exclude: - 'spec/fixtures/*.rb' Lint/DuplicateMethods: Exclude: - 'spec/fixtures/*.rb' RSpec/SpecFilePathFormat: Enabled: false RSpec/SpecFilePathSuffix: Enabled: false RSpec/DescribedClass: Enabled: false RSpec/ExampleLength: Enabled: false RSpec/MultipleExpectations: Enabled: false RSpec/NestedGroups: Enabled: false Performance/TimesMap: Exclude: - 'spec/**/**.rb' Gemspec/RequiredRubyVersion: Enabled: false # TODO: Fix these... Style/Documentation: Enabled: false Style/GuardClause: Exclude: - 'lib/**/**.rb' Style/ConditionalAssignment: Exclude: - 'lib/**/**.rb' Style/IfUnlessModifier: Exclude: - 'lib/**/**.rb' Lint/AssignmentInCondition: Exclude: - 'lib/**/**.rb' Metrics: Exclude: - 'lib/**/**.rb' Metrics/BlockLength: Enabled: false Layout/LineLength: Exclude: - 'lib/**/**.rb' Naming/PredicatePrefix: Exclude: - 'lib/**/**.rb' Naming/AccessorMethodName: Exclude: - 'lib/**/**.rb' Style/CaseLikeIf: Exclude: - 'lib/fast_jsonapi/object_serializer.rb' Style/OptionalBooleanParameter: Exclude: - 'lib/fast_jsonapi/serialization_core.rb' - 'lib/fast_jsonapi/relationship.rb' Lint/DuplicateBranch: Exclude: - 'lib/fast_jsonapi/relationship.rb' Style/DocumentDynamicEvalDefinition: Exclude: - 'lib/extensions/has_one.rb' ================================================ FILE: CHANGELOG.md ================================================ # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] - ... ## [2.2.0] - 2021-03-11 ### Added - Proper error is raised on unsupported includes (#125) ### Changed - Documentation updates (#137 #139 #143 #146) ### Fixed - Empty relationships are no longer added to serialized doc (#116) - Ruby v3 compatibility (#160) ## [2.1.0] - 2020-08-30 ### Added - Optional meta field to relationships (#99 #100) - Support for `params` on cache keys (#117) ### Changed - Performance instrumentation (#110 #39) - Improved collection detection (#112) ### Fixed - Ensure caching correctly incorporates fieldset information into the cache key to prevent incorrect fieldset caching (#90) - Performance optimizations for nested includes (#103) ## [2.0.0] - 2020-06-22 The project was renamed to `jsonapi-serializer`! (#94) ### Changed - Remove `ObjectSerializer#serialized_json` (#91) ## [1.7.2] - 2020-05-18 ### Fixed - Relationship#record_type_for does not assign static record type for polymorphic relationships (#83) ## [1.7.1] - 2020-05-01 ### Fixed - ObjectSerializer#serialized_json accepts arguments for to_json (#80) ## [1.7.0] - 2020-04-29 ### Added - Serializer option support for procs (#32) - JSON serialization API method is now implementable (#44) ### Changed - Support for polymorphic `id_method_name` (#17) - Relationships support for `&:proc` syntax (#58) - Conditional support for procs (#59) - Attribute support for procs (#67) - Refactor caching support (#52) - `is_collection?` is safer for objects (#18) ### Removed - `serialized_json` is now deprecated (#44) ## [1.6.0] - 2019-11-04 ### Added - Allow relationship links to be delcared as a method ([#2](https://github.com/fast-jsonapi/fast_jsonapi/pull/2)) - Test against Ruby 2.6 ([#1](https://github.com/fast-jsonapi/fast_jsonapi/pull/1)) - Include `data` key when lazy-loaded relationships are included ([#10](https://github.com/fast-jsonapi/fast_jsonapi/pull/10)) - Conditional links [#15](https://github.com/fast-jsonapi/fast_jsonapi/pull/15) - Include params on set_id block [#16](https://github.com/fast-jsonapi/fast_jsonapi/pull/16) ### Changed - Optimize SerializationCore.get_included_records calculates remaining_items only once ([#4](https://github.com/fast-jsonapi/fast_jsonapi/pull/4)) - Optimize SerializtionCore.parse_include_item by mapping in place ([#5](https://github.com/fast-jsonapi/fast_jsonapi/pull/5)) - Define ObjectSerializer.set_key_transform mapping as a constant ([#7](https://github.com/fast-jsonapi/fast_jsonapi/pull/7)) - Optimize SerializtionCore.remaining_items by taking from original array ([#9](https://github.com/fast-jsonapi/fast_jsonapi/pull/9)) - Optimize ObjectSerializer.deep_symbolize by using each_with_object instead of Hash[map] ([#6](https://github.com/fast-jsonapi/fast_jsonapi/pull/6)) ================================================ FILE: Gemfile ================================================ source 'https://rubygems.org' # Specify your gem's dependencies in fast_jsonapi.gemspec gemspec ================================================ FILE: LICENSE.txt ================================================ Apache License Version 2.0, January 2004 https://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "{}" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright {yyyy} {name of copyright owner} Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ================================================ FILE: README.md ================================================ # JSON:API Serialization Library ## :warning: :construction: v2 (the `master` branch) is in maintenance mode! :construction: :warning: We'll gladly accept bugfixes and security-related fixes for v2 (the `master` branch), but at this stage, contributions for new features/improvements are welcome only for v3. Please feel free to leave comments in the [v3 Pull Request](https://github.com/jsonapi-serializer/jsonapi-serializer/pull/141). --- A fast [JSON:API](https://jsonapi.org/) serializer for Ruby Objects. Previously this project was called **fast_jsonapi**, we forked the project and renamed it to **jsonapi/serializer** in order to keep it alive. We would like to thank the Netflix team for the initial work and to all our contributors and users for the continuous support! # Performance Comparison We compare serialization times with `ActiveModelSerializer` and alternative implementations as part of performance tests available at [jsonapi-serializer/comparisons](https://github.com/jsonapi-serializer/comparisons). We want to ensure that with every change on this library, serialization time stays significantly faster than the performance provided by the alternatives. Please read the performance article in the `docs` folder for any questions related to methodology. # Table of Contents * [Features](#features) * [Installation](#installation) * [Usage](#usage) * [Rails Generator](#rails-generator) * [Model Definition](#model-definition) * [Serializer Definition](#serializer-definition) * [Object Serialization](#object-serialization) * [Compound Document](#compound-document) * [Key Transforms](#key-transforms) * [Collection Serialization](#collection-serialization) * [Caching](#caching) * [Params](#params) * [Conditional Attributes](#conditional-attributes) * [Conditional Relationships](#conditional-relationships) * [Specifying a Relationship Serializer](#specifying-a-relationship-serializer) * [Ordering `has_many` Relationship](#ordering-has_many-relationship) * [Sparse Fieldsets](#sparse-fieldsets) * [Using helper methods](#using-helper-methods) * [Performance Instrumentation](#performance-instrumentation) * [Deserialization](#deserialization) * [Migrating from Netflix/fast_jsonapi](#migrating-from-netflixfast_jsonapi) * [Contributing](#contributing) ## Features * Declaration syntax similar to Active Model Serializer * Support for `belongs_to`, `has_many` and `has_one` * Support for compound documents (included) * Optimized serialization of compound documents * Caching ## Installation Add this line to your application's Gemfile: ```ruby gem 'jsonapi-serializer' ``` Execute: ```bash $ bundle install ``` ## Usage ### Rails Generator You can use the bundled generator if you are using the library inside of a Rails project: rails g serializer Movie name year This will create a new serializer in `app/serializers/movie_serializer.rb` ### Model Definition ```ruby class Movie attr_accessor :id, :name, :year, :actor_ids, :owner_id, :movie_type_id end ``` ### Serializer Definition ```ruby class MovieSerializer include JSONAPI::Serializer set_type :movie # optional set_id :owner_id # optional attributes :name, :year has_many :actors belongs_to :owner, record_type: :user belongs_to :movie_type end ``` ### Sample Object ```ruby movie = Movie.new movie.id = 232 movie.name = 'test movie' movie.actor_ids = [1, 2, 3] movie.owner_id = 3 movie.movie_type_id = 1 movie movies = 2.times.map do |i| m = Movie.new m.id = i + 1 m.name = "test movie #{i}" m.actor_ids = [1, 2, 3] m.owner_id = 3 m.movie_type_id = 1 m end ``` ### Object Serialization #### Return a hash ```ruby hash = MovieSerializer.new(movie).serializable_hash ``` #### Return Serialized JSON ```ruby json_string = MovieSerializer.new(movie).serializable_hash.to_json ``` #### Serialized Output ```json { "data": { "id": "3", "type": "movie", "attributes": { "name": "test movie", "year": null }, "relationships": { "actors": { "data": [ { "id": "1", "type": "actor" }, { "id": "2", "type": "actor" } ] }, "owner": { "data": { "id": "3", "type": "user" } } } } } ``` #### The Optionality of `set_type` By default fast_jsonapi will try to figure the type based on the name of the serializer class. For example `class MovieSerializer` will automatically have a type of `:movie`. If your serializer class name does not follow this format, you have to manually state the `set_type` at the serializer. ### Key Transforms By default fast_jsonapi underscores the key names. It supports the same key transforms that are supported by AMS. Here is the syntax of specifying a key transform ```ruby class MovieSerializer include JSONAPI::Serializer # Available options :camel, :camel_lower, :dash, :underscore(default) set_key_transform :camel end ``` Here are examples of how these options transform the keys ```ruby set_key_transform :camel # "some_key" => "SomeKey" set_key_transform :camel_lower # "some_key" => "someKey" set_key_transform :dash # "some_key" => "some-key" set_key_transform :underscore # "some_key" => "some_key" ``` ### Attributes Attributes are defined using the `attributes` method. This method is also aliased as `attribute`, which is useful when defining a single attribute. By default, attributes are read directly from the model property of the same name. In this example, `name` is expected to be a property of the object being serialized: ```ruby class MovieSerializer include JSONAPI::Serializer attribute :name end ``` Custom attributes that must be serialized but do not exist on the model can be declared using Ruby block syntax: ```ruby class MovieSerializer include JSONAPI::Serializer attributes :name, :year attribute :name_with_year do |object| "#{object.name} (#{object.year})" end end ``` The block syntax can also be used to override the property on the object: ```ruby class MovieSerializer include JSONAPI::Serializer attribute :name do |object| "#{object.name} Part 2" end end ``` Attributes can also use a different name by passing the original method or accessor with a proc shortcut: ```ruby class MovieSerializer include JSONAPI::Serializer attributes :name attribute :released_in_year, &:year end ``` ### Links Per Object Links are defined using the `link` method. By default, links are read directly from the model property of the same name. In this example, `public_url` is expected to be a property of the object being serialized. You can configure the method to use on the object for example a link with key `self` will get set to the value returned by a method called `url` on the movie object. You can also use a block to define a url as shown in `custom_url`. You can access params in these blocks as well as shown in `personalized_url` ```ruby class MovieSerializer include JSONAPI::Serializer link :public_url link :self, :url link :custom_url do |object| "https://movies.com/#{object.name}-(#{object.year})" end link :personalized_url do |object, params| "https://movies.com/#{object.name}-#{params[:user].reference_code}" end end ``` #### Links on a Relationship You can specify [relationship links](https://jsonapi.org/format/#document-resource-object-relationships) by using the `links:` option on the serializer. Relationship links in JSON API are useful if you want to load a parent document and then load associated documents later due to size constraints (see [related resource links](https://jsonapi.org/format/#document-resource-object-related-resource-links)) ```ruby class MovieSerializer include JSONAPI::Serializer has_many :actors, links: { self: :url, related: -> (object) { "https://movies.com/#{object.id}/actors" } } end ``` Relationship links can also be configured to be defined as a method on the object. ```ruby has_many :actors, links: :actor_relationship_links ``` This will create a `self` reference for the relationship, and a `related` link for loading the actors relationship later. NB: This will not automatically disable loading the data in the relationship, you'll need to do that using the `lazy_load_data` option: ```ruby has_many :actors, lazy_load_data: true, links: { self: :url, related: -> (object) { "https://movies.com/#{object.id}/actors" } } ``` ### Meta Per Resource For every resource in the collection, you can include a meta object containing non-standard meta-information about a resource that can not be represented as an attribute or relationship. ```ruby class MovieSerializer include JSONAPI::Serializer meta do |movie| { years_since_release: Date.current.year - movie.year } end end ``` #### Meta on a Relationship You can specify [relationship meta](https://jsonapi.org/format/#document-resource-object-relationships) by using the `meta:` option on the serializer. Relationship meta in JSON API is useful if you wish to provide non-standard meta-information about the relationship. Meta can be defined either by passing a static hash or by using Proc to the `meta` key. In the latter case, the record and any params passed to the serializer are available inside the Proc as the first and second parameters, respectively. ```ruby class MovieSerializer include JSONAPI::Serializer has_many :actors, meta: Proc.new do |movie_record, params| { count: movie_record.actors.length } end end ``` ### Compound Document Support for top-level and nested included associations through `options[:include]`. ```ruby options = {} options[:meta] = { total: 2 } options[:links] = { self: '...', next: '...', prev: '...' } options[:include] = [:actors, :'actors.agency', :'actors.agency.state'] MovieSerializer.new(movies, options).serializable_hash.to_json ``` ### Collection Serialization ```ruby options[:meta] = { total: 2 } options[:links] = { self: '...', next: '...', prev: '...' } hash = MovieSerializer.new(movies, options).serializable_hash json_string = MovieSerializer.new(movies, options).serializable_hash.to_json ``` #### Control Over Collection Serialization You can use `is_collection` option to have better control over collection serialization. If this option is not provided or `nil` autodetect logic is used to try understand if provided resource is a single object or collection. Autodetect logic is compatible with most DB toolkits (ActiveRecord, Sequel, etc.) but **cannot** guarantee that single vs collection will be always detected properly. ```ruby options[:is_collection] ``` was introduced to be able to have precise control this behavior - `nil` or not provided: will try to autodetect single vs collection (please, see notes above) - `true` will always treat input resource as *collection* - `false` will always treat input resource as *single object* ### Caching To enable caching, use `cache_options store: `: ```ruby class MovieSerializer include JSONAPI::Serializer # use rails cache with a separate namespace and fixed expiry cache_options store: Rails.cache, namespace: 'jsonapi-serializer', expires_in: 1.hour end ``` `store` is required can be anything that implements a `#fetch(record, **options, &block)` method: - `record` is the record that is currently serialized - `options` is everything that was passed to `cache_options` except `store`, so it can be everything the cache store supports - `&block` should be executed to fetch new data if cache is empty So for the example above it will call the cache instance like this: ```ruby Rails.cache.fetch(record, namespace: 'jsonapi-serializer', expires_in: 1.hour) { ... } ``` #### Caching and Sparse Fieldsets If caching is enabled and fields are provided to the serializer, the fieldset will be appended to the cache key's namespace. For example, given the following serializer definition and instance: ```ruby class ActorSerializer include JSONAPI::Serializer attributes :first_name, :last_name cache_options store: Rails.cache, namespace: 'jsonapi-serializer', expires_in: 1.hour end serializer = ActorSerializer.new(actor, { fields: { actor: [:first_name] } }) ``` The following cache namespace will be generated: `'jsonapi-serializer-fieldset:first_name'`. ### Params In some cases, attribute values might require more information than what is available on the record, for example, access privileges or other information related to a current authenticated user. The `options[:params]` value covers these cases by allowing you to pass in a hash of additional parameters necessary for your use case. Leveraging the new params is easy, when you define a custom id, attribute or relationship with a block you opt-in to using params by adding it as a block parameter. ```ruby class MovieSerializer include JSONAPI::Serializer set_id do |movie, params| # in here, params is a hash containing the `:admin` key params[:admin] ? movie.owner_id : "movie-#{movie.id}" end attributes :name, :year attribute :can_view_early do |movie, params| # in here, params is a hash containing the `:current_user` key params[:current_user].is_employee? ? true : false end belongs_to :primary_agent do |movie, params| # in here, params is a hash containing the `:current_user` key params[:current_user] end end # ... current_user = User.find(cookies[:current_user_id]) serializer = MovieSerializer.new(movie, {params: {current_user: current_user}}) serializer.serializable_hash ``` Custom attributes and relationships that only receive the resource are still possible by defining the block to only receive one argument. ### Conditional Attributes Conditional attributes can be defined by passing a Proc to the `if` key on the `attribute` method. Return `true` if the attribute should be serialized, and `false` if not. The record and any params passed to the serializer are available inside the Proc as the first and second parameters, respectively. ```ruby class MovieSerializer include JSONAPI::Serializer attributes :name, :year attribute :release_year, if: Proc.new { |record| # Release year will only be serialized if it's greater than 1990 record.release_year > 1990 } attribute :director, if: Proc.new { |record, params| # The director will be serialized only if the :admin key of params is true params && params[:admin] == true } # Custom attribute `name_year` will only be serialized if both `name` and `year` fields are present attribute :name_year, if: Proc.new { |record| record.name.present? && record.year.present? } do |object| "#{object.name} - #{object.year}" end end # ... current_user = User.find(cookies[:current_user_id]) serializer = MovieSerializer.new(movie, { params: { admin: current_user.admin? }}) serializer.serializable_hash ``` ### Conditional Relationships Conditional relationships can be defined by passing a Proc to the `if` key. Return `true` if the relationship should be serialized, and `false` if not. The record and any params passed to the serializer are available inside the Proc as the first and second parameters, respectively. ```ruby class MovieSerializer include JSONAPI::Serializer # Actors will only be serialized if the record has any associated actors has_many :actors, if: Proc.new { |record| record.actors.any? } # Owner will only be serialized if the :admin key of params is true belongs_to :owner, if: Proc.new { |record, params| params && params[:admin] == true } end # ... current_user = User.find(cookies[:current_user_id]) serializer = MovieSerializer.new(movie, { params: { admin: current_user.admin? }}) serializer.serializable_hash ``` ### Specifying a Relationship Serializer In many cases, the relationship can automatically detect the serializer to use. ```ruby class MovieSerializer include JSONAPI::Serializer # resolves to StudioSerializer belongs_to :studio # resolves to ActorSerializer has_many :actors end ``` At other times, such as when a property name differs from the class name, you may need to explicitly state the serializer to use. You can do so by specifying a different symbol or the serializer class itself (which is the recommended usage): ```ruby class MovieSerializer include JSONAPI::Serializer # resolves to MovieStudioSerializer belongs_to :studio, serializer: :movie_studio # resolves to PerformerSerializer has_many :actors, serializer: PerformerSerializer end ``` For more advanced cases, such as polymorphic relationships and Single Table Inheritance, you may need even greater control to select the serializer based on the specific object or some specified serialization parameters. You can do by defining the serializer as a `Proc`: ```ruby class MovieSerializer include JSONAPI::Serializer has_many :actors, serializer: Proc.new do |record, params| if record.comedian? ComedianSerializer elsif params[:use_drama_serializer] DramaSerializer else ActorSerializer end end end ``` ### Ordering `has_many` Relationship You can order the `has_many` relationship by providing a block: ```ruby class MovieSerializer include JSONAPI::Serializer has_many :actors do |movie| movie.actors.order(position: :asc) end end ``` ### Sparse Fieldsets Attributes and relationships can be selectively returned per record type by using the `fields` option. ```ruby class MovieSerializer include JSONAPI::Serializer attributes :name, :year end serializer = MovieSerializer.new(movie, { fields: { movie: [:name] } }) serializer.serializable_hash ``` ### Using helper methods You can mix-in code from another ruby module into your serializer class to reuse functions across your app. Since a serializer is evaluated in a the context of a `class` rather than an `instance` of a class, you need to make sure that your methods act as `class` methods when mixed in. ##### Using ActiveSupport::Concern ``` ruby module AvatarHelper extend ActiveSupport::Concern class_methods do def avatar_url(user) user.image.url end end end class UserSerializer include JSONAPI::Serializer include AvatarHelper # mixes in your helper method as class method set_type :user attributes :name, :email attribute :avatar do |user| avatar_url(user) end end ``` ##### Using Plain Old Ruby ``` ruby module AvatarHelper def avatar_url(user) user.image.url end end class UserSerializer include JSONAPI::Serializer extend AvatarHelper # mixes in your helper method as class method set_type :user attributes :name, :email attribute :avatar do |user| avatar_url(user) end end ``` ### Customizable Options Option | Purpose | Example ------------ | ------------- | ------------- set_type | Type name of Object | `set_type :movie` key | Key of Object | `belongs_to :owner, key: :user` set_id | ID of Object | `set_id :owner_id` or `set_id { \|record, params\| params[:admin] ? record.id : "#{record.name.downcase}-#{record.id}" }` cache_options | Hash with store to enable caching and optional further cache options | `cache_options store: ActiveSupport::Cache::MemoryStore.new, expires_in: 5.minutes` id_method_name | Set custom method name to get ID of an object (If block is provided for the relationship, `id_method_name` is invoked on the return value of the block instead of the resource object) | `has_many :locations, id_method_name: :place_ids` object_method_name | Set custom method name to get related objects | `has_many :locations, object_method_name: :places` record_type | Set custom Object Type for a relationship | `belongs_to :owner, record_type: :user` serializer | Set custom Serializer for a relationship | `has_many :actors, serializer: :custom_actor`, `has_many :actors, serializer: MyApp::Api::V1::ActorSerializer`, or `has_many :actors, serializer -> (object, params) { (return a serializer class) }` polymorphic | Allows different record types for a polymorphic association | `has_many :targets, polymorphic: true` polymorphic | Sets custom record types for each object class in a polymorphic association | `has_many :targets, polymorphic: { Person => :person, Group => :group }` ### Performance Instrumentation Performance instrumentation is available by using the `active_support/notifications`. To enable it, include the module in your serializer class: ```ruby require 'jsonapi/serializer' require 'jsonapi/serializer/instrumentation' class MovieSerializer include JSONAPI::Serializer include JSONAPI::Serializer::Instrumentation # ... end ``` [Skylight](https://www.skylight.io/) integration is also available and supported by us, follow the Skylight documentation to enable it. ### Running Tests The project has and requires unit tests, functional tests and performance tests. To run tests use the following command: ```bash rspec ``` ## Deserialization We currently do not support deserialization, but we recommend to use any of the next gems: ### [JSONAPI.rb](https://github.com/stas/jsonapi.rb) This gem provides the next features alongside deserialization: - Collection meta - Error handling - Includes and sparse fields - Filtering and sorting - Pagination ## Migrating from Netflix/fast_jsonapi If you come from [Netflix/fast_jsonapi](https://github.com/Netflix/fast_jsonapi), here is the instructions to switch. ### Modify your Gemfile ```diff - gem 'fast_jsonapi' + gem 'jsonapi-serializer' ``` ### Replace all constant references ```diff class MovieSerializer - include FastJsonapi::ObjectSerializer + include JSONAPI::Serializer end ``` ### Replace removed methods ```diff - json_string = MovieSerializer.new(movie).serialized_json + json_string = MovieSerializer.new(movie).serializable_hash.to_json ``` ### Replace require references ```diff - require 'fast_jsonapi' + require 'jsonapi/serializer' ``` ### Update your cache options See [docs](https://github.com/jsonapi-serializer/jsonapi-serializer#caching). ```diff - cache_options enabled: true, cache_length: 12.hours + cache_options store: Rails.cache, namespace: 'jsonapi-serializer', expires_in: 1.hour ``` ## Contributing Please follow the instructions we provide as part of the issue and pull request creation processes. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](https://contributor-covenant.org) code of conduct. ================================================ FILE: Rakefile ================================================ require 'bundler/gem_tasks' require 'rspec/core/rake_task' require 'rubocop/rake_task' desc('Codestyle check and linter') RuboCop::RakeTask.new('rubocop') do |task| task.fail_on_error = true task.patterns = [ 'lib/**/*.rb', 'spec/**/*.rb' ] end RSpec::Core::RakeTask.new(:spec) task(default: [:rubocop, :spec]) ================================================ FILE: docs/ISSUE_TEMPLATE.md ================================================ ## Expected Behavior ## Actual Behavior ## Steps to Reproduce the Problem 1. 2. 3. ## Specifications - Version: - Ruby version: ================================================ FILE: docs/PULL_REQUEST_TEMPLATE.md ================================================ ## What is the current behavior? ## What is the new behavior? ## Checklist Please make sure the following requirements are complete: - [ ] Tests for the changes have been added (for bug fixes / features) - [ ] Docs have been reviewed and added / updated if needed (for bug fixes / features) - [ ] All automated checks pass (CI/CD) ================================================ FILE: docs/json_serialization.md ================================================ # JSON Serialization Support Support for JSON serialization is no longer provided as part of the API of `fast_jsonapi`. This decision (see #12) is based on the idea that developers know better what library for JSON serialization works best for their project. To bring back the old functionality, define the `to_json` or `serialized_json` methods with the relevant JSON library call. Here's an example on how to get it working with the popular `oj` gem: ```ruby require 'oj' require 'fast_jsonapi' class BaseSerializer include JSONAPI::Serializer def to_json Oj.dump(serializable_hash) end alias_method :serialized_json, :to_json end class MovieSerializer < BaseSerializer # ... end ``` ================================================ FILE: docs/performance_methodology.md ================================================ # Performance using Fast JSON API We have been getting a few questions about Fast JSON API's performance statistics and the methodology used to measure the performance. This article is an attempt at addressing this aspect of the gem. ## Prologue With use cases like infinite scroll on complex models and bulk update on index pages, we started observing performance degradation on our Rails APIs. Our first step was to enable instrumentation and then tune for performance. We realized that, on average, more than 50% of the time was being spent on AMS serialization. At the same time, we had a couple of APIs that were simply proxying requests on top of a non-Rails, non-JSON API endpoint. Guess what? The non-Rails endpoints were giving us serialized JSON back in a fraction of the time spent by AMS. This led us to explore AMS documentation in depth in an effort to try a variety of techniques such as caching, using OJ for JSON string generation etc. It didn't yield the consistent results we were hoping to get. We loved the developer experience of using AMS, but wanted better performance for our use cases. We came up with patterns that we can rely upon such as: * We always use [JSON:API](https://jsonapi.org/) for our APIs * We almost always serialize a homogenous list of objects (Example: An array of movies) On the other hand: * AMS is designed to serialize JSON in several different formats, not just JSON:API * AMS can also handle lists that are not homogenous This led us to build our own object serialization library that would be faster because it would be tailored to our requirements. The usage of `fast_jsonapi` internally on production environments resulted in significant performance gains. ## Benchmark Setup The benchmark setup is simple with classes for `Movie, Actor, MovieType, User` on `movie_context.rb` for `fast_jsonapi` serializers and on `ams_context.rb` for AMS serializers. We benchmark the serializers with 1, 25, 250, 1000 movies, then we output the result. We also ensure that JSON string output is equivalent to ensure neither library is doing excess work compared to the other. Please checkout `spec/object_serializer_performance_spec.rb` ## Benchmark Results We benchmarked results for creating a Ruby Hash. This approach removes the effect of chosen JSON string generation engines like OJ, Yajl etc. Benchmarks indicate that `fast_jsonapi` consistently performs around 25 times faster than AMS in generating a ruby hash. We applied a similar benchmark on the operation to serialize the objects to a JSON string. This approach helps with ensuring some important criterias, such as: * OJ is used as the JSON engine for benchmarking both AMS and `fast_jsonapi` * The benchmark is easy to understand * The benchmark helps to improve performance * The benchmark influences design decisions for the gem This gem is currently used in several APIs at Netflix and has reduced the response times by more than half on many of these APIs. We truly appreciate the Ruby and Rails communities and wanted to contribute in an effort to help improve the performance of your APIs too. ## Epilogue `fast_jsonapi` is not a replacement for AMS. AMS is a great gem, and it does many things and is very flexible. We still use it for non JSON:API serialization and deserialization. What started off as an internal performance exercise evolved into `fast_jsonapi` and created an opportunity to give something back to the awesome **Ruby and Rails communities**. We are excited to share it with all of you since we believe that there will be **no** end to this need for speed on APIs. :) ================================================ FILE: jsonapi-serializer.gemspec ================================================ lib = File.expand_path('lib', __dir__) $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) require 'jsonapi/serializer/version' Gem::Specification.new do |gem| gem.name = 'jsonapi-serializer' gem.version = JSONAPI::Serializer::VERSION gem.authors = ['JSON:API Serializer Community'] gem.email = '' gem.summary = 'Fast JSON:API serialization library' gem.description = 'Fast, simple and easy to use ' \ 'JSON:API serialization library (also known as fast_jsonapi).' gem.homepage = 'https://github.com/jsonapi-serializer/jsonapi-serializer' gem.licenses = ['Apache-2.0'] gem.files = Dir['lib/**/*'] gem.require_paths = ['lib'] gem.extra_rdoc_files = ['LICENSE.txt', 'README.md'] gem.add_dependency('activesupport', '>= 4.2') gem.add_development_dependency('activerecord') gem.add_development_dependency('bundler') gem.add_development_dependency('byebug') gem.add_development_dependency('ffaker') gem.add_development_dependency('jsonapi-rspec', '>= 0.0.5') gem.add_development_dependency('rake') gem.add_development_dependency('rspec') gem.add_development_dependency('rubocop') gem.add_development_dependency('rubocop-performance') gem.add_development_dependency('rubocop-rspec') gem.add_development_dependency('simplecov') gem.add_development_dependency('sqlite3') gem.metadata['rubygems_mfa_required'] = 'true' end ================================================ FILE: lib/extensions/has_one.rb ================================================ # frozen_string_literal: true ActiveRecord::Associations::Builder::HasOne.class_eval do # Based on # https://github.com/rails/rails/blob/master/activerecord/lib/active_record/associations/builder/collection_association.rb#L50 # https://github.com/rails/rails/blob/master/activerecord/lib/active_record/associations/builder/singular_association.rb#L11 def self.define_accessors(mixin, reflection) super name = reflection.name mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1 def #{name}_id # if an attribute is already defined with this methods name we should just use it return read_attribute(__method__) if has_attribute?(__method__) association(:#{name}).reader.try(:id) end CODE end end ================================================ FILE: lib/fast_jsonapi/attribute.rb ================================================ require 'fast_jsonapi/scalar' module FastJsonapi class Attribute < Scalar; end end ================================================ FILE: lib/fast_jsonapi/helpers.rb ================================================ module FastJsonapi class << self # Calls either a Proc or a Lambda, making sure to never pass more parameters to it than it can receive # # @param [Proc] proc the Proc or Lambda to call # @param [Array] *params any number of parameters to be passed to the Proc # @return [Object] the result of the Proc call with the supplied parameters def call_proc(proc, *params) # The parameters array for a lambda created from a symbol (&:foo) differs # from explictly defined procs/lambdas, so we can't deduce the number of # parameters from the array length (and differs between Ruby 2.x and 3). # In the case of negative arity -- unlimited/unknown argument count -- # just send the object to act as the method receiver. if proc.arity.negative? proc.call(params.first) else proc.call(*params.take(proc.parameters.length)) end end end end ================================================ FILE: lib/fast_jsonapi/instrumentation/skylight.rb ================================================ require 'skylight' warn('DEPRECATION: Skylight support was moved into the `skylight` gem.') ================================================ FILE: lib/fast_jsonapi/instrumentation.rb ================================================ require 'jsonapi/serializer/instrumentation' warn( 'DEPRECATION: Performance instrumentation is no longer automatic. See: ' \ 'https://github.com/jsonapi-serializer/jsonapi-serializer' \ '#performance-instrumentation' ) ================================================ FILE: lib/fast_jsonapi/link.rb ================================================ require 'fast_jsonapi/scalar' module FastJsonapi class Link < Scalar; end end ================================================ FILE: lib/fast_jsonapi/object_serializer.rb ================================================ # frozen_string_literal: true require 'active_support' require 'active_support/time' require 'active_support/concern' require 'active_support/inflector' require 'active_support/core_ext/numeric/time' require 'fast_jsonapi/helpers' require 'fast_jsonapi/attribute' require 'fast_jsonapi/relationship' require 'fast_jsonapi/link' require 'fast_jsonapi/serialization_core' module FastJsonapi module ObjectSerializer extend ActiveSupport::Concern include SerializationCore TRANSFORMS_MAPPING = { camel: :camelize, camel_lower: [:camelize, :lower], dash: :dasherize, underscore: :underscore }.freeze included do # Set record_type based on the name of the serializer class set_type(reflected_record_type) if reflected_record_type end def initialize(resource, options = {}) process_options(options) @resource = resource end def serializable_hash if self.class.is_collection?(@resource, @is_collection) return hash_for_collection end hash_for_one_record end alias to_hash serializable_hash def hash_for_one_record serializable_hash = { data: nil } serializable_hash[:meta] = @meta if @meta.present? serializable_hash[:links] = @links if @links.present? return serializable_hash unless @resource serializable_hash[:data] = self.class.record_hash(@resource, @fieldsets[self.class.record_type.to_sym], @includes, @params) serializable_hash[:included] = self.class.get_included_records(@resource, @includes, @known_included_objects, @fieldsets, @params) if @includes.present? serializable_hash end def hash_for_collection serializable_hash = {} data = [] included = [] fieldset = @fieldsets[self.class.record_type.to_sym] @resource.each do |record| data << self.class.record_hash(record, fieldset, @includes, @params) included.concat self.class.get_included_records(record, @includes, @known_included_objects, @fieldsets, @params) if @includes.present? end serializable_hash[:data] = data serializable_hash[:included] = included if @includes.present? serializable_hash[:meta] = @meta if @meta.present? serializable_hash[:links] = @links if @links.present? serializable_hash end private def process_options(options) @fieldsets = deep_symbolize(options[:fields].presence || {}) @params = {} return if options.blank? @known_included_objects = Set.new @meta = options[:meta] @links = options[:links] @is_collection = options[:is_collection] @params = options[:params] || {} raise ArgumentError, '`params` option passed to serializer must be a hash' unless @params.is_a?(Hash) if options[:include].present? @includes = options[:include].reject(&:blank?).map(&:to_sym) self.class.validate_includes!(@includes) end end def deep_symbolize(collection) if collection.is_a? Hash collection.each_with_object({}) do |(k, v), hsh| hsh[k.to_sym] = deep_symbolize(v) end elsif collection.is_a? Array collection.map { |i| deep_symbolize(i) } else collection.to_sym end end class_methods do # Detects a collection/enumerable # # @return [TrueClass] on a successful detection def is_collection?(resource, force_is_collection = nil) return force_is_collection unless force_is_collection.nil? resource.is_a?(Enumerable) && !resource.respond_to?(:each_pair) end def inherited(subclass) super subclass.attributes_to_serialize = attributes_to_serialize.dup if attributes_to_serialize.present? subclass.relationships_to_serialize = relationships_to_serialize.dup if relationships_to_serialize.present? subclass.cachable_relationships_to_serialize = cachable_relationships_to_serialize.dup if cachable_relationships_to_serialize.present? subclass.uncachable_relationships_to_serialize = uncachable_relationships_to_serialize.dup if uncachable_relationships_to_serialize.present? subclass.transform_method = transform_method subclass.data_links = data_links.dup if data_links.present? subclass.cache_store_instance = cache_store_instance subclass.cache_store_options = cache_store_options subclass.set_type(subclass.reflected_record_type) if subclass.reflected_record_type subclass.meta_to_serialize = meta_to_serialize subclass.record_id = record_id end def reflected_record_type return @reflected_record_type if defined?(@reflected_record_type) @reflected_record_type ||= (name.split('::').last.chomp('Serializer').underscore.to_sym if name&.end_with?('Serializer')) end def set_key_transform(transform_name) self.transform_method = TRANSFORMS_MAPPING[transform_name.to_sym] # ensure that the record type is correctly transformed if record_type set_type(record_type) # TODO: Remove dead code elsif reflected_record_type set_type(reflected_record_type) end end def run_key_transform(input) if transform_method.present? input.to_s.send(*@transform_method).to_sym else input.to_sym end end def use_hyphen warn('DEPRECATION WARNING: use_hyphen is deprecated and will be removed from fast_jsonapi 2.0 use (set_key_transform :dash) instead') set_key_transform :dash end def set_type(type_name) self.record_type = run_key_transform(type_name) end def set_id(id_name = nil, &block) self.record_id = block || id_name end def cache_options(cache_options) # FIXME: remove this if block once deprecated cache_options are not supported anymore unless cache_options.key?(:store) # fall back to old, deprecated behaviour because no store was passed. # we assume the user explicitly wants new behaviour if he passed a # store because this is the new syntax. deprecated_cache_options(cache_options) return end self.cache_store_instance = cache_options[:store] self.cache_store_options = cache_options.except(:store) end # FIXME: remove this method once deprecated cache_options are not supported anymore def deprecated_cache_options(cache_options) warn('DEPRECATION WARNING: `store:` is a required cache option, we will default to `Rails.cache` for now. See https://github.com/fast-jsonapi/fast_jsonapi#caching for more information.') %i[enabled cache_length].select { |key| cache_options.key?(key) }.each do |key| warn("DEPRECATION WARNING: `#{key}` is a deprecated cache option and will have no effect soon. See https://github.com/fast-jsonapi/fast_jsonapi#caching for more information.") end self.cache_store_instance = cache_options[:enabled] ? Rails.cache : nil self.cache_store_options = { expires_in: cache_options[:cache_length] || 5.minutes, race_condition_ttl: cache_options[:race_condition_ttl] || 5.seconds } end def attributes(*attributes_list, &block) attributes_list = attributes_list.first if attributes_list.first.class.is_a?(Array) options = attributes_list.last.is_a?(Hash) ? attributes_list.pop : {} self.attributes_to_serialize = {} if attributes_to_serialize.nil? # to support calling `attribute` with a lambda, e.g `attribute :key, ->(object) { ... }` block = attributes_list.pop if attributes_list.last.is_a?(Proc) attributes_list.each do |attr_name| method_name = attr_name key = run_key_transform(method_name) attributes_to_serialize[key] = Attribute.new( key: key, method: block || method_name, options: options ) end end alias_method :attribute, :attributes def add_relationship(relationship) self.relationships_to_serialize = {} if relationships_to_serialize.nil? self.cachable_relationships_to_serialize = {} if cachable_relationships_to_serialize.nil? self.uncachable_relationships_to_serialize = {} if uncachable_relationships_to_serialize.nil? # TODO: Remove this undocumented option. # Delegate the caching to the serializer exclusively. if relationship.cached cachable_relationships_to_serialize[relationship.name] = relationship else uncachable_relationships_to_serialize[relationship.name] = relationship end relationships_to_serialize[relationship.name] = relationship end def has_many(relationship_name, options = {}, &block) relationship = create_relationship(relationship_name, :has_many, options, block) add_relationship(relationship) end def has_one(relationship_name, options = {}, &block) relationship = create_relationship(relationship_name, :has_one, options, block) add_relationship(relationship) end def belongs_to(relationship_name, options = {}, &block) relationship = create_relationship(relationship_name, :belongs_to, options, block) add_relationship(relationship) end def meta(meta_name = nil, &block) self.meta_to_serialize = block || meta_name end def create_relationship(base_key, relationship_type, options, block) name = base_key.to_sym if relationship_type == :has_many base_serialization_key = base_key.to_s.singularize id_postfix = '_ids' else base_serialization_key = base_key id_postfix = '_id' end polymorphic = fetch_polymorphic_option(options) Relationship.new( owner: self, key: options[:key] || run_key_transform(base_key), name: name, id_method_name: compute_id_method_name( options[:id_method_name], :"#{base_serialization_key}#{id_postfix}", polymorphic, options[:serializer], block ), record_type: options[:record_type], object_method_name: options[:object_method_name] || name, object_block: block, serializer: options[:serializer], relationship_type: relationship_type, cached: options[:cached], polymorphic: polymorphic, conditional_proc: options[:if], transform_method: @transform_method, meta: options[:meta], links: options[:links], lazy_load_data: options[:lazy_load_data] ) end def compute_id_method_name(custom_id_method_name, id_method_name_from_relationship, polymorphic, serializer, block) if block.present? || serializer.is_a?(Proc) || polymorphic custom_id_method_name || :id else custom_id_method_name || id_method_name_from_relationship end end def serializer_for(name) namespace = self.name.gsub(/()?\w+Serializer$/, '') serializer_name = "#{name.to_s.demodulize.classify}Serializer" serializer_class_name = namespace + serializer_name begin serializer_class_name.constantize rescue NameError raise NameError, "#{self.name} cannot resolve a serializer class for '#{name}'. " \ "Attempted to find '#{serializer_class_name}'. " \ 'Consider specifying the serializer directly through options[:serializer].' end end def fetch_polymorphic_option(options) option = options[:polymorphic] return false unless option.present? return option if option.respond_to? :keys {} end # def link(link_name, link_method_name = nil, &block) def link(*params, &block) self.data_links = {} if data_links.nil? options = params.last.is_a?(Hash) ? params.pop : {} link_name = params.first link_method_name = params[-1] key = run_key_transform(link_name) data_links[key] = Link.new( key: key, method: block || link_method_name, options: options ) end def validate_includes!(includes) return if includes.blank? parse_includes_list(includes).each_key do |include_item| relationship_to_include = relationships_to_serialize[include_item] raise(JSONAPI::Serializer::UnsupportedIncludeError.new(include_item, name)) unless relationship_to_include relationship_to_include.static_serializer # called for a side-effect to check for a known serializer class. end end end end end ================================================ FILE: lib/fast_jsonapi/railtie.rb ================================================ # frozen_string_literal: true require 'rails/railtie' class Railtie < Rails::Railtie initializer 'fast_jsonapi.active_record' do ActiveSupport.on_load :active_record do require 'extensions/has_one' end end end ================================================ FILE: lib/fast_jsonapi/relationship.rb ================================================ module FastJsonapi class Relationship attr_reader :owner, :key, :name, :id_method_name, :record_type, :object_method_name, :object_block, :serializer, :relationship_type, :cached, :polymorphic, :conditional_proc, :transform_method, :links, :meta, :lazy_load_data def initialize( owner:, key:, name:, id_method_name:, record_type:, object_method_name:, object_block:, serializer:, relationship_type:, polymorphic:, conditional_proc:, transform_method:, links:, meta:, cached: false, lazy_load_data: false ) @owner = owner @key = key @name = name @id_method_name = id_method_name @record_type = record_type @object_method_name = object_method_name @object_block = object_block @serializer = serializer @relationship_type = relationship_type @cached = cached @polymorphic = polymorphic @conditional_proc = conditional_proc @transform_method = transform_method @links = links || {} @meta = meta || {} @lazy_load_data = lazy_load_data @record_types_for = {} @serializers_for_name = {} end def serialize(record, included, serialization_params, output_hash) if include_relationship?(record, serialization_params) empty_case = relationship_type == :has_many ? [] : nil output_hash[key] = {} output_hash[key][:data] = ids_hash_from_record_and_relationship(record, serialization_params) || empty_case unless lazy_load_data && !included add_meta_hash(record, serialization_params, output_hash) if meta.present? add_links_hash(record, serialization_params, output_hash) if links.present? end end def fetch_associated_object(record, params) return FastJsonapi.call_proc(object_block, record, params) unless object_block.nil? record.send(object_method_name) end def include_relationship?(record, serialization_params) if conditional_proc.present? FastJsonapi.call_proc(conditional_proc, record, serialization_params) else true end end def serializer_for(record, serialization_params) # TODO: Remove this, dead code... if @static_serializer @static_serializer elsif polymorphic name = polymorphic[record.class] if polymorphic.is_a?(Hash) name ||= record.class.name serializer_for_name(name) elsif serializer.is_a?(Proc) FastJsonapi.call_proc(serializer, record, serialization_params) elsif object_block serializer_for_name(record.class.name) else # TODO: Remove this, dead code... raise "Unknown serializer for object #{record.inspect}" end end def static_serializer initialize_static_serializer unless @initialized_static_serializer @static_serializer end def static_record_type initialize_static_serializer unless @initialized_static_serializer @static_record_type end private def ids_hash_from_record_and_relationship(record, params = {}) initialize_static_serializer unless @initialized_static_serializer return ids_hash(fetch_id(record, params), @static_record_type) if @static_record_type return unless associated_object = fetch_associated_object(record, params) if associated_object.respond_to? :map return associated_object.map do |object| id_hash_from_record object, params end end id_hash_from_record associated_object, params end def id_hash_from_record(record, params) associated_record_type = record_type_for(record, params) id_hash(record.public_send(id_method_name), associated_record_type) end def ids_hash(ids, record_type) return ids.map { |id| id_hash(id, record_type) } if ids.respond_to? :map id_hash(ids, record_type) # ids variable is just a single id here end def id_hash(id, record_type, default_return = false) if id.present? { id: id.to_s, type: record_type } else default_return ? { id: nil, type: record_type } : nil end end def fetch_id(record, params) if object_block.present? object = FastJsonapi.call_proc(object_block, record, params) return object.map { |item| item.public_send(id_method_name) } if object.respond_to? :map return object.try(id_method_name) end record.public_send(id_method_name) end def add_links_hash(record, params, output_hash) output_hash[key][:links] = if links.is_a?(Symbol) record.public_send(links) else links.each_with_object({}) do |(key, method), hash| Link.new(key: key, method: method).serialize(record, params, hash) end end end def add_meta_hash(record, params, output_hash) output_hash[key][:meta] = if meta.is_a?(Proc) FastJsonapi.call_proc(meta, record, params) else meta end end def run_key_transform(input) if transform_method.present? input.to_s.send(*transform_method).to_sym else input.to_sym end end def initialize_static_serializer return if @initialized_static_serializer @static_serializer = compute_static_serializer @static_record_type = compute_static_record_type @initialized_static_serializer = true end def compute_static_serializer if polymorphic # polymorphic without a specific serializer -- # the serializer is determined on a record-by-record basis nil elsif serializer.is_a?(Symbol) || serializer.is_a?(String) # a serializer was explicitly specified by name -- determine the serializer class serializer_for_name(serializer) elsif serializer.is_a?(Proc) # the serializer is a Proc to be executed per object -- not static nil elsif serializer # something else was specified, e.g. a specific serializer class -- return it serializer elsif object_block # an object block is specified without a specific serializer -- # assume the objects might be different and infer the serializer by their class nil else # no serializer information was provided -- infer it from the relationship name serializer_name = name.to_s serializer_name = serializer_name.singularize if relationship_type.to_sym == :has_many serializer_for_name(serializer_name) end end def serializer_for_name(name) @serializers_for_name[name] ||= owner.serializer_for(name) end def record_type_for(record, serialization_params) # if the record type is static, return it return @static_record_type if @static_record_type # if not, use the record type of the serializer, and memoize the transformed version serializer = serializer_for(record, serialization_params) @record_types_for[serializer] ||= run_key_transform(serializer.record_type) end def compute_static_record_type if polymorphic nil elsif record_type run_key_transform(record_type) elsif @static_serializer run_key_transform(@static_serializer.record_type) end end end end ================================================ FILE: lib/fast_jsonapi/scalar.rb ================================================ module FastJsonapi class Scalar attr_reader :key, :method, :conditional_proc def initialize(key:, method:, options: {}) @key = key @method = method @conditional_proc = options[:if] end def serialize(record, serialization_params, output_hash) if conditionally_allowed?(record, serialization_params) if method.is_a?(Proc) output_hash[key] = FastJsonapi.call_proc(method, record, serialization_params) else output_hash[key] = record.public_send(method) end end end def conditionally_allowed?(record, serialization_params) if conditional_proc.present? FastJsonapi.call_proc(conditional_proc, record, serialization_params) else true end end end end ================================================ FILE: lib/fast_jsonapi/serialization_core.rb ================================================ # frozen_string_literal: true require 'active_support' require 'active_support/concern' require 'digest/sha1' module FastJsonapi MandatoryField = Class.new(StandardError) module SerializationCore extend ActiveSupport::Concern included do class << self attr_accessor :attributes_to_serialize, :relationships_to_serialize, :cachable_relationships_to_serialize, :uncachable_relationships_to_serialize, :transform_method, :record_type, :record_id, :cache_store_instance, :cache_store_options, :data_links, :meta_to_serialize end end class_methods do def id_hash(id, record_type, default_return = false) if id.present? { id: id.to_s, type: record_type } else default_return ? { id: nil, type: record_type } : nil end end def links_hash(record, params = {}) data_links.each_with_object({}) do |(_k, link), hash| link.serialize(record, params, hash) end end def attributes_hash(record, fieldset = nil, params = {}) attributes = attributes_to_serialize attributes = attributes.slice(*fieldset) if fieldset.present? attributes = {} if fieldset == [] attributes.each_with_object({}) do |(_k, attribute), hash| attribute.serialize(record, params, hash) end end def relationships_hash(record, relationships = nil, fieldset = nil, includes_list = nil, params = {}) relationships = relationships_to_serialize if relationships.nil? relationships = relationships.slice(*fieldset) if fieldset.present? relationships = {} if fieldset == [] relationships.each_with_object({}) do |(key, relationship), hash| included = includes_list.present? && includes_list.include?(key) relationship.serialize(record, included, params, hash) end end def meta_hash(record, params = {}) FastJsonapi.call_proc(meta_to_serialize, record, params) end def record_hash(record, fieldset, includes_list, params = {}) if cache_store_instance cache_opts = record_cache_options(cache_store_options, fieldset, includes_list, params) record_hash = cache_store_instance.fetch(record, **cache_opts) do temp_hash = id_hash(id_from_record(record, params), record_type, true) temp_hash[:attributes] = attributes_hash(record, fieldset, params) if attributes_to_serialize.present? temp_hash[:relationships] = relationships_hash(record, cachable_relationships_to_serialize, fieldset, includes_list, params) if cachable_relationships_to_serialize.present? temp_hash[:links] = links_hash(record, params) if data_links.present? temp_hash end record_hash[:relationships] = (record_hash[:relationships] || {}).merge(relationships_hash(record, uncachable_relationships_to_serialize, fieldset, includes_list, params)) if uncachable_relationships_to_serialize.present? else record_hash = id_hash(id_from_record(record, params), record_type, true) record_hash[:attributes] = attributes_hash(record, fieldset, params) if attributes_to_serialize.present? record_hash[:relationships] = relationships_hash(record, nil, fieldset, includes_list, params) if relationships_to_serialize.present? record_hash[:links] = links_hash(record, params) if data_links.present? end record_hash[:meta] = meta_hash(record, params) if meta_to_serialize.present? record_hash end # Cache options helper. Use it to adapt cache keys/rules. # # If a fieldset is specified, it modifies the namespace to include the # fields from the fieldset. # # @param options [Hash] default cache options # @param fieldset [Array, nil] passed fieldset values # @param includes_list [Array, nil] passed included values # @param params [Hash] the serializer params # # @return [Hash] processed options hash # rubocop:disable Lint/UnusedMethodArgument def record_cache_options(options, fieldset, includes_list, params) return options unless fieldset options = options ? options.dup : {} options[:namespace] ||= 'jsonapi-serializer' fieldset_key = fieldset.join('_') # Use a fixed-length fieldset key if the current length is more than # the length of a SHA1 digest if fieldset_key.length > 40 fieldset_key = Digest::SHA1.hexdigest(fieldset_key) end options[:namespace] = "#{options[:namespace]}-fieldset:#{fieldset_key}" options end # rubocop:enable Lint/UnusedMethodArgument def id_from_record(record, params) return FastJsonapi.call_proc(record_id, record, params) if record_id.is_a?(Proc) return record.send(record_id) if record_id raise MandatoryField, 'id is a mandatory field in the jsonapi spec' unless record.respond_to?(:id) record.id end # It chops out the root association (first part) from each include. # # It keeps an unique list and collects all of the rest of the include # value to hand it off to the next related to include serializer. # # This method will turn that include array into a Hash that looks like: # # { # authors: Set.new([ # 'books', # 'books.genre', # 'books.genre.books', # 'books.genre.books.authors', # 'books.genre.books.genre' # ]), # genre: Set.new(['books']) # } # # Because the serializer only cares about the root associations # included, it only needs the first segment of each include # (for books, it's the "authors" and "genre") and it doesn't need to # waste cycles parsing the rest of the include value. That will be done # by the next serializer in line. # # @param includes_list [List] to be parsed # @return [Hash] def parse_includes_list(includes_list) includes_list.each_with_object({}) do |include_item, include_sets| include_base, include_remainder = include_item.to_s.split('.', 2) include_sets[include_base.to_sym] ||= Set.new include_sets[include_base.to_sym] << include_remainder if include_remainder end end # includes handler def get_included_records(record, includes_list, known_included_objects, fieldsets, params = {}) return unless includes_list.present? return [] unless relationships_to_serialize includes_list = parse_includes_list(includes_list) includes_list.each_with_object([]) do |include_item, included_records| relationship_item = relationships_to_serialize[include_item.first] next unless relationship_item&.include_relationship?(record, params) included_objects = Array(relationship_item.fetch_associated_object(record, params)) next if included_objects.empty? static_serializer = relationship_item.static_serializer static_record_type = relationship_item.static_record_type included_objects.each do |inc_obj| serializer = static_serializer || relationship_item.serializer_for(inc_obj, params) record_type = static_record_type || serializer.record_type if include_item.last.any? serializer_records = serializer.get_included_records(inc_obj, include_item.last, known_included_objects, fieldsets, params) included_records.concat(serializer_records) unless serializer_records.empty? end code = "#{record_type}_#{serializer.id_from_record(inc_obj, params)}" next if known_included_objects.include?(code) known_included_objects << code included_records << serializer.record_hash(inc_obj, fieldsets[record_type], includes_list, params) end end end end end end ================================================ FILE: lib/fast_jsonapi/version.rb ================================================ module FastJsonapi VERSION = JSONAPI::Serializer::VERSION end ================================================ FILE: lib/fast_jsonapi.rb ================================================ # frozen_string_literal: true require 'jsonapi/serializer/errors' module FastJsonapi require 'fast_jsonapi/object_serializer' if defined?(::Rails) require 'fast_jsonapi/railtie' elsif defined?(::ActiveRecord) require 'extensions/has_one' end end ================================================ FILE: lib/generators/serializer/USAGE ================================================ Description: Generates a serializer for the given model. Example: rails generate serializer Movie This will create: app/serializers/movie_serializer.rb ================================================ FILE: lib/generators/serializer/serializer_generator.rb ================================================ # frozen_string_literal: true require 'rails/generators/base' class SerializerGenerator < Rails::Generators::NamedBase source_root File.expand_path('templates', __dir__) argument :attributes, type: :array, default: [], banner: 'field field' def create_serializer_file template 'serializer.rb.tt', File.join('app', 'serializers', class_path, "#{file_name}_serializer.rb") end private def attributes_names attributes.map { |a| a.name.to_sym.inspect } end end ================================================ FILE: lib/generators/serializer/templates/serializer.rb.tt ================================================ <% module_namespacing do -%> class <%= class_name %>Serializer include JSONAPI::Serializer attributes <%= attributes_names.join(", ") %> end <% end -%> ================================================ FILE: lib/jsonapi/serializer/errors.rb ================================================ # frozen_string_literal: true module JSONAPI module Serializer class Error < StandardError; end class UnsupportedIncludeError < Error attr_reader :include_item, :klass def initialize(include_item, klass) super() @include_item = include_item @klass = klass end def message "#{include_item} is not specified as a relationship on #{klass}" end end end end ================================================ FILE: lib/jsonapi/serializer/instrumentation.rb ================================================ require 'active_support' require 'active_support/notifications' module JSONAPI module Serializer # Support for instrumentation module Instrumentation # Performance instrumentation namespace NOTIFICATION_NAMESPACE = 'render.jsonapi-serializer.'.freeze # Patch methods to use instrumentation... %w[ serializable_hash get_included_records relationships_hash ].each do |method_name| define_method(method_name) do |*args| ActiveSupport::Notifications.instrument( NOTIFICATION_NAMESPACE + method_name, { name: self.class.name, serializer: self.class } ) do super(*args) end end end end end end ================================================ FILE: lib/jsonapi/serializer/version.rb ================================================ module JSONAPI module Serializer VERSION = '2.2.0'.freeze end end ================================================ FILE: lib/jsonapi/serializer.rb ================================================ require 'fast_jsonapi' module JSONAPI module Serializer # TODO: Move and cleanup the old implementation... def self.included(base) base.class_eval do include FastJsonapi::ObjectSerializer end end end end ================================================ FILE: spec/fixtures/_user.rb ================================================ require 'active_support' require 'active_support/cache' class User attr_accessor :uid, :first_name, :last_name, :email def self.fake(id = nil) faked = new faked.uid = id || SecureRandom.uuid faked.first_name = FFaker::Name.first_name faked.last_name = FFaker::Name.last_name faked.email = FFaker::Internet.email faked end end class NoSerializerUser < User end class UserSerializer include JSONAPI::Serializer set_id :uid attributes :first_name, :last_name, :email meta do |obj| { email_length: obj.email.size } end end module Cached class UserSerializer < ::UserSerializer cache_options( store: ActiveSupport::Cache::MemoryStore.new, namespace: 'test' ) end end ================================================ FILE: spec/fixtures/actor.rb ================================================ require 'active_support' require 'active_support/cache' require 'jsonapi/serializer/instrumentation' class Actor < User attr_accessor :movies, :movie_ids def self.fake(id = nil) faked = super faked.movies = [] faked.movie_ids = [] faked end def movie_urls { movie_url: movies[0]&.url } end end class ActorSerializer < UserSerializer set_type :actor attribute :email, if: ->(_object, params) { params[:conditionals_off].nil? } has_many( :played_movies, serializer: :movie, links: :movie_urls, if: ->(_object, params) { params[:conditionals_off].nil? } ) do |object| object.movies end end class CamelCaseActorSerializer include JSONAPI::Serializer set_key_transform :camel set_id :uid set_type :user_actor attributes :first_name link :movie_url do |obj| obj.movie_urls.values[0] end has_many( :played_movies, serializer: :movie ) do |object| object.movies end end class BadMovieSerializerActorSerializer < ActorSerializer has_many :played_movies, serializer: :bad, object_method_name: :movies end module Cached class ActorSerializer < ::ActorSerializer # TODO: Fix this, the serializer gets cached on inherited classes... has_many :played_movies, serializer: :movie do |object| object.movies end cache_options( store: ActiveSupport::Cache::MemoryStore.new, namespace: 'test' ) end end module Instrumented class ActorSerializer < ::ActorSerializer include ::JSONAPI::Serializer::Instrumentation end end ================================================ FILE: spec/fixtures/movie.rb ================================================ class Movie attr_accessor( :id, :name, :year, :actor_or_user, :actors, :actor_ids, :polymorphics, :owner, :owner_id ) def self.fake(id = nil) faked = new faked.id = id || SecureRandom.uuid faked.name = FFaker::Movie.title faked.year = FFaker::Vehicle.year faked.actors = [] faked.actor_ids = [] faked.polymorphics = [] faked end def url(obj = nil) @url ||= FFaker::Internet.http_url return @url if obj.nil? "#{@url}?#{obj.hash}" end def owner=(ownr) @owner = ownr @owner_id = ownr.uid end def actors=(acts) @actors = acts @actor_ids = actors.map do |actor| actor.movies << self actor.uid end end end class MovieSerializer include JSONAPI::Serializer set_type :movie attribute :released_in_year, &:year attributes :name attribute :release_year do |object, _params| object.year end link :self, :url belongs_to :owner, serializer: UserSerializer belongs_to :actor_or_user, id_method_name: :uid, polymorphic: { Actor => :actor, User => :user } has_many( :actors, meta: proc { |record, _| { count: record.actors.length } }, links: { actors_self: :url, related: ->(obj) { obj.url(obj) } } ) has_one( :creator, object_method_name: :owner, id_method_name: :uid, serializer: ->(object, _params) { UserSerializer if object.is_a?(User) } ) has_many( :actors_and_users, id_method_name: :uid, polymorphic: { Actor => :actor, User => :user } ) do |obj| obj.polymorphics end has_many( :dynamic_actors_and_users, id_method_name: :uid, polymorphic: true ) do |obj| obj.polymorphics end has_many( :auto_detected_actors_and_users, id_method_name: :uid ) do |obj| obj.polymorphics end end module Cached class MovieSerializer < ::MovieSerializer cache_options( store: ActorSerializer.cache_store_instance, namespace: 'test' ) has_one( :creator, id_method_name: :uid, serializer: :actor, # TODO: Remove this undocumented option. # Delegate the caching to the serializer exclusively. cached: false ) do |obj| obj.owner end end end ================================================ FILE: spec/integration/attributes_fields_spec.rb ================================================ require 'spec_helper' RSpec.describe JSONAPI::Serializer do let(:actor) do act = Actor.fake act.movies = [Movie.fake] act end let(:params) { {} } let(:serialized) do ActorSerializer.new(actor, params).serializable_hash.as_json end describe 'attributes' do it do expect(serialized['data']).to have_id(actor.uid) expect(serialized['data']).to have_type('actor') expect(serialized['data']) .to have_jsonapi_attributes('first_name', 'last_name', 'email').exactly expect(serialized['data']).to have_attribute('first_name') .with_value(actor.first_name) expect(serialized['data']).to have_attribute('last_name') .with_value(actor.last_name) expect(serialized['data']).to have_attribute('email') .with_value(actor.email) end context 'with nil identifier' do before { actor.uid = nil } it { expect(serialized['data']).to have_id(nil) } end context 'with `if` conditions' do let(:params) { { params: { conditionals_off: 'yes' } } } it do expect(serialized['data']).not_to have_attribute('email') end end context 'with include and fields' do let(:params) do { include: [:played_movies], fields: { movie: [:release_year], actor: [:first_name] } } end it do expect(serialized['data']) .to have_jsonapi_attributes(:first_name).exactly expect(serialized['included']).to include( have_type('movie') .and(have_id(actor.movies[0].id)) .and(have_jsonapi_attributes('release_year').exactly) ) end end end end ================================================ FILE: spec/integration/caching_spec.rb ================================================ require 'spec_helper' RSpec.describe JSONAPI::Serializer do let(:actor) do faked = Actor.fake movie = Movie.fake movie.owner = User.fake movie.actors = [faked] faked.movies = [movie] faked end let(:cache_store) { Cached::ActorSerializer.cache_store_instance } describe 'with caching' do it do expect(cache_store.delete(actor, namespace: 'test')).to be(false) Cached::ActorSerializer.new( [actor, actor], include: ['played_movies', 'played_movies.owner'] ).serializable_hash expect(cache_store.delete(actor, namespace: 'test')).to be(true) expect(cache_store.delete(actor.movies[0], namespace: 'test')).to be(true) expect( cache_store.delete(actor.movies[0].owner, namespace: 'test') ).to be(false) end context 'without relationships' do let(:user) { User.fake } let(:serialized) { Cached::UserSerializer.new(user).serializable_hash.as_json } it do expect(serialized['data']).not_to have_key('relationships') end end end describe 'with caching and different fieldsets' do context 'when fieldset is provided' do it 'includes the fieldset in the namespace' do expect(cache_store.delete(actor, namespace: 'test')).to be(false) Cached::ActorSerializer.new( [actor], fields: { actor: %i[first_name] } ).serializable_hash # Expect cached keys to match the passed fieldset expect(cache_store.read(actor, namespace: 'test-fieldset:first_name')[:attributes].keys).to eq(%i[first_name]) Cached::ActorSerializer.new( [actor] ).serializable_hash # Expect cached keys to match all valid actor fields (no fieldset) expect(cache_store.read(actor, namespace: 'test')[:attributes].keys).to eq(%i[first_name last_name email]) expect(cache_store.delete(actor, namespace: 'test')).to be(true) expect(cache_store.delete(actor, namespace: 'test-fieldset:first_name')).to be(true) end end context 'when long fieldset is provided' do let(:actor_keys) { %i[first_name last_name more_fields yet_more_fields so_very_many_fields] } let(:digest_key) { Digest::SHA1.hexdigest(actor_keys.join('_')) } it 'includes the hashed fieldset in the namespace' do Cached::ActorSerializer.new( [actor], fields: { actor: actor_keys } ).serializable_hash expect(cache_store.read(actor, namespace: "test-fieldset:#{digest_key}")[:attributes].keys).to eq( %i[first_name last_name] ) expect(cache_store.delete(actor, namespace: "test-fieldset:#{digest_key}")).to be(true) end end end end ================================================ FILE: spec/integration/errors_spec.rb ================================================ require 'spec_helper' RSpec.describe JSONAPI::Serializer do let(:actor) { Actor.fake } let(:params) { {} } describe 'with errors' do it do expect do BadMovieSerializerActorSerializer.new( actor, include: ['played_movies'] ) end.to raise_error( NameError, /cannot resolve a serializer class for 'bad'/ ) end it do expect { ActorSerializer.new(actor, include: ['bad_include']) } .to raise_error( JSONAPI::Serializer::UnsupportedIncludeError, /bad_include is not specified as a relationship/ ) end end end ================================================ FILE: spec/integration/instrumentation_spec.rb ================================================ require 'spec_helper' # Needed to subscribe to `active_support/notifications` require 'concurrent' RSpec.describe JSONAPI::Serializer do let(:serializer) do Instrumented::ActorSerializer.new(Actor.fake) end it do payload = event_name = nil notification_name = "#{JSONAPI::Serializer::Instrumentation::NOTIFICATION_NAMESPACE}serializable_hash" ActiveSupport::Notifications.subscribe( notification_name ) do |ev_name, _s, _f, _i, ev_payload| event_name = ev_name payload = ev_payload end expect(serializer.serializable_hash).not_to be_nil expect(event_name).to eq('render.jsonapi-serializer.serializable_hash') expect(payload[:name]).to eq(serializer.class.name) expect(payload[:serializer]).to eq(serializer.class) end end ================================================ FILE: spec/integration/key_transform_spec.rb ================================================ require 'spec_helper' RSpec.describe JSONAPI::Serializer do let(:actor) { Actor.fake } let(:params) { {} } let(:serialized) do CamelCaseActorSerializer.new(actor, params).serializable_hash.as_json end describe 'camel case key tranformation' do it do expect(serialized['data']).to have_id(actor.uid) expect(serialized['data']).to have_type('UserActor') expect(serialized['data']).to have_attribute('FirstName') expect(serialized['data']).to have_relationship('PlayedMovies') expect(serialized['data']).to have_link('MovieUrl').with_value(nil) end end end ================================================ FILE: spec/integration/links_spec.rb ================================================ require 'spec_helper' RSpec.describe JSONAPI::Serializer do let(:movie) do faked = Movie.fake faked.actors = [Actor.fake] faked end let(:params) { {} } let(:serialized) do MovieSerializer.new(movie, params).serializable_hash.as_json end describe 'links' do it do expect(serialized['data']).to have_link('self').with_value(movie.url) expect(serialized['data']['relationships']['actors']) .to have_link('actors_self').with_value(movie.url) expect(serialized['data']['relationships']['actors']) .to have_link('related').with_value(movie.url(movie)) end context 'with included records' do let(:serialized) do ActorSerializer.new(movie.actors[0]).serializable_hash.as_json end it do expect(serialized['data']['relationships']['played_movies']) .to have_link('movie_url').with_value(movie.url) end end context 'with root link' do let(:params) do { links: { 'root_link' => FFaker::Internet.http_url } } end it do expect(serialized) .to have_link('root_link').with_value(params[:links]['root_link']) end end end end ================================================ FILE: spec/integration/meta_spec.rb ================================================ require 'spec_helper' RSpec.describe JSONAPI::Serializer do let(:user) { User.fake } let(:params) { {} } let(:serialized) do UserSerializer.new(user, params).serializable_hash.as_json end it do expect(serialized['data']).to have_meta('email_length' => user.email.size) end context 'with root meta' do let(:params) do { meta: { 'code' => FFaker::Internet.password } } end it do expect(serialized).to have_meta(params[:meta]) end end end ================================================ FILE: spec/integration/relationships_spec.rb ================================================ require 'spec_helper' RSpec.describe JSONAPI::Serializer do let(:movie) do mov = Movie.fake mov.actors = rand(2..5).times.map { Actor.fake } mov.owner = User.fake poly_act = Actor.fake poly_act.movies = [Movie.fake] mov.polymorphics = [User.fake, poly_act] mov.actor_or_user = Actor.fake mov end let(:params) { {} } let(:serialized) do MovieSerializer.new(movie, params).serializable_hash.as_json end describe 'relationships' do it do actors_rel = movie.actors.map { |a| { 'id' => a.uid, 'type' => 'actor' } } expect(serialized['data']) .to have_relationship('actors').with_data(actors_rel) expect(serialized['data']) .to have_relationship('owner') .with_data('id' => movie.owner.uid, 'type' => 'user') expect(serialized['data']) .to have_relationship('creator') .with_data('id' => movie.owner.uid, 'type' => 'user') expect(serialized['data']) .to have_relationship('actors_and_users') .with_data( [ { 'id' => movie.polymorphics[0].uid, 'type' => 'user' }, { 'id' => movie.polymorphics[1].uid, 'type' => 'actor' } ] ) expect(serialized['data']) .to have_relationship('dynamic_actors_and_users') .with_data( [ { 'id' => movie.polymorphics[0].uid, 'type' => 'user' }, { 'id' => movie.polymorphics[1].uid, 'type' => 'actor' } ] ) expect(serialized['data']) .to have_relationship('auto_detected_actors_and_users') .with_data( [ { 'id' => movie.polymorphics[0].uid, 'type' => 'user' }, { 'id' => movie.polymorphics[1].uid, 'type' => 'actor' } ] ) end describe 'has relationship meta' do it do expect(serialized['data']['relationships']['actors']) .to have_meta('count' => movie.actors.length) end end context 'with include' do let(:params) do { include: [:actors] } end it do movie.actors.each do |actor| expect(serialized['included']).to include( have_type('actor') .and(have_id(actor.uid)) .and(have_relationship('played_movies') .with_data([{ 'id' => actor.movies[0].id, 'type' => 'movie' }])) ) end end context 'with `if` conditions' do let(:params) do { include: ['actors'], params: { conditionals_off: 'yes' } } end it do movie.actors.each do |actor| expect(serialized['included']).not_to include( have_type('actor') .and(have_id(actor.uid)) .and(have_relationship('played_movies')) ) end end end context 'with has_many polymorphic' do let(:params) do { include: ['actors_and_users.played_movies'] } end it do expect(serialized['included']).to include( have_type('user').and(have_id(movie.polymorphics[0].uid)) ) expect(serialized['included']).to include( have_type('movie').and(have_id(movie.polymorphics[1].movies[0].id)) ) expect(serialized['included']).to include( have_type('actor') .and(have_id(movie.polymorphics[1].uid)) .and( have_relationship('played_movies').with_data( [{ 'id' => movie.polymorphics[1].movies[0].id, 'type' => 'movie' }] ) ) ) end end context 'with belongs_to polymorphic' do let(:params) do { include: ['actor_or_user'] } end it do expect(serialized['included']).to include( have_type('actor').and(have_id(movie.actor_or_user.uid)) ) end end end end end ================================================ FILE: spec/spec_helper.rb ================================================ unless RUBY_ENGINE == 'truffleruby' require 'simplecov' SimpleCov.start do add_group 'Lib', 'lib' add_group 'Tests', 'spec' end SimpleCov.minimum_coverage 90 end require 'active_support' require 'active_support/core_ext/object' require 'active_support/core_ext/object/json' require 'jsonapi/serializer' require 'ffaker' require 'rspec' require 'jsonapi/rspec' require 'byebug' require 'securerandom' Dir[File.expand_path('spec/fixtures/*.rb')].sort.each { |f| require f } RSpec.configure do |config| config.include JSONAPI::RSpec config.mock_with :rspec config.filter_run_when_matching :focus config.disable_monkey_patching! config.expect_with :rspec do |c| c.syntax = :expect end end