lib/result.dart

// Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

/**
 * Capture asynchronous results into synchronous values, and release them again.
 *
 * Capturing a result (either a returned value or a thrown error)
 * means converting it into a [Result] -
 * either a [ValueResult] or an [ErrorResult].
 *
 * This value can release itself by writing itself either to a
 * [EventSink] or a [Completer], or by becoming a [Future].
 */
library dart.pkg.async.results;

import "dart:async";

/**
 * The result of a computation.
 */
abstract class Result<T> {
  /**
   * Create a `Result` with the result of calling [computation].
   *
   * This generates either a [ValueResult] with the value returned by
   * calling `computation`, or an [ErrorResult] with an error thrown by
   * the call.
   */
  factory Result(T computation()) {
    try {
      return new ValueResult(computation());
    } catch (e, s) {
      return new ErrorResult(e, s);
    }
  }

  /**
   * Create a `Result` holding a value.
   *
   * Alias for [ValueResult.ValueResult].
   */
  factory Result.value(T value) = ValueResult<T>;

  /**
   * Create a `Result` holding an error.
   *
   * Alias for [ErrorResult.ErrorResult].
   */
  factory Result.error(Object error, [StackTrace stackTrace]) =>
      new ErrorResult(error, stackTrace);

  // Helper functions.
  static _captureValue(value) => new ValueResult(value);
  static _captureError(error, stack) => new ErrorResult(error, stack);
  static _release(Result v) {
    if (v.isValue) return v.asValue.value;  // Avoid wrapping in future.
    return v.asFuture;
  }

  /**
   * Capture the result of a future into a `Result` future.
   *
   * The resulting future will never have an error.
   * Errors have been converted to an [ErrorResult] value.
   */
  static Future<Result> capture(Future future) {
    return future.then(_captureValue, onError: _captureError);
  }

  /**
   * Release the result of a captured future.
   *
   * Converts the [Result] value of the given [future] to a value or error
   * completion of the returned future.
   *
   * If [future] completes with an error, the returned future completes with
   * the same error.
   */
  static Future release(Future<Result> future) {
    return future.then(_release);
  }

  /**
   * Capture the results of a stream into a stream of [Result] values.
   *
   * The returned stream will not have any error events.
   * Errors from the source stream have been converted to [ErrorResult]s.
   *
   * Shorthand for transforming the stream using [CaptureStreamTransformer].
   */
  static Stream<Result> captureStream(Stream source) {
    return source.transform(const CaptureStreamTransformer());
  }

  /**
   * Release a stream of [result] values into a stream of the results.
   *
   * `Result` values of the source stream become value or error events in
   * the retuned stream as appropriate.
   * Errors from the source stream become errors in the returned stream.
   *
   * Shorthand for transforming the stream using [ReleaseStreamTransformer].
   */
  static Stream releaseStream(Stream<Result> source) {
    return source.transform(const ReleaseStreamTransformer());
  }

  /**
   * Converts a result of a result to a single result.
   *
   * If the result is an error, or it is a `Result` value
   * which is then an error, then a result with that error is returned.
   * Otherwise both levels of results are value results, and a single
   * result with the value is returned.
   */
  static Result flatten(Result<Result> result) {
    if (result.isError) return result;
    return result.asValue.value;
  }

  /**
   * Whether this result is a value result.
   *
   * Always the opposite of [isError].
   */
  bool get isValue;

  /**
   * Whether this result is an error result.
   *
   * Always the opposite of [isValue].
   */
  bool get isError;

  /**
   * If this is a value result, return itself.
   *
   * Otherwise return `null`.
   */
  ValueResult<T> get asValue;

  /**
   * If this is an error result, return itself.
   *
   * Otherwise return `null`.
   */
  ErrorResult get asError;

  /**
   * Complete a completer with this result.
   */
  void complete(Completer<T> completer);

  /**
   * Add this result to a [StreamSink].
   */
  void addTo(EventSink<T> sink);

  /**
   * Creates a future completed with this result as a value or an error.
   */
  Future<T> get asFuture;
}

/**
 * A result representing a returned value.
 */
class ValueResult<T> implements Result<T> {
  /** The returned value that this result represents. */
  final T value;
  /** Create a value result with the given [value]. */
  ValueResult(this.value);
  bool get isValue => true;
  bool get isError => false;
  ValueResult<T> get asValue => this;
  ErrorResult get asError => null;
  void complete(Completer<T> completer) {
    completer.complete(value);
  }
  void addTo(EventSink<T> sink) {
    sink.add(value);
  }
  Future<T> get asFuture => new Future.value(value);
}

/**
 * A result representing a thrown error.
 */
class ErrorResult implements Result {
  /** The thrown object that this result represents. */
  final error;
  /** The stack trace, if any, associated with the throw. */
  final StackTrace stackTrace;
  /** Create an error result with the given [error] and [stackTrace]. */
  ErrorResult(this.error, this.stackTrace);
  bool get isValue => false;
  bool get isError => true;
  ValueResult get asValue => null;
  ErrorResult get asError => this;
  void complete(Completer completer) {
    completer.completeError(error, stackTrace);
  }
  void addTo(EventSink sink) {
    sink.addError(error, stackTrace);
  }
  Future get asFuture => new Future.error(error, stackTrace);
}

/**
 * A stream transformer that captures a stream of events into [Result]s.
 *
 * The result of the transformation is a stream of [Result] values and
 * no error events.
 */
class CaptureStreamTransformer<T> implements StreamTransformer<T, Result<T>> {
  const CaptureStreamTransformer();

  Stream<Result<T>> bind(Stream<T> source) {
    return new Stream<Result<T>>.eventTransformed(source, _createSink);
  }

  static EventSink _createSink(EventSink<Result> sink) {
    return new CaptureSink(sink);
  }
}

/**
 * A stream transformer that releases a stream of result events.
 *
 * The result of the transformation is a stream of values and
 * error events.
 */
class ReleaseStreamTransformer<T> implements StreamTransformer<Result<T>, T> {
  const ReleaseStreamTransformer();

  Stream<T> bind(Stream<Result<T>> source) {
    return new Stream<T>.eventTransformed(source, _createSink);
  }

  static EventSink<Result> _createSink(EventSink sink) {
    return new ReleaseSink(sink);
  }
}

/**
 * An event sink wrapper that captures the incoming events.
 *
 * Wraps an [EventSink] that expects [Result] values.
 * Accepts any value and error result,
 * and passes them to the wrapped sink as [Result] values.
 *
 * The wrapped sink will never receive an error event.
 */
class CaptureSink<T> implements EventSink<T> {
  final EventSink _sink;

  CaptureSink(EventSink<Result<T>> sink) : _sink = sink;
  void add(T value) { _sink.add(new ValueResult(value)); }
  void addError(Object error, [StackTrace stackTrace]) {
    _sink.add(new ErrorResult(error, stackTrace));
  }
  void close() { _sink.close(); }
}

/**
 * An event sink wrapper that releases the incoming result events.
 *
 * Wraps an output [EventSink] that expects any result.
 * Accepts [Result] values, and puts the result value or error into the
 * corresponding output sink add method.
 */
class ReleaseSink<T> implements EventSink<Result<T>> {
  final EventSink _sink;
  ReleaseSink(EventSink<T> sink) : _sink = sink;
  void add(Result<T> result) {
    if (result.isValue) {
      _sink.add(result.asValue.value);
    } else {
      ErrorResult error = result.asError;
      _sink.addError(error.error, error.stackTrace);
    }
  }
  void addError(Object error, [StackTrace stackTrace]) {
    // Errors may be added by intermediate processing, even if it is never
    // added by CaptureSink.
    _sink.addError(error, stackTrace);
  }

  void close() { _sink.close(); }
}