batch-loader 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0ced31b90f33da9d4e1fe719fe5f6f0b5a043e60
-  data.tar.gz: bc75c0b4234c6bb01db28e648853be9afbc4e7bd
+  metadata.gz: e17f7617e248aa7b911c64dac882cdb192bb9b2c
+  data.tar.gz: 6b9d612ae58f95a0715c0d23427176375d8450c4
 SHA512:
-  metadata.gz: f4548669975cacfac9958d50ddb7b8d4a4d7de1cb974dcefd7c4b1545987ccfa552d76dce04252fa26ffa5e03b6cded5d699232ece4e184a0cf870167ca3f009
-  data.tar.gz: d3867a1d1313ae11f9d97af2b6dc3076165be4f68f990bf60487eaa7c811d2fad46356d909fc894537aea1992014636c5fe7c3b1127aabdc263ccde65f839fb5
+  metadata.gz: b34fa00da8e309c99b7bae84e8155dcd847722f5da30d60c19a318a114459d825645ef3377259219e5fa9c64c1ffd1495e4ac78bf4907ab811f66b8a8b0ba178
+  data.tar.gz: 7e97b3aa40becb1515a3a26d2a1992f2ccbfda2a4f5f090fc7c329e898319aa765edec379f8a0070d555276a0ab00cb24d9cf4235b230d0e7fcb6a0e0bce6625

data/.travis.yml

@@ -2,4 +2,6 @@ sudo: false
 language: ruby
 rvm:
   - 2.3.4
+env:
+  - CI=true
 before_install: gem install bundler -v 1.15.3

data/CHANGELOG.md

@@ -8,15 +8,20 @@ one of the following labels: `Added`, `Changed`, `Deprecated`,
 to manage the versions of this gem so
 that you can set version constraints properly.
 
-#### [Unreleased](https://github.com/exAspArk/batch-loader/compare/v0.2.0...HEAD)
+#### [Unreleased](https://github.com/exAspArk/batch-loader/compare/v0.3.0...HEAD)
 
 * WIP
 
+#### [v0.3.0](https://github.com/exAspArk/batch-loader/compare/v0.2.0...v0.3.0) – 2017-08-03
+
+* `Added`: `BatchLoader::Executor.clear_current` to clear cache manually.
+* `Added`: tests and description how to use with GraphQL.
+
 #### [v0.2.0](https://github.com/exAspArk/batch-loader/compare/v0.1.0...v0.2.0) – 2017-08-02
 
-* `Added`: `cache: false` option.
-* `Added`: `BatchLoader::Middleware`.
-* `Added`: More docs and tests.
+* `Added`: `cache: false` option to disable caching for resolved values.
+* `Added`: `BatchLoader::Middleware` to clear cache between Rack requests.
+* `Added`: more docs and tests.
 
 #### [v0.1.0](https://github.com/exAspArk/batch-loader/compare/ed32edb...v0.1.0) – 2017-07-31
 

data/Gemfile

@@ -2,7 +2,7 @@ source "https://rubygems.org"
 
 git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 
-gem "pry"
+gem 'coveralls', require: false
 
 # Specify your gem's dependencies in batch-loader.gemspec
 gemspec

data/README.md

@@ -1,6 +1,10 @@
 # BatchLoader
 
 [![Build Status](https://travis-ci.org/exAspArk/batch-loader.svg?branch=master)](https://travis-ci.org/exAspArk/batch-loader)
+[![Coverage Status](https://coveralls.io/repos/github/exAspArk/batch-loader/badge.svg)](https://coveralls.io/github/exAspArk/batch-loader)
+[![Code Climate](https://img.shields.io/codeclimate/github/exAspArk/batch-loader.svg)](https://codeclimate.com/github/exAspArk/batch-loader)
+[![Downloads](https://img.shields.io/gem/dt/batch-loader.svg)](https://rubygems.org/gems/batch-loader)
+[![Latest Version](https://img.shields.io/gem/v/batch-loader.svg)](https://rubygems.org/gems/batch-loader)
 
 Simple tool to avoid N+1 DB queries, HTTP requests, etc.
 
@@ -16,7 +20,6 @@ Simple tool to avoid N+1 DB queries, HTTP requests, etc.
   * [Caching](#caching)
 * [Installation](#installation)
 * [Implementation details](#implementation-details)
-* [Testing](#testing)
 * [Development](#development)
 * [Contributing](#contributing)
 * [License](#license)
@@ -96,7 +99,7 @@ users = load_posts(post.user)  #   ↓    U    ↓
 users.map { |u| user.name }    #      Users
 ```
 
-But the problem here is that `load_posts` now depends on the child association. Plus it'll preload the association every time, even if it's not necessary. Can we do better? Sure!
+But the problem here is that `load_posts` now depends on the child association and knows that it has to preload the data for `load_users`. And it'll do it every time, even if it's not necessary. Can we do better? Sure!
 
 ### Basic example
 
@@ -130,7 +133,7 @@ As we can see, batching is isolated and described right in a place where it's ne
 
 ### How it works
 
-In general, `BatchLoader` returns an object which in other similar implementations is call Promise. Each Promise knows which data it needs to load and how to batch the query. When all the Promises are collected it's possible to resolve them once without N+1 queries.
+In general, `BatchLoader` returns a lazy object. In other programming languages it usually called Promise, but I personally prefer to call it lazy, since Ruby already uses the name in standard library :) Each lazy object knows which data it needs to load and how to batch the query. When all the lazy objects are collected it's possible to resolve them once without N+1 queries.
 
 So, when we call `BatchLoader.for` we pass an item (`user_id`) which should be batched. For the `batch` method, we pass a block which uses all the collected items (`user_ids`):
 
@@ -172,7 +175,7 @@ end
 class PostsController < ApplicationController
   def index
     posts = Post.limit(10)
-    serialized_posts = posts.map { |post| {id: post.id, rating: post.rating} }
+    serialized_posts = posts.map { |post| {id: post.id, rating: post.rating} } # N+1 HTTP requests for each post.rating
 
     render json: serialized_posts
   end
@@ -182,7 +185,6 @@ end
 As we can see, the code above will make N+1 HTTP requests, one for each post. Let's batch the requests with a gem called [parallel](https://github.com/grosser/parallel):
 
 ```ruby
-# app/models/post.rb
 class Post < ApplicationRecord
   def rating_lazy
     BatchLoader.for(post).batch do |posts, batch_loader|
@@ -190,9 +192,7 @@ class Post < ApplicationRecord
     end
   end
 
-  def rating
-    HttpClient.request(:get, "https://example.com/ratings/#{id}")
-  end
+  # ...
 end
 ```
 
@@ -201,7 +201,6 @@ end
 Now we can resolve all `BatchLoader` objects in the controller:
 
 ```ruby
-# app/controllers/posts_controller.rb
 class PostsController < ApplicationController
   def index
     posts = Post.limit(10)
@@ -211,10 +210,9 @@ class PostsController < ApplicationController
 end
 ```
 
-`BatchLoader` caches the resolved values. To ensure that the cache is purged for each request in the app add the following middleware:
+`BatchLoader` caches the resolved values. To ensure that the cache is purged between requests in the app add the following middleware to your `config/application.rb`:
 
 ```ruby
-# config/application.rb
 config.middleware.use BatchLoader::Middleware
 ```
 
@@ -222,11 +220,120 @@ See the [Caching](#caching) section for more information.
 
 ### GraphQL example
 
-TODO
+With GraphQL using batching is particularly useful. You can't use usual techniques such as preloading associations in advance to avoid N+1 queries.
+Since you don't know which fields user is going to ask in a query.
+
+Let's take a look at the simple [graphql-ruby](https://github.com/rmosolgo/graphql-ruby) schema example:
+
+```ruby
+Schema = GraphQL::Schema.define do
+  query QueryType
+end
+
+QueryType = GraphQL::ObjectType.define do
+  name "Query"
+  field :posts, !types[PostType], resolve: ->(obj, args, ctx) { Post.all }
+end
+
+PostType = GraphQL::ObjectType.define do
+  name "Post"
+  field :user, !UserType, resolve: ->(post, args, ctx) { post.user } # N+1 queries
+end
+
+UserType = GraphQL::ObjectType.define do
+  name "User"
+  field :name, !types.String
+end
+```
+
+If we want to execute a simple query like:
+
+```ruby
+query = "
+{
+  posts {
+    user {
+      name
+    }
+  }
+}
+"
+Schema.execute(query, variables: {}, context: {})
+```
+
+We will get N+1 queries for each `post.user`. To avoid this problem, all we have to do is to change the resolver to use `BatchLoader`:
+
+```ruby
+PostType = GraphQL::ObjectType.define do
+  name "Post"
+  field :user, !UserType, resolve: ->(post, args, ctx) do
+    BatchLoader.for(post.user_id).batch do |user_ids, batch_loader|
+      User.where(id: user_ids).each { |user| batch_loader.load(user.id, user) }
+    end
+  end
+end
+```
+
+And setup GraphQL with built-in `lazy_resolve` method:
+
+```ruby
+Schema = GraphQL::Schema.define do
+  query QueryType
+  lazy_resolve BatchLoader, :sync
+end
+```
 
 ### Caching
 
-TODO
+By default `BatchLoader` caches the resolved values. You can test it by running something like:
+
+```ruby
+def user_lazy(id)
+  BatchLoader.for(id).batch do |ids, batch_loader|
+    User.where(id: ids).each { |user| batch_loader.load(user.id, user) }
+  end
+end
+
+user_lazy(1)      # no request
+# => <#BatchLoader>
+
+user_lazy(1).sync # SELECT * FROM users WHERE id IN (1)
+# => <#User>
+
+user_lazy(1).sync # no request
+# => <#User>
+```
+
+To drop the cache manually you can run:
+
+```ruby
+user_lazy(1).sync # SELECT * FROM users WHERE id IN (1)
+user_lazy(1).sync # no request
+
+BatchLoader::Executor.clear_current
+
+user_lazy(1).sync # SELECT * FROM users WHERE id IN (1)
+```
+
+Usually, it's just enough to clear the cache between HTTP requests in the app. To do so, simply add the middleware:
+
+```ruby
+# calls "BatchLoader::Executor.clear_current" after each request
+use BatchLoader::Middleware
+```
+
+In some rare cases it's useful to disable caching for `BatchLoader`. For example, in tests or after data mutations:
+
+```ruby
+def user_lazy(id)
+  BatchLoader.for(id).batch(cache: false) do |ids, batch_loader|
+    # ...
+  end
+end
+
+user_lazy(1).sync # SELECT * FROM users WHERE id IN (1)
+user_lazy(1).sync # SELECT * FROM users WHERE id IN (1)
+```
 
 ## Installation
 
@@ -246,11 +353,7 @@ Or install it yourself as:
 
 ## Implementation details
 
-TODO
-
-## Testing
-
-TODO
+Coming soon
 
 ## Development
 

data/batch-loader.gemspec

@@ -26,4 +26,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.15"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "graphql", "~> 1.6"
+  spec.add_development_dependency "pry-byebug", "~> 3.4"
 end

data/lib/batch_loader.rb

@@ -6,22 +6,20 @@ class BatchLoader
   NoBatchError = Class.new(StandardError)
   BatchAlreadyExistsError = Class.new(StandardError)
 
-  class << self
-    def for(item)
-      new(item: item)
-    end
+  def self.for(item)
+    new(item: item)
+  end
 
-    def sync!(value)
-      case value
-      when Array
-        value.map! { |v| sync!(v) }
-      when Hash
-        value.each { |k, v| value[k] = sync!(v) }
-      when BatchLoader
-        sync!(value.sync)
-      else
-        value
-      end
+  def self.sync!(value)
+    case value
+    when Array
+      value.map! { |v| sync!(v) }
+    when Hash
+      value.each { |k, v| value[k] = sync!(v) }
+    when BatchLoader
+      sync!(value.sync)
+    else
+      value
     end
   end
 

data/lib/batch_loader/executor.rb

@@ -6,7 +6,11 @@ class BatchLoader
       Thread.current[NAMESPACE] ||= new
     end
 
-    def self.delete_current
+    def self.current
+      Thread.current[NAMESPACE]
+    end
+
+    def self.clear_current
       Thread.current[NAMESPACE] = nil
     end
 

data/lib/batch_loader/middleware.rb

@@ -6,10 +6,9 @@ class BatchLoader
 
     def call(env)
       begin
-        BatchLoader::Executor.ensure_current
         @app.call(env)
       ensure
-        BatchLoader::Executor.delete_current
+        BatchLoader::Executor.clear_current
       end
     end
   end

data/lib/batch_loader/version.rb

@@ -1,3 +1,3 @@
 class BatchLoader
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: batch-loader
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - exAspArk
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-08-02 00:00:00.000000000 Z
+date: 2017-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
 description: Simple tool to avoid N+1 DB queries, HTTP requests, etc.
 email:
 - exaspark@gmail.com