sorbet_typed-short_circuit 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e3ce050f87a57dca5dccb55c765783dd0f84fb69579b93e892b77b87b850cd7
-  data.tar.gz: 7b26b4e2a158b895e711e3f2b5027e707c6e2fddf741157ab67878721a607eb2
+  metadata.gz: 9ea0d37eb463742ceea59c842b41be2e3b6a4d713a345ab75d2f5951253bcbbb
+  data.tar.gz: 03a370f7e2176db0571b0c9c26f5839be331e5f6dc923dca8275ed5ae30f6ced
 SHA512:
-  metadata.gz: 8fd009c77ba8a63fc5b5c092ede8a3116a1e4e69efb7966af4db5fb537686b5adf5f0f901852322b6b9e7212a9f6bc08da8dce6f4c81b4749d70023dae66e765
-  data.tar.gz: 36b79c49f3deb3d4f57d6cb78606f4b7187bf2bdfb3086ae29401fc0e1c3428b8ea3ee3294daec10d238341d7faaf1e742f3265a8578cfd0b95ca76891a3a85b
+  metadata.gz: abcea411c26737957a5a1574127fc69dccd5f7ead0628adf19056d4b5f1c70fa5df21fe58870fcdfd81f8172bb6b6a2090a967b10f5c8adf1b90be57545857e2
+  data.tar.gz: ce68d1218e72944b9b4bec1563d02f5e412e2bd6bf390c50763d5a119cf8a0c2290892bb3a38e7c65dc72bd4d18b9fb281f22a824522e4757a9280a146eb54e0

data/.cz.yaml

@@ -10,11 +10,12 @@ commitizen:
   name: cz_conventional_commits
   pre_bump_hooks:
     - mise x -- bundle install
+    - mise x -- bun install
     - mise run update
     - mise run format
   tag_format: v$version
   update_changelog_on_bump: true
-  version: 1.0.2
+  version: 1.0.3
   version_files:
     - lib/sorbet_typed/short_circuit/version.rb
   version_scheme: semver2

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## v1.0.3 (2025-11-18)
+
+### Fix
+
+- **deps**: update sorbet to v0.6.12778
+- **deps**: update sorbet to v0.6.12768
+- **deps**: update sorbet to v0.6.12765
+- **deps**: update sorbet to v0.6.12753
+- **deps**: update dependency markdownlint-cli2 to v0.19.0
+- **deps**: update dependency cspell to v9.3.1
+
 ## v1.0.2 (2025-11-10)
 
 ### Fix

data/README.md

@@ -1,3 +1,192 @@
 # SorbetTyped::ShortCircuit
 
 [![Gem Version](https://badge.fury.io/rb/sorbet_typed-short_circuit.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/sorbet_typed-short_circuit)
+
+Fully sorbet typed implementation of a fast-fail pattern based on signaling. It allows to chain multiple step-methods
+which each could fail and abort the whole process while keeping return values flexible to communicate eventual errors or
+further use some result. It should prevent `if...else` patterns after every part of a bigger process to ensure a step
+worked or bubble up failure message if not.
+
+Using this, you can break down more complex processes into smaller steps and make methods smaller and more readable
+while keeping full type safety.
+
+Inspiration for this comes from [dry-monads](https://dry-rb.org/gems/dry-monads/). The focus lies on strict type-safety
+while iteratively calling different steps of a bigger process and not relying on any instance-state or custom DSL.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Step Method Signature](#step-method-signature)
+  - [Signaling a failure](#signaling-a-failure)
+  - [Circuit Interface](#circuit-interface)
+  - [Passing Circuit Breakers as Method Parameters](#passing-circuit-breakers-as-method-parameters)
+  - [Nesting Circuits](#nesting-circuits)
+- [Development](#development)
+- [Contributing](#contributing)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add sorbet_typed-short_circuit
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install sorbet_typed-short_circuit
+```
+
+## Usage
+
+The following examples demonstrate the basics of how you can use this gem. For a detailed look at what you can and
+cannot do, you could look at [the type checker specs](spec/typechecking/sorbet_typed/short_circuit_spec.rb) and
+[usage specs](lib/sorbet_typed/short_circuit_spec.rb).
+
+### Basic Usage
+
+Initialize a new circuit with defined Success- and Failure-Type and call the run method. This method takes a block which
+gets a `CircuitBreaker` as parameter. The circuit breaker stops the block execution early, if it receives a `Shorted`
+signal.
+
+```ruby
+circuit = SorbetTyped::ShortCircuit[
+  Symbol,          # this will be the return type, when the block executes successfully
+  T::Array[String] # this will be the type of the Signal-Payload, when the block exits early
+].new
+
+result = circuit.run do |circuit_breaker|
+  foo = circuit_breaker.(get_foo)      # breaks the block, if `get_foo` returns a shorted signal. Otherwise returns a predictable success type.
+  bar = circuit_breaker.(do_bar(foo:)) # breaks the block, if `do_bar` returns a shorted signal.
+
+  transform_baz(bar:) # must return the success type or a shorted signal. CircuitBreaker not needed, because it is the last block statement
+end
+
+T.reveal_type(result) # => T.any(Symbol, SorbetTyped::ShortCircuit::Signals::Shorted[T::Array[String]])
+
+if result.is_a? SorbetTyped::ShortCircuit::Signals::Shorted
+  T.reveal_type(result.payload) # => T::Array[String]
+else
+  T.reveal_type(result) # => Symbol
+end
+```
+
+### Step Method Signature
+
+For step methods to be useful for the circuit breaker, they should return a union of any type you want to return and a
+shorted signal corresponding to the circuits failure type. Passing a signal type with unfitting payload type, will
+result in a type error.
+
+```ruby
+extend T::Sig
+
+sig { returns(T.any(String, SorbetTyped::ShortCircuit::Signals::Shorted[T::Array[String]])) }
+def get_foo
+  # ...
+end
+```
+
+### Signaling a failure
+
+You can generate a shorting signal using the `::short` method of the `SorbetTyped::ShortCircuit` class. Passing this
+signal to a circuit breaker will breaker the corresponding circuit. The payload type of the signal will be automatically
+inferred from the passed parameter.
+
+```ruby
+extend T::Sig
+
+sig { params(foo: String).returns(T.any(String, SorbetTyped::ShortCircuit::Signals::Shorted[T::Array[String]])) }
+def do_bar(foo:)
+  if foo == 'foo'
+    return 'bar'
+  else
+    SorbetTyped::ShortCircuit.short(['Unexpected value for foo:', foo])
+  end
+end
+```
+
+### Circuit Interface
+
+After initializing a circuit, it will respond to the following methods:
+
+- `#run` => Run a number of methods and use the circuit breaker to exit early. Returns either a successful value or the
+  shorted signal
+- `#run_without_signal` => Like run, but already extracts the signal payload on failure. Useful, if you don't want to
+  use the return value for flow-control. E.g. when success and failure use the same type, like a custom result-object
+  that gets filled with different information depending on the outcome.
+- `#last_run_short_circuited?` => `true` or `false`, depending on the outcome of the last run. Not really useful with
+  sorbet, as you cannot use it for flow control. But it's there.
+
+### Passing Circuit Breakers as Method Parameters
+
+Because the gems implementation relies heavily on generics and uses a raise/rescue pattern to implement the early exit,
+there are few edge-cases where directly using internal classes like the `CircuitBreaker` would allow to return different
+types than originally defined. This would introduce bugs, as static typing is circumvented and runtime type checks catch
+them pretty late, as generics get removed from runtime checks.
+
+To circumvent this, the custom error and the circuit breaker class are private constants, making accidental access
+harder.
+
+If you want to build some abstractions around the short circuit class, that need the circuit breaker to be passed around
+to some method, you cannot use its private class within the type signature. Instead, use
+`SorbetTyped::ShortCircuit::CircuitBreakerType`, which is a module without any behavior, but the circuit breaker
+fulfills it and can be passed as parameter to methods accepting this type.
+
+```ruby
+extend T::Sig
+
+sig { params(circuit_breaker: SorbetTyped::ShortCircuit::CircuitBreakerType[String]).returns(T.any(NilClass, SorbetTyped::ShortCircuit::Signals::Shorted[String])) }
+def foo(circuit_breaker:)
+  circuit_breaker.([SorbetTyped::ShortCircuit.short('shorted'), nil].sample)
+end
+
+SorbetTyped::ShortCircuit[NilClass, String].new.run do |circuit_breaker|
+  foo(circuit_breaker:)
+end
+```
+
+### Nesting Circuits
+
+It is possible to nest circuits. Especially when splitting your logic over multiple methods, each of them might use a
+circuit themselves to portray a part of the process. When doing this, each circuit creates its own circuit breaker,
+which can only break its original circuit. This is to prevent accidentally breaking inner circuits using outer circuit
+breakers, leading to incorrect types being returned.
+
+```ruby
+SorbetTyped::ShortCircuit[String, Symbol].new.run do |outer_circuit_breaker|
+  SorbetTyped::ShortCircuit[Integer, NilClass].new.run do |inner_circuit_breaker|
+    outer_circuit_breaker.(SorbetTyped::ShortCircuit.short(:failure)) # shorted signal must fulfill failure type of the outer circuit
+
+    # this will never be reached, as the breaker always gets a shorted signal.
+    # Sorbet detects this as unreachable
+    'foo'
+  end
+
+  # this will never be reached, as the outer breaker used within the inner
+  # circuit will still break the outer circuit. But sorbet cannot statically
+  # detect this as unreachable.
+  'bar'
+end
+```
+
+## Development
+
+The project uses [mise-en-place](https://mise.jdx.dev/) as development tool.
+
+After checking out the repo, run `mise run setup` to install dependencies. Then, run `mise test` to run the tests. You
+can also run `mise task ls` for a list of available tasks.
+
+RSpec is used as test suite. Spec files can and should be placed right beside their associated class files.
+
+Use the command `mise run console` (or `./bin/console`) to start an interactive ruby console session with the gem
+already loaded.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, run
+`mise run deploy`, which will update the version number, create a release commit, tag it and push the built gem to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and merge requests are welcome on GitLab at
+[gitlab.com/sorbet_typed/short_circuit](https://gitlab.com/sorbet_typed/short_circuit).

data/lib/sorbet_typed/short_circuit/version.rb

@@ -6,7 +6,7 @@
 # -- Disabled, because this file gets required in gemspec, where zeitwerk is not active
 module SorbetTyped
   class ShortCircuit
-    VERSION = '1.0.2'
+    VERSION = '1.0.3'
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sorbet_typed-short_circuit
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Richard Kramer
@@ -18,7 +18,7 @@ dependencies:
         version: '0.6'
     - - "<="
       - !ruby/object:Gem::Version
-        version: 0.6.12731
+        version: 0.6.12778
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -28,7 +28,7 @@ dependencies:
         version: '0.6'
     - - "<="
       - !ruby/object:Gem::Version
-        version: 0.6.12731
+        version: 0.6.12778
 description: ''
 email:
 - mail@richardkramer.de