Skip to content

Commit 2c53020

Browse files
wagenetwagenet
committed
Merge pull request emberjs#3278 from bmac/document-reduce-computed
Add API docs for Ember.reduceComputed and Ember.arrayComputed
2 parents 86de008 + 28a1d73 commit 2c53020

File tree

2 files changed

+229
-2
lines changed

2 files changed

+229
-2
lines changed

‎packages/ember-runtime/lib/computed/array_computed.js‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,120 @@ ArrayComputedProperty.prototype.resetValue = function (array) {
4141
return array;
4242
};
4343

44+
/**
45+
Creates a computed property which operates on dependent arrays and
46+
is updated with "one at a time" semantics. When items are added or
47+
removed from the dependent array(s) an array computed only operates
48+
on the change instead of re-evaluating the entire array. This should
49+
return an array, if you'd like to use "one at a time" semantics and
50+
compute some value other then an array look at
51+
`Ember.reduceComputed`.
4452
53+
If there are more than one arguments the first arguments are
54+
considered to be dependent property keys. The last argument is
55+
required to be an options object. The options object can have the
56+
following three properties.
57+
58+
`initialize` - An optional initialize function. Typically this will be used
59+
to set up state on the instanceMeta object.
60+
61+
`removedItem` - A function that is called each time an element is
62+
removed from the array.
63+
64+
`addedItem` - A function that is called each time an element is
65+
added to the array.
66+
67+
68+
The `initialize` function has the following signature:
69+
70+
```javascript
71+
function (array, changeMeta, instanceMeta)
72+
```
73+
74+
`array` - The initial value of the arrayComputed, an empty array.
75+
76+
`changeMeta` - An object which contains meta information about the
77+
computed. It contains the following properties:
78+
79+
- `property` the computed property
80+
- `propertyName` the name of the property on the object
81+
82+
`instanceMeta` - An object that can be used to store meta
83+
information needed for calculating your computed. For example a
84+
unique computed might use this to store the number of times a given
85+
element is found in the dependent array.
86+
87+
88+
The `removedItem` and `addedItem` functions both have the following signature:
89+
90+
```javascript
91+
function (accumulatedValue, item, changeMeta, instanceMeta)
92+
```
93+
94+
`accumulatedValue` - The value returned from the last time
95+
`removedItem` or `addedItem` was called or an empty array.
96+
97+
`item` - the element added or removed from the array
98+
99+
`changeMeta` - An object which contains meta information about the
100+
change. It contains the following properties:
101+
102+
- `property` the computed property
103+
- `propertyName` the name of the property on the object
104+
- `index` the index of the added or removed item
105+
- `item` the added or removed item: this is exactly the same as
106+
the second arg
107+
- `arrayChanged` the array that triggered the change. Can be
108+
useful when depending on multiple arrays.
109+
110+
For property changes triggered on an item property change (when
111+
depKey is something like `someArray.@each.someProperty`),
112+
`changeMeta` may also contain the followng properties:
113+
114+
- `keyChanged` the name of the property on the item that changed
115+
- `previousValue` the previous value of item.get(keyChanged)
116+
117+
These properties are important because Ember coalesces item
118+
property changes via Ember.run.once. This means that by the time
119+
removedItem gets called, item has the new value, but you may need
120+
the previous value (eg for sorting & filtering).
121+
122+
`instanceMeta` - An object that can be used to store meta
123+
information needed for calculating your computed. For example a
124+
unique computed might use this to store the number of times a given
125+
element is found in the dependent array.
126+
127+
The `removedItem` and `addedItem` functions should return the accumulated
128+
value. It is acceptable to not return anything (ie return undefined)
129+
to invalidate the computation. This is generally not a good idea for
130+
arrayComputed but it's used in eg max and min.
131+
132+
Example
133+
134+
```javascript
135+
Ember.computed.map = function(dependentKey, callback) {
136+
var options = {
137+
addedItem: function(array, item, changeMeta, instanceMeta) {
138+
var mapped = callback(item);
139+
array.insertAt(changeMeta.index, mapped);
140+
return array;
141+
},
142+
removedItem: function(array, item, changeMeta, instanceMeta) {
143+
array.removeAt(changeMeta.index, 1);
144+
return array;
145+
}
146+
};
147+
148+
return Ember.arrayComputed(dependentKey, options);
149+
};
150+
```
151+
152+
@method arrayComputed
153+
@for Ember
154+
@param {String} [dependentKeys*]
155+
@param {Object} options
156+
@returns {Ember.ComputedProperty}
157+
*/
45158
Ember.arrayComputed = function (options) {
46159
var args;
47160

‎packages/ember-runtime/lib/computed/reduce_computed.js‎

Lines changed: 116 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ var get = Ember.get,
1818
eachPropertyPattern = /^(.*)\.@each\.(.*)/,
1919
doubleEachPropertyPattern = /(.*\.@each){2,}/;
2020

21-
/**
21+
/*
2222
Tracks changes to dependent arrays, as well as to properties of items in
2323
dependent arrays.
2424
@@ -531,7 +531,122 @@ ReduceComputedProperty.prototype.property = function () {
531531
return ComputedProperty.prototype.property.apply(this, propertyArgs);
532532
};
533533

534+
/**
535+
Creates a computed property which operates on dependent arrays and
536+
is updated with "one at a time" semantics. When items are added or
537+
removed from the dependent array(s) a reduce computed only operates
538+
on the change instead of re-evaluating the entire array.
539+
540+
If there are more than one arguments the first arguments are
541+
considered to be dependent property keys. The last argument is
542+
required to be an options object. The options object can have the
543+
following four properties.
544+
545+
`initialValue` - A value or function that will be used as the initial
546+
value for the computed. If this property is a function the result of calling
547+
the function will be used as the initial value. This property is required.
548+
549+
`initialize` - An optional initialize function. Typically this will be used
550+
to set up state on the instanceMeta object.
551+
552+
`removedItem` - A function that is called each time an element is removed
553+
from the array.
554+
555+
`addedItem` - A function that is called each time an element is added to
556+
the array.
557+
558+
559+
The `initialize` function has the following signature:
560+
561+
```javascript
562+
function (initialValue, changeMeta, instanceMeta)
563+
```
564+
565+
`initialValue` - The value of the `initialValue` property from the
566+
options object.
567+
568+
`changeMeta` - An object which contains meta information about the
569+
computed. It contains the following properties:
570+
571+
- `property` the computed property
572+
- `propertyName` the name of the property on the object
573+
574+
`instanceMeta` - An object that can be used to store meta
575+
information needed for calculating your computed. For example a
576+
unique computed might use this to store the number of times a given
577+
element is found in the dependent array.
578+
579+
580+
The `removedItem` and `addedItem` functions both have the following signature:
581+
582+
```javascript
583+
function (accumulatedValue, item, changeMeta, instanceMeta)
584+
```
585+
586+
`accumulatedValue` - The value returned from the last time
587+
`removedItem` or `addedItem` was called or `initialValue`.
534588
589+
`item` - the element added or removed from the array
590+
591+
`changeMeta` - An object which contains meta information about the
592+
change. It contains the following properties:
593+
594+
- `property` the computed property
595+
- `propertyName` the name of the property on the object
596+
- `index` the index of the added or removed item
597+
- `item` the added or removed item: this is exactly the same as
598+
the second arg
599+
- `arrayChanged` the array that triggered the change. Can be
600+
useful when depending on multiple arrays.
601+
602+
For property changes triggered on an item property change (when
603+
depKey is something like `someArray.@each.someProperty`),
604+
`changeMeta` may also contain the followng properties:
605+
606+
- `keyChanged` the name of the property on the item that changed
607+
- `previousValue` the previous value of item.get(keyChanged)
608+
609+
These properties are important because Ember coalesces item
610+
property changes via Ember.run.once. This means that by the time
611+
removedItem gets called, item has the new value, but you may need
612+
the previous value (eg for sorting & filtering).
613+
614+
`instanceMeta` - An object that can be used to store meta
615+
information needed for calculating your computed. For example a
616+
unique computed might use this to store the number of times a given
617+
element is found in the dependent array.
618+
619+
The `removedItem` and `addedItem` functions should return the accumulated
620+
value. It is acceptable to not return anything (ie return undefined)
621+
to invalidate the computation. This is generally not a good idea for
622+
arrayComputed but it's used in eg max and min.
623+
624+
Example
625+
626+
```javascript
627+
Ember.computed.max = function (dependentKey) {
628+
return Ember.reduceComputed.call(null, dependentKey, {
629+
initialValue: -Infinity,
630+
631+
addedItem: function (accumulatedValue, item, changeMeta, instanceMeta) {
632+
return Math.max(accumulatedValue, item);
633+
},
634+
635+
removedItem: function (accumulatedValue, item, changeMeta, instanceMeta) {
636+
if (item < accumulatedValue) {
637+
return accumulatedValue;
638+
}
639+
}
640+
});
641+
};
642+
```
643+
644+
@method reduceComputed
645+
@for Ember
646+
@param {String} [dependentKeys*]
647+
@param {Object} options
648+
@returns {Ember.ComputedProperty}
649+
*/
535650
Ember.reduceComputed = function (options) {
536651
var args;
537652

@@ -556,4 +671,3 @@ Ember.reduceComputed = function (options) {
556671

557672
return cp;
558673
};
559-

0 commit comments

Comments
 (0)