ams_lazy_relationships 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 250cb8632ee5305b7f64e9c405d234f4314efd44
-  data.tar.gz: 13a9171c97c9404bf6bf999d089f65bafcc0240d
+  metadata.gz: 2a98cab560bd1120e26c240598acbe505250f486
+  data.tar.gz: 908ccee8070ca834715135833da3fb7e5e9faed9
 SHA512:
-  metadata.gz: c43418b6e95a06f7e5e1ca453004792b2b42f10a02a97f4f07b48304c02b0792ee706b14a548a4d97c95c32ff459e4884ebda4fec5dc3cb842f6cff05e565862
-  data.tar.gz: 1b574d51889e7ba67bce43b433e94d9da706f47d38008bbe81f804844380a8fd2f3231a467edb8705dc534215ce42439abcedc20b983887226122c26f40f2d8f
+  metadata.gz: 32dcc6601a4f8670806f58617d5342f5d601ab3a1c40ef17016912667aa91d36993d90bd65107223bee4fa7bb4af14d7585f3e2455385f2d0e1cd1f4342cb970
+  data.tar.gz: '0779950cd56d399924d3f7bbd5439d95d2dcb16f5e37294962b64c27a176270c746dd8aacc454b8666f03b217185a31af059b63da4d46a50be2fbe28be8d8b92'

data/.gitignore

@@ -10,5 +10,5 @@
 # rspec failure tracking
 .rspec_status
 
-Gemfile.lock
 gemfiles/*.lock
+.DS_Store

data/.travis.yml

@@ -12,7 +12,7 @@ cache: bundler
 rvm:
   - 2.3.4
 before_install:
-  - gem install bundler undercover --no-doc
+  - gem install bundler:1.17 undercover --no-doc
 before_script:
   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
   - chmod +x ./cc-test-reporter

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Change Log
 
-## [0.1.0](https://github.com/Bajena/ams_lazy_relationships/tree/0.1.0) (2018-12-30)
+## [0.1.1](https://github.com/Bajena/ams_lazy_relationships/tree/0.1.1) (2019-01-09)
+[Full Changelog](https://github.com/Bajena/ams_lazy_relationships/compare/v0.1.0...0.1.1)
+
+**Merged pull requests:**
+
+- Relax batch-loader version [\#13](https://github.com/Bajena/ams_lazy_relationships/pull/13) ([Bajena](https://github.com/Bajena))
+
+## [v0.1.0](https://github.com/Bajena/ams_lazy_relationships/tree/v0.1.0) (2018-12-30)
 **Closed issues:**
 
 - Add changelog [\#10](https://github.com/Bajena/ams_lazy_relationships/issues/10)

data/Gemfile.lock

@@ -0,0 +1,201 @@
+PATH
+  remote: .
+  specs:
+    ams_lazy_relationships (0.1.1)
+      active_model_serializers
+      batch-loader (~> 1.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actionpack (5.2.2)
+      actionview (= 5.2.2)
+      activesupport (= 5.2.2)
+      rack (~> 2.0)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.2.2)
+      activesupport (= 5.2.2)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    active_model_serializers (0.10.8)
+      actionpack (>= 4.1, < 6)
+      activemodel (>= 4.1, < 6)
+      case_transform (>= 0.2)
+      jsonapi-renderer (>= 0.1.1.beta1, < 0.3)
+    activemodel (5.2.2)
+      activesupport (= 5.2.2)
+    activerecord (5.2.2)
+      activemodel (= 5.2.2)
+      activesupport (= 5.2.2)
+      arel (>= 9.0)
+    activesupport (5.2.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
+    appraisal (2.2.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    arel (9.0.0)
+    ast (2.4.0)
+    batch-loader (1.2.2)
+    builder (3.2.3)
+    case_transform (0.2)
+      activesupport
+    coderay (1.1.2)
+    concurrent-ruby (1.1.4)
+    crass (1.0.4)
+    db-query-matchers (0.9.0)
+      activesupport (>= 4.0, <= 6.0)
+      rspec (~> 3.0)
+    diff-lcs (1.3)
+    docile (1.3.1)
+    erubi (1.8.0)
+    faraday (0.15.4)
+      multipart-post (>= 1.2, < 3)
+    faraday-http-cache (2.0.0)
+      faraday (~> 0.8)
+    github_changelog_generator (1.14.3)
+      activesupport
+      faraday-http-cache
+      multi_json
+      octokit (~> 4.6)
+      rainbow (>= 2.1)
+      rake (>= 10.0)
+      retriable (~> 2.1)
+    i18n (1.5.1)
+      concurrent-ruby (~> 1.0)
+    imagen (0.1.5)
+      parser (>= 2.5, != 2.5.1.1)
+    jaro_winkler (1.5.2)
+    json (2.1.0)
+    jsonapi-renderer (0.2.0)
+    loofah (2.2.3)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    method_source (0.8.2)
+    mini_portile2 (2.4.0)
+    minitest (5.11.3)
+    multi_json (1.13.1)
+    multipart-post (2.0.0)
+    nokogiri (1.10.0)
+      mini_portile2 (~> 2.4.0)
+    octokit (4.13.0)
+      sawyer (~> 0.8.0, >= 0.5.3)
+    parallel (1.12.1)
+    parser (2.5.3.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    pry (0.10.4)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    pry-nav (0.2.4)
+      pry (>= 0.9.10, < 0.11.0)
+    public_suffix (3.0.3)
+    rack (2.0.6)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.0.4)
+      loofah (~> 2.2, >= 2.2.2)
+    railties (5.2.2)
+      actionpack (= 5.2.2)
+      activesupport (= 5.2.2)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.19.0, < 2.0)
+    rainbow (2.2.2)
+      rake
+    rake (10.5.0)
+    retriable (2.1.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-rails (3.8.1)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.61.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    rubocop-rspec (1.20.1)
+      rubocop (>= 0.51.0)
+    ruby-progressbar (1.10.0)
+    rugged (0.27.7)
+    sawyer (0.8.1)
+      addressable (>= 2.3.5, < 2.6)
+      faraday (~> 0.8, < 1.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    simplecov-lcov (0.7.0)
+    slop (3.6.0)
+    sqlite3 (1.3.13)
+    thor (0.20.3)
+    thread_safe (0.3.6)
+    tzinfo (1.2.5)
+      thread_safe (~> 0.1)
+    undercover (0.3.0)
+      imagen (~> 0.1.5)
+      rainbow (~> 2.1)
+      rugged (~> 0.27.0)
+    unicode-display_width (1.4.1)
+    with_model (2.1.2)
+      activerecord (>= 4.2, < 6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord
+  ams_lazy_relationships!
+  appraisal
+  bundler (~> 1.17)
+  db-query-matchers
+  github_changelog_generator
+  pry
+  pry-nav
+  rake (~> 10.0)
+  rspec (~> 3.0)
+  rspec-rails (~> 3.5)
+  rubocop (= 0.61.0)
+  rubocop-rspec (= 1.20.1)
+  simplecov
+  simplecov-lcov
+  sqlite3 (~> 1.3)
+  undercover
+  with_model (~> 2.0)
+
+BUNDLED WITH
+   1.17.1

data/README.md

@@ -18,22 +18,22 @@ In many cases it's fine to use [`includes`](https://apidock.com/rails/ActiveReco
 There are a few problems with `includes` approach though:
 - It loads all the records provided in the arguments hash. Often you may not need all the nested records to serialize the data you want. `AmsLazyRelationships` will load only the data you need thanks to lazy evaluation.
 - When the app gets bigger and bigger you'd need to update all the `includes` statements across your app to prevent the N+1 queries problem which quickly becomes impossible.
+- It lets you remove N+1s even when not all relationships are ActiveRecord models (e.g. some records are stored in a MySQL DB and other models are stored in Cassandra)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+1. Add this line to your application's Gemfile:
 
 ```ruby
 gem "ams_lazy_relationships"
 ```
 
-And then execute:
-
-    $ bundle
-
-## Installation
+2. Execute:
+```
+$ bundle
+```
 
-Include `AmsLazyRelationships::Core` module in your base serializer
+3. Include `AmsLazyRelationships::Core` module in your base serializer
 
 ```ruby
 class BaseSerializer < ActiveModel::Serializer
@@ -41,19 +41,19 @@ class BaseSerializer < ActiveModel::Serializer
 end
 ```
 
-**Important:** 
+4. **Important:** 
 This gem uses `BatchLoader` heavily. I highly recommend to clear the batch loader's cache between HTTP requests.
 To do so add a following middleware:
-`use BatchLoader::Middleware`
+`config.middleware.use BatchLoader::Middleware` to your app's `application.rb`.
 
 For more info about the middleware check out BatchLoader gem docs: https://github.com/exAspArk/batch-loader#caching
 
-### Usage
+## Usage
 Adding the `AmsLazyRelationships::Core` module lets you define lazy relationships in your serializers:
 ```ruby
 
 class UserSerializer < BaseSerializer
-  # Short version - preloads a specified ActiveRecord relationships by default
+  # Short version - preloads a specified ActiveRecord relationship by default
   lazy_has_many :blog_posts
   
   # Works same as the previous one, but the loader option is specified explicitly
@@ -72,7 +72,7 @@ class UserSerializer < BaseSerializer
   lazy_belongs_to :account, loader: AmsLazyRelationships::Loaders::SimpleBelongsTo.new("Account")
   
   lazy_has_many :comment, loader: AmsLazyRelationships::Loaders::SimpleHasMany.new("Comment", foreign_key: :user_id)
-
+end
 ```
 
 As you may have already noticed the gem makes use of various loader classes. 
@@ -93,6 +93,76 @@ You can use it like this: `AmsLazyRelationships::Loaders::Direct.new(:poro_model
 The abovementioned loaders are mostly useful when using ActiveRecord, but there should be no problem building a new loader for different frameworks.
 If you're missing a loader you can create an issue or create your own loader taking the existing ones as an example. 
 
+### More examples
+Here are a few use cases for the lazy relationships. Hopefully they'll let you understand a bit more how the gem works.
+
+#### Example 1: Basic ActiveRecord relationships
+If the relationships in your serializers are plain old ActiveRecord relationships you're lucky, because ams_lazy_relationships by default assumes that the relationship is an ActiveRecord relationship, so you can use the simplest syntax.
+Imagine you have an endpoint that renders a list of blog posts and includes their comments.
+The N+1 prone way of defining the serializer would be:
+```ruby
+class BlogPostSerializer < BaseSerializer
+  has_many :comments
+end
+```
+
+To prevent loading comments using a separate DB query for each post just change it to:
+```ruby
+class BlogPostSerializer < BaseSerializer
+  lazy_has_many :comments
+end
+```
+
+#### Example 2: Modifying the relationship before rendering
+Sometimes it may happen that you need to process the relationship before rendering, e.g. decorate the records. In this case the gem provides a special method (in our case `lazy_comments`) for each defined relationship. Check out the example - we'll decorate every comment before serializing:
+
+```ruby
+class BlogPostSerializer < BaseSerializer
+  lazy_has_many :comments do
+    lazy_comments.map(&:decorate)
+   end
+end
+```
+
+#### Example 3: Introducing loader classes
+Under the hood ams_lazy_relationships uses special loader classes to batch load the relationships. By default the gem uses serializer class names and relationship names to instantiate correct loaders, but it may happen that e.g. your serializer's class name doesn't match the model name (e.g. your model's name is `BlogPost` but the serializer's name is `PostSerializer`).
+
+In this case you can define the lazy relationship by passing a correct loader param:
+```ruby
+class PostSerializer < BaseSerializer
+  lazy_has_many :comments, serializer: CommentSerializer,
+    loader: AmsLazyRelationships::Loaders::Association.new(
+              "BlogPost", :comments
+            )
+end
+```
+
+#### Example 4: Non ActiveRecord -> ActiveRecord relationships
+This one is interesting. It may happen that the root record is not an ActiveRecord model (e.g. a Cequel model), however its relationship is an AR model.
+Imagine that `BlogPost` is not an AR model and `Comment` is a standard AR model. The lazy relationship would look like this:
+```ruby
+class BlogPostSerializer < BaseSerializer
+  lazy_has_many :comments, 
+    loader: AmsLazyRelationships::Loaders::SimpleHasMany.new(
+      "Comment", foreign_key: :blog_post_id
+    )
+end
+```
+
+#### Example 5: Use lazy relationship without rendering it
+Sometimes you may just want to make use of lazy relationship without rendering the whole nested record. 
+For example imagine that your `BlogPost` serializer is supposed to render `author_name` attribute. You can define the lazy relationship and just use it in other attribute evaluator:
+
+```ruby
+class BlogPostSerializer < BaseSerializer
+  lazy_relationship :author
+  
+  attribute :author_name do
+    lazy_author.name
+  end
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -11,5 +11,5 @@ task default: :spec
 GitHubChangelogGenerator::RakeTask.new :changelog do |config|
   config.user = "Bajena"
   config.project = "ams_lazy_relationships"
-  config.future_release = "0.1.0"
+  config.future_release = "0.1.1"
 end

data/ams_lazy_relationships.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "active_model_serializers"
-  spec.add_dependency "batch-loader", "=1.2.2"
+  spec.add_dependency "batch-loader", "~> 1.2"
 
   spec.add_development_dependency "activerecord"
   # A Ruby library for testing against different versions of dependencies

data/lib/ams_lazy_relationships/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AmsLazyRelationships
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ams_lazy_relationships
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Jan Bajena
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-12-30 00:00:00.000000000 Z
+date: 2019-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_model_serializers
@@ -28,16 +28,16 @@ dependencies:
   name: batch-loader
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.2
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.2
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement