downstream 1.6.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e21fb36c5475aee1858bcdbfa9f99db92a62059f74605906f95034e8661df0e
-  data.tar.gz: 0bf3825da8014d5a0daed6cbdcf21303d11b9657af42d96e55e5fe4488c0981b
+  metadata.gz: 6117947c15849270ac37c5d1a02877b5903884f224cb87bb10fca63f8535c0b1
+  data.tar.gz: 11fcc576683c11ed8bd56fd6f2abc22d7adfd56d39cd33162a41f706debebc0b
 SHA512:
-  metadata.gz: b8b80db17bd482235eff304bf087c1eecd0e3a1a605cf4590f3c19cae725c1170cd8404dcab2b0603d67a726e53e08fc140069b38a4dcaf9e490a816a04e5b4d
-  data.tar.gz: 188c160278a9578615796d867833b1377bc1664b5ad1f750d4cd21d6eea3828eef956bf0a9570c0889d0b6a1b240c783df9bdb9c340768bc89893b3bdf00a392
+  metadata.gz: 8228d50071d6929e3ec64cdfe1a46c81a7a4045b043329044d731e746a7da0e4f1363a70420d04e5db1c5a66166bc8732245c1c10ccfcec4563ce382b277becc
+  data.tar.gz: 30e6fbf37793b809158a128db70cd24121d39ac83510ad024db68874d38485f5b576b9d9d1a4d5775092401ccc8f22dae66b7d557836065055da974922479f60

data/README.md

@@ -59,6 +59,22 @@ Each event has predefined (_reserved_) fields:
 
 Events are stored in `app/events` folder.
 
+You can also define events using the Data-interface:
+
+```ruby
+ProfileCreated = Downstream::Event.define(:user)
+
+# or with an explicit identifier
+ProfileCreated = Downstream::Event.define(:user) do
+  self.identifier = "user.profile_created"
+end
+```
+
+Date-events provide the same interface as regular events but use Data classes for keeping event payloads (`event.data`) and are frozen (as well as their derivatives, such as `event.to_h`).
+
+> [!NOTE]
+> Data-events are only available in Ruby 3.2+.
+
 ### Publish events
 
 To publish an event you must first create an instance of the event class and call `Downstream.publish` method:
@@ -127,6 +143,26 @@ store.subscribe OnProfileCreated::DoThat, async: {queue: :low_priority}
 
 **NOTE:** all subscribers are synchronous by default
 
+### Subscriber classes
+
+You can also use subscriber objects based on `Downstream::Subscriber` class. For example:
+
+```ruby
+class CRMSubscriber < Downstream::Subscriber
+  def profile_created(event)
+    # handle "profile_created" event
+  end
+
+  def project_created(event)
+    # handle "project_created" event
+  end
+end
+
+store.subscribe CRMSubscriber, async: true
+```
+
+The subscriber object allows you to subscribe to multiple events at once: each public method is considered an event handler for the same named event.
+
 ## Testing
 
 You can test subscribers as normal Ruby objects.

data/lib/downstream/data_event.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Downstream
+  class DataEvent < Event
+    class << self
+      attr_writer :data_class
+
+      def data_class
+        return @data_class if @data_class
+
+        @data_class = superclass.data_class
+      end
+
+      undef_method :attributes
+      undef_method :defined_attributes
+    end
+
+    def initialize(event_id: nil, **attrs)
+      @event_id = event_id || SecureRandom.hex(10)
+      @data = self.class.data_class.new(**attrs)
+      freeze
+    end
+
+    def to_h
+      {
+        type:,
+        event_id:,
+        data: data.to_h.freeze
+      }.freeze
+    end
+  end
+end

data/lib/downstream/engine.rb

@@ -6,6 +6,19 @@ module Downstream
   class Engine < ::Rails::Engine
     config.downstream = Downstream.config
 
+    ::GlobalID::Locator.use "downstream" do |gid|
+      params = gid.params.each_with_object({}) do |(key, value), memo|
+        memo[key.to_sym] = if value.is_a?(String) && value.start_with?("gid://")
+          GlobalID::Locator.locate(value)
+        else
+          value
+        end
+      end
+
+      gid.model_name.constantize
+        .new(event_id: gid.model_id, **params)
+    end
+
     config.to_prepare do
       Downstream.pubsub.reset
       ActiveSupport.run_load_hooks("downstream-events", Downstream)

data/lib/downstream/event.rb

@@ -1,18 +1,5 @@
 # frozen_string_literal: true
 
-GlobalID::Locator.use "downstream" do |gid|
-  params = gid.params.each_with_object({}) do |(key, value), memo|
-    memo[key.to_sym] = if value.is_a?(String) && value.start_with?("gid://")
-      GlobalID::Locator.locate(value)
-    else
-      value
-    end
-  end
-
-  gid.model_name.constantize
-    .new(event_id: gid.model_id, **params)
-end
-
 module Downstream
   class Event
     extend ActiveModel::Naming
@@ -26,7 +13,7 @@ module Downstream
       def identifier
         return @identifier if instance_variable_defined?(:@identifier)
 
-        @identifier = name.underscore.tr("/", ".")
+        @identifier = name.underscore.tr("/", ".").gsub(/_event$/, "")
       end
 
       # define store readers
@@ -56,6 +43,20 @@ module Downstream
           end
       end
 
+      def define(*fields, &)
+        fields.each do |field|
+          raise ArgumentError, "#{field} is reserved" if RESERVED_ATTRIBUTES.include?(field)
+        end
+
+        data_class = ::Data.define(*fields)
+
+        Class.new(DataEvent, &).tap do
+          _1.data_class = data_class
+
+          _1.delegate(*fields, to: :data)
+        end
+      end
+
       def i18n_scope
         :activemodel
       end
@@ -94,7 +95,7 @@ module Downstream
     end
 
     def to_global_id
-      new_data = data.each_with_object({}) do |(key, value), memo|
+      new_data = data.to_h.each_with_object({}) do |(key, value), memo|
         memo[key] = if value.respond_to?(:to_global_id)
           value.to_global_id
         else

data/lib/downstream/rspec/have_published_event.rb

@@ -74,7 +74,7 @@ module Downstream
     end
 
     def failure_message
-      (+"expected to publish #{event_class.identifier} event").tap do |msg|
+      "expected to publish #{event_class.identifier} event".tap do |msg|
         msg << " #{message_expectation_modifier}, but haven't published"
       end
     end

data/lib/downstream/subscriber.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Downstream
+  class Subscriber
+    class << self
+      # All public names are considered event handlers
+      # (same concept as action_names in controllers/mailers)
+      def event_names
+        @event_names ||= begin
+          # All public instance methods of this class, including ancestors
+          methods = (public_instance_methods(true) -
+            # Except for public instance methods of Base and its ancestors
+            Downstream.public_instance_methods(true) +
+            # Be sure to include shadowed public instance methods of this class
+            public_instance_methods(false)).uniq.map(&:to_s)
+          methods.to_set
+        end
+      end
+
+      # Downstream subscriber interface
+      def call(event)
+        new.process_event(event)
+      end
+    end
+
+    def process_event(event)
+      # TODO: callbacks? instrumentation?
+      # TODO: namespaced events?
+      public_send(event.type, event)
+    end
+  end
+end

data/lib/downstream/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Downstream
-  VERSION = "1.6.0"
+  VERSION = "2.0.0"
 end

data/lib/downstream.rb

@@ -8,6 +8,8 @@ require "after_commit_everywhere"
 
 require "downstream/config"
 require "downstream/event"
+require "downstream/data_event"
+require "downstream/subscriber"
 require "downstream/pubsub_adapters/abstract_pubsub"
 require "downstream/subscriber_job"
 
@@ -27,18 +29,26 @@ module Downstream
       subscriber ||= block if block
       raise ArgumentError, "Subsriber must be present" if subscriber.nil?
 
-      identifier = construct_identifier(subscriber, to)
+      construct_identifiers(subscriber, to).map do
+        pubsub.subscribe(_1, subscriber, async: async)
+      end.then do
+        next _1.first if _1.size == 1
 
-      pubsub.subscribe(identifier, subscriber, async: async)
+        _1
+      end
     end
 
     # temporary subscriptions
     def subscribed(subscriber, to: nil, &block)
       raise ArgumentError, "Subsriber must be present" if subscriber.nil?
 
-      identifier = construct_identifier(subscriber, to)
+      construct_identifiers(subscriber, to).map do
+        pubsub.subscribed(_1, subscriber, &block)
+      end.then do
+        next _1.first if _1.size == 1
 
-      pubsub.subscribed(identifier, subscriber, &block)
+        _1
+      end
     end
 
     def publish(event)
@@ -47,28 +57,34 @@ module Downstream
 
     private
 
-    def construct_identifier(subscriber, to)
-      to ||= infer_event_from_subscriber(subscriber) if subscriber.is_a?(Module)
+    def construct_identifiers(subscriber, to)
+      to ||= infer_events_from_subscriber(subscriber) if subscriber.is_a?(Module)
 
       if to.nil?
         raise ArgumentError, "Couldn't infer event from subscriber. " \
                               "Please, specify event using `to:` option"
       end
 
-      identifier = if to.is_a?(Class) && Event >= to # rubocop:disable Style/YodaCondition
-        to.identifier
-      else
-        to
-      end
+      Array(to).map do
+        identifier = if _1.is_a?(Class) && Event >= _1 # rubocop:disable Style/YodaCondition
+          _1.identifier
+        else
+          _1
+        end
 
-      "#{config.namespace}.#{identifier}"
+        "#{config.namespace}.#{identifier}"
+      end
     end
 
-    def infer_event_from_subscriber(subscriber)
+    def infer_events_from_subscriber(subscriber)
+      if subscriber.is_a?(Class) && Subscriber >= subscriber # rubocop:disable Style/YodaCondition
+        return subscriber.event_names
+      end
+
       event_class_name = subscriber.name.split("::").yield_self do |parts|
         # handle explicti top-level name, e.g. ::Some::Event
         parts.shift if parts.first.empty?
-        # drop last part – it's a unique subscriber name
+        # drop last part—it's a unique subscriber name
         parts.pop
 
         parts.last.sub!(/^On/, "")

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: downstream
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 2.0.0
 platform: ruby
 authors:
 - merkushin.m.s@gmail.com
 - dementiev.vm@gmail.com
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: after_commit_everywhere
@@ -45,14 +44,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -109,8 +108,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -119,6 +116,7 @@ files:
 - README.md
 - lib/downstream.rb
 - lib/downstream/config.rb
+- lib/downstream/data_event.rb
 - lib/downstream/engine.rb
 - lib/downstream/event.rb
 - lib/downstream/pubsub_adapters/abstract_pubsub.rb
@@ -127,6 +125,7 @@ files:
 - lib/downstream/rspec.rb
 - lib/downstream/rspec/have_enqueued_async_subscriber_for.rb
 - lib/downstream/rspec/have_published_event.rb
+- lib/downstream/subscriber.rb
 - lib/downstream/subscriber_job.rb
 - lib/downstream/version.rb
 homepage: https://github.com/palkan/downstream
@@ -139,7 +138,6 @@ metadata:
   homepage_uri: http://github.com/palkan/downstream
   source_code_uri: http://github.com/palkan/downstream
   allowed_push_host: https://rubygems.org
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -147,15 +145,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Straightforward way to implement communication between Rails Engines using
   the Publish-Subscribe pattern