puremvc 1.0.0 → 1.0.2

data/sig/interfaces/i_observer.rbs

@@ -0,0 +1,56 @@
+module PureMVC
+  # The interface definition for a PureMVC Observer.
+  #
+  # In PureMVC, <code>_IObserver</code> implementors assume these responsibilities:
+  # - Encapsulate the notification (callback) method of the interested object.
+  # - Encapsulate the notification context (this) of the interested object.
+  # - Provide methods for setting the interested object's notification method and context.
+  # - Provide a method for notifying the interested object.
+  #
+  # 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.
+  #
+  # An Observer is an object that encapsulates information
+  # about an interested object with a notification method that
+  # should be called when an <code>_INotification</code> is broadcast. The Observer then
+  # acts as a proxy for notifying the interested object.
+  #
+  # Observers can receive <code>Notification</code>s by having their
+  # <code>notifyObserver</code> method invoked, passing
+  # in an object implementing the <code>_INotification</code> interface, such
+  # as a subclass of <code>Notification</code>.
+  #
+  # @see IView
+  # @see INotification
+  interface _IObserver
+
+    # @return [Method, nil] The callback method to be called on notification.
+    def notify: () -> Method?
+    def notify=: (Method?) -> void
+
+    # @return [Object, nil] The object context for the callback.
+    def context: () -> Object?
+    def context=: (Object?) -> void
+
+    # Notify the interested object.
+    #
+    # @param notification [_INotification] the <code>_INotification</code> to pass to the interested object's notification method
+    def notify_observer: (_INotification notification) -> void
+
+    # Compare the given object to the notification context object.
+    #
+    # @param object [Object] the object to compare.
+    # @return [Boolean] indicating if the notification context and the object are the same.
+    def compare_notify_context?: (Object object) -> bool
+  end
+
+  # Assert that the given `Observer` type parameter is a subtype of `_IObserver`
+  type validate_observer[Observer < _IObserver] = top
+end

data/sig/interfaces/i_proxy.rbs

@@ -0,0 +1,36 @@
+module PureMVC
+  # The interface definition for a PureMVC Proxy.
+  #
+  # In PureMVC, <code>_IProxy</code> implementors assume these responsibilities:
+  # - Implement a common method which returns the name of the Proxy.
+  # - Provide methods for setting and getting the data object.
+  #
+  # Additionally, <code>_IProxy</code>s typically:
+  # - Maintain references to one or more pieces of model data.
+  # - Provide methods for manipulating that data.
+  # - Generate <code>_INotifications</code> when their model data changes.
+  # - Expose their name called <code>NAME</code>, if they are not instantiated multiple times.
+  # - Encapsulate interaction with local or remote services used to fetch and persist model data.
+  #
+  # @see INotifier
+  interface _IProxy
+
+    include _INotifier
+
+    # @return [String] The proxy name
+    def name: () -> String
+
+    # @return [Object | nil] The data managed by the proxy
+    def data: () -> Object?
+    def data=: (Object?) -> void
+
+    # Called by the Model when the Proxy is registered
+    def on_register: () -> void
+
+    # Called by the Model when the Proxy is removed
+    def on_remove: () -> void
+  end
+
+  # Assert that the given `Proxy` type parameter is a subtype of `_IProxy`
+  type validate_proxy[Proxy < _IProxy] = top
+end

data/sig/interfaces/i_view.rbs

@@ -0,0 +1,71 @@
+module PureMVC
+  # The interface definition for a PureMVC View.
+  #
+  # In PureMVC, <code>_IView</code> implementors assume these responsibilities:
+  #
+  # In PureMVC, the <code>View</code> class assumes these responsibilities:
+  # - Maintain a cache of <code>_IMediator</code> instances.
+  # - Provide methods for registering, retrieving, and removing <code>_IMediators</code>.
+  # - Managing the observer lists for each <code>_INotification</code> in the application.
+  # - Providing a method for attaching <code>_IObservers</code> to an <code>_INotification</code>'s observer list.
+  # - Providing a method for broadcasting an <code>_INotification</code>.
+  # - Notifying the <code>_IObservers</code> of a given <code>_INotification</code> when it is broadcast.
+  interface _IView
+    # 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 this <code>_IObserver</code> of
+    # @param observer [_IObserver] the <code>_IObserver</code> to register
+    def register_observer: (String notification_name, _IObserver observer) -> void
+
+    # 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: (_INotification notification) -> void
+
+    # Remove a group of observers from the observer list for a given <code>Notification</code> name.
+    #
+    # @param notification_name [String] which observer list to remove from
+    # @param notify_context [untyped] remove the observers with this object as their notifyContext
+    def remove_observer: (String notification_name, untyped notify_context) -> void
+
+    # 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: (_IMediator mediator) -> void
+
+    # 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] the <code>_IMediator</code> instance previously registered with the given <code>mediatorName</code>.
+    def retrieve_mediator: (String mediator_name) -> _IMediator?
+
+    # Check if a <code>Mediator</code> is registered or not.
+    #
+    # @param mediator_name [String]
+    # @return [Boolean] whether a <code>Mediator</code> is registered with the given <code>mediatorName</code>.
+    def has_mediator?: (String mediator_name) -> bool
+
+    # 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] the <code>_IMediator</code> that was removed from the <code>View</code>
+    def remove_mediator: (String mediator_name) -> _IMediator?
+  end
+
+  # Assert that the given `View` type parameter is a subtype of `_IView`
+  type validate_view[View < _IView] = top
+end

data/sig/patterns/command/macro_command.rbs

@@ -0,0 +1,18 @@
+module PureMVC
+
+  class MacroCommand < Notifier
+
+    include _ICommand
+
+    @sub_commands: Array[^() -> _ICommand]
+
+    def initialize: () -> void
+
+    def initialize_macro_command: () -> void
+
+    def add_sub_command: () { () -> _ICommand } -> void
+  end
+
+  # Type-level assertion that MacroCommand conforms to _ICommand
+  type macro_command_validation = validate_command[MacroCommand]
+end

data/sig/patterns/command/simple_command.rbs

@@ -0,0 +1,11 @@
+module PureMVC
+
+  class SimpleCommand < Notifier
+
+    include _ICommand
+
+  end
+
+  # Type-level assertion that SimpleCommand conforms to _ICommand
+  type simple_command_validation = validate_command[SimpleCommand]
+end

data/sig/patterns/facade/facade.rbs

@@ -0,0 +1,48 @@
+module PureMVC
+
+  class Facade
+
+    include _IFacade
+
+    self.@instance_map: Hash[String, _IFacade]
+
+    self.@mutex: Mutex
+
+    @model: _IModel?
+
+    @controller: _IController?
+
+    @view: _IView?
+
+    @multiton_key: String
+
+    MULTITON_MSG: String
+
+    def self.instance_map: () -> Hash[String, _IFacade]
+
+    private
+
+    def self.mutex: () -> Mutex
+
+    public
+
+    def self.get_instance: (String key) { (String k) -> _IFacade } -> _IFacade
+
+    def self.has_core?: (String key) -> bool
+
+    def self.remove_core: (String key) -> void
+
+    def initialize: (String key) -> void
+
+    def initialize_facade: () -> void
+
+    def initialize_controller: () -> void
+
+    def initialize_model: () -> void
+
+    def initialize_view: () -> void
+  end
+
+  # Type-level assertion that Facade conforms to _IFacade
+  type facade_validation = validate_facade[Facade]
+end

data/sig/patterns/mediator/mediator.rbs

@@ -0,0 +1,18 @@
+module PureMVC
+
+  class Mediator < Notifier
+
+    include _IMediator
+
+    NAME: String
+
+    attr_reader name: String
+
+    attr_accessor component: Object?
+
+    def initialize: (?String? name, ?Object? component) -> void
+  end
+
+  # Type-level assertion that Mediator conforms to _IMediator
+  type mediator_validation = validate_mediator[Mediator]
+end

data/sig/patterns/observer/notification.rbs

@@ -0,0 +1,18 @@
+module PureMVC
+
+  class Notification
+
+    include _INotification
+
+    attr_reader name: String
+
+    attr_accessor body: Object?
+
+    attr_accessor type: String?
+
+    def initialize: (String name, ?Object? body, ?String? type) -> void
+  end
+
+  # Type-level assertion that Notification conforms to _INotification
+  type notification_validation = validate_notification[Notification]
+end

data/sig/patterns/observer/notifier.rbs

@@ -0,0 +1,17 @@
+module PureMVC
+
+  class Notifier
+
+    include _INotifier
+
+    @multiton_key: String
+
+    MULTITON_MSG: String
+
+    def multiton_key: () -> String
+
+  end
+
+  # Type-level assertion that Notifier conforms to _INotifier
+  type notifier_validation = validate_notifier[Notifier]
+end

data/sig/patterns/observer/observer.rbs

@@ -0,0 +1,20 @@
+module PureMVC
+
+  class Observer
+
+    include _IObserver
+
+    attr_accessor notify: Method?
+
+    attr_accessor context: Object?
+
+    def initialize: (?Method? notify, ?Object? context) -> void
+
+    def notify_observer: (_INotification) -> void
+
+    def compare_notify_context?: (Object) -> bool
+  end
+
+  # Type-level assertion that Observer conforms to _IObserver
+  type observer_validation = validate_observer[Observer]
+end

data/sig/patterns/proxy/proxy.rbs

@@ -0,0 +1,19 @@
+module PureMVC
+
+  class Proxy < Notifier
+
+    include _IProxy
+
+    NAME: String
+
+    attr_reader name: String
+
+    attr_accessor data: Object?
+
+    def initialize: (?String? name, ?Object? data) -> void
+  end
+
+  # Type-level assertion that Proxy conforms to _IProxy
+  type proxy_validation = validate_proxy[Proxy]
+end
+

data/src/core/controller.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+# typed: true
+
+# controller.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>IController</code> implementation.
+  #
+  # In PureMVC, the <code>Controller</code> class follows the
+  # 'Command and Controller' strategy and assumes these responsibilities:
+  #
+  # * Remembering which <code>ICommand</code>s are intended to handle which <code>INotifications</code>.
+  # * Registering itself as an <code>IObserver</code> with the <code>View</code> for each <code>INotification</code>
+  #   that has an <code>ICommand</code> mapping.
+  # * Creating a new instance of the proper <code>ICommand</code> to handle a given <code>INotification</code>
+  #   when notified by the <code>View</code>.
+  # * Calling the <code>ICommand</code>'s <code>execute</code> method, passing in the <code>INotification</code>.
+  #
+  # Your application must register <code>ICommands</code> with the <code>Controller</code>.
+  #
+  # The simplest way is to subclass <code>Facade</code>, and use its <code>initializeController</code> method.
+  # to add your registrations.
+  #
+  # @see View
+  # @see Observer
+  # @see Notification
+  # @see SimpleCommand
+  # @see MacroCommand
+  class Controller
+    # Message Constants
+    MULTITON_MSG = 'Controller instance for this Multiton key already constructed!'
+    private_constant :MULTITON_MSG
+
+    class << self
+      # The Multiton IController instanceMap.
+      # @return [Hash{String => IController}]
+      def instance_map = (@instance_map ||= {})
+
+      # Mutex used to synchronize access to the instance map for thread safety.
+      # @return [Mutex]
+      def mutex = (@mutex ||= Mutex.new)
+
+      # Gets an instance using the provided factory block
+      #
+      # @param key [String] the unique key identifying the Multiton instance
+      # @param factory [^(String) -> _IController] the unique key passed to the factory block
+      # @return [IController] The controller instance created by the factory
+      def get_instance(key, &factory)
+        mutex.synchronize do
+          instance_map[key] ||= factory.call(key)
+        end
+      end
+
+      # Remove an IController instance
+      #
+      # @param key [String] the multiton key of the IController instance to remove
+      def remove_controller(key)
+        mutex.synchronize do
+          instance_map.delete(key)
+        end
+      end
+    end
+
+    # Constructor.
+    #
+    # This IController implementation is a Multiton, so you should not call the constructor
+    # directly. Instead, call the static factory method, passing the unique key for this instance:
+    # <code>PureMVC::Controller.getInstance(key) { |key| PureMVC::Controller.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
+      # Local reference to View
+      # @type var component: _IView?
+      @view = nil
+      # Mapping of Notification names to Command factories
+      # @type var command_map: Hash[String, ^() -> _ICommand]
+      @command_map = {}
+      # Mutex used to synchronize access to the @command_map
+      # @type var command_mutex: Mutex
+      @command_mutex = Mutex.new
+      initialize_controller
+    end
+
+    # Initialize the Multiton Controller instance.
+    #
+    # Called automatically by the constructor.
+    #
+    # Note that if you are using a subclass of View
+    # in your application, you should also subclass Controller
+    # and override the initialize_controller method in the
+    # following way:
+    #
+    # @example
+    #   # ensure that the Controller is talking to my IView implementation
+    #   def initialize_controller
+    #     @view = MyView::get_instance(key) { |key| MyView.new(key) }
+    #   end
+    #
+    def initialize_controller
+      @view = View.get_instance(@multiton_key) { |key| View.new(key) }
+    end
+
+    # Register a particular ICommand class as the handler for a particular INotification.
+    #
+    # If an ICommand has already been registered to handle INotifications with this name,
+    # it is replaced by the new ICommand.
+    #
+    # The Observer for the new ICommand is only created if this is the first time
+    # an ICommand has been registered for this notification name.
+    #
+    # @param notification_name [String] the name of the INotification
+    # @param factory [^<() -> ICommand>] the factory to produce an instance of the ICommand
+    def register_command(notification_name, &factory)
+      @command_mutex.synchronize do
+        if @command_map[notification_name].nil?
+          @view&.register_observer(notification_name, Observer.new(method(:execute_command), self))
+        end
+        @command_map[notification_name] = factory
+      end
+    end
+
+    # If an ICommand has previously been registered to handle the given INotification, then it is executed.
+    #
+    # @param notification [INotification] the notification to handle
+    def execute_command(notification)
+      @command_mutex.synchronize do
+        # @type factory: [^() -> ICommand]?
+        factory = @command_map[notification.name]
+        return if factory.nil?
+
+        # @type var command: _ICommand
+        command = factory.call
+        command.initialize_notifier(@multiton_key)
+        command.execute(notification)
+      end
+    end
+
+    # Check if a Command is registered for a given Notification.
+    #
+    # @param notification_name [String] the name of the Notification
+    # @return [Boolean] whether a Command is currently registered for the given notification_name
+    def has_command?(notification_name)
+      @command_mutex.synchronize do
+        @command_map.key?(notification_name)
+      end
+    end
+
+    # Remove a previously registered ICommand to INotification mapping.
+    #
+    # @param notification_name [String] the name of the INotification to remove the ICommand mapping for
+    def remove_command(notification_name)
+      @command_mutex.synchronize do
+        # @type var command: [^() -> ICommand]?
+        command = @command_map[notification_name]
+
+        # if the Command is registered...
+        if command
+          # remove the observer
+          @view&.remove_observer(notification_name, self)
+          # remove the command
+          @command_map.delete(notification_name)
+        end
+      end
+    end
+  end
+end

data/src/core/model.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+# typed: true
+
+# model.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>IModel</code> implementation.
+  #
+  # In PureMVC, the <code>Model</code> class provides access to model objects (Proxies) by named lookup.
+  #
+  # The <code>Model</code> assumes these responsibilities:
+  #
+  # - Maintains a cache of <code>IProxy</code> instances.
+  # - Provides methods for registering, retrieving, and removing <code>IProxy</code> instances.
+  #
+  # Your application must register <code>IProxy</code> instances with the <code>Model</code>. Typically,
+  # an <code>ICommand</code> is used to create and register <code>IProxy</code> instances after the <code>Facade<code>
+  # has initialized the Core actors.
+  #
+  # @see Proxy
+  # @see IProxy
+  class Model
+    # Message Constants
+    MULTITON_MSG = 'Model instance for this Multiton key already constructed!'
+    private_constant :MULTITON_MSG
+
+    class << self
+      # The Multiton IModel instanceMap.
+      # @return [Hash{String => IModel}]
+      def instance_map = (@instance_map ||= {})
+
+      # Mutex used to synchronize access to the instance map for thread safety.
+      # @return [Mutex]
+      def mutex = (@mutex ||= Mutex.new)
+
+      # <code>Model</code> Multiton Factory method.
+      #
+      # @param key [String] the unique key identifying the Multiton instance
+      # @param factory [^(String) -> IModel] the unique key passed to the factory block
+      # @return [IModel] the instance for this Multiton key
+      def get_instance(key, &factory)
+        mutex.synchronize do
+          instance_map[key] ||= factory.call(key)
+        end
+      end
+
+      # Remove an IModel instance
+      #
+      # @param key [String] the multiton key of the IModel instance to remove
+      def remove_model(key)
+        mutex.synchronize do
+          instance_map.delete(key)
+        end
+      end
+    end
+
+    # Constructor.
+    #
+    # This <code>IModel</code> implementation is a Multiton,
+    # so you should not call the constructor directly, but instead call the static
+    # Multiton Factory method <code>PureMVC::Model.get_instance(key) { |key| PureMVC::Model.new(key) }</code>.
+    #
+    # @param key [String]
+    # @raise [RuntimeError] Error 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
+      @multiton_key = key
+      @proxy_map = {}
+      @proxy_mutex = Mutex.new
+      initialize_model
+    end
+
+    # Initialize the <code>Model</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_model; end
+
+    # Register an <code>IProxy</code> with the <code>Model</code>.
+    #
+    # @param proxy [_IProxy] an <code>IProxy</code> to be held by the <code>Model</code>.
+    def register_proxy(proxy)
+      proxy.initialize_notifier(@multiton_key)
+      @proxy_mutex.synchronize do
+        @proxy_map[proxy.name] = proxy
+      end
+      proxy.on_register
+    end
+
+    # Retrieve an <code>IProxy</code> from the <code>Model</code>.
+    #
+    # @param proxy_name [String] the name of the proxy to retrieve.
+    # @return [_IProxy, nil] the <code>IProxy</code> instance previously registered with the  <code>proxy_name</code>,
+    # or nil if none found.
+    def retrieve_proxy(proxy_name)
+      @proxy_mutex.synchronize do
+        @proxy_map[proxy_name]
+      end
+    end
+
+    # Check if a Proxy is registered.
+    #
+    # @param proxy_name [String] the name of the proxy to check.
+    # @return [Boolean] whether a Proxy is currently registered with the given <code>proxy_name</code>.
+    def has_proxy?(proxy_name)
+      @proxy_mutex.synchronize do
+        @proxy_map.key?(proxy_name)
+      end
+    end
+
+    # Remove an <code>IProxy</code> from the <code>Model</code>.
+    #
+    # @param proxy_name [String] name of the <code>IProxy</code> instance to be removed.
+    # @return [_IProxy, nil] the <code>IProxy</code> that was removed from the <code>Model</code>, or nil if none found.
+    def remove_proxy(proxy_name)
+      # @type var proxy: _IProxy?
+      proxy = nil
+      @proxy_mutex.synchronize do
+        proxy = @proxy_map.delete(proxy_name)
+      end
+      proxy&.on_remove
+      proxy
+    end
+  end
+end