dataloader 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f032c75315465da12e47780bd7cd70ef20cf42d7
-  data.tar.gz: e065585b95c677ad39a5f84a069a6afc0412ee7e
+  metadata.gz: 1245888f26c565a88d6e2868c45218014e883ece
+  data.tar.gz: 25fc613bfa5ae2af41c6a9b31d44c77428e5d214
 SHA512:
-  metadata.gz: 2278ac3002ff9122bf74a3c0df593e8741b0042be119bc7d8249cdcc6906cbfe811c0101f97d330485a572c176913f3046d87336c13fb0b7e6e127c85abe8819
-  data.tar.gz: 5f8c7e2fecfc3fd1d9365d9d220a9d4ad45764e8bc259db06eac42f231ace5cdbe2708a26b12361132b85f5d93be174b291577c3a79f5ee2ce81c017fc3b3fce
+  metadata.gz: 68f9ea657f150d09ed9aeec7789e076a46865897d79b150f7303c8e6b2c860a4ae4e001cb05c9b76626c875942ad6f86cce81f33744e1ff0159cfa719b2cc105
+  data.tar.gz: 3dc95561576e7961454b734852619f81f87a2ba4c9e56b65ac4fc758ba5b2d49921a6a59ea1ed59cb7b03a9b6e3220318d922a89934630cdcec64814e14b068a

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2017-present, Adam Stankiewicz
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,259 @@
+# ![](http://i.imgur.com/ZdJKtj1.png) Dataloader
+
+[![Build Status](https://travis-ci.org/sheerun/dataloader.svg?branch=master)](https://travis-ci.org/sheerun/dataloader) [![codecov](https://codecov.io/gh/sheerun/dataloader/branch/master/graph/badge.svg)](https://codecov.io/gh/sheerun/dataloader)
+
+
+Dataloader is a generic utility to be used as part of your application's data fetching layer to provide a simplified and consistent API to perform batching and caching within a request. It is heavily inspired by [Facebook's dataloader](https://github.com/facebook/dataloader).
+
+## Getting started
+
+First, install Dataloader using bundler:
+
+```ruby
+gem "dataloader"
+```
+
+To get started, create a `Dataloader`. Each `Dataloader` instance represents a unique cache. Typically instances are created per request when used within a web-server. To see how to use with GraphQL server, see section below.
+
+
+## Basic usage
+
+```ruby
+# It will be called only once with ids = [1, 2, 3]
+loader = Dataloader.new do |ids|
+  User.find(*ids)
+end
+
+# Schedule data to load
+promise_one = loader.load(0)
+promise_two = loader.load_many([1, 2])
+
+# Get promises results
+user0 = promise_one.sync
+user1, user2 = promise_two.sync
+```
+
+## Using with GraphQL
+
+You can pass loaders passed inside [`context`](https://rmosolgo.github.io/graphql-ruby/queries/executing_queries).
+
+```ruby
+UserType = GraphQL::ObjectType.define do
+  field :name, types.String
+end
+
+QueryType = GraphQL::ObjectType.define do
+  name "Query"
+  description "The query root of this schema"
+
+  field :user do
+    type UserType
+    argument :id, !types.ID
+    resolve ->(obj, args, ctx) {
+      ctx[:user_loader].load(args["id"])
+    }
+  end
+end
+
+Schema = GraphQL::Schema.define do
+  lazy_resolve(Promise, :sync)
+
+  query QueryType
+end
+
+context = {
+  user_loader: Dataloader.new do |ids|
+    User.find(*ids)
+  end
+}
+
+Schema.execute("{ user(id: 12) { name } }", context: context)
+```
+
+## Batching
+
+You can create loaders by providing a batch loading function.
+
+```ruby
+user_loader = Dataloader.new { |ids| User.find(*ids) }
+```
+
+A batch loading block accepts an Array of keys, and returns a Promise which resolves to an Array or Hash of values.
+
+Dataloader will coalesce all individual loads which occur until first `.sync` is called on any promise returned by `#load` or `#load_many`, and then call your batch function with all requested keys.
+
+```ruby
+user_loader.load(1)
+  .then { |user| user_loader.load(user.invited_by_id)) }
+  .then { |invited_by| "User 1 was invited by ${invited_by[:name]}" }
+
+# Elsewhere in your backend
+user_loader.load(2)
+  .then { |user| user_loader.load(user.invited_by_id)) }
+  .then { |invited_by| "User 2 was invited by ${invited_by[:name]}" }
+```
+
+A naive solution is to isisue four SQL queries to get required information, but with `Dataloader` this application will make at most two queries (one to load users, and second one to load invites).
+
+`Dataloader` allows you to decouple unrelated parts of your application without sacrificing the performance of batch data-loading. While the loader presents an API that loads individual values, all concurrent requests will be coalesced and presented to your batch loading function. This allows your application to safely distribute data fetching requirements throughout your application and maintain minimal outgoing data requests.
+
+### Batch function
+
+A batch loading function accepts an Array of keys, and returns Array of values or Hash that maps from keys to values      (or a [Promise](https://github.com/lgierth/promise.rb) that returns such Array or Hash). There are a few constraints that must be upheld:
+
+* The Array of values must be the same length as the Array of keys.
+* Each index in the Array of values must correspond to the same index in the Array of keys.
+* If Hash is returned, it must include all keys passed to batch loading function
+
+For example, if your batch function was provided the Array of keys: `[ 2, 9, 6 ]`, you could return one of following:
+
+```ruby
+[
+  { id: 2, name: "foo" },
+  { id: 9, name: "bar" },
+  { id: 6, name: "baz" }
+]
+```
+
+```ruby
+{
+  2 => { id: 2, name: "foo" },
+  9 => { id: 9, name: "bar" },
+  6 => { id: 6, name: "baz" }
+}
+```
+
+## Caching
+
+Dataloader provides a memoization cache for all loads which occur withing single instance of it. After `#load` is called once with a given key, the resulting Promise is cached to eliminate redundant loads.
+
+In addition to reliving pressure on your data storage, caching results per-request also creates fewer objects which may relieve memory pressure on your application:
+
+```
+promise1 = user_loader.load(1)
+promise2 = user_loader.load(1)
+promise1 == promise2 # => true
+```
+
+### Caching per-request
+
+`Dataloader` caching does not replace Redis, Memcache, or any other shared application-level cache. DataLoader is first and foremost a data loading mechanism, and its cache only serves the purpose of not repeatedly loading the same data in the context of a single request to your Application. To do this, it maintains a simple in-memory memoization cache (more accurately: `#load` is a memoized function).
+
+Avoid multiple requests from different users using the same `Dataloader` instance, which could result in cached data incorrectly appearing in each request. Typically, `Dataloader` instances are created when a request begins, and are not used once the request ends.
+
+See "Using with GraphQL" section to see how you can pass dataloader instances using context.
+
+### Caching errors
+
+If a batch load fails (that is, a batch function throws or returns a rejected Promise), then the requested values will not be cached. However if a batch function returns an Error instance for an individual value, that Error will be cached to avoid frequently loading the same Error.
+
+In some circumstances you may wish to clear the cache for these individual Errors:
+
+```ruby
+user_loader.load(1).rescue do |error|
+  user_loader.cache.delete(1)
+  raise error
+end
+```
+
+### Disabling cache
+
+In certain uncommon cases, a Dataloader which does not cache may be desirable. Calling `Dataloader.new({ cache: nil }) { ... }` will ensure that every call to `#load` will produce a new Promise, and requested keys will not be saved in memory.
+
+However, when the memoization cache is disabled, your batch function will receive an array of keys which may contain duplicates! Each key will be associated with each call to `#load`. Your batch loader should provide a value for each instance of the requested key.
+
+```ruby
+loader = Dataloader.new({ cache: nil }) do |keys|
+  puts keys
+  some_loading_function(keys)
+end
+
+loader.load('A')
+loader.load('B')
+loader.load('A')
+
+// > [ 'A', 'B', 'A' ]
+```
+
+## API
+
+### `Dataloader`
+
+`Dataloader` is a class for fetching data given unique keys such as the id column (or any other key).
+
+Each `Dataloader` instance contains a unique memoized cache. Because of it, it is recommended to use one `Datalaoder` instane **per web request**. You can use more long-lived instances, but then you need to take care of manually cleaning the cache.
+
+You shound't share the same dataloader instance across different threads. This behavior is currently undefined.
+
+### `Dataloader.new(options = {}, &batch_load)`
+
+Create a new `Dataloader` given a batch loading function and options.
+
+* `batch_load`: A block which accepts an Array of keys, and returns Array of values or Hash that maps from keys to values (or a [Promise](https://github.com/lgierth/promise.rb) that returns such value).
+* `options`: An optional hash of options:
+  * `:key` A function to produce a cache key for a given load key. Defaults to function { |key| key }. Useful to provide when objects are keys and two similarly shaped objects should be considered equivalent.
+  * `:cache` An instance of cache used for caching of promies. Defaults to `Concurrent::Map.new`.
+    - The only required API is `#compute_if_absent(key)`).
+    - You can pass `nil` if you want to disable the cache.
+    - You can pass pre-populated cache as well. The values can be Promises.
+  * `:max_batch_size` Limits the number of items that get passed in to the batchLoadFn. Defaults to `INFINITY`. You can pass `1` to disable batching.
+
+### `#load(key)`
+
+**key** [Object] a key to load using `batch_load`
+
+Returns a [Promise](https://github.com/lgierth/promise.rb) of computed value.
+
+You can resolve this promise when you actually need the value with `promise.sync`.
+
+All calls to `#load` are batched until the first `#sync` is encountered. Then is starts batching again, et caetera.
+
+### `#load_many(keys)`
+
+**keys** [Array<Object>] list of keys to load using `batch_load`
+
+Returns a [Promise<Array>](https://github.com/lgierth/promise.rb) of array of computed values.
+
+To give an example, to multiple keys:
+
+```ruby
+promise = loader.load_many(['a', 'b'])
+object_a, object_b = promise.sync
+```
+
+This is equivalent to the more verbose:
+
+```ruby
+promise = Promise.all([loader.load('a'), loader.load('b')])
+object_a, object_b = promise.sync
+```
+
+### `#cache`
+
+Returns the internal cache that can be overridden with `:cache` option (see constructor)
+
+This field is writable, so you can reset the cache with something like:
+
+```ruby
+loader.cache = Concurrent::Map.new
+```
+
+### `#wait`
+
+Triggers all batched loaders until there are no keys to resolve.
+
+This method is invoked automatically when value of any promise is requested with `#sync`
+
+Here is the implementation that Dataloader sets as a default for [Promise](https://github.com/lgierth/promise.rb):
+
+```ruby
+class Promise
+  def wait
+    Dataloader.wait
+  end
+end
+```
+
+## License
+
+MIT

data/lib/dataloader.rb

@@ -1,5 +1,237 @@
-class DataLoader
-  def self.test
-    "test"
+require "concurrent"
+require "promise"
+
+# @!visibility private
+class Promise
+  alias_method :wait_old, :wait
+
+  def wait
+    Dataloader.wait
+    wait_old
+  end
+end
+
+class Dataloader
+  # @!visibility private
+  VERSION = "1.0.0".freeze
+
+  # @!visibility private
+  class NoCache
+    def compute_if_absent(key)
+      yield
+    end
+  end
+
+  # @!visibility private
+  class Batch
+    def initialize(dataloader)
+      # Used for storing cache of promises and batch load method
+      @dataloader = dataloader
+      # Batch can be dispatched only once (it loads all queued promises)
+      @dispatched = false
+      # This is where result of executing batch is stored
+      @result = Promise.new
+      # This is where items to batch load are stored
+      @queue = Concurrent::Array.new
+      # We store pending batches to load per-thread
+      Thread.current[:pending_batches].unshift(self)
+    end
+
+    def dispatch
+      @dispatched = true
+
+      result = @dataloader.batch_load.call(@queue)
+
+      if result.is_a?(Promise)
+        result.then do |values|
+          @result.fulfill(handle_result(@queue, values))
+        end
+      else
+        @result.fulfill(handle_result(@queue, result))
+      end
+    end
+
+    def dispatched?
+      @dispatched
+    end
+
+    def queue(key)
+      raise StandardError, "Cannot queue elements after batch is dispatched. Queued key: #{key}. This error shoudn't happen. Please raise an issue on https://github.com/sheerun/dataloader with steps to reproduce" if @dispatched
+
+      @queue.push(key)
+
+      if @queue.size >= @dataloader.max_batch_size
+        dispatch
+      end
+
+      @result.then do |values|
+        unless values.key?(key)
+          raise StandardError, "Batch loader didn't resolve a key: #{key}. Resolved keys: #{values.keys}"
+        end
+
+        values[key]
+      end
+    end
+
+    protected
+
+    def handle_result(keys, values)
+      unless values.is_a?(Array) || values.is_a?(Hash)
+        raise TypeError, "Batch loader must return an Array or Hash, but returned: #{values.class.name}"
+      end
+
+      if keys.size != values.size
+        raise StandardError, "Batch loader must be instantiated with function that returns Array or Hash " \
+          "of the same size as provided to it Array of keys" \
+          "\n\nProvided keys:\n#{keys}" \
+          "\n\nReturned values:\n#{values}"
+      end
+
+      values = Hash[keys.zip(values)] if values.is_a?(Array)
+
+      values
+    end
+  end
+
+  # Returns the internal cache that can be overridden with `:cache` option (see constructor)
+  # This field is writable, so you can reset the cache with something like:
+  #
+  #   loader.cache = Concurrent::Map.new
+  #
+  # Defaults to Concurrent::Map.new
+  attr_accessor :cache
+
+  # @!visibility private
+  attr_reader :batch_load
+
+  # @!visibility private
+  attr_reader :max_batch_size
+
+  # Creates new dataloader
+  #
+  # @option options [Proc] :key A function to produce a cache key for a given load key. Defaults to proc { |key| key }. Useful to provide when objects are keys and two similarly shaped objects should be considered equivalent.
+  # @option options [Object] :cache An instance of cache used for caching of promies (the only required api is `#compute_if_absent`). Defaults to Concurrent::Map.new. Values can be either promises or actual values. You can pass `nil` if you don't want caching.
+  # @option options [Object] :max_batch_size Limits the number of items that get passed in to the batchLoadFn. Defaults to  Float::INFINITY. You can pass 1 to disable batching.
+  # @yieldparam [Array] array is batched ids to load
+  # @yieldreturn [Promise] a promise of loaded value with batch_load block
+  def initialize(options = {}, &batch_load)
+    Thread.current[:pending_batches] ||= []
+
+    unless block_given?
+      raise TypeError, "Dataloader must be constructed with a block which accepts " \
+        "Array and returns either Array or Hash of the same size (or Promise)"
+    end
+
+    @batch_promise = Batch.new(self)
+    @batch_load = batch_load
+
+    @key = options.fetch(:key, lambda { |key| key })
+    @cache = options.fetch(:cache, Concurrent::Map.new)
+    @max_batch_size = options.fetch(:max_batch_size, Float::INFINITY)
+
+    if @cache.nil?
+      @cache = NoCache.new
+    end
+  end
+
+  # Forces all currently pending promises to be executed and resolved
+  #
+  # This method is invoked automatically when value of any promise is requested with `.sync`
+  # @example Promise.rb implementation that waits for all batched promises (default):
+  #   class Promise
+  #     def wait
+  #       Dataloader.wait
+  #     end
+  #   end
+  def self.wait
+    until Thread.current[:pending_batches].empty?
+      pending = Thread.current[:pending_batches]
+      Thread.current[:pending_batches] = []
+      pending.each(&:dispatch)
+    end
+  end
+
+  # Loads a key, returning a [Promise](https://github.com/lgierth/promise.rb) for the value represented by that key.
+  #
+  # You can resolve this promise when you actually need the value with `promise.sync`.
+  #
+  # All calls to `#load` are batched until the first `#sync` is encountered. Then is starts batching again, et caetera.
+  #
+  # @param key [Object] key to load using `batch_load` proc
+  # @return [Promise<Object>] A Promise of computed value
+  # @example Load promises of two users and resolve them:
+  #   user_loader = Dataloader.new do |ids|
+  #     User.find(*ids)
+  #   end
+  #
+  #   user1_promise = user_loader.load(1)
+  #   user2_promise = user_loader.load(2)
+  #
+  #   user1 = user1_promise.sync
+  #   user2 = user2_promise.sync
+  def load(key)
+    if key.nil?
+      raise TypeError, "#load must be called with a key, but got: nil"
+    end
+
+    result = compute_if_absent(key) do
+      batch_promise.queue(key)
+    end
+
+    unless result.is_a?(Promise)
+      return Promise.new.fulfill(result)
+    end
+
+    result
+  end
+
+  #
+  #
+  # Loads multiple keys, promising an array of values:
+  #
+  # ```ruby
+  # promise = loader.load_many(['a', 'b'])
+  # object_a, object_b = promise.sync
+  # ```
+  #
+  # This is equivalent to the more verbose:
+  #
+  # ```ruby
+  # promise = Promise.all([loader.load('a'), loader.load('b')])
+  # object_a, object_b = promise.sync
+  # ```
+  #
+  # @param keys [Array<Object>] list of keys to load using `batch_load` proc
+  # @return [Promise<Object>] A Promise of computed values
+  # @example Load promises of two users and resolve them:
+  #   user_loader = Dataloader.new do |ids|
+  #     User.find(*ids)
+  #   end
+  #
+  #   users_promise = user_loader.load_many([1, 2])
+  #
+  #   user1, user2 = users_promise.sync
+  def load_many(keys)
+    unless keys.is_a?(Array)
+      raise TypeError, "#load_many must be called with an Array, but got: #{keys.class.name}"
+    end
+
+    Promise.all(keys.map(&method(:load)))
+  end
+
+  protected
+
+  def compute_if_absent(key)
+    @cache.compute_if_absent(@key.call(key)) do
+      yield
+    end
+  end
+
+  def batch_promise
+    if @batch_promise.dispatched?
+      @batch_promise = Batch.new(self)
+    end
+
+    @batch_promise
   end
 end

metadata

@@ -1,26 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: dataloader
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
-- Samer Buna
+- Adam Stankiewicz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-06 00:00:00.000000000 Z
-dependencies: []
-description: DataLoader for Ruby
-email: samer@agilelabs.com
+date: 2017-07-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: promise.rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.3
+description: A data loading utility to batch loading of promises. It can be used with
+  graphql gem.
+email:
+- sheerun@sher.pl
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- Rakefile
+- LICENSE
+- README.md
 - lib/dataloader.rb
-- test/test_dataloader.rb
-homepage: http://rubygems.org/gems/dataloader
-licenses: []
+homepage: https://github.com/sheerun/dataloader
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -28,19 +59,18 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14.1
+rubygems_version: 2.6.11
 signing_key: 
-specification_version: 3
-summary: DataLoader
-test_files:
-- test/test_dataloader.rb
+specification_version: 4
+summary: Batch data loading, works great with graphql
+test_files: []

data/Rakefile

@@ -1,8 +0,0 @@
-require 'rake/testtask'
-
-Rake::TestTask.new do |t|
-  t.libs << 'test'
-end
-
-desc "Run tests"
-task :default => :test

data/test/test_dataloader.rb

@@ -1,8 +0,0 @@
-require 'test/unit'
-require 'dataloader'
-
-class DataLoaderTest < Test::Unit::TestCase
-  def test_test
-    assert_equal "test", DataLoader.test
-  end
-end