Make Transform a little more pleasant to use:

pkg/barback/lib/src/transform.dart

Index: pkg/barback/lib/src/transform.dart
diff --git a/pkg/barback/lib/src/transform.dart b/pkg/barback/lib/src/transform.dart
index d5d717696ff041f72d7077628ad224e3a5a2099a..4606b3754ec61a661ed96662b497a71c842efc1d 100644
--- a/pkg/barback/lib/src/transform.dart
+++ b/pkg/barback/lib/src/transform.dart
@@ -5,6 +5,7 @@
 library barback.transform;
 
 import 'dart:async';
+import 'dart:convert';
 
 import 'asset.dart';
 import 'asset_id.dart';
@@ -13,6 +14,7 @@ import 'asset_set.dart';
 import 'errors.dart';
 import 'transform_logger.dart';
 import 'transform_node.dart';
+import 'utils.dart';
 
 /// Creates a [Transform] by forwarding to the private constructor.
 ///
@@ -34,7 +36,10 @@ class Transform {
 
   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
@@ -43,13 +48,22 @@ class Transform {
   /// 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;
+  ///
+  /// This method may fail at runtime if called asynchronously after the
+  /// transform begins running. If the previous transform that generated this
+  /// primary input starts re-running while this transformer is in the middle
+  /// of running, it may be unavailable when this transformer later resumes.

[nweiz, 2013/08/28 21:15:00]

This sentence is confusing and slightly inaccurate. It's not just the previous
transform that can cause the input to change; it could be a source input. I
don't think it's worth trying to explain the full reasoning that the input may
not be available here. It's probably sufficient just to say that it may be
unavailable.

[Bob Nystrom, 2013/08/28 22:38:24]

Re-worded a bit.

+  ///
+  /// The intent is that this exception will unwind the transformer, which will
+  /// then be automatically re-run when the primary input becomes available
+  /// again, so you don't need to worry about this failing.
+  Asset get primaryInput {
+    if (_node.primary.state != AssetState.AVAILABLE) {
+      throw new AssetNotFoundException(_node.primary.id);
+    }
 
-  /// Gets the asset for the primary input.
-  Future<Asset> get primaryInput => getInput(primaryId);
+    return _node.primary.asset;
+  }
 
   Transform._(this._node, this._outputs);
 
@@ -59,6 +73,26 @@ class Transform {
   /// [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 calling `getInput()` followed by `readAsString()`.
+  ///
+  /// 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;
+    return getInput(id).then((input) => input.readAsString(encoding: encoding));
+  }
+
+  /// A convenience method to the contents of the input with [id].
+  ///
+  /// This is equivalent to calling `getInput()` followed by `read()`.
+  ///
+  /// If the asset was created from a [String], this returns its UTF-8 encoding.
+  Stream<List<int>> readInput(AssetId id) =>
+      futureStream(getInput(id).then((input) => input.read()));
+
   /// Stores [output] as the output created by this transformation.
   ///
   /// A transformation can output as many assets as it wants.