simple-result 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e32f46fc1e26c2db6e5590d44a2d5b94559d6139d678415f13f9b9894fb98bb1
+  data.tar.gz: d447f8140e20c734674a3e6edf62a1a6fcf7be8ba4fc8007f2c53667c9d8e2ac
+SHA512:
+  metadata.gz: e819e42f964243a839906ac6cfa603e43d9edd8692691ccde25a6aa888f8538e382f0b125d3648dc6ecf148b2c1408f3371ea396023965d36d67875514c1086f
+  data.tar.gz: bfe4bfe6a2e92b99c08a557fea5ca29ced83d04ad53e152325b83bc77ecd1045e164940bc54c3612a07868cea3c5a29e16c576b763ac8250303911171b002f12

data/README.md

@@ -0,0 +1,138 @@
+# SimpleResult
+
+A simple, idiomatic Ruby implementation of a response monad (`Success` or `Failure`) for handling success and failure states inspired by https://github.com/maxveldink/sorbet-result.
+
+This is a very simple implementation kept on purpose to be less than 100 LOC (currently at 60) and with no other dependencies than `zeitwerk`.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'simple_result'
+```
+
+## Usage
+
+The recommended usage is to use the `Success` and `Failure` helpers to create responses. You can also use the scoped classes 'SimpleResult::Success' and 'SimpleResult::Failure' if you want.
+
+### Basic Usage
+
+```ruby
+require 'simple_result'
+
+success = Success("Hello, World!")
+success.success? # => true
+success.payload  # => "Hello, World!"
+
+failure = Failure("Something went wrong")
+failure.failure? # => true
+failure.error    # => "Something went wrong"
+
+# Blank responses
+Success() # => Success with nil payload
+Failure() # => Failure with nil error
+```
+
+### Chaining Operations
+
+```ruby
+Success("hello")
+  .and_then { |value| value.upcase }
+  .and_then { |value| "#{value}!" }
+# => "HELLO!"
+
+# Failure short-circuiting
+Failure("error")
+  .and_then { |value| value.upcase }
+  .and_then { |value| "#{value}!" }
+# => Failure("error")
+```
+
+#### A more common case of chaining operations might look like this
+
+```ruby
+def validate(value)
+  # validation
+  Success(value)
+end
+
+def transform(value)
+  transformed_value = value.upcase
+
+  Success(transformed_value)
+end
+
+def present(value)
+  presenter = "#{value}!!"
+
+  Success(presenter)
+end
+
+validate("hello")
+  .and_then { |value| transform(value) }
+  .and_then { |value| present(value) }
+# => "HELLO!"
+
+# Or since Ruby 3.4 you can also use the implicit `it` block parameter
+validate("hello")
+  .and_then { transform(it) }
+  .and_then { present(it) }
+
+# or if you prefer to write without paranthesis in a more DSL like style:
+validate("hello")
+  .and_then { transform it }
+  .and_then { present it }
+```
+
+### Error Handling
+
+```ruby
+# Handle errors only when they occur
+Success("data").on_error { |error| puts "Error: #{error}" }
+# => Success("data") - block not called
+
+Failure("oops").on_error { |error| puts "Error: #{error}" }
+# => Prints "Error: oops", returns Failure("oops")
+```
+
+### Fallback Values
+
+The fallback will be called only when the result is nil or an error.
+Please be carefull when using blank Success and Failure values with `payload_or_fallback` because `Success().payload_or_fallback` will always return the fallback value.
+
+```ruby
+# Use payload or fallback
+Success("value").payload_or_fallback { "default" }
+# => "value"
+
+Success(nil).payload_or_fallback { "default" }
+# => "default"
+
+Failure("error").payload_or_fallback { "default" }
+# => "default"
+```
+
+## Development
+
+Run tests:
+
+```bash
+ruby test/test_simple_result.rb
+```
+
+Run RuboCop:
+
+```bash
+rubocop
+```
+
+Start an interactive console:
+
+```bash
+bin/console
+```
+
+## License
+
+The gem is available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/lib/simple_result/version.rb

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

data/lib/simple_result.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module SimpleResult
+  ResponseError = Class.new(StandardError)
+  ErrorNotPresentOnSuccess = Class.new(ResponseError)
+  PayloadNotPresentOnFailure = Class.new(ResponseError)
+  NotImplemented = Class.new(ResponseError)
+
+  Response = Data.define(:payload, :error) do
+    def initialize(payload: nil, error: nil) = super
+
+    def success? = raise NotImplemented, 'success? not implemented'
+    def failure? = raise NotImplemented, 'failure? not implemented'
+    def payload_or_fallback(&) = payload || yield
+    def and_then(&) = raise NotImplementedError, 'and_then not implemented'
+  end
+
+  class Success < Response
+    def self.blank               = new(payload: nil)
+    def initialize(payload: nil) = super(payload: payload, error: nil)
+
+    def success?   = true
+    def failure?   = false
+    def error      = raise(ResponseError, 'Error not present on success')
+
+    def and_then(&) = yield(payload)
+    def on_error(&) = self
+
+    def inspect = "#<data #{self.class.name} payload=#{payload.inspect}>"
+
+    def pretty_print(pp) = pp.text "#<data #{self.class.name} payload=#{payload.inspect}>"
+  end
+
+  class Failure < Response
+    def self.blank             = new(error: nil)
+    def initialize(error: nil) = super(payload: nil, error: error)
+
+    def success?   = false
+    def failure?   = true
+    def payload    = raise(ResponseError, 'Payload not present on failure')
+
+    def payload_or_fallback(&) = yield
+    def and_then(&) = self
+
+    def on_error(&)
+      yield(error)
+      self
+    end
+
+    def inspect = "#<data #{self.class.name} error=#{error.inspect}>"
+    def pretty_print(pp) = pp.text "#<data #{self.class.name} error=#{error.inspect}>"
+  end
+end
+
+def Success(payload = nil) = SimpleResult::Success.new(payload) # rubocop:disable Naming/MethodName -- These are helpers methods defined specifically like this to look similar with the classes
+def Failure(error = nil) = SimpleResult::Failure.new(error:) # rubocop:disable Naming/MethodName -- These are helpers methods defined specifically like this to look similar with the classes

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: simple-result
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lucian Ghinda
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: A one file less than 100LOC, idiomatic Ruby implementationof a response
+  monad for handling success and failure states
+email:
+- lucian@shortruby.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/simple_result.rb
+- lib/simple_result/version.rb
+homepage: https://github.com/lucianghinda/simple_result
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lucianghinda/simple_result
+  source_code_uri: https://github.com/lucianghinda/simple-result
+  changelog_uri: https://github.com/lucianghinda/web-author/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.4
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: A simple response monad implementation
+test_files: []