telephone 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2961c1545d60c8daef9cdc90a8ecea01c12ecd14357d446dbfe86cae84cc43c2
+  data.tar.gz: 27dad4361e48e380776fb3c32ea59855f95804e024b1aad879d84ad292f96a23
+SHA512:
+  metadata.gz: 70159c4118b77a694873f4cf9f14d28bfbaae52692c28eaa95eafec80b06a91e8fd65dd76db1a849efdd5e7b5a294c5d1836a5b924c6df81eb9b9a636145c14e
+  data.tar.gz: 2bd95f410bc0bc92960c1e6065ecf5b0971dbc6792dff760cebef1494d1cdbc8efd5e87499d53a7eaae1786f8904a4280b570c9d59327995877a17fad20a8773

data/README.md

@@ -0,0 +1,139 @@
+# Telephone ☎️
+
+![](https://github.com/bharget/telephone/actions/workflows/ci.yml/badge.svg)
+
+Telephone is a light weight utility that helps you create and call service objects from anywhere within your application.
+
+Telepone comes with a simple interface that helps with:
+
+* Keeping your code DRY
+* Encapsulating complex logic in a more readable way
+* Making your code easier to test
+* Gracefully handling errors and validations
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'telephone'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install telephone
+
+## Usage
+
+`Telephone::Service` is a simple utility class for creating and calling service objects. It allows you to define arguments and validations, and provides
+a simple interface for calling the service and determining its success.
+
+To start, define an `ApplicationService` and inherit from `Telephone::Service`.
+
+```ruby
+# /app/services/application_service.rb
+
+class ApplicationService < Telephone::Service
+end
+```
+
+A very simple example of a service object:
+
+```ruby
+class SimpleExample < ApplicationService
+  def call
+    "Hello World"
+  end
+end
+
+s = SimpleExample.call #=> <#SimpleExample @result="Hello World">
+s.success? #=> true
+s.result #=> "Hello World"
+```
+
+### Arguments
+
+You can define arguments for the service object. These arguments will be passed to the service object's `call` method, and will be available as an attribute.
+
+```ruby
+class SimpleExample < ApplicationService
+  argument :name
+
+  def call
+    "Hello, #{name}."
+  end
+end
+
+SimpleExample.call(name: "Benjamin").result #=> "Hello, Benjamin."
+```
+
+Arguments can also be required, which will prevent the service object from executing unless they are present.
+
+```ruby
+class SimpleExample < ApplicationService
+  argument :name, required: true
+
+  def call
+    "Hello, #{name}."
+  end
+end
+
+s = SimpleExample.call
+s.success? #=> false
+s.errors.full_messages #=> ["Name can't be blank"]
+s.result #=> nil
+```
+
+You can also give a default value for an argument.
+
+```ruby
+argument :name, default: "Benjamin"
+```
+
+### Validations
+
+Since `Telephone::Service` includes `ActiveModel::Model`, you can define validations in the same way you would for an ActiveRecord model.
+
+```ruby
+validates :name, format: { with: /\A[a-zA-Z]+\z/ }
+validate :admin_user?
+
+def admin_user?
+  errors.add(:user, "not admin") unless user.admin?
+end
+```
+
+If a validation fails, the service object will not execute and return `nil` as the result of th call. You can check the status of the service object by calling `success?`.
+
+```ruby
+s = SomeService.call
+s.success? #=> false
+```
+
+## Best Practices
+
+Service objects are a great way to keep your code DRY and encapsulate business logic. As a rule of thumb, try to keep your service objects to a single responsibility. If you find yourself dealing with very complex logic, consider breaking it up into smaller services.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. This will install the dependencies for each subgem and run the entire test suite.
+
+To experiment, you can run `bin/console` for an interactive prompt.
+
+### Documentation
+
+This project is documented using YARD. All code should be well documented via the YARD syntax prior to merging.
+
+You can access the docmentation by starting up the YARD server.
+
+```sh
+yard server --reload
+```
+
+The `--reload`, or `-r`, flag tells the server to auto reload the documentation on each request.
+
+Once the server is running, the documentation will by available at http://localhost:8808

data/lib/telephone.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "telephone/service"

data/lib/telephone/service.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Telephone
+  class Service
+    include ActiveModel::Model
+
+    ##
+    # The primary outcome of the service object. For consistency,
+    # all service objects always return +self+. If you need a value
+    # returned, the return value of +#call+ will be available on the
+    # attribute +@result+.
+    #
+    # @example
+    #   Telephone::Service.call(foo: bar).result # "baz"
+    attr_accessor :result
+
+    ##
+    # Determines whether or not the action of the service
+    # object was successful.
+    #
+    # @example
+    #   Telephone::Service.call(foo: bar).success? # true
+    #
+    # @return [Boolean] whether or not the action succeeded.
+    def success?
+      errors.empty?
+    end
+
+    class << self
+      ##
+      # Defines a getter/setter for a service object argument. This also allows you
+      # to pass in a default, or set the argument to "required" to add a validation
+      # that runs before executing the block.
+      #
+      # @example
+      #   class SomeService < Telephone::Service
+      #     argument :foo, default: "bar"
+      #     argument :baz, required: true
+      #
+      #     def call
+      #       puts foo
+      #       puts baz
+      #     end
+      #   end
+      def argument(arg, default: nil, required: false)
+        send(:attr_accessor, arg.to_sym)
+        send(:validates, arg.to_sym, presence: true) if required
+
+        defaults[arg.to_sym] = default
+      end
+
+      ##
+      # Used to maintain a list of default values to set prior to initialization
+      # based on the options in #argument.
+      def defaults
+        @defaults ||= {}
+      end
+
+      ##
+      # Executes the service object action directly from the class — similar to the
+      # way a Proc can be executed with `Proc#call`. This allows us to add some common
+      # logic around running validations and setting argument defaults.
+      #
+      # @example
+      #   Telephone::Service.call(foo: bar)
+      def call(**args)
+        instance = new(defaults.merge(args))
+        instance.result = instance.call if instance.valid?
+        instance
+      end
+    end
+  end
+end

data/lib/telephone/version.rb

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

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: telephone
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Benjamin Hargett
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-07-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Utility class for creating and calling service objects.
+email: hargettbenjamin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/telephone.rb
+- lib/telephone/service.rb
+- lib/telephone/version.rb
+homepage: https://github.com/bharget/telephone
+licenses: []
+metadata:
+  bug_tracker_uri: https://github.com/bharget/telephone/issues
+  changelog_uri: https://github.com/bharget/telephone/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/bharget/telephone
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- none
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Utility class for creating and calling service objects.
+test_files: []