- (void)logInWithUsername:(NSString *)username
                 password:(NSString *)password
                  success:( void (^)(User *user) )successBlock
                  failure:( void (^)(NSError *error) )failureBlock;

- (PINFuture<User *> *)logInWithUsername:(NSString *)username 
                                password:(NSString *)password;

[self showSpinner];
[User logInWithUsername:username password:password success:^(User *user) {
    [Posts fetchPostsForUser:user success:^(Posts *posts) {
        dispatch_async(dispatch_get_main_queue(), ^{
           [self hideSpinner];
            // update the UI to show posts
        });
    } failure:^(NSError *error) {
        dispatch_async(dispatch_get_main_queue(), ^{
            [self hideSpinner];
            // update the UI to show the error
        });
    }];
} failure:^(NSError *error) {
    dispatch_async(dispatch_get_main_queue(), ^{
        [self hideSpinner];
        // update the UI to show the error
    });
}];

[self showSpinner];
PINFuture<User *> *userFuture = [User logInWithUsername:username password:password];
PINFuture<Posts *> *postsFuture = [PINFutureMap<User *, Posts *> flatMap:userFuture executor:[PINExecutor main] transform:^PINFuture<Posts *> *(User *user) {
    return [Posts fetchPostsForUser:user];
}];
[postsFuture executor:[PINExecutor main] completion:^{
    [self hideSpinner];
}];
[postsFuture executor:[PINExecutor main] success:^(Posts *posts) {
    // update the UI to show posts
} failure:^(NSError *error) {
    // update the UI to show the error
}];

OCMStub([fileMock readContentsPath:@"foo.txt" 
                           success:OCMOCK_ANY
                           failure:OCMOCK_ANY]).andDo(^(NSInvocation *invocation) {
    (void)(^successBlock)(NSString *) = nil;
    [invocation getArgument:&successBlock atIndex:3];
    if (successBlock) {
        successBlock(@"fake contents");
    }
});

OCMStub([fileMock readContentsPath:@"foo.txt"]).andReturn([PINFuture<NSString *> withValue:@"fake contents"]);

[PINFuture<NSNumber *> withValue:@"foo"]; // Compile error.  Good!

[PINFuture withValue:@"foo"]; // This compiles but will likely blow up with "unrecognized selector" when the value is used.

PINFuture<NSString *> stringFuture = [PINFuture<NSString *> withValue:@"foo"];

PINFuture<NSString *> stringFuture = [PINFuture<NSString *> withError:[NSError errorWithDescription:...]];

PINFuture<NSString *> stringFuture = [PINFuture<NSString *> withBlock:^(void (^ fulfill)(NSString *), void (^ reject)(NSError *)) {
    [foo somethingAsyncWithSuccess:resolve failure:reject];
}];

PINFuture<NSNumber *> fibonacciResultFuture = [PINFuture<NSNumber *> executor:[PINExecutor background] block:^PINFuture *() {
    NSInteger *fibonacciResult = [self computeFibonacci:1000000];
    return [PINFuture<NSNumber *> withValue:fibonacciResult];
}];

PINFuture<NSString *> stringFuture = [PINFutureMap<NSNumber *, NSString *> map:numberFuture executor:[PINExecutor background] transform:^NSString *(NSNumber * number) {
    return [number stringValue];
}];

PINFuture<UIImage *> imageFuture = [PINFutureMap<User *, UIImage *> flatMap:userFuture executor:[PINExecutor background] transform:^PINFuture<NSString *> *(User *user) {
    return [NetworkImageManager fetchImageWithURL:user.profileURL];
}];

PINFuture<NSString *> *stringFuture = [File readUTF8ContentsPath:@"foo.txt" encoding:EncodingUTF8];
stringFuture = [fileAFuture executor:[PINExecutor immediate] mapError:^NSString * (NSError *errror) {
    return "";  // If there's any problem reading the file, continue processing as if the file was empty.
}];

PINFuture<NSString *> *stringFuture = [File readUTF8ContentsPath:@"tryFirst.txt"];
stringFuture = [fileAFuture executor:[PINExecutor background] flatMapError:^PINFuture<NSString *> * (NSError *errror) {
    if ([error isKindOf:[NSURLErrorFileDoesNotExist class]) {
        return [File readUTF8ContentsPath:@"trySecond.txt"];
    } else {
        return [PINFuture withError:error];  // Pass through any other type of error
    }
}];

NSArray<NSString *> fileNames = @[@"a.txt", @"b.txt", @"c.txt"];
NSArray<PINFuture<NSString *> *> *fileContentFutures = [fileNames map:^ PINFuture<NSString *> *(NSString *fileName) {
    return [File readUTF8ContentsPath:fileName];
}];
PINFuture<NSArray<NSString *> *> *fileContentsFuture = [PINFuture<NSString *> gatherAll:fileContentFutures];
[fileContentsFuture executor:[PINExecutor main] success:^(NSArray<NSString *> *fileContents) {
    // All succceeded.
} failure:^(NSError *error) {
    // One or more failed.  `error` is the first one to fail.
}];

NSArray<NSString *> fileNames = @[@"a.txt", @"b.txt", @"c.txt"];
NSArray<PINFuture<NSString *> *> *fileContentFutures = [fileNames map:^ PINFuture<NSString *> *(NSString *fileName) {
    return [File readUTF8ContentsPath:fileName];
}];
PINFuture<NSArray *> *fileContentsOrNullFuture = [PINFuture<NSString *> gatherSome:fileContentFutures];
[fileContentsFuture executor:[PINExecutor main] success:^(NSArray *fileContents) {
    // fileContents is an array of either `NSString *` or `[NSNull null]` depending on whether the source future resolved or rejected.
} failure:^(NSError *error) {
    // This can't be reached.  If any of the source futures fails, there will be a `[NSNull null]` entry in the array.
}];

// Fetch a user, and return a Future that resolves only after all NotificationCenter observers have been notified.
PINFuture<User *> *userFuture = [self userForUsername:username];
userFuture = [userFuture executor:[PINExecutor main] chainSuccess:^(User *user) {
    [[NSNotifcationCenter sharedCenter] postNotification:kUserUpdated object:user];
} failure:nil;
return userFuture;