graphql-batch 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3cf4d18124c65f414eb8fcdc54c0dab15e569041
-  data.tar.gz: fddb094273f8333c2cf25300c9a813104d382d6b
+  metadata.gz: 4daba918a3d53b660bb662a01fa76be31ab34507
+  data.tar.gz: a0bf9e1268a286ddd00c1dc60c74769fceb060ae
 SHA512:
-  metadata.gz: 2867edc13e5537b9999d2f1e0752c16524fa8a818ee5d834e2e7ef5273fcbf19db6e3a1f90a22a7874ca38ec7b312c35fd2412d6afae0dda07970bef23cff564
-  data.tar.gz: bc0e578c9315a211acd23748e765b8b1e993c34edf30e0f4dbd05acf97bc69b5a5671aa5015931491b6017f6940afbf57d2b5f29b0d1faa79f84530161a42488
+  metadata.gz: 8d532cace4412ef4a5e2aff115841b03590f9a72feb9f75086d1092849f19de4287fa6fd7e8dd4608868283499cf4cea17c414bd718d1c9bdb46c0817d75aac6
+  data.tar.gz: e6de630224733d0e5dcdcbdea70610910e463862164460e03fe8e4b9f91cca634c28ca2be867d60dd6c3355e13610dac0c5f73edb210daae501e883a0adc0e52

data/.travis.yml

@@ -1,4 +1,5 @@
 language: ruby
 rvm:
-  - 2.1.5
-before_install: gem install bundler -v 1.10.6
+  - 2.1
+  - 2.2
+before_install: gem install bundler -v 1.11.2

data/README.md

@@ -1,4 +1,4 @@
-# Graphql::Batch
+# GraphQL::Batch
 
 Provides an executor for the [`graphql` gem](https://github.com/rmosolgo/graphql-ruby) which allows queries to be batched.
 
@@ -28,54 +28,42 @@ Require the library
 require 'graphql/batch'
 ```
 
-Define a GraphQL::Batch::Query derived class. Use group_key to specify which queries can be reduced into a batch query, and an execute class method which makes that batch query and passes the result to each individual query.
+Define a custom loader, which is initialized with arguments that are used for grouping and an perform method for performing the batch load.
 
 ```ruby
-class FindQuery < GraphQL::Batch::Query
-  attr_reader :model, :id
-
-  def initialize(model, id, &block)
+class RecordLoader < GraphQL::Batch::Loader
+  def initialize(model)
     @model = model
-    @id = id
-    super(&block)
-  end
-
-  # super returns the class name
-  def group_key
-    "#{super}:#{model.name}"
   end
 
-  def self.execute(queries)
-    model = queries.first.model
-    ids = queries.map(&:id)
-    records_by_id = model.where(id: ids).index_by(&:id)
-    queries.each do |query|
-      query.complete(records_by_id[query.id])
-    end
+  def perform(ids)
+    @model.where(id: ids).each { |record| fulfill(record.id, record) }
+    ids.each { |id| fulfill(id, nil) unless fulfilled?(id) }
   end
 end
 ```
 
-When defining your schema, using the graphql gem, return a your batch query object from the resolve proc.
+Use the batch execution strategy with your schema
 
 ```ruby
-resolve -> (obj, args, context) { FindQuery.new(Product, args["id"]) }
+MySchema = GraphQL::Schema.new(query: MyQueryType)
+MySchema.query_execution_strategy = GraphQL::Batch::ExecutionStrategy
+MySchema.mutation_execution_strategy = GraphQL::Batch::ExecutionStrategy
 ```
 
-Use the batch execution strategy with your schema
+The loader class can be used from the resolve proc for a graphql field by calling `.for` with the grouping arguments to get a loader instance, then call `.load` on that instance with the key to load.
 
 ```ruby
-MySchema = GraphQL::Schema.new(query: MyQueryType)
-MySchema.query_execution_strategy = GraphQL::Batch::ExecutionStrategy
+resolve -> (obj, args, context) { RecordLoader.for(Product).load(args["id"]) }
 ```
 
-### Query Dependant Computed Fields
+### Promises
 
-If you don't want to use a query result directly, then you can pass a block which gets called after the query completes.
+GraphQL::Batch::Loader#load returns a Promise using the [promise.rb gem](https://rubygems.org/gems/promise.rb) to provide a promise based API, so you can transform the query results using `.then`
 
 ```ruby
 resolve -> (obj, args, context) do
-  FindQuery.new(Product, args["id"]) do |product|
+  RecordLoader.for(Product).load(args["id"]).then do |product|
     product.title
   end
 end
@@ -85,23 +73,59 @@ You may also need to do another query that depends on the first one to get the r
 
 ```ruby
 resolve -> (obj, args, context) do
-  FindQuery.new(Product, args["id"]) do |product|
-    FindQuery.new(Image, product.image_id)
+  RecordLoader.for(Product).load(args["id"]).then do |product|
+    RecordLoader.for(Image).load(product.image_id)
   end
 end
 ```
 
-If the second query doesn't depend on the other one, then you can use GraphQL::Batch::QueryGroup, which allows each query in the group to be batched with other queries.
+If the second query doesn't depend on the first one, then you can use Promise.all, which allows each query in the group to be batched with other queries.
 
 ```ruby
 resolve -> (obj, args, context) do
-  smart_collection_query = CountQuery.new(SmartCollection, context.shop_id)
-  custom_collection_query = CountQuery.new(CustomCollection, context.shop_id)
-
-  QueryGroup.new([smart_collection_query, custom_collection_query]) do
-    smart_collection_query.result + custom_collection_query.result
+  Promise.all([
+    CountLoader.for(Shop, :smart_collections).load(context.shop_id),
+    CountLoader.for(Shop, :custom_collections).load(context.shop_id),
+  ]).then do |results|
+    results.reduce(&:+)
   end
 end
+
+`.then` can optionally take two lambda arguments, the first of which is equivalent to passing a block to `.then`, and the second one handles exceptions.  This can be used to provide a fallback
+
+```ruby
+resolve -> (obj, args, context) do
+  CacheLoader.for(Product).load(args["id"]).then(nil, lambda do |exc|
+    raise exc unless exc.is_a?(Redis::BaseConnectionError)
+    logger.warn err.message
+    RecordLoader.for(Product).load(args["id"])
+  end)
+end
+```
+
+## Unit Testing
+
+GraphQL::Batch::Promise#sync can be used to wait for a promise to be resolved and return its result. This can be useful for debugging and unit testing loaders.
+
+```ruby
+  def test_single_query
+    product = products(:snowboard)
+    query = RecordLoader.for(Product).load(args["id"]).then(&:title)
+    assert_equal product.title, query.sync
+  end
+```
+
+Use GraphQL::Batch::Promise.all instead of Promise.all to be able to call sync on the returned promise.
+
+```
+  def test_batch_query
+    products = [products(:snowboard), products(:jacket)]
+    query1 = RecordLoader.for(Product).load(products(:snowboard).id).then(&:title)
+    query2 = RecordLoader.for(Product).load(products(:jacket).id).then(&:title)
+    results = GraphQL::Batch::Promise.all([query1, query2]).sync
+    assert_equal products(:snowboard).title, results[0]
+    assert_equal products(:jacket).title, results[1]
+  end
 ```
 
 ## Development
@@ -110,7 +134,7 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/graphql-batch.
+Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/graphql-batch.
 
 ## License
 

data/graphql-batch.gemspec

@@ -18,8 +18,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "graphql", "~>0.8"
+  spec.add_runtime_dependency "graphql", "~> 0.8"
+  spec.add_runtime_dependency "promise.rb", "~> 0.7.0.rc2"
 
+  spec.add_development_dependency "byebug" if RUBY_ENGINE == 'ruby'
   spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest"

data/lib/graphql/batch.rb

@@ -1,6 +1,14 @@
 require "graphql"
+require "promise.rb"
+
+module GraphQL
+  module Batch
+    BrokenPromiseError = Class.new(StandardError)
+  end
+end
+
 require_relative "batch/version"
-require_relative "batch/query_container"
-require_relative "batch/query"
-require_relative "batch/query_group"
+require_relative "batch/loader"
+require_relative "batch/executor"
+require_relative "batch/promise"
 require_relative "batch/execution_strategy"

data/lib/graphql/batch/execution_strategy.rb

@@ -1,57 +1,61 @@
 module GraphQL::Batch
   class ExecutionStrategy < GraphQL::Query::SerialExecution
-    attr_reader :batched_queries
+    def execute(_, _, _)
+      as_promise(super).sync
+    ensure
+      GraphQL::Batch::Executor.current.clear
+    end
+
+    private
 
-    def initialize
-      @batched_queries = Hash.new{ |hash, key| hash[key] = [] }
+    def as_promise(result)
+      GraphQL::Batch::Promise.resolve(as_promise_unless_resolved(result))
     end
 
-    class OperationResolution < GraphQL::Query::SerialExecution::OperationResolution
-      def result
-        result = super
-        until execution_strategy.batched_queries.empty?
-          queries = execution_strategy.batched_queries.shift.last
-          queries.first.class.execute(queries)
+    def as_promise_unless_resolved(result)
+      all_promises = []
+      each_promise(result) do |obj, key, promise|
+        obj[key] = nil
+        all_promises << promise.then do |value|
+          obj[key] = value
+          as_promise_unless_resolved(value)
         end
-        result
       end
+      return result if all_promises.empty?
+      Promise.all(all_promises).then { result }
     end
 
-    class SelectionResolution < GraphQL::Query::SerialExecution::SelectionResolution
-      def result
-        result_hash = super
-        result_hash.each do |key, value|
-          if value.is_a?(FieldResolution)
-            value.result_hash = result_hash
-          end
+    def each_promise(obj, &block)
+      case obj
+      when Array
+        obj.each_with_index do |value, idx|
+          each_promise_in_entry(obj, idx, value, &block)
+        end
+      when Hash
+        obj.each do |key, value|
+          each_promise_in_entry(obj, key, value, &block)
         end
-        result_hash
       end
     end
 
-    class FieldResolution < GraphQL::Query::SerialExecution::FieldResolution
-      attr_accessor :result_hash
+    def each_promise_in_entry(obj, key, value, &block)
+      if value.is_a?(::Promise)
+        yield obj, key, value
+      else
+        each_promise(value, &block)
+      end
+    end
 
+    class FieldResolution < GraphQL::Query::SerialExecution::FieldResolution
       def get_finished_value(raw_value)
-        if raw_value.is_a?(QueryContainer)
-          raw_value.query_listener = self
-          register_queries(raw_value)
-          self
+        if raw_value.is_a?(::Promise)
+          raw_value.then(->(result) { super(result) }, lambda do |error|
+            error.is_a?(GraphQL::ExecutionError) ? super(error) : raise(error)
+          end)
         else
           super
         end
       end
-
-      def register_queries(query_container)
-        query_container.each_query do |query|
-          execution_strategy.batched_queries[query.group_key] << query
-        end
-      end
-
-      def query_completed(query)
-        result_key = ast_node.alias || ast_node.name
-        @result_hash[result_key] = get_finished_value(query.result)
-      end
     end
   end
 end

data/lib/graphql/batch/executor.rb

@@ -0,0 +1,35 @@
+module GraphQL::Batch
+  class Executor
+    THREAD_KEY = :"#{name}.batched_queries"
+    private_constant :THREAD_KEY
+
+    def self.current
+      Thread.current[THREAD_KEY] ||= new
+    end
+
+    attr_reader :loaders
+
+    def initialize
+      @loaders = {}
+    end
+
+    def shift
+      @loaders.shift.last
+    end
+
+    def tick
+      shift.resolve
+    end
+
+    def wait(promise)
+      tick while promise.pending? && !loaders.empty?
+      if promise.pending?
+        promise.reject(BrokenPromiseError.new("Promise wasn't fulfilled after all queries were loaded"))
+      end
+    end
+
+    def clear
+      loaders.clear
+    end
+  end
+end

data/lib/graphql/batch/loader.rb

@@ -0,0 +1,51 @@
+module GraphQL::Batch
+  class Loader
+    def self.for(*group_args)
+      Executor.current.loaders[group_args] ||= new(*group_args)
+    end
+
+    def promises_by_key
+      @promises_by_key ||= {}
+    end
+
+    def keys
+      promises_by_key.keys
+    end
+
+    def load(key)
+      promises_by_key[key] ||= Promise.new
+    end
+
+    def fulfill(key, value)
+      promises_by_key[key].fulfill(value)
+    end
+
+    def fulfilled?(key)
+      promises_by_key[key].fulfilled?
+    end
+
+    # batch load keys and fulfill promises
+    def perform(keys)
+      raise NotImplementedError
+    end
+
+    def resolve
+      perform(keys)
+      check_for_broken_promises
+    rescue => err
+      promises_by_key.each do |key, promise|
+        promise.reject(err)
+      end
+    end
+
+    private
+
+    def check_for_broken_promises
+      promises_by_key.each do |key, promise|
+        if promise.pending?
+          promise.reject(BrokenPromiseError.new("#{self.class} didn't fulfill promise for key #{key.inspect}"))
+        end
+      end
+    end
+  end
+end

data/lib/graphql/batch/promise.rb

@@ -0,0 +1,7 @@
+module GraphQL::Batch
+  class Promise < ::Promise
+    def wait
+      Executor.current.wait(self)
+    end
+  end
+end

data/lib/graphql/batch/version.rb

@@ -1,5 +1,5 @@
 module Graphql
   module Batch
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-batch
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dylan Thacker-Smith
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-09-21 00:00:00.000000000 Z
+date: 2016-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -24,6 +24,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: promise.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0.rc2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0.rc2
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -84,9 +112,9 @@ files:
 - graphql-batch.gemspec
 - lib/graphql/batch.rb
 - lib/graphql/batch/execution_strategy.rb
-- lib/graphql/batch/query.rb
-- lib/graphql/batch/query_container.rb
-- lib/graphql/batch/query_group.rb
+- lib/graphql/batch/executor.rb
+- lib/graphql/batch/loader.rb
+- lib/graphql/batch/promise.rb
 - lib/graphql/batch/version.rb
 homepage: https://github.com/Shopify/graphql-batch
 licenses:
@@ -108,7 +136,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.2.3
 signing_key: 
 specification_version: 4
 summary: A query batching executor for the graphql gem

data/lib/graphql/batch/query.rb

@@ -1,29 +0,0 @@
-module GraphQL::Batch
-  class Query < QueryContainer
-    def initialize(&block)
-      @block = block
-    end
-
-    # batched queries with the same key are merged together
-    def group_key
-      self.class.name
-    end
-
-    def each_query
-      yield self
-    end
-
-    def complete(result)
-      if @block
-        result = @block.call(result)
-        @block = nil
-      end
-      super(result)
-    end
-
-    # execute queries, with the same group_key, as a batch
-    def self.execute(queries)
-      raise NotImplementedError
-    end
-  end
-end

data/lib/graphql/batch/query_container.rb

@@ -1,30 +0,0 @@
-module GraphQL::Batch
-  class QueryContainer
-    attr_accessor :query_listener, :result
-
-    def each_query
-      raise NotImplementedError
-    end
-
-    def complete(result)
-      if result.is_a?(QueryContainer)
-        result.query_listener = self
-        register_queries(result)
-      else
-        if instance_variable_defined?(:@result)
-          raise "Query was already completed"
-        end
-        @result = result
-        query_listener.query_completed(self)
-      end
-    end
-
-    def query_completed(query)
-      complete(query.result)
-    end
-
-    def register_queries(query_container)
-      query_listener.register_queries(query_container)
-    end
-  end
-end

data/lib/graphql/batch/query_group.rb

@@ -1,35 +0,0 @@
-module GraphQL::Batch
-  class QueryGroup < QueryContainer
-    def initialize(queries, &block)
-      @pending_queries = queries.dup
-      @pending_queries.each do |query|
-        query.query_listener = self
-      end
-      @block = block
-      raise ArgumentError, "QueryGroup requires a block" unless block
-    end
-
-    def each_query
-      @pending_queries.each do |query_container|
-        query_container.each_query do |query|
-          yield query
-        end
-      end
-    end
-
-    def query_completed(query)
-      @pending_queries.delete(query)
-      if @pending_queries.empty?
-        result = @block.call
-        @block = nil
-        if result.is_a?(QueryContainer)
-          result.query_listener = self
-          @pending_queries << result
-          register_queries(result)
-        else
-          complete(result)
-        end
-      end
-    end
-  end
-end