tron 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3d033d6fa697cd4da7d443028e7ca891676266f8e41ecf00be057d52e84e0e0
-  data.tar.gz: 222f4a27b2acd1f887ee5deeb6e41b475f45c027c82663174129d7d83db6e5f5
+  metadata.gz: dc919787c5b549b14e26fc8d2d2a1cfd601bfbf6320751e0e4862d23856ec604
+  data.tar.gz: 74e32cc0cd310b830bb58bb5a92c4e44f4a966d9271557ad7482337051d8dcf5
 SHA512:
-  metadata.gz: cbb6fe573460da64aac5a59da8148fc766dfc73152cb8f887950fd4b99e90c7e2f9c0ebabed249d44f6e5b28dc912e48506866f29d0b44a65e84a7318f9339c8
-  data.tar.gz: 497c6f228706f96d9157a9600de35af4bd2e432177ed7c5e66c6c37e10f6dc74a874467a1b8ca235066619e36a3db8bea51c390bd5e540a2ab641e1dfe5f2617
+  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
@@ -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.
+
+```ruby
+result = Tron.success(:api_not_responding, reason: :password_not_accepted)
 
-### 1. It will give you robust and predictable code
+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,15 +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.
+* `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
 
@@ -161,12 +170,16 @@ Tron is a complete rewrite of its predecessor [operation](https://github.com/hal
 
 ## Requirements
 
-* Ruby >= 2.5.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,6 +1,8 @@
+# frozen_string_literal: true
+
 module Tron
-  module VERSION #:nodoc:
-    MAJOR = 2
+  module VERSION # :nodoc:
+    MAJOR = 3
     MINOR = 0
     TINY  = 0
     PRE = nil

data/lib/tron.rb

@@ -2,8 +2,9 @@
 
 require 'tron/version'
 
+# 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')
 
@@ -11,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
@@ -39,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')
 
@@ -47,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

metadata

@@ -1,103 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: tron
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - halo
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-30 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'
-- !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'
+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: []
@@ -108,8 +24,9 @@ files:
 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
@@ -117,15 +34,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.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: []