OLD | NEW |
(Empty) | |
| 1 // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file |
| 2 // for details. All rights reserved. Use of this source code is governed by a |
| 3 // BSD-style license that can be found in the LICENSE file. |
| 4 |
| 5 import 'dart:async'; |
| 6 |
| 7 import 'capture_sink.dart'; |
| 8 import 'capture_transformer.dart'; |
| 9 import 'error.dart'; |
| 10 import 'release_sink.dart'; |
| 11 import 'release_transformer.dart'; |
| 12 import 'value.dart'; |
| 13 import '../stream_sink_transformer.dart'; |
| 14 |
| 15 /// The result of a computation. |
| 16 /// |
| 17 /// Capturing a result (either a returned value or a thrown error) means |
| 18 /// converting it into a [Result] - either a [ValueResult] or an [ErrorResult]. |
| 19 /// |
| 20 /// This value can release itself by writing itself either to a [EventSink] or a |
| 21 /// [Completer], or by becoming a [Future]. |
| 22 /// |
| 23 /// A [Future] represents a potential result, one that might not have been |
| 24 /// computed yet, and a [Result] is always a completed and available result. |
| 25 abstract class Result<T> { |
| 26 /// A stream transformer that captures a stream of events into [Result]s. |
| 27 /// |
| 28 /// The result of the transformation is a stream of [Result] values and no |
| 29 /// error events. This is the transformer used by [captureStream]. |
| 30 static const StreamTransformer<Object, Result<Object>> |
| 31 captureStreamTransformer = const CaptureStreamTransformer<Object>(); |
| 32 |
| 33 /// A stream transformer that releases a stream of result events. |
| 34 /// |
| 35 /// The result of the transformation is a stream of values and error events. |
| 36 /// This is the transformer used by [releaseStream]. |
| 37 static const StreamTransformer<Result<Object>, Object> |
| 38 releaseStreamTransformer = const ReleaseStreamTransformer<Object>(); |
| 39 |
| 40 /// A sink transformer that captures events into [Result]s. |
| 41 /// |
| 42 /// The result of the transformation is a sink that only forwards [Result] |
| 43 /// values and no error events. |
| 44 static const StreamSinkTransformer<Object, Result<Object>> |
| 45 captureSinkTransformer = |
| 46 const StreamSinkTransformer<Object, Result<Object>>.fromStreamTransformer( |
| 47 const CaptureStreamTransformer<Object>()); |
| 48 |
| 49 /// A sink transformer that releases result events. |
| 50 /// |
| 51 /// The result of the transformation is a sink that forwards of values and |
| 52 /// error events. |
| 53 static const StreamSinkTransformer<Result<Object>, Object> |
| 54 releaseSinkTransformer = |
| 55 const StreamSinkTransformer<Result<Object>, Object>.fromStreamTransformer( |
| 56 const ReleaseStreamTransformer<Object>()); |
| 57 |
| 58 /// Creates a `Result` with the result of calling [computation]. |
| 59 /// |
| 60 /// This generates either a [ValueResult] with the value returned by |
| 61 /// calling `computation`, or an [ErrorResult] with an error thrown by |
| 62 /// the call. |
| 63 factory Result(T computation()) { |
| 64 try { |
| 65 return new ValueResult<T>(computation()); |
| 66 } catch (e, s) { |
| 67 return new ErrorResult(e, s); |
| 68 } |
| 69 } |
| 70 |
| 71 /// Creates a `Result` holding a value. |
| 72 /// |
| 73 /// Alias for [ValueResult.ValueResult]. |
| 74 factory Result.value(T value) = ValueResult<T>; |
| 75 |
| 76 /// Creates a `Result` holding an error. |
| 77 /// |
| 78 /// Alias for [ErrorResult.ErrorResult]. |
| 79 factory Result.error(Object error, [StackTrace stackTrace]) => |
| 80 new ErrorResult(error, stackTrace); |
| 81 |
| 82 /// Captures the result of a future into a `Result` future. |
| 83 /// |
| 84 /// The resulting future will never have an error. |
| 85 /// Errors have been converted to an [ErrorResult] value. |
| 86 static Future<Result<T>> capture<T>(Future<T> future) { |
| 87 return future.then((value) => new ValueResult(value), |
| 88 onError: (error, stackTrace) => new ErrorResult(error, stackTrace)); |
| 89 } |
| 90 |
| 91 /// Captures each future in [elements], |
| 92 /// |
| 93 /// Returns a (future of) a list of results for each element in [elements], |
| 94 /// in iteration order. |
| 95 /// Each future in [elements] is [capture]d and each non-future is |
| 96 /// wrapped as a [Result.value]. |
| 97 /// The returned future will never have an error. |
| 98 static Future<List<Result<T>>> captureAll<T>(Iterable<FutureOr<T>> elements) { |
| 99 var results = <Result<T>>[]; |
| 100 int pending = 0; |
| 101 var completer; |
| 102 for (var element in elements) { |
| 103 if (element is Future<T>) { |
| 104 int i = results.length; |
| 105 results.add(null); |
| 106 pending++; |
| 107 Result.capture<T>(element).then((result) { |
| 108 results[i] = result; |
| 109 if (--pending == 0) { |
| 110 completer.complete(results); |
| 111 } |
| 112 }); |
| 113 } else { |
| 114 results.add(new Result<T>.value(element)); |
| 115 } |
| 116 } |
| 117 if (pending == 0) { |
| 118 return new Future<List<Result<T>>>.value(results); |
| 119 } |
| 120 completer = new Completer<List<Result<T>>>(); |
| 121 return completer.future; |
| 122 } |
| 123 |
| 124 /// Releases the result of a captured future. |
| 125 /// |
| 126 /// Converts the [Result] value of the given [future] to a value or error |
| 127 /// completion of the returned future. |
| 128 /// |
| 129 /// If [future] completes with an error, the returned future completes with |
| 130 /// the same error. |
| 131 static Future<T> release<T>(Future<Result<T>> future) => |
| 132 future.then<T>((result) => result.asFuture); |
| 133 |
| 134 /// Captures the results of a stream into a stream of [Result] values. |
| 135 /// |
| 136 /// The returned stream will not have any error events. |
| 137 /// Errors from the source stream have been converted to [ErrorResult]s. |
| 138 static Stream<Result<T>> captureStream<T>(Stream<T> source) => |
| 139 source.transform(new CaptureStreamTransformer<T>()); |
| 140 |
| 141 /// Releases a stream of [result] values into a stream of the results. |
| 142 /// |
| 143 /// `Result` values of the source stream become value or error events in |
| 144 /// the returned stream as appropriate. |
| 145 /// Errors from the source stream become errors in the returned stream. |
| 146 static Stream<T> releaseStream<T>(Stream<Result<T>> source) => |
| 147 source.transform(new ReleaseStreamTransformer<T>()); |
| 148 |
| 149 /// Releases results added to the returned sink as data and errors on [sink]. |
| 150 /// |
| 151 /// A [Result] added to the returned sink is added as a data or error event |
| 152 /// on [sink]. Errors added to the returned sink are forwarded directly to |
| 153 /// [sink] and so is the [EventSink.close] calls. |
| 154 static EventSink<Result<T>> releaseSink<T>(EventSink<T> sink) => |
| 155 new ReleaseSink<T>(sink); |
| 156 |
| 157 /// Captures the events of the returned sink into results on [sink]. |
| 158 /// |
| 159 /// Data and error events added to the returned sink are captured into |
| 160 /// [Result] values and added as data events on the provided [sink]. |
| 161 /// No error events are ever added to [sink]. |
| 162 /// |
| 163 /// When the returned sink is closed, so is [sink]. |
| 164 static EventSink<T> captureSink<T>(EventSink<Result<T>> sink) => |
| 165 new CaptureSink<T>(sink); |
| 166 |
| 167 /// Converts a result of a result to a single result. |
| 168 /// |
| 169 /// If the result is an error, or it is a `Result` value |
| 170 /// which is then an error, then a result with that error is returned. |
| 171 /// Otherwise both levels of results are value results, and a single |
| 172 /// result with the value is returned. |
| 173 static Result<T> flatten<T>(Result<Result<T>> result) { |
| 174 if (result.isValue) return result.asValue.value; |
| 175 return result.asError; |
| 176 } |
| 177 |
| 178 /// Converts a sequence of results to a result of a list. |
| 179 /// |
| 180 /// Returns either a list of values if [results] doesn't contain any errors, |
| 181 /// or the first error result in [results]. |
| 182 static Result<List<T>> flattenAll<T>(Iterable<Result<T>> results) { |
| 183 var values = <T>[]; |
| 184 for (var result in results) { |
| 185 if (result.isValue) { |
| 186 values.add(result.asValue.value); |
| 187 } else { |
| 188 return result.asError; |
| 189 } |
| 190 } |
| 191 return new Result<List<T>>.value(values); |
| 192 } |
| 193 |
| 194 /// Whether this result is a value result. |
| 195 /// |
| 196 /// Always the opposite of [isError]. |
| 197 bool get isValue; |
| 198 |
| 199 /// Whether this result is an error result. |
| 200 /// |
| 201 /// Always the opposite of [isValue]. |
| 202 bool get isError; |
| 203 |
| 204 /// If this is a value result, returns itself. |
| 205 /// |
| 206 /// Otherwise returns `null`. |
| 207 ValueResult<T> get asValue; |
| 208 |
| 209 /// If this is an error result, returns itself. |
| 210 /// |
| 211 /// Otherwise returns `null`. |
| 212 ErrorResult get asError; |
| 213 |
| 214 /// Completes a completer with this result. |
| 215 void complete(Completer<T> completer); |
| 216 |
| 217 /// Adds this result to an [EventSink]. |
| 218 /// |
| 219 /// Calls the sink's `add` or `addError` method as appropriate. |
| 220 void addTo(EventSink<T> sink); |
| 221 |
| 222 /// A future that has been completed with this result as a value or an error. |
| 223 Future<T> get asFuture; |
| 224 } |
OLD | NEW |