Make Transform a little more pleasant to use:

pkg/barback/lib/src/transform.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.
 
 library barback.transform;
 
 import 'dart:async';
+import 'dart:convert';
 
 import 'asset.dart';
 import 'asset_id.dart';
 import 'asset_node.dart';
 import 'asset_set.dart';
 import 'errors.dart';
 import 'transform_logger.dart';
 import 'transform_node.dart';
 
 /// Creates a [Transform] by forwarding to the private constructor.
 ///
 /// Lets [TransformNode] create [Transforms] without giving a [Transform]
 /// itself a public constructor, which would be visible to external users.
 /// Unlike the [Transform] class, this function is not exported by barback.dart.
 Transform createTransform(TransformNode node, AssetSet outputs) =>
     new Transform._(node, outputs);
 
 /// While a [Transformer] represents a *kind* of transformation, this defines
 /// one specific usage of it on a set of files.
 ///
 /// This ephemeral object exists only during an actual transform application to
 /// facilitate communication between the [Transformer] and the code hosting
 /// the transformation. It lets the [Transformer] access inputs and generate
 /// outputs.
 class Transform {
   final TransformNode _node;
 
   final AssetSet _outputs;
 
-  /// Gets the ID of the primary input for this transformation.
+  /// A logger so that the [Transformer] can report build details.
+  TransformLogger get logger => _logger;
+
+  /// Gets the primary input asset.
   ///
   /// While a transformation can use multiple input assets, one must be a
   /// special "primary" asset. This will be the "entrypoint" or "main" input
   /// file for a transformation.
   ///
   /// For example, with a dart2js transform, the primary input would be the
   /// entrypoint Dart file. All of the other Dart files that that imports
   /// would be secondary inputs.
-  AssetId get primaryId => _node.primary.id;
-
-  /// A logger so that the [Transformer] can report build details.
-  TransformLogger get logger => _logger;
-
-  /// Gets the asset for the primary input.
-  Future<Asset> get primaryInput => getInput(primaryId);
+  Asset get primaryInput {
+    assert(_node.primary.state == AssetState.AVAILABLE);

[nweiz, 2013/08/28 19:29:43]

This shouldn't be an assertion. It's expected to fail occasionally if the
transformer accesses primaryInput asynchronously, so it should throw a real
exception (probably StateError).

[Bob Nystrom, 2013/08/28 20:51:27]

Done.

+    return _node.primary.asset;
+  }
 
   Transform._(this._node, this._outputs);
 
   /// Gets the asset for an input [id].
   ///
   /// If an input with that ID cannot be found, throws an
   /// [AssetNotFoundException].
   Future<Asset> getInput(AssetId id) => _node.getInput(id);
 
+  /// A convenience method to the contents of the input with [id] as a string.
+  ///
+  /// This is equivalent to `getInput().readAsString()`.

[nweiz, 2013/08/28 19:29:43]

`getInput().readAsString()` is a little confusing, since [getInput] returns a
Future. Same below.

[Bob Nystrom, 2013/08/28 20:51:27]

Reworded a bit. I didn't want to do the full async code for it since it's
pointlessly verbose.

+  ///
+  /// If the asset was created from a [String] the original string is always
+  /// returned and [encoding] is ignored. Otherwise, the binary data of the
+  /// asset is decoded using [encoding], which defaults to [UTF8].
+  Future<String> readInputAsString(AssetId id, {Encoding encoding}) {
+    if (encoding == null) encoding = UTF8;

[Siggi Cherem (dart-lang), 2013/08/28 00:12:30]

why not use "encoding: UTF8" as default value above?

[Bob Nystrom, 2013/08/28 19:11:34]

If you do that, passing an explicit null will override the default value. That
breaks forwarding, so I always put the default value in the body.

+    return getInput(id).then((input) => input.readAsString(encoding: encoding));
+  }
+
+  /// A convenience method to the contents of the input with [id].
+  ///
+  /// This is equivalent to `getInput().read()`.
+  ///
+  /// If the asset was created from a [String], this returns its UTF-8 encoding.
+  Future<List<int>> readInput(AssetId id) =>
+      getInput(id).then((input) => input.read());

[nweiz, 2013/08/28 19:29:43]

[Asset.read] returns a Stream<List<int>>, not a Future<List<int>>. You could use
the [futureStream] function in pkg/scheduled_test/lib/src/utils.dart to just
have this return a Stream<List<int>>, though.

[Bob Nystrom, 2013/08/28 20:51:27]

Done.

+
   /// Stores [output] as the output created by this transformation.
   ///
   /// A transformation can output as many assets as it wants.
   void addOutput(Asset output) {
     // TODO(rnystrom): This should immediately throw if an output with that ID
     // has already been created by this transformer.
     _outputs.add(output);
   }
 }
 
 // TODO(sigmund,rnystrom): create a separate logger for each Transfom.
 final TransformLogger _logger = new TransformLogger(true);