crossbeam 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3e5a2f8df4b98114b1f734e78e22332078ea4f9f933fea9fe745f4113e1dab9
+  data.tar.gz: aae8768c3bd775c9e0939ae73b738b0ae2b00f50e2c1719116870f15e7fb3da4
+SHA512:
+  metadata.gz: 0c9c6b21bcf8058137a42317c0e18b24ec6cb9aaeb06ad34dacd318c38931c29bed9d657e66390f41e2df3462dbb5fd955c5438d3c6f10603bb94429099b0888
+  data.tar.gz: 80d02b81f62a3d9670802576cb27794050925ef15335b9b2472816813d5ba83286147855596c5ad73a388c7a9c4193c7ba894d5e873353a5a03f6e2988e2f6c5

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2022-06-18
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Brandon Hicks
+
+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,300 @@
+# Crossbeam
+
+Crossbeam is a gem to making it easy to create and run ruby service objects. It allows you to use validations, errors, etc to take away the troubles associated with service classes.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```shell
+bundle add crossbeam
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```shell
+gem install crossbeam
+```
+
+## Usage
+
+In order to too use the Crossbeam service class you will need to add `include Crossbeam` to the class you wish to make a service object.
+
+### Initializers
+
+You can call and initialize a Crossbeam service call like any other ruby object and 
+
+```ruby
+class ServiceClass
+  include Crossbeam
+
+  def initialize(name, age, other: nil)
+    @age = age
+    @name = name
+    @other = other
+  end
+
+  def call
+    do_something
+  end
+
+  private
+
+  def do_something
+    # .....
+  end
+end
+
+# Calling the service class
+ServiceClass.call('James', 12)
+```
+
+Crossbeam also includes [dry-initializer], which allows you to quickly initialize object parameters.
+This allows you to bypass having to setup an initialize method in order to assign all attributes to instance variables.
+
+```ruby
+class OtherService
+  include Crossbeam
+
+  param :name, proc(&:to_s)
+  param :age, proc(&:to_i)
+  option :other, default: proc { nil }
+
+  def call
+    do_something
+  end
+
+  private
+
+  def do_something
+    # .....
+    return "#{@name} is a minor" if @age < 18
+
+    "#{@name} is #{@age}"
+  end
+end
+
+# Calling the service class
+OtherService.call('James', 12)
+```
+
+### Output
+
+If you want skip assigning the last attribute returned from call to results you can specify a specific attribute to result reference after `#call` has been ran. This can be done by assigning an attribute to be assigned as the results with `output :attribute_name`.
+
+```ruby
+class OutputSample
+  include Crossbeam
+
+  param  :name, proc(&:to_s)
+  param  :age, default: proc { 10 }
+
+  # Attribute/Instance Variable to return
+  output :age
+
+  def call
+    @age += 1
+    "Hello, #{name}! You are #{age} years old."
+  end
+end
+
+output = OutputSample.call('James', 12)
+output.results
+```
+
+### Callbacks
+
+Similar to Rails actions or models Crossbeam allows you to have before/after callbacks for before `call` is ran. They are completely optional and either one can be used without the other. They before/after references can either by a symbol or a block.
+
+```ruby
+class SampleClass
+  include Crossbeam
+
+  # Callbacks that will be called before/after #call is referenced
+  before do
+    # setup for #call
+  end
+
+  after :cleanup_script
+
+  def call
+    # .....
+  end
+
+  private
+
+  def cleanup_script
+    # .....
+  end
+end
+
+SampleClass.call
+```
+
+### Errors and Validations
+
+#### Errors
+
+```ruby
+class ErrorClass
+  include Crossbeam
+
+  def initialize(name, age)
+    @name = name
+    @age = age
+  end
+
+  def call
+    errors.add(:age, "#{@name} is a minor") if @age < 18
+    errors.add(:base, 'something something something')
+  end
+end
+
+test = ErrorClass.call('James', 10)
+test.errors
+# => {:age=>["James is a minor"], :base=>["something something something"]}
+test.errors.full_messages
+# => ["Age James is a minor", "something something something"]
+test.errors.to_s
+# => Age James is a minor
+# => something something something
+```
+
+#### Validations
+
+```ruby
+require_relative 'crossbeam'
+
+class AgeCheck
+  include Crossbeam
+
+  option :age, default: proc { 0 }
+
+  validates :age, numericality: { greater_than_or_equal_to: 18, less_than_or_equal_to: 65 }
+
+  def call
+    return 'Minor' unless valid?
+
+    'Adult'
+  end
+end
+
+puts AgeCheck.call(age: 15).errors.full_messages
+# => ["Age must be greater than or equal to 18"]
+puts AgeCheck.call(age: 20).results
+# => Adult
+```
+
+```ruby
+require_relative 'crossbeam'
+
+class Bar
+  include Crossbeam
+
+  option :age, default: proc { 0 }
+  option :drink
+  option :description, default: proc { '' }
+
+  validates :age, numericality: { greater_than_or_equal_to: 21, less_than_or_equal_to: 65 }
+  validates :drink, inclusion: { in: %w(beer wine whiskey) }
+  validates :description, length: { minimum: 7, message: 'is required' }
+
+  def call
+    return 'Minor' unless valid?
+
+    'Adult'
+  end
+end
+
+after_hours = Bar.call(age: 15, drink: 'tran')
+puts after_hours.errors.full_messages if after_hours.errors?
+# => Age must be greater than or equal to 21
+# => Drink is not included in the list
+# => Description is required
+```
+
+### Fail
+
+If a particular condition is come across you may want to cause a service call to fail. This causes any further action within the service call to not be called and the classes result to be set as nil.
+
+```ruby
+class Something
+  include Crossbeam
+
+  def call
+    fail!('1 is less than 2') unless 1 > 2
+
+    true
+  end
+end
+
+test = Something.call
+test.failure? # => true
+puts test.errors.full_messages # => ['1 is less than 2']
+test.result # => nil
+```
+
+When calling `fail!` you need to supply a message/context very similar to an exception description. And when the service call is forced to fail no results should be returned.
+
+### Generators (Rails)
+
+The Crossbeam service class generator is only available when used with a rails application.
+
+When running the generator you will specify the class name for the service object.
+
+```shell
+rails g crossbeam AgeCheck
+```
+
+Running this will generate a file `app/services/age_check.rb` with the following contents
+
+```ruby
+# frozen_string_literal: true
+
+class AgeCheck
+  include Crossbeam
+
+  def call
+    # ...
+  end
+end
+```
+
+You can also specify attributes that you want use with the class.
+
+`rails g crossbeam IdentityCheck address age dob name`
+
+```ruby
+class IdentityCheck
+  include Crossbeam
+
+  option :address
+  option :age
+  option :dob
+  option :name
+
+  def call
+    # ...
+  end
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/tarellel/crossbeam.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+This project is intended to be a safe, welcoming space for collaboration, and everyone interacting in the project’s codebase and issue tracker is expected to adhere to the [Contributor Covenant code of conduct](https://github.com/tarellel/crossbeam/main/CODE_OF_CONDUCT.md).
+
+## Inspired by
+
+* [Actor](https://github.com/sunny/actor)
+* [Callee](https://github.com/dreikanter/callee)
+* [CivilService](https://github.com/actblue/civil_service)
+* [SimpleCommand](https://github.com/nebulab/simple_command)
+* [u-case](https://github.com/serradura/u-case)
+
+[dry-initializer]: <https://github.com/dry-rb/dry-initializer>

data/defs.rbi

@@ -0,0 +1,294 @@
+# typed: strong
+# Crossbeam module to include with your service classes
+module Crossbeam
+  VERSION = T.let('0.1.0', T.untyped)
+
+  # Used to include/extend modules into the current class
+  # 
+  # _@param_ `base`
+  sig { params(base: Object).void }
+  def self.included(base); end
+
+  # Force the job to raise an exception and stop the rest of the service call
+  # 
+  # _@param_ `error`
+  sig { params(error: String).void }
+  def fail!(error); end
+
+  # Used to return a list of errors for the current call
+  sig { returns(T::Hash[T.untyped, T.untyped]) }
+  def errors; end
+
+  # Methods to load in the service object as class methods
+  module ClassMethods
+    # Used to initiate and service call
+    # 
+    # _@param_ `params`
+    # 
+    # _@param_ `options`
+    sig { params(params: T::Array[Object], options: T::Hash[Symbol, Object], block: T.untyped).returns(T.any(Struct, Object)) }
+    def call(*params, **options, &block); end
+
+    # Call the klass's before/after callbacks, process errors, and call @klass
+    sig { params(block: T.untyped).void }
+    def run_callbacks_and_klass(&block); end
+
+    # Process the error that was thrown by the object call
+    # 
+    # _@param_ `error` — error generated by the object call
+    sig { params(error: Object).returns(T.any(Object, Crossbeam::Result)) }
+    def process_error(error); end
+  end
+
+  # Error message that is raised to flag a Crossbeam service error
+  #   used to create error messages for Crossbeam
+  # @private
+  class Error < StandardError
+    # Used to initializee an error message
+    # 
+    # _@param_ `context`
+    sig { params(context: T.nilable(T.any(String, T::Hash[T.untyped, T.untyped]))).void }
+    def initialize(context = nil); end
+
+    # _@return_ — Error message associated with StandardError
+    sig { returns(String) }
+    attr_reader :context
+  end
+
+  # Used to generate `ArguementError` exception
+  # @private
+  class ArguementError < Crossbeam::Error
+  end
+
+  # Used to generate `Failure` exception
+  # @private
+  class Failure < Crossbeam::Error
+  end
+
+  # Used to generate `NotImplementedError` exception
+  # @private
+  class NotImplementedError < Crossbeam::Error
+  end
+
+  # Used to generate `UndefinedMethod` exception
+  # @private
+  class UndefinedMethod < Crossbeam::Error
+  end
+
+  # Used to allow adding errors to the service call similar to ActiveRecord errors
+  class Errors < Hash
+    # Add an error to the list of errors
+    # 
+    # _@param_ `key` — the key/attribute for the error. (Usually ends up being :base)
+    # 
+    # _@param_ `value` — a description of the error
+    # 
+    # _@param_ `_opts` — additional attributes that get ignored
+    sig { params(key: T.any(String, Symbol), value: T.any(String, Symbol), _opts: T::Hash[T.untyped, T.untyped]).returns(T::Hash[T.untyped, T.untyped]) }
+    def add(key, value, _opts = {}); end
+
+    # Add multiple errors to the error hash
+    # 
+    # _@param_ `errors`
+    # 
+    # _@return_ — , Array]
+    sig { params(errors: T::Hash[String, Symbol]).returns(T::Hash[T.untyped, T.untyped]) }
+    def add_multiple_errors(errors); end
+
+    # Look through and return a list of all errorr messages
+    sig { returns(T.any(T::Hash[T.untyped, T.untyped], T::Array[T.untyped])) }
+    def each; end
+
+    # Return a full list of error messages
+    sig { returns(T::Array[String]) }
+    def full_messages; end
+
+    # Used to convert the list of errors to a string
+    sig { returns(String) }
+    def to_s; end
+
+    # Convert the message to a full error message
+    # 
+    # _@param_ `attribute`
+    # 
+    # _@param_ `message`
+    sig { params(attribute: T.any(String, Symbol), message: String).returns(String) }
+    def full_message(attribute, message); end
+  end
+
+  # For forcing specific output after `#call`
+  module Output
+    # Used to include/extend modules into the current class
+    # 
+    # _@param_ `base`
+    sig { params(base: Object).void }
+    def self.included(base); end
+
+    # Methods to load in the service object as class methods
+    module ClassMethods
+      CB_ALLOWED_OUTPUTS = T.let([NilClass, String, Symbol].freeze, T.untyped)
+
+      # Used to specify an attribute/instance variable that should be used too return instead of @result
+      # 
+      # _@param_ `param`
+      sig { params(param: T.any(String, Symbol)).returns(T.any(String, Symbol)) }
+      def output(param); end
+
+      # Determine if the output attribute type is allowed
+      # 
+      # _@param_ `output_type`
+      sig { params(output_type: String).returns(T::Boolean) }
+      def allowed_output?(output_type); end
+
+      # Used to determine if a output parameter has been set or not
+      sig { returns(T::Boolean) }
+      def output?; end
+
+      # Determine the output to return if the instance_variable exists in the klass
+      sig { returns(T::Hash[T.untyped, T.untyped]) }
+      def set_results_output; end
+
+      # Add errors to @result.errors
+      sig { void }
+      def build_error_list; end
+
+      # Reassign result, unless errors
+      sig { void }
+      def reassign_results; end
+
+      # Does the klass have an assigned output
+      sig { returns(T::Boolean) }
+      def specified_output?; end
+
+      # Used hold the parameter which can/will be used instead of @result
+      sig { returns(T.nilable(T.any(String, Symbol))) }
+      def output_param; end
+    end
+  end
+
+  # Used as a data container to hold a service calls results, errors, etc.
+  # class Result < Struct.new(:called, :errors, :failure, :results)
+  class Result < Struct
+    # Used to initialize a service calls results, errors, and stats
+    # 
+    # _@param_ `called`
+    # 
+    # _@param_ `errors`
+    # 
+    # _@param_ `failure`
+    # 
+    # _@param_ `results`
+    sig do
+      params(
+        called: T::Boolean,
+        errors: T.nilable(T::Hash[T.untyped, T.untyped]),
+        failure: T::Boolean,
+        results: T.nilable(Object)
+      ).void
+    end
+    def initialize(called: false, errors: nil, failure: false, results: nil); end
+
+    # The serivce can't officially be a failure/pass if it hasn't been "called"
+    sig { returns(T::Boolean) }
+    def called?; end
+
+    # Determine if the service call has any errors
+    sig { returns(T::Boolean) }
+    def errors?; end
+
+    # Determine if the service call has failed to uccessfully complete
+    sig { returns(T::Boolean) }
+    def failure?; end
+
+    # Determine if the service call has successfully ran
+    sig { returns(T::Boolean) }
+    def success?; end
+
+    # Return if the service has any issues (errors or failure)
+    sig { returns(T::Boolean) }
+    def issues?; end
+
+    # Returns the value of attribute called
+    sig { returns(Object) }
+    attr_accessor :called
+
+    # Returns the value of attribute errors
+    sig { returns(Object) }
+    attr_accessor :errors
+
+    # Returns the value of attribute failure
+    sig { returns(Object) }
+    attr_accessor :failure
+
+    # Returns the value of attribute results
+    sig { returns(Object) }
+    attr_accessor :results
+  end
+
+  # Callbacks before/after the services `call` is called
+  module Callbacks
+    # Used to include/extend modules into the current class
+    # 
+    # _@param_ `base`
+    sig { params(base: Object).void }
+    def self.included(base); end
+
+    # Methods to load in the service object as class methods
+    module ClassMethods
+      # Add callback `before` method or block
+      # 
+      # _@param_ `callbacks`
+      sig { params(callbacks: T::Hash[T.untyped, T.untyped], block: T.untyped).void }
+      def before(*callbacks, &block); end
+
+      # Add callback `after` method or block
+      # 
+      # _@param_ `callbacks`
+      sig { params(callbacks: T::Hash[T.untyped, T.untyped], block: T.untyped).void }
+      def after(*callbacks, &block); end
+
+      # Call all callbacks before `#call` is referenced (methods, blocks, etc.)
+      sig { void }
+      def run_before_callbacks; end
+
+      # Call and run all callbacks after `#call` has ran
+      sig { void }
+      def run_after_callbacks; end
+
+      # Create a list of `after` callback methods and/or blocks
+      sig { returns(T::Hash[T.untyped, T.untyped]) }
+      def after_callbacks; end
+
+      # Create a list of `before` callback methods and/or blocks
+      sig { returns(T::Hash[T.untyped, T.untyped]) }
+      def before_callbacks; end
+
+      # Loopthrough and run all the classes listed callback methods
+      # 
+      # _@param_ `callbacks` — a list of methods to be called
+      sig { params(callbacks: T::Array[T.any(String, Symbol)]).void }
+      def run_callbacks(callbacks); end
+
+      # Run callback m method or block
+      # 
+      # _@param_ `callback`
+      # 
+      # _@param_ `options`
+      sig { params(callback: Symbol, options: T::Hash[T.untyped, T.untyped]).void }
+      def run_callback(callback, *options); end
+    end
+  end
+end
+
+# Used to generate a Rails service object
+class CrossbeamGenerator < Rails::Generators::Base
+  sig { void }
+  def generate_service; end
+
+  sig { void }
+  def generate_test; end
+
+  # Returns a string to use as the service classes file name
+  sig { returns(String) }
+  def filename; end
+end

data/lib/crossbeam/callbacks.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative './error'
+
+module Crossbeam
+  # Callbacks before/after the services `call` is called
+  module Callbacks
+    # Used to include/extend modules into the current class
+    #
+    # @param base [Object]
+    # @return [void]
+    def self.included(base)
+      base.class_eval do
+        extend(ClassMethods)
+
+        attr_accessor :klass
+      end
+    end
+
+    # Methods to load in the service object as class methods
+    module ClassMethods
+      # Add callback `before` method or block
+      #
+      # @param callbacks [Hash]
+      # @return [void]
+      # @yield An optional block to instance_exec(&block) || instance_eval(&block)
+      def before(*callbacks, &block)
+        callbacks << block if block
+        callbacks.each { |callback| before_callbacks << callback }
+      end
+
+      # Add callback `after` method or block
+      #
+      # @param callbacks [Hash]
+      # @return [void]
+      # @yield An optional block to instance_exec(&block) || instance_eval(&block)
+      def after(*callbacks, &block)
+        callbacks << block if block
+        callbacks.each { |callback| after_callbacks << callback }
+      end
+
+      # Call all callbacks before `#call` is referenced (methods, blocks, etc.)
+      #
+      # @return [void]
+      def run_before_callbacks
+        # run_callbacks(self.class.before_callbacks)
+        run_callbacks(before_callbacks)
+      end
+
+      # Call and run all callbacks after `#call` has ran
+      #
+      # @return [void]
+      def run_after_callbacks
+        run_callbacks(after_callbacks)
+      end
+
+      # Create a list of `after` callback methods and/or blocks
+      #
+      # @return [Hash]
+      def after_callbacks
+        @after_callbacks ||= []
+      end
+
+      # Create a list of `before` callback methods and/or blocks
+      #
+      # @return [Hash]
+      def before_callbacks
+        @before_callbacks ||= []
+      end
+
+      # Loopthrough and run all the classes listed callback methods
+      #
+      # @param callbacks [Array<String, Symbol>] a list of methods to be called
+      # @return [void]
+      def run_callbacks(callbacks)
+        callbacks.each { |callback| run_callback(callback) }
+      end
+
+      private
+
+      # Run callback m method or block
+      #
+      # @param callback [Symbol]
+      # @param options [Hash]
+      # @return [void]
+      def run_callback(callback, *options)
+        # Ensure the initialize instance class has been called and passed
+        return unless @klass
+
+        # callback.is_a?(Symbol) ? send(callback, *options) : instance_exec(*options, &callback)
+        if [String, Symbol].include?(callback.class) && @klass.respond_to?(callback.to_sym)
+          @klass.send(callback, *options)
+        elsif callback.is_a?(Proc)
+          @klass.instance_exec(*options, &callback)
+        end
+      end
+    end
+  end
+end

data/lib/crossbeam/error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Crossbeam
+  # Error message that is raised to flag a Crossbeam service error
+  #   used to create error messages for Crossbeam
+  # @private
+  class Error < StandardError
+    # @return [String] Error message associated with StandardError
+    attr_reader :context
+
+    # Used to initializee an error message
+    #
+    # @param context [String, Hash]
+    # @return [Object]
+    def initialize(context = nil)
+      @context = context
+      super
+    end
+  end
+
+  # Used to generate `ArguementError` exception
+  # @private
+  class ArguementError < Error; end
+  # Used to generate `Failure` exception
+  # @private
+  class Failure < Error; end
+  # Used to generate `NotImplementedError` exception
+  # @private
+  class NotImplementedError < Error; end
+  # Used to generate `UndefinedMethod` exception
+  # @private
+  class UndefinedMethod < Error; end
+end

data/lib/crossbeam/errors.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative './error'
+
+module Crossbeam
+  # Very similar to ActiveModel errors
+  # https://github.com/rails/rails/blob/main/activemodel/lib/active_model/validations.rb
+
+  # Used to allow adding errors to the service call similar to ActiveRecord errors
+  class Errors < Hash
+    # Add an error to the list of errors
+    #
+    # @param key [String, Symbol] the key/attribute for the error. (Usually ends up being :base)
+    # @param value [String, Symbol] a description of the error
+    # @param _opts [Hash] additional attributes that get ignored
+    # @return [Hash]
+    def add(key, value, _opts = {})
+      self[key] ||= []
+      self[key] << value
+      self[key].uniq!
+    end
+
+    # Add multiple errors to the error hash
+    #
+    # @param errors [Hash<String, Symbol>]
+    # @return [Hash], Array]
+    def add_multiple_errors(errors)
+      errors.each do |key, values|
+        if values.is_a?(String)
+          add(key, values)
+        elsif [Array, Hash].include?(values.class)
+          values.each { |value| add(key, value) }
+        end
+      end
+    end
+
+    # Look through and return a list of all errorr messages
+    #
+    # @return [Hash, Array]
+    def each
+      each_key do |field|
+        self[field].each { |message| yield field, message }
+      end
+    end
+
+    # Return a full list of error messages
+    #
+    # @return [Array<String>]
+    def full_messages
+      map { |attribute, message| full_message(attribute, message) }.freeze
+    end
+
+    # Used to convert the list of errors to a string
+    #
+    # @return [String]
+    def to_s
+      return '' unless self&.any?
+
+      full_messages.join("\n")
+    end
+
+    private
+
+    # Convert the message to a full error message
+    #
+    # @param attribute [String, Symbol]
+    # @param message [String]
+    # @return [String]
+    def full_message(attribute, message)
+      return message if attribute == :base
+
+      attr_name = attribute.to_s.tr('.', '_').capitalize
+      format('%<attr>s %<msg>s', attr: attr_name, msg: message)
+    end
+  end
+end

data/lib/crossbeam/output.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative './error'
+
+module Crossbeam
+  # For forcing specific output after `#call`
+  module Output
+    # Used to include/extend modules into the current class
+    #
+    # @param base [Object]
+    # @return [void]
+    def self.included(base)
+      base.class_eval do
+        extend(ClassMethods)
+
+        attr_accessor :output_param
+      end
+    end
+
+    # Methods to load in the service object as class methods
+    module ClassMethods
+      # @return [Hash]
+      CB_ALLOWED_OUTPUTS = [NilClass, String, Symbol].freeze
+      # Used to specify an attribute/instance variable that should be used too return instead of @result
+      #
+      # @param param [String, Symbol]
+      # @return [String, Symbol]
+      def output(param)
+        raise(ArguementError, 'A string or symbol is require for output') unless allowed_output?(param)
+
+        @output_param = param
+      end
+
+      # Determine if the output attribute type is allowed
+      #
+      # @param output_type [String]
+      # @return [Boolean]
+      def allowed_output?(output_type)
+        CB_ALLOWED_OUTPUTS.include?(output_type.class)
+      end
+
+      # Used to determine if a output parameter has been set or not
+      #
+      # @return [Boolean]
+      def output?
+        !output_param.nil?
+      end
+
+      # Determine the output to return if the instance_variable exists in the klass
+      #
+      # @return [Hash]
+      def set_results_output
+        return unless @klass
+        return unless output? && @klass.instance_variable_defined?("@#{output_param}")
+
+        @result.results = @klass.instance_variable_get("@#{output_param}")
+      end
+
+      # Add errors to @result.errors
+      #
+      # @return [Void]
+      def build_error_list
+        return unless @klass && @klass&.errors&.any?
+
+        @klass.errors.each do |error|
+          # options is usually passed with an ActiveRecord validation error
+          # @example:
+          #   <attribute=age, type=greater_than_or_equal_to, options={:value=>15, :count=>18}>
+          @result.errors.add(error.attribute, error.message)
+        end
+        @klass.errors.clear
+        reassign_results
+      end
+
+      # Reassign result, unless errors
+      #
+      # @return [Void]
+      def reassign_results
+        @result.results = nil
+        @result.results = @klass.instance_variable_get("@#{output_param}") if specified_output?
+      end
+
+      # Does the klass have an assigned output
+      #
+      # @return [Boolean]
+      def specified_output?
+        output? && @klass.instance_variable_defined?("@#{output_param}")
+      end
+
+      # Used hold the parameter which can/will be used instead of @result
+      #
+      # @return [String, Symbol, nil]
+      def output_param
+        @output_param ||= nil
+      end
+    end
+  end
+end

data/lib/crossbeam/result.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'active_model'
+# Crossbeam files
+require_relative './error'
+require_relative './errors'
+
+module Crossbeam
+  # Used as a data container to hold a service calls results, errors, etc.
+  # class Result < Struct.new(:called, :errors, :failure, :results)
+  Result = Struct.new(:called, :errors, :failure, :results) do
+    # extend ActiveModel::Naming
+    # include ActiveModel::Conversion
+    # attr_accessor :called, :errors, :failure, :results
+
+    # Used to initialize a service calls results, errors, and stats
+    #
+    # @param called [Boolean]
+    # @param errors [Hash]
+    # @param failure [Boolean]
+    # @param results [Object]
+    def initialize(called: false, errors: nil, failure: false, results: nil)
+      super(called, errors, failure, results)
+
+      self.called = called
+      self.errors = Crossbeam::Errors.new
+      self.failure = failure
+      self.results = nil
+    end
+
+    # The serivce can't officially be a failure/pass if it hasn't been "called"
+    #
+    # @return [Boolean]
+    def called?
+      called || false
+    end
+
+    # Determine if the service call has any errors
+    #
+    # @return [Boolean]
+    def errors?
+      (errors.is_a?(Hash) && errors.any?) || false
+    end
+
+    # Determine if the service call has failed to uccessfully complete
+    #
+    # @return [Boolean]
+    def failure?
+      called? && issues?
+    end
+
+    # Determine if the service call has successfully ran
+    #
+    # @return [Boolean]
+    def success?
+      called? && !issues?
+    end
+
+    private
+
+    # Return if the service has any issues (errors or failure)
+    #
+    # @return [Boolean]
+    def issues?
+      errors? || failure
+    end
+  end
+end

data/lib/crossbeam/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Crossbeam
+  # @return [String]
+  VERSION = '0.1.0'
+end

data/lib/crossbeam.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require 'dry-initializer'
+
+# Crossbeam required modules
+require_relative 'crossbeam/callbacks'
+require_relative 'crossbeam/error' # exceptions
+require_relative 'crossbeam/errors' # errors
+# For forcing specific output after `#call`
+require_relative 'crossbeam/output'
+require_relative 'crossbeam/result'
+require_relative 'crossbeam/version'
+
+require 'debug'
+
+# Crossbeam module to include with your service classes
+module Crossbeam
+  # Used to include/extend modules into the current class
+  #
+  # @param base [Object]
+  # @return [void]
+  def self.included(base)
+    base.class_eval do
+      include(ActiveModel::Validations) # Used to add validation errors to a class
+      extend(Dry::Initializer) # Used to allow for easy attribute initializations
+      extend(ClassMethods) # Class methods used to initialize the service call
+      include(Output)
+      include(Callbacks) # Callbacks that get called before/after `.call` is referenced
+
+      # Holds the service call results and current class call for Crossbeam Instance
+      attr_reader :result, :klass
+    end
+  end
+
+  # Methods to load in the service object as class methods
+  module ClassMethods
+    # Used to initiate and service call
+    #
+    # @param params [Array<Object>]
+    # @param options [Hash<Symbol, Object>]
+    # @return [Struct, Object]
+    def call(*params, **options, &block)
+      @result = Crossbeam::Result.new(called: true)
+      @klass = new(*params, **options)
+      run_callbacks_and_klass(&block)
+      @result
+    rescue Crossbeam::Failure => e
+      process_error(e)
+    end
+
+    # Call the klass's before/after callbacks, process errors, and call @klass
+    #
+    # @return [Void]
+    def run_callbacks_and_klass(&block)
+      # Call all the classes `before`` callbacks
+      run_before_callbacks
+      # Initialize and run the classes call method
+      @result.results = @klass.call(&block)
+      # build @result.errors if errors were added
+      build_error_list if @klass.errors.any?
+      # re-assign @result if output was set
+      set_results_output
+      # Call all the classes `after` callbacks
+      run_after_callbacks
+    end
+
+    # Process the error that was thrown by the object call
+    #
+    # @param error [Object] error generated by the object call
+    # @return [Object, Crossbeam::Result]
+    def process_error(error)
+      @result.failure = true
+      @result.errors.add(:failure, error.to_s)
+      @result.results = nil
+      @result
+    end
+  end
+
+  # Force the job to raise an exception and stop the rest of the service call
+  #
+  # @param error [String]
+  # @return [void]
+  def fail!(error)
+    raise(Crossbeam::Failure, error)
+  end
+
+  %w[called failure errors issues success].each do |attr|
+    # Used to determine the current state of the service call
+    #
+    # @return [Boolean]
+    define_method("#{attr}?") do
+      return false unless @result
+
+      attr = attr.to_s
+      @result.send("#{attr}?".to_sym) || false
+    end
+  end
+
+  # Used to return a list of errors for the current call
+  #
+  # @return [Hash]
+  def errors
+    return {} unless @result
+
+    @result.errors
+  end
+end

data/lib/generators/crossbeam_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Only define the generators if part of rails app to prevent causing an excceeption
+if defined?(Rails)
+  require 'rails/generators'
+
+  # Used to generate a Rails service object
+  class CrossbeamGenerator < ::Rails::Generators::Base
+    source_root File.expand_path(File.join('.', 'templates'), File.dirname(__FILE__))
+
+    argument :class_name, type: :string
+    argument :attributes, type: :array, default: [], banner: 'field[:type]'
+    desc 'Generate a Crossbeam service class'
+
+    # @return [void]
+    def generate_service
+      template 'service_class.rb.tt', "app/services/#{filename}.rb", force: true
+    end
+
+    # @return [void]
+    def generate_test
+      return unless Rails&.application&.config&.generators&.test_framework == :rspec
+
+      template 'service_spec.rb.tt', "spec/services/#{filename}_spec.rb", force: true
+    end
+
+    private
+
+    # Returns a string to use as the service classes file name
+    #
+    # @return [String]
+    def filename
+      class_name.underscore
+    end
+  end
+end

data/lib/generators/templates/service_class.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class <%= class_name.classify %>
+  include Crossbeam
+<%- attributes.each do |attribute| -%>
+  option :<%= attribute.parameterize(separator: '_') %>
+<%- end -%>
+
+  def call
+    # ...
+  end
+end

data/lib/generators/templates/service_spec.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe <%= class_name.classify %>, type: :helper do
+  subject { described_class.call }
+
+  describe 'an example' do
+    it 'is a pending example'
+  end
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: crossbeam
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brandon Hicks
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: dry-initializer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: rubocop-rspec
+  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-performance
+  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: An easy way to create and run service objects with callbacks, validations,
+  errors, and responses
+email:
+- tarellel@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- README.md
+- LICENSE.txt
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- defs.rbi
+- lib/crossbeam.rb
+- lib/crossbeam/callbacks.rb
+- lib/crossbeam/error.rb
+- lib/crossbeam/errors.rb
+- lib/crossbeam/output.rb
+- lib/crossbeam/result.rb
+- lib/crossbeam/version.rb
+- lib/generators/crossbeam_generator.rb
+- lib/generators/templates/service_class.rb.tt
+- lib/generators/templates/service_spec.rb.tt
+homepage: https://github.com/tarellel/crossbeam
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/tarellel/crossbeam/issue
+  changelog_uri: https://github.com/tarellel/crossbeam/blob/master/CHANGELOG.md
+  homepage_uri: https://github.com/tarellel/crossbeam
+  source_code_uri: https://github.com/tarellel/crossbeam
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.15
+signing_key:
+specification_version: 4
+summary: An easy way to create and run service objects with callbacks, validations,
+  errors, and responses
+test_files: []