Refresh README for SPM-first integration and release 5.3.0.

Rewrite docs around Swift Package Manager, document legacy CocoaPods/Carthage as unmaintained, and bump the podspec for the 5.3.0 tag.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: cesarferreira

README.md

@@ -1,197 +1,248 @@
-# SwiftEventBus
+<p align="center">
+  <h1 align="center">SwiftEventBus</h1>
+  <p align="center">
+    A tiny, thread-safe publish/subscribe bus for Apple platforms — decouple components without wiring delegates everywhere.
+  </p>
+  <p align="center">
+    <a href="https://github.com/cesarferreira/SwiftEventBus/actions/workflows/ci.yml"><img src="https://github.com/cesarferreira/SwiftEventBus/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+    <a href="Package.swift"><img src="https://img.shields.io/badge/Swift%20PM-compatible-brightgreen.svg" alt="Swift PM"></a>
+    <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License">
+    <img src="https://img.shields.io/badge/Swift-5-green.svg?style=flat" alt="Swift 5">
+  </p>
+  <p align="center">
+    <a href="#install">Install</a>
+    &nbsp;·&nbsp;
+    <a href="#quickstart">Quickstart</a>
+    &nbsp;·&nbsp;
+    <a href="#highlights">Highlights</a>
+    &nbsp;·&nbsp;
+    <a href="#api">API</a>
+    &nbsp;·&nbsp;
+    <a href="#platforms">Platforms</a>
+  </p>
+</p>
 
-[![CI](https://github.com/cesarferreira/SwiftEventBus/actions/workflows/ci.yml/badge.svg)](https://github.com/cesarferreira/SwiftEventBus/actions/workflows/ci.yml)
-[![Swift Package Manager](https://img.shields.io/badge/Swift%20PM-compatible-brightgreen.svg)](Package.swift)
-[![CocoaPods](https://img.shields.io/badge/CocoaPods-compatible-brightgreen.svg)](https://cocoapods.org/pods/SwiftEventBus)
-[![Carthage](https://img.shields.io/badge/Carthage-compatible-brightgreen.svg)](https://github.com/Carthage/Carthage)
-[![Swift 5](https://img.shields.io/badge/Swift-5-green.svg?style=flat)](https://swift.org)
-
-Allows publish-subscribe-style communication between components without requiring the components to explicitly be aware of each other.
+---
 
-## Features
+## Why SwiftEventBus
 
-- [x] simplifies the communication between components
-- [x] decouples event senders and receivers
-- [x] avoids complex and error-prone dependencies and life cycle issues
-- [x] makes your code simpler
-- [x] is fast
-- [x] is tiny
-- [x] Thread-safe
-- [x] iOS, macOS, tvOS, and watchOS (Swift Package Manager)
+NotificationCenter is built in, but stringly-typed observers, thread hops, and lifecycle cleanup get messy fast. **SwiftEventBus** wraps the same primitives with a small API: register on a target, post by name, unregister when the target goes away.
 
-## Installation
+- **Decouple senders and receivers.** Components talk through event names, not direct references.
+- **Thread-aware delivery.** `onMainThread`, `onBackgroundThread`, or a custom `OperationQueue`.
+- **Main-thread posting.** `postToMainThread` when work finishes off the UI queue.
+- **Lifecycle-friendly.** Track observers per target; `unregister(_:)` tears them down in one call.
+- **Foundation-only.** No UIKit in the library — same API on iOS, macOS, tvOS, and watchOS via **Swift Package Manager**.
+- **Battle-tested.** Built on `NotificationCenter`; registration cache is guarded for concurrent use.
 
-### Swift Package Manager
+## Quickstart
 
-In Xcode: **File → Add Package Dependencies…** and enter:
+Add the package in Xcode (**File → Add Package Dependencies…**):
 
 ```
 https://github.com/cesarferreira/SwiftEventBus.git
 ```
 
-Or add to your `Package.swift`:
+Then wire a subscriber and post an event:
 
 ```swift
-.package(url: "https://github.com/cesarferreira/SwiftEventBus.git", from: "5.2.0")
-```
+import SwiftEventBus
 
-### CocoaPods
+final class ProfileViewController: UIViewController {
+    override func viewDidLoad() {
+        super.viewDidLoad()
 
-```bash
-pod 'SwiftEventBus', '~> 5.2'
-```
+        SwiftEventBus.onMainThread(self, name: "profileUpdated") { notification in
+            self.refreshUI(with: notification?.object)
+        }
+    }
 
-Or pin a release:
+    func saveProfile() {
+        SwiftEventBus.post("profileUpdated", sender: currentUser)
+    }
 
-```bash
-pod 'SwiftEventBus', :tag => '5.2.0', :git => 'https://github.com/cesarferreira/SwiftEventBus.git'
+    deinit {
+        SwiftEventBus.unregister(self)
+    }
+}
 ```
 
-### Carthage
-
-```bash
-github "cesarferreira/SwiftEventBus" ~> 5.2
-```
+**Rule of thumb:** pass `self` (or another long-lived object) as the registration target and call `unregister` when that object is done — typically `deinit` or `viewWillDisappear`.
 
-### Versions
+## Install
 
-- `5.2.+` — Swift 5, iOS 12+, macOS 10.15+, tvOS 12+, watchOS 6+
-- `5.+` — Swift 5
-- `3.+` — Swift 4.2
-- `2.+` — Swift 3
-- `1.1.0` — Swift 2.2
+SwiftEventBus is distributed as a **Swift package**. That is the supported integration path for new apps and libraries.
 
-## macOS
+### Xcode
 
-SwiftEventBus is **Foundation-only** (no UIKit), so it works on **macOS 10.15+** with the same API as on iOS.
+1. **File → Add Package Dependencies…**
+2. Enter `https://github.com/cesarferreira/SwiftEventBus.git`
+3. Choose **Up to Next Major** from `5.3.0` (or a newer release tag)
+4. Add the **SwiftEventBus** product to your app or framework target
 
-**Recommended:** add the package in Xcode (**File → Add Package Dependencies…**) or depend on it from your app's `Package.swift` (see above). CI builds and tests the library on macOS on every push.
+### Package.swift
 
-**CocoaPods** on Mac:
+Add the dependency to your package manifest:
 
-```bash
-pod 'SwiftEventBus', '~> 5.2'
+```swift
+dependencies: [
+    .package(url: "https://github.com/cesarferreira/SwiftEventBus.git", from: "5.3.0"),
+],
+targets: [
+    .target(
+        name: "MyApp",
+        dependencies: ["SwiftEventBus"]
+    ),
+]
 ```
 
-Example in an `NSViewController` subclass:
+Pin an exact version when you need reproducible builds:
 
 ```swift
-import AppKit
-import SwiftEventBus
+.package(url: "https://github.com/cesarferreira/SwiftEventBus.git", exact: "5.3.0"),
+```
 
-final class MainViewController: NSViewController {
-    override func viewDidLoad() {
-        super.viewDidLoad()
+### Command line
 
-        SwiftEventBus.onMainThread(self, name: "refresh") { _ in
-            self.view.needsLayout = true
-        }
-    }
+From an existing Swift package directory:
 
-    deinit {
-        SwiftEventBus.unregister(self)
-    }
-}
+```bash
+swift package resolve
+swift build
+swift test   # when developing against a local checkout of this repo
 ```
 
-The **Sample** app in this repo is iOS-only (storyboard demo). For Mac apps, integrate via Swift Package Manager or CocoaPods as above.
+### Platforms (SPM)
+
+| Release | Swift | Minimum OS |
+| ------- | ----- | ---------- |
+| `5.3.+` | 5     | iOS 12, macOS 10.15, tvOS 12, watchOS 6 |
+| `5.2.+` | 5     | Same platform mins; prefer `5.3.+` for macOS Xcode framework fixes |
+| `5.+`   | 5     | See `Package.swift` `platforms` for the tag you pin |
+| Older tags | 2–4 | Legacy; not recommended for new projects |
+
+### Legacy integrators
 
-## Usage
+[CocoaPods](https://cocoapods.org/) and [Carthage](https://github.com/Carthage/Carthage) are **not** actively maintained for this project anymore. The last published podspec (`SwiftEventBus.podspec`) and Xcode framework target remain in the repo for existing users, but new work should use SPM above.
 
-### 1 — Prepare subscribers
+## Highlights
 
-Subscribers implement event handling methods that will be called when an event is received.
+### Payloads and filtering
+
+Attach a sender object or `userInfo` like any notification:
 
 ```swift
-SwiftEventBus.onMainThread(target, name: "someEventName") { result in
-    // UI thread
+SwiftEventBus.post("personFetched", sender: person)
+SwiftEventBus.post("syncProgress", sender: nil, userInfo: ["percent": 42])
+
+SwiftEventBus.onMainThread(self, name: "personFetched") { note in
+    let person = note?.object as! Person
+    print(person.name)
 }
+```
 
-// or
+Register with a specific `sender` to only receive posts that use the same object:
 
-SwiftEventBus.onBackgroundThread(target, name: "someEventName") { result in
-    // API access
+```swift
+SwiftEventBus.onBackgroundThread(self, name: "jobDone", sender: jobID) { _ in
+    // only fires when post(..., sender: jobID) matches
 }
 ```
 
-### 2 — Post events
+### Background work → main UI
 
-Post an event from any part of your code. All subscribers matching the event type will receive it.
+`NotificationCenter` delivers on the thread where you post. For UI updates, hop explicitly:
 
 ```swift
-SwiftEventBus.post("someEventName")
+SwiftEventBus.onBackgroundThread(self, name: "fetchData") { _ in
+    let result = loadFromNetwork()
+    SwiftEventBus.postToMainThread("fetchDataDone", sender: result)
+}
+
+SwiftEventBus.onMainThread(self, name: "fetchDataDone") { note in
+    self.apply(result: note?.object)
+}
 ```
 
----
+Credit for the original pattern: [@nunogoncalves](https://github.com/nunogoncalves).
 
-### Event bus with parameters
+### macOS
 
-Post event:
+Add the package in Xcode or your `Package.swift` (see [Install](#install)). Example with AppKit:
 
 ```swift
-SwiftEventBus.post("personFetchEvent", sender: Person(name: "john doe"))
-```
+import AppKit
+import SwiftEventBus
 
-Expecting parameters:
+final class MainViewController: NSViewController {
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        SwiftEventBus.onMainThread(self, name: "refresh") { _ in
+            self.view.needsLayout = true
+        }
+    }
 
-```swift
-SwiftEventBus.onMainThread(target, name: "personFetchEvent") { result in
-    let person = result?.object as! Person
-    print(person.name) // will output "john doe"
+    deinit {
+        SwiftEventBus.unregister(self)
+    }
 }
 ```
 
-### Posting events from the background thread to the main thread
+The **Sample** target in this repo is an iOS storyboard demo only; Mac apps should add the Swift package dependency.
 
-Quoting the official Apple [documentation](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Notifications/Articles/Threading.html):
+## API
 
-> Regular notification centers deliver notifications on the thread in which the notification was posted
+### Subscribe
 
-Regarding this limitation, [@nunogoncalves](https://github.com/nunogoncalves) implemented the feature and provided a working example:
+| Method | Delivery |
+| ------ | -------- |
+| `onMainThread(_:name:sender:handler:)` | `OperationQueue.main` |
+| `onBackgroundThread(_:name:sender:handler:)` | Background `OperationQueue` |
+| `on(_:name:sender:queue:handler:)` | Custom queue |
 
-```swift
-@IBAction func clicked(sender: AnyObject) {
-    count += 1
-    SwiftEventBus.post("doStuffOnBackground")
-}
+Handlers receive `(Notification?) -> Void`. Registration returns an observer token (usually you rely on `unregister` instead).
 
-@IBOutlet weak var textField: UITextField!
+### Post
 
-var count = 0
+| Method | Behavior |
+| ------ | -------- |
+| `post(_:sender:)` | Post on the current thread |
+| `post(_:sender:userInfo:)` | Post with dictionary payload |
+| `postToMainThread(_:sender:)` | Async dispatch to main, then post |
+| `postToMainThread(_:sender:userInfo:)` | Same, with `userInfo` |
 
-override func viewDidLoad() {
-    super.viewDidLoad()
+### Unregister
 
-    SwiftEventBus.onBackgroundThread(self, name: "doStuffOnBackground") { _ in
-        print("doing stuff in background thread")
-        SwiftEventBus.postToMainThread("updateText")
-    }
+```swift
+SwiftEventBus.unregister(target)              // all events for target
+SwiftEventBus.unregister(target, name: "x")   // one event name for target
+```
 
-    SwiftEventBus.onMainThread(self, name: "updateText") { _ in
-        self.textField.text = "\(self.count)"
-    }
-}
+## Platforms
 
-// Perhaps on viewDidDisappear depending on your needs
-override func viewWillDisappear(_ animated: Bool) {
-    super.viewWillDisappear(animated)
+SwiftEventBus is tested on every push via [GitHub Actions](https://github.com/cesarferreira/SwiftEventBus/actions):
 
-    SwiftEventBus.unregister(self)
-}
-```
+| Job | What it verifies |
+| --- | ---------------- |
+| **macOS (Swift Package Manager)** | `swift build` / `swift test` on macOS (14 unit tests) |
+| **macOS (Xcode framework)** | Framework build for `generic/platform=macOS` |
+| **iOS (Xcode framework)** | Framework build for iOS |
+| **Sample iOS app** | Sample app build, Simulator launch, smoke event path |
 
----
+**Requirements:** Swift 5, Xcode 15+ recommended for local development.
 
-## Unregistering
+## Sample app
 
-Remove all the observers from the target:
+Open `SwiftEventBus.xcodeproj`, run the **Sample** scheme on an iOS Simulator. It exercises login flow events (`loginCall` → background work → `login` on the main thread). CI launches Sample with `-SmokeTest` to assert the bus end-to-end.
 
-```swift
-SwiftEventBus.unregister(target)
-```
+## Contributing
 
-Remove observers of the same name from the target:
+Issues and PRs welcome. Please keep changes focused; CI must stay green.
 
-```swift
-SwiftEventBus.unregister(target, name: "someEventName")
-```
+1. Fork and branch from `master`
+2. Run tests locally: `swift test` (macOS or Linux Docker with Swift 5.10+)
+3. Open a PR — the workflow runs SPM, iOS/macOS framework builds, and the Sample smoke test
+
+## License
+
+[MIT](LICENSE) © César Ferreira

SwiftEventBus.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name = 'SwiftEventBus'
-  s.version = '5.2.0'
+  s.version = '5.3.0'
   s.license = 'MIT'
   s.summary = 'Publish/subscribe event bus for iOS and macOS'
   s.homepage = 'https://github.com/cesarferreira/SwiftEventBus'