both_is_good 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0a0f01162c428c642c314b4abfcef3d918315c7816fc2b3ee1d31cdf276eb18
-  data.tar.gz: b8a4aa017737830cfe38dd8b47be2bca99d0b42258df9312c5f91dd410457ecd
+  metadata.gz: 51b74df537030d143e21234302934cf0893cf9cb5e476c1eaf11d7451454b986
+  data.tar.gz: bda32fe8c40fe83abcbb8e416f1f3e2ce4f465ec6f125b9f5a28264305df20c8
 SHA512:
-  metadata.gz: 04f815942d66db366b44ec374ffabeba0094b1b64c41483b7a328ca4732191eae62075b2402fb4313bb7504468b5f0aac95e04f3e8029b906f4aedad618da5bd
-  data.tar.gz: a7a640ba54f642e98a0f67c06b3745cfe47a9b75b9bc5399691001e88139a6ef4282b96d9cb6b82cdbcf52cb1811a3b708b9b21eb8a84cc2edd680a90b59f4c5
+  metadata.gz: a368aa4dccf34706bbb6d0ca5b563cedd9af13920580775cf44cb7c5c135439e67b0b0fb306f6c9f0e467d21c19779ebb0c2ba69be15de89aec1a050c7e10fd7
+  data.tar.gz: 5d682bcfd654cae15d627aa53a51c0819a73874b70c6336df0177177e75ad1478e5ecb06f17724ce8537b71f7bec15f35452ea2180fe23115b34e170093e5949

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.4.0 (unreleased)
+
+### Breaking changes
+
+* `primary:` and `secondary:` are renamed to `original:` and `replacement:`
+  throughout the public API.
+* The internal alias prefixes change from
+  `_bothisgood_primary_` / `_bothisgood_secondary_` to
+  `_bothisgood_original_` / `_bothisgood_replacement_`.
+
+### New features
+
+* Added `switch:` parameter, for swapping the implementation based on
+  feature-flags.
+
+## 0.3.1
+
+* Allow the supplied `original` / `replacement` methods to be private.

data/README.md

@@ -1,19 +1,20 @@
 # BothIsGood
 
-This gem adds a module to include into classes, supplying a convenient, concise way
-to implement multiple versions of the same method, and _run them both_. Then you
-can still _use_ the old implementation, but get an alert or log message if the new
-version ever produces a different result.
+This gem adds a module to include into classes, supplying a convenient, concise
+way to implement multiple versions of the same method, and _run them both_. Then
+you can still _use_ the old implementation, but get an alert or log message if
+the new version ever produces a different result.
 
-This is not a new concept; `scientist` pioneered the approach in 2016. But scientist
-is moderately _heavy_, and takes significant effort to use, so I've ended up implementing
-lightweight dual-implementation libraries multiple times; this time I'm publishing
-it so I won't have to do so again later!
+This is not a new concept; `scientist` pioneered the approach in 2016. But
+scientist is moderately _heavy_, and takes significant effort to use, so I've
+ended up implementing lightweight dual-implementation libraries multiple times;
+this time I'm publishing it so I won't have to do so again later!
 
 ## Inline Invocation
 
-The "simplest" way to use BothIsGood is 'inline' - no configuration object, you just
-supply all of the needed options on the `implemented_twice` call in place.
+The "simplest" way to use BothIsGood is 'inline' - no configuration object,
+you just supply all of the needed options on the `implemented_twice` call in
+place.
 
 ```ruby
 include BothIsGood
@@ -21,21 +22,23 @@ include BothIsGood
 def foo_one = implementation(details)
 def foo_two = more_implementation(details)
 
-# A minimal call. Note that with no global configuration this is not very valuable,
-# since if the implementations disagree, there's no hook implemented to _tell you_ that.
-implemented_twice(:foo, primary: :foo_one, secondary: :foo_two)
+# A minimal call. Note that with no global configuration this is not very
+# valuable, since if the implementations disagree, there's no hook implemented
+# to _tell you_ that.
+implemented_twice(:foo, original: :foo_one, replacement: :foo_two)
 
 # A complex call using all of the available options:
 implemented_twice(
   :foo,
-  primary: :foo_one,
-  secondary: :foo_two,
+  original: :foo_one,
+  replacement: :foo_two,
   rate: 0.01,
+  switch: ->(klass, name) { FeatureFlags.enabled?(:"enable_#{name}") },
   comparator: ->(val_one, val_two) { Math.abs(val_one - val_two) < 0.01 },
-  on_mismatch: ->(val_one, val_two) { LOGGER.warn("result mismatch on Foo#foo_one vs Foo#foo_two: #{val_one} | #{val_two}") },
+  on_mismatch: ->(val_one, val_two) { LOGGER.warn("mismatch: #{val_one} | #{val_two}") },
   on_compare: ->(val_one, val_two) { LOGGER.warn("comparing #{val_one} to #{val_two}") },
-  on_primary_error: ->(err, args) { LOGGER.warn("calling foo_one with #{args.to_json} produced error #{err.class.name}") },
-  on_secondary_error: ->(err, args) { LOGGER.warn("calling foo_two with #{args.to_json} produced error #{err.class.name}") },
+  on_primary_error: ->(err, args) { LOGGER.warn("primary error #{err.class.name}") },
+  on_secondary_error: ->(err, args) { LOGGER.warn("secondary error #{err.class.name}") },
   on_hook_error: ->(err) { LOGGER.warn("OH NO! #{err.class.name}: #{err.message}") }
 )
 ```
@@ -43,48 +46,63 @@ implemented_twice(
 The method takes these parameters:
 
 * The (only) positional parameter is the name of the method it will implement.
-  This _can_ match the 'primary' or 'secondary' name (but not both, obviously),
-  and if it does, `implemented_twice` will alias the existing method out of the
-  way (to `_bothisgood_primary_#{name}` or `_bothisgood_secondary_#{name}`).
-* The `primary:` parameter specifies a method name that will be called _and have
-  its result used as the result of the final method_ regardless of the comparison
-  outcome. Errors from the primary method are bubbled up as usual.
-* The `secondary:` parameter specifies a method name that will be called for
-  comparison's sake (though not necessarily every time). Errors raised from the
-  secondary method are swallowed.
-* The `rate:` parameter (default 1.0) specifies what fraction of the calls should
-  bother evaluating the secondary implementation for comparison. If the
-  implementation is costly (makes significant database calls, for example) and/or
-  invoked frequently, you probably want a lower rate, at least in production.
-* The `comparator:` parameter takes a callable, and yields two arguments to it
-  (the results of the two implementations); its result is either truthy or falsey.
+  This _can_ match the `original:` or `replacement:` name (but not both),
+  and if it does, `implemented_twice` will alias the existing method out of
+  the way (to `_bothisgood_original_#{name}` or
+  `_bothisgood_replacement_#{name}`).
+* The `original:` parameter specifies a method name that will be called _and
+  have its result used as the return value_ regardless of the comparison
+  outcome. Errors from the original method are bubbled up as usual.
+* The `replacement:` parameter specifies a method name that will be called for
+  comparison's sake (though not necessarily every time). Errors raised from
+  the replacement method are swallowed.
+* The `rate:` parameter (default 1.0) specifies what fraction of the calls
+  should bother evaluating the shadow implementation for comparison. If the
+  implementation is costly (makes significant database calls, for example)
+  and/or invoked frequently, you probably want a lower rate in production.
+* The `switch:` parameter takes a callable with arity 0 or 2. When it returns
+  a truthy value, the roles swap: replacement becomes the return value and
+  original becomes the shadow (called at `rate` for comparison). Arity 2
+  receives the target's actual class and the method name as a symbol, making
+  it straightforward to drive from a feature-flag system:
+
+  ```ruby
+  switch: ->(klass, name) { FeatureFlags.enabled?(:"enable_#{klass}_#{name}") }
+  ```
+
+  `switch` can be set on a shared `Configuration` object so you only have to
+  define it once.
+* The `comparator:` parameter takes a callable, and yields two arguments to
+  it (the results of the two implementations); its result is truthy or falsey.
   By default, comparison is done using `==`.
-* The `on_mismatch:` parameter takes a callable (lamba or Proc generally). It will
-  yield the two values being compared, but can yield additional details depending
-  on the arity of the callable; arities 2, 3, and 4 are all supported, and will be
-  yielded the arguments supplied, and then a Hash of the implementation method
-  names like `{primary: :foo_one, secondary: :foo_two}`. It will be invoked any
-  time the results of the two implementations _differ_.
-* The `on_compare:` parameter takes the same shaped argument, but will be fired
-  any time both implementations are evaluated (so every time, unless `rate` is set)
+* The `on_mismatch:` parameter takes a callable (lambda or Proc generally).
+  It supports arities 2, 3, and 4. The first two arguments are always the
+  _primary_ result (the one being returned) and the _secondary_ result (the
+  shadow). **When `switch` is active, these are `(replacement, original)`,
+  not `(original, replacement)`.** Arity 3 also receives a names hash like
+  `{primary: :foo_one, secondary: :foo_two}` reflecting the current role
+  assignment. Arity 4 additionally receives the call args array before the
+  names hash. It fires any time the results _differ_.
+* The `on_compare:` parameter takes the same shaped argument, but fires any
+  time both implementations are evaluated (every time unless `rate` is set).
 * The `on_primary_error:` parameter takes a callable and yields 1, 2, or 3
-  arguments to it, depending on its arity - those arguments are the StandardError
-  instance rescued, the args supplied to the implementation (as an array,
-  potentially with a Hash arg at the end for any kwargs), and the name of the
-  primary method. The exception will be re-raised after handling.
-* The `on_secondary_error:` parameter behaves identically (yielding the secondary
-  method name), but secondary exceptions are _not_ re-raised.
+  arguments: the StandardError rescued, the args supplied (as an array,
+  potentially with a Hash at the end for kwargs), and the name of the primary
+  method. The exception will be re-raised after handling. With `switch`
+  active, "primary" is the replacement method.
+* The `on_secondary_error:` parameter behaves identically (yielding the
+  secondary method name), but secondary exceptions are _not_ re-raised.
+  With `switch` active, "secondary" is the original method.
 * The `on_hook_error:` parameter is a callable that will be yielded _one_
-  parameter (the StandardError instance), and is invoked if an error is _raised_
-  during one of the other hooks. None of us write bug-free code, and the callbacks
-  supplied to `implemented_twice` are no exception. Those errors will be swallowed
-  if `on_hook_error` is supplied (unless your hook raises the error!), but will be
-  bubbled otherwise.
+  parameter (the StandardError instance), and is invoked if an error is
+  _raised_ during one of the other hooks. Those errors will be swallowed if
+  `on_hook_error` is supplied (unless your hook re-raises!), and bubbled
+  otherwise.
 
-`implemented_twice` can additionally be called with three positional parameters;
-the second parameter is used as the `primary` method name, and the third parameter
-is used as the `secondary` method name. That means that, if you use a configuration
-object, you can just:
+`implemented_twice` can additionally be called with three positional
+parameters; the second is used as the `original` method name, and the third
+as `replacement`. That means that, if you use a configuration object, you can
+just:
 
 ```ruby
 include BothIsGood
@@ -92,12 +110,12 @@ include BothIsGood
 def foo_one = implementation(details)
 def foo_two = more_implementation(details)
 
-# defines `foo`, using `foo_one` as the primary implementation and `foo_two` as secondary.
+# defines `foo`, using `foo_one` as original and `foo_two` as replacement.
 implemented_twice :foo, :foo_one, :foo_two
 ```
 
-If it is called with _two_ positional parameters, it will use the first argument
-as both the final method name _and_ the primary implementation.
+If called with _two_ positional parameters, the first is used as both the
+final method name _and_ the original implementation.
 
 ```ruby
 include BothIsGood
@@ -105,21 +123,22 @@ include BothIsGood
 def foo = implementation(details)
 def foo_two = more_implementation(details)
 
-# Defines `foo`, using `foo` as the primary implementation and `foo_two` as secondary.
-# In the process, the original `foo` method is redefined as `_bothisgood_primary_foo`.
+# Defines `foo`, using `foo` as original and `foo_two` as replacement.
+# The original `foo` method is aliased to `_bothisgood_original_foo`.
 implemented_twice :foo, :foo_two
 ```
 
 ## Configuration
 
-All of those parameters aside from the positional, `primary`, and `secondary` ones
-can be configured globally, or onto a BothIsGood::Configuration object, to avoid
-having to supply them constantly.
+All parameters aside from the positional, `original:`, and `replacement:` ones
+can be configured globally, or onto a `BothIsGood::Configuration` object, to
+avoid having to supply them constantly.
 
 ```ruby
 # Global configuration
 BothIsGood.configure do |config|
   config.rate = 0.5
+  config.switch = ->(klass, name) { FeatureFlags.enabled?(:"enable_#{name}") }
   config.on_compare = ->(a, b) { LOGGER.puts "compared!" }
   config.on_hook_error = ->(e) { LOGGER.puts "bad -.-" }
 end
@@ -127,16 +146,15 @@ end
 # Local configuration - starting values are taken from the global config
 MY_BIG_CONFIG = BothIsGood::Configuration.new
 MY_BIG_CONFIG.rate = 0.7
-MY_BIG_CONFIG.on_secondary_error = ->(a, b) { LOGGER.puts "No" }
+MY_BIG_CONFIG.on_secondary_error = ->(e) { LOGGER.puts "No" }
 
 module MyFoo
   include BothIsGood
   self.both_is_good_configure(MY_BIG_CONFIG)
 end
 
-
-# In-class configuration - starting values are taken from the global config, or the
-# supplied config object if one is given.
+# In-class configuration - starting values are taken from the global config,
+# or the supplied config object if one is given.
 module MyBar
   include BothIsGood
   self.both_is_good_configure(rate: 0.02)

data/lib/both_is_good/configuration.rb

@@ -2,6 +2,7 @@ module BothIsGood
   class Configuration
     DEFAULTS = {
       rate: 1.0,
+      switch: nil,
       on_mismatch: nil,
       on_compare: nil,
       on_primary_error: nil,
@@ -32,6 +33,11 @@ module BothIsGood
       @rate = value
     end
 
+    def switch=(value)
+      validate_hook!(:switch, value, [0, 2])
+      @switch = value
+    end
+
     def on_mismatch=(value)
       validate_hook!(:on_mismatch, value, [2, 3, 4])
       @on_mismatch = value

data/lib/both_is_good/implemented_twice.rb

@@ -1,8 +1,8 @@
 module BothIsGood
   class ImplementedTwice
-    def initialize(owner, primary:, secondary:, **opts)
+    def initialize(owner, original:, replacement:, **opts)
       base = owner.both_is_good_configuration
-      @local_config = LocalConfiguration.new(base, owner:, primary:, secondary:, **opts)
+      @local_config = LocalConfiguration.new(base, owner:, original:, replacement:, **opts)
     end
 
     def call(target, *args, **kwargs)

data/lib/both_is_good/invocation.rb

@@ -18,8 +18,18 @@ module BothIsGood
 
     private
 
-    memoize def primary = @config.primary
-    memoize def secondary = @config.secondary
+    memoize def switched?
+      if @config.switch.nil?
+        false
+      elsif @config.switch.arity == 0
+        @config.switch.call
+      else
+        @config.switch.call(@target.target_class, @target.method_name)
+      end
+    end
+
+    memoize def primary = switched? ? @config.replacement : @config.original
+    memoize def secondary = switched? ? @config.original : @config.replacement
 
     memoize def trigger? = rand < @config.rate
 
@@ -38,8 +48,8 @@ module BothIsGood
       on_secondary_success
     end
 
-    memoize def primary_result = @target.send(@config.primary, *@args, **@kwargs)
-    memoize def secondary_result = @target.send(@config.secondary, *@args, **@kwargs)
+    memoize def primary_result = @target.instance.send(primary, *@args, **@kwargs)
+    memoize def secondary_result = @target.instance.send(secondary, *@args, **@kwargs)
 
     def on_primary_error(error)
       hook = @config.on_primary_error

data/lib/both_is_good/local_configuration.rb

@@ -1,14 +1,14 @@
 module BothIsGood
   class LocalConfiguration < Configuration
-    LOCAL_ATTRIBUTES = %i[primary secondary comparator].freeze
+    LOCAL_ATTRIBUTES = %i[original replacement comparator].freeze
 
     attr_reader(*LOCAL_ATTRIBUTES)
 
-    def initialize(base_config, owner:, primary:, secondary:, **opts)
+    def initialize(base_config, owner:, original:, replacement:, **opts)
       comparator = opts.delete(:comparator)
       super(base_config, **opts)
-      @primary = validated_method(owner, :primary, primary)
-      @secondary = validated_method(owner, :secondary, secondary)
+      @original = validated_method(owner, :original, original)
+      @replacement = validated_method(owner, :replacement, replacement)
       @comparator = validated_comparator(comparator)
     end
 
@@ -16,7 +16,7 @@ module BothIsGood
 
     def validated_method(owner, role, name)
       raise ArgumentError, "#{role} must not be nil" if name.nil?
-      unless owner.method_defined?(name)
+      unless owner.method_defined?(name) || owner.private_method_defined?(name)
         raise ArgumentError, "#{role} method #{name.inspect} is not defined on #{owner}"
       end
       name

data/lib/both_is_good/target.rb

@@ -0,0 +1,3 @@
+module BothIsGood
+  Target = Struct.new(:instance, :method_name, :target_class)
+end

data/lib/both_is_good/version.rb

@@ -1,3 +1,3 @@
 module BothIsGood
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/both_is_good.rb

@@ -1,4 +1,5 @@
 require_relative "both_is_good/memoization"
+require_relative "both_is_good/target"
 
 module BothIsGood
   def self.configuration = Configuration.global
@@ -23,13 +24,13 @@ module BothIsGood
       @both_is_good_configuration || BothIsGood.configuration
     end
 
-    def implemented_twice(*positional, primary: nil, secondary: nil, **opts)
-      implementer = DualImplementer.new(*positional, target: self, primary:, secondary:, **opts)
+    def implemented_twice(*positional, original: nil, replacement: nil, **opts)
+      implementer = DualImplementer.new(*positional, target: self, original:, replacement:, **opts)
       implementer.apply_aliases!
       runner = implementer.implementation
 
       define_method(implementer.name) do |*args, **kwargs|
-        runner.call(self, *args, **kwargs)
+        runner.call(BothIsGood::Target.new(self, implementer.name, self.class), *args, **kwargs)
       end
     end
   end
@@ -37,11 +38,11 @@ module BothIsGood
   class DualImplementer
     include Memoization
 
-    def initialize(*positional, target:, primary:, secondary:, **opts)
+    def initialize(*positional, target:, original:, replacement:, **opts)
       @target = target
       @positional = positional
-      @kw_primary = primary
-      @kw_secondary = secondary
+      @kw_original = original
+      @kw_replacement = replacement
       @opts = opts
 
       validate!
@@ -50,28 +51,28 @@ module BothIsGood
     attr_reader :positional, :target, :opts
 
     memoize def name = positional.first
-    memoize def primary = aliased_primary? ? :"_bothisgood_primary_#{name}" : original_primary
-    memoize def secondary = aliased_secondary? ? :"_bothisgood_secondary_#{name}" : original_secondary
+    memoize def original = aliased_original? ? :"_bothisgood_original_#{name}" : supplied_original
+    memoize def replacement = aliased_replacement? ? :"_bothisgood_replacement_#{name}" : supplied_replacement
 
     def apply_aliases!
-      target.alias_method(primary, name) if aliased_primary?
-      target.alias_method(secondary, name) if aliased_secondary?
+      target.alias_method(original, name) if aliased_original?
+      target.alias_method(replacement, name) if aliased_replacement?
     end
 
-    memoize def implementation = ImplementedTwice.new(target, primary:, secondary:, **opts)
+    memoize def implementation = ImplementedTwice.new(target, original:, replacement:, **opts)
 
     private
 
-    memoize def original_primary = @kw_primary || positional[-2]
-    memoize def original_secondary = @kw_secondary || positional.last
+    memoize def supplied_original = @kw_original || positional[-2]
+    memoize def supplied_replacement = @kw_replacement || positional.last
 
-    memoize def aliased_primary? = original_primary == name
-    memoize def aliased_secondary? = original_secondary == name
+    memoize def aliased_original? = supplied_original == name
+    memoize def aliased_replacement? = supplied_replacement == name
 
     def validate!
       validate_name_supplied!
-      validate_secondary_supplied!
-      validate_no_primary_secondary_match!
+      validate_replacement_supplied!
+      validate_no_original_replacement_match!
       validate_no_mixing!
       validate_no_extra_positional!
     end
@@ -81,20 +82,20 @@ module BothIsGood
       raise(ArgumentError, "the 'name' positional parameter is required")
     end
 
-    def validate_secondary_supplied!
-      return if @kw_secondary || positional.length >= 2
-      raise ArgumentError, "secondary is required, either as a positional argument or as a keyword argument"
+    def validate_replacement_supplied!
+      return if @kw_replacement || positional.length >= 2
+      raise ArgumentError, "replacement is required, either as a positional argument or as a keyword argument"
     end
 
-    def validate_no_primary_secondary_match!
-      return if original_primary != original_secondary
-      raise ArgumentError, "primary and secondary cannot be the same method"
+    def validate_no_original_replacement_match!
+      return if supplied_original != supplied_replacement
+      raise ArgumentError, "original and replacement cannot be the same method"
     end
 
     def validate_no_mixing!
       return if positional.length <= 1
-      return if @kw_primary.nil? && @kw_secondary.nil?
-      raise ArgumentError, "cannot mix positional and keyword primary:/secondary:"
+      return if @kw_original.nil? && @kw_replacement.nil?
+      raise ArgumentError, "cannot mix positional and keyword original:/replacement:"
     end
 
     def validate_no_extra_positional!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: both_is_good
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Eric Mueller
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-31 00:00:00.000000000 Z
+date: 2026-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -126,6 +126,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".standard.yml"
+- CHANGELOG.md
 - LICENSE
 - README.md
 - both_is_good.gemspec
@@ -135,6 +136,7 @@ files:
 - lib/both_is_good/invocation.rb
 - lib/both_is_good/local_configuration.rb
 - lib/both_is_good/memoization.rb
+- lib/both_is_good/target.rb
 - lib/both_is_good/version.rb
 homepage: https://github.com/nevinera/both_is_good
 licenses: