Skip to content

Commit

Permalink
Modernize the package's style.
Browse files Browse the repository at this point in the history 
This moves the package to new-style doc comments, deprecates separate
top-level libraries, and removes library tags. It also deprecates some
top-level classes in favor of static const fields.

There's more that could be done, but this fixes most of the low-hanging
fruit.

R=lrn@google.com

Review URL: https://codereview.chromium.org//1777453002 .
  • Loading branch information
@nex3
nex3 committed Mar 8, 2016
1 parent 43463f7 commit 66843f1
Show file tree
Hide file tree
Showing 41 changed files with 513 additions and 449 deletions.
13 changes: 13 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,16 @@
## 1.9.0

* Deprecate top-level libraries other than `package:async/async.dart`, which
exports these libraries' interfaces.

* Add `Result.captureStreamTransformer`, `Result.releaseStreamTransformer`,
`Result.captureSinkTransformer`, and `Result.releaseSinkTransformer`.

* Deprecate `CaptureStreamTransformer`, `ReleaseStreamTransformer`,
`CaptureSink`, and `ReleaseSink`. `Result.captureStreamTransformer`,
`Result.releaseStreamTransformer`, `Result.captureSinkTransformer`, and
`Result.releaseSinkTransformer` should be used instead.

## 1.8.0

- Added `StreamSinkCompleter`, for creating a `StreamSink` now and providing its
Expand Down
31 changes: 9 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,15 @@
# Async utilities package

Contains tools to work with asynchronous computations.

The package contains `Stream` and `Future` related functionality,
as well as sub-libraries with different utilities.
Contains utility classes in the style of `dart:async` to work with asynchronous
computations.

### Zipping streams

The "stream_zip.dart" sub-library contains functionality
to combine several streams of events into a single stream of tuples of events.
The `StreamZip` class can combine several streams of events into a single stream
of tuples of events.

### Results
The "result.dart" sub-library introduces a `Result` class that can hold either
a value or an error.
It allows capturing an asynchronous computation which can give either a value
or an error, into an asynchronous computation that always gives a `Result`
value, where errors can be treated as data.
It also allows releasing the `Result` back into an asynchronous computation.

### History.
This package is unrelated to the discontinued `async` package with version 0.1.7.

## Features and bugs

Please file feature requests and bugs at the [issue tracker][tracker].

[tracker]: https://github.com/dart-lang/async/issues
The package introduces a `Result` class that can hold either a value or an
error. It allows capturing an asynchronous computation which can give either a
value or an error, into an asynchronous computation that always gives a `Result`
value, where errors can be treated as data. It also allows releasing the
`Result` back into an asynchronous computation.
12 changes: 7 additions & 5 deletions lib/async.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,6 @@
// 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.

library dart.pkg.async;

export "result.dart";
export "src/async_memoizer.dart";
export "src/cancelable_operation.dart";
export "src/delegate/event_sink.dart";
Expand All @@ -17,13 +14,18 @@ export "src/future_group.dart";
export "src/lazy_stream.dart";
export "src/null_stream_sink.dart";
export "src/restartable_timer.dart";
export "src/result_future.dart";
export "src/result.dart";
export "src/result/capture_transformer.dart";
export "src/result/error.dart";
export "src/result/future.dart";
export "src/result/release_transformer.dart";
export "src/result/value.dart";
export "src/single_subscription_transformer.dart";
export "src/stream_completer.dart";
export "src/stream_group.dart";
export "src/stream_queue.dart";
export "src/stream_sink_completer.dart";
export "src/stream_sink_transformer.dart";
export "src/stream_splitter.dart";
export "src/stream_zip.dart";
export "src/subscription_stream.dart";
export "stream_zip.dart";
257 changes: 7 additions & 250 deletions lib/result.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,255 +2,12 @@
// 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.
///
/// 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].
/// Import `async.dart` instead.
@Deprecated("Will be removed in async 2.0.0.")
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 returned 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 an [EventSink].
///
/// Calls the sink's `add` or `addError` method as appropriate.
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> {
final T 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 {
final error;
final StackTrace 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);

/// Calls an error handler with the error and stacktrace.
///
/// An async error handler function is either a function expecting two
/// arguments, which will be called with the error and the stack trace,
/// or it has to be a function expecting only one argument,
/// which will be called with only the error.
void handle(Function errorHandler) {
if (errorHandler is ZoneBinaryCallback) {
errorHandler(error, stackTrace);
} else {
errorHandler(error);
}
}
}

/// 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(); }
}
export "src/result.dart";
export "src/result/capture_transformer.dart";
export "src/result/error.dart";
export "src/result/release_transformer.dart";
export "src/result/value.dart";
6 changes: 2 additions & 4 deletions lib/src/async_memoizer.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@
// 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.

library async.async_memoizer;

import 'dart:async';

/// A class for running an asynchronous function exactly once and caching its
Expand Down Expand Up @@ -35,12 +33,12 @@ class AsyncMemoizer<T> {
Future<T> get future => _completer.future;
final _completer = new Completer();

/// Whether [run] has been called yet.
/// Whether [runOnce] has been called yet.
bool get hasRun => _completer.isCompleted;

/// Runs the function, [computation], if it hasn't been run before.
///
/// If [run] has already been called, this returns the original result.
/// If [runOnce] has already been called, this returns the original result.
Future<T> runOnce(computation()) {
if (!hasRun) _completer.complete(new Future.sync(computation));
return future;
Expand Down
2 changes: 0 additions & 2 deletions lib/src/cancelable_operation.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@
// 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.

library async.cancelable_operation;

import 'dart:async';

import 'package:async/async.dart';
Expand Down
2 changes: 0 additions & 2 deletions lib/src/delegate/event_sink.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@
// 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.

library async.delegate.event_sink;

import 'dart:async';

/// Simple delegating wrapper around an [EventSink].
Expand Down
2 changes: 0 additions & 2 deletions lib/src/delegate/future.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@
// 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.

library async.delegate.future;

import 'dart:async';

/// A wrapper that forwards calls to a [Future].
Expand Down
Loading

0 comments on commit 66843f1

Please sign in to comment.