From fd90485e619d33ee44a224506c49b4684c3d0f55 Mon Sep 17 00:00:00 2001 From: Wehlney <52572763+Wehlney@users.noreply.github.com> Date: Fri, 3 Jul 2026 18:04:20 +0200 Subject: [PATCH 1/2] Clean EventBus docs and comments --- eventbus/README.md | 25 +++----- .../Runtime/Reflex/PubSubBindings.cs | 61 ++----------------- .../Runtime/Reflex/PurrNetPubSubBindings.cs | 2 - .../Runtime/Core/EventBus.cs | 4 -- .../Runtime/Core/Events.cs | 20 +----- .../Runtime/Core/Publisher.cs | 5 +- .../Runtime/Core/Subscriber.cs | 2 - .../Runtime/Core/SubscriptionBag.cs | 3 +- 8 files changed, 18 insertions(+), 104 deletions(-) diff --git a/eventbus/README.md b/eventbus/README.md index 47331a5..6f88065 100644 --- a/eventbus/README.md +++ b/eventbus/README.md @@ -1,37 +1,30 @@ # Wehlney EventBus Packages -This folder is a Unity Package Manager monorepo for the Wehlney EventBus stack. +This folder contains the EventBus packages in the `unity-packages` repository. ## Packages -- `com.wehlney.eventbus`: pure in-process EventBus core. No Reflex, no PurrNet, no project-specific dependencies. +- `com.wehlney.eventbus`: in-process EventBus core. No Reflex, no PurrNet, no project-specific dependencies. - `com.wehlney.eventbus.purrnet`: PurrNet runtime network-event sharing extension. Depends on `com.wehlney.eventbus` and PurrNet. - `com.wehlney.eventbus.reflex`: Reflex adapter registration helpers. Depends on `com.wehlney.eventbus`, `com.wehlney.eventbus.purrnet`, and Reflex. -## Install From Git +## Install from Git -After this folder is pushed to GitHub, install packages with `?path=` URLs: +Install packages with `?path=` URLs: ```json -"com.wehlney.eventbus": "https://github.com/wehlney/wehlney-unity-packages.git?path=/eventbus/com.wehlney.eventbus#v0.1.0", -"com.wehlney.eventbus.purrnet": "https://github.com/wehlney/wehlney-unity-packages.git?path=/eventbus/com.wehlney.eventbus.purrnet#v0.1.0", -"com.wehlney.eventbus.reflex": "https://github.com/wehlney/wehlney-unity-packages.git?path=/eventbus/com.wehlney.eventbus.reflex#v0.1.0" +"com.wehlney.eventbus": "https://github.com/Wehlney/unity-packages.git?path=/eventbus/com.wehlney.eventbus#v0.1.0", +"com.wehlney.eventbus.purrnet": "https://github.com/Wehlney/unity-packages.git?path=/eventbus/com.wehlney.eventbus.purrnet#v0.1.0", +"com.wehlney.eventbus.reflex": "https://github.com/Wehlney/unity-packages.git?path=/eventbus/com.wehlney.eventbus.reflex#v0.1.0" ``` Install the core package first, then the PurrNet extension, then the Reflex adapter. ## Versioning -Keep each `package.json` version aligned with the Git tag unless intentionally versioning packages independently. +Release tags currently version this repository as a whole. Keep each `package.json` version aligned with the tag unless a package is intentionally versioned on its own. -Recommended first tag: - -```powershell -git tag v0.1.0 -git push origin v0.1.0 -``` - -## Publishing Checklist +## Publishing checklist - Commit all `.meta` files. - Keep package names stable. diff --git a/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PubSubBindings.cs b/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PubSubBindings.cs index 59eb3f7..c3cb308 100644 --- a/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PubSubBindings.cs +++ b/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PubSubBindings.cs @@ -1,13 +1,3 @@ -// File: PubSubBindings.cs -// -// Provides DI registration helpers for the PubSub system. -// -// Design rules enforced here: -// - Concrete event types may be registered for full PubSub (Publisher + Subscriber). -// - Interfaces may ONLY be registered as Subscriber. -// - Publishing interface types is explicitly forbidden. -// - using System; using Wehlney.EventBus; using Reflex.Core; @@ -18,23 +8,9 @@ namespace Wehlney.EventBus.Reflex public static class PubSubBindings { /// - /// Registers both and for a concrete event type. - /// - /// Interfaces are NOT allowed here. - /// This enforces the architectural rule that only concrete event types may be published. + /// Registers publisher and subscriber bindings for a concrete event type; sticky bindings replay the last value to late subscribers. /// - /// - /// The concrete event type to register. - /// Must NOT be an interface. - /// - /// The DI container builder. - /// - /// Enables sticky behavior for this event type. - /// If enabled, the last published value will be replayed to new subscribers. - /// - /// - /// Thrown if T is an interface. - /// + /// Thrown when T is an interface. public static PubSubRegistration RegisterPubSub(this ContainerBuilder builder, bool sticky = false) where T : IBaseEvent { @@ -50,22 +26,8 @@ public static PubSubRegistration RegisterPubSub(this ContainerBuilder buil } /// - /// Registers a only. - /// - /// This method is intended for: - /// - Marker interfaces (e.g. IFailureEvent) - /// - Cross-cutting contracts - /// - Base event abstractions - /// - /// Both interfaces and concrete types are allowed. + /// Registers a subscriber binding. Interfaces are allowed for marker or cross-cutting event routes. /// - /// - /// The event type or interface to subscribe to. - /// - /// The DI container builder. - /// - /// Enables sticky behavior for this event type. - /// public static void RegisterSubscriber(this ContainerBuilder builder, bool sticky = false) where T : IEventMarker { @@ -78,22 +40,9 @@ public static void RegisterSubscriber(this ContainerBuilder builder, bool sti } /// - /// Registers a only. - /// - /// Interfaces are NOT allowed. - /// Publishing must always occur through concrete event types. + /// Registers a publisher binding for a concrete event type. /// - /// - /// The concrete event type to publish. - /// Must NOT be an interface. - /// - /// The DI container builder. - /// - /// Enables sticky behavior for this event type. - /// - /// - /// Thrown if T is an interface. - /// + /// Thrown when T is an interface. public static PubSubRegistration RegisterPublisher(this ContainerBuilder builder, bool sticky = false) where T : IBaseEvent { diff --git a/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PurrNetPubSubBindings.cs b/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PurrNetPubSubBindings.cs index 3d6a9e6..b437e3d 100644 --- a/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PurrNetPubSubBindings.cs +++ b/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PurrNetPubSubBindings.cs @@ -1,5 +1,3 @@ -// File: PurrNetPubSubBindings.cs - using Wehlney.EventBus; using Wehlney.EventBus.PurrNet; using PurrNet.Packing; diff --git a/eventbus/com.wehlney.eventbus/Runtime/Core/EventBus.cs b/eventbus/com.wehlney.eventbus/Runtime/Core/EventBus.cs index a2cac09..64b81da 100644 --- a/eventbus/com.wehlney.eventbus/Runtime/Core/EventBus.cs +++ b/eventbus/com.wehlney.eventbus/Runtime/Core/EventBus.cs @@ -77,10 +77,6 @@ public void Unsubscribe(in SubscriptionToken token) bucket.Remove(token.Index, token.Version); } - // ---------------------------- - // Helpers - // ---------------------------- - private HandlerBucket GetOrCreateBucket(Type key) { if (_buckets.TryGetValue(key, out var bucket)) diff --git a/eventbus/com.wehlney.eventbus/Runtime/Core/Events.cs b/eventbus/com.wehlney.eventbus/Runtime/Core/Events.cs index 8b61887..5274c30 100644 --- a/eventbus/com.wehlney.eventbus/Runtime/Core/Events.cs +++ b/eventbus/com.wehlney.eventbus/Runtime/Core/Events.cs @@ -5,15 +5,8 @@ namespace Wehlney.EventBus { - //Base Record & Base Marker /// - /// Root marker interface for the PubSub event system. - /// - /// This interface is intended strictly as a base contract for - /// inheritance and grouping within the PubSub infrastructure. - /// - /// Do NOT use this interface directly as an event type. - /// Always derive a dedicated marker interface or concrete event from it. + /// Root marker for event contracts. Use a derived marker or concrete event type instead of this interface directly. /// public interface IEventMarker { @@ -21,14 +14,8 @@ public interface IEventMarker public interface IBaseEvent : IEventMarker { } - /// - /// Abstract base record for all concrete publishable events. - /// - /// This type exists solely as an inheritance root for the PubSub system. - /// It must not be used as a standalone event. - /// - /// Always create a specific derived record when defining an event. + /// Base record for concrete publishable events. /// public abstract record LocalEvent : IBaseEvent { @@ -58,9 +45,6 @@ IEnumerable e when value is not string } } - // Semantics public interface ICommand : IEventMarker { } public interface IStateChange : IEventMarker { } - - // Outcome / Result markers } diff --git a/eventbus/com.wehlney.eventbus/Runtime/Core/Publisher.cs b/eventbus/com.wehlney.eventbus/Runtime/Core/Publisher.cs index ead35c2..24bfb46 100644 --- a/eventbus/com.wehlney.eventbus/Runtime/Core/Publisher.cs +++ b/eventbus/com.wehlney.eventbus/Runtime/Core/Publisher.cs @@ -1,5 +1,3 @@ -// File: Publisher.cs - using System; namespace Wehlney.EventBus @@ -12,8 +10,7 @@ public Publisher(IEventBus bus, bool stickyEnabled) { _bus = bus ?? throw new ArgumentNullException(nameof(bus)); - // HARD GUARD: - // Interfaces are Marker only and shall not be used as Publishers - Use Records instead + // Interfaces are marker routes only; publishers must use concrete event records. if (typeof(T).IsInterface) { throw new InvalidOperationException( diff --git a/eventbus/com.wehlney.eventbus/Runtime/Core/Subscriber.cs b/eventbus/com.wehlney.eventbus/Runtime/Core/Subscriber.cs index 0a29fca..59f6a41 100644 --- a/eventbus/com.wehlney.eventbus/Runtime/Core/Subscriber.cs +++ b/eventbus/com.wehlney.eventbus/Runtime/Core/Subscriber.cs @@ -1,5 +1,3 @@ -// File: Subscriber.cs - using System; namespace Wehlney.EventBus diff --git a/eventbus/com.wehlney.eventbus/Runtime/Core/SubscriptionBag.cs b/eventbus/com.wehlney.eventbus/Runtime/Core/SubscriptionBag.cs index 27fe6eb..d8d85db 100644 --- a/eventbus/com.wehlney.eventbus/Runtime/Core/SubscriptionBag.cs +++ b/eventbus/com.wehlney.eventbus/Runtime/Core/SubscriptionBag.cs @@ -4,8 +4,7 @@ namespace Wehlney.EventBus { /// - /// holds SubscriptionTokens central. - /// No IDisposable-Interfaces -> No Boxing. + /// Owns subscription tokens without storing them as IDisposable, avoiding boxing on dispose. /// public sealed class SubscriptionBag : IDisposable { From fe2739a52c40e852cc62c927c236bb50e6e44a88 Mon Sep 17 00:00:00 2001 From: Wehlney <52572763+Wehlney@users.noreply.github.com> Date: Fri, 3 Jul 2026 18:19:08 +0200 Subject: [PATCH 2/2] Restore EventBus API comments --- .../Runtime/Reflex/PubSubBindings.cs | 38 ++++++++++++++++--- .../Runtime/Core/Events.cs | 10 ++++- 2 files changed, 42 insertions(+), 6 deletions(-) diff --git a/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PubSubBindings.cs b/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PubSubBindings.cs index c3cb308..4c89191 100644 --- a/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PubSubBindings.cs +++ b/eventbus/com.wehlney.eventbus.reflex/Runtime/Reflex/PubSubBindings.cs @@ -8,9 +8,19 @@ namespace Wehlney.EventBus.Reflex public static class PubSubBindings { /// - /// Registers publisher and subscriber bindings for a concrete event type; sticky bindings replay the last value to late subscribers. + /// Registers both and for a concrete event type. /// - /// Thrown when T is an interface. + /// + /// Interfaces are not allowed here. Publishable events must be concrete event records, + /// while interfaces are subscriber-only routes. + /// + /// The concrete event type to register. + /// The DI container builder. + /// + /// Enables sticky behavior for this event type. + /// If enabled, the last published value is replayed to new subscribers. + /// + /// Thrown if T is an interface. public static PubSubRegistration RegisterPubSub(this ContainerBuilder builder, bool sticky = false) where T : IBaseEvent { @@ -26,8 +36,17 @@ public static PubSubRegistration RegisterPubSub(this ContainerBuilder buil } /// - /// Registers a subscriber binding. Interfaces are allowed for marker or cross-cutting event routes. + /// Registers a only. /// + /// + /// Use this for marker interfaces, cross-cutting event contracts, and base event + /// abstractions. Both interfaces and concrete event types are valid subscriber routes. + /// + /// The event type or interface to subscribe to. + /// The DI container builder. + /// + /// Enables sticky replay for this subscriber route. + /// public static void RegisterSubscriber(this ContainerBuilder builder, bool sticky = false) where T : IEventMarker { @@ -40,9 +59,18 @@ public static void RegisterSubscriber(this ContainerBuilder builder, bool sti } /// - /// Registers a publisher binding for a concrete event type. + /// Registers a only. /// - /// Thrown when T is an interface. + /// + /// Interfaces are not allowed. Publishing must happen through concrete event records so + /// routing can dispatch to the concrete type and any registered subscriber interfaces. + /// + /// The concrete event type to publish. + /// The DI container builder. + /// + /// Enables sticky behavior for this event type. + /// + /// Thrown if T is an interface. public static PubSubRegistration RegisterPublisher(this ContainerBuilder builder, bool sticky = false) where T : IBaseEvent { diff --git a/eventbus/com.wehlney.eventbus/Runtime/Core/Events.cs b/eventbus/com.wehlney.eventbus/Runtime/Core/Events.cs index 5274c30..0fbd01e 100644 --- a/eventbus/com.wehlney.eventbus/Runtime/Core/Events.cs +++ b/eventbus/com.wehlney.eventbus/Runtime/Core/Events.cs @@ -6,8 +6,12 @@ namespace Wehlney.EventBus { /// - /// Root marker for event contracts. Use a derived marker or concrete event type instead of this interface directly. + /// Root marker interface for the event system. /// + /// + /// Use this only as the base contract for inheritance and grouping. Do not use it + /// directly as an event route; derive a dedicated marker interface or concrete event. + /// public interface IEventMarker { }; @@ -17,6 +21,10 @@ public interface IBaseEvent : IEventMarker { } /// /// Base record for concrete publishable events. /// + /// + /// This is the inheritance root for local event records. Define a specific derived + /// record for each event instead of publishing directly. + /// public abstract record LocalEvent : IBaseEvent { public override string ToString()