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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
/**
* 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/mixins/mutable-data.html
*/
/// <reference path="../utils/mixin.d.ts" />
declare namespace Polymer {
/**
* Element class mixin to skip strict dirty-checking for objects and arrays
* (always consider them to be "dirty"), for use on elements utilizing
* `Polymer.PropertyEffects`
*
* 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 mixin or enable the
* `Polymer.OptionalMutableData` mixin.
*
* In order to make the dirty check strategy configurable, see
* `Polymer.OptionalMutableData`.
*
* 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.
*/
function MutableData<T extends new (...args: any[]) => {}>(base: T): T & MutableDataConstructor;
interface MutableDataConstructor {
new(...args: any[]): MutableData;
}
interface MutableData {
/**
* 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;
}
/**
* Element class mixin 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 mixin or apply the
* `Polymer.MutableData` mixin.
*
* While this mixin 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.
*/
function OptionalMutableData<T extends new (...args: any[]) => {}>(base: T): T & OptionalMutableDataConstructor;
interface OptionalMutableDataConstructor {
new(...args: any[]): OptionalMutableData;
}
interface OptionalMutableData {
/**
* 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 provide option for skipping
* strict equality checking for Objects and Arrays.
*
* When `this.mutableData` is true on this instance, 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;
}
}
|
