Add ko.when

build/fragments/source-references.js

@@ -17,6 +17,7 @@ knockoutDebugCallback([
     'src/subscribables/observableArray.changeTracking.js',
     'src/subscribables/dependentObservable.js',
     'src/subscribables/mappingHelpers.js',
+    'src/subscribables/observableUtils.js',
     'src/binding/selectExtensions.js',
     'src/binding/expressionRewriting.js',
     'src/virtualElements.js',

spec/asyncBehaviors.js

@@ -1238,4 +1238,56 @@ describe('Deferred', function() {
             expect(notifySpy).not.toHaveBeenCalled();
         });
     });
+
+    describe('ko.when', function() {
+        it('Runs callback in a sepearate task when predicate function becomes true, but only once', function() {
+            this.restoreAfter(ko.options, 'deferUpdates');
+            ko.options.deferUpdates = true;
+
+            var x = ko.observable(3),
+                called = 0;
+
+            ko.when(function () { return x() === 4; }, function () { called++; });
+
+            x(5);
+            expect(called).toBe(0);
+            expect(x.getSubscriptionsCount()).toBe(1);
+
+            x(4);
+            expect(called).toBe(0);
+
+            jasmine.Clock.tick(1);
+            expect(called).toBe(1);
+            expect(x.getSubscriptionsCount()).toBe(0);
+
+            x(3);
+            x(4);
+            jasmine.Clock.tick(1);
+            expect(called).toBe(1);
+            expect(x.getSubscriptionsCount()).toBe(0);
+        });
+
+        it('Runs callback in a sepearate task if predicate function is already true', function() {
+            this.restoreAfter(ko.options, 'deferUpdates');
+            ko.options.deferUpdates = true;
+
+            var x = ko.observable(4),
+                called = 0;
+
+            ko.when(function () { return x() === 4; }, function () { called++; });
+
+            expect(called).toBe(0);
+            expect(x.getSubscriptionsCount()).toBe(1);
+
+            jasmine.Clock.tick(1);
+            expect(called).toBe(1);
+            expect(x.getSubscriptionsCount()).toBe(0);
+
+            x(3);
+            x(4);
+            jasmine.Clock.tick(1);
+            expect(called).toBe(1);
+            expect(x.getSubscriptionsCount()).toBe(0);
+        });
+    });
 });

spec/observableUtilsBehaviors.js

@@ -0,0 +1,91 @@
+describe('ko.when', function() {
+    it('Runs callback when predicate function becomes true, but only once', function() {
+        var x = ko.observable(3),
+            called = 0;
+
+        ko.when(function () { return x() === 4; }, function () { called++; });
+
+        x(5);
+        expect(called).toBe(0);
+        expect(x.getSubscriptionsCount()).toBe(1);
+
+        x(4);
+        expect(called).toBe(1);
+        expect(x.getSubscriptionsCount()).toBe(0);
+
+        x(3);
+        x(4);
+        expect(called).toBe(1);
+        expect(x.getSubscriptionsCount()).toBe(0);
+    });
+
+    it('Runs callback if predicate function is already true', function() {
+        var x = ko.observable(4),
+            called = 0;
+
+        ko.when(function () { return x() === 4; }, function () { called++; });
+
+        expect(called).toBe(1);
+        expect(x.getSubscriptionsCount()).toBe(0);
+
+        x(3);
+        x(4);
+        expect(called).toBe(1);
+        expect(x.getSubscriptionsCount()).toBe(0);
+    });
+
+    it('Accepts an observable as the predicate', function() {
+        var x = ko.observable(false),
+            called = 0;
+
+        ko.when(x, function () { called++; });
+
+        expect(called).toBe(0);
+        expect(x.getSubscriptionsCount()).toBe(1);
+
+        x(true);
+        expect(called).toBe(1);
+        expect(x.getSubscriptionsCount()).toBe(0);
+    });
+
+    it('Returns an object with a dispose function that cancels the notification', function() {
+        var x = ko.observable(false),
+            called = 0;
+
+        var handle = ko.when(x, function () { called++; });
+
+        expect(called).toBe(0);
+        expect(x.getSubscriptionsCount()).toBe(1);
+
+        handle.dispose();
+        expect(x.getSubscriptionsCount()).toBe(0);
+
+        x(true);
+        expect(called).toBe(0);
+    });
+
+    it('Will call callback function only once even if value is updated during callback', function() {
+        var x = ko.observable(false),
+            called = 0;
+
+        ko.when(x, function () {
+            called++;
+            x(false);
+            x(true);
+        });
+
+        expect(called).toBe(0);
+        expect(x.getSubscriptionsCount()).toBe(1);
+
+        x(true);
+        expect(called).toBe(1);
+    });
+
+    it('Should be able to specify a \'this\' pointer for the callback', function () {
+        var model = {
+            someProperty: 123,
+            myCallback: function () { expect(this.someProperty).toEqual(123); }
+        };
+        ko.when(ko.observable(true), model.myCallback, model);
+    });
+});

spec/runner.html

@@ -30,6 +30,7 @@
         <script type="text/javascript" src="dependentObservableDomBehaviors.js"></script>
         <script type="text/javascript" src="pureComputedBehaviors.js"></script>
         <script type="text/javascript" src="extenderBehaviors.js"></script>
+        <script type="text/javascript" src="observableUtilsBehaviors.js"></script>
         <script type="text/javascript" src="domNodeDisposalBehaviors.js"></script>
         <script type="text/javascript" src="mappingHelperBehaviors.js"></script>
         <script type="text/javascript" src="expressionRewritingBehaviors.js"></script>

spec/runner.node.js

@@ -39,6 +39,7 @@ require('./mappingHelperBehaviors');
 require('./observableArrayBehaviors');
 require('./observableArrayChangeTrackingBehaviors');
 require('./observableBehaviors');
+require('./observableUtilsBehaviors');
 require('./subscribableBehaviors');
 require('./taskBehaviors');
 require('./utilsBehaviors');

src/subscribables/observableUtils.js

@@ -0,0 +1,15 @@
+ko.when = function(predicate, callback, context) {
+    var observable = ko.pureComputed(predicate).extend({notify:'always'});
+    var subscription = observable.subscribe(function(value) {
+        if (value) {
+            subscription.dispose();
+            callback.call(context);
+        }
+    });
+    // In case the initial value is true, process it right away
+    observable['notifySubscribers'](observable.peek());
+
+    return subscription;
+};
+
+ko.exportSymbol('when', ko.when);