Index: lib/src/result/result.dart |
diff --git a/lib/src/result/result.dart b/lib/src/result/result.dart |
new file mode 100644 |
index 0000000000000000000000000000000000000000..98b5aa434a7bb82782513c9ad4ae10b1f9cd2715 |
--- /dev/null |
+++ b/lib/src/result/result.dart |
@@ -0,0 +1,224 @@ |
+// Copyright (c) 2016, 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. |
+ |
+import 'dart:async'; |
+ |
+import 'capture_sink.dart'; |
+import 'capture_transformer.dart'; |
+import 'error.dart'; |
+import 'release_sink.dart'; |
+import 'release_transformer.dart'; |
+import 'value.dart'; |
+import '../stream_sink_transformer.dart'; |
+ |
+/// The result of a computation. |
+/// |
+/// 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]. |
+/// |
+/// A [Future] represents a potential result, one that might not have been |
+/// computed yet, and a [Result] is always a completed and available result. |
+abstract class Result<T> { |
+ /// 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. This is the transformer used by [captureStream]. |
+ static const StreamTransformer<Object, Result<Object>> |
+ captureStreamTransformer = const CaptureStreamTransformer<Object>(); |
+ |
+ /// A stream transformer that releases a stream of result events. |
+ /// |
+ /// The result of the transformation is a stream of values and error events. |
+ /// This is the transformer used by [releaseStream]. |
+ static const StreamTransformer<Result<Object>, Object> |
+ releaseStreamTransformer = const ReleaseStreamTransformer<Object>(); |
+ |
+ /// A sink transformer that captures events into [Result]s. |
+ /// |
+ /// The result of the transformation is a sink that only forwards [Result] |
+ /// values and no error events. |
+ static const StreamSinkTransformer<Object, Result<Object>> |
+ captureSinkTransformer = |
+ const StreamSinkTransformer<Object, Result<Object>>.fromStreamTransformer( |
+ const CaptureStreamTransformer<Object>()); |
+ |
+ /// A sink transformer that releases result events. |
+ /// |
+ /// The result of the transformation is a sink that forwards of values and |
+ /// error events. |
+ static const StreamSinkTransformer<Result<Object>, Object> |
+ releaseSinkTransformer = |
+ const StreamSinkTransformer<Result<Object>, Object>.fromStreamTransformer( |
+ const ReleaseStreamTransformer<Object>()); |
+ |
+ /// Creates 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<T>(computation()); |
+ } catch (e, s) { |
+ return new ErrorResult(e, s); |
+ } |
+ } |
+ |
+ /// Creates a `Result` holding a value. |
+ /// |
+ /// Alias for [ValueResult.ValueResult]. |
+ factory Result.value(T value) = ValueResult<T>; |
+ |
+ /// Creates a `Result` holding an error. |
+ /// |
+ /// Alias for [ErrorResult.ErrorResult]. |
+ factory Result.error(Object error, [StackTrace stackTrace]) => |
+ new ErrorResult(error, stackTrace); |
+ |
+ /// Captures 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<T>> capture<T>(Future<T> future) { |
+ return future.then((value) => new ValueResult(value), |
+ onError: (error, stackTrace) => new ErrorResult(error, stackTrace)); |
+ } |
+ |
+ /// Captures each future in [elements], |
+ /// |
+ /// Returns a (future of) a list of results for each element in [elements], |
+ /// in iteration order. |
+ /// Each future in [elements] is [capture]d and each non-future is |
+ /// wrapped as a [Result.value]. |
+ /// The returned future will never have an error. |
+ static Future<List<Result<T>>> captureAll<T>(Iterable<FutureOr<T>> elements) { |
+ var results = <Result<T>>[]; |
+ int pending = 0; |
+ var completer; |
+ for (var element in elements) { |
+ if (element is Future<T>) { |
+ int i = results.length; |
+ results.add(null); |
+ pending++; |
+ Result.capture<T>(element).then((result) { |
+ results[i] = result; |
+ if (--pending == 0) { |
+ completer.complete(results); |
+ } |
+ }); |
+ } else { |
+ results.add(new Result<T>.value(element)); |
+ } |
+ } |
+ if (pending == 0) { |
+ return new Future<List<Result<T>>>.value(results); |
+ } |
+ completer = new Completer<List<Result<T>>>(); |
+ return completer.future; |
+ } |
+ |
+ /// Releases 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<T> release<T>(Future<Result<T>> future) => |
+ future.then<T>((result) => result.asFuture); |
+ |
+ /// Captures 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. |
+ static Stream<Result<T>> captureStream<T>(Stream<T> source) => |
+ source.transform(new CaptureStreamTransformer<T>()); |
+ |
+ /// Releases a stream of [result] values into a stream of the results. |
+ /// |
+ /// `Result` values of the source stream become value or error events in |
+ /// the returned stream as appropriate. |
+ /// Errors from the source stream become errors in the returned stream. |
+ static Stream<T> releaseStream<T>(Stream<Result<T>> source) => |
+ source.transform(new ReleaseStreamTransformer<T>()); |
+ |
+ /// Releases results added to the returned sink as data and errors on [sink]. |
+ /// |
+ /// A [Result] added to the returned sink is added as a data or error event |
+ /// on [sink]. Errors added to the returned sink are forwarded directly to |
+ /// [sink] and so is the [EventSink.close] calls. |
+ static EventSink<Result<T>> releaseSink<T>(EventSink<T> sink) => |
+ new ReleaseSink<T>(sink); |
+ |
+ /// Captures the events of the returned sink into results on [sink]. |
+ /// |
+ /// Data and error events added to the returned sink are captured into |
+ /// [Result] values and added as data events on the provided [sink]. |
+ /// No error events are ever added to [sink]. |
+ /// |
+ /// When the returned sink is closed, so is [sink]. |
+ static EventSink<T> captureSink<T>(EventSink<Result<T>> sink) => |
+ new CaptureSink<T>(sink); |
+ |
+ /// 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<T> flatten<T>(Result<Result<T>> result) { |
+ if (result.isValue) return result.asValue.value; |
+ return result.asError; |
+ } |
+ |
+ /// Converts a sequence of results to a result of a list. |
+ /// |
+ /// Returns either a list of values if [results] doesn't contain any errors, |
+ /// or the first error result in [results]. |
+ static Result<List<T>> flattenAll<T>(Iterable<Result<T>> results) { |
+ var values = <T>[]; |
+ for (var result in results) { |
+ if (result.isValue) { |
+ values.add(result.asValue.value); |
+ } else { |
+ return result.asError; |
+ } |
+ } |
+ return new Result<List<T>>.value(values); |
+ } |
+ |
+ /// 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, returns itself. |
+ /// |
+ /// Otherwise returns `null`. |
+ ValueResult<T> get asValue; |
+ |
+ /// If this is an error result, returns itself. |
+ /// |
+ /// Otherwise returns `null`. |
+ ErrorResult get asError; |
+ |
+ /// Completes a completer with this result. |
+ void complete(Completer<T> completer); |
+ |
+ /// Adds this result to an [EventSink]. |
+ /// |
+ /// Calls the sink's `add` or `addError` method as appropriate. |
+ void addTo(EventSink<T> sink); |
+ |
+ /// A future that has been completed with this result as a value or an error. |
+ Future<T> get asFuture; |
+} |