grumlin 0.23.0 → 1.0.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0560f7bf90bba9601628d6042ac1286076f9a8e9039b6f8e755b6f4beedb3e1a
-  data.tar.gz: 83b7b4409198a6cbb5520b003e2dcdacfe8623b9aa8c057b0e9df1e29692a4f3
+  metadata.gz: 1321ed876a7cc42db4e40d16fe7a7c7baa4cd0d955ad58901ecfd07051700e7b
+  data.tar.gz: 1b66499966537dff77767ddc5936222a7129b29004f05a60d4f578ede6c08a9f
 SHA512:
-  metadata.gz: f87b6a69c71ebd867f227b35e13a50c499d054c6688747465e05a41426167ee3ffea5afbfb1875ca5c49e6a0c2a97f42ea20b93f9cf32cd5966942ba844f839c
-  data.tar.gz: 4b5262eacf5e57f4ad95e6cc5f450d924858b1e238e2bf3943b9b127da53db36c76078b22d8ba5d244aa35e5d0ddfc4db45516481bd41c58bbe2123ac262dd5f
+  metadata.gz: d6158025426480ae13930848e370014e2fc77325d650d5540c11a516b4ed982ee5b3526049d7f8e1b669d9b2ddffe2370e4dc5e8ce4cda55755e69f3b72750d3
+  data.tar.gz: 33c02aca842d77dbe1284504b9c00195a72301bbcf23ba69cbeeffa5ca75d4d95aa71791e3d7228e863c62d1048739c70f3df90515f0339698741c1938e49484

data/.rubocop.yml

@@ -65,10 +65,6 @@ RSpec/DescribeClass:
 RSpec/MultipleMemoizedHelpers:
   Max: 7
 
-Style/WordArray:
-  Exclude:
-    - spec/**/*_spec.rb
-
 Style/StringLiterals:
   Enabled: true
   EnforcedStyle: double_quotes
@@ -83,9 +79,13 @@ Style/Documentation:
 Style/MultilineBlockChain:
   Enabled: false
 
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+Style/WordArray:
+  EnforcedStyle: brackets
+  Exclude:
+    - spec/**/*_spec.rb
 
-# TODO:
-# Style/SymbolArray:
-#   EnforcedStyle: brackets
-# Style/WordArray:
-#   EnforcedStyle: brackets
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    grumlin (0.23.0)
+    grumlin (1.0.0.rc2)
       async-pool (~> 0.3)
       async-websocket (>= 0.19, < 0.20)
       ibsciss-middleware (~> 0.4.0)

data/README.md

@@ -82,116 +82,11 @@ Current differences between providers:
 
 **Warning**: Not all steps and expressions defined in the reference documentation are supported.
 
-#### Sugar
-
-Grumlin provides an easy to use module called `Grumlin::Sugar`. Once included in your class it injects some useful
-constants and methods turning your class into an entrypoint for traversals with pure gremlin experience.
-
-```ruby
-class MyRepository
-  include Grumlin::Sugar
-  
-  def nodes(property1:, property2:)
-    g.V()
-      .has(T.label, "node")
-      .has(:property1, property1)
-      .has(:property2, property2)
-      .order.by(:property3, Order.asc).limit(10)
-      .toList
-  end
-end
-```
-
-#### Shortcuts
-
-**Shortcuts** is a way to share and organize gremlin code. They let developers define their own steps consisting of
-sequences of standard gremlin steps, other shortcuts and even add new initially unsupported by Grumlin steps.
-Remember ActiveRecord scopes? Shortcuts are very similar.
-
-**Important**: if a shortcut's name matches a name of a method defined on the wrapped object, this shortcut will be
-be ignored because methods have higher priority.
-
-Shortcuts are designed to be used with `Grumlin::Repository` but still can be used separately, with `Grumlin::Sugar`
-for example.
-
-**Defining**:
-```ruby
-
-# Defining shortcuts
-class ColorShortcut
-  extend Grumlin::Shortcuts
-
-  # Custom step
-  shortcut :hasColor do |color|
-    has(:color, color)
-  end
-end
-
-class ChooseShortcut
-  extend Grumlin::Shortcuts
-
-  # Standard Gremlin step
-  shortcut :choose do |*args|
-    step(:choose, *args)
-  end
-end
-
-class AllShortcuts
-  extend Grumlin::Shortcuts
-
-  # Adding shortcuts from other modules
-  shortcuts_from ColorShortcut
-  shortcuts_from ChooseShortcut
-end
-```
-
-**Using with Grumlin::Sugar**:
-```ruby
-class MyRepository
-  include Grumlin::Sugar
-  extend Grumlin::Shortcuts
-
-  shortcuts_from AllShortcuts
-
-  # Wrapping a traversal
-  def red_triangles
-    g(self.class.shortcuts).V.hasLabel(:triangle)
-       .hasColor("red")
-       .toList
-  end
-
-  # Wrapping _
-  def something_else
-    g(self.class.shortcuts).V.hasColor("red")
-       .repeat(__(self.class.shortcuts))
-       .out(:has)
-       .hasColor("blue")
-       .toList
-  end
-end
-```
-
-##### Overriding standard steps and shortcuts
-
-Sometimes it may be useful to override standard steps. Grumlin does not allow it by default, but one
-is still able to override standard steps if they know what they are doing:
-
-```ruby
-shortcut :addV, override: true do |label|
-  super(label).property(:default, :value)
-end
-```
-
-This will create a new shortcut that overrides the standard step `addV` and adds default properties to all vertices
-created by the repository that uses this shortcut.
-
-Shortcuts also can be overridden, but super() is not available.
-
 #### Grumlin::Repository
-`Grumlin::Repository` combines functionality of `Grumlin::Sugar` and `Grumlin::Shortcuts` as well as adds a few useful
-shortcuts to make gremlin code more rubyish. Can be used as a drop in replacement for `Grumlin::Sugar`. Remember that
-`Grumlin::Sugar` needs to be included, but `Grumlin::Repository` - extended. **Classes extending `Grumlin::Repository`
-or `Grumlin::Shortcuts` can be inherited**, successors don't need to extend them again and have access to shortcuts 
+`Grumlin::Repository` - is a starting point for all traversals. It provides easy access to `g`, `__` and usual gremlin
+expressions for you class. It has support for defining your own shortcuts and is even shipped with a couple of useful
+shortcuts to make gremlin code more rubyish. **Classes extending `Grumlin::Repository`
+or `Grumlin::Shortcuts` can be inherited**, successors don't need to extend them again and have access to shortcuts
 defined in the ancestor.
 
 **Definition**
@@ -199,8 +94,8 @@ defined in the ancestor.
 ```ruby
 class MyRepository
   extend Grumlin::Repository
-
-  # Repository supports all Grumlin::Shortcut and Grumlin::Sugar features.
+  # read_only! - forbids mutating queries for this repository. May be useful for separation reads and writes
+  
   # It can add shortcuts from another repository or a shortcuts module
   shortcuts_from ChooseShortcut
   
@@ -252,13 +147,18 @@ Each `return_mode` is mapped to a particular termination step:
 - `drop_in_batches(traversal, batch_size: 10_000)`
 
 and a few methods that emulate upserts:
-- `upsert_vertex(label, id, create_properties: {}, update_properties: {}, on_failure: :retry, start: g, **params)` 
+- `upsert_vertex(label, id, create_properties: {}, update_properties: {}, on_failure: :retry, start: g, **params)`
+- `upsert_vertices(edges, batch_size: 100, on_failure: :retry, start: g, **params)`
 - `upsert_edge(label, from:, to:, create_properties: {}, update_properties: {}, on_failure: :retry, start: g, **params)`
 - `upsert_edges(edges, batch_size: 100, on_failure: :retry, start: g, **params)`
-- `upsert_vertices(edges, batch_size: 100, on_failure: :retry, start: g, **params)`
+
+**Note**: all upsert methods expect your provider has support for user supplied string ids for nodes and edges 
+respectively. For edges and if `create_properties[T.id]` if nil, grumlin will generate a uuid-like id out of `from` and
+`to` vertex ids and edge's label to ensure uniqueness of the edge. If you manually provide an id, it's your 
+responsibility to ensure it's uniquely identifies the edge using it's `from`, `to` and `label`.
 
 All of them support 3 different modes for error handling: `:retry`, `:ignore` and `:raise`. Retry mode is implemented
-with [retryable](https://github.com/nfedyashev/retryable). **params will be merged to the default config for upserts 
+with [retryable](https://github.com/nfedyashev/retryable). **params will be merged to the default config for upserts
 and passed to `Retryable.retryable`. In case if you want to modify retryable behaviour you are to do so.
 
 If you want to use these methods inside a transaction simply pass your `gtx` as `start` parameter:
@@ -270,7 +170,7 @@ end
 
 If you don't want to define you own repository, simply use
 
-`Grumlin::Repository.new` returns an instance of an anonymous class extending `Grumlin::Repository`. 
+`Grumlin::Repository.new` returns an instance of an anonymous class extending `Grumlin::Repository`.
 
 **Usage**
 
@@ -295,6 +195,62 @@ it may be useful for debugging. Note that one needs to call a termination step m
 
 method will return profiling data of the results.
 
+#### Shortcuts
+
+**Shortcuts** is a way to share and organize gremlin code. They let developers define their own steps consisting of
+sequences of standard gremlin steps, other shortcuts and even add new initially unsupported by Grumlin steps.
+Remember ActiveRecord scopes? Shortcuts are very similar.
+
+**Important**: if a shortcut's name matches a name of a method defined on the wrapped object, this shortcut will be
+be ignored because methods have higher priority.
+
+**Defining**:
+```ruby
+
+# Defining shortcuts
+class ColorShortcut
+  extend Grumlin::Shortcuts
+
+  # Custom step
+  shortcut :hasColor do |color|
+    has(:color, color)
+  end
+end
+
+class ChooseShortcut
+  extend Grumlin::Shortcuts
+
+  # Standard Gremlin step
+  shortcut :choose do |*args|
+    step(:choose, *args)
+  end
+end
+
+class AllShortcuts
+  extend Grumlin::Shortcuts
+
+  # Adding shortcuts from other modules
+  shortcuts_from ColorShortcut
+  shortcuts_from ChooseShortcut
+end
+```
+
+##### Overriding standard steps and shortcuts
+
+Sometimes it may be useful to override standard steps. Grumlin does not allow it by default, but one
+is still able to override standard steps if they know what they are doing:
+
+```ruby
+shortcut :addV, override: true do |label|
+  super(label).property(:default, :value)
+end
+```
+
+This will create a new shortcut that overrides the standard step `addV` and adds default properties to all vertices
+created by the repository that uses this shortcut.
+
+Shortcuts also can be overridden, but super() is not available.
+
 ##### Middlewares
 
 Middlewares can be used to perform certain actions before and after every query made by `Grumlin`. It can be useful for
@@ -323,41 +279,43 @@ end # commits automatically
 
 #### IRB
 
-An example of how to start an IRB session with support for executing gremlin queries:
-
-```ruby
-Async do
-  include Grumlin::Sugar
-
-  IRB.start
-ensure
-  Grumlin.close
-end
-```
-
-Please check out [bin/console](bin/console) for full source. A similar trick may be applied to PRY.
+Please check out [bin/console](bin/console) for inspiration. A similar trick may be applied to PRY.
 
 #### Rails console
 
 In order to make it possible to execute gremlin queries from the rails console you need to define
-a custom console class. It should look somehow like
+a custom console class. It should look somewhat like
 
 ```ruby
-class MyRailsConsole
-  def self.start
+class Async::RailsConsole
+  extend Grumlin::Repository
+
+  def start
+    self.class.shortcuts_from Shortcuts::Content
+
     IRB::WorkSpace.prepend(Rails::Console::BacktraceCleaner)
     IRB::ExtendCommandBundle.include(Rails::ConsoleMethods)
 
-    Async do
-      include Grumlin::Sugar
+    IRB.setup(binding.source_location[0], argv: [])
+    workspace = IRB::WorkSpace.new(binding)
+
+    begin
+      Async do
+        IRB::Irb.new(workspace).run(IRB.conf)
+      ensure
+        Grumlin.close
+      end
+    rescue StandardError, Interrupt, Async::Stop, IRB::Abort
+      retry
+    end
+  end
 
-      IRB.setup(binding.source_location[0], argv: [])
-      workspace = IRB::WorkSpace.new(binding)
+  def inspect
+    'main'
+  end
 
-      IRB::Irb.new(workspace).run(IRB.conf)
-    ensure
-      Grumlin.close
-    end
+  def to_s
+    inspect
   end
 end
 ```
@@ -381,13 +339,13 @@ require 'async/rspec'
 require require "grumlin/test/rspec"
 ...
 config.include_context(Async::RSpec::Reactor) # Runs async reactor
-config.include_context(Grumlin::Test::RSpec::GremlinContext) # Injects sugar and makes sure client is closed after every test
+config.include_context(Grumlin::Test::RSpec::GremlinContext) # Injects `g`, `__` and expressions, makes sure client is closed after every test
 config.include_context(Grumlin::Test::RSpec::DBCleanerContext) # Cleans the database before every test
 ...
 ```
 
-It is highly recommended to use `Grumlin::Sugar` or `Grumlin::Repository` and not trying to use lower level APIs
-as they are subject to change.
+It is highly recommended to use `Grumlin::Repository` and not trying to use lower level APIs as they are subject to 
+change.
 
 ## Development
 

data/Rakefile

@@ -9,7 +9,7 @@ require "rubocop/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
 
-task default: %i[rubocop spec]
+task default: [:rubocop, :spec]
 
 namespace :definitions do
   desc "Format definitions.yml"

data/bin/console

@@ -13,10 +13,25 @@ Grumlin.configure do |config|
   config.url = ENV.fetch("GREMLIN_URL", "ws://localhost:8182/gremlin")
 end
 
-Async do
-  include Grumlin::Sugar
+class Repository
+  extend Grumlin::Repository
+
+  def start_irb
+    IRB.setup(nil)
+    IRB.conf[:PROMPT][:DEFAULT] = { PROMPT_I: "%N(main):%03n:%i> ",
+                                    PROMPT_N: "%N(main):%03n:%i> ",
+                                    PROMPT_S: "%N(main):%03n:%i%l ",
+                                    PROMPT_C: "%N(main):%03n:%i* ",
+                                    RETURN: "=> %s\n" }
+    workspace = IRB::WorkSpace.new(binding)
+    irb = IRB::Irb.new(workspace)
+    IRB.conf[:MAIN_CONTEXT] = irb.context
+    irb.eval_input
+  end
+end
 
-  IRB.start
+Async do
+  Repository.new.start_irb
 ensure
   Grumlin.close
 end

data/doc/middlewares.md

@@ -14,10 +14,11 @@ execution process:
 Normally these middlewares must never be rearranged or removed from the stack. Middlewares added after
 `Middlewares::RunQuery` will not be executed.
 
-# Writing a middleware for Grumlin
+## Writing a middleware for Grumlin
 
-This entire feature is built on top of [ibsciss-middleware](https://github.com/Ibsciss/ruby-middleware).
-Please refer to it's docs if you want to implement a middleware.
+This entire feature is built on top of [ibsciss-middleware](https://github.com/Ibsciss/ruby-middleware) but uses a
+slightly modified `Builder` which caches the chain for better performance.
+Please refer to ibsciss-middleware docs if you want to implement a middleware.
 
 
 A minimal middleware that measures query execution time and puts it back to `env`:
@@ -31,13 +32,6 @@ class MeasureExecutionTime < Grumlin::Middlewares::Middleware # Middleware provi
     result
   end
 end
-
-Grumlin.configure do |cfg|
-  cfg.url = ENV.fetch("GREMLIN_URL", "ws://localhost:8182/gremlin")
-  cfg.provider = :tinkergraph
-
-  cfg.middlewares.insert_before Grumlin::Middlewares::CastResults, MeasureExecutionTime
-end
 ```
 
 When placed right before `Grumlin::Middlewares::CastResults` your middleware will have access to every intermediate result
@@ -56,3 +50,48 @@ Other useful parts of `env`:
 - `env[:session_id]` - id of the session when executed inside a transaction, otherwise `nil`
 - `env[:pool]` - connection pool that will be used to interact with the server
 - `env[:need_results]` - flag stating whether the client needs the query execution results(`toList`, `next`) or not(`iterate`)
+
+## Adding your middleware to the stack
+
+There are two ways of adding middlewares to your queries:
+- `global` - add the middleware to every single query from every single repository
+- `per repository` - add the middleware to queries performed by particular repositories
+
+Grumlin has one global middleware stack and every repository defines it's which is by default is a
+copy of the global stack. This means one can easily modify repository's stack without worrying about the global one.
+
+When inherited a class extending `Grumlin::Repository` will copy it's middlewares to the subclass, they can also be
+modified independently from the parent's middlewares.
+
+### Adding a middleware globally
+```ruby
+Grumlin.configure do |cfg|
+  cfg.url = ENV.fetch("GREMLIN_URL", "ws://localhost:8182/gremlin")
+  cfg.provider = :tinkergraph
+
+  cfg.middlewares do |b|
+    b.insert_before Grumlin::Middlewares::CastResults, MeasureExecutionTime
+  end
+end
+```
+
+### Adding a middleware to a repository
+```ruby
+class MyRepository
+  # MyRepository inherits a copy of global middlewares
+  extend Grumlin::Repository
+
+  # SomeOtherMiddleware will be added to MyRepository's middlewares only
+  middlewares do |b|
+    b.insert_before Grumlin::Middlewares::CastResults, MeasureExecutionTime
+  end
+end
+
+class AnotherRepository < MyRepository
+  # AnotherRepository inherits parent's middlewares
+  middlewares do |b|
+    # SomeOtherMiddleware will be added to AnotherRepository's middlewares only 
+    b.insert_before Grumlin::Middlewares::CastResults, SomeOtherMiddleware
+  end
+end
+```

data/lib/async/channel.rb

@@ -1,74 +1,72 @@
 # frozen_string_literal: true
 
-module Async
-  # Channel is a wrapper around Async::Queue that provides
-  # a protocol and handy tools for passing data, exceptions and closing.
-  # It is designed to be used only with one publisher and one subscriber
-  class Channel
-    class ChannelError < StandardError; end
-
-    class ChannelClosedError < ChannelError; end
-
-    def initialize
-      @queue = Async::Queue.new
-      @closed = false
-    end
+# Channel is a wrapper around Async::Queue that provides
+# a protocol and handy tools for passing data, exceptions and closing.
+# It is designed to be used only with one publisher and one subscriber
+class Async::Channel
+  class ChannelError < StandardError; end
 
-    def closed?
-      @closed
-    end
+  class ChannelClosedError < ChannelError; end
 
-    def open?
-      !@closed
-    end
+  def initialize
+    @queue = Async::Queue.new
+    @closed = false
+  end
 
-    # Methods for a publisher
-    def <<(payload)
-      raise(ChannelClosedError, "Cannot send to a closed channel") if @closed
+  def closed?
+    @closed
+  end
 
-      @queue << [:payload, payload]
-    end
+  def open?
+    !@closed
+  end
 
-    def exception(exception)
-      raise(ChannelClosedError, "Cannot send to a closed channel") if closed?
+  # Methods for a publisher
+  def <<(payload)
+    raise(ChannelClosedError, "Cannot send to a closed channel") if @closed
 
-      @queue << [:exception, exception]
-    end
+    @queue << [:payload, payload]
+  end
 
-    def close
-      return if closed?
+  def exception(exception)
+    raise(ChannelClosedError, "Cannot send to a closed channel") if closed?
 
-      @queue << [:close]
-      @closed = true
-    end
+    @queue << [:exception, exception]
+  end
 
-    def close!
-      return if closed?
+  def close
+    return if closed?
 
-      exception(ChannelClosedError.new("Channel was forcefully closed"))
-      close
-    end
+    @queue << [:close]
+    @closed = true
+  end
 
-    # Methods for a subscriber
-    def dequeue
-      each do |payload| # rubocop:disable Lint/UnreachableLoop this is intended
-        return payload
-      end
+  def close!
+    return if closed?
+
+    exception(ChannelClosedError.new("Channel was forcefully closed"))
+    close
+  end
+
+  # Methods for a subscriber
+  def dequeue
+    each do |payload| # rubocop:disable Lint/UnreachableLoop this is intended
+      return payload
     end
+  end
 
-    def each
-      raise(ChannelClosedError, "Cannot receive from a closed channel") if closed?
-
-      @queue.each do |type, payload|
-        case type
-        when :exception
-          payload.set_backtrace(caller + (payload.backtrace || [])) # A hack to preserve full backtrace
-          raise payload
-        when :payload
-          yield payload
-        when :close
-          break
-        end
+  def each
+    raise(ChannelClosedError, "Cannot receive from a closed channel") if closed?
+
+    @queue.each do |type, payload|
+      case type
+      when :exception
+        payload.set_backtrace(caller + (payload.backtrace || [])) # A hack to preserve full backtrace
+        raise payload
+      when :payload
+        yield payload
+      when :close
+        break
       end
     end
   end

data/lib/grumlin/benchmark/repository.rb

@@ -1,21 +1,17 @@
 # frozen_string_literal: true
 
-module Grumlin
-  module Benchmark
-    class Repository
-      extend Grumlin::Repository
+class Grumlin::Benchmark::Repository
+  extend Grumlin::Repository
 
-      shortcut :simple_test do
-        self.V
-      end
+  shortcut :simple_test do
+    self.V
+  end
 
-      def simple_test
-        g.V.bytecode.serialize
-      end
+  def simple_test
+    g.V.bytecode.serialize
+  end
 
-      def simple_test_with_shortcut
-        g.simple_test.bytecode.serialize
-      end
-    end
+  def simple_test_with_shortcut
+    g.simple_test.bytecode.serialize
   end
 end