bcdd-result 0.9.0 → 0.10.0

data/lib/bcdd/result/transitions/tracking.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Transitions
+    module Tracking
+      require_relative 'tracking/enabled'
+      require_relative 'tracking/disabled'
+
+      EMPTY_ARRAY = [].freeze
+      EMPTY_HASH = {}.freeze
+      EMPTY_TREE = Tree.new(nil).freeze
+      VERSION = 1
+      EMPTY = { version: VERSION, records: EMPTY_ARRAY, metadata: { duration: 0, tree_map: EMPTY_ARRAY } }.freeze
+
+      def self.instance
+        Config.instance.feature.enabled?(:transitions) ? Tracking::Enabled.new : Tracking::Disabled
+      end
+    end
+  end
+end

data/lib/bcdd/result/transitions/tree.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Transitions
+    class Tree
+      class Node
+        attr_reader :id, :value, :parent, :normalizer, :children
+
+        def initialize(value, parent:, id:, normalizer:)
+          @normalizer = normalizer
+
+          @id = id
+          @value = normalizer.call(id, value)
+          @parent = parent
+
+          @children = []
+        end
+
+        def insert(value, id:)
+          node = self.class.new(value, parent: self, id: id, normalizer: normalizer)
+
+          @children << node
+
+          node
+        end
+
+        def root?
+          parent.nil?
+        end
+
+        def leaf?
+          children.empty?
+        end
+
+        def node?
+          !leaf?
+        end
+
+        def inspect
+          "#<#{self.class.name} id=#{id} children.size=#{children.size}>"
+        end
+      end
+
+      attr_reader :size, :root, :current
+
+      def initialize(value, normalizer: ->(_id, val) { val })
+        @size = 0
+
+        @root = Node.new(value, parent: nil, id: @size, normalizer: normalizer)
+
+        @current = @root
+      end
+
+      def root_value
+        root.value
+      end
+
+      def parent_value
+        current.parent&.value || root_value
+      end
+
+      def current_value
+        current.value
+      end
+
+      def insert(value)
+        @size += 1
+
+        current.insert(value, id: size)
+      end
+
+      def insert!(value)
+        @current = insert(value)
+      end
+
+      def move_up!(level = 1)
+        tap { level.times { @current = current.parent || root } }
+      end
+
+      def move_down!(level = 1, index: -1)
+        tap { level.times { current.children[index].then { |child| @current = child if child } } }
+      end
+
+      def move_to_root!
+        tap { @current = root }
+      end
+
+      NestedIds = ->(node) { [node.id, node.children.map(&NestedIds)] }
+
+      def nested_ids
+        NestedIds[root]
+      end
+    end
+  end
+end

data/lib/bcdd/result/transitions.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class BCDD::Result
+  module Transitions
+    require_relative 'transitions/tree'
+    require_relative 'transitions/tracking'
+
+    THREAD_VAR_NAME = :bcdd_result_transitions_tracking
+
+    def self.tracking
+      Thread.current[THREAD_VAR_NAME] ||= Tracking.instance
+    end
+  end
+
+  def self.transitions(name: nil, desc: nil)
+    Transitions.tracking.start(name: name, desc: desc)
+
+    result = yield
+
+    result.is_a?(::BCDD::Result) or raise Error::UnexpectedOutcome.build(outcome: result, origin: :transitions)
+
+    Transitions.tracking.finish(result: result)
+
+    result
+  rescue ::Exception => e
+    Transitions.tracking.reset!
+
+    raise e
+  end
+end

data/lib/bcdd/result/version.rb

@@ -2,6 +2,6 @@
 
 module BCDD
   class Result
-    VERSION = '0.9.0'
+    VERSION = '0.10.0'
   end
 end

data/lib/bcdd/result.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'result/version'
+require_relative 'result/transitions'
 require_relative 'result/error'
 require_relative 'result/data'
 require_relative 'result/handler'
@@ -13,13 +14,13 @@ require_relative 'result/context'
 require_relative 'result/config'
 
 class BCDD::Result
-  attr_accessor :unknown
+  attr_accessor :unknown, :transitions
 
   attr_reader :subject, :data, :type_checker, :halted
 
   protected :subject
 
-  private :unknown, :unknown=, :type_checker
+  private :unknown, :unknown=, :type_checker, :transitions=
 
   def self.config
     Config.instance
@@ -40,6 +41,9 @@ class BCDD::Result
     @data = data
 
     self.unknown = true
+    self.transitions = Transitions::Tracking::EMPTY
+
+    Transitions.tracking.record(self)
   end
 
   def halted?
@@ -84,16 +88,12 @@ class BCDD::Result
     tap { yield(value, type) if unknown }
   end
 
-  def and_then(method_name = nil, context = nil)
+  def and_then(method_name = nil, context = nil, &block)
     return self if halted?
 
-    method_name && block_given? and raise ::ArgumentError, 'method_name and block are mutually exclusive'
-
-    return call_subject_method(method_name, context) if method_name
-
-    result = yield(value)
+    method_name && block and raise ::ArgumentError, 'method_name and block are mutually exclusive'
 
-    ensure_result_object(result, origin: :block)
+    method_name ? call_and_then_subject_method(method_name, context) : call_and_then_block(block)
   end
 
   def handle
@@ -139,18 +139,35 @@ class BCDD::Result
     block.call(value, type)
   end
 
-  def call_subject_method(method_name, context)
+  def call_and_then_subject_method(method_name, context_data)
     method = subject.method(method_name)
 
-    result =
-      case method.arity
-      when 0 then subject.send(method_name)
-      when 1 then subject.send(method_name, value)
-      when 2 then subject.send(method_name, value, context)
-      else raise Error::InvalidSubjectMethodArity.build(subject: subject, method: method, max_arity: 2)
-      end
+    Transitions.tracking.record_and_then(method, context_data, subject) do
+      result = call_and_then_subject_method!(method, context_data)
+
+      ensure_result_object(result, origin: :method)
+    end
+  end
+
+  def call_and_then_subject_method!(method, context_data)
+    case method.arity
+    when 0 then subject.send(method.name)
+    when 1 then subject.send(method.name, value)
+    when 2 then subject.send(method.name, value, context_data)
+    else raise Error::InvalidSubjectMethodArity.build(subject: subject, method: method, max_arity: 2)
+    end
+  end
+
+  def call_and_then_block(block)
+    Transitions.tracking.record_and_then(:block, nil, subject) do
+      result = call_and_then_block!(block)
+
+      ensure_result_object(result, origin: :block)
+    end
+  end
 
-    ensure_result_object(result, origin: :method)
+  def call_and_then_block!(block)
+    block.call(value)
   end
 
   def ensure_result_object(result, origin:)

data/sig/bcdd/result/config.rbs

@@ -0,0 +1,100 @@
+class BCDD::Result::Config
+  include Singleton
+
+  ADDON: Hash[Symbol, Hash[Symbol, untyped]]
+  FEATURE: Hash[Symbol, Hash[Symbol, untyped]]
+  PATTERN_MATCHING: Hash[Symbol, Hash[Symbol, untyped]]
+
+  attr_reader addon: BCDD::Result::Config::Switcher
+  attr_reader feature: BCDD::Result::Config::Switcher
+  attr_reader constant_alias: BCDD::Result::Config::Switcher
+  attr_reader pattern_matching: BCDD::Result::Config::Switcher
+
+  def self.instance: -> BCDD::Result::Config
+
+  def initialize: -> void
+
+  def freeze: -> BCDD::Result::Config
+  def options: -> Hash[Symbol, BCDD::Result::Config::Switcher]
+  def to_h: -> Hash[Symbol, Hash[Symbol | String, bool]]
+end
+
+module BCDD::Result::Config::Options
+  def self.with_defaults: (
+    Hash[Symbol, Hash[Symbol, bool]],
+    Symbol
+  ) -> Hash[Symbol, bool]
+
+  def self.select: (
+    Hash[Symbol, Hash[Symbol, bool]],
+    config: Symbol,
+    from: Hash[Symbol, untyped]
+  ) -> Hash[Symbol, untyped]
+
+  def self.addon: (
+    map: Hash[Symbol, Hash[Symbol, bool]],
+    from: Hash[Symbol, Module]
+  ) -> Hash[Symbol, Module]
+end
+
+class BCDD::Result::Config::Switcher
+  private attr_reader _affects: Hash[Symbol | String, Array[String]]
+  private attr_reader _options: Hash[Symbol | String, bool]
+  private attr_reader listener: Proc
+
+  def initialize: (
+    options: Hash[Symbol | String, Hash[Symbol, untyped]],
+    ?listener: Proc
+  ) -> void
+
+  def freeze: -> BCDD::Result::Config::Switcher
+
+  def to_h: -> Hash[Symbol | String, bool]
+
+  def options: -> Hash[Symbol | String, Hash[Symbol, untyped]]
+
+  def enabled?: (Symbol | String) -> bool
+
+  def enable!: (*(Symbol | String)) -> Hash[Symbol | String, Hash[Symbol, untyped]]
+
+  def disable!: (*(Symbol | String)) -> Hash[Symbol | String, Hash[Symbol, untyped]]
+
+  private
+
+  def set_many: (Array[Symbol | String], to: bool) -> Hash[Symbol | String, Hash[Symbol, untyped]]
+
+  def set_one: (Symbol | String, bool) -> void
+
+  def require_option!: (Array[Symbol | String]) -> void
+
+  def validate_option!: (Symbol | String) -> void
+
+  def available_options_message: -> String
+end
+
+module BCDD::Result::Config::Addons
+  OPTIONS: Hash[String, Hash[Symbol, untyped]]
+
+  def self.switcher: -> BCDD::Result::Config::Switcher
+end
+
+module BCDD::Result::Config::ConstantAliases
+  MAPPING: Hash[String, Hash[Symbol, untyped]]
+  OPTIONS: Hash[String, Hash[Symbol, untyped]]
+  Listener: Proc
+
+  def self.switcher: -> BCDD::Result::Config::Switcher
+end
+
+module BCDD::Result::Config::Features
+  OPTIONS: Hash[String, Hash[Symbol, untyped]]
+  Listener: Proc
+
+  def self.switcher: -> BCDD::Result::Config::Switcher
+end
+
+module BCDD::Result::Config::PatternMatching
+  OPTIONS: Hash[String, Hash[Symbol, untyped]]
+
+  def self.switcher: -> BCDD::Result::Config::Switcher
+end

data/sig/bcdd/result/context.rbs

@@ -0,0 +1,102 @@
+class BCDD::Result::Context < BCDD::Result
+  EXPECTED_OUTCOME: String
+
+  SubjectMethodArity: ^(Method) -> Integer
+
+  attr_reader acc: Hash[Symbol, untyped]
+
+  def initialize: (
+    type: Symbol,
+    value: untyped,
+    ?subject: untyped,
+    ?expectations: BCDD::Result::Contract::Evaluator,
+    ?halted: bool
+  ) -> void
+
+  def and_then: (?Symbol, **untyped) ?{ (Hash[Symbol, untyped]) -> untyped } -> BCDD::Result::Context
+
+  private
+
+  def call_and_then_subject_method: (Symbol, Hash[Symbol, untyped]) -> BCDD::Result::Context
+  def ensure_result_object: (untyped, origin: Symbol) -> BCDD::Result::Context
+
+  def raise_unexpected_outcome_error: (BCDD::Result::Context | untyped, Symbol) -> void
+end
+
+class BCDD::Result::Context
+  class Success < BCDD::Result::Context
+    include BCDD::Result::Success::Methods
+
+    def and_expose: (Symbol, Array[Symbol], halted: bool) -> BCDD::Result::Context::Success
+  end
+
+  def self.Success: (Symbol, **untyped) -> BCDD::Result::Context::Success
+end
+
+class BCDD::Result::Context
+  class Failure < BCDD::Result::Context
+    include BCDD::Result::Failure::Methods
+
+    def and_expose: (Symbol, Array[Symbol], **untyped) -> BCDD::Result::Context::Failure
+  end
+
+  def self.Failure: (Symbol, **untyped) -> BCDD::Result::Context::Failure
+end
+
+class BCDD::Result::Context
+  module Mixin
+    Factory: singleton(BCDD::Result::Mixin::Factory)
+
+    module Methods
+      def Success: (Symbol, **untyped) -> BCDD::Result::Context::Success
+
+      def Failure: (Symbol, **untyped) -> BCDD::Result::Context::Failure
+
+      private
+
+      def _ResultAs: (singleton(BCDD::Result::Context), Symbol, untyped, ?halted: bool) -> untyped
+    end
+
+    module Addons
+      module Continuable
+        include BCDD::Result::Context::Mixin::Methods
+
+        private
+
+        def Continue: (**untyped) -> BCDD::Result::Context::Success
+      end
+
+      OPTIONS: Hash[Symbol, Module]
+
+      def self.options: (Hash[Symbol, Hash[Symbol, bool]]) -> Hash[Symbol, Module]
+    end
+  end
+
+  def self.mixin_module: -> singleton(BCDD::Result::Context::Mixin)
+
+  def self.result_factory: -> singleton(BCDD::Result::Context)
+end
+
+class BCDD::Result::Context::Expectations < BCDD::Result::Expectations
+  def self.mixin_module: -> singleton(BCDD::Result::Context::Expectations::Mixin)
+
+  def self.result_factory_without_expectations: -> singleton(BCDD::Result)
+
+  def Success: (Symbol, **untyped) -> BCDD::Result::Context::Success
+  def Failure: (Symbol, **untyped) -> BCDD::Result::Context::Failure
+end
+
+module BCDD::Result::Context::Expectations::Mixin
+  Methods: singleton(BCDD::Result::Expectations::Mixin::Methods)
+  Factory: singleton(BCDD::Result::Expectations::Mixin::Factory)
+
+  module Addons
+    module Continuable
+      private def Continue: (**untyped) -> BCDD::Result::Context::Success
+    end
+
+    OPTIONS: Hash[Symbol, Module]
+
+    def self.options: (Hash[Symbol, Hash[Symbol, bool]]) -> Hash[Symbol, Module]
+  end
+end

data/sig/bcdd/result/contract.rbs

@@ -0,0 +1,119 @@
+module BCDD::Result::Contract
+  NONE: BCDD::Result::Contract::Evaluator
+
+  def self.evaluate: (
+    BCDD::Result::Data,
+    BCDD::Result::Contract::Evaluator
+  ) -> BCDD::Result::Contract::TypeChecker
+
+  ToEnsure: ^(Hash[Symbol, untyped] | Array[Symbol], Hash[Symbol, Hash[Symbol, bool]])
+    -> BCDD::Result::Contract::Interface
+
+  def self.new: (
+    success: Hash[Symbol, untyped] | Array[Symbol],
+    failure: Hash[Symbol, untyped] | Array[Symbol],
+    config: Hash[Symbol, Hash[Symbol, bool]]
+  ) -> BCDD::Result::Contract::Evaluator
+end
+
+module BCDD::Result::Contract
+  class TypeChecker
+    attr_reader result_type: Symbol
+    attr_reader expectations: BCDD::Result::Contract::Evaluator
+
+    def initialize: (
+      Symbol,
+      expectations: BCDD::Result::Contract::Evaluator
+    ) -> void
+
+    def allow?: (Array[Symbol]) -> bool
+    def allow_success?: (Array[Symbol]) -> bool
+    def allow_failure?: (Array[Symbol]) -> bool
+
+    private
+
+    def validate: (
+      Array[Symbol],
+      expected: BCDD::Result::Contract::Interface,
+      allow_empty: bool
+    ) -> bool
+  end
+end
+
+class BCDD::Result::Contract::Error < BCDD::Result::Error
+  class UnexpectedType < BCDD::Result::Contract::Error
+    def self.build: (type: Symbol, allowed_types: Set[Symbol])
+        -> BCDD::Result::Contract::Error::UnexpectedType
+  end
+
+  class UnexpectedValue < BCDD::Result::Contract::Error
+    def self.build: (type: Symbol, value: untyped, ?cause: Exception)
+      -> BCDD::Result::Contract::Error::UnexpectedValue
+  end
+end
+
+module BCDD::Result::Contract
+  module Interface
+    def ==: (BCDD::Result::Contract::Interface) -> bool
+
+    def allowed_types: -> Set[Symbol]
+
+    def type?: (Symbol) -> bool
+
+    def type!: (Symbol) -> Symbol
+
+    def type_and_value!: (BCDD::Result::Data) -> void
+
+    def !=: (untyped) -> bool
+  end
+end
+
+module BCDD::Result::Contract
+  module Disabled
+    extend Interface
+
+    EMPTY_SET: Set[Symbol]
+  end
+end
+
+module BCDD::Result::Contract
+  class ForTypes
+    include Interface
+
+    def initialize: (Array[Symbol]) -> void
+  end
+end
+
+module BCDD::Result::Contract
+  class ForTypesAndValues
+    include Interface
+
+    def initialize: (
+      Hash[Symbol, untyped],
+      Hash[Symbol, Hash[Symbol, bool]]
+    ) -> void
+
+    private
+
+    def nil_as_valid_value_checking?: -> bool
+  end
+end
+
+module BCDD::Result::Contract
+  class Evaluator
+    include Interface
+
+    attr_reader allowed_types: Set[Symbol]
+    attr_reader success: BCDD::Result::Contract::Interface
+    attr_reader failure: BCDD::Result::Contract::Interface
+
+    def initialize: (
+      BCDD::Result::Contract::Interface,
+      BCDD::Result::Contract::Interface
+    ) -> void
+
+    private
+
+    def for: (BCDD::Result::Data) -> BCDD::Result::Contract::Interface
+  end
+end

data/sig/bcdd/result/data.rbs

@@ -0,0 +1,16 @@
+class BCDD::Result
+  class Data
+    attr_reader kind: Symbol
+    attr_reader type: Symbol
+    attr_reader value: untyped
+    attr_reader to_h: Hash[Symbol, untyped]
+    attr_reader to_a: [Symbol, Symbol, untyped]
+
+    def initialize: (Symbol, Symbol, untyped) -> void
+
+    def inspect: -> String
+
+    alias to_ary to_a
+    alias to_hash to_h
+  end
+end

data/sig/bcdd/result/error.rbs

@@ -0,0 +1,31 @@
+class BCDD::Result
+  class Error < StandardError
+    def self.build: (**untyped) -> BCDD::Result::Error
+
+    class NotImplemented < BCDD::Result::Error
+    end
+
+    class MissingTypeArgument < BCDD::Result::Error
+    end
+
+    class UnexpectedOutcome < BCDD::Result::Error
+      def self.build: (outcome: untyped, origin: Symbol, ?expected: String)
+          -> BCDD::Result::Error::UnexpectedOutcome
+    end
+
+    class InvalidResultSubject < BCDD::Result::Error
+      def self.build: (given_result: BCDD::Result, expected_subject: untyped)
+          -> BCDD::Result::Error::InvalidResultSubject
+    end
+
+    class InvalidSubjectMethodArity < BCDD::Result::Error
+      def self.build: (subject: untyped, method: Method, max_arity: Integer)
+        -> BCDD::Result::Error::InvalidSubjectMethodArity
+    end
+
+    class UnhandledTypes < BCDD::Result::Error
+      def self.build: (types: Set[Symbol])
+        -> BCDD::Result::Error::UnhandledTypes
+    end
+  end
+end

data/sig/bcdd/result/expectations.rbs

@@ -0,0 +1,67 @@
+class BCDD::Result::Expectations
+  def self.mixin: (
+    ?config: Hash[Symbol, Hash[Symbol, bool]],
+    ?success: Hash[Symbol, untyped] | Array[Symbol],
+    ?failure: Hash[Symbol, untyped] | Array[Symbol]
+  ) -> Module
+
+  def self.mixin!: (
+    ?config: Hash[Symbol, Hash[Symbol, bool]],
+    ?success: Hash[Symbol, untyped] | Array[Symbol],
+    ?failure: Hash[Symbol, untyped] | Array[Symbol]
+  ) -> Module
+
+  def self.mixin_module: -> singleton(BCDD::Result::Expectations::Mixin)
+
+  def self.result_factory_without_expectations: -> singleton(BCDD::Result)
+
+  def self.new: (
+    ?subject: untyped,
+    ?contract: BCDD::Result::Contract::Evaluator,
+    ?halted: bool,
+    **untyped
+  ) -> (BCDD::Result::Expectations | untyped)
+
+  def initialize: (
+    ?subject: untyped,
+    ?contract: BCDD::Result::Contract::Evaluator,
+    ?halted: bool,
+    **untyped
+  ) -> void
+
+  def Success: (Symbol, ?untyped) -> BCDD::Result::Success
+  def Failure: (Symbol, ?untyped) -> BCDD::Result::Failure
+
+  def with: (subject: untyped) -> BCDD::Result::Expectations
+
+  private
+
+  def _ResultAs: (singleton(BCDD::Result), Symbol, untyped) -> untyped
+
+  attr_reader subject: untyped
+  attr_reader contract: BCDD::Result::Contract::Evaluator
+  attr_reader halted: bool
+end
+
+module BCDD::Result::Expectations::Mixin
+  module Factory
+    def self.module!: -> Module
+  end
+
+  module Methods
+    BASE: String
+    FACTORY: String
+
+    def self.to_eval: (Hash[Symbol, untyped]) -> String
+  end
+
+  module Addons
+    module Continuable
+      private def Continue: (untyped) -> BCDD::Result::Success
+    end
+
+    OPTIONS: Hash[Symbol, Module]
+
+    def self.options: (Hash[Symbol, Hash[Symbol, bool]]) -> Hash[Symbol, Module]
+  end
+end