operatic 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79842e69c42fad058cef240224911da273e0b801b51762bb4edc062590b1db1c
-  data.tar.gz: d3262c93d6332c3833b3688425f09d1168bc961fc084b67bcaa148f2700ff60c
+  metadata.gz: 56ef955a17eedc8782756d9a79b164662f2d558f16e2e8f48f5991d6452a30df
+  data.tar.gz: 660cb2d0ae5118614bcd449a8b3b06b041afe467d762bac8dbe3e10de506b2dc
 SHA512:
-  metadata.gz: 212c3d737d571164069bacb305fe196008cbf27d1b81e440c230025715032a84c5df6e1dd2d2d6dc3a9073a5a9ebf010dff712e2f1577b68564f0d0d9594ca33
-  data.tar.gz: 42d76bcf9a9e5ecef9ebb9e22d5eaa1378ed93bbbc164ac589acf134803b250c2ba8c6b461ef74e6927c6794d78c791d58811316c76ad6bc66fc0f44692326a2
+  metadata.gz: 7a432089ae7b3f71c3028bf34e278ea33553e924212bcc83bf5c02b0e3d28923e416e3f1cd054bfa664fce27343dcd76c9beec98dd88b4da2e85a625cb012e37
+  data.tar.gz: 271a800712179e79efcb75f1bd267e1dd12900b5eb07837a78aab4c35cffe3914e98733d08436a4cc3d52872934b07c04ae941648b70cd60eb61d0e3b6a6e030

data/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+
+updates:
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: daily

data/.github/workflows/ruby.yml

@@ -8,14 +8,14 @@ jobs:
     strategy:
       matrix:
         ruby:
-          - '2.5'
-          - '2.6'
           - '2.7'
           - '3.0'
           - '3.1'
+          - '3.2'
+          - '3.3'
     name: Ruby ${{ matrix.ruby }} RSpec
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - uses: ruby/setup-ruby@v1
       with:
         bundler-cache: true

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # CHANGELOG
 
+## Version 0.7.0 - 2024-05-12
+
+- Data within an operation is now gathered on a separate `#data` object that's passed to a concrete `Operatic::Success`/`Operatic::Failure` result instance on completion. Convenience data accessors can be defined on the `Data` object (via the renamed `Operatic.data_attr`) but remain available on the result using the magic of `Result#method_missing`. <https://github.com/benpickles/operatic/pull/18>
+- Require Ruby version 2.7+.
+- Support pattern matching solely against a Result's data. <https://github.com/benpickles/operatic/pull/20>
+
+## Version 0.6.0 - 2022-08-22
+
+- Support pattern matching a Result (in Ruby 2.7+). <https://github.com/benpickles/operatic/pull/12>
+
 ## Version 0.5.0 - 2022-06-23
 
 - Support custom initialize method to aid compatibility with other libraries. <https://github.com/benpickles/operatic/pull/11>

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in operatic.gemspec
 gemspec
+
+gem 'yard'

data/README.md

@@ -24,7 +24,7 @@ class SayHello
   attr_reader :name
 
   # Declare convenience accessors on the result.
-  result_attr :message
+  data_attr :message
 
   def call
     # Exit the method and mark the result as a failure.
@@ -36,12 +36,15 @@ class SayHello
 end
 
 result = SayHello.call(name: 'Dave')
+result.class     # => Operatic::Success
+result.failure?  # => false
 result.success?  # => true
 result.message   # => "Hello Dave"
 result[:message] # => "Hello Dave"
 result.to_h      # => {:message=>"Hello Dave"}
 
 result = SayHello.call
+result.class     # => Operatic::Failure
 result.failure?  # => true
 result.success?  # => false
 result.message   # => nil
@@ -65,10 +68,63 @@ class HellosController < ApplicationController
 end
 ```
 
+## Pattern matching
+
+An Operatic result also supports pattern matching allowing you to match over a tuple of the result class and its data:
+
+```ruby
+case SayHello.call(name: 'Dave')
+in [Operatic::Success, { message: }]
+  # Result is a success, do something with the `message` variable.
+in [Operatic::Failure, _]
+  # Result is a failure, do something else.
+end
+```
+
+Or match solely against its data:
+
+```ruby
+case SayHello.call(name: 'Dave')
+in message:
+  # Result has the `message` key, do something with the variable.
+else
+  # Do something else.
+end
+```
+
+Which might be consumed in Rails like this:
+
+```ruby
+class HellosController < ApplicationController
+  def create
+    case SayHello.call(name: params[:name])
+    in [Operatic::Success, { message: }]
+      render plain: message
+    in [Operatic::Failure, _]
+      render :new
+    end
+  end
+end
+```
+
+## Development
+
+Run the tests with:
+
+```
+bundle exec rspec
+```
+
+Generate Yard documentation with:
+
+```
+bundle exec yardoc
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the Operatic project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/benpickles/operatic/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Operatic project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/benpickles/operatic/blob/main/CODE_OF_CONDUCT.md).

data/lib/operatic/data.rb

@@ -0,0 +1,72 @@
+module Operatic
+  class Data
+    # Generate a subclass of {Data} with named +attrs+ accessors. This wouldn't
+    # normally be called directly, see {ClassMethods#data_attr} for example
+    # usage.
+    #
+    # @param attrs [Array<Symbol>] a list of convenience data accessors.
+    def self.define(*attrs)
+      Class.new(self) do
+        attrs.each do |name|
+          define_method name do
+            self[name]
+          end
+
+          define_method "#{name}=" do |value|
+            self[name] = value
+          end
+        end
+      end
+    end
+
+    # @param kwargs [Hash<Symbol, anything>]
+    def initialize(**kwargs)
+      @data = kwargs
+    end
+
+    # Return the value for +key+.
+    #
+    # @param key [Symbol]
+    #
+    # @return [anything]
+    def [](key)
+      @data[key]
+    end
+
+    # Set data on the result.
+    #
+    # @param key [Symbol]
+    # @param value [anything]
+    def []=(key, value)
+      @data[key] = value
+    end
+
+    # @return [self]
+    def freeze
+      @data.freeze
+      super
+    end
+
+    # @param hash [Hash<Symbol, anything>]
+    #
+    # @return [Data]
+    def merge(hash)
+      self.class.new.tap { |other|
+        other.set_data(@data)
+        other.set_data(hash)
+      }
+    end
+
+    # @return [Hash<Symbol, anything>]
+    def to_h
+      @data
+    end
+
+    protected
+      def set_data(data)
+        data.each do |key, value|
+          @data[key] = value
+        end
+      end
+  end
+end

data/lib/operatic/result.rb

@@ -1,91 +1,116 @@
 module Operatic
   class Result
-    # Generate a subclass of {Result} with named +attrs+ accessors. This
-    # wouldn't normally be called directly, see {ClassMethods#result_attr} for
-    # example usage.
-    #
-    # @param attrs [Array<Symbol>] a list of convenience data accessors.
-    def self.generate(*attrs)
-      Class.new(self) do
-        attrs.each do |name|
-          define_method name do
-            @data[name]
-          end
-
-          define_method "#{name}=" do |value|
-            @data[name] = value
-          end
-        end
-      end
-    end
+    # @return [Data]
+    attr_reader :data
 
-    def initialize
-      @data = {}
-      @success = true
+    # @param data [Data]
+    def initialize(data)
+      @data = data
     end
 
-    # Read data that's attached to the result.
+    # Convenience proxy to read the +key+ from its {#data} object.
+    #
+    # @param key [Symbol]
+    #
+    # @return [anything]
     def [](key)
-      @data[key]
+      data[key]
     end
 
-    # Set data on the result.
-    def []=(key, value)
-      @data[key] = value
-    end
-
-    # Mark the result as a failure, optionally attach +data+ via kwargs, and
-    # freeze the object so it cannot be modified further.
+    # Returns a tuple of self and {#to_h} allowing you to pattern match across
+    # both the result's status and its data.
+    #
+    # @example
+    #   class SayHello
+    #     include Operatic
+    #
+    #     def call
+    #       data[:message] = 'Hello world'
+    #     end
+    #   end
     #
-    # *Note*: Calling {#success!} or {#failure!} more than once will raise a
-    # +FrozenError+.
-    def failure!(**data)
-      set_data(**data)
-      @success = false
-      freeze
+    #   case SayHello.call
+    #   in [Operatic::Success, { message: }]
+    #     # Result is a success, do something with the `message` variable.
+    #   in [Operatic::Failure, _]
+    #     # Result is a failure, do something else.
+    #   end
+    #
+    # @return [Array(self, Hash<Symbol, anything>)]
+    def deconstruct
+      [self, to_h]
     end
 
-    def failure?
-      !@success
+    # Pattern match against the result's data via {#to_h}.
+    #
+    # @example
+    #   class SayHello
+    #     include Operatic
+    #
+    #     def call
+    #       data[:message] = 'Hello world'
+    #     end
+    #   end
+    #
+    #   case SayHello.call
+    #   in message:
+    #     # Result has the `message` key, do something with the variable.
+    #   else
+    #     # Do something else.
+    #   end
+    #
+    # @return [Hash<Symbol, anything>]
+    def deconstruct_keys(keys = nil)
+      to_h
     end
 
+    # @return [self]
     def freeze
-      @data.freeze
+      data.freeze
       super
     end
 
-    # Mark the result as a success, optionally attach +data+ via kwargs, and
-    # freeze the object so it cannot be modified further.
-    #
-    # Calling this is not strictly necessary as a +Result+ defaults to being a
-    # success, but it's a convenient means of attaching data and of indicating
-    # intent in the consuming code.
-    #
-    # *Note*: Calling {#success!} or {#failure!} more than once will raise a
-    # +FrozenError+.
-    def success!(**data)
-      set_data(**data)
-      @success = true
-      freeze
+    # Forwards unknown methods to its {#data} object allowing convenience
+    # accessors defined via {Data.define} to be available directly on the
+    # {Result}.
+    def method_missing(name, *args, **kwargs, &block)
+      return data.public_send(name, *args, **kwargs, &block) if data.respond_to?(name)
+      super
     end
 
-    def success?
-      @success
+    def respond_to?(...)
+      super || data.respond_to?(...)
     end
 
-    # Returns the full (frozen) hash of data attached to the result via
-    # {#success!}, {#failure!}, or convenience accessors added with {.generate}.
+    # Convenience proxy to {Data#to_h}.
     #
     # @return [Hash<Symbol, anything>]
     def to_h
-      @data
+      data.to_h
+    end
+  end
+
+  class Success < Result
+    # @return [false]
+    def failure?
+      false
+    end
+
+    # @return [true]
+    def success?
+      true
+    end
+  end
+
+  class Failure < Result
+    # @return [true]
+    def failure?
+      true
     end
 
-    private
-      def set_data(**data)
-        data.each do |key, value|
-          @data[key] = value
-        end
-      end
+    # @return [false]
+    def success?
+      false
+    end
   end
 end

data/lib/operatic/version.rb

@@ -1,3 +1,3 @@
 module Operatic
-  VERSION = '0.5.0'
+  VERSION = '0.7.0'
 end

data/lib/operatic.rb

@@ -1,3 +1,4 @@
+require 'operatic/data'
 require 'operatic/errors'
 require 'operatic/result'
 require 'operatic/version'
@@ -9,115 +10,152 @@ module Operatic
   end
 
   module ClassMethods
-    # The main way of calling an operation.
+    # The main way to call an operation. This initializes the class with the
+    # supplied +attrs+ keyword arguments and calls {Operatic#call} returning a
+    # frozen {Result} instance.
     #
-    # The class is instantiated with the supplied +attrs+ keyword arguments and
-    # calls {Operatic#call} returning a frozen {Result} instance.
+    # @param attrs [Hash<Symbol, anything>]
     #
-    # @return [Result]
+    # @return [Failure, Success]
     def call(**attrs)
-      new(**attrs)
-        .tap(&:call)
-        .result
-        .freeze
+      operation = new(**attrs)
+      operation.call
+      operation.result || Success.new(operation.data).freeze
     end
 
-    # Calls {#call} but raises {FailureError} if the returned {Result} is a
-    # {Result#failure?} - useful for things like background jobs, rake tasks,
-    # test setups, etc.
+    # The same as {#call} but raises {FailureError} if the returned {#result} is
+    # a {Failure} - useful for things like background jobs, rake tasks, test
+    # setups, etc.
     #
-    # @return [Result]
+    # @param attrs [Hash<Symbol, anything>]
+    #
+    # @return [Success]
+    #
+    # @raise [FailureError] if the operation is not a {Success}
     def call!(**attrs)
       call(**attrs).tap { |result|
         raise FailureError if result.failure?
       }
     end
 
-    # Define a {Result} subclass with named accessors specific to the class via
-    # {Result.generate}.
+    # Define a class-specific {Data} subclass with the named accessors added via
+    # {Data.define}.
     #
     # @example
     #   class SayHello
     #     include Operatic
     #
-    #     attr_reader :name
-    #
-    #     result_attr :message
+    #     data_attr :message
     #
     #     def call
-    #       success!(message: "Hello #{name}")
+    #       success!(message: "Hello #{@name}")
     #     end
     #   end
     #
     #   result = SayHello.call(name: 'Dave')
-    #   result.success? # => true
-    #   result.message  # => "Hello Dave"
+    #   result.class     # => Operatic::Success
+    #   result.message   # => "Hello Dave"
+    #   result[:message] # => "Hello Dave"
+    #   result.to_h      # => {:message=>"Hello Dave"}
     #
     # @param attrs [Array<Symbol>] a list of convenience data accessors to
     #   define on the {Result}.
-    def result_attr(*attrs)
-      @result_class = Result.generate(*attrs)
+    def data_attr(*attrs)
+      @data_class = Data.define(*attrs)
     end
 
-    def result_class
-      @result_class || Result
+    # @return [Class<Data>]
+    def data_class
+      @data_class || Data
     end
   end
 
+  # @return [Success, Failure]
+  attr_reader :result
+
+  # @param attrs [Hash<Symbol, anything>]
   def initialize(**attrs)
     attrs.each do |key, value|
       instance_variable_set("@#{key}", value)
     end
   end
 
-  # Override this method with your implementation. Use {#success!} or
-  # {#failure!} methods to communicate the {#result}'s status and to attach
-  # data to it. Define convenience result accessors with
-  # {ClassMethods#result_attr}.
+  # Override this method with your implementation. Use {#success!}/{#failure!}
+  # to define the status of the result {Success}/{Failure} and attach data.
   #
   # @example
   #   class SayHello
   #     include Operatic
   #
-  #     attr_reader :name
-  #
-  #     result_attr :message
-  #
   #     def call
-  #       return failure! unless name
-  #       success!(message: "Hello #{name}")
+  #       return failure! unless @name
+  #       success!(message: "Hello #{@name}")
   #     end
   #   end
   #
   #   result = SayHello.call(name: 'Dave')
-  #   result.failure? # => false
-  #   result.success? # => true
-  #   result.message  # => "Hello Dave"
-  #   result.to_h     # => {:message=>"Hello Dave"}
+  #   result.class     # => Operatic::Success
+  #   result.failure?  # => false
+  #   result.success?  # => true
+  #   result[:message] # => "Hello Dave"
+  #   result.to_h      # => {:message=>"Hello Dave"}
   #
   #   result = SayHello.call
-  #   result.failure? # => true
-  #   result.success? # => false
-  #   result.message  # => nil
-  #   result.to_h     # => {}
+  #   result.class     # => Operatic::Failure
+  #   result.failure?  # => true
+  #   result.success?  # => false
+  #   result.to_h      # => {}
   def call
   end
 
-  # Convenience shortcut to the operation's {Result#failure!}.
-  def failure!(**data)
-    result.failure!(**data)
+  # Any data to be communicated via the operation's result should be added to
+  # this {Data} object.
+  #
+  # *Note*: This will be frozen when returned from an operation.
+  #
+  # @example
+  #   class SayHello
+  #     include Operatic
+  #
+  #     def call
+  #       data[:message] = "Hello #{@name}"
+  #     end
+  #   end
+  #
+  #   result = SayHello.call(name: 'Dave')
+  #   result.data.to_h     # => {:message=>"Dave"}
+  #   result.data.frozen?  # => true
+  #
+  # @return [Data]
+  def data
+    @data ||= self.class.data_class.new
   end
 
-  # An instance of {Result} or a subclass generated by
-  # {ClassMethods#result_attr}.
+  # Mark the operation as a failure and prevent further modification to the
+  # operation, its result, and its data.
   #
-  # @return [Result]
-  def result
-    @result ||= self.class.result_class.new
+  # @param kwargs [Hash<Symbol, anything>]
+  #
+  # @raise [FrozenError] if called more than once
+  def failure!(**kwargs)
+    @result = Failure.new(data.merge(kwargs))
+    freeze
+  end
+
+  # @return [self]
+  def freeze
+    @result.freeze
+    super
   end
 
-  # Convenience shortcut to the operation's {Result#success!}.
-  def success!(**data)
-    result.success!(**data)
+  # Mark the operation as a success and prevent further modification to the
+  # operation, its result, and its data.
+  #
+  # @param kwargs [Hash<Symbol, anything>]
+  #
+  # @raise [FrozenError] if called more than once
+  def success!(**kwargs)
+    @result = Success.new(data.merge(kwargs))
+    freeze
   end
 end

data/operatic.gemspec

@@ -14,12 +14,13 @@ Gem::Specification.new do |spec|
   spec.license       = 'MIT'
 
   spec.metadata = {
-    'changelog_uri'     => 'https://github.com/benpickles/operatic/blob/master/CHANGELOG.md',
+    'changelog_uri'     => 'https://github.com/benpickles/operatic/blob/main/CHANGELOG.md',
     'documentation_uri' => 'https://rubydoc.info/gems/operatic',
+    'rubygems_mfa_required' => 'true',
     'source_code_uri'   => 'https://github.com/benpickles/operatic',
   }
 
-  spec.required_ruby_version = '>= 2.5.0'
+  spec.required_ruby_version = '>= 2.7.0'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: operatic
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Ben Pickles
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-23 00:00:00.000000000 Z
+date: 2024-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -59,6 +59,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
@@ -71,6 +72,7 @@ files:
 - bin/console
 - bin/setup
 - lib/operatic.rb
+- lib/operatic/data.rb
 - lib/operatic/errors.rb
 - lib/operatic/result.rb
 - lib/operatic/version.rb
@@ -79,8 +81,9 @@ homepage: https://github.com/benpickles/operatic
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://github.com/benpickles/operatic/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/benpickles/operatic/blob/main/CHANGELOG.md
   documentation_uri: https://rubydoc.info/gems/operatic
+  rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/benpickles/operatic
 post_install_message:
 rdoc_options: []
@@ -90,14 +93,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: A minimal standard interface for your operations