hidden_hooks 1.1.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88532a44bde6fdd20a6bcd02505060ec0abffd7fe55e815c3dd82a80d0be8819
-  data.tar.gz: 118bd2af55f7472686deaf3c93f9008b8d3fd820dab2082d6f032103f4f72583
+  metadata.gz: '0738dd3eb4b4db1b211e7cf2f93837ae8b5e23e47dd1b5108b8590fc8eea870c'
+  data.tar.gz: 4c208ee06f8e57a049daaf990727ccd9d6cba79c422ec2efa3ec7340443d08b1
 SHA512:
-  metadata.gz: 6c7b53ac8c04c1b6d02dbd6af42d7c7d6e6d93a60faea4c23ffcbf615e6744d3626678b01a4d8d4c4b53846263e188aedfcfb39ea9e22d36c61ddbdb4c98fa9e
-  data.tar.gz: c81d8c1c686af906141279a02067a90a131445506a6c83c9fd967bd582b7868a6da54e780f08c1cba3d44da920ae8796e2be2a8c2b47611792647eb92da39434
+  metadata.gz: 107ba5f389928174c5fbd28a402224b639c45ba52f9bec7e619cbba5c61c78a8088d55c4430bac076abd68383c932b225b1891b7f3f8774806eebef58ec5bc9b
+  data.tar.gz: 443fe108faca6c89796b5dcb5772ffad28e87c9c457b8f109b8077f3cf3a73911063059703e26401b037d1d15b3f03c6bfae253b3103b8f39a1e8e79b29f23f5

data/CHANGELOG.md

@@ -8,6 +8,19 @@
 ### Bug fixes
 )-->
 
+## 1.3.0 2025-03-03
+
+### New features
+
+- Added `sole` and `present` keyword parameter for hook invocation.
+- Made hook invocation return the result values.
+
+## 1.2.0 2025-02-04
+
+### New features
+
+- Added the `context` keyword parameter for hooks.
+
 ## 1.1.2 2025-01-28
 
 ### Bug fixes

data/README.md

@@ -120,12 +120,77 @@ end
 
 #### Interface Declaration
 
-A class `C` declares the interface through `HiddenHooks[C]`. Calling a method on the returned proxy will call every hook that someone else defined, forwarding any argument. 
+A class `C` declares the interface through `HiddenHooks[C]`. Calling a method on the returned proxy will call every hook that someone else defined, forwarding any argument.
+
+```ruby
+class User
+  def confirm!
+    HiddenHooks[User].before_confirmation self
+    @confirmed = true
+    HiddenHooks[User].after_confirmation self
+  end
+end
+```
+
+The results are returned as an array:
+
+```ruby
+def valid_password? password
+  HiddenHooks[User].valid_password?(self, password).all?
+end
+```
+
+You can enforce that at least one hook be present passing `present: true` to `HiddenHooks.[]`:
+
+```ruby
+HiddenHooks[User, present: true].valid_password?(self, password).all?
+# => There must be at least one hook `valid_password?` defined for class `User` (HiddenHooks::AtLeastOneHookRequired)
+```
+
+You can also enforce that no more than one hook be present passing `sole: true`:
+
+```ruby
+HiddenHooks[User, sole: true].valid_password?(self, password).all?
+# => There must be at most one hook `valid_password?` defined for class `User` (HiddenHooks::SoleHookExceeded)
+```
+
+`sole:` defaults to `false`, and `present` defaults to whatever value `sole` has, so by default nothing is checked, and if you pass `sole: true` both checks are performed.
+
+If both `sole:` and `present:` are true, then we can be certain that there is one and only one hook, so the single result value is unwrapped:
+
+```ruby
+HiddenHooks[URI].signature_code(uri)
+# => ["1234"]
+HiddenHooks[URI, sole: true].signature_code(uri)
+# => "1234"
+```
 
 #### Hook Definition
 
 Whenever you want to define a hook, you simply call `HiddenHooks.hook_up`. Inside the block, you can call any method and pass it a class and a block: the block will become a hook for that class.
 
+```ruby
+class Admin
+  HiddenHooks.hook_up do
+    before_confirmation User do |user|
+      Admin.first.notify! "#{user.name} is being confirmed."
+    end
+  end
+end
+```
+
+You can provide a callable `context`, which will be invoked with the same parameters as the hook. Its result will be bound to `self` inside the hook.
+
+```ruby
+class Admin
+  HiddenHooks.hook_up do
+    before_confirmation User, context: proc { Admin.first } do |user|
+      notify! "#{user.name} is being confirmed."
+    end
+  end
+end
+```
+
 #### Rails Callbacks
 
 Thanks to the [callback objects](https://guides.rubyonrails.org/active_record_callbacks.html#callback-objects) system, in Rails you can simply pass the proxy to the callback methods:

data/lib/hidden_hooks/at_least_one_hook_required.rb

@@ -0,0 +1,4 @@
+module HiddenHooks
+  class AtLeastOneHookRequired < StandardError
+  end
+end

data/lib/hidden_hooks/sole_hook_exceeded.rb

@@ -0,0 +1,4 @@
+module HiddenHooks
+  class SoleHookExceeded < StandardError
+  end
+end

data/lib/hidden_hooks/version.rb

@@ -1,3 +1,3 @@
 module HiddenHooks
-  VERSION = '1.1.2'
+  VERSION = '1.3.0'
 end

data/lib/hidden_hooks.rb

@@ -1,5 +1,8 @@
 require_relative 'hidden_hooks/version'
 
+require_relative 'hidden_hooks/at_least_one_hook_required'
+require_relative 'hidden_hooks/sole_hook_exceeded'
+
 require 'active_support/core_ext/module/attribute_accessors'
 
 module HiddenHooks
@@ -9,10 +12,18 @@ module HiddenHooks
                instance_reader: false
 
   class SetUpProxy
-    private
+  private
 
-    def method_missing hook, klass, &block
-      ::HiddenHooks.hooks[klass][hook] << block
+    def method_missing hook, klass=nil, context: nil, &block
+      ::HiddenHooks.hooks[klass][hook] << if context.nil?
+                                            block
+                                          else
+                                            proc do |*args, **kwargs, &hook_block|
+                                              context
+                                                .call(*args, **kwargs, &hook_block)
+                                                .instance_exec(*args, hook_block, **kwargs, &block)
+                                            end
+                                          end
     end
 
     def respond_to_missing? _, _=false
@@ -21,14 +32,31 @@ module HiddenHooks
   end
 
   class LookUpProxy
-    def initialize klass
+    def initialize klass=nil, sole: false, present: sole
+      @klass = klass
       @hooks = ::HiddenHooks.hooks[klass]
+      @sole = sole
+      @present = present
     end
 
-    private
+  private
+
+    def method_missing(hook_name, *args, **kwargs, &block)
+      hooks = @hooks[hook_name]
+
+      if @present && hooks.empty?
+        raise HiddenHooks::AtLeastOneHookRequired,
+              "There must be at least one hook `#{hook_name}` defined for class `#{@klass}`"
+      end
+
+      if @sole && hooks.size > 1
+        raise HiddenHooks::SoleHookExceeded,
+              "There must be at most one hook `#{hook_name}` defined for class `#{@klass}`"
+      end
 
-    def method_missing(hook, *args, **kwargs, &block)
-      @hooks[hook].each { _1.call(*args, **kwargs, &block) }
+      hooks
+        .map { |hook| hook.call(*args, **kwargs, &block) }
+        .then { |results| (@sole && @present) ? results.first : results }
     end
 
     def respond_to_missing? _, _=false
@@ -36,12 +64,12 @@ module HiddenHooks
     end
   end
 
-  def self.hook_up(&block)
+  def self.hook_up &block
     SetUpProxy.new.instance_exec(&block)
   end
 
-  def self.[] klass
-    LookUpProxy.new klass
+  def self.[](...)
+    LookUpProxy.new(...)
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hidden_hooks
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Moku S.r.l.
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-01-28 00:00:00.000000000 Z
+date: 2025-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -42,6 +42,8 @@ files:
 - hidden_hooks.gemspec
 - lib/hidden_hooks.rb
 - lib/hidden_hooks/active_record.rb
+- lib/hidden_hooks/at_least_one_hook_required.rb
+- lib/hidden_hooks/sole_hook_exceeded.rb
 - lib/hidden_hooks/version.rb
 homepage: https://github.com/moku-io/hidden_hooks
 licenses: