/
mutable-data-behavior.d.ts
131 lines (124 loc) · 6.16 KB
/
mutable-data-behavior.d.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
/**
* DO NOT EDIT
*
* This file was automatically generated by
* https://github.com/Polymer/gen-typescript-declarations
*
* To modify these typings, edit the source file(s):
* lib/legacy/mutable-data-behavior.html
*/
/// <reference path="../mixins/mutable-data.d.ts" />
declare namespace Polymer {
/**
* Legacy element behavior to skip strict dirty-checking for objects and arrays,
* (always consider them to be "dirty") for use on legacy API Polymer elements.
*
* By default, `Polymer.PropertyEffects` performs strict dirty checking on
* objects, which means that any deep modifications to an object or array will
* not be propagated unless "immutable" data patterns are used (i.e. all object
* references from the root to the mutation were changed).
*
* Polymer also provides a proprietary data mutation and path notification API
* (e.g. `notifyPath`, `set`, and array mutation API's) that allow efficient
* mutation and notification of deep changes in an object graph to all elements
* bound to the same object graph.
*
* In cases where neither immutable patterns nor the data mutation API can be
* used, applying this mixin will cause Polymer to skip dirty checking for
* objects and arrays (always consider them to be "dirty"). This allows a
* user to make a deep modification to a bound object graph, and then either
* simply re-set the object (e.g. `this.items = this.items`) or call `notifyPath`
* (e.g. `this.notifyPath('items')`) to update the tree. Note that all
* elements that wish to be updated based on deep mutations must apply this
* mixin or otherwise skip strict dirty checking for objects/arrays.
* Specifically, any elements in the binding tree between the source of a
* mutation and the consumption of it must apply this behavior or enable the
* `Polymer.OptionalMutableDataBehavior`.
*
* In order to make the dirty check strategy configurable, see
* `Polymer.OptionalMutableDataBehavior`.
*
* Note, the performance characteristics of propagating large object graphs
* will be worse as opposed to using strict dirty checking with immutable
* patterns or Polymer's path notification API.
*/
interface MutableDataBehavior {
/**
* Overrides `Polymer.PropertyEffects` to provide option for skipping
* strict equality checking for Objects and Arrays.
*
* This method pulls the value to dirty check against from the `__dataTemp`
* cache (rather than the normal `__data` cache) for Objects. Since the temp
* cache is cleared at the end of a turn, this implementation allows
* side-effects of deep object changes to be processed by re-setting the
* same object (using the temp cache as an in-turn backstop to prevent
* cycles due to 2-way notification).
*
* @param property Property name
* @param value New property value
* @param old Previous property value
* @returns Whether the property should be considered a change
*/
_shouldPropertyChange(property: string, value: any, old: any): boolean;
}
/**
* Legacy element behavior to add the optional ability to skip strict
* dirty-checking for objects and arrays (always consider them to be
* "dirty") by setting a `mutable-data` attribute on an element instance.
*
* By default, `Polymer.PropertyEffects` performs strict dirty checking on
* objects, which means that any deep modifications to an object or array will
* not be propagated unless "immutable" data patterns are used (i.e. all object
* references from the root to the mutation were changed).
*
* Polymer also provides a proprietary data mutation and path notification API
* (e.g. `notifyPath`, `set`, and array mutation API's) that allow efficient
* mutation and notification of deep changes in an object graph to all elements
* bound to the same object graph.
*
* In cases where neither immutable patterns nor the data mutation API can be
* used, applying this mixin will allow Polymer to skip dirty checking for
* objects and arrays (always consider them to be "dirty"). This allows a
* user to make a deep modification to a bound object graph, and then either
* simply re-set the object (e.g. `this.items = this.items`) or call `notifyPath`
* (e.g. `this.notifyPath('items')`) to update the tree. Note that all
* elements that wish to be updated based on deep mutations must apply this
* mixin or otherwise skip strict dirty checking for objects/arrays.
* Specifically, any elements in the binding tree between the source of a
* mutation and the consumption of it must enable this behavior or apply the
* `Polymer.OptionalMutableDataBehavior`.
*
* While this behavior adds the ability to forgo Object/Array dirty checking,
* the `mutableData` flag defaults to false and must be set on the instance.
*
* Note, the performance characteristics of propagating large object graphs
* will be worse by relying on `mutableData: true` as opposed to using
* strict dirty checking with immutable patterns or Polymer's path notification
* API.
*/
interface OptionalMutableDataBehavior {
/**
* Instance-level flag for configuring the dirty-checking strategy
* for this element. When true, Objects and Arrays will skip dirty
* checking, otherwise strict equality checking will be used.
*/
mutableData: boolean|null|undefined;
/**
* Overrides `Polymer.PropertyEffects` to skip strict equality checking
* for Objects and Arrays.
*
* Pulls the value to dirty check against from the `__dataTemp` cache
* (rather than the normal `__data` cache) for Objects. Since the temp
* cache is cleared at the end of a turn, this implementation allows
* side-effects of deep object changes to be processed by re-setting the
* same object (using the temp cache as an in-turn backstop to prevent
* cycles due to 2-way notification).
*
* @param property Property name
* @param value New property value
* @param old Previous property value
* @returns Whether the property should be considered a change
*/
_shouldPropertyChange(property: string, value: any, old: any): boolean;
}
}