let fut = Future<Int>.async {
  NSThread.sleepForTimeInterval(0.2)
  return .Success(1)
}

assert(succeeded.get() == .Success(1))

flatMap<U>(f: T throws -> Future<U>) -> Future<U>

enum Error: ErrorType {
  case Deliberate(String)
}

let fut: Future<[Int]> = Future.async { .Success(0) }
  .flatMap { Future.succeeded([$0, 1]) }
  .flatMap { throw Error.Deliberate(String($0)) }
  .flatMap { Future.succeeded($0 + [2]) }

assert(String(fut.get()) == "Failure(Deliberate(\"[0, 1]\"))")

extension String {
  var trimmed: String {
    return stringByTrimmingCharactersInSet(NSCharacterSet.whitespaceAndNewlineCharacterSet())
  }

  func excerpt(maxLength: Int) -> String {
    precondition(maxLength >= 0, "maxLength must be positive")

    if maxLength == 0 {
      return ""
    }

    let length = characters.count

    if length <= maxLength {
      return self
    }

    return self[startIndex..<startIndex.advancedBy(maxLength-1)].trimmed + "…"
  }
}

/**
 * Request a web resource asynchronously, immediately returning a handle to
 * the job as a promise kind of Future. When NSURLSession calls the completion
 * handler, we fullfill the promise. If the completion handler gets called
 * with the contents of the web resource, we resolve the promise with the
 * contents (the success case). Otherwise, we reject the promise with failure.
 */
func loadURL(url: NSURL) -> Future<NSData> {
  let promise = Future<NSData>.promise()
  let task = NSURLSession.sharedSession().dataTaskWithURL(url, completionHandler: { data, response, error in
    if let err: NSError = error {
      promise.reject(err)
    } else if let d = data {
      promise.resolve(d)
    } else {
      promise.reject(Error.FailedLoadingURL(url))
    }
  })
  task.resume()
  return promise
}

/**
 * Parse data as HTML document, finding specific contents from it with an
 * XPath query. We return a completed Future as the handle to the result. If
 * we can parse the data as an HTML document and the query succeeds, we return
 * a successful Future with the query result. Otherwise, we return failed
 * Future describing the error.
 *
 * Because this function gets called inside `Future#flatMap`, it's run in
 * background in a queue worker thread.
 */
func readXPathFromHTML(xpath: String, data: NSData) throws -> Future<HTMLNode> {
  let doc = try HTMLDocument.readDataAsUTF8(data)
  let node = try doc.rootHTMLNode()
  let found = try node.nodeForXPath(xpath)
  return Future.succeeded(found)
}

let wikipediaURL = NSURL(string: "https://en.wikipedia.org/wiki/Main_Page")!
let featuredArticleXPath = "//*[@id='mp-tfa']"

let result = loadURL(wikipediaURL)
  /* Future composition (chaining): when this Future completes successfully,
   * pass its result to a function that does more work, returning another
   * Future. If this Future completes with failure, the chain short-circuits
   * and further flatMap methods are not called. Calls to flatMap are always
   * executed in a queue worker thread.
   */
  .flatMap { try readXPathFromHTML(featuredArticleXPath, data: $0) }
  /* Wait for Future chain to complete. This acts as a synchronization point.
   */
  .get()

switch result {
case .Success(let value):
  let excerpt = value.textContents!.excerpt(78)
  print("Excerpt from today's featured article at Wikipedia: \(excerpt)")
case .Failure(let error):
  print("Error getting today's featured article from Wikipedia: \(error)")
}