SignalKit

SignalKit is a reactive Swift framework with focus on clean and readable API.

Code Quality Rank: L5

Programming language: Swift

License: MIT License

Tags: Events    

Latest version: v4.0.0

README

---

Abstract

SignalKit is a lightweight event and binding framework. The core of SignalKit is the Observable protocol. Each implementation of the Observable protocol defines the type of the observation thus an Observable can sendNext only one type of event. For example an Observable of type String can only sendNext String values.

Another key protocol is SignalType which implements Observable and Disposable. Each SignalType implementation has a property disposableSource: Disposable? which points to a Disposable that comes before the current signal.

Because SignalType implements Disposable we can use the disposableSource property to chain signal operations like map, filter and combineLatest together. Each operation returns either a new SignalType or a Disposable. When we call dispose() on a SignalType it will dispose the whole chain of operations.

To store the chain of operations we can use a stored property or the disposeWith(container: DisposableBag) -> Disposable method on the Disposable protocol. When DisposableBag is deinitialized it will dispose all of its items for us.

let disposableBag = DisposableBag()
let userName = Signal<String>()

userName.next { print("name: \($0)") }
    .disposeWith(disposableBag)

userName.sendNext("John") // prints "name: John"

Events And Bindings

SignalKit comes with an elegant way to observe for different event sources like KVO, Target Action and NSNotificationCenter via an unified API by simply calling observe() method. The observe method is a protocol extension on the NSObjectProtocol which returns a SignalEvent with sender Self. Then we use Protocol Oriented Programming to add extensions to a SignalEventType protocol where Sender is from a given type.

Key Value Observing

Let's say we want to observe an instance of class Person: NSObject for it's name property changes with KVO. This is super easy with SignalKit, just call observe() on the instance and it will return the available events for this type. Then choose keyPath(path: String, value: T) where for the value parameter pass the initial value of the property. SignalKit will use this initial value type to perform an optional type cast on the values sent by KVO.

let person = Person(name: "John")

person.observe()
    .keyPath("name", value: person.name)
    .next { print("Hello \($0)") }
    .disposeWith(disposableBag)

Target Action

SignalKit comes with SignalEventType extensions for controls which inherits from UIControl and UIBarButtonItem:

let control = UIControl()
let barButton = UIBarButtonItem()

control.observe().events([.TouchUpInside])
    .next { _ in print("Tap!") }
    .disposeWith(disposableBag)

barButton.observe().tapEvent
    .next { _ in print("Tap!") }
    .disposeWith(disposableBag)

NSNotificationCenter

SignalEventType also have a handy extensions for observing an instance of NSNotificationCenter for notifications:

let center = NSNotificationCenter.defaultCenter()

center.observe().notification(UIApplicationWillResignActiveNotification)
    .next{ _ in print("Resign Active") }
    .disposeWith(disposableBag)

Bindings

Bindings in SignalKit are implemented again with protocol extensions. We extend the SignalType where the ObservationType (from the generic Observable protocol) is from a certain type and add method to bind the value to a UI control like UILabel. Here is an example of binding the String value from the signal to the text property of UILabel:

let userName = Signal<String>()
let nameLabel = UILabel()

userName.bindTo(textIn: nameLabel)
    .disposeWith(disposableBag)

Signals

Signal

Signal is the primary object which you can use to send events and it is thread safe.

SignalValue

SignalValue is a signal that stores its last sent/current value. If we add a new observer to it it will send immediately its value to the newly added observer. If we change the value of the signal it will notify its observers for the change. SignalValue is also thread safe.

let name = SignalValue(value: "John")

name.next { print($0) }.disposeWith(bag) // prints "John"

name.value = "Jonathan" // prints "Jonathan"

CollectionEvent

We can use a signal of type Signal<CollectionEvent> to send the changes that occur in our data source. Then we can bind the signal to UITableView or UICollectionView and the changes that we send will be reflected in the table/collection view:

// UsersListViewController
...
viewModel.usersChangeSignal.bindTo(tableView, rowAnimation: .Fade).disposeWith(bag)

// UsersListViewModel
let usersChangeSignal = Signal<CollectionEvent>()
var users = [User]()
...

var event = CollectionEvent()

users.insert(User(name: "John"), atIndex: 0)
event.itemInsertedAt(0, inSection: 0)

usersChangeSignal.sendNext(event)

Operations

SignalKit comes with the following SignalType operations:

Extensions

Currently SignalKit comes with extensions for the the following UIKit components:

Keyboard

You can use the Keyboard structure to observe for keyboard events posted by the system. Then you will get back a structure of type KeyboardState which you can query for the keyboard end/start frame and other data that the system sends with the notification:

Keyboard.observe().willShow
    .next { print($0.endFrame) }
    .disposeWith(disposableBag)

Installation

SignalKit requires Swift 2.0 and Xcode 7

Carthage

Add the following line to your Cartfile

github "yankodimitrov/SignalKit" "master"

CocoaPods

Add the following line to your Podfile

pod “SignalKit”

License

SignalKit is released under the MIT license. See the LICENSE.txt file for more info.