SwiftObserver is a lightweight package for reactive Swift. Its design goals make it easy to learn and a joy to use:

1. Meaningful Code 💡
   SwiftObserver promotes meaningful metaphors, names and syntax, producing highly readable code.
2. Non-intrusive Design ✊🏻
   SwiftObserver doesn't limit or modulate your design. It just makes it easy to do the right thing.
3. Simplicity 🕹
   SwiftObserver employs few radically simple concepts and applies them consistently without exceptions.
4. Flexibility 🤸🏻‍♀️
   SwiftObserver's types are simple but universal and composable, making them applicable in many situations.
5. Safety ⛑
   SwiftObserver eradicates those memory leaks that typically come with observer- and reactive patterns.

SwiftObserver is only 1400 lines of production code, but it's well beyond a 1000 hours of work, re-imagining and reworking it many times, letting go of fancy features, documenting, unit-testing, and battle-testing it in practice.

Reactive Programming adresses the central challenge of implementing effective architectures: controlling dependency direction, in particular making specific concerns depend on abstract ones. SwiftObserver breaks reactive programming down to its essence, which is the Observer Pattern.

SwiftObserver diverges from convention as it doesn't inherit the metaphors, terms, types, or function- and operator arsenals of common reactive libraries. It's not as fancy as Rx and Combine and not as restrictive as Redux. Instead, it offers a powerful simplicity you might actually love to work with.

• Get Involved
• Get Started
  • Install
  • Introduction
• Messengers
  • Understand Observable Objects
• Variables
  • Observe Variables
  • Enjoy the Property Wrapper
  • Encode and Decode Variables
• Transforms
  • Make Transforms Observable
  • Use Prebuilt Transforms
  • Chain Transforms
• Advanced
  • Interoperate With Combine
  • Message Authors
  • Cached Messages
  • Weak Observable Objects
• More

• Found a bug? Create a github issue.
• Need a feature? Create a github issue.
• Want to improve stuff? Create a pull request.
• Need support and troubleshooting? Write at hello@codeface.io.
• Want to contact us? Write at hello@codeface.io.

With the Swift Package Manager, you add the SwiftObserver package via Xcode (11+).

Or you manually adjust the Package.swift file of your project:

// swift-tools-version:5.6.0

import PackageDescription

let package = Package(
    name: "MyProject",
    platforms: [
        .iOS(.v12), .macOS(.v10_14), .tvOS(.v12), .watchOS(.v6)
    ],
    products: [
        .library(
            name: "MyProject",
            targets: ["MyProject"]
        )
    ],
    dependencies: [
        .package(
            url: "https://github.com/codeface-io/SwiftObserver.git",
            exact: "7.0.3"
        )
    ],
    targets: [
        .target(name: "MyProject",
                dependencies: ["SwiftObserver"])
    ]
)

Then run $ swift build or $ swift run.

Finally, in your Swift files:

import SwiftObserver

No need to learn a bunch of arbitrary metaphors, terms or types.

SwiftObserver is simple: Objects observe other objects.

Or a tad more technically: Observable objects send messages to their observers.

That's it. Just readable code:

dog.observe(Sky.shared) { color in
    // marvel at the sky changing its color
}

Any object can be an Observer if it has a Receiver for receiving messages:

class Dog: Observer {
    let receiver = Receiver()
}

The receiver keeps the observer's observations alive. The observer just holds on to it strongly.

• For a message receiving closure to be called, the Observer/Receiver must still be alive. There's no awareness after death in memory.
• An Observer can do multiple simultaneous observations of the same ObservableObject, for example by calling observe(...) multiple times.
• You can check wether an observer is observing an "observable" via observer.isObserving(observable).

Any object can be an ObservableObject if it has a Messenger<Message> for sending messages:

class Sky: ObservableObject {
    let messenger = Messenger<Color>()  // Message == Color
}

• An ObservableObject sends messages via send(_ message: Message). The object's clients, even its observers, are also free to call that function.
• An ObservableObject delivers messages in exactly the order in which send is called, which helps when observers, from their message handling closures, somehow trigger further calls of send.
• Just starting to observe an ObservableObject does not trigger it to send a message. This keeps everything simple, predictable and consistent.

1. Create a Messenger<Message>. It's a mediator through which other entities communicate.
2. Create an object of a custom ObservableObject class that utilizes Messenger<Message>.
3. Create a Variable<Value> (a.k.a. Var<Value>). It holds a value and sends value updates.
4. Create a transform object. It wraps and transforms another ObservableObject.

When an Observer or ObservableObject dies, SwiftObserver cleans up all related observations automatically, making those memory leaks impossible that typically come with observer- and reactive patterns. So there's no specific memory management to worry about – nor are there "Cancellables", "Tokens", "DisposeBags" or any such weirdness.

However, observing- and observed objects can stop particular- or all their ongoing observations:

dog.stopObserving(Sky.shared)          // no more messages from the sky
dog.stopObserving()                    // no more messages from anywhere
Sky.shared.stopBeingObserved(by: dog)  // no more messages to dog
Sky.shared.stopBeingObserved()         // no more messages to anywhere

Have a look at the internal codebase (compositions and essential dependencies) of the "SwiftObserver" target:

Diagrams of all top-level source folders are over here. The images were generated with Codeface.

Messenger is the simplest ObservableObject and the basis of every other ObservableObject. It doesn't send messages by itself, but anyone can send messages through it and use it for any type of message:

let textMessenger = Messenger<String>()

observer.observe(textMessenger) { textMessage in
    // respond to textMessage
}

textMessenger.send("my message")

Messenger embodies the common messenger / notifier pattern and can be used for that out of the box.

Having a Messenger is actually what defines ObservableObject:

public protocol ObservableObject: class {
    var messenger: Messenger<Message> { get }
    associatedtype Message: Any
}

Messenger is itself an ObservableObject because it points to itself as the required Messenger:

extension Messenger: ObservableObject {
    public var messenger: Messenger<Message> { self }
}

Every other ObservableObject class is either a subclass of Messenger or a custom ObservableObject class that provides a Messenger. Custom observables often employ some enum as their message type:

class Model: SuperModel, ObservableObject {
    func foo() { send(.willUpdate) }
    func bar() { send(.didUpdate) }
    deinit { send(.willDie) }
    let messenger = Messenger<Event>()  // Message == Event
    enum Event { case willUpdate, didUpdate, willDie }
}

Var<Value> is an ObservableObject that has a property value: Value.

Whenever its value changes, Var<Value> sends a message of type Update<Value>, informing about the old and new value:

let number = Var(42)

observer.observe(number) { update in
    let whatsTheBigDifference = update.new - update.old
}

number <- 123

In addition, you can always manually call variable.send() (without argument) to send an update in which old and new both hold the current value (see Cached Messages).

Using the property wrapper Observable, the above example would look like this:

@Observable var number = 42

observer.observe($number) { update in
    let whatsTheBigDifference = update.new - update.old
}

number = 123

The wrapper's projected value provides the underlying Var<Value>, which you access via the $ sign like in the above example. This is analogous to how you access publishers in Combine.

A Var<Value> is automatically Codable if its Value is. So when one of your types has Var properties, you can make that type Codable by simply adopting the Codable protocol:

class Model: Codable {
    private(set) var text = Var("String Variable")
}

Note that text is a var instead of a let. It cannot be constant because Swift's implicit decoder must mutate it. However, clients of Model would be supposed to set only text.value and not text itself, so the setter is private.

Transforms make common steps of message processing more succinct and readable. They allow to map, filter and unwrap messages in many ways. You may freely chain these transforms together and also define new ones with them.

This example transforms messages of type Update<String?> into ones of type Int:

let title = Var<String?>()

observer.observe(title).new().unwrap("Untitled").map({ $0.count }) { titleLength in
    // do something with the new title length
}

You may transform a particular observation directly on the fly, like in the above example. Such ad hoc transforms give the observer lots of flexibility.

Or you may instantiate a new ObservableObject that has the transform chain baked into it. The above example could then look like this:

let title = Var<String?>()
let titleLength = title.new().unwrap("Untitled").map { $0.count }

observer.observe(titleLength) { titleLength in
    // do something with the new title length
}

Every transform object exposes its underlying ObservableObject as origin. You may even replace origin:

let titleLength = Var("Dummy Title").new().map { $0.count }
let title = Var("Real Title")
titleLength.origin.origin = title

Such stand-alone transforms can offer the same preprocessing to multiple observers. But since these transforms are distinct ObservableObjects, you must hold them strongly somewhere. Holding transform chains as dedicated observable objects suits entities like view models that represent transformations of other data.

Whether you apply transforms ad hoc or as stand-alone objects, they work the same way. The following list illustrates prebuilt transforms as observable objects.

First, there is your regular familiar map function. It transforms messages and often also their type:

let messenger = Messenger<String>()          // sends String
let stringToInt = messenger.map { Int($0) }  // sends Int?

When an ObservableObject like a Var<Value> sends messages of type Update<Value>, we often only care about the new value, so we map the update with new():

let errorCode = Var<Int>()          // sends Update<Int>
let newErrorCode = errorCode.new()  // sends Int

When you want to receive only certain messages, use filter:

let messenger = Messenger<String>()                     // sends String
let shortMessages = messenger.filter { $0.count < 10 }  // sends String if length < 10

Use select to receive only one specific message. select works with all Equatable message types. select maps the message type onto Void, so a receiving closure after a selection takes no message argument:

let messenger = Messenger<String>()                   // sends String
let myNotifier = messenger.select("my notification")  // sends Void (no messages)

observer.observe(myNotifier) {                        // no argument
    // someone sent "my notification"
}

Sometimes, we make message types optional, for example when there is no meaningful initial value for a Var. But we often don't want to deal with optionals down the line. So we can use unwrap(), suppressing nil messages entirely:

let errorCodes = Messenger<Int?>()     // sends Int?       
let errorAlert = errorCodes.unwrap()   // sends Int if the message is not nil

You may also unwrap optional messages by replacing nil values with a default:

let points = Messenger<Int?>()         // sends Int?       
let pointsToShow = points.unwrap(0)    // sends Int with 0 for nil

You may chain transforms together:

let numbers = Messenger<Int>()

observer.observe(numbers).map {
    "\($0)"                      // Int -> String
}.filter {
    $0.count > 1                 // suppress single digit integers
}.map {
    Int.init($0)                 // String -> Int?
}.unwrap {                       // Int? -> Int
    print($0)                    // receive and process resulting Int
}

Of course, ad hoc transforms like the above end on the actual message handling closure. Now, when the last transform in the chain also takes a closure argument for its processing, like map and filter do, we use receive to stick with the nice syntax of trailing closures:

dog.observe(Sky.shared).map {
    $0 == .blue     
}.receive {
    print("Will we go outside? \($0 ? "Yes" : "No")!")
} 

CombineObserver is another library product of the SwiftObserver package. It depends on SwiftObserver and adds a simple way to transform any SwiftObserver-ObservableObject into a Combine-Publisher:

import CombineObserver

@Observable var number = 7                  // SwiftObserver
let numberPublisher = $number.publisher()   // Combine

let cancellable = numberPublisher.dropFirst().sink { numberUpdate in
    print("\(numberUpdate.new)")
}

number = 42 // prints "42"

Some reasoning behind this: SwiftObserver is for pure Swift-/model code without external dependencies – not even on Combine. When combined with Combine (🙊), SwiftObserver would be employed in the model core of an application, while Combine would be used more with I/O periphery like SwiftUI and other system-specific APIs that already rely on Combine. That means, the "Combine layer" might want to observe (react to-) the "SwiftObserver layer" – but hardly the other way around.

Every message has an author associated with it. This feature is only noticable in code if you use it.

An observable object can send an author together with a message via object.send(message, from: author). If noone specifies an author as in object.send(message), the observable object itself becomes the author.

Variables have a special value setter that allows to identify change authors:

let number = Var(0)
number.set(42, as: controller) // controller becomes author of the update message

The observer can receive the author, by adding it as an argument to the message handling closure:

observer.observe(observableObject) { message, author in
    // process message from author
}

Through the author, observers can determine a message's origin. In the plain messenger pattern, the origin would simply be the message sender.

Identifying message authors can become essential whenever multiple observers observe the same object while their actions can cause it so send messages.

Mutable data is a common type of such shared observable objects. For example, when multiple entities observe and modify a storage abstraction or caching hierarchy, they often want to avoid reacting to their own actions. Such overreaction might lead to redundant work or inifnite response cycles. So they identify as change authors when modifying the data and ignore messages from self when observing it:

class Collaborator: Observer {
    func observeText() {
        observe(sharedText).notFrom(self) { update, author in  // see author filters below
            // someone else edited the text
        }
    }
  
    func editText() {
        sharedText.set("my new text", as: self)                // identify as change author
    }
  
    let receiver = Receiver()
}

let sharedText = Var<String>()

There are three transforms related to message authors. As with other transforms, we can apply them directly in observations or create them as standalone observable objects.

We filter authors just like messages:

let messenger = Messenger<String>()             // sends String

let friendMessages = messenger.filterAuthor {   // sends String if message is from friend
    friends.contains($0)
} 

If only one specific author is of interest, filter authors with from. It captures the selected author weakly:

let messenger = Messenger<String>()             // sends String
let joesMessages = messenger.from(joe)          // sends String if message is from joe

If all but one specific author are of interest, use notFrom. It also captures the excluded author weakly:

let messenger = Messenger<String>()             // sends String
let humanMessages = messenger.notFrom(hal9000)  // sends String, but not from an evil AI

An ObservableCache is an ObservableObject that has a property latestMessage: Message which typically returns the last sent message or one that indicates that nothing has changed. ObservableCache has a function send() that takes no argument and sends latestMessage.

1. Any Var is an ObservableCache. Its latestMessage is an Update in which old and new both hold the current value.

2. Calling cache() on an ObservableObject creates a transform that is an ObservableCache. That cache's Message will be optional but never an optional optional, even when the origin's Message is already optional.

   Of course, cache() wouldn't make sense as an adhoc transform of an observation, so it can only create a distinct observable object.

3. Any transform whose origin is an ObservableCache is itself implicitly an ObservableCache if it never suppresses (filters) messages. These compatible transforms are: map, new and unwrap(default).

   Note that the latestMessage of a transform that is an implicit ObservableCache returns the transformed latestMessage of its underlying ObservableCache origin. Calling send(transformedMessage) on that transform itself will not "update" its latestMessage.

4. Custom observable objects can easily conform to ObservableCache. Even if their message type isn't based on some state, latestMessage can still return a meaningful default value - or even nil where Message is optional.

An ObservableObject like Var, that derives its messages from its state, can generate a "latest message" on demand and therefore act as an ObservableCache:

class Model: Messenger<String>, ObservableCache {  // informs about the latest state
    var latestMessage: String { state }            // ... either on demand
  
    var state = "initial state" {
        didSet {
            if state != oldValue {
                send(state)                        // ... or when the state changes
            }
        }
    }
}

When you want to put an ObservableObject into some data structure or as the origin into a transform object but hold it there as a weak reference, transform it via observableObject.weak():

let number = Var(12)
let weakNumber = number.weak()

observer.observe(weakNumber) { update in
    // process update of type Update<Int>
}

var weakNumbers = [Weak<Var<Int>>]()
weakNumbers.append(weakNumber)

Of course, weak() wouldn't make sense as an adhoc transform, so it can only create a distinct observable object.

• Patterns: Read more about some patterns that emerged from using SwiftObserver.
• Philosophy: Read more about the philosophy and features of SwiftObserver.
• License: SwiftObserver is released under the MIT license. See LICENSE for details.

• Update and rework (or simply delete) texts about philosophy and patterns
• Engage feedback and contribution