fluxus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 53b87715576086932fa0632d366b8f17a9abb4790a7115777f2891795e4762bc
+  data.tar.gz: 0c1efd6a6a09618de16a27690c936ab6911a751b17f3943f637efcfb35a356e6
+SHA512:
+  metadata.gz: f833f3d13d02259e8e6fdb4a003e1af89e2a8a50ae85353122b1bd4a130723acb6a9c1dceacdf1d28692569cae032e0760757e2e1a4c4e8333abb1d94f6f0ec7
+  data.tar.gz: ff4fee21d2f14dc6feb32bd3c539643830df5e4d017b27d9edd60705ae468d4c38173133295ef3cfa9eb63ba0d799c07185ecdfab9bed730d2cb7c63f52aa709

data/.rubocop.yml

@@ -0,0 +1,16 @@
+AllCops:
+  TargetRubyVersion: 2.7
+
+Style/Documentation:
+  Enable: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/Gemfile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'rake', '~> 13.0'
+
+group :development, :test do
+  gem 'rubocop', '~> 1.21'
+
+  gem 'byebug', '~>  11'
+  gem 'pry', '~> 0.14'
+  gem 'pry-byebug', '~> 3.10'
+end
+
+group :test do
+  gem 'minitest', '~> 5'
+  gem 'simplecov', '~> 0.22'
+end
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,83 @@
+PATH
+  remote: .
+  specs:
+    fluxus (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    coveralls (0.7.2)
+      multi_json (~> 1.3)
+      rest-client (= 1.6.7)
+      simplecov (>= 0.7)
+      term-ansicolor (= 1.2.2)
+      thor (= 0.18.1)
+    docile (1.4.0)
+    json (2.6.1)
+    method_source (1.0.0)
+    mime-types (3.4.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2022.0105)
+    minitest (5.16.3)
+    multi_json (1.15.0)
+    parallel (1.22.1)
+    parser (3.2.0.0)
+      ast (~> 2.4.1)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.2)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rexml (3.2.5)
+    rubocop (1.44.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.24.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
+    thor (0.18.1)
+    tins (0.13.2)
+    unicode-display_width (2.4.2)
+
+PLATFORMS
+  arm64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  bundler
+  byebug (~> 11)
+  coveralls
+  fluxus!
+  minitest (~> 5)
+  pry (~> 0.14)
+  pry-byebug (~> 3.10)
+  rake (~> 13.0)
+  rubocop (~> 1.21)
+  simplecov (~> 0.22)
+
+BUNDLED WITH
+   2.3.7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Henrique Aparecido Lavezzo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,241 @@
+# Fluxus
+
+[![build](https://github.com/Rynaro/fluxus/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Rynaro/fluxus/actions/workflows/ci.yml)
+[![Maintainability](https://api.codeclimate.com/v1/badges/e86034a1a2fdc1e8e88b/maintainability)](https://codeclimate.com/github/Rynaro/fluxus/maintainability)
+
+
+Fluxus [[ˈfluːk.sus]](https://en.wiktionary.org/wiki/fluxus#Latin) is a simple way to bring use cases to your code. The library uses what Ruby can provide and a little taste of pure object-oriented concepts.
+
+_This library takes inspiration from the Clean Architecture concepts of use cases._
+
+_Some similarities with [dry-monads](https://github.com/dry-rb/dry-monads) and [u-case](https://github.com/serradura/u-case) can easily be perceived. This library operates to bring interoperability with them._
+
+## Installation
+
+You can add as your project as a dependency:
+
+```ruby
+gem 'fluxus'
+```
+
+## Usage
+
+An use case is a set of business instructions that will be carefully followed by the runtime code and its dependencies to achieve a great purpose. The level of complexity can vary, but _Fluxus_ is here to create readability and scope around it!
+
+_Fluxus_ always tries to deliver more from an object-oriented paradigm than from showing itself. This means _Fluxus_ is more about directions than dependency. And that's why we call our definition classes as `Fluxus::Object` and `Fluxus::SafeObject`.
+
+### Creating a basic Fluxus::Object
+
+```ruby
+class IsEven < Fluxus::Object
+    def call!(number)
+        return Failure(result: "#{number} is odd") if number.odd?
+
+        Success(result: "#{number} is even")
+    end
+end
+
+IsEven.call!(2)
+```
+
+### Creating a basic Fluxus::SafeObject
+
+```ruby
+class IsEven < Fluxus::SafeObject
+    def call!(number)
+        return Failure(result: "#{number} is odd") if number.odd?
+
+        Success(result: "#{number} is even")
+    end
+end
+
+IsEven.call!(2)
+```
+
+#### Differences of `Object` and `SafeObject`
+
+While `Fluxus::Object` preserves the actual Ruby code autonomy to dictate the flow breakers like error management. `SafeObject` stays in the middle and defines safe positions by respecting the `Fluxus` contract and delivering the `Fluxus::Results::Result` interface.
+
+This approach could be useful for some error recovery systems. Since the application will always recover from it by using the error as a dependency not a runtime flow control.
+
+
+---
+
+### The return `Flow::Results`
+
+The expected `Fluxus` contract expects a `Fluxus::Results::Result` interface compatible as a return value.
+
+While `Object` (and `SafeObject`) are responsible for delivering a place to hold the actual logic and control this code runtime. The `Results::Result` contract will be responsible for delivering back the necessary hooks and their processed data to the application.
+
+We natively support two kinds of `Fluxus::Results::Result` the `Success` and `Failure`. Using this idiom is closer to the natural conception of use cases, when they fail or are successful.
+
+#### Success
+
+```ruby
+Success(result: true)
+Success(type: :shinning, result: true)
+```
+
+#### Failure
+
+```ruby
+Failure(result: false)
+Failure(type: :dusty, result: false)
+
+```
+
+#### The `Fluxus::Results::Result` contract
+
+All results share the same (abstract) ancestor definitions which mean they are interchangeable. This brings more coherence in your code when you are handling the most crucial part of the flow, their results.
+
+The `Success` and `Failure` public contracts could be defined by
+
+```ruby
+success_object = Success(type: :ok, result: 1+1)
+
+success_object.success? # => true
+success_object.failure? # => false
+success_object.unknown? # => false
+
+success_object.type # => :ok
+success_object.data # => 2
+
+failure_object = Failure(type: :fail, result: 1-1)
+
+failure_object.success? # => false
+failure_object.failure? # => true
+failure_object.unknown? # => false
+
+failure_object.type # => :fail
+failure_object.data # => 0
+
+```
+
+#### The `result` and `data` relationship
+
+You already noticed the `Success` and `Failure` receiving `result:` but getting the data from `data`. In fact, inside the `Fluxus::Results::Result,` the actual contract handles `data` directly. But `result` is a wrapper defined by `Fluxus` to bring more meaning inside the use case concept.
+
+#### The `type` importance
+
+The `type` is a way to categorize the major events inside the use case. Your use case can hold a variety of `Success` and `Failure` and depend on how the business is defined different paths are taken.
+
+The `Fluxus` also defines a default value to bring simplicity to small use cases. The default value is `:ok` for `Success` and `:error` for `Failure`.
+
+Prefer using `symbols` for handling those types.
+
+#### Results are chainable
+
+Was described that `Fluxus::Results::Result` are responsible for handling the (obviously) result. This means, this also needs to control the post-use case without leaking data to the runtime void.
+
+With this in mind, the Result implements **chainable** methods. You can call them hooks if you wish.
+
+Each hook represents one of the expected states.
+
+```ruby
+Fluxus::Results::Result#on_success
+Fluxus::Results::Result#on_failure
+Fluxus::Results::Result#on_exception
+```
+
+The `on_exception` is a contract for `SafeObject`, but they are basically a `Failure` with a specialized eye for `Exception` looking.
+
+#### Hooks are blocks
+
+All hooks are essentially blocks, and `data` is available there. This means, you can define the code routine that will handle the `data`, and `data` is immutable. Each hook handles its own version of `data`, and this belongs there.
+
+#### Hooks respect `self`
+
+All hook implementation preserves the `Success` or `Failure` instance. And this brings a powerful feature to your pipeline. Use cases can chain various conclusions.
+
+
+
+---
+
+## Compiling the knowledge
+
+Using the `IsEven` simple use case, let's implement a fully covered `Fluxus::Object`, so you can fully understand how to build your own use cases.
+
+### Basic flow
+
+```ruby
+class IsEven < Fluxus::Object
+    def call!(number)
+        return Failure(result: "#{number} is odd") if number.odd?
+
+        Success(result: "#{number} is even")
+    end
+end
+
+def my_use_case(number)
+    IsEven
+        .call!(number)
+        .on_success { |data| puts data << '!' }
+        .on_failure { |data| puts 'Why? ' << data }
+end
+
+my_use_case(2) #=> 2 is even!
+my_use_case(3) #=> Why? 3 is odd
+my_use_case(nil) #=> NoMethodError
+```
+
+### Scoped Results flow
+
+```ruby
+class IsEven < Fluxus::Object
+    def call!(number)
+        return Failure(type: :zero, result: 'you got zero') if number.zero?
+        return Failure(type: :odd, result: "#{number} is odd") if number.odd?
+
+        Success(type: :even, result: "#{number} is even")
+    end
+end
+
+def my_use_case(number)
+    IsEven
+        .call!(number)
+        .on_success(:even) { |data| p data << '!' }
+        .on_failure(:odd) { |data| p 'Why? ' << data }
+        .on_failure(:zero) { |data| p data }
+end
+
+my_use_case(0) #=> you got zero
+my_use_case(2) #=> 2 is even!
+my_use_case(3) #=> Why? 3 is odd
+my_use_case(nil) #=> NoMethodError
+```
+
+### Safe Results flow
+
+```ruby
+class IsEven < Fluxus::SafeObject
+    def call!(number)
+        return Failure(type: :zero, result: 'you got zero') if number.zero?
+        return Failure(type: :odd, result: "#{number} is odd") if number.odd?
+
+        Success(type: :even, result: "#{number} is even")
+    end
+end
+
+def my_use_case(number)
+    IsEven
+        .call!(number)
+        .on_success(:even) { |data| p data << '!' }
+        .on_failure(:odd) { |data| p 'Why? ' << data }
+        .on_failure(:zero) { |data| p data }
+        .on_exception(NoMethodError) { |data| p  }
+end
+
+my_use_case(0) #=> you got zero
+my_use_case(2) #=> 2 is even!
+my_use_case(3) #=> Why? 3 is odd
+my_use_case(nil) #=> Failure with exception: data
+```
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Rynaro/fluxus.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/fluxus/caller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'fluxus/runner'
+
+module Fluxus
+  class Caller < Runner
+    def self.call!(...)
+      __call__(new, ...)
+    end
+  end
+end

data/lib/fluxus/results/chainable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Fluxus
+  module Results
+    module Chainable
+      def on_success(expected_type = nil)
+        yield(data) if __success_type?(expected_type)
+        self
+      end
+
+      def on_failure(expected_type = nil)
+        yield(data) if __failure_type?(expected_type)
+        self
+      end
+
+      def on_exception(expected_exception = nil)
+        return self unless __failure_type?(:exception)
+
+        if expected_exception.nil? ||
+           (expected_exception.is_a?(Exception) && data[:exception].is_a?(expected_exception))
+          yield(data)
+        end
+        self
+      end
+
+      def __success_type?(expected_type)
+        success? && (expected_type.nil? || expected_type == type)
+      end
+
+      def __failure_type?(expected_type = nil)
+        failure? && (expected_type.nil? || expected_type == type)
+      end
+    end
+  end
+end

data/lib/fluxus/results/failure.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'fluxus/results/result'
+
+module Fluxus
+  module Results
+    class Failure < Result
+      private
+
+      def define_state
+        :failure
+      end
+    end
+  end
+end

data/lib/fluxus/results/result.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Fluxus
+  module Results
+    require 'fluxus/results/chainable'
+
+    class Result
+      include Chainable
+      attr_reader :type, :data
+
+      class StateNotImplemented < StandardError; end
+
+      def initialize(type: :unknown, data: {})
+        @type = type
+        @data = data
+        @state = define_state
+      end
+
+      def success?
+        state == :success
+      end
+
+      def failure?
+        state == :failure
+      end
+
+      def unknown?
+        !(failure? || success?)
+      end
+
+      private
+
+      attr_reader :state
+
+      def define_state
+        raise StateNotImplemented, 'the #define_state hook must be implemented by a concrete class'
+      end
+    end
+  end
+end

data/lib/fluxus/results/success.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'fluxus/results/result'
+
+module Fluxus
+  module Results
+    class Success < Result
+      private
+
+      def define_state
+        :success
+      end
+    end
+  end
+end

data/lib/fluxus/runner.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Fluxus
+  require 'fluxus/results/success'
+  require 'fluxus/results/failure'
+
+  class Runner
+    class ResultTypeNotDefinedError < StandardError; end
+    class CallerNotImplemented < StandardError; end
+
+    private_class_method :new
+
+    def self.call!(...)
+      raise CallerNotImplemented, 'the flow must be implemented by a caller'
+    end
+
+    def self.__call__(instance, ...)
+      result = instance.call!(...)
+      raise ResultTypeNotDefinedError, 'flow results must be Success or Failure' unless result.is_a?(Results::Result)
+
+      result
+    end
+    private_class_method :__call__
+
+    def call!
+      raise NotImplementedError, '#call! must be implemented'
+    end
+
+    # rubocop:disable Naming/MethodName
+    def Success(type: :ok, result: nil)
+      @__result = Results::Success.new(type: type, data: result)
+    end
+
+    def Failure(type: :error, result: nil)
+      @__result = Results::Failure.new(type: type, data: result)
+    end
+    # rubocop:enable Naming/MethodName
+
+    private
+
+    attr_reader :__result
+  end
+end

data/lib/fluxus/safe/caller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'fluxus/runner'
+
+module Fluxus
+  module Safe
+    class Caller < Runner
+      def self.call!(...)
+        instance = new
+        __call__(instance, ...)
+      rescue StandardError => e
+        raise e if e.is_a?(ResultTypeNotDefinedError)
+
+        instance.Failure(type: :exception, result: { exception: e })
+      end
+    end
+  end
+end

data/lib/fluxus/version.rb

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

data/lib/fluxus.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'fluxus/version'
+require 'fluxus/caller'
+require 'fluxus/safe/caller'
+
+module Fluxus
+  Object = Caller
+  SafeObject = Safe::Caller
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: fluxus
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Henrique Aparecido Lavezzo
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2023-02-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  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: Really simple fluxus objects for use cases.
+email:
+- hi@hlavezzo.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/fluxus.rb
+- lib/fluxus/caller.rb
+- lib/fluxus/results/chainable.rb
+- lib/fluxus/results/failure.rb
+- lib/fluxus/results/result.rb
+- lib/fluxus/results/success.rb
+- lib/fluxus/runner.rb
+- lib/fluxus/safe/caller.rb
+- lib/fluxus/version.rb
+homepage: https://github.com/Rynaro/fluxus
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Rynaro/fluxus
+  source_code_uri: https://github.com/Rynaro/fluxus
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key: 
+specification_version: 4
+summary: Simple use case objects
+test_files: []