lazy_graph 0.1.0

data/lib/lazy_graph/path_parser.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+# LazyGraph supports a bespoke path structure for querying a LazyGraph.
+# It has some overlap with
+# * JSON path (but supports querying a subset of object properties), and
+# * GraphQL (but it supports direct references to deeply nested properties without preserving structure)/
+#
+# Example query paths and outputs
+#
+# "employees" => {"employees": [{...whole object...}, {...whole object...}]}
+# "employees[id,name]" => {"employees": [{ "id": "3", "name": "John Smith}, { "id": "4", "name": "Jane Smith}]}
+# "employees[0..1] => {"employees": [{...whole object...}, {...whole object...}]}"
+# "employees[0..1] => {"employees": [{...whole object...}, {...whole object...}]}"
+#
+module LazyGraph
+  module PathParser
+    require_relative 'path_parser/path'
+    require_relative 'path_parser/path_group'
+    require_relative 'path_parser/path_part'
+    # This module is responsible for parsing complex path strings into structured components.
+    # Public class method to parse the path string
+    def self.parse(path, strip_root = false)
+      return Path::BLANK if path.nil? || path.empty?
+
+      start = strip_root && path.to_s.start_with?('$.') ? 2 : 0
+      parse_recursive(path, start)
+    end
+
+    class << self
+      # Recursively parses the path starting from index 'start'
+      # Returns [Path object, new_index]
+      def parse_recursive(path, start)
+        parse_structure = {
+          parts: [],
+          buffer: ''.dup,
+          i: start
+        }
+
+        parse_main_loop(path, parse_structure)
+        parse_finalize(parse_structure)
+
+        Path.new(parts: parse_structure[:parts])
+      end
+
+      def parse_main_loop(path, parse_structure)
+        while parse_structure[:i] < path.length
+          char = path[parse_structure[:i]]
+          handle_char(char, path, parse_structure)
+        end
+      end
+
+      def handle_char(char, path, structure)
+        case char
+        when '.'
+          handle_dot(path, structure)
+        when '['
+          handle_open_bracket(path, structure)
+        when ','
+          handle_comma(structure)
+        when ']'
+          handle_close_bracket(structure)
+        else
+          structure[:buffer] += char
+          structure[:i] += 1
+        end
+      end
+
+      def handle_dot(path, structure)
+        # Check if it's part of a range ('..' or '...')
+        if path[structure[:i] + 1] == '.'
+          handle_range_dot(path, structure)
+        else
+          handle_single_dot(structure)
+        end
+      end
+
+      def handle_range_dot(path, structure)
+        if path[structure[:i] + 2] == '.'
+          structure[:buffer] += '...'
+          structure[:i] += 3
+        else
+          structure[:buffer] += '..'
+          structure[:i] += 2
+        end
+      end
+
+      def handle_single_dot(structure)
+        unless structure[:buffer].strip.empty?
+          parsed = parse_buffer(structure[:buffer].strip)
+          append_parsed(parsed, structure[:parts])
+          structure[:buffer] = ''.dup
+        end
+        structure[:i] += 1
+      end
+
+      def append_parsed(parsed, parts)
+        if parsed.is_a?(Array)
+          parsed.each { |p| parts << p }
+        elsif parsed.is_a?(Range)
+          parts << PathGroup.new(options: parsed.map { |p| Path.new(parts: [PathPart.new(part: p.to_sym)]) })
+        else
+          parts << parsed
+        end
+      end
+
+      def handle_open_bracket(path, structure)
+        unless structure[:buffer].strip.empty?
+          paths = structure[:buffer].strip.split('.').map(&:strip)
+          paths.each { |p| structure[:parts] << PathPart.new(part: p.to_sym) }
+          structure[:buffer] = ''.dup
+        end
+
+        closing_bracket = find_matching_bracket(path, structure[:i])
+        raise 'Unbalanced brackets in path.' if closing_bracket == -1
+
+        inside = path[(structure[:i] + 1)...closing_bracket]
+        elements = split_by_comma(inside)
+        parsed_elements = elements.map { |el| parse_recursive(el, 0) }
+        path_group = PathGroup.new(options: parsed_elements)
+        structure[:parts] << path_group
+        structure[:i] = closing_bracket + 1
+      end
+
+      def handle_comma(structure)
+        unless structure[:buffer].strip.empty?
+          parsed = parse_buffer(structure[:buffer].strip)
+          append_parsed(parsed, structure[:parts])
+          structure[:buffer] = ''.dup
+        end
+        structure[:i] += 1
+      end
+
+      def handle_close_bracket(structure)
+        raise 'Unbalanced closing bracket in path.' if structure[:buffer].strip.empty?
+
+        parsed = parse_buffer(structure[:buffer].strip)
+        append_parsed(parsed, structure[:parts])
+        structure[:buffer] = ''.dup
+      end
+
+      def parse_finalize(structure)
+        return if structure[:buffer].strip.empty?
+
+        parsed = parse_buffer(structure[:buffer].strip)
+        append_parsed(parsed, structure[:parts])
+      end
+
+      def find_matching_bracket(path, start)
+        depth = 1
+        i = start + 1
+        while i < path.length
+          if path[i] == '['
+            depth += 1
+          elsif path[i] == ']'
+            depth -= 1
+            return i if depth.zero?
+          end
+          i += 1
+        end
+        -1 # No matching closing bracket found
+      end
+
+      def split_by_comma(str)
+        elements = []
+        buffer = ''.dup
+        depth = 0
+        str.each_char do |c|
+          case c
+          when '['
+            depth += 1
+            buffer << c
+          when ']'
+            depth -= 1
+            buffer << c
+          when ','
+            if depth.zero?
+              elements << buffer.strip
+              buffer = ''.dup
+            else
+              buffer << c
+            end
+          else
+            buffer << c
+          end
+        end
+        elements << buffer.strip unless buffer.strip.empty?
+        elements
+      end
+
+      def parse_buffer(buffer)
+        if buffer.include?('...')
+          parse_range(buffer, '...', true)
+        elsif buffer.include?('..')
+          parse_range(buffer, '..', false)
+        elsif buffer.include?('.')
+          paths = buffer.split('.').map(&:strip)
+          paths.map { |p| PathPart.new(part: p.to_sym) }
+        else
+          PathPart.new(part: buffer.to_sym)
+        end
+      end
+
+      def parse_range(buffer, delimiter, exclude_end)
+        parts = buffer.split(delimiter)
+        return buffer unless parts.size == 2
+
+        Range.new(parts[0].strip, parts[1].strip, exclude_end)
+      end
+    end
+  end
+end

data/lib/lazy_graph/server.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  class Server
+    ALLOWED_VALUES_VALIDATE = [true, false, nil, 'input', 'context'].to_set.freeze
+    ALLOWED_VALUES_DEBUG = [true, false, nil].to_set.freeze
+
+    def initialize(routes: {})
+      @routes = routes.transform_keys(&:to_sym).compare_by_identity
+    end
+
+    def call(env)
+      # Rack environment contains request details
+      request = Rack::Request.new(env)
+
+      unless (graph_module = @routes[request.path.to_sym])
+        return not_found!(request.path)
+      end
+
+      return success!(request, graph_module.usage) if request.get?
+
+      if request.post?
+        body = JSON.parse(request.body.read)
+        context, modules, validate, debug, query = body.values_at('context', 'modules', 'validate', 'debug', 'query')
+        unless context.is_a?(Hash) && !context.empty?
+          return not_acceptable!(request, "Invalid 'context' Parameter", 'Should be a non-empty object.')
+        end
+
+        unless modules.is_a?(Hash) && !modules.empty?
+          return not_acceptable!(request, "Invalid 'modules' Parameter", 'Should be a non-empty object.')
+        end
+
+        unless ALLOWED_VALUES_VALIDATE.include?(validate)
+          return not_acceptable!(
+            request, "Invalid 'validate' Parameter", "Should be nil, bool, or one of 'input', 'context'"
+          )
+        end
+
+        unless ALLOWED_VALUES_DEBUG.include?(debug)
+          return not_acceptable!(request, "Invalid 'debug' Parameter", 'Should be nil or bool')
+        end
+
+        unless query.nil? || query.is_a?(String) || (query.is_a?(Array) && query.all? do |q|
+          q.is_a?(String)
+        end)
+          return not_acceptable!(request, "Invalid 'query' Parameter", 'Should be nil, array or string array')
+        end
+
+        begin
+          result = graph_module.eval!(
+            modules: modules, context: context,
+            validate: validate, debug: debug,
+            query: query
+          )
+          return not_acceptable!(request, result[:message], result[:detail]) if result[:type] == :error
+
+          return success!(request, result)
+        rescue StandardError => e
+          LazyGraph.logger.error(e.message)
+          LazyGraph.logger.error(e.backtrace.join("\n"))
+          return error!(request, 500, 'Internal Server Error', e.message)
+        end
+      end
+
+      not_found!("#{request.request_method} #{request.path}")
+    end
+
+    def not_acceptable!(request, message, details = '')
+      error!(request, 406, message, details)
+    end
+
+    def not_found!(request, details = '')
+      error!(request, 404, 'Not Found', details)
+    end
+
+    def success!(request, result, status: 200)
+      LazyGraph.logger.info("#{request.request_method}: #{request.path} => #{status}")
+      [status, { 'Content-Type' => 'text/json' }, [result.to_json]]
+    end
+
+    def error!(request, status, message, details = '')
+      LazyGraph.logger.info("#{request.request_method}: #{request.path} => #{status}")
+      [status, { 'Content-Type' => 'text/json' }, [{ 'error': message, 'details': details }.to_json]]
+    end
+  end
+end

data/lib/lazy_graph/stack_pointer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  # Module to provide lazy graph functionalities using stack pointers.
+  POINTER_POOL = []
+
+  StackPointer = Struct.new(:parent, :frame, :depth, :key, :root) do
+    def push(frame, key)
+      (POINTER_POOL.pop || StackPointer.new).tap do |pointer|
+        pointer.parent = self
+        pointer.frame = frame
+        pointer.key = key
+        pointer.depth = depth + 1
+        pointer.root = root || self
+      end
+    end
+
+    def recycle!
+      POINTER_POOL.push(self)
+      nil
+    end
+
+    def ptr_at(index)
+      return self if depth == index
+
+      parent&.ptr_at(index)
+    end
+
+    def method_missing(name, *args, &block)
+      if frame.respond_to?(name)
+        frame.send(name, *args, &block)
+      elsif parent
+        parent.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def log_debug(**log_item)
+      root.frame[:DEBUG] = [] if !root.frame[:DEBUG] || root.frame[:DEBUG].is_a?(MissingValue)
+      root.frame[:DEBUG] << { **log_item, location: to_s }
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      frame.respond_to?(name, include_private) || parent.respond_to?(name, include_private)
+    end
+
+    def to_s
+      if parent
+        "#{parent}#{key.to_s =~ /\d+/ ? "[#{key}]" : ".#{key}"}"
+      else
+        key.to_s
+      end
+    end
+  end
+end

data/lib/lazy_graph/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  VERSION = '0.1.0'
+end

data/lib/lazy_graph.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+# LazyGraph is a library which allows you to define a strictly typed hierarchical Graph structure.
+# Within this graph you can annotate certain nodes as derived nodes, which compute their outputs based
+# on input dependencies on other nodes in the graph structure (can be relative and absolute references).
+# Dependencies can be nested any level deep (but cannot be circular).
+#
+# You can then provide a subset of the graph as input context, and extract calculated outputs from the same graph
+# which will be lazily computed (only derived rules actually needed for the queried output is computed).
+#
+module LazyGraph
+  class AbortError < StandardError; end
+  class << self
+    attr_accessor :logger
+  end
+
+  self.logger = Logger.new($stdout)
+end
+
+require_relative 'lazy_graph/context'
+require_relative 'lazy_graph/missing_value'
+require_relative 'lazy_graph/node'
+require_relative 'lazy_graph/graph'
+require_relative 'lazy_graph/version'
+require_relative 'lazy_graph/path_parser'
+require_relative 'lazy_graph/hash_utils'
+require_relative 'lazy_graph/builder'
+require_relative 'lazy_graph/builder_group'
+require_relative 'lazy_graph/stack_pointer'
+require_relative 'lazy_graph/server'

metadata

@@ -0,0 +1,200 @@
+--- !ruby/object:Gem::Specification
+name: lazy_graph
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Wouter Coppieters
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-12-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  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: rubocop
+  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: fiddle
+  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: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  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'
+description: JSON Driven, Stateless Rules Engine for JIT and efficient evaluation
+  of complex rules and computation graphs.
+email:
+- wc@pico.net.nz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/performance_tests.rb
+- lib/lazy_graph.rb
+- lib/lazy_graph/builder.rb
+- lib/lazy_graph/builder/dsl.rb
+- lib/lazy_graph/builder_group.rb
+- lib/lazy_graph/context.rb
+- lib/lazy_graph/graph.rb
+- lib/lazy_graph/hash_utils.rb
+- lib/lazy_graph/lazy-graph.json
+- lib/lazy_graph/missing_value.rb
+- lib/lazy_graph/node.rb
+- lib/lazy_graph/node/array_node.rb
+- lib/lazy_graph/node/derived_rules.rb
+- lib/lazy_graph/node/node_properties.rb
+- lib/lazy_graph/node/object_node.rb
+- lib/lazy_graph/path_parser.rb
+- lib/lazy_graph/path_parser/path.rb
+- lib/lazy_graph/path_parser/path_group.rb
+- lib/lazy_graph/path_parser/path_part.rb
+- lib/lazy_graph/server.rb
+- lib/lazy_graph/stack_pointer.rb
+- lib/lazy_graph/version.rb
+- logo.png
+homepage: https://github.com/wouterken/lazy_graph
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/wouterken/lazy_graph
+  source_code_uri: https://github.com/wouterken/lazy_graph
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: JSON Driven, Stateless Rules Engine
+test_files: []