tron 1.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0231e5a13e707acc3ec83ffc50af2cb846b01c31ba8e2bb9fc105e78d30bd60e
-  data.tar.gz: b3ab4cd46c20a71bfc2673345f5da04ca0a388e2141c259387976952ddd7c983
+  metadata.gz: dc919787c5b549b14e26fc8d2d2a1cfd601bfbf6320751e0e4862d23856ec604
+  data.tar.gz: 74e32cc0cd310b830bb58bb5a92c4e44f4a966d9271557ad7482337051d8dcf5
 SHA512:
-  metadata.gz: 187817f794d517f5c176f2c719344485df1afaca69cd32caf4e94b271f38a6a80e9dd0f328e2368bc0762985e7acf711b1f77c47fb77621e77e65080101a084f
-  data.tar.gz: 80811f5605325a75668bdbe9e8de95f18eb481ccd094e2f4b10f6a772b4fb483c876d34c06906b42e89ad8fafffea375d1620d4a0d111e4a1d40f067f34eed04
+  metadata.gz: 82a40a2046b62244b66cf7dbc52210215359b9f61112bd4836363b65491f7aec939be457d9a67de6bc7093cd9bdfc7676074a4cc791ba14a64389d18891c429f
+  data.tar.gz: 51149e095d5bf173eafeb4a99f46b4890bc47f6dcee8b8c8cbe4337ca59f5c94df436073b263aa2d1b152330a3e50d5654f15d0193728d174164e715f00e2923

data/README.md

@@ -1,21 +1,18 @@
 [![Gem Version](https://img.shields.io/gem/v/tron.svg)](https://rubygems.org/gems/tron)
-[![Build Status](https://travis-ci.org/halo/tron.svg?branch=master)](https://travis-ci.org/halo/tron)
+[![Build Status](https://github.com/halo/tron/actions/workflows/main.yml/badge.svg)](https://github.com/halo/tron/actions)
 [![License](http://img.shields.io/badge/license-MIT-blue.svg)](http://github.com/halo/tron/blob/master/LICENSE.md)
 
 ## TL;DR
 
 Tron is a minimalistic combination of a [monad](https://www.morozov.is/2018/09/08/monad-laws-in-ruby.html) and [value object](https://madeintandem.com/blog/creating-value-objects-in-ruby/), implemented in [a few lines](https://github.com/halo/tron/blob/master/lib/tron.rb) of code.
 
-Return `Tron.success(:it_worked)` or `Tron.failure(:aww_too_bad)` from a method to explain why and how it succeded/failed. That returns an immutable Struct (value object) that responds to `result.success?` and `result.failure?`. 
-
-The reason is accessible in `result.success #=> :it_worked`. You can add more metadata as a second argument: `Tron.failure(:nopes, error_code: 404)` which you can access like a Struct: `result.error_code #=> 404`.
-
-Chaining can make your code cleaner: `result.on_success { download }.on_failure { show_message }`
+* Return `Tron.success(:it_worked)` or `Tron.failure(:aww_too_bad)` from a method, to explain why and how it succeded or failed. That returns an immutable Data (value object) that responds to `result.success?` and `result.failure?`.
+* Add metadata as a second argument: `Tron.failure(:nopes, error_code: 404)` which you then can access: `result.error_code #=> 404`.
+* The result can also be queried with `result.success #=> :it_worked` and `result.failure #=> nil`.
+* Chaining can make your code cleaner: `result.on_success { download }.on_failure { show_message }`
 
 ## Introduction
 
-
-
 Imagine you have a class like this:
 
 ```ruby
@@ -42,7 +39,7 @@ class User
     if @users.delete id
       Tron.success :user_deleted, user: user
     else
-      Tron.success :deletion_failed, id: id
+      Tron.success :already_deleted, id: id # Notice the success here
     end
 
   rescue ConnectionError
@@ -51,7 +48,7 @@ class User
 end
 ```
 
-One could even take it a step further and write it like this:
+One could break the functionality apart into smaller pieces:
 
 ```ruby
 class User
@@ -64,13 +61,13 @@ class User
   def self.check_id_syntax(id)
     return Tron.failure(:id_missing) unless id
     return Tron.failure(:invalid_id, id: id) unless id.match /[a-f]{8}/
-    
+
     Tron.success :id_looks_good
   end
 
   def self.delete_user(id)
     user = @users[id]
-    
+
     if @users.delete id
       Tron.success :user_deleted, user: user
     else
@@ -83,11 +80,20 @@ class User
 end
 ```
 
-## So what are the benefits?
+On a side-note, the data object can be passed on further with modifications, that's due to the way `Data` object work.
 
-### 1. It will give you robust and predictable code
+```ruby
+result = Tron.success(:api_not_responding, reason: :password_not_accepted)
+
+result.with(code: :could_not_delete_user)
+  # => "#<data failure=:could_not_delete_user, reason=:password_not_accepted>"
+```
 
-Tron will give you this consistent, implementation-unaware, programming convention:
+## So, what are the benefits?
+
+### 1. An internal API that doesn't change over time
+
+Tron will give you a consistent, implementation-unaware, programming convention. That means that you can decide later, what constitutes a success or a failure, without changing the way the result is handled. You could also add metadata after-the-fact and the following code would still work fine:
 
 ```ruby
 result = User.delete 42
@@ -99,7 +105,7 @@ else
 end
 ```
 
-The result is just a Struct:
+The result is just an instance of Data:
 
 ```ruby
 result = User.delete 42
@@ -114,9 +120,7 @@ result.failure # => :deletion_failed_badly
 
 # Access immutable metadata
 result.message # => "..."
-result.inspect # => "#<struct failure=:alright, user_id=42, message='...'>"
-
-result.message.upcase! # => modification raises an exception
+result.inspect # => "#<data failure=:alright, user_id=42, message='...'>"
 ```
 
 ### 2. If will give you better tests
@@ -138,11 +142,20 @@ class Product
 end
 ```
 
-You cannot simply test for the `false` as expected return value because it could mean anything. Tron helps you to check the response objects for every case.
+You cannot simply test for `false` as expected return value, because it could mean anything. Tron helps you to check the response objects for every case. Data objects even support deconstruction for `case` statements.
 
 ### 3. It gives you documentation
 
-While the code you're writing becomes slightly more verbose, that verbosity translates directly into documenation. You see immediately what each line is doing.
+While the code you're writing becomes slightly more verbose, that verbosity translates directly into documentation. You see immediately what each line is doing.
+
+## Upgrading from 2.0.0 to 3.0.0
+
+* You will need to use at least Ruby `3.2`
+* The result object doesn't respond to collection methods any more, such as `result[:some_key]` or `result.to_a`, but it's unlikely that you relied on them in the first place.
+
+## Upgrading from 1.x.x to 2.0.0
+
+* `1.2.0` and `2.0.0` are identical, except that all deprecations have been removed and don't work any more.
 
 ## Upgrading from 0.x.x to 1.x.x
 
@@ -157,12 +170,16 @@ Tron is a complete rewrite of its predecessor [operation](https://github.com/hal
 
 ## Requirements
 
-* Ruby >= 2.3.0
+* Ruby >= 3.2.0
+
+## Development
+
+Clone the repository, run `bundle install` and run the tests with `bundle exec rake`.
 
 ## Copyright
 
-MIT 2015-2019 halo. See [MIT-LICENSE](http://github.com/halo/tron/blob/master/LICENSE.md).
+MIT halo. See [MIT-LICENSE](http://github.com/halo/tron/blob/master/LICENSE.txt).
 
 ## Caveats
 
-* There are no setter methods in the returned Struct, so you cannot overwrite the metadata. The values are also frozen, so you don't accidentally modify the attributes in-place. However, they are not deep-frozen, so an object may still be modified if you're ignorant.
+* There are no setter methods in the returned Data, so you cannot overwrite the metadata. But you can use `Data#with` to essentially clone the object and change values.

data/lib/tron/version.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Tron
-  module VERSION #:nodoc:
-    MAJOR = 1
-    MINOR = 2
+  module VERSION # :nodoc:
+    MAJOR = 3
+    MINOR = 0
     TINY  = 0
     PRE = nil
 

data/lib/tron.rb

@@ -2,12 +2,9 @@
 
 require 'tron/version'
 
-require 'tron/resultable' # Legacy
-require 'tron/success' # Legacy
-require 'tron/failure' # Legacy
-
+# Return data objects that can indicate success or failure.
 module Tron
-  def self.success(code, attributes = {}) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+  def self.success(code, attributes = {}) # rubocop:disable Metrics/MethodLength
     code.respond_to?(:to_sym) ||
       raise(ArgumentError, 'Tron.success must be called with a Symbol as first argument')
 
@@ -15,12 +12,10 @@ module Tron
       raise(ArgumentError, 'The second argument (metadata) for Tron.success must respond to #keys')
 
     attributes.respond_to?(:values) ||
-      raise(ArgumentError, 'The second argument (metadata) for Tron.success must respond to #values')
-
-    Struct.new(:success, *attributes.keys) do
-      undef_method :[]=
-      members.each { |member| undef_method :"#{member}=" }
+      raise(ArgumentError,
+            'The second argument (metadata) for Tron.success must respond to #values')
 
+    Data.define(:success, *attributes.keys) do
       def success?
         true
       end
@@ -33,13 +28,6 @@ module Tron
         nil
       end
 
-      def code
-        warn 'DEPRECATION WARNING: Calling `#code` on a Tron object is deprecated and will be removed in Tron 2.0.0. ' \
-             "Please use `#success` instead. Called from `#{caller.first}`"
-
-        success
-      end
-
       def on_success(proc = nil, &block)
         (proc || block).call self
       end
@@ -50,7 +38,7 @@ module Tron
     end.new code.to_sym, *attributes.values
   end
 
-  def self.failure(code, attributes = {}) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+  def self.failure(code, attributes = {}) # rubocop:disable Metrics/MethodLength
     code.respond_to?(:to_sym) ||
       raise(ArgumentError, 'Tron.failure must be called with a Symbol as first argument')
 
@@ -58,12 +46,10 @@ module Tron
       raise(ArgumentError, 'The second argument (metadata) for Tron.failure must respond to #keys')
 
     attributes.respond_to?(:values) ||
-      raise(ArgumentError, 'The second argument (metadata) for Tron.failure must respond to #values')
-
-    Struct.new(:failure, *attributes.keys) do
-      undef_method :[]=
-      members.each { |member| undef_method :"#{member}=" }
+      raise(ArgumentError,
+            'The second argument (metadata) for Tron.failure must respond to #values')
 
+    Data.define(:failure, *attributes.keys) do
       def success?
         false
       end
@@ -76,13 +62,6 @@ module Tron
         nil
       end
 
-      def code
-        warn 'DEPRECATION WARNING: Calling `#code` on a Tron object is deprecated and will be removed in Tron 2.0.0. ' \
-             "Please use `#failure` instead. Called from `#{caller.first}`"
-
-        failure
-      end
-
       def on_success(_ = nil)
         self
       end

metadata

@@ -1,90 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: tron
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 3.0.0
 platform: ruby
 authors:
 - halo
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2016-11-29 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: guard-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: hashie
-  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: rb-fsevent
-  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: 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'
+date: 2023-08-25 00:00:00.000000000 Z
+dependencies: []
 description: General-purpose method return objects that can be chained. Think minimalistic
   value object monads. Heavily inspired by the `deterministic` gem, but much much
   more light-weight.
-email: 
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - README.md
 - lib/tron.rb
-- lib/tron/failure.rb
-- lib/tron/resultable.rb
-- lib/tron/success.rb
 - lib/tron/version.rb
 homepage: https://github.com/halo/tron
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -92,15 +34,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.4.18
+signing_key:
 specification_version: 4
 summary: General-purpose method return objects that can be chained.
 test_files: []

data/lib/tron/failure.rb

@@ -1,13 +0,0 @@
-module Tron
-  class Failure
-    include Resultable
-
-    def on_success(_ = nil)
-      self
-    end
-
-    def on_failure(proc = nil, &block)
-      (proc || block).call
-    end
-  end
-end

data/lib/tron/resultable.rb

@@ -1,65 +0,0 @@
-module Tron
-  module Resultable
-    attr_reader :metadata
-
-    def self.included(receiver)
-      receiver.extend ::Tron::Resultable::ClassMethods
-    end
-
-    module ClassMethods
-      # Convenience wrapper
-      def call(code, metadata = nil)
-        new code: code, metadata: metadata
-      end
-    end
-
-    def initialize(code: nil, metadata: nil)
-      @code     = code
-      @metadata = metadata
-      warn 'DEPRECATION WARNING: As of Tron 1.0.0 calls to `Tron::Success.call` and `Tron::Failure.call` are deprecated. ' \
-           'They will be removed in Tron 2.0.0. Please migrate using `Tron.success` and `Tron.failure`. ' \
-           "See github.com/halo/tron Called in:: `#{caller[2]}`"
-    end
-
-    def success?
-      is_a? ::Tron::Success
-    end
-
-    def failure?
-      is_a? ::Tron::Failure
-    end
-
-    def code
-      return if @code.to_s == ''
-
-      @code.to_s.to_sym
-    end
-
-    # Convenience Wrapper
-    def object
-      metadata[:object] || metadata['object']
-    rescue StandardError
-      nil
-    end
-
-    def meta
-      if defined? ::Hashie::Mash
-        metamash
-      else
-        metadata
-      end
-    end
-
-    private
-
-    def metamash
-      if metadata.respond_to? :each_pair
-        ::Hashie::Mash.new metadata
-      elsif metadata
-        metadata
-      else
-        ::Hashie::Mash.new
-      end
-    end
-  end
-end

data/lib/tron/success.rb

@@ -1,13 +0,0 @@
-module Tron
-  class Success
-    include Resultable
-
-    def on_success(proc = nil, &block)
-      (proc || block).call
-    end
-
-    def on_failure(_ = nil)
-      self
-    end
-  end
-end