diff --git a/.coco.yml b/.coco.yml deleted file mode 100644 index 8fd397a..0000000 --- a/.coco.yml +++ /dev/null @@ -1,7 +0,0 @@ -:directories: -- lib -:excludes: -- test -- .direnv -:single_line_report: true -:show_link_in_terminal: true \ No newline at end of file diff --git a/README.md b/README.md index 45ea139..152ad59 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,11 @@ # ApiView -[![Build Status](https://travis-ci.org/mindreframer/api_view.svg?branch=master)](http://travis-ci.org/mindreframer/api_view) -[![codecov.io](https://codecov.io/github/mindreframer/api_view/coverage.svg?branch=master)](https://codecov.io/github/mindreframer/api_view?branch=master) +[![Build Status](https://travis-ci.org/ddd-ruby/api_view.png)](https://travis-ci.org/ddd-ruby/api_view) +[![Gem Version](https://badge.fury.io/rb/api_view.png)](http://badge.fury.io/rb/api_view) +[![Code Climate](https://codeclimate.com/github/ddd-ruby/api_view/badges/gpa.svg)](https://codeclimate.com/github/ddd-ruby/api_view) +[![codecov](https://codecov.io/gh/ddd-ruby/api_view/branch/master/graph/badge.svg)](https://codecov.io/gh/ddd-ruby/api_view) +[![Dependency Status](https://gemnasium.com/ddd-ruby/api_view.png)](https://gemnasium.com/ddd-ruby/api_view) + Object serializer with - small codebase @@ -46,51 +50,50 @@ ApiView gives you all that and stays very small doing that. -> `field` - a setter method, that also accepts `via: SomeSerializerApiView` - class EventApiView < EventSummaryApiView - # default serializer for BoxScore, will be picked, if none other was given - for_model ::Event - - # the attributes to copy from the object - attributes :share_url, :sport_name - - # the name of your main object, optional - main_object :event - - # the method to add additional logic + fields - def instance_convert - # just a setter method with optional serializer for that sub-object - field :box_score, event.box_score, via: BasketballBoxScoreApiView - end - end +```ruby +class EventApiView < EventSummaryApiView + # default serializer for BoxScore, will be picked, if none other was given + for_model ::Event + # the attributes to copy from the object + attributes :share_url, :sport_name + # the name of your main object, optional + main_object :event + # the method to add additional logic + fields + def instance_convert + # just a setter method with optional serializer for that sub-object + field :box_score, event.box_score, via: BasketballBoxScoreApiView + end +end - ## a more complete example - class Event - attr_accessor :game_date, :game_type, :status - end +## a more complete example +class Event + attr_accessor :game_date, :game_type, :status +end - class EventSerializer < ::ApiView::Base - attributes :game_date, :game_type, :status - main_object :event - for_model ::Event +class EventSerializer < ::ApiView::Base + attributes :game_date, :game_type, :status + main_object :event + for_model ::Event - # this is your chance to do extra work - def instance_convert - field :away_team, "any value here" - end - end + # this is your chance to do extra work + def instance_convert + field :away_team, "any value here" + end +end - e = Event.new; e.game_date = Time.now; e.game_type = 'baseball'; e.status = 'won' - EventSerializer.render(e) +e = Event.new; e.game_date = Time.now; e.game_type = 'baseball'; e.status = 'won' +EventSerializer.render(e) - # because we configured the mapping from serializer to a Ruby class, this also works: - ApiView::Engine.render(e) +# because we configured the mapping from serializer to a Ruby class, this also works: +ApiView::Engine.render(e) +``` - For more examples take a look into the `example/`-folder and run the benchmark script via `ruby example/benchmark.rb`. +For more examples take a look into the `example/`-folder and run the benchmark script via `ruby example/benchmark.rb`. diff --git a/api_view.gemspec b/api_view.gemspec index d5536b6..1115b73 100644 --- a/api_view.gemspec +++ b/api_view.gemspec @@ -18,10 +18,10 @@ Gem::Specification.new do |spec| spec.test_files = spec.files.grep(%r{^(test|spec|features)/}) spec.require_paths = ["lib"] - spec.add_development_dependency "bundler", "~> 1.7" - spec.add_development_dependency "rake", "~> 10.0" + spec.add_development_dependency "bundler", "~> 2.1" + spec.add_development_dependency "rake", "~> 12" spec.add_development_dependency "require_pattern" - spec.add_development_dependency "minitest", '~> 5.4.3' + spec.add_development_dependency "minitest", '~> 5.10' spec.add_development_dependency "mocha" spec.add_development_dependency "minitest-reporters" spec.add_development_dependency "oj" @@ -31,6 +31,4 @@ Gem::Specification.new do |spec| spec.add_development_dependency "ruby-prof" spec.add_development_dependency "allocation_stats" spec.add_development_dependency "bixby-bench" - spec.add_development_dependency "coco" - end diff --git a/benchmark_results.md b/benchmark_results.md index c3a4533..9eb85e6 100644 --- a/benchmark_results.md +++ b/benchmark_results.md @@ -1,13 +1,14 @@ + for Ruby ruby 2.5.7p206 (2019-10-01 revision 67816) [x86_64-darwin17] Object tests: user system total real allocations memsize - ApiView Ultra Simple 0.150000 0.000000 0.150000 ( 0.150730) 13 651 - ApiView Simple 0.280000 0.000000 0.280000 ( 0.274873) 17 2252 - ApiView Complex 0.260000 0.000000 0.260000 ( 0.259376) 21 1501 + ApiView Ultra Simple 0.117433 0.004252 0.121685 ( 0.121785) 14 1064 + ApiView Simple 0.250597 0.002926 0.253523 ( 0.253570) 27 3884 + ApiView Complex 0.229965 0.001594 0.231559 ( 0.231955) 29 2914 Collection tests: user system total real allocations memsize - ApiView Ultra Simple: Collection 0.020000 0.000000 0.020000 ( 0.021320) 113 46850 - ApiView Simple: Collection 0.120000 0.010000 0.130000 ( 0.124666) 712 187986 - ApiView Complex: Collection 0.150000 0.000000 0.150000 ( 0.150299) 1112 112886 + ApiView Ultra Simple: Collection 0.044432 0.000964 0.045396 ( 0.045640) 312 63276 + ApiView Simple: Collection 0.214602 0.005569 0.220171 ( 0.221290) 1811 338594 + ApiView Complex: Collection 0.159631 0.001276 0.160907 ( 0.161784) 2011 241594 diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..2f7efbe --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1 @@ +theme: jekyll-theme-minimal \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..bf66c35 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,158 @@ +# ApiView + +[![Build Status](https://travis-ci.org/ddd-ruby/api_view.png)](https://travis-ci.org/ddd-ruby/api_view) +[![Code Climate](https://codeclimate.com/github/ddd-ruby/api_view/badges/gpa.svg)](https://codeclimate.com/github/ddd-ruby/api_view) +[![codecov](https://codecov.io/gh/ddd-ruby/api_view/branch/master/graph/badge.svg)](https://codecov.io/gh/ddd-ruby/api_view) +[![Dependency Status](https://gemnasium.com/ddd-ruby/api_view.png)](https://gemnasium.com/ddd-ruby/api_view) + + +Object serializer with + - small codebase + - focus on performance + - benchmarks are guiding the implementation + - only MultiJson as sole dependency + + +The initial code was copied from `chetan` and wrapped into a gem with unit-tests and a bit more convenient API ( [original links](#original-links) ) + + + +### Why should you even care? Is (... insert your favourite ruby serializer ... ) not good enough? + + - you want great performance + - you care about object allocations (less garbage to collect for the Ruby VM) + - you want **blazing** fast test suite, so that you can switch globally the serialization off and test just the shape of the resulting Hash object + -> no converting to JSON, then parsing JSON back and checking values on it, that sux! + - really small and clean codebase + - zero dependencies (NO ACTIVESUPPORT!), but you should use MultiJson + OJ for best performance. + - unit-tested and with 100% test coverage + +ApiView gives you all that and stays very small doing that. + +## Installation + + ## Add this line to your application's Gemfile: + gem 'api_view' + + + ## And then execute: + $ bundle + + +## Usage + + - you inherit from ApiView::Base + - you say, what model should be serialized by default with this serializer (optional) + - you specify an array of attributes, that will be copied from the object in serializer + - you tell how you main object is called (defaults to `object` / `obj`) + - you implement `instance_convert`-method for further customization of the serialization + -> `field` - a setter method, that also accepts `via: SomeSerializerApiView` + + +```ruby +class EventApiView < EventSummaryApiView + # default serializer for BoxScore, will be picked, if none other was given + for_model ::Event + + # the attributes to copy from the object + attributes :share_url, :sport_name + + # the name of your main object, optional + main_object :event + + # the method to add additional logic + fields + def instance_convert + # just a setter method with optional serializer for that sub-object + field :box_score, event.box_score, via: BasketballBoxScoreApiView + end +end + +## a more complete example +class Event + attr_accessor :game_date, :game_type, :status +end + +class EventSerializer < ::ApiView::Base + attributes :game_date, :game_type, :status + main_object :event + for_model ::Event + + # this is your chance to do extra work + def instance_convert + field :away_team, "any value here" + end +end + +e = Event.new; e.game_date = Time.now; e.game_type = 'baseball'; e.status = 'won' +EventSerializer.render(e) + +# because we configured the mapping from serializer to a Ruby class, this also works: +ApiView::Engine.render(e) +``` + + + +For more examples take a look into the `example/`-folder and run the benchmark script via `ruby example/benchmark.rb`. + + + +## Developement + + # run tests + $ sh/test + + + + +## Contributing + +1. Fork it ( https://github.com/mindframer/api_view/fork ) +2. Create your feature branch (`git checkout -b my-new-feature`) +3. Commit your changes (`git commit -am 'Add some feature'`) +4. Push to the branch (`git push origin my-new-feature`) +5. Create a new Pull Request + + + +## Benchmark numbers (ApiView vs the rest of the pack) + + user system total real allocations memsize + RABL Ultra Simple 4.860000 0.620000 5.480000 ( 5.493406) 664 25787 + AMS Ultra Simple 0.220000 0.000000 0.220000 ( 0.220079) 26 650 + Presenters Ultra Simple 0.140000 0.000000 0.140000 ( 0.152729) 24 650 + ApiView Ultra Simple 0.190000 0.000000 0.190000 ( 0.193124) 12 842 + ------------------------------------------------------------------------------------------------------------------- + RABL Simple 21.470000 3.330000 24.800000 ( 25.147988) 2265 114051 + AMS Simple 1.060000 0.000000 1.060000 ( 1.066668) 105 2726 + Presenters Simple 0.610000 0.000000 0.610000 ( 0.611980) 98 2918 + ApiView Simple 0.280000 0.010000 0.290000 ( 0.292290) 17 2246 + ------------------------------------------------------------------------------------------------------------------- + RABL Complex 43.930000 6.850000 50.780000 ( 51.574975) 4325 248000 + AMS Complex 2.150000 0.000000 2.150000 ( 2.160445) 209 5851 + Presenters Complex 1.210000 0.010000 1.220000 ( 1.220806) 201 7395 + ApiView Complex 0.270000 0.000000 0.270000 ( 0.270517) 21 1504 + + + Collection tests: + + user system total real allocations memsize + RABL Ultra Simple: Collection 3.560000 0.600000 4.160000 ( 4.182852) 43102 1977224 + AMS Ultra Simple: Collection 0.120000 0.000000 0.120000 ( 0.124631) 1914 47786 + Presenters Ultra Simple: Collection 0.100000 0.010000 0.110000 ( 0.109781) 3508 67594 + ApiView Ultra Simple: Collection 0.050000 0.000000 0.050000 ( 0.050875) 311 46986 + ------------------------------------------------------------------------------------------------------------------- + RABL Simple: Collection 18.720000 3.150000 21.870000 ( 21.924020) 202905 11255130 + AMS Simple: Collection 0.870000 0.010000 0.880000 ( 0.890479) 9714 236186 + Presenters Simple: Collection 0.540000 0.000000 0.540000 ( 0.542100) 16108 380794 + ApiView Simple: Collection 0.160000 0.000000 0.160000 ( 0.166484) 812 187386 + ------------------------------------------------------------------------------------------------------------------- + RABL Complex: Collection 41.190000 6.680000 47.870000 ( 48.438854) 408015 25251570 + AMS Complex: Collection 2.170000 0.030000 2.200000 ( 2.211721) 20114 548686 + Presenters Complex: Collection 1.380000 0.010000 1.390000 ( 1.389608) 34408 960494 + ApiView Complex: Collection 0.150000 0.000000 0.150000 ( 0.145595) 1212 113186 + + +## Original links: + - http://techblog.thescore.com/benchmarking-json-generation-in-ruby/#comment-1678429451 + - https://github.com/chetan/json_serialization_benchmark/tree/api_view + - https://gist.github.com/chetan/d613e8f7d45600e1ca34 diff --git a/example/benchmark.rb b/example/benchmark.rb index f888717..153c86c 100644 --- a/example/benchmark.rb +++ b/example/benchmark.rb @@ -11,6 +11,8 @@ module SerializationBenchmark event_collection = collection_size.times.map { event } team_collection = collection_size.times.map { EventFactory.home_team } + puts "for Ruby " + `ruby -v`.strip + puts "\nObject tests:\n" Bixby::Bench.run(10_000) do |b| b.sample('ApiView Ultra Simple') do diff --git a/example/models/event_factory.rb b/example/models/event_factory.rb index b6b30fd..9f317b0 100644 --- a/example/models/event_factory.rb +++ b/example/models/event_factory.rb @@ -42,8 +42,8 @@ def self.box_score def self.away_team Team.new( abbreviation: 'MIA', - full_name: Faker::Name.name, - location: Faker::AddressUS.state, + full_name: FFaker::Name.name, + location: FFaker::AddressUS.state, meidum_name: 'Miami', short_name: 'Heats' ) @@ -52,9 +52,9 @@ def self.away_team def self.home_team Team.new( abbreviation: 'TOR', - full_name: Faker::Name.name, - location: Faker::AddressUS.state, - medium_name: Faker::AddressUS.state, + full_name: FFaker::Name.name, + location: FFaker::AddressUS.state, + medium_name: FFaker::AddressUS.state, short_name: 'Raptors' ) end diff --git a/lib/api_view/engine.rb b/lib/api_view/engine.rb index 8293b12..e7fb32c 100644 --- a/lib/api_view/engine.rb +++ b/lib/api_view/engine.rb @@ -1,10 +1,11 @@ +require "date" module ApiView class Engine # Classes which require no further conversion BASIC_TYPES = [ - String, Integer, Fixnum, Bignum, Float, + String, Integer, Bignum, Float, TrueClass, FalseClass, Time, Date, DateTime ] diff --git a/test/test_helper.rb b/test/test_helper.rb index a37045f..81c45b0 100644 --- a/test/test_helper.rb +++ b/test/test_helper.rb @@ -14,10 +14,11 @@ end Bundler.setup(:default, :development) -require 'minitest' -require 'mocha/mini_test' require "minitest/autorun" +gem 'mocha' +require 'mocha/minitest' + require 'minitest/reporters' reporter_options = { color: true, slow_count: 10 } Minitest::Reporters.use! [Minitest::Reporters::SpecReporter.new(reporter_options)]