Debian Codegraph @

packages/properties/src/index.ts

raw
1 // Copyright (c) Jupyter Development Team.
2 // Distributed under the terms of the Modified BSD License.
3 /*-----------------------------------------------------------------------------
4 | Copyright (c) 2014-2017, PhosphorJS Contributors
5 |
6 | Distributed under the terms of the BSD 3-Clause License.
7 |
8 | The full license is in the file LICENSE, distributed with this software.
9 |----------------------------------------------------------------------------*/
10
11 /**
12 * @packageDocumentation
13 * @module properties
14 */
15
16 /**
17 * A class which attaches a value to an external object.
18 *
19 * #### Notes
20 * Attached properties are used to extend the state of an object with
21 * semantic data from an unrelated class. They also encapsulate value
22 * creation, coercion, and notification.
23 *
24 * Because attached property values are stored in a hash table, which
25 * in turn is stored in a WeakMap keyed on the owner object, there is
26 * non-trivial storage overhead involved in their use. The pattern is
27 * therefore best used for the storage of rare data.
28 */
29 export class AttachedProperty<T, U> {
30 /**
31 * Construct a new attached property.
32 *
33 * @param options - The options for initializing the property.
34 */
35 constructor(options: AttachedProperty.IOptions<T, U>) {
36 this.name = options.name;
37 this._create = options.create;
38 this._coerce = options.coerce || null;
39 this._compare = options.compare || null;
40 this._changed = options.changed || null;
41 }
42
43 /**
44 * The human readable name for the property.
45 */
46 readonly name: string;
47
48 /**
49 * Get the current value of the property for a given owner.
50 *
51 * @param owner - The property owner of interest.
52 *
53 * @returns The current value of the property.
54 *
55 * #### Notes
56 * If the value has not yet been set, the default value will be
57 * computed and assigned as the current value of the property.
58 */
59 get(owner: T): U {
60 let value: U;
61 let map = Private.ensureMap(owner);
62 if (this._pid in map) {
63 value = map[this._pid];
64 } else {
65 value = map[this._pid] = this._createValue(owner);
66 }
67 return value;
68 }
69
70 /**
71 * Set the current value of the property for a given owner.
72 *
73 * @param owner - The property owner of interest.
74 *
75 * @param value - The value for the property.
76 *
77 * #### Notes
78 * If the value has not yet been set, the default value will be
79 * computed and used as the previous value for the comparison.
80 */
81 set(owner: T, value: U): void {
82 let oldValue: U;
83 let map = Private.ensureMap(owner);
84 if (this._pid in map) {
85 oldValue = map[this._pid];
86 } else {
87 oldValue = map[this._pid] = this._createValue(owner);
88 }
89 let newValue = this._coerceValue(owner, value);
90 this._maybeNotify(owner, oldValue, (map[this._pid] = newValue));
91 }
92
93 /**
94 * Explicitly coerce the current property value for a given owner.
95 *
96 * @param owner - The property owner of interest.
97 *
98 * #### Notes
99 * If the value has not yet been set, the default value will be
100 * computed and used as the previous value for the comparison.
101 */
102 coerce(owner: T): void {
103 let oldValue: U;
104 let map = Private.ensureMap(owner);
105 if (this._pid in map) {
106 oldValue = map[this._pid];
107 } else {
108 oldValue = map[this._pid] = this._createValue(owner);
109 }
110 let newValue = this._coerceValue(owner, oldValue);
111 this._maybeNotify(owner, oldValue, (map[this._pid] = newValue));
112 }
113
114 /**
115 * Get or create the default value for the given owner.
116 */
117 private _createValue(owner: T): U {
118 let create = this._create;
119 return create(owner);
120 }
121
122 /**
123 * Coerce the value for the given owner.
124 */
125 private _coerceValue(owner: T, value: U): U {
126 let coerce = this._coerce;
127 return coerce ? coerce(owner, value) : value;
128 }
129
130 /**
131 * Compare the old value and new value for equality.
132 */
133 private _compareValue(oldValue: U, newValue: U): boolean {
134 let compare = this._compare;
135 return compare ? compare(oldValue, newValue) : oldValue === newValue;
136 }
137
138 /**
139 * Run the change notification if the given values are different.
140 */
141 private _maybeNotify(owner: T, oldValue: U, newValue: U): void {
142 let changed = this._changed;
143 if (changed && !this._compareValue(oldValue, newValue)) {
144 changed(owner, oldValue, newValue);
145 }
146 }
147
148 private _pid = Private.nextPID();
149 private _create: (owner: T) => U;
150 private _coerce: ((owner: T, value: U) => U) | null;
151 private _compare: ((oldValue: U, newValue: U) => boolean) | null;
152 private _changed: ((owner: T, oldValue: U, newValue: U) => void) | null;
153 }
154
155 /**
156 * The namespace for the `AttachedProperty` class statics.
157 */
158 export namespace AttachedProperty {
159 /**
160 * The options object used to initialize an attached property.
161 */
162 export interface IOptions<T, U> {
163 /**
164 * The human readable name for the property.
165 *
166 * #### Notes
167 * By convention, this should be the same as the name used to define
168 * the public accessor for the property value.
169 *
170 * This **does not** have an effect on the property lookup behavior.
171 * Multiple properties may share the same name without conflict.
172 */
173 name: string;
174
175 /**
176 * A factory function used to create the default property value.
177 *
178 * #### Notes
179 * This will be called whenever the property value is required,
180 * but has not yet been set for a given owner.
181 */
182 create: (owner: T) => U;
183
184 /**
185 * A function used to coerce a supplied value into the final value.
186 *
187 * #### Notes
188 * This will be called whenever the property value is changed, or
189 * when the property is explicitly coerced. The return value will
190 * be used as the final value of the property.
191 *
192 * This will **not** be called for the initial default value.
193 */
194 coerce?: (owner: T, value: U) => U;
195
196 /**
197 * A function used to compare two values for equality.
198 *
199 * #### Notes
200 * This is called to determine if the property value has changed.
201 * It should return `true` if the given values are equivalent, or
202 * `false` if they are different.
203 *
204 * If this is not provided, it defaults to the `===` operator.
205 */
206 compare?: (oldValue: U, newValue: U) => boolean;
207
208 /**
209 * A function called when the property value has changed.
210 *
211 * #### Notes
212 * This will be invoked when the property value is changed and the
213 * comparator indicates that the old value is not equal to the new
214 * value.
215 *
216 * This will **not** be called for the initial default value.
217 */
218 changed?: (owner: T, oldValue: U, newValue: U) => void;
219 }
220
221 /**
222 * Clear the stored property data for the given owner.
223 *
224 * @param owner - The property owner of interest.
225 *
226 * #### Notes
227 * This will clear all property values for the owner, but it will
228 * **not** run the change notification for any of the properties.
229 */
230 export function clearData(owner: unknown): void {
231 Private.ownerData.delete(owner);
232 }
233 }
234
235 /**
236 * The namespace for the module implementation details.
237 */
238 namespace Private {
239 /**
240 * A typedef for a mapping of property id to property value.
241 */
242 export type PropertyMap = { [key: string]: any };
243
244 /**
245 * A weak mapping of property owner to property map.
246 */
247 export const ownerData = new WeakMap<any, PropertyMap>();
248
249 /**
250 * A function which computes successive unique property ids.
251 */
252 export const nextPID = (() => {
253 let id = 0;
254 return () => {
255 let rand = Math.random();
256 let stem = `${rand}`.slice(2);
257 return `pid-${stem}-${id++}`;
258 };
259 })();
260
261 /**
262 * Lookup the data map for the property owner.
263 *
264 * This will create the map if one does not already exist.
265 */
266 export function ensureMap(owner: unknown): PropertyMap {
267 let map = ownerData.get(owner);
268 if (map) {
269 return map;
270 }
271 map = Object.create(null) as PropertyMap;
272 ownerData.set(owner, map);
273 return map;
274 }
275 }