puremvc 1.0.0 → 1.0.2

data/src/core/view.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+# typed: true
+
+# view.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 Multiton <code>IView</code> implementation.
+  #
+  # In PureMVC, the <code>IView</code> class assumes these responsibilities:
+  #
+  # - Maintains a cache of <code>IMediator</code>instances.
+  # - Provides methods for registering, retrieving, and removing <code>IMediators</code>.
+  # - Notifies <code>IMediators</code>when they are registered or removed.
+  # - Manages the observer lists for each <code>INotification</code>in the application.
+  # - Provides a method for attaching <code>IObservers</code>to an <code>INotification</code>'s observer list.
+  # - Provides a method for broadcasting an <code>INotification</code>.
+  # - Notifies the <code>IObservers</code>of a given <code>INotification</code>when it is broadcast.
+  #
+  # @see Mediator
+  # @see Observer
+  # @see Notification
+  class View
+    MULTITON_MSG = 'View instance for this Multiton key already constructed!'
+    private_constant :MULTITON_MSG
+
+    class << self
+      # The Multiton IModel instanceMap.
+      # @return [Hash{String => IView}]
+      def instance_map = (@instance_map ||= {})
+
+      # Mutex used to synchronize access to the instance map for thread safety.
+      # @return [Mutex]
+      def mutex = (@mutex ||= Mutex.new)
+
+      # View Multiton Factory method.
+      #
+      # @param key [String] the unique key identifying the Multiton instance
+      # @param factory [^(String) -> _IView] the unique key passed to the factory block
+      # @return [_IView] the Multiton instance of <code>View</code>
+      def get_instance(key, &factory)
+        mutex.synchronize do
+          instance_map[key] ||= factory.call(key)
+        end
+      end
+
+      # Remove an <code>IView</code> instance.
+      #
+      # @param key [String] the key of the <code>IView</code> instance to remove
+      def remove_view(key)
+        mutex.synchronize do
+          instance_map.delete(key)
+        end
+      end
+    end
+
+    # Constructor.
+    #
+    # This <code>IView</code> implementation is a Multiton,
+    # so you should not call the constructor directly. Instead, call the static
+    # Multiton factory method <code>View.get_instance(multiton_key) { |key| View.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
+      # The Multiton Key for this Core
+      # @type var multiton_key: String
+      @multiton_key = key
+      # Mapping of Notification names to Observer lists
+      # @type var observer_map: Hash[String, Array[_IObserver]]
+      @observer_map = {}
+      # Mutex used to synchronize access to the observer_map
+      # @type var observer_mutex: Mutex
+      @observer_mutex = Mutex.new
+      # Mapping of Mediator names to Mediator instances
+      # @type var mediator_map: Hash[String, _IMediator]
+      @mediator_map = {}
+      # Mutex used to synchronize access to the mediator_map
+      # @type var mediator_mutex: Mutex
+      @mediator_mutex = Mutex.new
+      initialize_view
+    end
+
+    # Initialize the Multiton <code>View</code> instance.
+    #
+    # Called automatically by the constructor, this
+    # is your opportunity to initialize the Multiton
+    # instance in your subclass without overriding the
+    # constructor.
+    def initialize_view; end
+
+    # Register an <code>IObserver</code> to be notified
+    # of <code>INotifications</code> with a given name.
+    #
+    # @param notification_name [String] the name of the <code>INotifications</code> to notify <code>IObserver</code> of
+    # @param observer [IObserver] the <code>IObserver</code> to register
+    def register_observer(notification_name, observer)
+      @observer_mutex.synchronize do
+        observers = (@observer_map[notification_name] ||= [])
+        observers << observer
+      end
+    end
+
+    # Notify the <code>IObservers</code> for a particular <code>INotification</code>.
+    #
+    # All previously attached <code>IObservers</code> for this <code>INotification</code>'s
+    # list are notified and are passed a reference to the <code>INotification</code> in
+    # the order in which they were registered.
+    #
+    # @param notification [INotification] the <code>INotification</code> to notify <code>IObservers</code> of.
+    def notify_observers(notification)
+      # @type var observers: Array[_IObserver]?
+      observers = nil
+      @observer_mutex.synchronize do
+        # Get a reference to the observers list for this notification name
+        # Iteration safe, copy observers from reference array to working array,
+        # since the reference array may change during the notification loop
+        observers = @observer_map[notification.name].dup
+      end
+      # Notify Observers from the working array
+      observers&.each { |observer| observer.notify_observer(notification) }
+    end
+
+    # Remove the observer for a given notifyContext from an observer list for a given Notification name.
+    #
+    # @param notification_name [String] which observer list to remove from
+    # @param notify_context [Object] remove the observer with this object as its notifyContext
+    def remove_observer(notification_name, notify_context)
+      @observer_mutex.synchronize do
+        # the observer list for the notification under inspection
+        # @type var observers: Array[_IObserver]?
+        observers = @observer_map[notification_name]
+        # find and remove the sole Observer for the given notify_context
+        # there can only be one Observer for a given notify_context
+        # in any given Observer list, so remove it
+        observers&.reject! { |observer| observer.compare_notify_context?(notify_context) }
+        # Also, when a Notification's Observer list length falls to
+        # zero, delete the notification key from the observer map
+        @observer_map.delete(notification_name) if observers&.empty?
+      end
+    end
+
+    # Register an <code>IMediator</code> instance with the <code>View</code>.
+    #
+    # Registers the <code>IMediator</code> so that it can be retrieved by name,
+    # and further interrogates the <code>IMediator</code> for its
+    # <code>INotification</code> interests.
+    #
+    # If the <code>IMediator</code> returns any <code>INotification</code>
+    # names to be notified about, an <code>Observer</code> is created encapsulating
+    # the <code>IMediator</code> instance's <code>handleNotification</code> method
+    # and registering it as an <code>Observer</code> for all <code>INotifications</code> the
+    # <code>IMediator</code> is interested in.
+    #
+    # @param mediator [IMediator] a reference to the <code>IMediator</code> instance
+    def register_mediator(mediator)
+      @mediator_mutex.synchronize do
+        return if @mediator_map.key?(mediator.name)
+
+        @mediator_map[mediator.name] = mediator
+      end
+
+      mediator.initialize_notifier(@multiton_key)
+
+      # Create Observer referencing this mediator's handleNotification method
+      # @type observer [IObserver]
+      observer = Observer.new(mediator.method(:handle_notification), mediator)
+
+      # Get Notification interests, if any.
+      # @type interests [Array<String>]
+      interests = mediator.list_notification_interests
+      # Register Mediator as Observer for its list of Notification interests
+      interests.each { |interest| register_observer(interest, observer) }
+
+      # alert the mediator that it has been registered
+      mediator.on_register
+    end
+
+    # Retrieve an <code>IMediator</code> from the <code>View</code>.
+    #
+    # @param mediator_name [String] the name of the <code>IMediator</code> instance to retrieve.
+    # @return [IMediator, nil] <code>IMediator</code> previously registered with the given <code>mediatorName</code>.
+    def retrieve_mediator(mediator_name)
+      @mediator_mutex.synchronize do
+        @mediator_map[mediator_name]
+      end
+    end
+
+    # Check if a Mediator is registered or not.
+    #
+    # @param mediator_name [String] the name of the mediator to check.
+    # @return [Boolean] whether a Mediator is registered with the given <code>mediatorName</code>.
+    def has_mediator?(mediator_name)
+      @mediator_mutex.synchronize do
+        @mediator_map.key?(mediator_name)
+      end
+    end
+
+    # Remove an <code>IMediator</code> from the <code>View</code>.
+    #
+    # @param mediator_name [String] name of the <code>IMediator</code> instance to be removed.
+    # @return [IMediator, nil] <code>IMediator</code> that was removed from the <code>View</code>, or nil if none found.
+    def remove_mediator(mediator_name)
+      # @type var mediator: _IMediator?
+      mediator = nil
+      @mediator_mutex.synchronize do
+        # retrieve the named mediator and delete from the mediator map
+        mediator = @mediator_map.delete(mediator_name)
+      end
+      return unless mediator
+
+      # for every notification this mediator is interested in...
+      # @type var interests: Array[String]
+      interests = mediator.list_notification_interests
+      # remove the observer linking the mediator
+      # to the notification interest
+      interests.each { |interest| remove_observer(interest, mediator) }
+
+      # alert the mediator that it has been removed
+      mediator.on_remove
+      mediator
+    end
+  end
+end

data/src/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/src/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/src/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/src/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