lazy_graph 0.1.0

data/lib/lazy_graph/node/object_node.rb

@@ -0,0 +1,113 @@
+module LazyGraph
+  class ObjectNode < Node
+    # An object supports the following types of path resolutions.
+    # 1. Property name: obj.property => value
+    # 2. Property name group: obj[property1, property2] =>  { property1: value1, property2: value2 }
+    # 3. All [*]
+    def resolve(
+      path,
+      stack_memory,
+      should_recycle = stack_memory,
+      preserve_keys: false
+    )
+      input = stack_memory.frame
+      @visited[input.object_id ^ (path.object_id << 8)] ||= begin
+        if (path_segment = path.segment).is_a?(PathParser::PathGroup)
+          return path_segment.options.each_with_object({}.tap(&:compare_by_identity)) do |part, object|
+            resolve(part.merge(path.next), stack_memory, nil, preserve_keys: object)
+          end
+        end
+
+        if !segment = path_segment&.part
+          @properties_a.each do |key, node|
+            item = node.fetch_item(input, key, stack_memory)
+            node.resolve(path.next, stack_memory.push(item, key))
+          end
+          if @pattern_properties_a.any? && input.keys.length > @properties_a.length
+            input.each_key do |key|
+              node = !@properties[key] && @pattern_properties_a.find { |pattern, _value| pattern.match?(key) }&.last
+              item = node.fetch_item(input, key, stack_memory)
+              node.resolve(path.next, stack_memory.push(item, key))
+            end
+          end
+          input
+        elsif (prop = @properties[segment])
+          item = prop.fetch_item(input, segment, stack_memory)
+          value = prop.resolve(
+            path.next, stack_memory.push(item, segment)
+          )
+          preserve_keys ? preserve_keys[segment] = value : value
+        elsif segment == :*
+          # rubocop:disable
+          (input.keys | @properties_a.map(&:first)).each do |key|
+            next unless (node = @properties[key] || @pattern_properties_a.find do |pattern, _value|
+              pattern.match?(key)
+            end&.last)
+
+            item = node.fetch_item(input, key, stack_memory)
+            preserve_keys[key] = node.resolve(path.next, stack_memory.push(item, key))
+          end
+        elsif (_, prop = @pattern_properties_a.find { |key, _val| key.match?(segment) })
+          item = prop.fetch_item(input, segment, stack_memory)
+          value = prop.resolve(
+            path.next, stack_memory.push(item, segment)
+          )
+          preserve_keys ? preserve_keys[segment] = value : value
+        elsif input.key?(segment)
+          prop = @properties[segment] = lazy_init_node!(input[segment], segment)
+          @properties_a = @properties.to_a
+          item = prop.fetch_item(input, segment, stack_memory)
+          value = prop.resolve(
+            path.next, stack_memory.push(item, segment)
+          )
+          preserve_keys ? preserve_keys[segment] = value : value
+        else
+          value = MissingValue()
+          preserve_keys ? preserve_keys[segment] = value : value
+        end
+      end
+    ensure
+      should_recycle&.recycle!
+    end
+
+    def find_resolver_for(segment)
+      if segment == :'$'
+        root
+      elsif @properties.key?(segment)
+        self
+      else
+        @parent&.find_resolver_for(segment)
+      end
+    end
+
+    def children=(value)
+      @children = value
+
+      @properties = @children.fetch(:properties, {})
+      @properties.compare_by_identity
+      @pattern_properties = @children.fetch(:pattern_properties, {})
+
+      @properties_a = @properties.to_a
+      @pattern_properties_a = @pattern_properties.to_a
+
+      @has_properties = @properties.any? || @pattern_properties.any?
+      return if @pattern_properties.any?
+      return unless @properties.any?
+
+      invisible = @properties.select { |_k, v| v.invisible }.map(&:first)
+      @property_class = PROPERTY_CLASSES[{ members: @properties.keys + (@debug && !parent ? [:DEBUG] : []),
+                                           invisible: invisible }]
+    end
+
+    def cast(value)
+      if !@property_class && value.is_a?(Hash)
+        value.default_proc = ->(h, k) { k.is_a?(Symbol) ? nil : h[k.to_s.to_sym] }
+        value.compare_by_identity
+      elsif @property_class && !value.is_a?(@property_class)
+        @property_class.new(value.to_h)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/lazy_graph/node.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require 'bigdecimal/util'
+require 'json'
+
+module LazyGraph
+  require_relative 'node/derived_rules'
+  require_relative 'node/array_node'
+  require_relative 'node/object_node'
+  require_relative 'node/node_properties'
+
+  DIGIT_REGEXP = /^-?\d+$/
+  SAFE_TOKEN_REGEXP = /^[A-Za-z][A-Za-z0-9]*$/
+  PROPERTY_CLASSES = Hash.new do |h, members|
+    h[members] = LazyGraph.const_set("NodeProperties#{h.hash.abs}", NodeProperties.build(**members))
+  end
+
+  # Class: Node
+  # Represents A single Node within our LazyGraph structure
+  # A node is a logical position with a graph structure.
+  # The node might capture knowledge about how to derived values at its position
+  # if a value is not provided.
+  # This can be in the form of a default value or a derivation rule.
+  #
+  # This class is heavily optimized to resolve values in a graph structure
+  # with as little overhead as possible. (Note heavy use of ivars,
+  # and minimal method calls in the recursive resolve method).
+  #
+  # Nodes support (non-circular) recursive resolution of values, i.e.
+  # if a node depends on the output of several other nodes in the graph,
+  # it will resolve those nodes first before resolving itself.
+  #
+  # Node resolution maintains a full stack, so that values can be resolved relative to the position
+  # of the node itself.
+  #
+
+  class Node
+    include DerivedRules
+    attr_accessor :name, :path, :type, :derived, :depth, :parent, :root, :invisible
+    attr_accessor :children
+    attr_reader :is_object
+
+    def initialize(name, path, node, parent, debug: false, helpers: nil)
+      @name = name
+      @path = path
+      @parent = parent
+      @debug = debug
+      @depth = parent ? parent.depth + 1 : 0
+      @root = parent ? parent.root : self
+      @type = node[:type]
+      @invisible = node[:invisible]
+      @visited = {}.compare_by_identity
+
+      define_missing_value_proc!
+
+      @has_default = node.key?(:default)
+      @default = @has_default ? node[:default] : MissingValue { @name }
+      @resolution_stack = []
+
+      instance_variable_set("@is_#{@type}", true)
+      build_derived_inputs(node[:rule], helpers) if node[:rule]
+    end
+
+    def define_missing_value_proc!
+      define_singleton_method(
+        :MissingValue,
+        @debug ? ->(&blk) { MissingValue.new(blk&.call || absolute_path) } : -> { MissingValue::BLANK }
+      )
+    end
+
+    def clear_visits!
+      @visited.clear
+      return unless @children
+      return @children.clear_visits! if @children.is_a?(Node)
+
+      @children[:properties]&.each do |_, node|
+        node.clear_visits!
+      end
+
+      @children[:pattern_properties]&.each do |_, node|
+        node.clear_visits!
+      end
+    end
+
+    # When we assign children to a node, we preemptively extract the properties, and pattern properties
+    # in both hash and array form. This micro-optimization pays off when we resolve values in the graph at
+    # very high frequency.
+
+    def resolve(
+      path,
+      stack_memory,
+      should_recycle = stack_memory,
+      **
+    )
+      path.empty? ? stack_memory.frame : MissingValue()
+    ensure
+      should_recycle&.recycle!
+    end
+
+    def lazy_init_node!(input, key)
+      case input
+      when Hash
+        node = Node.new(key, "#{path}.#{key}", { type: :object }, self)
+        node.children = { properties: {}, pattern_properties: {} }
+        node
+      when Array
+        node = Node.new(key, :"#{path}.#{key}[]", { type: :array }, self)
+        child_type = \
+          case input.first
+          when Hash then :object
+          when Array then :array
+          end
+        node.children = Node.new(:items, :"#{path}.#{key}[].items", { type: child_type }, node)
+        node.children.children = { properties: {}, pattern_properties: {} } if child_type == :object
+        node
+      else
+        Node.new(key, :"#{path}.#{key}", {}, self)
+      end
+    end
+
+    def absolute_path
+      @absolute_path ||= begin
+        next_node = self
+        path = []
+        while next_node
+          path << next_node.name
+          next_node = next_node.parent
+        end
+        path.reverse.join('.')
+      end
+    end
+
+    def resolve_input(stack_memory, path, key)
+      input_id = key.object_id ^ (stack_memory.object_id << 8)
+      if @resolution_stack.include?(input_id)
+        if @debug
+          stack_memory.log_debug(
+            property: "#{stack_memory}.#{key}",
+            exception: 'Infinite Recursion Detected during dependency resolution'
+          )
+        end
+        return MissingValue { "Infinite Recursion in #{stack_memory} => #{path.to_path_str}" }
+      end
+
+      @resolution_stack << (input_id)
+      first_segment = path.parts.first.part
+      resolver_node = @resolvers[first_segment] ||= (first_segment == key ? parent.parent : parent).find_resolver_for(first_segment)
+
+      if resolver_node
+        input_frame_pointer = stack_memory.ptr_at(resolver_node.depth)
+        resolver_node.resolve(
+          first_segment == :'$' ? path.next : path,
+          input_frame_pointer,
+          nil
+        )
+      else
+        MissingValue { path.to_path_str }
+      end
+    ensure
+      @resolution_stack.pop
+    end
+
+    def ancestors
+      @ancestors ||= [self, *(parent ? parent.ancestors : [])]
+    end
+
+    def find_resolver_for(segment)
+      segment == :'$' ? root : @parent&.find_resolver_for(segment)
+    end
+
+    def cast(value)
+      if @is_decimal
+        value.is_a?(BigDecimal) ? value : value.to_d
+      elsif @is_date
+        value.is_a?(String) ? Date.parse(value) : value
+      elsif @is_boolean
+        if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          value
+        else
+          value.is_a?(MissingValue) ? false : !!value
+        end
+      elsif @is_timestamp
+        case value
+        when String then DateTime.parse(value).to_time
+        when Numeric then Time.at(value)
+        else value
+        end
+      else
+        value
+      end
+    end
+
+    def fetch_item(input, key, stack)
+      return MissingValue { key } unless input
+
+      has_value = \
+        case input
+        when Array then input.length > key && input[key]
+        when Hash, Struct then input.key?(key) && !input[key].is_a?(MissingValue)
+        end
+
+      if has_value
+        value = input[key]
+        value = cast(value) if value || @is_boolean
+        return input[key] = value
+      end
+
+      return input[key] = @default unless derived
+
+      if @copy_input
+        copy_item!(input, key, stack, @inputs.first)
+      else
+        derive_item!(input, key, stack)
+      end
+    end
+
+    def copy_item!(input, key, stack, (path, i, segment_indexes))
+      if segment_indexes
+        missing_value = nil
+        parts = path.parts.dup
+        parts_identity = path.identity
+        segment_indexes.each do |index|
+          part = resolve_input(stack, parts[index].options.first, key)
+          break missing_value = part if part.is_a?(MissingValue)
+
+          part_sym = part.to_s.to_sym
+          parts_identity ^= part_sym.object_id << index
+          parts[index] = @path_cache[part_sym] ||= PathParser::PathPart.new(part: part_sym)
+        end
+        path = @path_cache[parts_identity] ||= PathParser::Path.new(parts: parts) unless missing_value
+      end
+
+      result = missing_value || cast(resolve_input(stack, path, key))
+
+      if @debug
+        stack.log_debug(
+          output: :"#{stack}.#{key}",
+          result: result,
+          inputs: @node_context.to_h.except(:itself, :stack_ptr),
+          calc: @src
+        )
+      end
+
+      input[key] = result.nil? ? MissingValue { key } : result
+    end
+
+    def derive_item!(input, key, stack)
+      @inputs.each do |path, i, segment_indexes|
+        if segment_indexes
+          missing_value = nil
+          parts = path.parts.dup
+          parts_identity = path.identity
+          segment_indexes.each do |index|
+            part = resolve_input(stack, parts[index].options.first, key)
+            break missing_value = part if part.is_a?(MissingValue)
+
+            part_sym = part.to_s.to_sym
+            parts_identity ^= part_sym.object_id << index
+            parts[index] = @path_cache[part_sym] ||= PathParser::PathPart.new(part: part_sym)
+          end
+          path = @path_cache[parts_identity] ||= PathParser::Path.new(parts: parts) unless missing_value
+        end
+
+        result = missing_value || resolve_input(stack, path, key)
+        @node_context[i] = result.is_a?(MissingValue) ? nil : result
+      end
+
+      @node_context[:itself] = input
+      @node_context[:stack_ptr] = stack
+
+      conditions_passed = !@conditions || @conditions.all? do |field, allowed_value|
+        allowed_value.is_a?(Array) ? allowed_value.include?(@node_context[field]) : allowed_value == @node_context[field]
+      end
+
+      ex = nil
+      result = \
+        if conditions_passed
+          output = begin
+            cast(@node_context.process!)
+          rescue LazyGraph::AbortError => e
+            raise e
+          rescue StandardError => e
+            ex = e
+            MissingValue { "#{key} raised exception: #{e.message}" }
+          end
+          output = output.dup if @has_properties
+          input[key] = output.nil? ? MissingValue { key } : output
+        else
+          MissingValue { key }
+        end
+
+      if @debug
+        stack.log_debug(
+          output: :"#{stack}.#{key}",
+          result: result,
+          inputs: @node_context.to_h.except(:itself, :stack_ptr),
+          calc: @src,
+          **(@conditions ? { conditions: @conditions } : {}),
+          **(
+            if ex
+              {
+                exception: ex,
+                backtrace: ex.backtrace.take_while do |line|
+                  !line.include?('lazy_graph/node.rb')
+                end
+              }
+            else
+              {}
+            end
+          )
+        )
+      end
+      result
+    end
+  end
+end

data/lib/lazy_graph/path_parser/path.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  module PathParser
+    # This module is responsible for parsing complex path strings into structured components.
+
+    # Path represents a structured component of a complex path string.
+    # It provides methods to navigate and manipulate the path parts.
+
+    Path = Struct.new(:parts, keyword_init: true) do
+      def next        = @next ||= parts.length <= 1 ? Path::BLANK : Path.new(parts: parts[1..])
+      def empty?      = @empty ||= parts.empty?
+      def segment     = @segment ||= parts&.[](0)
+      def index?      = @index   ||= parts.any? && parts.first.index?
+      def identity    = @identity ||= parts&.each_with_index&.reduce(0) { |acc, (p, i)| acc ^ (p.object_id) << (i * 4) }
+      def map(&block) = empty? ? self : Path.new(parts: parts.map(&block))
+
+      def merge(other)
+        (@merged ||= {})[other] ||= \
+          if other.empty?
+            self
+          else
+            empty? ? other : Path.new(parts: parts + other.parts)
+          end
+      end
+
+      def to_path_str
+        @to_path_str ||= create_path_str
+      end
+
+      private
+
+      def create_path_str
+        parts.inject('$') do |path_str, part|
+          path_str + \
+            if part.is_a?(PathPart)
+              ".#{part.part}"
+            else
+              "[#{part.options.map(&:to_path_str).join(',').delete_prefix('$.')}]"
+            end
+        end
+      end
+    end
+    Path::BLANK = Path.new(parts: [])
+  end
+end

data/lib/lazy_graph/path_parser/path_group.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  module PathParser
+    # Represents a group of paths with a list of options, which must all be resolved.
+    PathGroup = Struct.new(:options, keyword_init: true) do
+      def index?
+        @index ||= options.all?(&:index?)
+      end
+    end
+  end
+end

data/lib/lazy_graph/path_parser/path_part.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module LazyGraph
+  module PathParser
+    INDEX_REGEXP = /\A-?\d+\z/
+    # Represents a single part of a path.
+    PathPart = Struct.new(:part, keyword_init: true) do
+      def index?
+        @index ||= part =~ INDEX_REGEXP
+      end
+    end
+  end
+end