grumlin 0.16.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce713ebd08c676dfe38124e0286963ea18ee8d5d51f678096fd5f2ae8c28c51c
-  data.tar.gz: 6cd25c9ac701a2276fdb470b55b4ebaf123323521c6cd8d4d87365b68d604426
+  metadata.gz: 2d63d3923f895d20e89fd1647495d99bb3a97888689c8f25c34973355d7c80e1
+  data.tar.gz: 878546a65736522f3c1f00f42741b6b207e992a1983321205d05406e0a74ed6b
 SHA512:
-  metadata.gz: 81b5b522b5d183240d27cb36285f448e4918386cd267ea84fcffb2cc763d156d272844a4ffab2e00999d5c5be129930d905220506e07702ff150c49ac7388d1b
-  data.tar.gz: f4d56b0a66d91f8f454964a8d42de46fa0b6b85595c48e67e09875e01bfdb96eb131e0c6cb5ec395ebeb7dda59c45ff67c445f88e75a12a03436689d9ba14279
+  metadata.gz: 60bf726b74019b36bb0437c78b97ea1ba78703058ba2a619805e0081d49158f30bb67cc7918b959cf0375c37a5600632a1df805563edccb0266b71c9ab70f1de
+  data.tar.gz: cc7dc9ecfd45c67b28301593d3ba60e471e7a9993460ce39dcb912bbed5fb0aa01ed25bcf52f49634f704d6732ba563d849fb8d492276f19fe83e5e8531a8181

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    grumlin (0.16.1)
+    grumlin (0.17.0)
       async-pool (~> 0.3)
       async-websocket (~> 0.19)
       oj (~> 3.12)
@@ -44,7 +44,7 @@ GEM
     benchmark (0.1.1)
     childprocess (4.0.0)
     concurrent-ruby (1.1.8)
-    console (1.14.0)
+    console (1.15.0)
       fiber-local
     diff-lcs (1.4.4)
     docile (1.4.0)

data/README.md

@@ -150,7 +150,7 @@ shortcuts to make gremlin code more rubyish. Can be used as a drop in replacemen
 or `Grumlin::Shortcuts` can be inherited**, successors don't need to extend them again and have access to shortcuts 
 defined in the ancestor.
 
-**Using**:
+**Definition**
 
 ```ruby
 class MyRepository
@@ -167,15 +167,45 @@ class MyRepository
     hasAll(T.label => :triangle, color: color)
   end
 
-  # g and __ are already aware of shortcuts 
-  def red_triangles
+  # g and __ are already aware of shortcuts
+  query(:triangles_with_color, return_mode: :list) do |color| # :list is the default return mode, also possible: :none, :single, :traversal
     g.V.hasLabel(:triangle)
-       .hasColor("red")
-       .toList
+       .hasColor(color)
   end
+  # Note that when using the `query` one does not need to call a termination step like `next` or `toList`,
+  # repository does it automatically in according to the `return_mode` parameter. 
 end
 ```
 
+Each `return_mode` is mapped to a particular termination step:
+- `:list` - `toList`
+- `:single` - `next`
+- `:none` - `iterate`
+- `:traversal` - do not execute the query and return the traversal as is
+
+**Usage**
+
+To execute the query defined in a query block one simply needs to call a method with the same name:
+
+`MyRepository.new.triangles_with_color(:red)`
+
+One can also override the `return_mode`:
+
+`MyRepository.new.triangles_with_color(:red, query_params: { return_mode: :single })`
+
+or even pass a block to the method and a raw traversal will be yielded:
+```ruby
+MyRepository.new.triangles_with_color(:red) do |t|
+  t.has(:other_property, :some_value).toList
+end
+```
+it may be useful for debugging. Note that one needs to call a termination step manually in this case.
+
+`query` also provides a helper for profiling requests:
+`MyRepository.new.triangles_with_color(:red, query_params: { profile: true })`
+
+method will return profiling data of the results.
+
 #### IRB
 
 An example of how to start an IRB session with support for executing gremlin queries:

data/lib/grumlin/repository.rb

@@ -2,6 +2,13 @@
 
 module Grumlin
   module Repository
+    RETURN_MODES = {
+      list: :toList,
+      none: :iterate,
+      single: :next,
+      traversal: :nil
+    }.freeze
+
     module InstanceMethods
       def __
         TraversalStart.new(self.class.shortcuts)
@@ -19,5 +26,53 @@ module Grumlin
 
       base.shortcuts_from(Grumlin::Shortcuts::Properties)
     end
+
+    def query(name, return_mode: :list, postprocess_with: nil, &query_block) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      return_mode = validate_return_mode!(return_mode)
+      postprocess_with = validate_postprocess_with!(postprocess_with)
+
+      define_method name do |*args, query_params: {}, **params, &block|
+        t = instance_exec(*args, **params, &query_block)
+        return t if self.class.empty_result?(t)
+
+        unless t.is_a?(Grumlin::Action)
+          raise WrongQueryResult,
+                "queries must return #{Grumlin::Action}, nil or an empty collection. Given: #{t.class}"
+        end
+
+        return block.call(t) unless block.nil?
+
+        return t.profile.next if query_params[:profile] == true
+
+        return_mode = self.class.validate_return_mode!(query_params[:return_mode] || return_mode)
+
+        return t if return_mode == :traversal
+
+        t.public_send(RETURN_MODES[return_mode]).tap do |result|
+          return postprocess_with.call(result) if postprocess_with.respond_to?(:call)
+          return send(postprocess_with, result) unless postprocess_with.nil?
+        end
+      end
+    end
+
+    def validate_return_mode!(return_mode)
+      return return_mode if RETURN_MODES.key?(return_mode)
+
+      raise ArgumentError, "unsupported return mode #{return_mode}. Supported modes: #{RETURN_MODES.keys}"
+    end
+
+    def validate_postprocess_with!(postprocess_with)
+      if postprocess_with.nil? || postprocess_with.is_a?(Symbol) ||
+         postprocess_with.is_a?(String) || postprocess_with.respond_to?(:call)
+        return postprocess_with
+      end
+
+      raise ArgumentError,
+            "postprocess_with must be a String, Symbol or a callable object, given: #{postprocess_with.class}"
+    end
+
+    def empty_result?(result)
+      result.nil? || (result.respond_to?(:empty?) && result.empty?)
+    end
   end
 end

data/lib/grumlin/typing.rb

@@ -69,7 +69,7 @@ module Grumlin
       def cast_map(value)
         Hash[*value].transform_keys do |key|
           next key.to_sym if key.respond_to?(:to_sym)
-          next cast(key) if key[:@type]
+          next cast(key) if key[:@type] # TODO: g.V.group.by(:none_existing_property).next
 
           raise UnknownMapKey, key, value
         end.transform_values { |v| cast(v) }

data/lib/grumlin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Grumlin
-  VERSION = "0.16.1"
+  VERSION = "0.17.0"
 end

data/lib/grumlin.rb

@@ -100,6 +100,10 @@ module Grumlin
     end
   end
 
+  class RepositoryError < Error; end
+
+  class WrongQueryResult < RepositoryError; end
+
   class Config
     attr_accessor :url, :pool_size, :client_concurrency, :client_factory
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grumlin
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 0.17.0
 platform: ruby
 authors:
 - Gleb Sinyavskiy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-03-15 00:00:00.000000000 Z
+date: 2022-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-pool