Add support for lazy transformers.

pkg/barback/lib/src/asset_node.dart

Index: pkg/barback/lib/src/asset_node.dart
diff --git a/pkg/barback/lib/src/asset_node.dart b/pkg/barback/lib/src/asset_node.dart
index a1af547ddddc53cedd25b3f6044bf28cdbdad51d..f05c338d6f34505e0b8d56ddb35b1e4ab5b5f5cf 100644
--- a/pkg/barback/lib/src/asset_node.dart
+++ b/pkg/barback/lib/src/asset_node.dart
@@ -50,6 +50,14 @@ class AssetNode {
   Asset get asset => _asset;
   Asset _asset;
 
+  /// The callback to be called to notify this asset node's creator that the
+  /// asset should be materialized.
+  ///
+  /// This is only non-null for lazy asset nodes (see

[Bob Nystrom, 2014/01/30 19:33:44]

"only non-null for lazy" -> "null for non-lazy"

[nweiz, 2014/01/31 03:43:27]

Done.

+  /// [AssetNodeController.lazy]). Once this is called, it's set to null and
+  /// [this] is no longer considered lazy.
+  Function _lazyCallback;

[Bob Nystrom, 2014/01/30 19:33:44]

I'm all for using callbacks in barback, but isn't this inconsistent with the
rest of barback which uses streams? Shouldn't this be a onMaterialize stream?

[nweiz, 2014/01/31 03:43:27]

I chose a callback instead because it's guaranteed to only fire once, and the
person who instantiates a lazy node or makes a node lazy should always register
a callback for it.

I'd make this a Future if that worked with synchronous callbacks and I could
somehow return a Future from [AssetNodeController.lazy].

+
   /// A broadcast stream that emits an event whenever the node changes state.
   ///
   /// This stream is synchronous to ensure that when a source asset is modified
@@ -137,6 +145,21 @@ class AssetNode {
       : id = asset.id,
         _asset = asset,
         _state = AssetState.AVAILABLE;
+
+  AssetNode._lazy(this.id, this._transform, this._origin, this._lazyCallback)
+      : _state = AssetState.DIRTY;
+
+  /// If [this] is lazy, materialize it; otherwise, do nothing.
+  ///
+  /// See [AssetNodeController.lazy].
+  void materialize() {
+    if (_origin != null) {
+      _origin.materialize();
+    } else if (_lazyCallback != null) {
+      _lazyCallback();
+      _lazyCallback = null;
+    }
+  }
 }
 
 /// The controller for an [AssetNode].
@@ -154,11 +177,27 @@ class AssetNodeController {
   AssetNodeController.available(Asset asset, [TransformNode transform])
       : node = new AssetNode._available(asset, transform, null);
 
+  /// Creates a controller for a lazy node.
+  ///
+  /// For the most party, this node works like any other dirty node. However,

[Bob Nystrom, 2014/01/30 19:33:44]

I'm always trying to maximize my party too, but here it should just be "for the
most part".

[nweiz, 2014/01/31 03:43:27]

Done.

+  /// the owner of its controller isn't expected to do the work to make it
+  /// available as soon as possible like they would for a non-lazy node.

[Bob Nystrom, 2014/01/30 19:33:44]

they -> it

TransformNodes are gender-less, not gender-neutral. :)

[nweiz, 2014/01/31 03:43:27]

"They" actually refers to "the owner" here, who is gender-neutral.

+  /// Instead, when its value is needed, [callback] will fire to indicate that
+  /// it should be made available as soon as possible.
+  ///
+  /// [callback] is guaranteed to only fire once.
+  AssetNodeController.lazy(AssetId id, void callback(),
+          [TransformNode transform])
+      : node = new AssetNode._lazy(id, transform, null, callback);
+
   /// Creates a controller for a node whose initial state matches the current
   /// state of [node].
   ///
   /// [AssetNode.origin] of the returned node will automatically be set to
   /// `node.origin`.
+  ///
+  /// If [node] is lazy, the returned node will also be lazy. If the returned
+  /// node is materialized, [node] will be materialized as well.
   AssetNodeController.from(AssetNode node)
       : node = new AssetNode._(node.id, node.transform, node.origin) {
     if (node.state.isAvailable) {
@@ -173,6 +212,7 @@ class AssetNodeController {
     assert(node._state != AssetState.REMOVED);
     node._state = AssetState.DIRTY;
     node._asset = null;
+    node._lazyCallback = null;
     node._stateChangeController.add(AssetState.DIRTY);
   }
 
@@ -184,6 +224,7 @@ class AssetNodeController {
     assert(node._state != AssetState.REMOVED);
     node._state = AssetState.REMOVED;
     node._asset = null;
+    node._lazyCallback = null;
     node._stateChangeController.add(AssetState.REMOVED);
   }
 
@@ -197,8 +238,24 @@ class AssetNodeController {
     assert(node._state != AssetState.AVAILABLE);
     node._state = AssetState.AVAILABLE;
     node._asset = asset;
+    node._lazyCallback = null;
     node._stateChangeController.add(AssetState.AVAILABLE);
   }
+
+  /// Marks the node as [AssetState.DIRTY] and lazy.
+  ///
+  /// Lazy nodes aren't expected to have their values generated until it's

[Bob Nystrom, 2014/01/30 19:33:44]

"it's necessary" -> "needed".

[nweiz, 2014/01/31 03:43:27]

Done.

+  /// necessary. Once it's necessary, [callback] will be called. [callback] is
+  /// guaranteed to be called only once.
+  ///
+  /// See also [AssetNodeController.lazy].
+  void setLazy(void callback()) {
+    assert(node._state != AssetState.REMOVED);
+    node._state = AssetState.DIRTY;
+    node._asset = null;
+    node._lazyCallback = callback;
+    node._stateChangeController.add(AssetState.DIRTY);
+  }
 }
 
 // TODO(nweiz): add an error state.