debounced 0.1.19 → 0.1.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5469038458279f90317b22acd88274c9a9cd5ddfe7d932e0fba6141230da1f65
-  data.tar.gz: 2776dc85b634f88d5f9ec7f4903de124a092455e25cffba08b91aaab903d7667
+  metadata.gz: '08e33800aa43c78d6be5abffcda05d1ca70e46436531f42f79193cbf1ab86059'
+  data.tar.gz: 455c57c30a34f260aeb6adf2e61c45c13b190d13b8e4236f324f6a703beab655
 SHA512:
-  metadata.gz: 9559170057bc4e13012e8d3d7234d1d2e2d1ed9eaa7100c8b2120b5c5b7b0d57cebfd4aa7e881b059bb9a6475b1dd45c4854467a883d09f7e88e159636faea4f
-  data.tar.gz: 5dadd3b4312c8985a2e3ad44b7aceb948250031bd9ca0e26da903211a42dc7a9ff0b26f57fa3e30062a05947c7738af6b999c809548a1781ccfe08176be0fb13
+  metadata.gz: 32a872b4f22b473ec19890db74d264a11931fc810c57d83f9d14e1ce1ff18f4eb2f5403b74d45feb16fdf27cd236886e19ba18f9096d6009bcc0a6aed574ce93
+  data.tar.gz: fabd72e50c1b94cbb4fcf2677306c360f8eb299e9eff14b7acb380b1737722e54e2ee5ec03ea58d76cdb82427cc5dca0b36542367748a30833ec288d3c553be8

data/README.md

@@ -1,6 +1,7 @@
 # Debounced
 
-A Ruby gem that provides a NodeJS-based event debouncing service for Ruby applications. It uses the JavaScript micro event loop to efficiently debounce events.
+Efficient debouncing mechanism for Ruby events. Use it for rate limiting, deduplication, or other 
+scenarios where you want to wait for a certain amount of time before processing a given event.
 
 ## Installation
 
@@ -26,15 +27,7 @@ $ gem install debounced
 
 This gem requires Node.js to be installed on your system, as it uses a Node.js server to handle the debouncing logic. You'll need:
 
-- Node.js >= 14.0.0
-- npm (to install the required node packages)
-
-After installing the gem, run:
-
-```bash
-$ cd $(bundle show debounced)
-$ npm install
-```
+- Node.js >= 20.0.0
 
 ## Usage
 
@@ -44,51 +37,70 @@ $ npm install
 # config/initializers/debounced.rb
 Debounced.configure do |config|
   config.socket_descriptor = '/tmp/my_app.debounceEvents'
+  config.wait_timeout = 3 # idle timeout in seconds for a given activity descriptor
 end
 ```
 
 ### Starting the server
 
-You can start the debounce server with:
+Start the nodeJS debounce server with:
 
 ```bash
-$ bundle exec debounced-server
+$ bundle exec debounced:server
 ```
 
-Or in your application code:
+In your Ruby application code:
 
 ```ruby
 require 'debounced'
 
-# Start the listener thread
+# Start a background thread to receive notification that events are ready to be handled after debounce wait is complete
 proxy = Debounced::ServiceProxy.new
-listener_thread = proxy.listen
+proxy.listen
 
-# Debounce an event
+# Define your event class; create a helper method that will produce a Debounced::Callback object, which 
+# is used to notify the server that the event is ready to be handled
 class MyEvent
-  attr_reader :attributes
+  attr_reader :test_id
 
-  def initialize(data)
-    @attributes = data
+  def initialize(test_id:)
+    @test_id = test_id
   end
 
-  def self.publish(data)
-    # Publish logic here
-    puts "Publishing event with data: #{data.inspect}"
+  def publish
+    # put logic here to publish the event after debouncing
+    puts "Publishing event: #{inspect}"
+  end
+  
+  def debounce_callback
+    Debounced::Callback.new(
+      class_name: self.class.name,
+      params: { test_id: },
+      method_name: 'publish',
+      method_params: []
+    )
   end
 end
 
-event = MyEvent.new({ id: 1, message: "Hello World" })
-proxy.debounce_event("my-event-123", event, 5) # Debounce for 5 seconds
+event = MyEvent.new({ test_id: "Hello World" })
+
+# request the server to debounce the event, ignoring it if another event with the 
+# same descriptor arrives before the timeout
+proxy.debounce_activity("my-event-123", 5, event.debounce_callback)
+# 2 seconds later
+proxy.debounce_activity("my-event-123", 5, event.debounce_callback)
+# 4 seconds later
+proxy.debounce_activity("my-event-123", 5, event.debounce_callback)
+# 5 seconds later the event is published!
+# > Publishing event: #<MyEvent:0x00007f9b1b8b3b40 @test_id="Hello World">
 ```
 
 ## How It Works
 
 1. The gem creates a Unix socket for communication between Ruby and Node.js
-2. When you call `debounce_event`, it sends the event to the Node.js server
-3. The Node.js server keeps track of events with the same descriptor
-4. If another event with the same descriptor arrives before the timeout, it resets the timer
-5. When the timeout expires, it sends the event back to Ruby to be published
+2. When you call `debounce_activity`, it sends the event to the Node.js server
+3. The Node.js server restarts a timer every time an event with a given activity_descriptor is received
+4. When the timeout expires, it sends the event back to Ruby to be published
 
 ## License
 

data/lib/debounced/callback.rb

@@ -3,7 +3,18 @@ require 'debug'
 module Debounced
   class Callback
 
-    attr_reader :class_name, :params, :method_name, :method_params
+    attr_accessor :class_name, :params, :method_name, :method_params
+
+    ###
+    # Create a new callback object
+    # @param class_name [String] the name of the class to call the method on
+    # @param params [Hash] a hash of parameters to pass to the class initializer (optional)
+    # @param method_name [String] the name of the method to call.
+    #   If the method is a class method, it should be prefixed with a "."
+    #   If it is an instance method, it should be prefixed with a "#"
+    # @param method_params [Array] an array of parameters to pass to the method
+    # @return [Debounced::Callback]
+    # @note @params is ignored if the method is a class method
     def initialize(class_name:, params:, method_name:, method_params:)
       @class_name = class_name.to_s
       @params = params || {}
@@ -11,7 +22,7 @@ module Debounced
       @method_params = method_params || []
     end
 
-    def self.json_create(data)
+    def self.parse(data)
       new(
         class_name: data['class_name'],
         params: data['params'],
@@ -30,9 +41,14 @@ module Debounced
     end
 
     def call
-      Object.const_get(class_name)
-            .new(**params.transform_keys(&:to_sym))
-            .send(method_name, *method_params)
+      klass = Object.const_get(class_name)
+      message = method_name[1..-1] # strip of method_name prefix, either "." or "#"
+      target = klass
+      if method_name[0] == '#'
+        target = klass.new(**params.transform_keys(&:to_sym))
+      end
+      target.send(message, *method_params)
     end
+
   end
 end

data/lib/debounced/service_proxy.rb

@@ -116,7 +116,7 @@ module Debounced
     end
 
     def instantiate_callback(data)
-      Callback.json_create(data)
+      Callback.parse(data)
     end
 
     def socket_descriptor

data/lib/debounced/version.rb

@@ -1,3 +1,3 @@
 module Debounced
-  VERSION = "0.1.19"
+  VERSION = "0.1.21"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: debounced
 version: !ruby/object:Gem::Version
-  version: 0.1.19
+  version: 0.1.21
 platform: ruby
 authors:
 - Gary Passero