ReactiveObjC Documentation

ReactiveObjC unifies disparate Cocoa APIs like UI callbacks, network responses, and KVO notifications into RACSignal objects. This allows you to compose them using operators like combineLatest:, RACObserve, and rac_signalForControlEvents:.

Key patterns include:

• Using RACObserve(object, keyPath) for KVO.
• Using rac_addObserverForName:object: for NSNotificationCenter.
• Using rac_textSignal for text field changes.
• Using rac_signalForControlEvents: for UI events.

// Example: Combining multiple signals to drive UI state
@weakify(self);

RAC(self.logInButton, enabled) = [RACSignal
    combineLatest:@[
        self.usernameTextField.rac_textSignal,
        self.passwordTextField.rac_textSignal,
        RACObserve(LoginManager.sharedManager, loggingIn),
        RACObserve(self, loggedIn)
    ] reduce:^(NSString *username, NSString *password, NSNumber *loggingIn, NSNumber *loggedIn) {
        return @(username.length > 0 && password.length > 0 && !loggingIn.boolValue && !loggedIn.boolValue);
    }];

When implementing custom operators for RACStream, RACSequence, or RACSignal, follow these best practices to ensure stability and compatibility:

• Prefer RACStream methods: Implement new operators using RACStream methods whenever possible. RACStream provides a simpler interface, and its operators are automatically applicable to both sequences and signals. Key methods like -bind:, -zipWith:, and -concat: are powerful enough for most tasks.
• Use -materialize for error handling: If a RACSignal operator needs to handle error or completed events, use the -materialize method to bring these events into the stream. This allows you to use standard stream operators to manipulate them.
• Compose existing operators: Avoid writing logic from scratch. Use the built-in, tested RAC operators to minimize duplication and bugs.
• Avoid introducing concurrency: Operators should not perform work concurrently. Callers can manage concurrency by subscribing or delivering events on a specific RACScheduler.

If an operator requires recursion (e.g., a repeat operator), do not use standard recursive function calls, as this can lead to stack overflow and crashes. Instead, use the -scheduleRecursiveBlock: method of RACScheduler. This transforms recursion into iteration, protecting the call stack.

// Correct implementation of repeat using scheduleRecursiveBlock to avoid stack overflow
- (RACSignal *)repeat {
    return [RACSignal createSignal:^(id<RACSubscriber> subscriber) {
        RACCompoundDisposable *compoundDisposable = [RACCompoundDisposable compoundDisposable];

        RACScheduler *scheduler = RACScheduler.currentScheduler ?: [RACScheduler scheduler];
        RACDisposable *disposable = [scheduler scheduleRecursiveBlock:^(void (^reschedule)(void)) {
            RACDisposable *subDisposable = [self subscribeNext:^(id x) {
                [subscriber sendNext:x];
            } error:^(NSError *error) {
                [subscriber sendError:error];
            } completed:^{
                reschedule();
            }];

            [compoundDisposable addDisposable:subDisposable];
        }];

        [compoundDisposable addDisposable:disposable];
        return compoundDisposable;
    }];
}

Stream operators should return a new stream almost immediately. Any heavy lifting or work required by the operator should be part of the evaluation of the new stream, not part of the operator invocation itself.

Incorrect approach: Performing work (like a loop) inside the operator method and returning a constructed result. Correct approach: Using existing operators (like flattenMap:) to return a new stream that performs the work when evaluated.

// WRONG!
- (RACSequence *)map:(id (^)(id))block {
    RACSequence *result = [RACSequence empty];
    for (id obj in self) {
        id mappedObj = block(obj);
        result = [result concat:[RACSequence return:mappedObj]];
    }

    return result;
}

// Right!
- (RACSequence *)map:(id (^)(id))block {
    return [self flattenMap:^(id obj) {
        id mappedObj = block(obj);
        return [RACSequence return:mappedObj];
    }];
}

A RACSequence is a pull-driven stream that behaves similarly to collections. Developers should be aware of three core behaviors:

1. Lazy Evaluation: Sequences are evaluated lazily by default. Work (like mapping or transformations) is only performed when a value is actually requested (e.g., accessing .head). Once a value is evaluated, it is memoized and won't be recalculated.
2. Blocking Evaluation: Evaluating any part of a sequence will block the calling thread until the value is synchronously retrieved. For expensive operations, use [-signalWithScheduler:][RACSequence] to convert it to a signal instead.
3. Single Side Effects: Side effects within a sequence operator occur only once per value—specifically when that value is first evaluated. Subsequent accesses to the same value or derived sequences will not re-trigger the side effect.

NSArray *strings = @[ @"A", @"B", @"C" ];
RACSequence *sequence = [strings.rac_sequence map:^(NSString *str) {
    return [str stringByAppendingString:@"_"];
}];
// No concatenation has happened yet. Accessing sequence.head triggers it.