rooibos 0.6.2 → 0.7.0

data/sig/rooibos/router/forwards.rbs

@@ -0,0 +1,34 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Collection of forward rules.
+    class Forwards < Data
+      include Registry[Forward]
+
+      attr_reader rules: Array[Forward]
+
+      def initialize: (?rules: Array[Forward]) -> void
+
+      # Adds a forward rule matching class instances.
+      def add_instances_of: (Class klass, ?to: route_target?, ?as: Symbol?, ?broadcast: bool, ?broadcast_to: Array[route_target]?) -> void
+
+      # Adds a forward rule matching key events.
+      def add_events: (Symbol | Array[Symbol] keys, ?to: route_target?, ?as: Symbol?, ?guard: guard?, ?when: guard?, ?unless: guard?) -> void
+
+      # Adds a forward rule matching routed messages by envelope.
+      def add_routed: (Symbol | Array[Symbol] envelopes, ?to: route_target?, ?as: Symbol?) -> void
+
+      # Adds a forward rule matching a custom predicate.
+      def add_custom: (guard predicate, ?to: route_target?, ?as: Symbol?) -> void
+
+      private
+
+      # Resolves broadcast options into a targets value.
+      def resolve_targets: (to: route_target?, broadcast: bool, broadcast_to: Array[route_target]?) -> Forward::targets
+    end
+  end
+end

data/sig/rooibos/router/guard.rbs

@@ -0,0 +1,21 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Normalizes guard options into a callable.
+    class Guard < Data
+      attr_reader callable: guard?
+
+      def self.from: (?guard: guard?, ?when: guard?, ?unless: guard?) -> Guard
+
+      # Effective arity of the guard (2 if no callable).
+      def arity: () -> Integer
+
+      # Evaluates the guard. Returns true if no callable.
+      def call: (message, _DataModel) -> boolish
+    end
+  end
+end

data/sig/rooibos/router/observe.rbs

@@ -0,0 +1,20 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Observe rule - matches messages, handles, and continues processing.
+    class Observe < Data
+      include Rule
+
+      attr_reader predicate: predicate
+      attr_reader action: action
+      attr_reader guard: Guard
+
+      # Applies the action and returns a Transition.
+      def apply: (message, _DataModel, Routes) -> Transition
+    end
+  end
+end

data/sig/rooibos/router/observes.rbs

@@ -0,0 +1,38 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Collection of observe rules.
+    class Observes < Data
+      include Registry[Observe]
+
+      attr_reader rules: Array[Observe]
+      attr_reader actions: Actions
+
+      def initialize: (?rules: Array[Observe], actions: Actions) -> void
+
+      # Adds an observe rule matching key events.
+      def add_events: (Symbol | Array[Symbol] keys, handler_or_action handler, ?guard: guard?, ?when: guard?, ?unless: guard?) -> void
+
+      # Adds an observe rule matching routed messages by envelope.
+      def add_routed: (Symbol envelope, handler_or_action handler, ?guard: guard?) -> void
+
+      # Adds an observe rule matching class instances.
+      def add_instances_of: (Class klass, handler_or_action handler, ?guard: guard?) -> void
+
+      # Adds a catch-all observe rule.
+      def add_all: (handler_or_action handler, ?guard: guard?, ?when: guard?, ?unless: guard?) -> void
+
+      # Adds an observe rule matching a custom predicate.
+      def add_custom: (guard predicate, handler_or_action handler, ?guard: guard?, ?when: guard?, ?unless: guard?) -> void
+
+      private
+
+      # Resolves a Symbol action name to its Action, or wraps a lambda.
+      def resolve: (handler_or_action handler) -> action
+    end
+  end
+end

data/sig/rooibos/router/otherwise.rbs

@@ -0,0 +1,22 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Otherwise rule - routes unhandled messages to a fragment.
+    class Otherwise < Data
+      include Rule
+
+      attr_reader target: route_target
+      attr_reader guard: Guard
+      attr_reader predicate: Predicate::Always
+
+      def initialize: (target: route_target, ?guard: Guard?) -> void
+
+      # Routes the message through the target route.
+      def apply: (message, _DataModel, Routes) -> Transition
+    end
+  end
+end

data/sig/rooibos/router/otherwises.rbs

@@ -0,0 +1,20 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Collection of otherwise rules.
+    class Otherwises < Data
+      include Registry[Otherwise]
+
+      attr_reader rules: Array[Otherwise]
+
+      def initialize: (?rules: Array[Otherwise]) -> void
+
+      # Adds an otherwise rule with optional guard.
+      def add: (route_to: route_target, ?guard: guard?, ?when: guard?, ?unless: guard?) -> void
+    end
+  end
+end

data/sig/rooibos/router/predicate.rbs

@@ -0,0 +1,51 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Predicate classes for message matching.
+    module Predicate
+      # Matches key events by symbol.
+      class Events < Data
+        attr_reader keys: Array[Symbol]
+
+        def initialize: (keys: Symbol | Array[Symbol]) -> void
+        def arity: () -> Integer
+        def call: (message, _DataModel) -> boolish
+      end
+
+      # Matches routed messages by single envelope.
+      class Routed < Data
+        attr_reader envelope: Symbol
+
+        def arity: () -> Integer
+        def call: (message, _DataModel) -> boolish
+      end
+
+      # Matches routed messages by any of the given envelopes.
+      class RoutedEnvelopes < Data
+        attr_reader envelopes: Array[Symbol]
+
+        def initialize: (envelopes: Symbol | Array[Symbol]) -> void
+        def arity: () -> Integer
+        def call: (message, _DataModel) -> boolish
+      end
+
+      # Matches messages by class.
+      class InstancesOf < Data
+        attr_reader klass: Class
+
+        def arity: () -> Integer
+        def call: (message, _DataModel) -> boolish
+      end
+
+      # Matches all messages.
+      class Always < Data
+        def arity: () -> Integer
+        def call: (message, _DataModel) -> boolish
+      end
+    end
+  end
+end

data/sig/rooibos/router/receive.rbs

@@ -0,0 +1,20 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Receive rule - matches messages and delegates to action.
+    class Receive < Data
+      include Rule
+
+      attr_reader predicate: predicate
+      attr_reader action: action
+      attr_reader guard: Guard
+
+      # Applies the action and returns a Transition.
+      def apply: (message, _DataModel, Routes) -> Transition
+    end
+  end
+end

data/sig/rooibos/router/receives.rbs

@@ -0,0 +1,38 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Collection of receive rules.
+    class Receives < Data
+      include Registry[Receive]
+
+      attr_reader rules: Array[Receive]
+      attr_reader actions: Actions
+
+      def initialize: (?rules: Array[Receive], actions: Actions) -> void
+
+      # Adds a receive rule matching key events.
+      def add_events: (Symbol | Array[Symbol] keys, handler_or_action handler, ?guard: guard?, ?when: guard?, ?unless: guard?) -> void
+
+      # Adds a receive rule matching routed messages by envelope.
+      def add_routed: (Symbol envelope, handler_or_action handler, ?guard: guard?) -> void
+
+      # Adds a receive rule matching class instances.
+      def add_instances_of: (Class klass, handler_or_action handler, ?guard: guard?) -> void
+
+      # Adds a catch-all receive rule.
+      def add_all: (handler_or_action handler, ?guard: guard?, ?when: guard?, ?unless: guard?) -> void
+
+      # Adds a receive rule matching a custom predicate.
+      def add_custom: (guard predicate, handler_or_action handler, ?guard: guard?) -> void
+
+      private
+
+      # Resolves a Symbol action name to its Action, or wraps a lambda.
+      def resolve: (handler_or_action handler) -> action
+    end
+  end
+end

data/sig/rooibos/router/registry.rbs

@@ -0,0 +1,24 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Common behavior for Rule collections.
+    # Including classes must define `rules` as a Data member.
+    module Registry[T]
+      include Enumerable[T]
+
+      # The underlying rules collection (provided by including Data class).
+      def rules: () -> Array[T]
+
+      # Appends a rule to the collection.
+      def add: (T rule) -> Array[T]
+
+      # Iterates over all rules.
+      def each: () { (T) -> void } -> Array[T]
+              | () -> Enumerator[T, Array[T]]
+    end
+  end
+end

data/sig/rooibos/router/route.rbs

@@ -0,0 +1,46 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # A configured route to a child fragment.
+    class Route < Data
+      # Route prefix symbol (model accessor name).
+      attr_reader prefix: Symbol
+
+      # Fragment module with Update callable.
+      attr_reader fragment: Module
+
+      # Optional custom model reader.
+      attr_reader read: (^(_DataModel) -> _DataModel)?
+
+      # Optional custom model writer.
+      attr_reader write: (^(_DataModel, _DataModel) -> _DataModel)?
+
+      def self.new: (
+        prefix: Symbol,
+        fragment: Module,
+        ?read: (^(_DataModel) -> _DataModel)?,
+        ?write: (^(_DataModel, _DataModel) -> _DataModel)?
+      ) -> instance
+
+      def initialize: (
+        prefix: Symbol,
+        fragment: Module,
+        ?read: (^(_DataModel) -> _DataModel)?,
+        ?write: (^(_DataModel, _DataModel) -> _DataModel)?
+      ) -> void
+
+      # Delegates message to child fragment and merges result.
+      def delegate: (message msg, _DataModel model) -> [_DataModel, Command::execution?]
+
+      private
+
+      def extract: (_DataModel model) -> _DataModel
+
+      def merge: (_DataModel model, _DataModel new_child) -> _DataModel
+    end
+  end
+end

data/sig/rooibos/router/router_update.rbs

@@ -0,0 +1,33 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Encapsulates dispatch logic - given frozen flow objects, processes messages.
+    class RouterUpdate < Data
+      attr_reader inward: Flow::Inward
+      attr_reader outward: Flow::Outward
+
+      def initialize: (
+        inward: Flow::Inward,
+        outward: Flow::Outward
+      ) -> void
+
+      # Dispatches a message through the router pipeline.
+      def call: (message, _DataModel) -> [_DataModel, Command::execution?]
+
+      private
+
+      # Handles inward dispatch (non-bubbled messages).
+      def dispatch_inward: (message, _DataModel) -> [_DataModel, Command::execution?]
+
+      # Extracts bubbles from a Command::Batch and processes them.
+      def extract_bubbles_from_batch: (Transition transition) -> Transition
+
+      # Handles outward dispatch (bubbled messages).
+      def dispatch_outward: (message, _DataModel) -> [_DataModel, Command::execution?]
+    end
+  end
+end

data/sig/rooibos/router/routes.rbs

@@ -0,0 +1,41 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Collection of routes - offers add/fetch/broadcast interface.
+    class Routes
+      include Enumerable[Route]
+
+      @routes: Set[Route]
+
+      def initialize: (?Set[Route] routes) -> void
+
+      # Adds a route to the collection. Returns the route for capture.
+      def add: (Route route) -> Route
+
+      # Resolves a target (Module, Symbol, or Route) to a Route.
+      def for: (route_target identifier) -> Route?
+
+      # Iterates over all routes.
+      def each: () { (Route) -> void } -> Set[Route]
+              | () -> Enumerator[Route, Set[Route]]
+
+      # Returns a subset of routes for the given targets.
+      def subset: (Array[route_target] targets) -> Routes
+
+      # Broadcasts a message to all routes, accumulating transitions.
+      def broadcast: (message msg, _DataModel model) -> Transition
+
+      # Broadcasts to a specific subset of routes.
+      def broadcast_to: (Array[route_target] targets, message msg, _DataModel model) -> Transition
+
+      private
+
+      # Finds the unique route matching the block, raises on ambiguity.
+      def unique: (route_target identifier) { (Route) -> boolish } -> Route?
+    end
+  end
+end

data/sig/rooibos/router/rule.rbs

@@ -0,0 +1,36 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Predicate type: callable matching (message, model).
+    type predicate = Predicate::Events | Predicate::Routed | Predicate::RoutedEnvelopes
+                   | Predicate::InstancesOf | Predicate::Always
+                   | ^(message, _DataModel) -> boolish
+
+    # Common behavior for routing rules (Forward, Receive, Observe, Otherwise).
+    module Rule
+      # Provided by including Data class: the message-matching predicate.
+      def predicate: () -> predicate
+
+      # Provided by including Data class: the guard condition.
+      def guard: () -> Guard
+
+      # Provided by including Data class: applies the rule to a message.
+      def apply: (message, _DataModel, Routes) -> Transition
+
+      # Tests predicate and guard.
+      def matches?: (Configuration config) -> boolish
+
+      # Matches and applies if matching. Returns Transition or nil.
+      def apply_if_matches: (Configuration config, Routes routes) -> Transition?
+
+      private
+
+      def predicate_matches?: (Configuration config) -> boolish
+      def guard_passes?: (Configuration config) -> boolish
+    end
+  end
+end