From 2fc7aba3c337956cfc6ce92095c46966d139fcaa Mon Sep 17 00:00:00 2001 From: Laura Steadman Date: Thu, 29 Jan 2015 08:58:00 -0700 Subject: [PATCH] Deprecate `as_json` and `array_as_json`. Rename methods to `as_serialized` and `array_as_serialized`. --- README.md | 12 ++++++--- lib/restpack_serializer/serializable.rb | 24 ++++++++++++++--- .../serializable/paging.rb | 2 +- .../serializable/side_load_data_builder.rb | 2 +- .../serializable/single.rb | 2 +- spec/serializable/attributes_spec.rb | 4 +-- spec/serializable/serializer_spec.rb | 26 +++++++++---------- .../side_loading/belongs_to_spec.rb | 6 ++--- 8 files changed, 49 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index d08ea1d..725101d 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ class AlbumSerializer end ``` -`AlbumSerializer.as_json(album)` produces: +`AlbumSerializer.as_serialized(album)` produces: ```javascript { @@ -57,7 +57,7 @@ end } ``` -`as_json` accepts an optional `context` hash parameter which can be used by your Serializers to customize their output: +`as_serialized` accepts an optional `context` hash parameter which can be used by your Serializers to customize their output: ```ruby class AlbumSerializer @@ -75,7 +75,7 @@ end ``` ```ruby -AlbumSerializer.as_json(album, { admin?: true }) +AlbumSerializer.as_serialized(album, { admin?: true }) ``` ## Exposing an API @@ -99,7 +99,7 @@ These endpoint will live at URLs such as `/albums` and `/albums/142857`: * http://restpack-serializer-sample.herokuapp.com/api/v1/albums.json * http://restpack-serializer-sample.herokuapp.com/api/v1/albums/4.json -The `AlbumSerializer` also provides a `single` method which will return a serialized resource similar to `as_json` above. +The `AlbumSerializer` also provides a `single` method which will return a serialized resource similar to `as_serialized` above. `page`, `resource` and `single` methods take an optional scope argument allowing us to enforce arbitrary constraints: @@ -381,3 +381,7 @@ end `bundle` `rake spec` + +## Deprecation Notice + +The `as_json` method has been renamed to `as_serialized` to more accurately represent the output of the method. In addition, the `array_as_json` method has been renamed to `array_as_serialized`. For the time being, `as_json` and `array_as_json` wrappers have been provided to prevent breaking changes, but they will be removed in the future. diff --git a/lib/restpack_serializer/serializable.rb b/lib/restpack_serializer/serializable.rb index 770b66b..951c027 100644 --- a/lib/restpack_serializer/serializable.rb +++ b/lib/restpack_serializer/serializable.rb @@ -32,10 +32,15 @@ module Serializer class InvalidInclude < Exception; end + ## Note: `as_json is deprecated. Please use `as_serialized` instead. def as_json(model, context = {}) + as_serialized(model, context) + end + + def as_serialized(model, context = {}) return if model.nil? if model.kind_of?(Array) - return model.map { |item| as_json(item, context) } + return model.map { |item| as_serialized(item, context) } end @model, @context = model, context @@ -91,19 +96,30 @@ def include_attribute?(name) module ClassMethods attr_accessor :model_class, :href_prefix, :key + ## NOTE: `array_as_json` has been renamed + ## to `array_as_serialized` and is nowdeprecated. def array_as_json(models, context = {}) - new.as_json(models, context) + array_as_serialized(models, context) + end + + def array_as_serialized(models, context = {}) + new.as_serialized(models, context = {}) end + ## NOTE: `as_json` has been renamed to `as_serialized` and is now deprecated. def as_json(model, context = {}) - new.as_json(model, context) + as_serialized(model,context) + end + + def as_serialized(model, context = {}) + new.as_serialized(model, context) end def serialize(models, context = {}) models = [models] unless models.kind_of?(Array) { - self.key() => models.map {|model| self.as_json(model, context)} + self.key() => models.map {|model| self.as_serialized(model, context)} } end diff --git a/lib/restpack_serializer/serializable/paging.rb b/lib/restpack_serializer/serializable/paging.rb index 9ad2f46..562abc2 100644 --- a/lib/restpack_serializer/serializable/paging.rb +++ b/lib/restpack_serializer/serializable/paging.rb @@ -30,7 +30,7 @@ def page_with_options(options) private def serialize_page(page, options) - page.map { |model| self.as_json(model, options.context) } + page.map { |model| self.as_serialized(model, options.context) } end def serialize_meta(page, options) diff --git a/lib/restpack_serializer/serializable/side_load_data_builder.rb b/lib/restpack_serializer/serializable/side_load_data_builder.rb index 8900218..afbe2b1 100644 --- a/lib/restpack_serializer/serializable/side_load_data_builder.rb +++ b/lib/restpack_serializer/serializable/side_load_data_builder.rb @@ -11,7 +11,7 @@ def initialize(association, models, serializer) def side_load_belongs_to foreign_keys = @models.map { |model| model.send(@association.foreign_key) }.uniq side_load = @association.klass.find(foreign_keys) - json_model_data = side_load.map { |model| @serializer.as_json(model) } + json_model_data = side_load.map { |model| @serializer.as_serialized(model) } { @association.plural_name.to_sym => json_model_data, meta: { } } end diff --git a/lib/restpack_serializer/serializable/single.rb b/lib/restpack_serializer/serializable/single.rb index 09ee299..31ab407 100644 --- a/lib/restpack_serializer/serializable/single.rb +++ b/lib/restpack_serializer/serializable/single.rb @@ -6,7 +6,7 @@ def single(params = {}, scope = nil, context = {}) options = RestPack::Serializer::Options.new(self, params, scope, context) model = options.scope_with_filters.first - return model ? self.as_json(model, context) : nil + return model ? self.as_serialized(model, context) : nil end end end diff --git a/spec/serializable/attributes_spec.rb b/spec/serializable/attributes_spec.rb index b0f9556..b9abd2d 100644 --- a/spec/serializable/attributes_spec.rb +++ b/spec/serializable/attributes_spec.rb @@ -27,10 +27,10 @@ class CustomSerializer describe '#transform_attributes' do let(:model) { OpenStruct.new(gonzaga: 'IS A SCHOOL') } - subject(:as_json) { CustomSerializer.as_json(model) } + subject(:as_serialized) { CustomSerializer.as_serialized(model) } it 'uses the transform method on the model attribute' do - expect(as_json[:gonzaga]).to eq('is a school') + expect(as_serialized[:gonzaga]).to eq('is a school') end end end diff --git a/spec/serializable/serializer_spec.rb b/spec/serializable/serializer_spec.rb index aaa3e3a..04e3cea 100644 --- a/spec/serializable/serializer_spec.rb +++ b/spec/serializable/serializer_spec.rb @@ -26,8 +26,8 @@ class EmptySerializer include RestPack::Serializer end - it ".as_json serializes to an empty hash" do - EmptySerializer.as_json(person).should == { } + it ".as_serialized serializes to an empty hash" do + EmptySerializer.as_serialized(person).should == { } end end @@ -70,9 +70,9 @@ def custom_attributes end end - describe ".as_json" do + describe ".as_serialized" do it "serializes specified attributes" do - serializer.as_json(person).should == { + serializer.as_serialized(person).should == { id: '123', name: 'Gavin', description: 'This is person #123', href: '/people/123', custom_key: 'custom value for model id 123' } @@ -81,7 +81,7 @@ def custom_attributes context "an array" do let(:people) { [person, person] } it "results in a serialized array" do - serializer.as_json(people).should == [ + serializer.as_serialized(people).should == [ { id: '123', name: 'Gavin', description: 'This is person #123', href: '/people/123', custom_key: 'custom value for model id 123' @@ -92,9 +92,9 @@ def custom_attributes } ] end - context "#array_as_json" do + context "#array_as_serialized" do it "results in a serialized array" do - serializer.class.array_as_json(people).should == [ + serializer.class.array_as_serialized(people).should == [ { id: '123', name: 'Gavin', description: 'This is person #123', href: '/people/123', custom_key: 'custom value for model id 123' @@ -110,25 +110,25 @@ def custom_attributes context "nil" do it "results in nil" do - serializer.as_json(nil).should == nil + serializer.as_serialized(nil).should == nil end end context "with options" do it "excludes specified attributes" do - serializer.as_json(person, { include_description?: false }).should == { + serializer.as_serialized(person, { include_description?: false }).should == { id: '123', name: 'Gavin', href: '/people/123', custom_key: 'custom value for model id 123' } end it "excludes custom attributes if specified" do - hash = serializer.as_json(person, { is_admin?: false }) + hash = serializer.as_serialized(person, { is_admin?: false }) hash[:admin_info].should == nil end it "includes custom attributes if specified" do - hash = serializer.as_json(person, { is_admin?: true }) + hash = serializer.as_serialized(person, { is_admin?: true }) hash[:admin_info].should == { key: "super_secret_sauce", array: [ @@ -144,7 +144,7 @@ def custom_attributes it "includes 'links' data for :belongs_to associations" do @album1 = FactoryGirl.create(:album_with_songs, song_count: 11) - json = serializer.as_json(@album1.songs.first) + json = serializer.as_serialized(@album1.songs.first) json[:links].should == { artist: @album1.artist_id.to_s, album: @album1.id.to_s @@ -155,7 +155,7 @@ def custom_attributes context "with a serializer with has_* associations" do let(:artist_factory) { FactoryGirl.create :artist_with_fans } let(:artist_serializer) { MyApp::ArtistSerializer.new } - let(:json) { artist_serializer.as_json(artist_factory) } + let(:json) { artist_serializer.as_serialized(artist_factory) } let(:side_load_ids) { artist_has_association.map {|obj| obj.id.to_s } } context "when the association has been eager loaded" do diff --git a/spec/serializable/side_loading/belongs_to_spec.rb b/spec/serializable/side_loading/belongs_to_spec.rb index 2a341b5..bf40c3b 100644 --- a/spec/serializable/side_loading/belongs_to_spec.rb +++ b/spec/serializable/side_loading/belongs_to_spec.rb @@ -38,7 +38,7 @@ it "returns side-loaded albums" do side_loads.should == { - albums: [MyApp::AlbumSerializer.as_json(MyApp::Song.first.album)], + albums: [MyApp::AlbumSerializer.as_serialized(MyApp::Song.first.album)], meta: { } } end @@ -58,8 +58,8 @@ it "returns side-loaded albums" do side_loads.should == { albums: [ - MyApp::AlbumSerializer.as_json(song1.album), - MyApp::AlbumSerializer.as_json(song2.album) + MyApp::AlbumSerializer.as_serialized(song1.album), + MyApp::AlbumSerializer.as_serialized(song2.album) ], :meta => { } }