Note: This rate-limit API was added in Knockout 3.1.0. For previous versions, the throttle
extender provides similar functionality.
Normally, an observable that is changed notifies its subscribers immediately, so that any computed observables or bindings that depend on the observable are updated synchronously. The rateLimit
extender, however, causes an observable to suppress and delay change notifications for a specified period of time. A rate-limited observable therefore updates dependencies asynchronously.
The rateLimit
extender can be applied to any type of observable, including observable arrays and computed observables. The main use cases for rate-limiting are:
- Making things respond after a certain delay
- Combining multiple changes into a single update
If you only need to combine updates without adding a delay, deferred updates provides a more efficient method.
Applying the rateLimit extender
rateLimit
supports two parameter formats:
// Shorthand: Specify just a timeout in milliseconds someObservableOrComputed.extend({ rateLimit: 500 }); // Longhand: Specify timeout and/or method someObservableOrComputed.extend({ rateLimit: { timeout: 500, method: "notifyWhenChangesStop" } });
The method
option controls when notifications fire, and accepts the following values:
-
notifyAtFixedRate
— Default value if not otherwise specified. The notification happens after the specified period of time from the first change to the observable (either initially or since the previous notification). -
notifyWhenChangesStop
— The notification happens after no changes have occured to the observable for the specified period of time. Each time the observable changes, that timer is reset, so notifications cannot happen if the observable continuously changes more frequently than the timeout period.
Example 1: The basics
Consider the observables in the following code:
var name = ko.observable('Bert'); var upperCaseName = ko.computed(function() { return name().toUpperCase(); });
Normally, if you change name
as follows:
name('The New Bert');
… then upperCaseName
will be recomputed immediately, before your next line of code runs. But if you instead define name
using rateLimit
as follows:
var name = ko.observable('Bert').extend({ rateLimit: 500 });
… then upperCaseName
will not be recomputed immediately when name
changes—instead, name
will wait for 500 milliseconds (half a second) before notifying its new value to upperCaseName
, which will then recompute its value. No matter how many times name
is changed during those 500 ms, upperCaseName
will only be updated once with the most recent value.
Example 2: Doing something when the user stops typing
In this live example, there’s an instantaneousValue
observable that reacts immediately when you press a key. This is then wrapped inside a delayedValue
computed observable that’s configured to notify only when changes stop for at least 400 milliseconds, using the notifyWhenChangesStop
rate-limit method.
Try it:
Source code: View
<p>Type stuff here: <input data-bind='textInput: instantaneousValue' /></p> <p>Current delayed value: <b data-bind='text: delayedValue'> </b></p> <div data-bind="visible: loggedValues().length > 0"> <h3>Stuff you have typed:</h3> <ul data-bind="foreach: loggedValues"> <li data-bind="text: $data"></li> </ul> </div>
Source code: View model
function AppViewModel() { this.instantaneousValue = ko.observable(); this.delayedValue = ko.pureComputed(this.instantaneousValue) .extend({ rateLimit: { method: "notifyWhenChangesStop", timeout: 400 } }); // Keep a log of the throttled values this.loggedValues = ko.observableArray([]); this.delayedValue.subscribe(function (val) { if (val !== '') this.loggedValues.push(val); }, this); } ko.applyBindings(new AppViewModel());
Special consideration for computed observables
For a computed observable, the rate-limit timer is triggered when one of the computed observable’s dependencies change instead of when its value changes. The computed observable is not re-evaluated until its value is actually needed—after the timeout period when the change notification should happen, or when the computed observable value is accessed directly. If you need to access the value of the computed’s most recent evaluation, you can do so with the peek
method.
Forcing rate-limited observables to always notify subscribers
When the value of any observable is primitive (a number, string, boolean, or null), the dependents of the observable are by default notified only when it is set to a value that is actually different from before. So, primitive-valued rate-limited observables notify only when their value is actually different at the end of the timeout period. In other words, if a primitive-valued rate-limited observable is changed to a new value and then changed back to the original value before the timeout period ends, no notification will happen.
If you want to ensure that the subscribers are always notified of an update, even if the value is the same, you would use the notify
extender in addition to rateLimit
:
myViewModel.fullName = ko.computed(function() { return myViewModel.firstName() + " " + myViewModel.lastName(); }).extend({ notify: 'always', rateLimit: 500 });
Comparison with deferred updates
Knockout version 3.4.0 added support for deferred updates, which works similarly to rate-limiting by making notifications and updates asynchronous. But instead of using a timed delay, deferred updates are processed as soon as possible after the current task, before yielding for I/O, reflow, or redrawing. If you are upgrading to 3.4.0 and have code that uses a short rate-limit timeout (e.g., 0 milliseconds), you could modify it to use deferred updates instead:
ko.computed(function() { // .... }).extend({ deferred: true });
Comparison with the throttle extender
If you’d like to migrate code from using the deprecated throttle
extender, you should note the following ways that the rateLimit
extender is different from the throttle
extender.
When using rateLimit
:
- Writes to observables are not delayed; the observable’s value is updated right away. For writable computed observables, this means that the write function is always run right away.
- All
change
notifications are delayed, including when callingvalueHasMutated
manually. This means you can’t usevalueHasMutated
to force a rate-limited observable to notify an un-changed value. - The default rate-limit method is different from the
throttle
algorithm. To match thethrottle
behavior, use thenotifyWhenChangesStop
method. - Evaluation of a rate-limited computed observable isn’t rate-limited; it will re-evaluate if you read its value.
Please login to continue.