puremvc 1.0.0 → 1.0.1

data/lib/patterns/command/macro_command.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+# typed: true
+
+# macro_command.rb
+# PureMVC Ruby Multicore
+#
+# Copyright(c) 2025 Saad Shams <saad.shams@puremvc.org>
+# Your reuse is governed by the BSD 3-Clause License
+
+module PureMVC
+  # A base ICommand implementation that executes other ICommand instances.
+  #
+  # A MacroCommand maintains a list of ICommand class references called SubCommands.
+  #
+  # When <code>execute</code>is called, the MacroCommand instantiates and calls <code>execute</code>on each of its
+  # SubCommands in turn. Each SubCommand will be passed a reference to the original INotification that was passed to
+  # the MacroCommand's <code>execute</code>method.
+  #
+  # Unlike SimpleCommand, your subclass should not override <code>execute</code> but instead override
+  # <code>initialize_macro_command</code> calling <code>add_sub_command</code>once for each SubCommand to be executed.
+  #
+  # @see Controller
+  # @see Notification
+  # @see SimpleCommand
+  class MacroCommand < Notifier
+    # Constructor.
+    #
+    # You should not need to define a constructor,
+    # instead, override the <code>initialize_macro_command</code> method.
+    #
+    # If your subclass does define a constructor,
+    # be sure to call <code>super</code>
+    def initialize
+      super()
+      @sub_commands = []
+      initialize_macro_command
+    end
+
+    # Initialize the MacroCommand.
+    #
+    # In your subclass, override this method to
+    # initialize the MacroCommand's SubCommand list with
+    # ICommand factory references, like this:
+    #
+    # @example
+    #   def initialize_macro_command
+    #     add_sub_command  { FirstCommand.new }
+    #     add_sub_command  { SecondCommand.new }
+    #     add_sub_command  { ThirdCommand.new }
+    #   end
+    #
+    # Note that SubCommands may be any ICommand implementor;
+    # MacroCommands or SimpleCommands are both acceptable.
+    def initialize_macro_command; end
+
+    # Add a SubCommand.
+    # SubCommands will be called in First In/First Out (FIFO) order.
+    #
+    # @param factory [^() -> _ICommand] A block or callable that returns an instance of ICommand when called.
+    def add_sub_command(&factory)
+      @sub_commands << factory
+    end
+
+    # Execute this MacroCommand's SubCommands.
+    #
+    # The SubCommands will be called in First In/First Out (FIFO) order.
+    #
+    # @param notification [INotification] the notification object to be passed to each SubCommand.
+    def execute(notification)
+      while @sub_commands.any?
+        # @type factory: [^() -> ICommand]
+        factory = @sub_commands.shift
+
+        # @type var command: _ICommand
+        command = factory.call
+        command.initialize_notifier(@multiton_key)
+        command.execute(notification)
+      end
+    end
+  end
+end

data/lib/patterns/command/simple_command.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# simple_command.rb
+# PureMVC Ruby Multicore
+#
+# Copyright(c) 2025 Saad Shams <saad.shams@puremvc.org>
+# Your reuse is governed by the BSD 3-Clause License
+
+module PureMVC
+  # A base <code>ICommand</code>implementation.
+  #
+  # Subclasses should override the <code>execute</code>method, where business logic
+  # will handle the <code>INotification</code>.
+  #
+  # @see Controller
+  # @see Notification
+  # @see MacroCommand
+  class SimpleCommand < Notifier
+    # Fulfill the use-case initiated by the given <code>INotification</code>.
+    #
+    # In the Command Pattern, an application use-case typically begins with some user action,
+    # which results in an <code>INotification</code>being broadcast, handled by business logic in the
+    # <code>execute</code>method of an <code>ICommand</code>.
+    #
+    # @param notification [_INotification] the notification to handle
+    def execute(notification); end
+  end
+end

data/lib/patterns/facade/facade.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+# facade.rb
+# PureMVC Ruby Multicore
+#
+# Copyright(c) 2025 Saad Shams <saad.shams@puremvc.org>
+# Your reuse is governed by the BSD 3-Clause License
+
+module PureMVC
+  # A base Multiton <code>IFacade</code> implementation.
+  #
+  # @see Model
+  # @see View
+  # @see Controller
+  class Facade
+    # Message Constants
+    MULTITON_MSG = 'Facade instance for this Multiton key already constructed!'
+    private_constant :MULTITON_MSG
+
+    class << self
+      # The Multiton IFacade instanceMap.
+      # @return [Hash{String => IFacade}]
+      def instance_map = (@instance_map ||= {})
+
+      # Mutex used to synchronize access to the instance map for thread safety.
+      # @return [Mutex]
+      def mutex = (@mutex ||= Mutex.new)
+
+      # Facade Multiton Factory method.
+      #
+      # @param key [String] the unique key identifying the Multiton instance
+      # @param factory [^(String) -> _IFacade] the unique key passed to the factory block
+      # @return [IFacade] the Multiton instance of the Facade
+      def get_instance(key, &factory)
+        mutex.synchronize do
+          instance_map[key] ||= factory.call(key)
+        end
+      end
+
+      # Check if a Core is registered or not.
+      #
+      # @param key [String] the multiton key for the Core in question
+      # @return [Boolean] whether a Core is registered with the given <code>key</code>.
+      def has_core?(key)
+        instance_map.key?(key)
+      end
+
+      # Remove a Core.
+      #
+      # Removes the Model, View, Controller, and Facade
+      # instances associated with the given key.
+      #
+      # @param key [String] the key of the Core to remove
+      def remove_core(key)
+        mutex.synchronize do
+          Model.remove_model(key)
+          View.remove_view(key)
+          Controller.remove_controller(key)
+          instance_map.delete(key)
+        end
+      end
+    end
+
+    # Constructor.
+    #
+    # This <code>IFacade</code> implementation is a Multiton, so you should not call the constructor
+    # directly. Instead, use the static factory method and pass the unique key for this instance with factory:
+    # <code>PureMVC::Facade.get_instance(key) { |key| PureMVC::Facade.new(key) }</code>.
+    #
+    # @param key [String]
+    # @raise [RuntimeError] if an instance for this Multiton key has already been constructed.
+    def initialize(key)
+      raise MULTITON_MSG if self.class.instance_map[key]
+
+      self.class.instance_map[key] = self
+      @model = @view = @controller = nil
+      initialize_notifier(key)
+      initialize_facade
+    end
+
+    # Initialize the Multiton <code>Facade</code> instance.
+    #
+    # This method is called automatically by the constructor. Override it in your
+    # subclass to perform any subclass-specific initialization.
+    #
+    # @note Be sure to call <code>super.initialize_facade</code> when overriding.
+    def initialize_facade
+      initialize_model
+      initialize_controller
+      initialize_view
+    end
+
+    # Initialize the <code>Controller</code>.
+    #
+    # Called by the <code>initialize_facade</code> method.
+    #
+    # Override this method in your subclass of <code>Facade</code> if one or both of the following are true:
+    # - You wish to initialize a different <code>IController</code>.
+    # - You have <code>Commands</code> to register with the <code>Controller</code> at startup.
+    #
+    # If you don't want to initialize a different<code>IController</code>,call<code>super.initialize_controller()</code>
+    # at the beginning of your method, then register <code>Command</code>s.
+    def initialize_controller
+      @controller = Controller.get_instance(@multiton_key) { |key| Controller.new(key) }
+    end
+
+    # Initialize the <code>Model</code>.
+    #
+    # Called by the <code>initializeFacade</code> method.
+    #
+    # Override this method in your subclass of <code>Facade</code> if one or both of the following are true:
+    # - You wish to initialize a different <code>IModel</code>.
+    # - You have <code>Proxy</code>s to register with the Model that do not retrieve a reference to the
+    #   <code>Facade</code> at construction time.
+    #
+    # If you don't want to initialize a different <code>IModel</code>, call <code>super.initialize_model()</code> at
+    # the beginning of your method, then register <code>Proxy</code>s.
+    #
+    # Note: This method is <i>rarely</i> overridden; in practice you are more likely to use a <code>Command</code> to
+    # create and register <code>Proxy</code>s with the <code>Model</code>, since <code>Proxy</code>s with mutable data
+    # will likely need to send <code>INotification</code>s and thus will likely want to fetch a reference to the
+    # <code>Facade</code> during their construction.
+    def initialize_model
+      @model = Model.get_instance(@multiton_key) { |key| Model.new(key) }
+    end
+
+    # Initialize the <code>View</code>.
+    #
+    # Called by the <code>initializeFacade</code> method.
+    #
+    # Override this method in your subclass of <code>Facade</code> if one or both of the following are true:
+    # - You wish to initialize a different <code>IView</code>.
+    # - You have <code>Observers</code> to register with the <code>View</code>.
+    #
+    # If you don't want to initialize a different <code>IView</code>, call <code>super.initialize_view()</code> at the
+    # beginning of your method, then register <code>IMediator</code> instances.
+    #
+    # Note: This method is <i>rarely</i> overridden; in practice you are more likely to use a <code>Command</code> to
+    # create and register <code>Mediator</code>s with the <code>View</code>, since <code>IMediator</code> instances will
+    # need to send <code>INotification</code>s and thus will likely want to fetch a reference to the <code>Facade</code>
+    # during their construction.
+    def initialize_view
+      @view = View.get_instance(@multiton_key) { |key| View.new(key) }
+    end
+
+    # Register an <code>ICommand</code> with the <code>Controller</code> by Notification name.
+    #
+    # @param notification_name [String] name of the <code>INotification</code> to associate with <code>ICommand</code>
+    # @param factory [^<() -> ICommand>] a reference to the Class of the <code>ICommand</code>
+    def register_command(notification_name, &factory)
+      @controller&.register_command(notification_name, &factory)
+    end
+
+    # Check if a Command is registered for a given Notification
+    #
+    # @param notification_name [String] The name of the Notification to check
+    # @return [Boolean] whether a Command is currently registered for the given <code>notification_name</code>.
+    def has_command?(notification_name)
+      !!@controller&.has_command?(notification_name)
+    end
+
+    # Remove a previously registered <code>ICommand</code> to <code>INotification</code> mapping from the Controller.
+    #
+    # @param notification_name [String] the name of the <code>INotification</code> to remove the <code>ICommand</code>
+    def remove_command(notification_name)
+      @controller&.remove_command(notification_name)
+    end
+
+    # Register an <code>IProxy</code> with the <code>Model</code> by name.
+    #
+    # @param proxy [IProxy] the <code>IProxy</code> instance to be registered with the <code>Model</code>.
+    def register_proxy(proxy)
+      @model&.register_proxy(proxy)
+    end
+
+    # Retrieve an <code>IProxy</code> from the <code>Model</code> by name.
+    #
+    # @param proxy_name [String] the name of the proxy to be retrieved.
+    # @return [IProxy, nil] the <code>IProxy</code> instance previously registered with the <code>proxy_name</code>
+    def retrieve_proxy(proxy_name)
+      @model&.retrieve_proxy(proxy_name)
+    end
+
+    # Check if a Proxy is registered
+    #
+    # @param proxy_name [String] the name of the Proxy
+    # @return [Boolean] whether a Proxy is currently registered with the given <code>proxyName</code>.
+    def has_proxy?(proxy_name)
+      !!@model&.has_proxy?(proxy_name)
+    end
+
+    # Remove an <code>IProxy</code> from the <code>Model</code> by name.
+    #
+    # @param proxy_name [String] the <code>IProxy</code> to remove from the <code>Model</code>.
+    # @return [IProxy, nil] the <code>IProxy</code> that was removed from the <code>Model</code>, or nil
+    def remove_proxy(proxy_name)
+      @model&.remove_proxy(proxy_name)
+    end
+
+    # Register an <code>IMediator</code> with the <code>View</code>.
+    #
+    # @param mediator [IMediator] a reference to the <code>IMediator</code>
+    def register_mediator(mediator)
+      @view&.register_mediator(mediator)
+    end
+
+    # Retrieve an <code>IMediator</code> from the <code>View</code>.
+    #
+    # @param mediator_name [String] the name of the <code>IMediator</code> to retrieve
+    # @return [IMediator, nil] the <code>IMediator</code> previously registered with the <code>mediator_name</code>
+    def retrieve_mediator(mediator_name)
+      @view&.retrieve_mediator(mediator_name)
+    end
+
+    # Check if a Mediator is registered or not
+    #
+    # @param mediator_name [String] the name of the Mediator
+    # @return [Boolean] whether a Mediator is registered with the given <code>mediator_name</code>.
+    def has_mediator?(mediator_name)
+      !!@view&.has_mediator?(mediator_name)
+    end
+
+    # Remove an <code>IMediator</code> from the <code>View</code>.
+    #
+    # @param mediator_name [String] name of the <code>IMediator</code> to be removed.
+    # @return [IMediator, nil] the <code>IMediator</code> that was removed from the <code>View</code>, or nil
+    def remove_mediator(mediator_name)
+      @view&.remove_mediator(mediator_name)
+    end
+
+    # Notify <code>Observer</code>s.
+    #
+    # This method is left public mostly for backward compatibility
+    # and to allow you to send custom notification classes using the facade.
+    #
+    # Usually you should call <code>send_notification</code>
+    # and pass the parameters, never having to
+    # construct the notification yourself.
+    #
+    # @param notification [INotification] the notification to have the <code>View</code> notify <code>Observers</code>.
+    def notify_observers(notification)
+      @view&.notify_observers(notification)
+    end
+
+    # Create and send an <code>INotification</code>.
+    #
+    # Keeps us from having to construct new notification instances in our implementation code.
+    #
+    # @param name [String] the name of the notification to send
+    # @param body [Object, nil] the body of the notification (optional)
+    # @param type [String, nil] the type of the notification (optional)
+    def send_notification(name, body = nil, type = nil)
+      notify_observers(Notification.new(name, body, type))
+    end
+
+    # Set the Multiton key for this facade instance.
+    #
+    # This is not meant to be called directly. It is invoked internally by the
+    # constructor when <code>get_instance</code> is called. However, it must be public
+    # to implement <code>INotifier</code>.
+    #
+    # @param key [String] the multiton key for this instance
+    def initialize_notifier(key)
+      @multiton_key = key
+    end
+  end
+end

data/lib/patterns/mediator/mediator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# mediator.rb
+# PureMVC Ruby Multicore
+#
+# Copyright(c) 2025 Saad Shams <saad.shams@puremvc.org>
+# Your reuse is governed by the BSD 3-Clause License
+
+module PureMVC
+  # A base <code>IMediator</code> implementation.
+  #
+  # @see View
+  class Mediator < Notifier
+    # The name of the <code>Mediator</code>.
+    #
+    # Typically, a <code>Mediator</code> will be written to serve
+    # one specific control or group controls and so,
+    # will not have a need to be dynamically named.
+    NAME = 'Mediator'
+    public_constant :NAME
+
+    # @return [String] The name of the Mediator.
+    attr_reader :name
+
+    # @return [Object, nil] The component associated with this Mediator.
+    attr_accessor :component
+
+    # Initializes a new Mediator instance.
+    #
+    # @param name [String | nil] the name of the mediator
+    # @param component [Object, nil] the component this mediator manages
+    def initialize(name = nil, component = nil)
+      super()
+      @name = name || NAME
+      @component = component
+    end
+
+    # Returns an array of notification names this mediator is interested in.
+    #
+    # @return [Array<String>] list of notification names
+    def list_notification_interests
+      []
+    end
+
+    # Handles a notification.
+    #
+    # @param notification [_INotification] the notification to handle
+    def handle_notification(notification); end
+
+    # Called when the mediator is registered.
+    def on_register; end
+
+    # Called when the mediator is removed.
+    def on_remove; end
+  end
+end

data/lib/patterns/observer/notification.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# notification.rb
+# PureMVC Ruby Multicore
+#
+# Copyright(c) 2025 Saad Shams <saad.shams@puremvc.org>
+# Your reuse is governed by the BSD 3-Clause License
+
+module PureMVC
+  # A base <code>INotification</code>implementation.
+  #
+  # PureMVC does not rely upon underlying event models such
+  # as the one provided with Flash, and ActionScript 3 does
+  # not have an inherent event model.
+  #
+  # The Observer Pattern as implemented within PureMVC exists
+  # to support event-driven communication between the
+  # application and the actors of the MVC triad.
+  #
+  # Notifications are not meant to be a replacement for Events
+  # in Flex/Flash/Apollo. Generally, <code>IMediator</code>implementors
+  # place event listeners on their view components, which they
+  # then handle in the usual way. This may lead to the broadcast of <code>Notification</code>s to
+  # trigger <code>ICommand</code>s or to communicate with other <code>IMediator</code>s. <code>IProxy</code> and
+  # <code>ICommand</code> instances communicate with each other and <code>IMediator</code>s
+  # by broadcasting <code>INotification</code>s.
+  #
+  # A key difference between Flash <code>Event</code>s and PureMVC
+  # <code>Notification</code>s is that <code>Event</code>s follow the
+  # 'Chain of Responsibility' pattern, 'bubbling' up the display hierarchy
+  # until some parent component handles the <code>Event</code>, while
+  # PureMVC <code>Notification</code>s follow a 'Publish/Subscribe'
+  # pattern. PureMVC classes need not be related to each other in a
+  # parent/child relationship to communicate with one another
+  # using <code>Notification</code>s.
+  #
+  # @see Observer
+  class Notification
+    # @return [String] the name of the notification
+    attr_reader :name
+
+    # @return [Object, nil] the body of the notification
+    attr_accessor :body
+
+    # @return [String, nil] the type of the notification
+    attr_accessor :type
+
+    # The Notification class represents a message with a name, optional body, and optional type.
+    #
+    # @param name [String] the name of the notification
+    # @param body [Object, nil] optional data to pass with the notification
+    # @param type [String, nil] optional type identifier
+    def initialize(name, body = nil, type = nil)
+      @name = name
+      @body = body
+      @type = type
+    end
+
+    # Returns a string representation of the notification.
+    #
+    # @return [String]
+    def to_s
+      "Notification Name: #{@name}" \
+        "\nBody: #{@body.inspect}" \
+        "\nType: #{@type}"
+    end
+  end
+end

data/lib/patterns/observer/notifier.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# notifier.rb
+# PureMVC Ruby Multicore
+#
+# Copyright(c) 2025 Saad Shams <saad.shams@puremvc.org>
+# Your reuse is governed by the BSD 3-Clause License
+
+module PureMVC
+  # A base <code>INotifier</code> implementation.
+  #
+  # <code>MacroCommand</code>, <code>SimpleCommand</code>, <code>Mediator</code>, and <code>Proxy</code>
+  # all need to send <code>Notification</code>s.
+  #
+  # The <code>INotifier</code> interface provides a common method called
+  # <code>send_notification</code> that relieves implementation code of
+  # the necessity to actually construct <code>Notification</code>s.
+  #
+  # The <code>Notifier</code> class, which all the above-mentioned classes
+  # extend, provides an initialized reference to the <code>Facade</code>
+  # Multiton, which is required for the convenience method
+  # for sending <code>Notification</code>s. It also eases implementation,
+  # as these classes have frequent <code>Facade</code> interactions and
+  # usually require access to it anyway.
+  #
+  # NOTE: In the MultiCore version of the framework, there is one caveat:
+  # notifiers cannot send notifications or reach the facade until they
+  # have a valid <code>multiton_key</code>.
+  #
+  # The <code>multiton_key</code> is set:
+  # * on a <code>SimpleCommand</code> when it is executed by the <code>Controller<c/ode>
+  # * on a <code>Mediator</code> when registered with the <code>View</code>
+  # * on a <code>Proxy</code> when registered with the <code>Model</code>
+  #
+  # @see Proxy
+  # @see Facade
+  # @see Mediator
+  # @see MacroCommand
+  # @see SimpleCommand
+  class Notifier
+    # Message Constants
+    MULTITON_MSG = 'multitonKey for this Notifier not yet initialized!'
+    private_constant :MULTITON_MSG
+
+    # @attr_reader [String] The Multiton Key for this app
+    attr_reader :multiton_key
+
+    # Initialize this INotifier instance.
+    #
+    # This is how a Notifier receives its <code>multiton_key</code>.
+    # Any calls to <code>send_notification</code> or attempts to access the <code>facade</code>
+    # will fail until this method has been called.
+    #
+    # Subclasses such as <code>Mediator</code>, <code>Command</code>, or <code>Proxy</code> may override this
+    # method if they need to send notifications or access the <code>Facade</code> instance
+    # as early as possible. However, note that the <code>Facade</code> cannot be accessed
+    # within the constructor of these classes, because <code>initialize_notifier</code>
+    # will not yet have been called at that point.
+    #
+    # @param key [String] the <code>multiton_key</code> this <code>INotifier</code> will use
+    def initialize_notifier(key)
+      @multiton_key = key
+    end
+
+    # Create and send an INotification.
+    #
+    # This method eliminates the need to manually construct
+    # INotification instances in your implementation code.
+    #
+    # @param name [String] the name of the notification
+    # @param body [Object, nil] optional body
+    # @param type [String, nil] optional type
+    def send_notification(name, body = nil, type = nil)
+      facade.send_notification(name, body, type)
+    end
+
+    # Return the Multiton Facade instance
+    #
+    # @raise [RuntimeError] if the <code>multiton_key</code> is not set
+    # @return [IFacade] the facade instance for the notifier's key
+    def facade
+      raise MULTITON_MSG if @multiton_key.nil?
+
+      Facade.get_instance(@multiton_key) { |key| Facade.new(key) }
+    end
+  end
+end

data/lib/patterns/observer/observer.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# observer.rb
+# PureMVC Ruby Multicore
+#
+# Copyright(c) 2025 Saad Shams <saad.shams@puremvc.org>
+# Your reuse is governed by the BSD 3-Clause License
+
+module PureMVC
+  # A base <code>IObserver</code> implementation.
+  #
+  # An <code>Observer</code> is an object that encapsulates information
+  # about an interested object with a method that should
+  # be called when a particular <code>INotification</code> is broadcast.
+  #
+  # In PureMVC, the <code>Observer</code> class assumes these responsibilities:
+  # - Encapsulate the notification (callback) method of the interested object.
+  # - Encapsulate the notification context (<code>self</code>) of the interested object.
+  # - Provide methods for setting the notification method and context.
+  # - Provide a method for notifying the interested object.
+  #
+  # @see View
+  # @see Notification
+  class Observer
+    # @return [Method | nil] notify The callback method to be called on notification.
+    attr_accessor :notify
+
+    # @return [Object | nil] context The object context for the callback.
+    attr_accessor :context
+
+    # Initialize an Observer with a notify method and context.
+    #
+    # @param notify [Method, nil] the callback method to invoke on notification.
+    # @param context [Object, nil] the object context for the callback.
+    def initialize(notify = nil, context = nil)
+      @notify = notify
+      @context = context
+    end
+
+    # Calls the notify method with the given notification.
+    #
+    # @param notification [INotification] the notification to send.
+    def notify_observer(notification)
+      @notify&.call(notification)
+    end
+
+    # Compares the given object with the Observer's context.
+    #
+    # @param object [Object] the object to compare.
+    # @return [Boolean] true if the given object is the same as the context.
+    def compare_notify_context?(object)
+      object.equal?(@context)
+    end
+  end
+end