Line data Source code
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 'result/capture_transformer.dart';
8 : import 'result/error.dart';
9 : import 'result/release_transformer.dart';
10 : import 'result/value.dart';
11 : import 'stream_sink_transformer.dart';
12 :
13 : /// The result of a computation.
14 : ///
15 : /// Capturing a result (either a returned value or a thrown error) means
16 : /// converting it into a [Result] - either a [ValueResult] or an [ErrorResult].
17 : ///
18 : /// This value can release itself by writing itself either to a [EventSink] or a
19 : /// [Completer], or by becoming a [Future].
20 : abstract class Result<T> {
21 : /// A stream transformer that captures a stream of events into [Result]s.
22 : ///
23 : /// The result of the transformation is a stream of [Result] values and no
24 : /// error events. This is the transformer used by [captureStream].
25 : static const StreamTransformer<Object, Result> captureStreamTransformer =
26 : const CaptureStreamTransformer();
27 :
28 : /// A stream transformer that releases a stream of result events.
29 : ///
30 : /// The result of the transformation is a stream of values and error events.
31 : /// This is the transformer used by [releaseStream].
32 : static const StreamTransformer<Object, Result> releaseStreamTransformer =
33 : const ReleaseStreamTransformer();
34 :
35 : /// A sink transformer that captures events into [Result]s.
36 : ///
37 : /// The result of the transformation is a sink that only forwards [Result]
38 : /// values and no error events.
39 : static const StreamSinkTransformer<Object, Result> captureSinkTransformer =
40 : const StreamSinkTransformer.fromStreamTransformer(
41 : const CaptureStreamTransformer());
42 :
43 : /// A sink transformer that releases result events.
44 : ///
45 : /// The result of the transformation is a sink that forwards of values and
46 : /// error events.
47 : static const StreamSinkTransformer<Object, Result> releaseSinkTransformer =
48 : const StreamSinkTransformer.fromStreamTransformer(
49 : const ReleaseStreamTransformer());
50 :
51 : /// Create a `Result` with the result of calling [computation].
52 : ///
53 : /// This generates either a [ValueResult] with the value returned by
54 : /// calling `computation`, or an [ErrorResult] with an error thrown by
55 : /// the call.
56 : factory Result(T computation()) {
57 : try {
58 0 : return new ValueResult(computation());
59 : } catch (e, s) {
60 0 : return new ErrorResult(e, s);
61 : }
62 : }
63 :
64 : /// Create a `Result` holding a value.
65 : ///
66 : /// Alias for [ValueResult.ValueResult].
67 : factory Result.value(T value) = ValueResult<T>;
68 :
69 : /// Create a `Result` holding an error.
70 : ///
71 : /// Alias for [ErrorResult.ErrorResult].
72 : factory Result.error(Object error, [StackTrace stackTrace]) =>
73 0 : new ErrorResult(error, stackTrace);
74 :
75 : /// Capture the result of a future into a `Result` future.
76 : ///
77 : /// The resulting future will never have an error.
78 : /// Errors have been converted to an [ErrorResult] value.
79 : static Future<Result<T>> capture<T>(Future<T> future) {
80 0 : return future.then((value) => new ValueResult(value),
81 0 : onError: (error, stackTrace) => new ErrorResult<T>(error, stackTrace));
82 : }
83 :
84 : /// Release the result of a captured future.
85 : ///
86 : /// Converts the [Result] value of the given [future] to a value or error
87 : /// completion of the returned future.
88 : ///
89 : /// If [future] completes with an error, the returned future completes with
90 : /// the same error.
91 : static Future<T> release<T>(Future<Result<T>> future) =>
92 0 : future.then<T>((result) => result.asFuture);
93 :
94 : /// Capture the results of a stream into a stream of [Result] values.
95 : ///
96 : /// The returned stream will not have any error events.
97 : /// Errors from the source stream have been converted to [ErrorResult]s.
98 : static Stream<Result<T>> captureStream<T>(Stream<T> source) =>
99 0 : source.transform(new CaptureStreamTransformer<T>());
100 :
101 : /// Release a stream of [result] values into a stream of the results.
102 : ///
103 : /// `Result` values of the source stream become value or error events in
104 : /// the returned stream as appropriate.
105 : /// Errors from the source stream become errors in the returned stream.
106 : static Stream<T> releaseStream<T>(Stream<Result<T>> source) =>
107 0 : source.transform(new ReleaseStreamTransformer<T>());
108 :
109 : /// Converts a result of a result to a single result.
110 : ///
111 : /// If the result is an error, or it is a `Result` value
112 : /// which is then an error, then a result with that error is returned.
113 : /// Otherwise both levels of results are value results, and a single
114 : /// result with the value is returned.
115 : static Result<T> flatten<T>(Result<Result<T>> result) {
116 0 : if (result.isValue) return result.asValue.value;
117 0 : return new ErrorResult<T>(result.asError.error, result.asError.stackTrace);
118 : }
119 :
120 : /// Whether this result is a value result.
121 : ///
122 : /// Always the opposite of [isError].
123 : bool get isValue;
124 :
125 : /// Whether this result is an error result.
126 : ///
127 : /// Always the opposite of [isValue].
128 : bool get isError;
129 :
130 : /// If this is a value result, return itself.
131 : ///
132 : /// Otherwise return `null`.
133 : ValueResult<T> get asValue;
134 :
135 : /// If this is an error result, return itself.
136 : ///
137 : /// Otherwise return `null`.
138 : ErrorResult<T> get asError;
139 :
140 : /// Complete a completer with this result.
141 : void complete(Completer<T> completer);
142 :
143 : /// Add this result to an [EventSink].
144 : ///
145 : /// Calls the sink's `add` or `addError` method as appropriate.
146 : void addTo(EventSink<T> sink);
147 :
148 : /// Creates a future completed with this result as a value or an error.
149 : Future<T> get asFuture;
150 : }
|