fauna 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9179efc5b2e53c99b6d398de61902fd963fefea7
-  data.tar.gz: cfbee10e91d3cdfe4baabc212b34cfd1ae348ea9
+  metadata.gz: c9cd9dd6bfc9acdf8f25a0bfe186e4afcff76647
+  data.tar.gz: 5072c863a7172f7925aa15ad68f1af39e6004fee
 SHA512:
-  metadata.gz: c143182304816bde8ed2b057cfd9e0c0a267e382e810c7c651139d7efcfe2aedee343fdae75c76816a4dfe90a775d6cdf921f295cc94f7c7241038fa06ed2587
-  data.tar.gz: 534a5305cacdc340f870f975435c8a69cd0aa3647ddfbf4324226d3171f3ab0f16f1280e96e4551fc1cde9b6ee01691933a016f122be7ec25ecc658c802ae150
+  metadata.gz: 479a37575bccd657be309c20cfbdf15be951ad86a4694368280b74027c8fa70d02b069af82f20742e973fb658cc4d31a82701c2d350b3950f8ab104c21ba6136
+  data.tar.gz: beb72b4e1fde21d0e50f08157252484406c666e47fb1763f20186a09ec8c4e8b93a5515282e069c99b7c61613f067fa0c2e0ae81f4c2f147368489cd537a09de

data/CHANGELOG

@@ -1,36 +1,7 @@
-v2.0.0 Complete rewrite for API 2.0. Not backwards compatible with the old client or api.
+2.1.0
+* Added paginate helper.
+* Improved exception messages (now include FaunaDB errors).
+* Added `ref` and `next_id` query functions.
 
-v1.3.4 Index support.
-
-v1.3.3 Fix #61.
-
-v1.3.2 Fix patch.
-
-v1.3.1 Switch to Faraday http client.
-
-v1.3.0 Add support for PATCH, minor error handling improvements.
-
-v1.2.0 Switch to Typhoeus HTTP client.
-
-v1.1.1 Remove last bit of ORM-ness.
-
-v1.1.0 Updates for Fauna 1.1. Remove schema configuration.
-
-v0.2.6 Implement set paging.
-
-v0.2.5 Anonymous class configuration.
-
-v0.2.4 Event set query API.
-
-v0.2.3 Event set API enhancements.
-
-v0.2.2 Support for Fauna API version 1.
-
-v0.1.2 Fauna::User.find_by_external_id returns a User or nil, not an Array.
-
-v0.1.1 Fix ActionDispatch::Reloader bug.
-
-v0.1.1 Refactor resource hierarchy. Add cache. Flesh out ActiveModel
-	support.
-
-v0.0.0 First release.
+2.0.0
+* Complete rewrite for API 2.0. Not backwards compatible with the old client or api.

data/README.md

@@ -1,10 +1,10 @@
 # FaunaDB
 
-Ruby client for [FaunaDB](https://faunadb.com).
+Ruby driver for [FaunaDB](https://faunadb.com).
 
 ## Installation
 
-The FaunaDB ruby client is distributed as a gem. Install it via:
+The FaunaDB ruby driver is distributed as a gem. Install it via:
 
     $ gem install fauna
 

data/fauna.gemspec

@@ -6,8 +6,8 @@ Gem::Specification.new do |s|
   s.version = Fauna::VERSION
   s.author = 'Fauna, Inc.'
   s.email = 'priority@faunadb.com'
-  s.summary = 'FaunaDB Ruby client'
-  s.description = 'Ruby client for the Fauna distributed database.'
+  s.summary = 'FaunaDB Ruby driver'
+  s.description = 'Ruby driver for FaunaDB.'
   s.homepage = 'https://github.com/faunadb/faunadb-ruby'
   s.license = 'MPL-2.0'
 
@@ -20,6 +20,6 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'faraday', '~> 0.9.0'
   s.add_runtime_dependency 'json', '~> 1.8'
   s.add_development_dependency 'rspec', '~> 3.4'
-  s.add_development_dependency 'rubocop', '~> 0.35.0'
-  s.add_development_dependency 'coveralls', '~> 0.8.10'
+  s.add_development_dependency 'rubocop', '~> 0.38.0'
+  s.add_development_dependency 'coveralls', '~> 0.8.13'
 end

data/lib/fauna.rb

@@ -19,4 +19,5 @@ require 'fauna/client_logger'
 require 'fauna/context'
 require 'fauna/objects'
 require 'fauna/query'
+require 'fauna/page'
 require 'fauna/request_result'

data/lib/fauna/client.rb

@@ -90,6 +90,17 @@ module Fauna
       end
     end
 
+    ##
+    # Creates a Fauna::Page for paging/iterating over a set.
+    #
+    # +set+:: A set query to paginate over.
+    # +params+:: A list of parameters to pass to {paginate}[https://faunadb.com/documentation/queries#read_functions-paginate_set].
+    # +fauna_map+:: Optional block to wrap the generated paginate query with. The block will be run in a query context.
+    #               The paginate query will be passed into the block as an argument.
+    def paginate(set, params = {}, &fauna_map)
+      Fauna::Page.new(self, set, params, &fauna_map)
+    end
+
     ##
     # Performs a +GET+ request for a REST endpoint.
     #
@@ -235,15 +246,15 @@ module Fauna
       @app.call(env).on_complete do |response_env|
         raw_body = response_env[:body]
         response_env[:body] =
-            case response_env[:response_headers]['Content-Encoding']
-            when 'gzip'
-              io = StringIO.new raw_body
-              Zlib::GzipReader.new(io, external_encoding: Encoding::UTF_8).read
-            when 'deflate'
-              Zlib::Inflate.inflate raw_body
-            else
-              raw_body
-            end
+          case response_env[:response_headers]['Content-Encoding']
+          when 'gzip'
+            io = StringIO.new raw_body
+            Zlib::GzipReader.new(io, external_encoding: Encoding::UTF_8).read
+          when 'deflate'
+            Zlib::Inflate.inflate raw_body
+          else
+            raw_body
+          end
       end
     end
   end

data/lib/fauna/context.rb

@@ -118,6 +118,17 @@ module Fauna
       client.query(expression, &expr_block)
     end
 
+    ##
+    # Creates a Fauna::Page for paging/iterating over a set with the current client context.
+    #
+    # +set+:: A set query to paginate over.
+    # +params+:: A list of parameters to pass to {paginate}[https://faunadb.com/documentation/queries#read_functions-paginate_set].
+    # +fauna_map+:: Optional block to wrap the generated paginate query with. The block will be run in a query context.
+    #               The paginate query will be passed into the block as an argument.
+    def self.paginate(set, params = {}, &fauna_map)
+      client.paginate(set, params, &fauna_map)
+    end
+
     ##
     # Returns the current context's client, or if there is none, raises NoContextError.
     def self.client

data/lib/fauna/errors.rb

@@ -66,9 +66,25 @@ module Fauna
 
       if @errors.nil?
         fail UnexpectedError.new('Error data has an unexpected format.', request_result)
+      elsif @errors.empty?
+        fail UnexpectedError.new('Error data returned was blank.', request_result)
       end
 
-      super(@errors ? @errors[0].description : '(empty `errors`)')
+      message = @errors.map do |error|
+        msg = 'Error'
+        msg += " at #{error.position}" unless error.position.nil?
+        msg += ": #{error.code} - #{error.description}"
+
+        unless error.failures.nil?
+          msg += ' (' + error.failures.map do |failure|
+            "Failure at #{failure.field}: #{failure.code} - #{failure.description}"
+          end.join(' ') + ')'
+        end
+
+        msg
+      end.join(' ')
+
+      super(message)
     end
   end
 

data/lib/fauna/objects.rb

@@ -12,25 +12,23 @@ module Fauna
     #
     # :call-seq:
     #   Ref.new('databases/prydain')
-    #   Ref.new('databases', 'prydain')
-    #   Ref.new(Ref.new('databases'), 'prydain')
     #
-    # +parts+: A string, or a list of strings/refs to be joined.
-    def initialize(*parts)
-      @value = parts.join '/'
+    # +value+: A string.
+    def initialize(value)
+      @value = value
     end
 
     ##
     # Gets the class part out of the Ref.
     # This is done by removing ref.id().
-    # So <code>Fauna::Ref.new('a', 'b/c').to_class</code> will be
+    # So <code>Fauna::Ref.new('a/b/c').to_class</code> will be
     # <code>Fauna::Ref.new('a/b')</code>.
     def to_class
       parts = value.split '/'
       if parts.length == 1
         self
       else
-        Fauna::Ref.new(*parts[0...-1])
+        Fauna::Ref.new(parts[0...-1].join('/'))
       end
     end
 

data/lib/fauna/page.rb

@@ -0,0 +1,374 @@
+module Fauna
+  ##
+  # Helper for handling pagination over sets.
+  #
+  # Given a client and a set, allows you to iterate as well as individually move page by page over a set.
+  #
+  # Pages lazily load the contents of the page. Loading will occur when +data+, +before+, or +after+ are first accessed
+  # for a new page. Additionally this will occur when calling +page_before+ or +page_after+ without calling one of the
+  # data methods first (as the first page must be checked to find the next page). Pages created by builders will unload
+  # any data from the current page. Pages will always proceed in the requested direction.
+  #
+  # Explicit paging is done via the +page_after+ and +page_before+ methods. Iteration can be done via the +each+ and
+  # +reverse_each+ enumerators. A single page can be retrieved by passing a cursor and then accessing it's data.
+  #
+  # Examples:
+  #
+  # Paging over a class index
+  #
+  #   page = Page.new(client, Query.match(Ref('indexes/items')))
+  #
+  # Paging over a class index 5 at a time, mapping the refs to the +data.value+ for each instance
+  #
+  #   page = Page.new(client, Query.match(Ref('indexes/items')), size: 5) do |ref|
+  #     select ['data', 'value'], get(ref)
+  #   end
+  #
+  #   # Same thing, but using builders instead
+  #
+  #   page = Page.new(client, Query.match(Ref('indexes/items'))).with_params(size: 5).map do |ref|
+  #     select ['data', 'value'], get(ref)
+  #   end
+  #
+  # Paging over a class index, mapping refs to the +data.value+ for each instance, filtering out odd numbers, and
+  # multiplying the value:
+  #
+  #   page = Page.new(client, Query.match(Ref('indexes/items'))).map do |ref|
+  #     select ['data', 'value'], get(ref)
+  #   end.filter do |value|
+  #     equals modulo(value, 2), 0
+  #   end.map do |value|
+  #     multiply value, 2
+  #   end
+  class Page
+    ##
+    # Creates a pagination helper for paging/iterating over a set.
+    #
+    # +client+:: Client to execute queries with.
+    # +set+:: A set query to paginate over.
+    # +params+:: A list of parameters to pass to {paginate}[https://faunadb.com/documentation/queries#read_functions-paginate_set].
+    # +lambda+:: Optional lambda to map the generated paginate query with. The block will be run in a query context.
+    #            An element from the current page will be passed into the block as an argument. See #map for more info.
+    def initialize(client, set, params = {}, &lambda)
+      @client = client
+      @set = set
+      @params = params.dup
+      @fauna_funcs = []
+      @postprocessing_map = nil
+
+      @fauna_funcs << proc { |query| map(query, &lambda) } unless lambda.nil?
+
+      unload_page
+      @params.freeze
+    end
+
+    # Returns +true+ if +other+ is a Page and contains the same configuration and data.
+    def ==(other)
+      return false unless other.is_a? Page
+      @populated == other.instance_variable_get(:@populated) &&
+        @data == other.instance_variable_get(:@data) &&
+        @before == other.instance_variable_get(:@before) &&
+        @after == other.instance_variable_get(:@after) &&
+        @client == other.instance_variable_get(:@client) &&
+        @set == other.instance_variable_get(:@set) &&
+        @params == other.instance_variable_get(:@params) &&
+        @fauna_funcs == other.instance_variable_get(:@fauna_funcs) &&
+        @postprocessing_map == other.instance_variable_get(:@postprocessing_map)
+    end
+
+    alias_method :eql?, :==
+
+    # The configured params used for the current pagination.
+    attr_reader :params
+
+    ##
+    # Explicitly loads data for the current page if it has not already been loaded.
+    #
+    # Returns +true+ if the data was just loaded and +false+ if it was already loaded.
+    def load!
+      if @populated
+        false
+      else
+        load_page(get_page(@params))
+        true
+      end
+    end
+
+    # :section: Data
+
+    ##
+    # Data contained within the current page.
+    #
+    # Lazily loads the page data if it has not already been loaded.
+    def data
+      load!
+      @data
+    end
+
+    ##
+    # Before cursor for the current page.
+    #
+    # Lazily loads the page data if it has not already been loaded.
+    def before
+      load!
+      @before
+    end
+
+    ##
+    # After cursor for the current page.
+    #
+    # Lazily loads the page data if it has not already been loaded.
+    def after
+      load!
+      @after
+    end
+
+    # :section: Builders
+
+    ##
+    # Returns a copy of the page with the given +params+ set.
+    #
+    # See {paginate}[https://faunadb.com/documentation/queries#read_functions-paginate_set] for more details.
+    def with_params(params = {})
+      with_dup do |page|
+        page_params = page.instance_variable_get(:@params)
+
+        if CURSOR_KEYS.any? { |key| params.include? key }
+          # Remove previous cursor
+          CURSOR_KEYS.each { |key| page_params.delete key }
+        end
+
+        # Update params
+        page_params.merge!(params)
+      end
+    end
+
+    ##
+    # Returns a copy of the page with a fauna +map+ using the given lambda chained onto the paginate query.
+    #
+    # The lambda will be passed into a +map+ function that wraps the generated paginate query. Additional collection
+    # functions may be combined by chaining them together.
+    #
+    # The lambda will be run in a Query.expr context, and passed an element from the current page as an argument.
+    #
+    # Example of mapping a set of refs to their instances:
+    #
+    #   page.map { |ref| get ref }
+    def map(&lambda)
+      with_dup do |page|
+        page.instance_variable_get(:@fauna_funcs) << proc { |query| map(query, &lambda) }
+      end
+    end
+
+    ##
+    # Returns a copy of the page with a fauna +filter+ using the given lambda chained onto the paginate query.
+    #
+    # The lambda will be passed into a +filter+ function that wraps the generated paginate query. Additional collection
+    # functions may be combined by chaining them together.
+    #
+    # The lambda will be run in a Query.expr context, and passed an element from the current page as an argument.
+    #
+    # Example of filtering out odd numbers from a set of numbers:
+    #
+    #   page.filter { |value| equals(modulo(value, 2), 0) }
+    def filter(&lambda)
+      with_dup do |page|
+        page.instance_variable_get(:@fauna_funcs) << proc { |query| filter(query, &lambda) }
+      end
+    end
+
+    ##
+    # Returns a copy of the page with the given ruby block set.
+    #
+    # The block will be used to map the returned data elements from the executed fauna query. Only one postprocessing
+    # map can be configured at a time.
+    #
+    # Intended for use when the elements in a page need to be converted within ruby (ie loading into a model). Wherever
+    # the operation can be performed from within FaunaDB, +map+ should be used instead.
+    #
+    # The block will be passed the each element as a parameter from the data of the page currently being loaded.
+    #
+    # Example of loading instances into your own model:
+    #
+    #   page.postprocessing_map { |instance| YourModel.load(instance) }
+    def postprocessing_map(&block)
+      with_dup do |page|
+        page.instance_variable_set(:@postprocessing_map, block)
+      end
+    end
+
+    # :section: Pagination
+
+    ##
+    # The page after the current one in the set.
+    #
+    # Returns +nil+ when there are no more pages after the current page. Lazily loads the current page if it has not
+    # already been loaded in order to determine the page after.
+    def page_after
+      new_page(:after)
+    end
+
+    ##
+    # The page before the current one in the set.
+    #
+    # Returns +nil+ when there are no more pages before the current page. Lazily loads the current page if it has not
+    # already been loaded in order to determine the page before.
+    def page_before
+      new_page(:before)
+    end
+
+    ##
+    # Returns an enumerator that iterates in the +after+ direction.
+    #
+    # When a block is provided, the return of the block will always be +nil+ (to avoid loading large sets into memory).
+    def each
+      return enum_for(:each) unless block_given?
+
+      # Return current page
+      yield data
+
+      # Begin returning pages after
+      page = self.page_after
+      until page.nil?
+        yield page.data
+        page = page.page_after
+      end
+    end
+
+    ##
+    # Returns an enumerator that iterates in the +before+ direction.
+    #
+    # When a block is provided, the return of the block will always be +nil+ (to avoid loading large sets into memory).
+    #
+    # While the paging will occur in the reverse direction, the data returned will still be in the normal direction.
+    def reverse_each
+      return enum_for(:reverse_each) unless block_given?
+
+      # Return current page
+      yield data
+
+      # Begin returning pages before
+      page = self.page_before
+      until page.nil?
+        yield page.data
+        page = page.page_before
+      end
+    end
+
+    ##
+    # Returns the flattened contents of the set as an array.
+    #
+    # Ideal for when you need the full contents of a set with a known small size. If you need to iterate over a set
+    # of large or unknown size, it is recommended to use +each+ instead.
+    #
+    # The set is paged in the +after+ direction.
+    def all
+      each.flat_map { |x| x }
+    end
+
+    ##
+    # Iterates over the entire set, applying the configured lambda in a foreach block, and discarding the result.
+    #
+    # Ideal for performing a +foreach+ over an entire set (like deleting all instances in a set). The set is iterated in
+    # the +after+ direction. The +foreach+ will be chained on top of any previously configured collection functions.
+    #
+    # Example of deleting every instance in a set:
+    #
+    #   page.foreach! { |ref| delete ref }
+    def foreach!(&lambda)
+      # Create new page with foreach block
+      iter_page = with_dup do |page|
+        page.instance_variable_get(:@fauna_funcs) << proc { |query| foreach(query, &lambda) }
+      end
+
+      # Apply to all pages in the set
+      until iter_page.nil?
+        iter_page.load!
+        iter_page = iter_page.page_after
+      end
+      nil
+    end
+
+    def dup # :nodoc:
+      page = super
+      page.instance_variable_set(:@params, @params.dup)
+      page.instance_variable_set(:@fauna_funcs, @fauna_funcs.dup)
+      page
+    end
+
+  private
+
+    CURSOR_KEYS = [:before, :after].freeze # :nodoc:
+
+    def with_dup
+      # Create a copy and drop loaded data
+      page = self.dup
+      page.send(:unload_page)
+
+      # Yield page for manipulation
+      yield page
+
+      # Freeze params and return page
+      page.params.freeze
+      page
+    end
+
+    def get_page(params)
+      # Create query
+      query = Query.paginate @set, params
+
+      unless @fauna_funcs.empty?
+        # Wrap paginate query with the fauna maps
+        dsl = Query::QueryDSLContext.new
+        @fauna_funcs.each do |proc|
+          query = DSLContext.eval_dsl(dsl, query, &proc)
+        end
+        query = Query::Expr.wrap query
+      end
+
+      # Execute query
+      result = @client.query query
+
+      unless @postprocessing_map.nil?
+        # Map the resulting data with the ruby block
+        result[:data].map! { |element| @postprocessing_map.call(element) }
+      end
+
+      # Return result
+      result
+    end
+
+    def load_page(page)
+      # Not initial after the first page
+      @populated = true
+
+      # Update the page fields
+      @data = page[:data]
+      @before = page[:before]
+      @after = page[:after]
+    end
+
+    def unload_page
+      # Reset paging
+      @populated = false
+
+      # Reset data
+      @data = nil
+      @before = nil
+      @after = nil
+    end
+
+    def new_page(direction)
+      fail "Invalid direction; must be one of #{CURSOR_KEYS}" unless CURSOR_KEYS.include?(direction)
+
+      cursor = self.send(direction)
+
+      # If there is no next cursor, we have reached the end of the set.
+      # Return +nil+.
+      return nil if cursor.nil?
+
+      # Use the configured cursor to fetch the first page.
+      with_params(direction => cursor)
+    end
+  end
+end