bcdd-result 0.3.0 → 0.5.0

data/lib/bcdd/result.rb

@@ -2,26 +2,38 @@
 
 require_relative 'result/version'
 require_relative 'result/error'
-require_relative 'result/type'
+require_relative 'result/data'
 require_relative 'result/handler'
 require_relative 'result/failure'
 require_relative 'result/success'
-
-require_relative 'resultable'
+require_relative 'result/mixin'
+require_relative 'result/expectations'
 
 class BCDD::Result
-  attr_reader :_type, :value, :subject
+  attr_accessor :unknown
+
+  attr_reader :subject, :data, :type_checker
 
   protected :subject
 
-  def initialize(type:, value:, subject: nil)
-    @_type = Type.new(type)
-    @value = value
+  private :unknown, :unknown=, :type_checker
+
+  def initialize(type:, value:, subject: nil, expectations: nil)
+    data = Data.new(name, type, value)
+
+    @type_checker = Expectations.evaluate(data, expectations)
     @subject = subject
+    @data = data
+
+    self.unknown = true
   end
 
   def type
-    _type.to_sym
+    data.type
+  end
+
+  def value
+    data.value
   end
 
   def success?(_type = nil)
@@ -36,31 +48,22 @@ class BCDD::Result
     raise Error::NotImplemented
   end
 
-  def ==(other)
-    self.class == other.class && type == other.type && value == other.value
-  end
-  alias eql? ==
-
-  def hash
-    [self.class, type, value].hash
-  end
+  def on(*types, &block)
+    raise Error::MissingTypeArgument if types.empty?
 
-  def inspect
-    format('#<%<class_name>s type=%<type>p value=%<value>p>', class_name: self.class.name, type: type, value: value)
+    tap { known(block) if type_checker.allow?(types) }
   end
 
-  def on(*types)
-    raise Error::MissingTypeArgument if types.empty?
-
-    tap { yield(value, type) if _type.in?(types, allow_empty: false) }
+  def on_success(*types, &block)
+    tap { known(block) if type_checker.allow_success?(types) && success? }
   end
 
-  def on_success(*types)
-    tap { yield(value, type) if success? && _type.in?(types, allow_empty: true) }
+  def on_failure(*types, &block)
+    tap { known(block) if type_checker.allow_failure?(types) && failure? }
   end
 
-  def on_failure(*types)
-    tap { yield(value, type) if failure? && _type.in?(types, allow_empty: true) }
+  def on_unknown
+    tap { yield(value, type) if unknown }
   end
 
   def and_then(method_name = nil)
@@ -74,19 +77,48 @@ class BCDD::Result
   end
 
   def handle
-    handler = Handler.new(self)
+    handler = Handler.new(self, type_checker: type_checker)
 
     yield handler
 
     handler.send(:outcome)
   end
 
-  alias data value
-  alias data_or value_or
+  def ==(other)
+    self.class == other.class && type == other.type && value == other.value
+  end
+
+  def hash
+    [self.class, type, value].hash
+  end
+
+  def inspect
+    format('#<%<class_name>s type=%<type>p value=%<value>p>', class_name: self.class.name, type: type, value: value)
+  end
+
+  def deconstruct
+    [type, value]
+  end
+
+  def deconstruct_keys(_keys)
+    { name => { type => value } }
+  end
+
+  alias eql? ==
   alias on_type on
 
   private
 
+  def name
+    :unknown
+  end
+
+  def known(block)
+    self.unknown = false
+
+    block.call(value, type)
+  end
+
   def call_subject_method(method_name)
     method = subject.method(method_name)
 

data/lib/result.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'bcdd/result'
+
+Object.const_set(:Result, BCDD::Result)

data/sig/bcdd/result.rbs

@@ -5,40 +5,50 @@ module BCDD
 end
 
 class BCDD::Result
-  attr_reader _type: BCDD::Result::Type
-  attr_reader value: untyped
+  private attr_accessor unknown: bool
+  private attr_reader type_checker: BCDD::Result::Expectations::TypeChecker
+
+  attr_reader data: BCDD::Result::Data
   attr_reader subject: untyped
 
-  def initialize: (type: Symbol, value: untyped, ?subject: untyped) -> void
+  def initialize: (
+    type: Symbol,
+    value: untyped,
+    ?subject: untyped,
+    ?expectations: BCDD::Result::Expectations::Contract::Evaluator
+  ) -> void
 
   def type: -> Symbol
+  def value: -> untyped
 
   def success?: (?Symbol type) -> bool
   def failure?: (?Symbol type) -> bool
 
   def value_or: { () -> untyped } -> untyped
 
-  def ==: (untyped) -> bool
-  alias eql? ==
-
-  def hash: -> Integer
-
-  def inspect: -> String
-
   def on: (*Symbol) { (untyped, Symbol) -> void } -> BCDD::Result
   def on_success: (*Symbol) { (untyped, Symbol) -> void } -> BCDD::Result
   def on_failure: (*Symbol) { (untyped, Symbol) -> void } -> BCDD::Result
+  def on_unknown: () { (untyped, Symbol) -> void } -> BCDD::Result
 
   def and_then: (?Symbol method_name) { (untyped) -> untyped } -> BCDD::Result
 
-  def handle: { (BCDD::Result::Handler) -> void } -> untyped
+  def handle: () { (BCDD::Result::Handler) -> void } -> untyped
 
-  alias data value
-  alias data_or value_or
+  def ==: (untyped) -> bool
+  def hash: -> Integer
+  def inspect: -> String
+
+  def deconstruct: -> [Symbol, [Symbol, untyped]]
+  def deconstruct_keys: (Array[Symbol]) -> Hash[Symbol, Hash[Symbol, untyped]]
+
+  alias eql? ==
   alias on_type on
 
   private
 
+  def name: -> Symbol
+  def known: (Proc) -> untyped
   def call_subject_method: (Symbol) -> BCDD::Result
   def ensure_result_object: (untyped, origin: Symbol) -> BCDD::Result
 end
@@ -58,32 +68,7 @@ class BCDD::Result
 end
 
 class BCDD::Result
-  class Handler
-    UNDEFINED: Object
-
-    def initialize: (BCDD::Result) -> void
-
-    def []: (*Symbol) { (untyped, Symbol) -> void } -> untyped
-    def failure: (*Symbol) { (untyped, Symbol) -> void } -> untyped
-    def success: (*Symbol) { (untyped, Symbol) -> void } -> untyped
-
-    alias type []
-
-    private
-
-    attr_reader _type: BCDD::Result::Type
-    attr_reader result: BCDD::Result
-
-    def outcome?: -> bool
-
-    def outcome: -> untyped
-
-    def outcome=: (Proc) -> void
-  end
-end
-
-module BCDD
-  module Resultable
+  module Mixin
     def Success: (Symbol type, ?untyped value) -> BCDD::Result::Success
 
     def Failure: (Symbol type, ?untyped value) -> BCDD::Result::Failure
@@ -91,12 +76,19 @@ module BCDD
 end
 
 class BCDD::Result
-  class Type
-    attr_reader to_sym: Symbol
+  class Data
+    attr_reader name: 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 initialize: (Symbol) -> void
+    def inspect: -> String
 
-    def in?: (Array[Symbol], allow_empty: bool) -> bool
+    alias to_ary to_a
+    alias to_hash to_h
   end
 end
 
@@ -124,5 +116,194 @@ class BCDD::Result
       def self.build: (subject: untyped, method: ::Method)
         -> BCDD::Result::Error::WrongSubjectMethodArity
     end
+
+    class UnhandledTypes < BCDD::Result::Error
+      def self.build: (types: Set[Symbol])
+        -> BCDD::Result::Error::UnhandledTypes
+    end
+  end
+end
+
+class BCDD::Result
+  class Handler
+    UNDEFINED: Object
+
+    def initialize: (
+      BCDD::Result,
+      type_checker: BCDD::Result::Expectations::TypeChecker
+    ) -> void
+
+    def []: (*Symbol) { (untyped, Symbol) -> void } -> untyped
+    def failure: (*Symbol) { (untyped, Symbol) -> void } -> untyped
+    def success: (*Symbol) { (untyped, Symbol) -> void } -> untyped
+    def unknown: () { (untyped, Symbol) -> void } -> untyped
+
+    alias type []
+
+    private
+
+    attr_reader result: BCDD::Result
+    attr_reader allowed_types: BCDD::Result::Handler::AllowedTypes
+
+    def outcome?: -> bool
+    def outcome=: (Proc) -> void
+    def outcome: -> untyped
+  end
+end
+
+class BCDD::Result::Handler
+  class AllowedTypes
+    attr_reader unchecked: Set[Symbol]
+    attr_reader type_checker: BCDD::Result::Expectations::TypeChecker
+
+    def initialize: (
+      BCDD::Result::Expectations::TypeChecker
+    ) -> void
+
+    def allow?: (Array[Symbol]) -> bool
+    def allow_success?: (Array[Symbol]) -> bool
+    def allow_failure?: (Array[Symbol]) -> bool
+
+    def all_checked?: -> bool
+
+    private
+
+    def check!: (Array[Symbol], bool) -> bool
+  end
+end
+
+class BCDD::Result::Expectations
+  MIXIN_METHODS: String
+
+  def self.mixin: (
+    ?success: Hash[Symbol, untyped] | Array[Symbol],
+    ?failure: Hash[Symbol, untyped] | Array[Symbol]
+  ) -> Module
+
+  def self.evaluate: (
+    BCDD::Result::Data,
+    BCDD::Result::Expectations::Contract::Evaluator
+  ) -> BCDD::Result::Expectations::TypeChecker
+
+  def initialize: (
+    ?subject: untyped,
+    ?success: Hash[Symbol, untyped] | Array[Symbol],
+    ?failure: Hash[Symbol, untyped] | Array[Symbol],
+    ?contract: BCDD::Result::Expectations::Contract::Evaluator
+  ) -> void
+
+  def Success: (Symbol, ?untyped) -> BCDD::Result::Success
+  def Failure: (Symbol, ?untyped) -> BCDD::Result::Failure
+
+  private
+
+  attr_reader subject: untyped
+  attr_reader contract: BCDD::Result::Expectations::Contract::Evaluator
+end
+
+module BCDD::Result::Expectations::Contract
+  NONE: BCDD::Result::Expectations::Contract::Evaluator
+
+  ToEnsure: ^(Hash[Symbol, untyped] | Array[Symbol])
+    -> BCDD::Result::Expectations::Contract::Evaluator
+
+  def self.new: (
+    success: Hash[Symbol, untyped] | Array[Symbol],
+    failure: Hash[Symbol, untyped] | Array[Symbol]
+  ) -> BCDD::Result::Expectations::Contract::Evaluator
+end
+
+class BCDD::Result::Expectations
+  class TypeChecker
+    attr_reader result_type: Symbol
+    attr_reader expectations: BCDD::Result::Expectations::Contract::Evaluator
+
+    def initialize: (
+      Symbol,
+      expectations: BCDD::Result::Expectations::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::Expectations::Contract::Interface,
+      allow_empty: bool
+    ) -> bool
+  end
+end
+
+class BCDD::Result::Expectations::Error < BCDD::Result::Error
+  class UnexpectedType < BCDD::Result::Expectations::Error
+    def self.build: (type: Symbol, allowed_types: Set[Symbol])
+        -> BCDD::Result::Expectations::Error::UnexpectedType
+  end
+
+  class UnexpectedValue < BCDD::Result::Expectations::Error
+    def self.build: (type: Symbol, value: untyped)
+      -> BCDD::Result::Expectations::Error::UnexpectedValue
+  end
+end
+
+module BCDD::Result::Expectations::Contract
+  module Interface
+    def ==: (BCDD::Result::Expectations::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::Expectations::Contract
+  module Disabled
+    extend Interface
+
+    EMPTY_SET: Set[Symbol]
+  end
+end
+
+module BCDD::Result::Expectations::Contract
+  class ForTypes
+    include Interface
+
+    def initialize: (Array[Symbol]) -> void
+  end
+end
+
+module BCDD::Result::Expectations::Contract
+  class ForTypesAndValues
+    include Interface
+
+    def initialize: (Hash[Symbol, untyped]) -> void
+  end
+end
+
+module BCDD::Result::Expectations::Contract
+  class Evaluator
+    include Interface
+
+    attr_reader allowed_types: Set[Symbol]
+    attr_reader success: BCDD::Result::Expectations::Contract::Interface
+    attr_reader failure: BCDD::Result::Expectations::Contract::Interface
+
+    def initialize: (
+      BCDD::Result::Expectations::Contract::Interface,
+      BCDD::Result::Expectations::Contract::Interface
+    ) -> void
+
+    private
+
+    def for: (BCDD::Result::Data) -> BCDD::Result::Expectations::Contract::Interface
   end
 end

metadata

@@ -1,17 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: bcdd-result
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Rodrigo Serradura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-27 00:00:00.000000000 Z
+date: 2023-10-10 00:00:00.000000000 Z
 dependencies: []
-description: A general-purpose result monad that allows you to create objects that
-  represent a success (BCDD::Result::Success) or failure (BCDD::Result::Failure).
+description: |-
+  Empower Ruby apps with a pragmatic use of Railway Oriented Programming.
+
+  It's a general-purpose result monad that allows you to create objects representing a success (BCDD::Result::Success) or failure (BCDD::Result::Failure).
 email:
 - rodrigo.serradura@gmail.com
 executables: []
@@ -27,13 +29,24 @@ files:
 - Rakefile
 - Steepfile
 - lib/bcdd/result.rb
+- lib/bcdd/result/data.rb
 - lib/bcdd/result/error.rb
+- lib/bcdd/result/expectations.rb
+- lib/bcdd/result/expectations/contract.rb
+- lib/bcdd/result/expectations/contract/disabled.rb
+- lib/bcdd/result/expectations/contract/evaluator.rb
+- lib/bcdd/result/expectations/contract/for_types.rb
+- lib/bcdd/result/expectations/contract/for_types_and_values.rb
+- lib/bcdd/result/expectations/contract/interface.rb
+- lib/bcdd/result/expectations/error.rb
+- lib/bcdd/result/expectations/type_checker.rb
 - lib/bcdd/result/failure.rb
 - lib/bcdd/result/handler.rb
+- lib/bcdd/result/handler/allowed_types.rb
+- lib/bcdd/result/mixin.rb
 - lib/bcdd/result/success.rb
-- lib/bcdd/result/type.rb
 - lib/bcdd/result/version.rb
-- lib/bcdd/resultable.rb
+- lib/result.rb
 - sig/bcdd/result.rbs
 homepage: https://github.com/b-cdd/result
 licenses:
@@ -62,5 +75,5 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: A result abstraction (monad based) for Ruby.
+summary: A pragmatic result abstraction (monad based) for Ruby.
 test_files: []

data/lib/bcdd/result/type.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-class BCDD::Result
-  class Type
-    attr_reader :to_sym
-
-    def initialize(type)
-      @to_sym = type.to_sym
-    end
-
-    def in?(types, allow_empty: false)
-      (allow_empty && types.empty?) || types.any?(to_sym)
-    end
-  end
-
-  private_constant :Type
-end

data/lib/bcdd/resultable.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module BCDD::Resultable
-  def Success(type, value = nil)
-    BCDD::Result::Success.new(type: type, value: value, subject: self)
-  end
-
-  def Failure(type, value = nil)
-    BCDD::Result::Failure.new(type: type, value: value, subject: self)
-  end
-end