Swiftpack.co - Package - ReactiveCocoa/ReactiveSwift

ReactiveSwift

Streams of values over time. Tailored for Swift.

Latest ReactiveSwift Documentation Join the ReactiveSwift Slack community.


Carthage compatible CocoaPods compatible SwiftPM compatible GitHub release Swift 4.0 platforms

🎉 Getting Started 🚄 Release Roadmap

What is ReactiveSwift?

ReactiveSwift offers composable, declarative and flexible primitives that are built around the grand concept of streams of values over time.

These primitives can be used to uniformly represent common Cocoa and generic programming patterns that are fundamentally an act of observation, e.g. delegate pattern, callback closures, notifications, control actions, responder chain events, futures/promises and key-value observing (KVO).

Because all of these different mechanisms can be represented in the same way, it’s easy to declaratively compose them together, with less spaghetti code and state to bridge the gap.

Getting Started

  1. Core Reactive Primitives

    An overview of the semantics and example use cases of the ReactiveSwift primitives, including Signal, SignalProducer, Property and Action.

  2. Basic Operators

    An overview of the operators provided to compose and transform streams of values.

  3. ReactiveCocoa

    Building on top of ReactiveSwift, ReactiveCocoa extends Cocoa platform frameworks with reactive bindings and extensions.

    GitHub releaseCarthage compatible CocoaPods compatible

  4. How does ReactiveSwift relate to RxSwift?

    An overview of how ReactiveSwift differs from RxSwift for Swift idiomaticity.

Examples

  1. Interactive Form UI

    ReactiveSwift includes a UI Examples playground, which demonstrates:

    • how to build an interactive form UI with bindings, properties and Actions, with a live view in action.
    • how to use reactive primitives to implement the Model-View-ViewModel architectural pattern, with the View Model being the source of truth for the View.
  2. Online Searching

Advanced Topics

  1. ReactiveCocoa

    Bindings and reactive extensions for Cocoa and Cocoa Touch frameworks are offered separately as ReactiveCocoa.

  2. API Reference

  3. API Contracts

    Contracts of the ReactiveSwift primitives, Best Practices with ReactiveSwift, and Guidelines on implementing custom operators.

  4. Debugging Techniques

Installation

ReactiveSwift supports macOS 10.9+, iOS 8.0+, watchOS 2.0+, tvOS 9.0+ and Linux.

Carthage

If you use Carthage to manage your dependencies, simply add ReactiveSwift to your Cartfile:

github "ReactiveCocoa/ReactiveSwift" ~> 3.0

If you use Carthage to build your dependencies, make sure you have added ReactiveSwift.framework, and Result.framework to the "Linked Frameworks and Libraries" section of your target, and have included them in your Carthage framework copying build phase.

CocoaPods

If you use CocoaPods to manage your dependencies, simply add ReactiveSwift to your Podfile:

pod 'ReactiveSwift', '~> 3.0'

Swift Package Manager

If you use Swift Package Manager, simply add ReactiveSwift as a dependency of your package in Package.swift:

.Package(url: "https://github.com/ReactiveCocoa/ReactiveSwift.git", majorVersion: 3)

Git submodule

  1. Add the ReactiveSwift repository as a submodule of your application’s repository.
  2. Run git submodule update --init --recursive from within the ReactiveCocoa folder.
  3. Drag and drop ReactiveSwift.xcodeproj and Carthage/Checkouts/Result/Result.xcodeproj into your application’s Xcode project or workspace.
  4. On the “General” tab of your application target’s settings, add ReactiveSwift.framework, and Result.framework to the “Embedded Binaries” section.
  5. If your application target does not contain Swift code at all, you should also set the EMBEDDED_CONTENT_CONTAINS_SWIFT build setting to “Yes”.

Playground

We also provide a great Playground, so you can get used to ReactiveCocoa's operators. In order to start using it:

  1. Clone the ReactiveSwift repository.
  2. Retrieve the project dependencies using one of the following terminal commands from the ReactiveSwift project root directory:
    • git submodule update --init --recursive OR, if you have Carthage installed
    • carthage checkout
  3. Open ReactiveSwift.xcworkspace
  4. Build Result-Mac scheme
  5. Build ReactiveSwift-macOS scheme
  6. Finally open the ReactiveSwift.playground
  7. Choose View > Show Debug Area

Have a question?

If you need any help, please visit our GitHub issues or Stack Overflow. Feel free to file an issue if you do not manage to find any solution from the archives.

Release Roadmap

Current Stable Release:
GitHub release

Plan of Record

ABI stability release

ReactiveSwift is expected to declare library ABI stability when Swift rolls out resilence support. Until then, ReactiveSwift would incrementally adopt new language features that help move towards to goal. The ETA is Swift 5.

Github

link
Stars: 1983
Help us keep the lights on

Releases

4.0.0 - Jul 17, 2018

This is the first release of ReactiveSwift 4.0. It requires Swift 4.1 or above.

Xcode 10 Support

  1. Swift 4.2 and Xcode 10 support (#644, kudos to @ikesyo)

Operators

  1. New method collect(every:on:skipEmpty:discardWhenCompleted:) which delivers all values that occurred during a time interval (#619, kudos to @Qata)
  2. debounce now offers an opt-in behaviour to preserve the pending value when the signal or producer completes. You may enable it by specifying discardWhenCompleted as false (#287, kudos to @Qata)
  3. New property operator: filter (#586, kudos to @iv-mexx)
  4. New operator merge(with:) (#600, kudos to @ra1028)
  5. New operator map(value:) (#601, kudos to @ra1028)
  6. SignalProducer.merge(with:), SignalProducer.concat, SignalProducer.prefix, SignalProducer.then, SignalProducer.and, SignalProducer.or, SignalProducer.zip(with:), SignalProducer.sample(with:), SignalProducer.sample(on:), SignalProducer.take(until:), SignalProducer.take(untilReplacement:), SignalProducer.skip(until:), SignalProducer.flatMap, SignalProducer.flatMapError, SignalProducer.combineLatest(with:), Signal.flatMap, Signal.flatMapError, Signal.withLatest(from:) and Property.init(initial:then:) now accept SignalProducerConvertible conforming types (#610, #611, kudos to @ra1028)

Changes: <~ Bindings

  1. <~ bindings now works with optional left-hand-side operands. (#642, kudos to @andersio and @Ankit-Aggarwal)

    let nilTarget: BindingTarget<Int>? = nil
    
    // This is now a valid binding. Previously required manual
    // unwrapping in ReactiveSwift 3.x.
    nilTarget <~ notifications.map { $0.count }
    

Changes: Conditional Conformance

  1. For Swift 4.1 and above, BindingSource conformances are required to have Error parameterized as exactly NoError. As a result, Signal and SignalProducer are now conditionally BindingSource. (#590, kudos to @NachoSoto and @andersio)
  2. For Swift 4.1 and above, Signal.Event and ActionError are now conditionally Equatable. (#590, kudos to @NachoSoto and @andersio)

Interoperability

  1. Result now interoperates with SignalProducer n-ary operators as a constant producer (#606, kudos to @Qata)

Miscellaneous

  1. When unfair locks from libplatform are unavailable, ReactiveSwift now fallbacks to error checking Pthread mutexes instead of the default. Mitigations regarding issues with pthread_mutex_trylock have also been applied. (#654, kudos to @andersio)
  2. Lifetime may now be manually ended using Lifetime.Token.dispose(), in addition to the existing when-token-deinitializes semantic. (#641, kudos to @andersio)
  3. Bag may now be initialised with a sequence of elements. (#609, kudos to @ra1028)
  4. Non-class types may now conform to ReactiveExtensionProvider. (#636, kudos to @ra1028)
  5. Fix some documentation errors about Carthage usage (#655)
  6. [CocoaPods] CocoaPods 1.4.0 is the minimum required version. (#651, kudos to @ikesyo)

4.0.0-rc.2 - Jun 14, 2018

This is the second release candidate of ReactiveSwift 4.0. It requires Swift 4.1 or above.

Change

  1. Swift 4.2 and Xcode 10 support (#644, kudos to @ikesyo)

4.0.0-rc.1 - Jun 1, 2018

This is the first release candidate of ReactiveSwift 4.0. It requires Swift 4.1.

Operators

  1. New method collect(every:on:skipEmpty:discardWhenCompleted:) which delivers all values that occurred during a time interval (#619, kudos to @Qata)
  2. debounce now offers an opt-in behaviour to preserve the pending value when the signal or producer completes. You may enable it by specifying discardWhenCompleted as false (#287, kudos to @Qata)
  3. New property operator: filter (#586, kudos to @iv-mexx)
  4. New operator merge(with:) (#600, kudos to @ra1028)
  5. New operator map(value:) (#601, kudos to @ra1028)
  6. SignalProducer.merge(with:), SignalProducer.concat, SignalProducer.prefix, SignalProducer.then, SignalProducer.and, SignalProducer.or, SignalProducer.zip(with:), SignalProducer.sample(with:), SignalProducer.sample(on:), SignalProducer.take(until:), SignalProducer.take(untilReplacement:), SignalProducer.skip(until:), SignalProducer.flatMap, SignalProducer.flatMapError, SignalProducer.combineLatest(with:), Signal.flatMap, Signal.flatMapError, Signal.withLatest(from:) and Property.init(initial:then:) now accept SignalProducerConvertible conforming types (#610, #611, kudos to @1028)

Changes: Conditional Conformance

  1. For Swift 4.1 and above, BindingSource conformances are required to have Error parameterized as exactly NoError. As a result, Signal and SignalProducer are now conditionally BindingSource. (#590, kudos to @NachoSoto and @andersio)
  2. For Swift 4.1 and above, Signal.Event and ActionError are now conditionally Equatable. (#590, kudos to @NachoSoto and @andersio)

Interoperability

  1. Result now interoperates with SignalProducer n-ary operators as a constant producer (#606, kudos to @Qata)

Miscellaneous

  1. Lifetime may now be manually ended using Lifetime.Token.dispose(), in addition to the existing when-token-deinitializes semantic. (#641, kudos to @andersio)
  2. Bag may now be initialised with a sequence of elements. (#609, kudos to @ra1028)
  3. Non-class types may now conform to ReactiveExtensionProvider. (#636, kudos to @ra1028)

3.1.0 - Jan 11, 2018

This is the first release of ReactiveSwift 3.1. It supports Swift 3.2 and Swift 4.0.

Bugfix

  1. Fixed a scenario of downstream interruptions being dropped. (#577, kudos to @andersio)

    Manual interruption of time shifted producers, including delay, observe(on:), throttle, debounce and lazyMap, should discard outstanding events at best effort ASAP.

    But in ReactiveSwift 2.0 to 3.0, the manual interruption is ignored if the upstream producer has terminated. For example:

    // Completed upstream + `delay`.
    SignalProducer.empty
        .delay(10.0, on: QueueScheduler.main)
        .startWithCompleted { print("The producer should have been interrupted!") }
        .dispose()
    
    // Console(t+10): The producer should have been interrupted!
    

    The expected behavior has now been restored.

    Please note that, since ReactiveSwift 2.0, while the interruption is handled immediately, the interrupted event delivery is not synchronous — it generally respects the closest asynchronous operator applied, and delivers on that scheduler.

  2. Fixed schedule(after:interval:leeway:) being cancelled when the returned Disposable is not retained. (#584, kudos to @jjoelson)

    The issue affects only direct use of QueueScheduler. SignalProducer.timer is not affected.

Addition

  1. SignalProducer.concat now has an overload that accepts an error. (#564, kudos to @nmccann)

Change

  1. Fix some documentation errors (#560, kudos to @ikesyo)

3.1.0-rc.1 - Dec 22, 2017

This is the first release candidate of ReactiveSwift 3.1. It supports Swift 3.2 and Swift 4.0.

Bugfix

  1. Fixed a scenario of downstream interruptions being dropped. (#577, kudos to @andersio)

    Manual interruption of time shifted producers, including delay, observe(on:), throttle, debounce and lazyMap, should discard outstanding events at best effort ASAP.

    But in ReactiveSwift 2.0 to 3.0, the manual interruption is ignored if the upstream producer has terminated. For example:

    // Completed upstream + `delay`.
    SignalProducer.empty
        .delay(10.0, on: QueueScheduler.main)
        .startWithCompleted { print("Value should have been discarded!") }
        .dispose()
    
    // Console(t+10): Value should have been discarded!
    

    The expected behavior has now been restored.

    Please note that, since ReactiveSwift 2.0, while the interruption is handled immediately, the interrupted event delivery is not synchronous — it generally respects the closest asynchronous operator applied, and delivers on that scheduler.

Addition

  1. SignalProducer.concat now has an overload that accepts an error. (#564, kudos to @nmccann)

Change

  1. Fix some documentation errors (#560, kudos to @ikesyo)